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