001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 2.0.12 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 * Implementation of SBML's Rule construct. 013 <p> 014 * In SBML, <em>rules</em> provide additional ways to define the values of 015 * variables in a model, their relationships, and the dynamical behaviors 016 * of those variables. They enable encoding relationships that cannot be 017 * expressed using {@link Reaction} nor {@link InitialAssignment} objects alone. 018 <p> 019 * The libSBML implementation of rules mirrors the SBML Level 3 020 * Version 1 Core definition (which is in turn is very similar to the 021 * Level 2 Version 4 definition), with {@link Rule} being the parent 022 * class of three subclasses as explained below. The {@link Rule} class itself 023 * cannot be instantiated by user programs and has no constructor; only the 024 * subclasses {@link AssignmentRule}, {@link AlgebraicRule} and {@link RateRule} can be 025 * instantiated directly. 026 <p> 027 * <p> 028 * <h2>General summary of SBML rules</h2> 029 <p> 030 * In SBML Level 3 as well as Level 2, rules are separated into three 031 * subclasses for the benefit of model analysis software. The three 032 * subclasses are based on the following three different possible functional 033 * forms (where <em>x</em> is a variable, <em>f</em> is some arbitrary 034 * function returning a numerical result, <b><em>V</em></b> is a vector of 035 * variables that does not include <em>x</em>, and <b><em>W</em></b> is a 036 * vector of variables that may include <em>x</em>): 037 <p> 038 * <table border='0' cellpadding='0' class='centered' style='font-size: small'> 039 * <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> 040 * <tr><td><em>Assignment:</em></td><td>left-hand side is a scalar:</td><td><em>x = f(<b>V</b>)</em></td></tr> 041 * <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> 042 * </table> 043 <p> 044 * In their general form given above, there is little to distinguish 045 * between <em>assignment</em> and <em>algebraic</em> rules. They are treated as 046 * separate cases for the following reasons: 047 <p> 048 * <ul> 049 * <li> <em>Assignment</em> rules can simply be evaluated to calculate 050 * intermediate values for use in numerical methods. They are statements 051 * of equality that hold at all times. (For assignments that are only 052 * performed once, see {@link InitialAssignment}.) 053<p> 054 * <li> SBML needs to place restrictions on assignment rules, for example 055 * the restriction that assignment rules cannot contain algebraic loops. 056 <p> 057 * <li> Some simulators do not contain numerical solvers capable of solving 058 * unconstrained algebraic equations, and providing more direct forms such 059 * as assignment rules may enable those simulators to process models they 060 * could not process if the same assignments were put in the form of 061 * general algebraic equations; 062 <p> 063 * <li> Those simulators that <em>can</em> solve these algebraic equations make a 064 * distinction between the different categories listed above; and 065 <p> 066 * <li> Some specialized numerical analyses of models may only be applicable 067 * to models that do not contain <em>algebraic</em> rules. 068 * 069 * </ul> <p> 070 * The approach taken to covering these cases in SBML is to define an 071 * abstract {@link Rule} structure containing a subelement, 'math', to hold the 072 * right-hand side expression, then to derive subtypes of {@link Rule} that add 073 * attributes to distinguish the cases of algebraic, assignment and rate 074 * rules. The 'math' subelement must contain a MathML expression defining the 075 * mathematical formula of the rule. This MathML formula must return a 076 * numerical value. The formula can be an arbitrary expression referencing 077 * the variables and other entities in an SBML model. 078 <p> 079 * Each of the three subclasses of {@link Rule} (AssignmentRule, {@link AlgebraicRule}, 080 * {@link RateRule}) inherit the the 'math' subelement and other fields from {@link SBase}. 081 * The {@link AssignmentRule} and {@link RateRule} classes add an additional attribute, 082 * 'variable'. See the definitions of {@link AssignmentRule}, {@link AlgebraicRule} and 083 * {@link RateRule} for details about the structure and interpretation of each one. 084 <p> 085 * <h2>Additional restrictions on SBML rules</h2> 086 <p> 087 * An important design goal of SBML rule semantics is to ensure that a 088 * model's simulation and analysis results will not be dependent on when or 089 * how often rules are evaluated. To achieve this, SBML needs to place two 090 * restrictions on rule use. The first concerns algebraic loops in the system 091 * of assignments in a model, and the second concerns overdetermined systems. 092 <p> 093 * <h3>A model must not contain algebraic loops</h3> 094 <p> 095 * The combined set of {@link InitialAssignment}, {@link AssignmentRule} and {@link KineticLaw} 096 * objects in a model constitute a set of assignment statements that should be 097 * considered as a whole. (A {@link KineticLaw} object is counted as an assignment 098 * because it assigns a value to the symbol contained in the 'id' attribute of 099 * the {@link Reaction} object in which it is defined.) This combined set of 100 * assignment statements must not contain algebraic loops—dependency 101 * chains between these statements must terminate. To put this more formally, 102 * consider a directed graph in which nodes are assignment statements and 103 * directed arcs exist for each occurrence of an SBML species, compartment or 104 * parameter symbol in an assignment statement's 'math' subelement. Let the 105 * directed arcs point from the statement assigning the symbol to the 106 * statements that contain the symbol in their 'math' subelement expressions. 107 * This graph must be acyclic. 108 <p> 109 * SBML does not specify when or how often rules should be evaluated. 110 * Eliminating algebraic loops ensures that assignment statements can be 111 * evaluated any number of times without the result of those evaluations 112 * changing. As an example, consider the set of equations <em>x = x + 1</em>, 113 * <em>y = z + 200</em> and <em>z = y + 100</em>. If this set of equations 114 * were interpreted as a set of assignment statements, it would be invalid 115 * because the rule for <em>x</em> refers to <em>x</em> (exhibiting one type 116 * of loop), and the rule for <em>y</em> refers to <em>z</em> while the rule 117 * for <em>z</em> refers back to <em>y</em> (exhibiting another type of loop). 118 * Conversely, the following set of equations would constitute a valid set of 119 * assignment statements: <em>x = 10</em>, <em>y = z + 200</em>, and <em>z = x 120 * + 100</em>. 121 <p> 122 * <h3>A model must not be overdetermined</h3> 123 <p> 124 * An SBML model must not be overdetermined; that is, a model must not 125 * define more equations than there are unknowns in a model. An SBML model 126 * that does not contain {@link AlgebraicRule} structures cannot be overdetermined. 127 <p> 128 * LibSBML implements the static analysis procedure described in 129 * Appendix B of the SBML Level 3 Version 1 Core 130 * specification for assessing whether a model is overdetermined. 131 <p> 132 * (In summary, assessing whether a given continuous, deterministic, 133 * mathematical model is overdetermined does not require dynamic analysis; it 134 * can be done by analyzing the system of equations created from the model. 135 * One approach is to construct a bipartite graph in which one set of vertices 136 * represents the variables and the other the set of vertices represents the 137 * equations. Place edges between vertices such that variables in the system 138 * are linked to the equations that determine them. For algebraic equations, 139 * there will be edges between the equation and each variable occurring in the 140 * equation. For ordinary differential equations (such as those defined by 141 * rate rules or implied by the reaction rate definitions), there will be a 142 * single edge between the equation and the variable determined by that 143 * differential equation. A mathematical model is overdetermined if the 144 * maximal matchings of the bipartite graph contain disconnected vertexes 145 * representing equations. If one maximal matching has this property, then 146 * all the maximal matchings will have this property; i.e., it is only 147 * necessary to find one maximal matching.) 148 <p> 149 * <h2>Rule types for SBML Level 1</h2> 150 <p> 151 * SBML Level 1 uses a different scheme than SBML Level 2 and Level 3 for 152 * distinguishing rules; specifically, it uses an attribute whose value is 153 * drawn from an enumeration of 3 values. LibSBML supports this using methods 154 * that work with the enumeration values listed below. 155 <p> 156 * <ul> 157 * <li> {@link libsbmlConstants#RULE_TYPE_RATE RULE_TYPE_RATE}: Indicates 158 * the rule is a 'rate' rule. 159 * <li> {@link libsbmlConstants#RULE_TYPE_SCALAR RULE_TYPE_SCALAR}: 160 * Indicates the rule is a 'scalar' rule. 161 * <li> {@link libsbmlConstants#RULE_TYPE_INVALID RULE_TYPE_INVALID}: 162 * Indicates the rule type is unknown or not yet set. 163 * 164 * </ul> 165 */ 166 167public class Rule extends SBase { 168 private long swigCPtr; 169 170 protected Rule(long cPtr, boolean cMemoryOwn) 171 { 172 super(libsbmlJNI.Rule_SWIGUpcast(cPtr), cMemoryOwn); 173 swigCPtr = cPtr; 174 } 175 176 protected static long getCPtr(Rule obj) 177 { 178 return (obj == null) ? 0 : obj.swigCPtr; 179 } 180 181 protected static long getCPtrAndDisown (Rule obj) 182 { 183 long ptr = 0; 184 185 if (obj != null) 186 { 187 ptr = obj.swigCPtr; 188 obj.swigCMemOwn = false; 189 } 190 191 return ptr; 192 } 193 194 protected void finalize() { 195 delete(); 196 } 197 198 public synchronized void delete() { 199 if (swigCPtr != 0) { 200 if (swigCMemOwn) { 201 swigCMemOwn = false; 202 libsbmlJNI.delete_Rule(swigCPtr); 203 } 204 swigCPtr = 0; 205 } 206 super.delete(); 207 } 208 209 210/** 211 * Copy constructor; creates a copy of this {@link Rule}. 212 <p> 213 * @param orig the object to copy. 214 <p> 215 * @throws SBMLConstructorException 216 * Thrown if the argument <code>orig</code> is <code>null.</code> 217 */ public 218 Rule(Rule orig) { 219 this(libsbmlJNI.new_Rule(Rule.getCPtr(orig), orig), true); 220 } 221 222 223/** 224 * Creates and returns a deep copy of this {@link Rule}. 225 <p> 226 * @return a (deep) copy of this {@link Rule}. 227 */ public 228 Rule cloneObject() { 229 return (Rule) libsbml.DowncastSBase(libsbmlJNI.Rule_cloneObject(swigCPtr, this), true); 230} 231 232 233/** 234 * Returns the mathematical expression of this {@link Rule} in text-string form. 235 <p> 236 * The text string is produced by 237 * <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'>libsbml.formulaToString()</a></code>; please consult 238 * the documentation for that function to find out more about the format 239 * of the text-string formula. 240 <p> 241 * @return the formula text string for this {@link Rule}. 242 <p> 243 * @note The attribute 'formula' is specific to SBML Level 1; in 244 * higher Levels of SBML, it has been replaced with a subelement named 245 * 'math'. However, libSBML provides a unified interface to the 246 * underlying math expression and this method can be used for models 247 * of all Levels of SBML. 248 <p> 249 * @see #getMath() 250 */ public 251 String getFormula() { 252 return libsbmlJNI.Rule_getFormula(swigCPtr, this); 253 } 254 255 256/** 257 * Get the mathematical formula of this {@link Rule} as an {@link ASTNode} tree. 258 <p> 259 * @return an {@link ASTNode}, the value of the 'math' subelement of this {@link Rule}. 260 <p> 261 * @note The subelement 'math' is present in SBML Levels 2 262 * and 3. In SBML Level 1, the equivalent construct is the 263 * attribute named 'formula'. LibSBML provides a unified interface to 264 * the underlying math expression and this method can be used for models 265 * of all Levels of SBML. 266 <p> 267 * @see #getFormula() 268 */ public 269 ASTNode getMath() { 270 long cPtr = libsbmlJNI.Rule_getMath(swigCPtr, this); 271 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 272 } 273 274 275/** 276 * Get the value of the 'variable' attribute of this {@link Rule} object. 277 <p> 278 * <p> 279 * In SBML Level 1, the different rule types each have a different 280 * name for the attribute holding the reference to the object constituting 281 * the left-hand side of the rule. (E.g., for SBML Level 1's 282 * SpeciesConcentrationRule the attribute is 'species', for 283 * CompartmentVolumeRule it is 'compartment', etc.) In SBML Levels 2 284 * and 3, the only two types of {@link Rule} objects with a left-hand side 285 * object reference are {@link AssignmentRule} and {@link RateRule}, and both of them use the 286 * same name for attribute: 'variable'. In order to make it easier for 287 * application developers to work with all Levels of SBML, libSBML uses a 288 * uniform name for all such attributes, and it is 'variable', regardless of 289 * whether Level 1 rules or Level 2–3 rules are being used. 290 <p> 291 * @return the identifier string stored as the 'variable' attribute value 292 * in this {@link Rule}, or <code>null</code> if this object is an {@link AlgebraicRule} object. 293 */ public 294 String getVariable() { 295 return libsbmlJNI.Rule_getVariable(swigCPtr, this); 296 } 297 298 299/** 300 * Returns the units for the 301 * mathematical formula of this {@link Rule}. 302 <p> 303 * @return the identifier of the units for the expression of this {@link Rule}. 304 <p> 305 * @note The attribute 'units' exists on SBML Level 1 ParameterRule 306 * objects only. It is not present in SBML Levels 2 and 3. 307 */ public 308 String getUnits() { 309 return libsbmlJNI.Rule_getUnits(swigCPtr, this); 310 } 311 312 313/** 314 * Predicate returning <code>true</code> if this {@link Rule}'s mathematical expression is 315 * set. 316 <p> 317 * This method is equivalent to isSetMath(). This version is present for 318 * easier compatibility with SBML Level 1, in which mathematical 319 * formulas were written in text-string form. 320 <p> 321 * @return <code>true</code> if the mathematical formula for this {@link Rule} is 322 * set, <code>false</code> otherwise. 323 <p> 324 * @note The attribute 'formula' is specific to SBML Level 1; in 325 * higher Levels of SBML, it has been replaced with a subelement named 326 * 'math'. However, libSBML provides a unified interface to the 327 * underlying math expression and this method can be used for models 328 * of all Levels of SBML. 329 <p> 330 * @see #isSetMath() 331 */ public 332 boolean isSetFormula() { 333 return libsbmlJNI.Rule_isSetFormula(swigCPtr, this); 334 } 335 336 337/** 338 * Predicate returning <code>true</code> if this {@link Rule}'s mathematical expression is 339 * set. 340 <p> 341 * This method is equivalent to isSetFormula(). 342 <p> 343 * @return <code>true</code> if the formula (or equivalently the math) for this 344 * {@link Rule} is set, <code>false</code> otherwise. 345 <p> 346 * @note The subelement 'math' is present in SBML Levels 2 347 * and 3. In SBML Level 1, the equivalent construct is the 348 * attribute named 'formula'. LibSBML provides a unified interface to 349 * the underlying math expression and this method can be used for models 350 * of all Levels of SBML. 351 <p> 352 * @see #isSetFormula() 353 */ public 354 boolean isSetMath() { 355 return libsbmlJNI.Rule_isSetMath(swigCPtr, this); 356 } 357 358 359/** 360 * Predicate returning <code>true</code> if this {@link Rule}'s 'variable' attribute is set. 361 <p> 362 * <p> 363 * In SBML Level 1, the different rule types each have a different 364 * name for the attribute holding the reference to the object constituting 365 * the left-hand side of the rule. (E.g., for SBML Level 1's 366 * SpeciesConcentrationRule the attribute is 'species', for 367 * CompartmentVolumeRule it is 'compartment', etc.) In SBML Levels 2 368 * and 3, the only two types of {@link Rule} objects with a left-hand side 369 * object reference are {@link AssignmentRule} and {@link RateRule}, and both of them use the 370 * same name for attribute: 'variable'. In order to make it easier for 371 * application developers to work with all Levels of SBML, libSBML uses a 372 * uniform name for all such attributes, and it is 'variable', regardless of 373 * whether Level 1 rules or Level 2–3 rules are being used. 374 <p> 375 * @return <code>true</code> if the 'variable' attribute value of this {@link Rule} is 376 * set, <code>false</code> otherwise. 377 */ public 378 boolean isSetVariable() { 379 return libsbmlJNI.Rule_isSetVariable(swigCPtr, this); 380 } 381 382 383/** 384 * Predicate returning <code>true</code> if this {@link Rule}'s 'units' attribute is set. 385 <p> 386 * @return <code>true</code> if the units for this {@link Rule} is set, <code>false</code> 387 * otherwise 388 <p> 389 * @note The attribute 'units' exists on SBML Level 1 ParameterRule 390 * objects only. It is not present in SBML Levels 2 and 3. 391 */ public 392 boolean isSetUnits() { 393 return libsbmlJNI.Rule_isSetUnits(swigCPtr, this); 394 } 395 396 397/** 398 * Sets the 'math' subelement of this {@link Rule} to an expression in text-string 399 * form. 400 <p> 401 * This is equivalent to setMath(ASTNode math). The provision of 402 * using text-string formulas is retained for easier SBML Level 1 403 * compatibility. The formula is converted to an {@link ASTNode} internally. 404 <p> 405 * @param formula a mathematical formula in text-string form. 406 <p> 407 * @return integer value indicating success/failure of the 408 * function. The possible values 409 * returned by this function are: 410 * <ul> 411 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 412 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT } 413 * 414 * </ul> <p> 415 * @note The attribute 'formula' is specific to SBML Level 1; in 416 * higher Levels of SBML, it has been replaced with a subelement named 417 * 'math'. However, libSBML provides a unified interface to the 418 * underlying math expression and this method can be used for models 419 * of all Levels of SBML. 420 <p> 421 * @see #setMath(ASTNode math) 422 */ public 423 int setFormula(String formula) { 424 return libsbmlJNI.Rule_setFormula(swigCPtr, this, formula); 425 } 426 427 428/** 429 * Sets the 'math' subelement of this {@link Rule} to a copy of the given 430 * {@link ASTNode}. 431 <p> 432 * @param math the ASTNode_t structure of the mathematical formula. 433 <p> 434 * @return integer value indicating success/failure of the 435 * function. The possible values 436 * returned by this function are: 437 * <ul> 438 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 439 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT } 440 * 441 * </ul> <p> 442 * @note The subelement 'math' is present in SBML Levels 2 443 * and 3. In SBML Level 1, the equivalent construct is the 444 * attribute named 'formula'. LibSBML provides a unified interface to 445 * the underlying math expression and this method can be used for models 446 * of all Levels of SBML. 447 <p> 448 * @see #setFormula(String formula) 449 */ public 450 int setMath(ASTNode math) { 451 return libsbmlJNI.Rule_setMath(swigCPtr, this, ASTNode.getCPtr(math), math); 452 } 453 454 455/** 456 * Sets the 'variable' attribute value of this {@link Rule} object. 457 <p> 458 * <p> 459 * In SBML Level 1, the different rule types each have a different 460 * name for the attribute holding the reference to the object constituting 461 * the left-hand side of the rule. (E.g., for SBML Level 1's 462 * SpeciesConcentrationRule the attribute is 'species', for 463 * CompartmentVolumeRule it is 'compartment', etc.) In SBML Levels 2 464 * and 3, the only two types of {@link Rule} objects with a left-hand side 465 * object reference are {@link AssignmentRule} and {@link RateRule}, and both of them use the 466 * same name for attribute: 'variable'. In order to make it easier for 467 * application developers to work with all Levels of SBML, libSBML uses a 468 * uniform name for all such attributes, and it is 'variable', regardless of 469 * whether Level 1 rules or Level 2–3 rules are being used. 470 <p> 471 * @param sid the identifier of a {@link Compartment}, {@link Species} or {@link Parameter} 472 * elsewhere in the enclosing {@link Model} object. 473 <p> 474 * @return integer value indicating success/failure of the 475 * function. The possible values 476 * returned by this function are: 477 * <ul> 478 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 479 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE } 480 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE } 481 * </ul> 482 */ public 483 int setVariable(String sid) { 484 return libsbmlJNI.Rule_setVariable(swigCPtr, this, sid); 485 } 486 487 488/** 489 * Sets the units for this {@link Rule}. 490 <p> 491 * @param sname the identifier of the units 492 <p> 493 * @return integer value indicating success/failure of the 494 * function. The possible values 495 * returned by this function are: 496 * <ul> 497 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 498 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE } 499 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE } 500 * 501 * </ul> <p> 502 * @note The attribute 'units' exists on SBML Level 1 ParameterRule 503 * objects only. It is not present in SBML Levels 2 and 3. 504 */ public 505 int setUnits(String sname) { 506 return libsbmlJNI.Rule_setUnits(swigCPtr, this, sname); 507 } 508 509 510/** 511 * Unsets the 'units' for this {@link Rule}. 512 <p> 513 * @return integer value indicating success/failure of the 514 * function. The possible values 515 * returned by this function are: 516 * <ul> 517 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 518 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED } 519 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE } 520 * 521 * </ul> <p> 522 * @note The attribute 'units' exists on SBML Level 1 ParameterRule 523 * objects only. It is not present in SBML Levels 2 and 3. 524 */ public 525 int unsetUnits() { 526 return libsbmlJNI.Rule_unsetUnits(swigCPtr, this); 527 } 528 529 530/** 531 * Calculates and returns a {@link UnitDefinition} that expresses the units of 532 * measurement assumed for the 'math' expression of this {@link Rule}. 533 <p> 534 * <p> 535 * The units are calculated based on the mathematical expression in the 536 * {@link Rule} and the model quantities referenced by <code><ci></code> 537 * elements used within that expression. The method 538 * {@link Rule#getDerivedUnitDefinition()} returns the calculated units, to the 539 * extent that libSBML can compute them. 540 <p> 541 * <p> 542 * @note The functionality that facilitates unit analysis depends on the 543 * model as a whole. Thus, in cases where the object has not been added to 544 * a model or the model itself is incomplete, unit analysis is not possible 545 * and this method will return <code>null.</code> 546 <p> 547 * <p> 548 * @warning <span class='warning'>Note that it is possible the 'math' 549 * expression in the {@link Rule} contains pure numbers or parameters with undeclared 550 * units. In those cases, it is not possible to calculate the units of the 551 * overall expression without making assumptions. LibSBML does not make 552 * assumptions about the units, and {@link Rule#getDerivedUnitDefinition()} only 553 * returns the units as far as it is able to determine them. For example, in 554 * an expression <em>X + Y</em>, if <em>X</em> has unambiguously-defined 555 * units and <em>Y</em> does not, it will return the units of <em>X</em>. 556 * <strong>It is important that callers also invoke the method</strong> 557 * {@link Rule#containsUndeclaredUnits()} <strong>to determine whether this 558 * situation holds</strong>. Callers may wish to take suitable actions in 559 * those scenarios.</span> 560 <p> 561 * @return a {@link UnitDefinition} that expresses the units of the math 562 * expression of this {@link Rule}, or <code>null</code> if one cannot be constructed. 563 <p> 564 * @see #containsUndeclaredUnits() 565 */ public 566 UnitDefinition getDerivedUnitDefinition() { 567 long cPtr = libsbmlJNI.Rule_getDerivedUnitDefinition__SWIG_0(swigCPtr, this); 568 return (cPtr == 0) ? null : new UnitDefinition(cPtr, false); 569 } 570 571 572/** 573 * Predicate returning <code>true</code> if the math expression of this {@link Rule} contains 574 * parameters/numbers with undeclared units. 575 <p> 576 * @return <code>true</code> if the math expression of this {@link Rule} includes 577 * parameters/numbers with undeclared units, <code>false</code> otherwise. 578 <p> 579 * @note A return value of <code>true</code> indicates that the {@link UnitDefinition} 580 * returned by getDerivedUnitDefinition() may not accurately represent 581 * the units of the expression. 582 <p> 583 * @see #getDerivedUnitDefinition() 584 */ public 585 boolean containsUndeclaredUnits() { 586 return libsbmlJNI.Rule_containsUndeclaredUnits__SWIG_0(swigCPtr, this); 587 } 588 589 590/** 591 * Returns a code representing the type of rule this is. 592 <p> 593 * @return the rule type, which will be one of the following three possible 594 * values: 595 * * 596 * <ul> 597 * <li> {@link libsbmlConstants#RULE_TYPE_RATE RULE_TYPE_RATE} 598 * <li> {@link libsbmlConstants#RULE_TYPE_SCALAR RULE_TYPE_SCALAR} 599 * <li> {@link libsbmlConstants#RULE_TYPE_INVALID RULE_TYPE_INVALID} 600 * 601 * </ul> <p> 602 <p> 603 * @note The attribute 'type' on {@link Rule} objects is present only in SBML 604 * Level 1. In SBML Level 2 and later, the type has been 605 * replaced by subclassing the {@link Rule} object. 606 */ public 607 int getType() { 608 return libsbmlJNI.Rule_getType(swigCPtr, this); 609 } 610 611 612/** 613 * Predicate returning <code>true</code> if this {@link Rule} is an {@link AlgebraicRule}. 614 <p> 615 * @return <code>true</code> if this {@link Rule} is an {@link AlgebraicRule}, <code>false</code> otherwise. 616 */ public 617 boolean isAlgebraic() { 618 return libsbmlJNI.Rule_isAlgebraic(swigCPtr, this); 619 } 620 621 622/** 623 * Predicate returning <code>true</code> if this {@link Rule} is an {@link AssignmentRule}. 624 <p> 625 * @return <code>true</code> if this {@link Rule} is an {@link AssignmentRule}, <code>false</code> otherwise. 626 */ public 627 boolean isAssignment() { 628 return libsbmlJNI.Rule_isAssignment(swigCPtr, this); 629 } 630 631 632/** 633 * Predicate returning <code>true</code> if this {@link Rule} is an CompartmentVolumeRule 634 * or equivalent. 635 <p> 636 * This libSBML method works for SBML Level 1 models (where there is 637 * such a thing as an explicit CompartmentVolumeRule), as well as other Levels of 638 * SBML. For Levels above Level 1, this method checks the symbol 639 * being affected by the rule, and returns <code>true</code> if the symbol is the 640 * identifier of a {@link Compartment} object defined in the model. 641 <p> 642 * @return <code>true</code> if this {@link Rule} is a CompartmentVolumeRule, <code>false</code> 643 * otherwise. 644 */ public 645 boolean isCompartmentVolume() { 646 return libsbmlJNI.Rule_isCompartmentVolume(swigCPtr, this); 647 } 648 649 650/** 651 * Predicate returning <code>true</code> if this {@link Rule} is an ParameterRule or 652 * equivalent. 653 <p> 654 * This libSBML method works for SBML Level 1 models (where there is 655 * such a thing as an explicit ParameterRule), as well as other Levels of 656 * SBML. For Levels above Level 1, this method checks the symbol 657 * being affected by the rule, and returns <code>true</code> if the symbol is the 658 * identifier of a {@link Parameter} object defined in the model. 659 <p> 660 * @return <code>true</code> if this {@link Rule} is a ParameterRule, <code>false</code> 661 * otherwise. 662 */ public 663 boolean isParameter() { 664 return libsbmlJNI.Rule_isParameter(swigCPtr, this); 665 } 666 667 668/** 669 * Predicate returning <code>true</code> if this {@link Rule} is a {@link RateRule} (SBML 670 * Levels 2–3) or has a 'type' attribute value of <code>'rate'</code> 671 * (SBML Level 1). 672 <p> 673 * @return <code>true</code> if this {@link Rule} is a {@link RateRule} (Level 2) or has 674 * type 'rate' (Level 1), <code>false</code> otherwise. 675 */ public 676 boolean isRate() { 677 return libsbmlJNI.Rule_isRate(swigCPtr, this); 678 } 679 680 681/** 682 * Predicate returning <code>true</code> if this {@link Rule} is an {@link AssignmentRule} (SBML 683 * Levels 2–3) or has a 'type' attribute value of <code>'scalar'</code> 684 * (SBML Level 1). 685 <p> 686 * @return <code>true</code> if this {@link Rule} is an {@link AssignmentRule} (Level 2) or has 687 * type 'scalar' (Level 1), <code>false</code> otherwise. 688 */ public 689 boolean isScalar() { 690 return libsbmlJNI.Rule_isScalar(swigCPtr, this); 691 } 692 693 694/** 695 * Predicate returning <code>true</code> if this {@link Rule} is a SpeciesConcentrationRule 696 * or equivalent. 697 <p> 698 * This libSBML method works for SBML Level 1 models (where there is 699 * such a thing as an explicit SpeciesConcentrationRule), as well as 700 * other Levels of SBML. For Levels above Level 1, this method 701 * checks the symbol being affected by the rule, and returns <code>true</code> if 702 * the symbol is the identifier of a {@link Species} object defined in the model. 703 <p> 704 * @return <code>true</code> if this {@link Rule} is a SpeciesConcentrationRule, <code>false</code> 705 * otherwise. 706 */ public 707 boolean isSpeciesConcentration() { 708 return libsbmlJNI.Rule_isSpeciesConcentration(swigCPtr, this); 709 } 710 711 712/** 713 * Returns the libSBML type code for this SBML object. 714 <p> 715 * <p> 716 * LibSBML attaches an identifying code to every kind of SBML object. These 717 * are integer constants known as <em>SBML type codes</em>. The names of all 718 * the codes begin with the characters “<code>SBML_</code>”. 719 * In the Java language interface for libSBML, the 720 * type codes are defined as static integer constants in the interface class 721 * {@link libsbmlConstants}. Note that different Level 3 722 * package plug-ins may use overlapping type codes; to identify the package 723 * to which a given object belongs, call the <code>getPackageName()</code> 724 * method on the object. 725 <p> 726 * @return the SBML type code for this object, either 727 * {@link libsbmlConstants#SBML_ASSIGNMENT_RULE SBML_ASSIGNMENT_RULE}, 728 * {@link libsbmlConstants#SBML_RATE_RULE SBML_RATE_RULE}, or 729 * {@link libsbmlConstants#SBML_ALGEBRAIC_RULE SBML_ALGEBRAIC_RULE} 730 * for SBML Core. 731 <p> 732 * <p> 733 * @warning <span class='warning'>The specific integer values of the possible 734 * type codes may be reused by different Level 3 package plug-ins. 735 * Thus, to identifiy the correct code, <strong>it is necessary to invoke 736 * both getTypeCode() and getPackageName()</strong>.</span> 737 <p> 738 * @see #getElementName() 739 * @see #getPackageName() 740 */ public 741 int getTypeCode() { 742 return libsbmlJNI.Rule_getTypeCode(swigCPtr, this); 743 } 744 745 746/** 747 * Returns the SBML Level 1 type code for this {@link Rule} object. 748 <p> 749 * This method only applies to SBML Level 1 model objects. If this 750 * is not an SBML Level 1 rule object, this method will return {@link 751 * libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN}. 752 <p> 753 * @return the SBML Level 1 type code for this {@link Rule} (namely, {@link 754 * libsbmlConstants#SBML_COMPARTMENT_VOLUME_RULE 755 * SBML_COMPARTMENT_VOLUME_RULE}, {@link 756 * libsbmlConstants#SBML_PARAMETER_RULE SBML_PARAMETER_RULE}, {@link 757 * libsbmlConstants#SBML_SPECIES_CONCENTRATION_RULE 758 * SBML_SPECIES_CONCENTRATION_RULE}, or {@link 759 * libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN}). 760 */ public 761 int getL1TypeCode() { 762 return libsbmlJNI.Rule_getL1TypeCode(swigCPtr, this); 763 } 764 765 766/** 767 * Returns the XML element name of this object 768 <p> 769 * The returned value can be any of a number of different strings, 770 * depending on the SBML Level in use and the kind of {@link Rule} object this 771 * is. The rules as of libSBML version 5.10.0 772 773 * are the following: 774 * <ul> 775 * <li> (Level 2 and 3) RateRule: returns <code>'rateRule'</code> 776 * <li> (Level 2 and 3) AssignmentRule: returns <code>'assignmentRule'</code> 777 * <li> (Level 2 and 3) AlgebraicRule: returns <code>'algebraicRule'</code> 778 * <li> (Level 1 Version 1) SpecieConcentrationRule: returns <code>'specieConcentrationRule'</code> 779 * <li> (Level 1 Version 2) SpeciesConcentrationRule: returns <code>'speciesConcentrationRule'</code> 780 * <li> (Level 1) CompartmentVolumeRule: returns <code>'compartmentVolumeRule'</code> 781 * <li> (Level 1) ParameterRule: returns <code>'parameterRule'</code> 782 * <li> Unknown rule type: returns <code>'unknownRule'</code> 783 * </ul> 784 <p> 785 * Beware that the last (<code>'unknownRule'</code>) is not a valid SBML element 786 * name. 787 <p> 788 * @return the name of this element 789 */ public 790 String getElementName() { 791 return libsbmlJNI.Rule_getElementName(swigCPtr, this); 792 } 793 794 795/** 796 * Sets the SBML Level 1 type code for this {@link Rule}. 797 <p> 798 * @param type the SBML Level 1 type code for this {@link Rule}. The 799 * allowable values are {@link libsbmlConstants#SBML_COMPARTMENT_VOLUME_RULE 800 * SBML_COMPARTMENT_VOLUME_RULE}, {@link 801 * libsbmlConstants#SBML_PARAMETER_RULE SBML_PARAMETER_RULE}, and 802 * {@link libsbmlConstants#SBML_SPECIES_CONCENTRATION_RULE 803 * SBML_SPECIES_CONCENTRATION_RULE}. 804 <p> 805 * @return integer value indicating success/failure of the 806 * function. The possible values returned by this function are: 807 * <ul> 808 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 809 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 810 * if given <code>type</code> value is not one of the above. 811 * </ul> 812 */ public 813 int setL1TypeCode(int type) { 814 return libsbmlJNI.Rule_setL1TypeCode(swigCPtr, this, type); 815 } 816 817 818/** 819 * Predicate returning <code>true</code> if all the required elements for this {@link Rule} 820 * object have been set. 821 <p> 822 * The only required element for a {@link Rule} object is the 'math' subelement. 823 <p> 824 * @return a boolean value indicating whether all the required 825 * elements for this object have been defined. 826 */ public 827 boolean hasRequiredElements() { 828 return libsbmlJNI.Rule_hasRequiredElements(swigCPtr, this); 829 } 830 831 832/** 833 * Predicate returning <code>true</code> if all the required attributes for this {@link Rule} 834 * object have been set. 835 <p> 836 * The required attributes for a {@link Rule} object depend on the type of {@link Rule} 837 * it is. For {@link AssignmentRule} and {@link RateRule} objects (and SBML 838 * Level 1's SpeciesConcentrationRule, CompartmentVolumeRule, and 839 * ParameterRule objects), the required attribute is 'variable'; for 840 * {@link AlgebraicRule} objects, there is no required attribute. 841 <p> 842 * @return a boolean value indicating whether all the required 843 * elements for this object have been defined. 844 */ public 845 boolean hasRequiredAttributes() { 846 return libsbmlJNI.Rule_hasRequiredAttributes(swigCPtr, this); 847 } 848 849 850/** 851 * Renames all the <code>SIdRef</code> attributes on this element, including any 852 * found in MathML. 853 <p> 854 * <p> 855 * In SBML, object identifiers are of a data type called <code>SId</code>. 856 * In SBML Level 3, an explicit data type called <code>SIdRef</code> was 857 * introduced for attribute values that refer to <code>SId</code> values; in 858 * previous Levels of SBML, this data type did not exist and attributes were 859 * simply described to as 'referring to an identifier', but the effective 860 * data type was the same as <code>SIdRef</code>in Level 3. These and 861 * other methods of libSBML refer to the type <code>SIdRef</code> for all 862 * Levels of SBML, even if the corresponding SBML specification did not 863 * explicitly name the data type. 864 <p> 865 * This method works by looking at all attributes and (if appropriate) 866 * mathematical formulas, comparing the identifiers to the value of 867 * <code>oldid</code>. If any matches are found, the matching identifiers are replaced 868 * with <code>newid</code>. The method does <em>not</em> descend into child elements. 869 <p> 870 * @param oldid the old identifier 871 * @param newid the new identifier 872 */ public 873 void renameSIdRefs(String oldid, String newid) { 874 libsbmlJNI.Rule_renameSIdRefs(swigCPtr, this, oldid, newid); 875 } 876 877 878/** 879 * Renames all the <code>UnitSIdRef</code> attributes on this element. 880 <p> 881 * <p> 882 * In SBML, unit definitions have identifiers of type <code>UnitSId</code>. In 883 * SBML Level 3, an explicit data type called <code>UnitSIdRef</code> was 884 * introduced for attribute values that refer to <code>UnitSId</code> values; in 885 * previous Levels of SBML, this data type did not exist and attributes were 886 * simply described to as 'referring to a unit identifier', but the effective 887 * data type was the same as <code>UnitSIdRef</code> in Level 3. These and 888 * other methods of libSBML refer to the type <code>UnitSIdRef</code> for all 889 * Levels of SBML, even if the corresponding SBML specification did not 890 * explicitly name the data type. 891 <p> 892 * This method works by looking at all unit identifier attribute values 893 * (including, if appropriate, inside mathematical formulas), comparing the 894 * unit identifiers to the value of <code>oldid</code>. If any matches are found, 895 * the matching identifiers are replaced with <code>newid</code>. The method does 896 * <em>not</em> descend into child elements. 897 <p> 898 * @param oldid the old identifier 899 * @param newid the new identifier 900 */ public 901 void renameUnitSIdRefs(String oldid, String newid) { 902 libsbmlJNI.Rule_renameUnitSIdRefs(swigCPtr, this, oldid, newid); 903 } 904 905 906/** * @internal */ public 907 String getId() { 908 return libsbmlJNI.Rule_getId(swigCPtr, this); 909 } 910 911 912/** 913 * Replace all nodes with the name 'id' from the child 'math' object with the provided function. 914 <p> 915 * @internal 916 */ public 917 void replaceSIDWithFunction(String id, ASTNode function) { 918 libsbmlJNI.Rule_replaceSIDWithFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 919 } 920 921 922/** 923 * If this rule assigns a value or a change to the 'id' element, replace the 'math' object with the function (existing/function). 924 * @internal 925 */ public 926 void divideAssignmentsToSIdByFunction(String id, ASTNode function) { 927 libsbmlJNI.Rule_divideAssignmentsToSIdByFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 928 } 929 930 931/** 932 * If this assignment assigns a value to the 'id' element, replace the 'math' object with the function (existing*function). 933 * @internal 934 */ public 935 void multiplyAssignmentsToSIdByFunction(String id, ASTNode function) { 936 libsbmlJNI.Rule_multiplyAssignmentsToSIdByFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 937 } 938 939}