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