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 AssignmentRule construct. 014 * <p> 015 * The rule type {@link AssignmentRule} is derived from the parent class {@link Rule}. It 016 * is used to express equations that set the values of variables. The 017 * left-hand side (the attribute named 'variable') of an assignment rule 018 * can refer to the identifier of a {@link Species}, {@link SpeciesReference} (in SBML 019 * Level 3), {@link Compartment}, or {@link Parameter} object in the model (but not a 020 * {@link Reaction}). The entity identified must have its 'constant' attribute set 021 * to <code>false.</code> The effects of an {@link AssignmentRule} are in general terms the 022 * same, but differ in the precise details depending on the type of 023 * variable being set: <ul> 024<p> 025 * <li> <em>In the case of a species</em>, an {@link AssignmentRule} sets the 026 * referenced species' quantity (whether a 'concentration' or 'amount') to 027 * the value determined by the formula in the MathML subelement 'math'. 028 * The unit associated with the value produced by the 'math' formula 029 * <em>should</em> (in SBML Level 2 Version 4 and in SBML Level 3) or <em>must</em> (in 030 * SBML releases prior to Level 2 version 4) be equal to the unit 031 * associated with the species' quantity. <em>Restrictions</em>: There 032 * must not be both an {@link AssignmentRule} 'variable' attribute and a 033 * {@link SpeciesReference} 'species' attribute having the same value, unless the 034 * referenced {@link Species} object has its 'boundaryCondition' attribute set to 035 * <code>true.</code> In other words, an assignment rule cannot be defined for a 036 * species that is created or destroyed in a reaction unless that species 037 * is defined as a boundary condition in the model. 038 * <p> 039 * <li> (For SBML Level 3 only) <em>In the case of a species 040 * reference</em>, an {@link AssignmentRule} sets the stoichiometry of the 041 * referenced reactant or product to the value determined by the formula in 042 * 'math'. The unit associated with the value produced by the 'math' 043 * formula should be consistent with the unit 'dimensionless', because 044 * reactant and product stoichiometries in reactions are dimensionless 045 * quantities. 046 * <p> 047 * <li> <em>In the case of a compartment</em>, an {@link AssignmentRule} sets the 048 * referenced compartment's size to the value determined by the formula in 049 * the 'math' subelement of the {@link AssignmentRule} object. The overall units 050 * of the formula in 'math' <em>should</em> (in SBML Level 2 Version 4 051 * and in SBML Level 3) or <em>must</em> (in SBML releases prior to Level 2 052 * version 4) be the same as the units of the size of the compartment. 053 * <p> 054 * <li> <em>In the case of a parameter</em>, an {@link AssignmentRule} sets the 055 * referenced parameter's value to that determined by the formula in the 056 * 'math' subelement of the {@link AssignmentRule} object. The overall units of 057 * the formula in the 'math' subelement <em>should</em> (in SBML Level 2 058 * Version 4 and in SBML Level 3) or <em>must</em> (in SBML releases prior to 059 * Level 2 version 4) be the same as the units defined for the 060 * parameter. </ul> 061 * <p> 062 * In the context of a simulation, assignment rules are in effect at all 063 * times, <em>t</em> ≥ <em>0</em>. For purposes of evaluating 064 * expressions that involve the <em>delay</em> 'csymbol' (see the SBML 065 * Level 2 specification), assignment rules are considered to apply 066 * also at <em>t</em> ≤ <em>0</em>. Please consult the relevant 067 * SBML specification for additional information about the semantics of 068 * assignments, rules, and entity values for simulation time <em>t</em> 069 * ≤ <em>0</em>. 070 * <p> 071 * A model must not contain more than one {@link AssignmentRule} or {@link RateRule} 072 * object having the same value of 'variable'; in other words, in the set 073 * of all assignment rules and rate rules in an SBML model, each variable 074 * appearing in the left-hand sides can only appear once. This simply 075 * follows from the fact that an indeterminate system would result if a 076 * model contained more than one assignment rule for the same variable or 077 * both an assignment rule and a rate rule for the same variable. 078 * <p> 079 * Similarly, a model must also not contain <em>both</em> an {@link AssignmentRule} 080 * and an {@link InitialAssignment} for the same variable, because both kinds of 081 * constructs apply prior to and at the start of simulation time, i.e., 082 * <em>t</em> ≤ <em>0</em>. If a model contained both an initial 083 * assignment and an assignment rule for the same variable, an 084 * indeterminate system would result. 085 * <p> 086 * The value calculated by an {@link AssignmentRule} object overrides the value 087 * assigned to the given symbol by the object defining that symbol. For 088 * example, if a {@link Compartment} object's 'size' attribute value is set in its 089 * definition, and the model also contains an {@link AssignmentRule} object having 090 * that compartment's 'id' as its 'variable' value, then the 'size' 091 * assigned in the {@link Compartment} object definition is ignored and the value 092 * assigned based on the computation defined in the {@link AssignmentRule}. This 093 * does <em>not</em> mean that a definition for a given symbol can be 094 * omitted if there is an {@link AssignmentRule} object for it. For example, there 095 * must be a {@link Parameter} definition for a given parameter if there is an 096 * {@link AssignmentRule} for that parameter. It is only a question of which value 097 * definition takes precedence. 098 * <p> 099 * <h2>General summary of SBML rules</h2> 100 * <p> 101 * In SBML Level 3 as well as Level 2, rules are separated into three 102subclasses for the benefit of model analysis software. The three 103subclasses are based on the following three different possible functional 104forms (where <em>x</em> is a variable, <em>f</em> is some arbitrary 105function returning a numerical result, <b><em>V</em></b> is a vector of 106variables that does not include <em>x</em>, and <b><em>W</em></b> is a 107vector of variables that may include <em>x</em>): 108 109<center> 110<table border='0' cellpadding='0' style='font-size: small'> 111<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> 112<tr><td><em>Assignment:</em></td><td>left-hand side is a scalar:</td><td><em>x = f(<b>V</b>)</em></td></tr> 113<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> 114</table> 115</center> 116 117In their general form given above, there is little to distinguish 118between <em>assignment</em> and <em>algebraic</em> rules. They are treated as 119separate cases for the following reasons: 120 121<ul> 122<li> <em>Assignment</em> rules can simply be evaluated to calculate 123intermediate values for use in numerical methods. They are statements 124of equality that hold at all times. (For assignments that are only 125performed once, see {@link InitialAssignment}.)<p> 126 127<li> SBML needs to place restrictions on assignment rules, for example 128the restriction that assignment rules cannot contain algebraic loops.<p> 129 130<li> Some simulators do not contain numerical solvers capable of solving 131unconstrained algebraic equations, and providing more direct forms such 132as assignment rules may enable those simulators to process models they 133could not process if the same assignments were put in the form of 134general algebraic equations;<p> 135 136<li> Those simulators that <em>can</em> solve these algebraic equations make a 137distinction between the different categories listed above; and<p> 138 139<li> Some specialized numerical analyses of models may only be applicable 140to models that do not contain <em>algebraic</em> rules. 141</ul> 142 143The approach taken to covering these cases in SBML is to define an 144abstract {@link Rule} structure containing a subelement, 'math', to hold the 145right-hand side expression, then to derive subtypes of {@link Rule} that add 146attributes to distinguish the cases of algebraic, assignment and rate 147rules. The 'math' subelement must contain a MathML expression defining the 148mathematical formula of the rule. This MathML formula must return a 149numerical value. The formula can be an arbitrary expression referencing 150the variables and other entities in an SBML model. 151 152Each of the three subclasses of {@link Rule} (AssignmentRule, {@link AlgebraicRule}, 153{@link RateRule}) inherit the the 'math' subelement and other fields from {@link SBase}. 154The {@link AssignmentRule} and {@link RateRule} classes add an additional attribute, 155'variable'. See the definitions of {@link AssignmentRule}, {@link AlgebraicRule} and 156{@link RateRule} for details about the structure and interpretation of each one. 157 158 * <p> 159 * <h2>Additional restrictions on SBML rules</h2> 160 * <p> 161 * An important design goal of SBML rule semantics is to ensure that a 162model's simulation and analysis results will not be dependent on when or 163how often rules are evaluated. To achieve this, SBML needs to place two 164restrictions on rule use. The first concerns algebraic loops in the system 165of assignments in a model, and the second concerns overdetermined systems. 166 167<h3><a class='anchor' id='no-algebraic-loops'>A model must not contain 168algebraic loops</a></h3> 169 170The combined set of {@link InitialAssignment}, {@link AssignmentRule} and {@link KineticLaw} 171objects in a model constitute a set of assignment statements that should be 172considered as a whole. (A {@link KineticLaw} object is counted as an assignment 173because it assigns a value to the symbol contained in the 'id' attribute of 174the {@link Reaction} object in which it is defined.) This combined set of 175assignment statements must not contain algebraic loops—dependency 176chains between these statements must terminate. To put this more formally, 177consider a directed graph in which nodes are assignment statements and 178directed arcs exist for each occurrence of an SBML species, compartment or 179parameter symbol in an assignment statement's 'math' subelement. Let the 180directed arcs point from the statement assigning the symbol to the 181statements that contain the symbol in their 'math' subelement expressions. 182This graph must be acyclic. 183 184SBML does not specify when or how often rules should be evaluated. 185Eliminating algebraic loops ensures that assignment statements can be 186evaluated any number of times without the result of those evaluations 187changing. As an example, consider the set of equations <em>x = x + 1</em>, 188<em>y = z + 200</em> and <em>z = y + 100</em>. If this set of equations 189were interpreted as a set of assignment statements, it would be invalid 190because the rule for <em>x</em> refers to <em>x</em> (exhibiting one type 191of loop), and the rule for <em>y</em> refers to <em>z</em> while the rule 192for <em>z</em> refers back to <em>y</em> (exhibiting another type of loop). 193Conversely, the following set of equations would constitute a valid set of 194assignment statements: <em>x = 10</em>, <em>y = z + 200</em>, and <em>z = x 195+ 100</em>. 196 197<h3><a class='anchor' id='no-overdetermined'>A model must not be 198overdetermined</a></h3> 199 200An SBML model must not be overdetermined; that is, a model must not 201define more equations than there are unknowns in a model. An SBML model 202that does not contain {@link AlgebraicRule} structures cannot be overdetermined. 203 204LibSBML implements the static analysis procedure described in 205Appendix B of the SBML Level 3 Version 1 Core 206specification for assessing whether a model is overdetermined. 207 208(In summary, assessing whether a given continuous, deterministic, 209mathematical model is overdetermined does not require dynamic analysis; it 210can be done by analyzing the system of equations created from the model. 211One approach is to construct a bipartite graph in which one set of vertices 212represents the variables and the other the set of vertices represents the 213equations. Place edges between vertices such that variables in the system 214are linked to the equations that determine them. For algebraic equations, 215there will be edges between the equation and each variable occurring in the 216equation. For ordinary differential equations (such as those defined by 217rate rules or implied by the reaction rate definitions), there will be a 218single edge between the equation and the variable determined by that 219differential equation. A mathematical model is overdetermined if the 220maximal matchings of the bipartite graph contain disconnected vertexes 221representing equations. If one maximal matching has this property, then 222all the maximal matchings will have this property; i.e., it is only 223necessary to find one maximal matching.) 224 225 * <p> 226 * <h2>Rule types for SBML Level 1</h2> 227 * <p> 228 * SBML Level 1 uses a different scheme than SBML Level 2 and Level 3 for 229 * distinguishing rules; specifically, it uses an attribute whose value is 230 * drawn from an enumeration of 3 values. LibSBML supports this using methods 231 * that work with the enumeration values listed below. 232 * <p> 233 * <ul> 234 * <li> {@link libsbmlConstants#RULE_TYPE_RATE RULE_TYPE_RATE}: Indicates 235 * the rule is a 'rate' rule. 236 * <li> {@link libsbmlConstants#RULE_TYPE_SCALAR RULE_TYPE_SCALAR}: 237 * Indicates the rule is a 'scalar' rule. 238 * <li> {@link libsbmlConstants#RULE_TYPE_INVALID RULE_TYPE_INVALID}: 239 * Indicates the rule type is unknown or not yet set. 240 * </ul> 241 * <p> 242 * <!-- leave this next break as-is to work around some doxygen bug --> 243 */ 244 245public class AssignmentRule extends Rule { 246 private long swigCPtr; 247 248 protected AssignmentRule(long cPtr, boolean cMemoryOwn) 249 { 250 super(libsbmlJNI.AssignmentRule_SWIGUpcast(cPtr), cMemoryOwn); 251 swigCPtr = cPtr; 252 } 253 254 protected static long getCPtr(AssignmentRule obj) 255 { 256 return (obj == null) ? 0 : obj.swigCPtr; 257 } 258 259 protected static long getCPtrAndDisown (AssignmentRule obj) 260 { 261 long ptr = 0; 262 263 if (obj != null) 264 { 265 ptr = obj.swigCPtr; 266 obj.swigCMemOwn = false; 267 } 268 269 return ptr; 270 } 271 272 protected void finalize() { 273 delete(); 274 } 275 276 public synchronized void delete() { 277 if (swigCPtr != 0) { 278 if (swigCMemOwn) { 279 swigCMemOwn = false; 280 libsbmlJNI.delete_AssignmentRule(swigCPtr); 281 } 282 swigCPtr = 0; 283 } 284 super.delete(); 285 } 286 287 288/** 289 * Creates a new {@link AssignmentRule} using the given SBML <code>level</code> and <code>version</code> 290 * values. 291 * <p> 292 * @param level a long integer, the SBML Level to assign to this {@link AssignmentRule} 293 * <p> 294 * @param version a long integer, the SBML Version to assign to this 295 * {@link AssignmentRule} 296 * <p> 297 * @throws SBMLConstructorException 298 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 299 * of SBML object, are either invalid or mismatched with respect to the 300 * parent {@link SBMLDocument} object. 301 * <p> 302 * @note Upon the addition of an {@link AssignmentRule} object to an {@link SBMLDocument} 303 * (e.g., using {@link Model#addRule(Rule r)}, the SBML Level, SBML Version 304 * and XML namespace of the document <em>override</em> the values used 305 * when creating the {@link AssignmentRule} object via this constructor. This is 306 * necessary to ensure that an SBML document is a consistent structure. 307 * Nevertheless, the ability to supply the values at the time of creation 308 * of a {@link AssignmentRule} is an important aid to producing valid SBML. 309 * Knowledge of the intented SBML Level and Version determine whether it 310 * is valid to assign a particular value to an attribute, or whether it 311 * is valid to add an object to an existing {@link SBMLDocument}. 312 */ public 313 AssignmentRule(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 314 this(libsbmlJNI.new_AssignmentRule__SWIG_0(level, version), true); 315 } 316 317 318/** 319 * Creates a new {@link AssignmentRule} using the given {@link SBMLNamespaces} object 320 * <code>sbmlns</code>. 321 * <p> 322 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces 323 * information. It is used to communicate the SBML Level, Version, and 324 * (in Level 3) packages used in addition to SBML Level 3 Core. 325 * A common approach to using this class constructor is to create an 326 * {@link SBMLNamespaces} object somewhere in a program, once, then pass it to 327 * object constructors such as this one when needed. 328 * <p> 329 * @param sbmlns an {@link SBMLNamespaces} object. 330 * <p> 331 * @throws SBMLConstructorException 332 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 333 * of SBML object, are either invalid or mismatched with respect to the 334 * parent {@link SBMLDocument} object. 335 * <p> 336 * @note Upon the addition of a {@link AssignmentRule} object to an {@link SBMLDocument} 337 * (e.g., using {@link Model#addRule(Rule r)}, the SBML XML namespace of 338 * the document <em>overrides</em> the value used when creating the 339 * {@link AssignmentRule} object via this constructor. This is necessary to 340 * ensure that an SBML document is a consistent structure. Nevertheless, 341 * the ability to supply the values at the time of creation of a 342 * {@link AssignmentRule} is an important aid to producing valid SBML. Knowledge 343 * of the intented SBML Level and Version determine whether it is valid 344 * to assign a particular value to an attribute, or whether it is valid 345 * to add an object to an existing {@link SBMLDocument}. 346 */ public 347 AssignmentRule(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException { 348 this(libsbmlJNI.new_AssignmentRule__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true); 349 } 350 351 352/** 353 * Creates and returns a deep copy of this {@link Rule}. 354 * <p> 355 * @return a (deep) copy of this {@link Rule}. 356 */ public 357 AssignmentRule cloneObject() { 358 long cPtr = libsbmlJNI.AssignmentRule_cloneObject(swigCPtr, this); 359 return (cPtr == 0) ? null : new AssignmentRule(cPtr, true); 360 } 361 362 363/** 364 * Predicate returning <code>true</code> if 365 * all the required attributes for this {@link AssignmentRule} object 366 * have been set. 367 * <p> 368 * @note In SBML Levels 2–3, the only required attribute for 369 * an {@link AssignmentRule} object is 'variable'. For Level 1, where the 370 * equivalent attribute is known by different names ('compartment', 371 * 'species', or 'name', depending on the type of object), there is an 372 * additional required attribute called 'formula'. 373 * <p> 374 * @return <code>true</code> if the required attributes have been set, <code>false</code> 375 * otherwise. 376 */ public 377 boolean hasRequiredAttributes() { 378 return libsbmlJNI.AssignmentRule_hasRequiredAttributes(swigCPtr, this); 379 } 380 381 382/** 383 * Renames all the SIdRef attributes on this element, including any found in MathML 384 */ public 385 void renameSIdRefs(String oldid, String newid) { 386 libsbmlJNI.AssignmentRule_renameSIdRefs(swigCPtr, this, oldid, newid); 387 } 388 389}