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