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