001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 2.0.11 004 * 005 * Do not make changes to this file unless you know what you are doing--modify 006 * the SWIG interface file instead. 007 * ----------------------------------------------------------------------------- */ 008 009package org.sbml.libsbml; 010 011/** 012 * 013 * Implementation of SBML's AlgebraicRule construct. 014 * <p> 015 * The rule type {@link AlgebraicRule} is derived from the parent class {@link Rule}. It 016 * is used to express equations that are neither assignments of model 017 * variables nor rates of change. {@link AlgebraicRule} does not add any 018 * attributes to the basic {@link Rule}; its role is simply to distinguish this 019 * case from the other cases. 020 * <p> 021 * In the context of a simulation, algebraic rules are in effect at all 022 * times, <em>t</em> ≥ <em>0</em>. For purposes of evaluating 023 * expressions that involve the delay 'csymbol' (see the SBML 024 * specification), algebraic rules are considered to apply also at 025 * <em>t</em> ≤ <em>0</em>. Please consult the relevant SBML 026 * specification for additional information about the semantics of 027 * assignments, rules, and entity values for simulation time <em>t</em> 028 * ≤ <em>0</em>. 029 * <p> 030 * An SBML model must not be overdetermined. The ability to define 031 * arbitrary algebraic expressions in an SBML model introduces the 032 * possibility that a model is mathematically overdetermined by the overall 033 * system of equations constructed from its rules, reactions and events. 034 * Therefore, if an algebraic rule is introduced in a model, for at least 035 * one of the entities referenced in the rule's 'math' element the value of 036 * that entity must not be completely determined by other constructs in the 037 * model. This means that at least this entity must not have the attribute 038 * 'constant'=<code>true</code> and there must also not be a rate rule or assignment 039 * rule for it. Furthermore, if the entity is a {@link Species} object, its value 040 * must not be determined by reactions, which means that it must either 041 * have the attribute 'boundaryCondition'=<code>true</code> or else not be involved 042 * in any reaction at all. These restrictions are explained in more detail 043 * in the SBML specification documents. 044 * <p> 045 * In SBML Levels 2 and 3, {@link Reaction} object identifiers can be 046 * referenced in the 'math' expression of an algebraic rule, but reaction 047 * rates can never be <em>determined</em> by algebraic rules. This is true 048 * even when a reaction does not contain a {@link KineticLaw} element. (In such 049 * cases of missing {@link KineticLaw} elements, the model is valid but incomplete; 050 * the rates of reactions lacking kinetic laws are simply undefined, and 051 * not determined by the algebraic rule.) 052 * <p> 053 * <h2>General summary of SBML rules</h2> 054 * <p> 055 * In SBML Level 3 as well as Level 2, rules are separated into three 056subclasses for the benefit of model analysis software. The three 057subclasses are based on the following three different possible functional 058forms (where <em>x</em> is a variable, <em>f</em> is some arbitrary 059function returning a numerical result, <b><em>V</em></b> is a vector of 060variables that does not include <em>x</em>, and <b><em>W</em></b> is a 061vector of variables that may include <em>x</em>): 062 063<center> 064<table border='0' cellpadding='0' style='font-size: small'> 065<tr><td width='120px'><em>Algebraic:</em></td><td width='250px'>left-hand side is zero</td><td><em>0 = f(<b>W</b>)</em></td></tr> 066<tr><td><em>Assignment:</em></td><td>left-hand side is a scalar:</td><td><em>x = f(<b>V</b>)</em></td></tr> 067<tr><td><em>Rate:</em></td><td>left-hand side is a rate-of-change:</td><td><em>dx/dt = f(<b>W</b>)</em></td></tr> 068</table> 069</center> 070 071In their general form given above, there is little to distinguish 072between <em>assignment</em> and <em>algebraic</em> rules. They are treated as 073separate cases for the following reasons: 074 075<ul> 076<li> <em>Assignment</em> rules can simply be evaluated to calculate 077intermediate values for use in numerical methods. They are statements 078of equality that hold at all times. (For assignments that are only 079performed once, see {@link InitialAssignment}.)<p> 080 081<li> SBML needs to place restrictions on assignment rules, for example 082the restriction that assignment rules cannot contain algebraic loops.<p> 083 084<li> Some simulators do not contain numerical solvers capable of solving 085unconstrained algebraic equations, and providing more direct forms such 086as assignment rules may enable those simulators to process models they 087could not process if the same assignments were put in the form of 088general algebraic equations;<p> 089 090<li> Those simulators that <em>can</em> solve these algebraic equations make a 091distinction between the different categories listed above; and<p> 092 093<li> Some specialized numerical analyses of models may only be applicable 094to models that do not contain <em>algebraic</em> rules. 095</ul> 096 097The approach taken to covering these cases in SBML is to define an 098abstract {@link Rule} structure containing a subelement, 'math', to hold the 099right-hand side expression, then to derive subtypes of {@link Rule} that add 100attributes to distinguish the cases of algebraic, assignment and rate 101rules. The 'math' subelement must contain a MathML expression defining the 102mathematical formula of the rule. This MathML formula must return a 103numerical value. The formula can be an arbitrary expression referencing 104the variables and other entities in an SBML model. 105 106Each of the three subclasses of {@link Rule} (AssignmentRule, {@link AlgebraicRule}, 107{@link RateRule}) inherit the the 'math' subelement and other fields from {@link SBase}. 108The {@link AssignmentRule} and {@link RateRule} classes add an additional attribute, 109'variable'. See the definitions of {@link AssignmentRule}, {@link AlgebraicRule} and 110{@link RateRule} for details about the structure and interpretation of each one. 111 112 * <p> 113 * <h2>Additional restrictions on SBML rules</h2> 114 * <p> 115 * An important design goal of SBML rule semantics is to ensure that a 116model's simulation and analysis results will not be dependent on when or 117how often rules are evaluated. To achieve this, SBML needs to place two 118restrictions on rule use. The first concerns algebraic loops in the system 119of assignments in a model, and the second concerns overdetermined systems. 120 121<h3><a class='anchor' id='no-algebraic-loops'>A model must not contain 122algebraic loops</a></h3> 123 124The combined set of {@link InitialAssignment}, {@link AssignmentRule} and {@link KineticLaw} 125objects in a model constitute a set of assignment statements that should be 126considered as a whole. (A {@link KineticLaw} object is counted as an assignment 127because it assigns a value to the symbol contained in the 'id' attribute of 128the {@link Reaction} object in which it is defined.) This combined set of 129assignment statements must not contain algebraic loops—dependency 130chains between these statements must terminate. To put this more formally, 131consider a directed graph in which nodes are assignment statements and 132directed arcs exist for each occurrence of an SBML species, compartment or 133parameter symbol in an assignment statement's 'math' subelement. Let the 134directed arcs point from the statement assigning the symbol to the 135statements that contain the symbol in their 'math' subelement expressions. 136This graph must be acyclic. 137 138SBML does not specify when or how often rules should be evaluated. 139Eliminating algebraic loops ensures that assignment statements can be 140evaluated any number of times without the result of those evaluations 141changing. As an example, consider the set of equations <em>x = x + 1</em>, 142<em>y = z + 200</em> and <em>z = y + 100</em>. If this set of equations 143were interpreted as a set of assignment statements, it would be invalid 144because the rule for <em>x</em> refers to <em>x</em> (exhibiting one type 145of loop), and the rule for <em>y</em> refers to <em>z</em> while the rule 146for <em>z</em> refers back to <em>y</em> (exhibiting another type of loop). 147Conversely, the following set of equations would constitute a valid set of 148assignment statements: <em>x = 10</em>, <em>y = z + 200</em>, and <em>z = x 149+ 100</em>. 150 151<h3><a class='anchor' id='no-overdetermined'>A model must not be 152overdetermined</a></h3> 153 154An SBML model must not be overdetermined; that is, a model must not 155define more equations than there are unknowns in a model. An SBML model 156that does not contain {@link AlgebraicRule} structures cannot be overdetermined. 157 158LibSBML implements the static analysis procedure described in 159Appendix B of the SBML Level 3 Version 1 Core 160specification for assessing whether a model is overdetermined. 161 162(In summary, assessing whether a given continuous, deterministic, 163mathematical model is overdetermined does not require dynamic analysis; it 164can be done by analyzing the system of equations created from the model. 165One approach is to construct a bipartite graph in which one set of vertices 166represents the variables and the other the set of vertices represents the 167equations. Place edges between vertices such that variables in the system 168are linked to the equations that determine them. For algebraic equations, 169there will be edges between the equation and each variable occurring in the 170equation. For ordinary differential equations (such as those defined by 171rate rules or implied by the reaction rate definitions), there will be a 172single edge between the equation and the variable determined by that 173differential equation. A mathematical model is overdetermined if the 174maximal matchings of the bipartite graph contain disconnected vertexes 175representing equations. If one maximal matching has this property, then 176all the maximal matchings will have this property; i.e., it is only 177necessary to find one maximal matching.) 178 179 * <p> 180 * <h2>Rule types for SBML Level 1</h2> 181 * <p> 182 * SBML Level 1 uses a different scheme than SBML Level 2 and Level 3 for 183 * distinguishing rules; specifically, it uses an attribute whose value is 184 * drawn from an enumeration of 3 values. LibSBML supports this using methods 185 * that work with the enumeration values listed below. 186 * <p> 187 * <ul> 188 * <li> {@link libsbmlConstants#RULE_TYPE_RATE RULE_TYPE_RATE}: Indicates 189 * the rule is a 'rate' rule. 190 * <li> {@link libsbmlConstants#RULE_TYPE_SCALAR RULE_TYPE_SCALAR}: 191 * Indicates the rule is a 'scalar' rule. 192 * <li> {@link libsbmlConstants#RULE_TYPE_INVALID RULE_TYPE_INVALID}: 193 * Indicates the rule type is unknown or not yet set. 194 * </ul> 195 * <p> 196 * <!-- leave this next break as-is to work around some doxygen bug --> 197 */ 198 199public class AlgebraicRule extends Rule { 200 private long swigCPtr; 201 202 protected AlgebraicRule(long cPtr, boolean cMemoryOwn) 203 { 204 super(libsbmlJNI.AlgebraicRule_SWIGUpcast(cPtr), cMemoryOwn); 205 swigCPtr = cPtr; 206 } 207 208 protected static long getCPtr(AlgebraicRule obj) 209 { 210 return (obj == null) ? 0 : obj.swigCPtr; 211 } 212 213 protected static long getCPtrAndDisown (AlgebraicRule obj) 214 { 215 long ptr = 0; 216 217 if (obj != null) 218 { 219 ptr = obj.swigCPtr; 220 obj.swigCMemOwn = false; 221 } 222 223 return ptr; 224 } 225 226 protected void finalize() { 227 delete(); 228 } 229 230 public synchronized void delete() { 231 if (swigCPtr != 0) { 232 if (swigCMemOwn) { 233 swigCMemOwn = false; 234 libsbmlJNI.delete_AlgebraicRule(swigCPtr); 235 } 236 swigCPtr = 0; 237 } 238 super.delete(); 239 } 240 241 242/** 243 * Creates a new {@link AlgebraicRule} using the given SBML <code>level</code> and <code>version</code> 244 * values. 245 * <p> 246 * @param level a long integer, the SBML Level to assign to this {@link AlgebraicRule} 247 * <p> 248 * @param version a long integer, the SBML Version to assign to this 249 * {@link AlgebraicRule} 250 * <p> 251 * @throws SBMLConstructorException 252 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 253 * of SBML object, are either invalid or mismatched with respect to the 254 * parent {@link SBMLDocument} object. 255 * <p> 256 * @note Upon the addition of an {@link AlgebraicRule} object to an {@link SBMLDocument} 257 * (e.g., using {@link Model#addRule(Rule r)}), the SBML Level, SBML Version 258 * and XML namespace of the document <em>override</em> the values used 259 * when creating the {@link AlgebraicRule} object via this constructor. This is 260 * necessary to ensure that an SBML document is a consistent structure. 261 * Nevertheless, the ability to supply the values at the time of creation 262 * of a {@link AlgebraicRule} is an important aid to producing valid SBML. 263 * Knowledge of the intented SBML Level and Version determine whether it 264 * is valid to assign a particular value to an attribute, or whether it 265 * is valid to add an object to an existing {@link SBMLDocument}. 266 */ public 267 AlgebraicRule(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 268 this(libsbmlJNI.new_AlgebraicRule__SWIG_0(level, version), true); 269 } 270 271 272/** 273 * Creates a new {@link AlgebraicRule} using the given {@link SBMLNamespaces} object 274 * <code>sbmlns</code>. 275 * <p> 276 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces 277 * information. It is used to communicate the SBML Level, Version, and 278 * (in Level 3) packages used in addition to SBML Level 3 Core. 279 * A common approach to using this class constructor is to create an 280 * {@link SBMLNamespaces} object somewhere in a program, once, then pass it to 281 * object constructors such as this one when needed. 282 * <p> 283 * @param sbmlns an {@link SBMLNamespaces} object. 284 * <p> 285 * @throws SBMLConstructorException 286 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 287 * of SBML object, are either invalid or mismatched with respect to the 288 * parent {@link SBMLDocument} object. 289 * <p> 290 * @note Upon the addition of a {@link AlgebraicRule} object to an {@link SBMLDocument} 291 * (e.g., using {@link Model#addRule(Rule r)}, the SBML XML namespace of the 292 * document <em>overrides</em> the value used when creating the {@link AlgebraicRule} 293 * object via this constructor. This is necessary to ensure that an SBML 294 * document is a consistent structure. Nevertheless, the ability to 295 * supply the values at the time of creation of a {@link AlgebraicRule} is an 296 * important aid to producing valid SBML. Knowledge of the intented SBML 297 * Level and Version determine whether it is valid to assign a particular 298 * value to an attribute, or whether it is valid to add an object to an 299 * existing {@link SBMLDocument}. 300 */ public 301 AlgebraicRule(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException { 302 this(libsbmlJNI.new_AlgebraicRule__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true); 303 } 304 305 306/** 307 * Creates and returns a deep copy of this {@link Rule}. 308 * <p> 309 * @return a (deep) copy of this {@link Rule}. 310 */ public 311 AlgebraicRule cloneObject() { 312 long cPtr = libsbmlJNI.AlgebraicRule_cloneObject(swigCPtr, this); 313 return (cPtr == 0) ? null : new AlgebraicRule(cPtr, true); 314 } 315 316 317/** 318 * Predicate returning <code>true</code> if 319 * all the required attributes for this {@link AlgebraicRule} object 320 * have been set. 321 * <p> 322 * @note In SBML Levels 2–3, there is no required attribute 323 * for an {@link AlgebraicRule} object. For Level 1, the only required 324 * attribute is 'formula'. 325 * <p> 326 * @return <code>true</code> if the required attributes have been set, <code>false</code> 327 * otherwise. 328 */ public 329 boolean hasRequiredAttributes() { 330 return libsbmlJNI.AlgebraicRule_hasRequiredAttributes(swigCPtr, this); 331 } 332 333}