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