1 //------------------------------------------------------------------------------ 2 // <auto-generated /> 3 // 4 // This file was automatically generated by SWIG (http://www.swig.org). 5 // Version 4.0.2 6 // 7 // Do not make changes to this file unless you know what you are doing--modify 8 // the SWIG interface file instead. 9 //------------------------------------------------------------------------------ 10 11 namespace libsbml { 12 13 using System; 14 using System.Runtime.InteropServices; 15 16 /** 17 * @sbmlpackage{core} 18 * 19 @htmlinclude pkg-marker-core.html An SBML <em>rate rule</em> representing <em>dx/dt = f(<b>Y</b>)</em>. 20 * 21 * The rule type RateRule is derived from the parent class Rule. It is 22 * used to express equations that determine the rates of change of 23 * variables. The left-hand side (the 'variable' attribute) can refer to 24 * the identifier of a species, compartment, or parameter (but not a 25 * reaction). The entity identified must have its 'constant' attribute set 26 * to @c false. The effects of a RateRule are in general terms the same, 27 * but differ in the precise details depending on which variable is being 28 * set: 29 * 30 * <ul> <li> <em>In the case of a species</em>, a RateRule sets the rate of 31 * change of the species' quantity (<em>concentration</em> or <em>amount of 32 * substance</em>) to the value determined by the formula in the 'math' 33 * subelement of the RateRule object. The overall units of the formula in 34 * 'math' @em should (in SBML Level 2 Version 4 and in SBML Level 3) or @em 35 * must (in SBML releases prior to Level 2 version 4) be equal to 36 * the unit of <em>species quantity</em> divided by the model-wide unit of 37 * <em>time</em>. <em>Restrictions</em>: There must not be both a RateRule 38 * 'variable' attribute and a SpeciesReference 'species' attribute having 39 * the same value, unless that species has its 'boundaryCondition' 40 * attribute is set to @c true. This means a rate rule cannot be defined 41 * for a species that is created or destroyed in a reaction, unless that 42 * species is defined as a boundary condition in the model. 43 * 44 * <li> (For SBML Level 3 only) <em>In the case of a species 45 * reference</em>, a RateRule sets the rate of change of the stoichiometry 46 * of the referenced reactant or product to the value determined by the 47 * formula in 'math'. The unit associated with the value produced by the 48 * 'math' formula should be consistent with the unit 'dimensionless' 49 * divided by the model-wide unit of <em>time</em>. 50 * 51 * <li> <em>In the case of a compartment</em>, a RateRule sets the rate of 52 * change of the compartment's size to the value determined by the formula 53 * in the 'math' subelement of the RateRule object. The overall units of 54 * the formula @em should (in SBML Level 2 Version 4 and in SBML 55 * Level 3) or @em must (in SBML releases prior to Level 2 56 * version 4) be the units of the compartment's <em>size</em> divided 57 * by the model-wide unit of <em>time</em>. 58 * 59 * <li> <em>In the case of a parameter</em>, a RateRule sets the rate of 60 * change of the parameter's value to that determined by the formula in the 61 * 'math' subelement of the RateRule object. The overall units of the 62 * formula @em should (in SBML Level 2 Version 4 and in SBML 63 * Level 3) or @em must (in SBML releases prior to Level 2 64 * version 4) be the Parameter object's 'unit' attribute value divided 65 * by the model-wide unit of <em>time</em>. 66 * 67 * <li> (For SBML Level 3 Version 2 only) <em>In the case of 68 * an object from an SBML Level 3 package</em>, a RateRule sets the rate 69 * of change of the referenced object's value (as defined by that package) 70 * to the value of the formula in 'math'. The unit of measurement associated 71 * with the value produced by the formula should be the same as that object's 72 * units attribute value (if it has such an attribute) divided by the 73 * model-wide unit of @em time, or be equal to the units of model components 74 * of that type (if objects of that class are defined by the package as having 75 * the same units) divided by the model-wide unit of @em time. 76 * </ul> 77 * 78 * In SBML Level 2 and Level 3 Version 1, the 'math' 79 * subelement of the RateRule is required. In SBML Level 3 80 * Version 2, this rule is relaxed, and the subelement is 81 * optional. If a RateRule with no 'math' child is present in the model, 82 * the rate at which its referenced 'variable' changes over time is 83 * undefined. This may represent a situation where the model itself 84 * is unfinished, or the missing information may be provided by an 85 * SBML Level 3 package. 86 * 87 * If the variable attribute of a RateRule object references an object in 88 * an SBML namespace that is not understood by the interpreter reading a 89 * given SBML document (that is, if the object is defined by an SBML 90 * Level 3 package that the software does not support), the rate rule 91 * must be ignored--the object's value will not need to be set, as the 92 * interpreter could not understand that package. If an interpreter cannot 93 * establish whether a referenced object is missing from the model or 94 * instead is defined in an SBML namespace not understood by the interpreter, 95 * it may produce a warning to the user. (The latter situation may only 96 * arise if an SBML package is present in the SBML document with a 97 * package:required attribute of 'true'.) 98 * 99 * In the context of a simulation, rate rules are in effect for simulation 100 * time <em>t</em> > <em>0</em>. Please consult the relevant SBML 101 * specification for additional information about the semantics of 102 * assignments, rules, and entity values for simulation time <em>t</em> 103 * <= <em>0</em>. 104 * 105 * As mentioned in the description of AssignmentRule, a model must not 106 * contain more than one RateRule or AssignmentRule object having the same 107 * value of 'variable'; in other words, in the set of all assignment rules 108 * and rate rules in an SBML model, each variable appearing in the 109 * left-hand sides can only appear once. This simply follows from the fact 110 * that an indeterminate system would result if a model contained more than 111 * one assignment rule for the same variable or both an assignment rule and 112 * a rate rule for the same variable. 113 * 114 * 115 * @section rules-general General summary of SBML rules 116 * 117 * In SBML Level 3 as well as Level 2, rules are separated into three 118 * subclasses for the benefit of model analysis software. The three 119 * subclasses are based on the following three different possible functional 120 * forms (where <em>x</em> is a variable, <em>f</em> is some arbitrary 121 * function returning a numerical result, <b><em>V</em></b> is a vector of 122 * variables that does not include <em>x</em>, and <b><em>W</em></b> is a 123 * vector of variables that may include <em>x</em>): 124 * 125 * <table border='0' cellpadding='0' class='centered' style='font-size: small'> 126 * <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> 127 * <tr><td><em>Assignment:</em></td><td>left-hand side is a scalar:</td><td><em>x = f(<b>V</b>)</em></td></tr> 128 * <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> 129 * </table> 130 * 131 * In their general form given above, there is little to distinguish 132 * between <em>assignment</em> and <em>algebraic</em> rules. They are treated as 133 * separate cases for the following reasons: 134 * 135 * @li <em>Assignment</em> rules can simply be evaluated to calculate 136 * intermediate values for use in numerical methods. They are statements 137 * of equality that hold at all times. (For assignments that are only 138 * performed once, see InitialAssignment.) 139 140 * @li SBML needs to place restrictions on assignment rules, for example 141 * the restriction that assignment rules cannot contain algebraic loops. 142 * 143 * @li Some simulators do not contain numerical solvers capable of solving 144 * unconstrained algebraic equations, and providing more direct forms such 145 * as assignment rules may enable those simulators to process models they 146 * could not process if the same assignments were put in the form of 147 * general algebraic equations; 148 * 149 * @li Those simulators that <em>can</em> solve these algebraic equations make a 150 * distinction between the different categories listed above; and 151 * 152 * @li Some specialized numerical analyses of models may only be applicable 153 * to models that do not contain <em>algebraic</em> rules. 154 * 155 * The approach taken to covering these cases in SBML is to define an 156 * abstract Rule structure containing a subelement, 'math', to hold the 157 * right-hand side expression, then to derive subtypes of Rule that add 158 * attributes to distinguish the cases of algebraic, assignment and rate 159 * rules. The 'math' subelement must contain a MathML expression defining the 160 * mathematical formula of the rule. This MathML formula must return a 161 * numerical value. The formula can be an arbitrary expression referencing 162 * the variables and other entities in an SBML model. 163 * 164 * Each of the three subclasses of Rule (AssignmentRule, AlgebraicRule, 165 * RateRule) inherit the the 'math' subelement and other fields from SBase. 166 * The AssignmentRule and RateRule classes add an additional attribute, 167 * 'variable'. See the definitions of AssignmentRule, AlgebraicRule and 168 * RateRule for details about the structure and interpretation of each one. 169 * 170 * @section rules-restrictions Additional restrictions on SBML rules 171 * 172 * An important design goal of SBML rule semantics is to ensure that a 173 * model's simulation and analysis results will not be dependent on when or 174 * how often rules are evaluated. To achieve this, SBML needs to place two 175 * restrictions on rule use. The first concerns algebraic loops in the system 176 * of assignments in a model, and the second concerns overdetermined systems. 177 * 178 * @subsection rules-no-loops A model must not contain algebraic loops 179 * 180 * The combined set of InitialAssignment, AssignmentRule and KineticLaw 181 * objects in a model constitute a set of assignment statements that should be 182 * considered as a whole. (A KineticLaw object is counted as an assignment 183 * because it assigns a value to the symbol contained in the 'id' attribute of 184 * the Reaction object in which it is defined.) This combined set of 185 * assignment statements must not contain algebraic loops---dependency 186 * chains between these statements must terminate. To put this more formally, 187 * consider a directed graph in which nodes are assignment statements and 188 * directed arcs exist for each occurrence of an SBML species, compartment or 189 * parameter symbol in an assignment statement's 'math' subelement. Let the 190 * directed arcs point from the statement assigning the symbol to the 191 * statements that contain the symbol in their 'math' subelement expressions. 192 * This graph must be acyclic. 193 * 194 * Similarly, the combined set of RateRule and Reaction objects constitute 195 * a set of definitions for the rates of change of various model entities 196 * (namely, the objects identified by the values of the 'variable' attributes 197 * of the RateRule objects, and the 'species' attributes of the SpeciesReference 198 * objects in each Reaction). In SBML Level 3 Version 2, these rates 199 * of change may be referenced directly 200 * using the <em>rateOf</em> csymbol, but may not thereby contain algebraic 201 * loops---dependency chains between these statements must terminate. More 202 * formally, consider a directed graph in which the nodes are the definitions 203 * of different variables' rates of change, and directed arcs exist for each 204 * occurrence of a variable referenced by a <em>rateOf</em> csymbol from any 205 * RateRule or KineticLaw object in the model. Let the directed arcs point 206 * from the variable referenced by the <em>rateOf</em> csymbol (call it 207 * <em>x</em>) to the variable(s) determined by the 'math' expression in which 208 * <em>x</em> appears. This graph must be acyclic. 209 * 210 * SBML does not specify when or how often rules should be evaluated. 211 * Eliminating algebraic loops ensures that assignment statements can be 212 * evaluated any number of times without the result of those evaluations 213 * changing. As an example, consider the set of equations <em>x = x + 1</em>, 214 * <em>y = z + 200</em> and <em>z = y + 100</em>. If this set of equations 215 * were interpreted as a set of assignment statements, it would be invalid 216 * because the rule for <em>x</em> refers to <em>x</em> (exhibiting one type 217 * of loop), and the rule for <em>y</em> refers to <em>z</em> while the rule 218 * for <em>z</em> refers back to <em>y</em> (exhibiting another type of loop). 219 * Conversely, the following set of equations would constitute a valid set of 220 * assignment statements: <em>x = 10</em>, <em>y = z + 200</em>, and <em>z = x 221 * + 100</em>. 222 * 223 * @subsection rules-not-overdetermined A model must not be overdetermined 224 * 225 * An SBML model must not be overdetermined; that is, a model must not 226 * define more equations than there are unknowns in a model. A valid SBML model 227 * that does not contain AlgebraicRule structures cannot be overdetermined. 228 * 229 * LibSBML implements the static analysis procedure described in 230 * Appendix B of the SBML Level 3 231 * specification for assessing whether a model is overdetermined. 232 * 233 * (In summary, assessing whether a given continuous, deterministic, 234 * mathematical model is overdetermined does not require dynamic analysis; it 235 * can be done by analyzing the system of equations created from the model. 236 * One approach is to construct a bipartite graph in which one set of vertices 237 * represents the variables and the other the set of vertices represents the 238 * equations. Place edges between vertices such that variables in the system 239 * are linked to the equations that determine them. For algebraic equations, 240 * there will be edges between the equation and each variable occurring in the 241 * equation. For ordinary differential equations (such as those defined by 242 * rate rules or implied by the reaction rate definitions), there will be a 243 * single edge between the equation and the variable determined by that 244 * differential equation. A mathematical model is overdetermined if the 245 * maximal matchings of the bipartite graph contain disconnected vertexes 246 * representing equations. If one maximal matching has this property, then 247 * all the maximal matchings will have this property; i.e., it is only 248 * necessary to find one maximal matching.) 249 * 250 * @section RuleType_t Rule types for SBML Level 1 251 * 252 * SBML Level 1 uses a different scheme than SBML Level 2 and Level 3 for 253 * distinguishing rules; specifically, it uses an attribute whose value is 254 * drawn from an enumeration of 3 values. LibSBML supports this using methods 255 * that work @if clike a libSBML enumeration type, 256 * @link Rule::RuleType_t RuleType_t@endlink, whose values 257 * are @else with the enumeration values @endif listed below. 258 * 259 * @li @link libsbml#RULE_TYPE_RATE RULE_TYPE_RATE@endlink: Indicates 260 * the rule is a 'rate' rule. 261 * @li @link libsbml#RULE_TYPE_SCALAR RULE_TYPE_SCALAR@endlink: 262 * Indicates the rule is a 'scalar' rule. 263 * @li @link libsbml#RULE_TYPE_INVALID RULE_TYPE_INVALID@endlink: 264 * Indicates the rule type is unknown or not yet set. 265 * 266 * 267 */ 268 269 public class RateRule : Rule { 270 private HandleRef swigCPtr; 271 RateRule(IntPtr cPtr, bool cMemoryOwn)272 internal RateRule(IntPtr cPtr, bool cMemoryOwn) : base(libsbmlPINVOKE.RateRule_SWIGUpcast(cPtr), cMemoryOwn) 273 { 274 //super(libsbmlPINVOKE.RateRuleUpcast(cPtr), cMemoryOwn); 275 swigCPtr = new HandleRef(this, cPtr); 276 } 277 getCPtr(RateRule obj)278 internal static HandleRef getCPtr(RateRule obj) 279 { 280 return (obj == null) ? new HandleRef(null, IntPtr.Zero) : obj.swigCPtr; 281 } 282 getCPtrAndDisown(RateRule obj)283 internal static HandleRef getCPtrAndDisown (RateRule obj) 284 { 285 HandleRef ptr = new HandleRef(null, IntPtr.Zero); 286 287 if (obj != null) 288 { 289 ptr = obj.swigCPtr; 290 obj.swigCMemOwn = false; 291 } 292 293 return ptr; 294 } 295 Dispose(bool disposing)296 protected override void Dispose(bool disposing) { 297 lock(this) { 298 if (swigCPtr.Handle != global::System.IntPtr.Zero) { 299 if (swigCMemOwn) { 300 swigCMemOwn = false; 301 libsbmlPINVOKE.delete_RateRule(swigCPtr); 302 } 303 swigCPtr = new global::System.Runtime.InteropServices.HandleRef(null, global::System.IntPtr.Zero); 304 } 305 base.Dispose(disposing); 306 } 307 } 308 309 310 /** 311 * Creates a new RateRule using the given SBML @p level and @p version 312 * values. 313 * 314 * @param level a long integer, the SBML Level to assign to this RateRule. 315 * 316 * @param version a long integer, the SBML Version to assign to this 317 * RateRule. 318 * 319 * 320 * @throws SBMLConstructorException 321 * Thrown if the given @p level and @p version combination are invalid 322 * or if this object is incompatible with the given level and version. 323 * 324 * 325 * 326 * 327 * @note Attempting to add an object to an SBMLDocument having a different 328 * combination of SBML Level, Version and XML namespaces than the object 329 * itself will result in an error at the time a caller attempts to make the 330 * addition. A parent object must have compatible Level, Version and XML 331 * namespaces. (Strictly speaking, a parent may also have more XML 332 * namespaces than a child, but the reverse is not permitted.) The 333 * restriction is necessary to ensure that an SBML model has a consistent 334 * overall structure. This requires callers to manage their objects 335 * carefully, but the benefit is increased flexibility in how models can be 336 * created by permitting callers to create objects bottom-up if desired. In 337 * situations where objects are not yet attached to parents (e.g., 338 * SBMLDocument), knowledge of the intented SBML Level and Version help 339 * libSBML determine such things as whether it is valid to assign a 340 * particular value to an attribute. 341 * 342 * 343 */ public RateRule(long level, long version)344 RateRule(long level, long version) : this(libsbmlPINVOKE.new_RateRule__SWIG_0(level, version), true) { 345 if (libsbmlPINVOKE.SWIGPendingException.Pending) throw libsbmlPINVOKE.SWIGPendingException.Retrieve(); 346 } 347 348 349 /** 350 * Creates a new RateRule using the given SBMLNamespaces object 351 * @p sbmlns. 352 * 353 * 354 * 355 * The SBMLNamespaces object encapsulates SBML Level/Version/namespaces 356 * information. It is used to communicate the SBML Level, Version, and (in 357 * Level 3) packages used in addition to SBML Level 3 Core. A 358 * common approach to using libSBML's SBMLNamespaces facilities is to create an 359 * SBMLNamespaces object somewhere in a program once, then hand that object 360 * as needed to object constructors that accept SBMLNamespaces as arguments. 361 * 362 * 363 * 364 * @param sbmlns an SBMLNamespaces object. 365 * 366 * 367 * @throws SBMLConstructorException 368 * Thrown if the given @p sbmlns is inconsistent or incompatible 369 * with this object. 370 * 371 * 372 * 373 * 374 * @note Attempting to add an object to an SBMLDocument having a different 375 * combination of SBML Level, Version and XML namespaces than the object 376 * itself will result in an error at the time a caller attempts to make the 377 * addition. A parent object must have compatible Level, Version and XML 378 * namespaces. (Strictly speaking, a parent may also have more XML 379 * namespaces than a child, but the reverse is not permitted.) The 380 * restriction is necessary to ensure that an SBML model has a consistent 381 * overall structure. This requires callers to manage their objects 382 * carefully, but the benefit is increased flexibility in how models can be 383 * created by permitting callers to create objects bottom-up if desired. In 384 * situations where objects are not yet attached to parents (e.g., 385 * SBMLDocument), knowledge of the intented SBML Level and Version help 386 * libSBML determine such things as whether it is valid to assign a 387 * particular value to an attribute. 388 * 389 * 390 */ public RateRule(SBMLNamespaces sbmlns)391 RateRule(SBMLNamespaces sbmlns) : this(libsbmlPINVOKE.new_RateRule__SWIG_1(SBMLNamespaces.getCPtr(sbmlns)), true) { 392 if (libsbmlPINVOKE.SWIGPendingException.Pending) throw libsbmlPINVOKE.SWIGPendingException.Retrieve(); 393 } 394 395 396 /** 397 * Creates and returns a deep copy of this RateRule object. 398 * 399 * @return the (deep) copy of this RateRule object. 400 */ public new clone()401 RateRule clone() { 402 global::System.IntPtr cPtr = libsbmlPINVOKE.RateRule_clone(swigCPtr); 403 RateRule ret = (cPtr == global::System.IntPtr.Zero) ? null : new RateRule(cPtr, true); 404 return ret; 405 } 406 407 408 /** 409 * Predicate returning @c true if 410 * all the required attributes for this RateRule object 411 * have been set. 412 * 413 * In SBML Levels 2–3, the only required attribute for a 414 * RateRule object is 'variable'. For Level 1, where the equivalent 415 * attribute is known by different names ('compartment', 'species', or 416 * 'name', depending on the type of object), there is an additional 417 * required attribute called 'formula'. 418 * 419 * @return @c true if the required attributes have been set, @c false 420 * otherwise. 421 */ public new hasRequiredAttributes()422 bool hasRequiredAttributes() { 423 bool ret = libsbmlPINVOKE.RateRule_hasRequiredAttributes(swigCPtr); 424 return ret; 425 } 426 427 428 /** 429 * 430 * Replaces all uses of a given @c SIdRef type attribute value with another 431 * value. 432 * 433 * 434 * 435 436 * In SBML, object identifiers are of a data type called <code>SId</code>. 437 * In SBML Level 3, an explicit data type called <code>SIdRef</code> was 438 * introduced for attribute values that refer to <code>SId</code> values; in 439 * previous Levels of SBML, this data type did not exist and attributes were 440 * simply described to as 'referring to an identifier', but the effective 441 * data type was the same as <code>SIdRef</code> in Level 3. These and 442 * other methods of libSBML refer to the type <code>SIdRef</code> for all 443 * Levels of SBML, even if the corresponding SBML specification did not 444 * explicitly name the data type. 445 * 446 * 447 * 448 * This method works by looking at all attributes and (if appropriate) 449 * mathematical formulas in MathML content, comparing the referenced 450 * identifiers to the value of @p oldid. If any matches are found, the 451 * matching values are replaced with @p newid. The method does @em not 452 * descend into child elements. 453 * 454 * @param oldid the old identifier. 455 * @param newid the new identifier. 456 * 457 * 458 */ public new renameSIdRefs(string oldid, string newid)459 void renameSIdRefs(string oldid, string newid) { 460 libsbmlPINVOKE.RateRule_renameSIdRefs(swigCPtr, oldid, newid); 461 } 462 463 } 464 465 } 466