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