001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 3.0.10 004 * 005 * Do not make changes to this file unless you know what you are doing--modify 006 * the SWIG interface file instead. 007 * ----------------------------------------------------------------------------- */ 008 009package org.sbml.libsbml; 010 011/** 012 * 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 * 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 */ public 215 Rule(Rule orig) { 216 this(libsbmlJNI.new_Rule(Rule.getCPtr(orig), orig), true); 217 } 218 219 220/** 221 * Creates and returns a deep copy of this {@link Rule} object. 222 <p> 223 * @return the (deep) copy of this {@link Rule} object. 224 */ public 225 Rule cloneObject() { 226 return (Rule) libsbml.DowncastSBase(libsbmlJNI.Rule_cloneObject(swigCPtr, this), true); 227} 228 229 230/** 231 * Returns the mathematical expression of this {@link Rule} in text-string form. 232 <p> 233 * The text string is produced by 234 * <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'>libsbml.formulaToString()</a></code>; please consult 235 * the documentation for that function to find out more about the format 236 * of the text-string formula. 237 <p> 238 * @return the formula text string for this {@link Rule}. 239 <p> 240 * @note The attribute 'formula' is specific to SBML Level 1; in 241 * higher Levels of SBML, it has been replaced with a subelement named 242 * 'math'. However, libSBML provides a unified interface to the 243 * underlying math expression and this method can be used for models 244 * of all Levels of SBML. 245 <p> 246 * @see #getMath() 247 */ public 248 String getFormula() { 249 return libsbmlJNI.Rule_getFormula(swigCPtr, this); 250 } 251 252 253/** 254 * Get the mathematical formula of this {@link Rule} as an {@link ASTNode} tree. 255 <p> 256 * @return an {@link ASTNode}, the value of the 'math' subelement of this {@link Rule}. 257 <p> 258 * @note The subelement 'math' is present in SBML Levels 2 259 * and 3. In SBML Level 1, the equivalent construct is the 260 * attribute named 'formula'. LibSBML provides a unified interface to 261 * the underlying math expression and this method can be used for models 262 * of all Levels of SBML. 263 <p> 264 * @see #getFormula() 265 */ public 266 ASTNode getMath() { 267 long cPtr = libsbmlJNI.Rule_getMath(swigCPtr, this); 268 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 269 } 270 271 272/** 273 * Get the value of the 'variable' attribute of this {@link Rule} object. 274 <p> 275 * <p> 276 * In SBML Level 1, the different rule types each have a different 277 * name for the attribute holding the reference to the object constituting 278 * the left-hand side of the rule. (E.g., for SBML Level 1's 279 * SpeciesConcentrationRule the attribute is 'species', for 280 * CompartmentVolumeRule it is 'compartment', etc.) In SBML Levels 2 281 * and 3, the only two types of {@link Rule} objects with a left-hand side 282 * object reference are {@link AssignmentRule} and {@link RateRule}, and both of them use the 283 * same name for attribute: 'variable'. In order to make it easier for 284 * application developers to work with all Levels of SBML, libSBML uses a 285 * uniform name for all such attributes, and it is 'variable', regardless of 286 * whether Level 1 rules or Level 2–3 rules are being used. 287 <p> 288 * @return the identifier string stored as the 'variable' attribute value 289 * in this {@link Rule}, or <code>null</code> if this object is an {@link AlgebraicRule} object. 290 */ public 291 String getVariable() { 292 return libsbmlJNI.Rule_getVariable(swigCPtr, this); 293 } 294 295 296/** 297 * Returns the units for the 298 * mathematical formula of this {@link Rule}. 299 <p> 300 * @return the identifier of the units for the expression of this {@link Rule}. 301 <p> 302 * @note The attribute 'units' exists on SBML Level 1 ParameterRule 303 * objects only. It is not present in SBML Levels 2 and 3. 304 */ public 305 String getUnits() { 306 return libsbmlJNI.Rule_getUnits(swigCPtr, this); 307 } 308 309 310/** 311 * Predicate returning <code>true</code> if this {@link Rule}'s mathematical expression is 312 * set. 313 <p> 314 * This method is equivalent to isSetMath(). This version is present for 315 * easier compatibility with SBML Level 1, in which mathematical 316 * formulas were written in text-string form. 317 <p> 318 * @return <code>true</code> if the mathematical formula for this {@link Rule} is 319 * set, <code>false</code> otherwise. 320 <p> 321 * @note The attribute 'formula' is specific to SBML Level 1; in 322 * higher Levels of SBML, it has been replaced with a subelement named 323 * 'math'. However, libSBML provides a unified interface to the 324 * underlying math expression and this method can be used for models 325 * of all Levels of SBML. 326 <p> 327 * @see #isSetMath() 328 */ public 329 boolean isSetFormula() { 330 return libsbmlJNI.Rule_isSetFormula(swigCPtr, this); 331 } 332 333 334/** 335 * Predicate returning <code>true</code> if this {@link Rule}'s mathematical expression is 336 * set. 337 <p> 338 * This method is equivalent to isSetFormula(). 339 <p> 340 * @return <code>true</code> if the formula (or equivalently the math) for this 341 * {@link Rule} is set, <code>false</code> otherwise. 342 <p> 343 * @note The subelement 'math' is present in SBML Levels 2 344 * and 3. In SBML Level 1, the equivalent construct is the 345 * attribute named 'formula'. LibSBML provides a unified interface to 346 * the underlying math expression and this method can be used for models 347 * of all Levels of SBML. 348 <p> 349 * @see #isSetFormula() 350 */ public 351 boolean isSetMath() { 352 return libsbmlJNI.Rule_isSetMath(swigCPtr, this); 353 } 354 355 356/** 357 * Predicate returning <code>true</code> if this {@link Rule}'s 'variable' attribute is set. 358 <p> 359 * <p> 360 * In SBML Level 1, the different rule types each have a different 361 * name for the attribute holding the reference to the object constituting 362 * the left-hand side of the rule. (E.g., for SBML Level 1's 363 * SpeciesConcentrationRule the attribute is 'species', for 364 * CompartmentVolumeRule it is 'compartment', etc.) In SBML Levels 2 365 * and 3, the only two types of {@link Rule} objects with a left-hand side 366 * object reference are {@link AssignmentRule} and {@link RateRule}, and both of them use the 367 * same name for attribute: 'variable'. In order to make it easier for 368 * application developers to work with all Levels of SBML, libSBML uses a 369 * uniform name for all such attributes, and it is 'variable', regardless of 370 * whether Level 1 rules or Level 2–3 rules are being used. 371 <p> 372 * @return <code>true</code> if the 'variable' attribute value of this {@link Rule} is 373 * set, <code>false</code> otherwise. 374 */ public 375 boolean isSetVariable() { 376 return libsbmlJNI.Rule_isSetVariable(swigCPtr, this); 377 } 378 379 380/** 381 * Predicate returning <code>true</code> if this {@link Rule}'s 'units' attribute is set. 382 <p> 383 * @return <code>true</code> if the units for this {@link Rule} is set, <code>false</code> 384 * otherwise 385 <p> 386 * @note The attribute 'units' exists on SBML Level 1 ParameterRule 387 * objects only. It is not present in SBML Levels 2 and 3. 388 */ public 389 boolean isSetUnits() { 390 return libsbmlJNI.Rule_isSetUnits(swigCPtr, this); 391 } 392 393 394/** 395 * Sets the 'math' subelement of this {@link Rule} to an expression in text-string 396 * form. 397 <p> 398 * This is equivalent to setMath(ASTNode math). The provision of 399 * using text-string formulas is retained for easier SBML Level 1 400 * compatibility. The formula is converted to an {@link ASTNode} internally. 401 <p> 402 * @param formula a mathematical formula in text-string form. 403 <p> 404 * <p> 405 * @return integer value indicating success/failure of the 406 * function. The possible values 407 * returned by this function are: 408 * <ul> 409 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 410 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT} 411 * 412 * </ul> <p> 413 * @note The attribute 'formula' is specific to SBML Level 1; in 414 * higher Levels of SBML, it has been replaced with a subelement named 415 * 'math'. However, libSBML provides a unified interface to the 416 * underlying math expression and this method can be used for models 417 * of all Levels of SBML. 418 <p> 419 * @see #setMath(ASTNode math) 420 */ public 421 int setFormula(String formula) { 422 return libsbmlJNI.Rule_setFormula(swigCPtr, this, formula); 423 } 424 425 426/** 427 * Sets the 'math' subelement of this {@link Rule} to a copy of the given 428 * {@link ASTNode}. 429 <p> 430 * @param math the AST structure of the mathematical formula. 431 <p> 432 * <p> 433 * @return integer value indicating success/failure of the 434 * function. The possible values 435 * returned by this function are: 436 * <ul> 437 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 438 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT} 439 * 440 * </ul> <p> 441 * @note The subelement 'math' is present in SBML Levels 2 442 * and 3. In SBML Level 1, the equivalent construct is the 443 * attribute named 'formula'. LibSBML provides a unified interface to 444 * the underlying math expression and this method can be used for models 445 * of all Levels of SBML. 446 <p> 447 * @see #setFormula(String formula) 448 */ public 449 int setMath(ASTNode math) { 450 return libsbmlJNI.Rule_setMath(swigCPtr, this, ASTNode.getCPtr(math), math); 451 } 452 453 454/** 455 * Sets the 'variable' attribute value of this {@link Rule} object. 456 <p> 457 * <p> 458 * In SBML Level 1, the different rule types each have a different 459 * name for the attribute holding the reference to the object constituting 460 * the left-hand side of the rule. (E.g., for SBML Level 1's 461 * SpeciesConcentrationRule the attribute is 'species', for 462 * CompartmentVolumeRule it is 'compartment', etc.) In SBML Levels 2 463 * and 3, the only two types of {@link Rule} objects with a left-hand side 464 * object reference are {@link AssignmentRule} and {@link RateRule}, and both of them use the 465 * same name for attribute: 'variable'. In order to make it easier for 466 * application developers to work with all Levels of SBML, libSBML uses a 467 * uniform name for all such attributes, and it is 'variable', regardless of 468 * whether Level 1 rules or Level 2–3 rules are being used. 469 <p> 470 * @param sid the identifier of a {@link Compartment}, {@link Species} or {@link Parameter} 471 * elsewhere in the enclosing {@link Model} object. 472 <p> 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 * <p> 494 * @return integer value indicating success/failure of the 495 * function. The possible values 496 * returned by this function are: 497 * <ul> 498 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 499 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 500 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 501 * 502 * </ul> <p> 503 * @note The attribute 'units' exists on SBML Level 1 ParameterRule 504 * objects only. It is not present in SBML Levels 2 and 3. 505 */ public 506 int setUnits(String sname) { 507 return libsbmlJNI.Rule_setUnits(swigCPtr, this, sname); 508 } 509 510 511/** 512 * Unsets the value of the 'variable' attribute of this {@link Rule} object. 513 <p> 514 * <p> 515 * @return integer value indicating success/failure of the 516 * function. The possible values 517 * returned by this function are: 518 * <ul> 519 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 520 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 521 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 522 * 523 * </ul> <p> 524 * @see #setVariable(String sid) 525 * @see #isSetVariable() 526 * @see #getVariable() 527 */ public 528 int unsetVariable() { 529 return libsbmlJNI.Rule_unsetVariable(swigCPtr, this); 530 } 531 532 533/** 534 * Unsets the 'units' for this {@link Rule}. 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 * @note The attribute 'units' exists on SBML Level 1 ParameterRule 547 * objects only. It is not present in SBML Levels 2 and 3. 548 */ public 549 int unsetUnits() { 550 return libsbmlJNI.Rule_unsetUnits(swigCPtr, this); 551 } 552 553 554/** 555 * Calculates and returns a {@link UnitDefinition} that expresses the units of 556 * measurement assumed for the 'math' expression of this {@link Rule}. 557 <p> 558 * <p> 559 * The units are calculated based on the mathematical expression in the 560 * {@link Rule} and the model quantities referenced by <code><ci></code> 561 * elements used within that expression. The method 562 * {@link Rule#getDerivedUnitDefinition()} returns the calculated units, to the 563 * extent that libSBML can compute them. 564 <p> 565 * <p> 566 * @note The functionality that facilitates unit analysis depends on the 567 * model as a whole. Thus, in cases where the object has not been added to 568 * a model or the model itself is incomplete, unit analysis is not possible 569 * and this method will return <code>null.</code> 570 <p> 571 * <p> 572 * @warning <span class='warning'>Note that it is possible the 'math' 573 * expression in the {@link Rule} contains pure numbers or parameters with undeclared 574 * units. In those cases, it is not possible to calculate the units of the 575 * overall expression without making assumptions. LibSBML does not make 576 * assumptions about the units, and {@link Rule#getDerivedUnitDefinition()} only 577 * returns the units as far as it is able to determine them. For example, in 578 * an expression <em>X + Y</em>, if <em>X</em> has unambiguously-defined 579 * units and <em>Y</em> does not, it will return the units of <em>X</em>. 580 * <strong>It is important that callers also invoke the method</strong> 581 * {@link Rule#containsUndeclaredUnits()} <strong>to determine whether this 582 * situation holds</strong>. Callers may wish to take suitable actions in 583 * those scenarios.</span> 584 <p> 585 * @return a {@link UnitDefinition} that expresses the units of the math 586 * expression of this {@link Rule}, or <code>null</code> if one cannot be constructed. 587 <p> 588 * @see #containsUndeclaredUnits() 589 */ public 590 UnitDefinition getDerivedUnitDefinition() { 591 long cPtr = libsbmlJNI.Rule_getDerivedUnitDefinition__SWIG_0(swigCPtr, this); 592 return (cPtr == 0) ? null : new UnitDefinition(cPtr, false); 593 } 594 595 596/** 597 * Predicate returning <code>true</code> if the math expression of this {@link Rule} contains 598 * parameters/numbers with undeclared units. 599 <p> 600 * @return <code>true</code> if the math expression of this {@link Rule} includes 601 * parameters/numbers with undeclared units, <code>false</code> otherwise. 602 <p> 603 * @note A return value of <code>true</code> indicates that the {@link UnitDefinition} 604 * returned by getDerivedUnitDefinition() may not accurately represent 605 * the units of the expression. 606 <p> 607 * @see #getDerivedUnitDefinition() 608 */ public 609 boolean containsUndeclaredUnits() { 610 return libsbmlJNI.Rule_containsUndeclaredUnits__SWIG_0(swigCPtr, this); 611 } 612 613 614/** 615 * Returns a code representing the type of rule this is. 616 <p> 617 * @return the rule type, which will be one of the following three possible 618 * values: 619 * <ul> 620 * <li> {@link libsbmlConstants#RULE_TYPE_RATE RULE_TYPE_RATE} 621 * <li> {@link libsbmlConstants#RULE_TYPE_SCALAR RULE_TYPE_SCALAR} 622 * <li> {@link libsbmlConstants#RULE_TYPE_INVALID RULE_TYPE_INVALID} 623 * 624 * </ul> <p> 625 * @note The attribute 'type' on {@link Rule} objects is present only in SBML 626 * Level 1. In SBML Level 2 and later, the type has been 627 * replaced by subclassing the {@link Rule} object. 628 */ public 629 int getType() { 630 return libsbmlJNI.Rule_getType(swigCPtr, this); 631 } 632 633 634/** 635 * Predicate returning <code>true</code> if this {@link Rule} is an {@link AlgebraicRule}. 636 <p> 637 * @return <code>true</code> if this {@link Rule} is an {@link AlgebraicRule}, <code>false</code> otherwise. 638 */ public 639 boolean isAlgebraic() { 640 return libsbmlJNI.Rule_isAlgebraic(swigCPtr, this); 641 } 642 643 644/** 645 * Predicate returning <code>true</code> if this {@link Rule} is an {@link AssignmentRule}. 646 <p> 647 * @return <code>true</code> if this {@link Rule} is an {@link AssignmentRule}, <code>false</code> otherwise. 648 */ public 649 boolean isAssignment() { 650 return libsbmlJNI.Rule_isAssignment(swigCPtr, this); 651 } 652 653 654/** 655 * Predicate returning <code>true</code> if this {@link Rule} is an CompartmentVolumeRule 656 * or equivalent. 657 <p> 658 * This libSBML method works for SBML Level 1 models (where there is 659 * such a thing as an explicit CompartmentVolumeRule), as well as other Levels of 660 * SBML. For Levels above Level 1, this method checks the symbol 661 * being affected by the rule, and returns <code>true</code> if the symbol is the 662 * identifier of a {@link Compartment} object defined in the model. 663 <p> 664 * @return <code>true</code> if this {@link Rule} is a CompartmentVolumeRule, <code>false</code> 665 * otherwise. 666 */ public 667 boolean isCompartmentVolume() { 668 return libsbmlJNI.Rule_isCompartmentVolume(swigCPtr, this); 669 } 670 671 672/** 673 * Predicate returning <code>true</code> if this {@link Rule} is an ParameterRule or 674 * equivalent. 675 <p> 676 * This libSBML method works for SBML Level 1 models (where there is 677 * such a thing as an explicit ParameterRule), as well as other Levels of 678 * SBML. For Levels above Level 1, this method checks the symbol 679 * being affected by the rule, and returns <code>true</code> if the symbol is the 680 * identifier of a {@link Parameter} object defined in the model. 681 <p> 682 * @return <code>true</code> if this {@link Rule} is a ParameterRule, <code>false</code> 683 * otherwise. 684 */ public 685 boolean isParameter() { 686 return libsbmlJNI.Rule_isParameter(swigCPtr, this); 687 } 688 689 690/** 691 * Predicate returning <code>true</code> if this {@link Rule} is a {@link RateRule} (SBML 692 * Levels 2–3) or has a 'type' attribute value of <code>'rate'</code> 693 * (SBML Level 1). 694 <p> 695 * @return <code>true</code> if this {@link Rule} is a {@link RateRule} (Level 2) or has 696 * type 'rate' (Level 1), <code>false</code> otherwise. 697 */ public 698 boolean isRate() { 699 return libsbmlJNI.Rule_isRate(swigCPtr, this); 700 } 701 702 703/** 704 * Predicate returning <code>true</code> if this {@link Rule} is an {@link AssignmentRule} (SBML 705 * Levels 2–3) or has a 'type' attribute value of <code>'scalar'</code> 706 * (SBML Level 1). 707 <p> 708 * @return <code>true</code> if this {@link Rule} is an {@link AssignmentRule} (Level 2) or has 709 * type 'scalar' (Level 1), <code>false</code> otherwise. 710 */ public 711 boolean isScalar() { 712 return libsbmlJNI.Rule_isScalar(swigCPtr, this); 713 } 714 715 716/** 717 * Predicate returning <code>true</code> if this {@link Rule} is a SpeciesConcentrationRule 718 * or equivalent. 719 <p> 720 * This libSBML method works for SBML Level 1 models (where there is 721 * such a thing as an explicit SpeciesConcentrationRule), as well as 722 * other Levels of SBML. For Levels above Level 1, this method 723 * checks the symbol being affected by the rule, and returns <code>true</code> if 724 * the symbol is the identifier of a {@link Species} object defined in the model. 725 <p> 726 * @return <code>true</code> if this {@link Rule} is a SpeciesConcentrationRule, <code>false</code> 727 * otherwise. 728 */ public 729 boolean isSpeciesConcentration() { 730 return libsbmlJNI.Rule_isSpeciesConcentration(swigCPtr, this); 731 } 732 733 734/** 735 * Returns the libSBML type code for this SBML object. 736 <p> 737 * <p> 738 * LibSBML attaches an identifying code to every kind of SBML object. These 739 * are integer constants known as <em>SBML type codes</em>. The names of all 740 * the codes begin with the characters <code>SBML_</code>. 741 * In the Java language interface for libSBML, the 742 * type codes are defined as static integer constants in the interface class 743 * {@link libsbmlConstants}. Note that different Level 3 744 * package plug-ins may use overlapping type codes; to identify the package 745 * to which a given object belongs, call the <code>getPackageName()</code> 746 * method on the object. 747 <p> 748 * @return the SBML type code for this object, either 749 * {@link libsbmlConstants#SBML_ASSIGNMENT_RULE SBML_ASSIGNMENT_RULE}, 750 * {@link libsbmlConstants#SBML_RATE_RULE SBML_RATE_RULE}, or 751 * {@link libsbmlConstants#SBML_ALGEBRAIC_RULE SBML_ALGEBRAIC_RULE} 752 * for SBML Core. 753 <p> 754 * <p> 755 * @warning <span class='warning'>The specific integer values of the possible 756 * type codes may be reused by different libSBML plug-ins for SBML Level 3. 757 * packages, To fully identify the correct code, <strong>it is necessary to 758 * invoke both getTypeCode() and getPackageName()</strong>.</span> 759 <p> 760 * @see #getElementName() 761 * @see #getPackageName() 762 */ public 763 int getTypeCode() { 764 return libsbmlJNI.Rule_getTypeCode(swigCPtr, this); 765 } 766 767 768/** 769 * Returns the SBML Level 1 type code for this {@link Rule} object. 770 <p> 771 * This method only applies to SBML Level 1 model objects. If this is 772 * not an SBML Level 1 rule object, this method will return 773 * {@link libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN}. 774 <p> 775 * @return the SBML Level 1 type code for this {@link Rule} (namely, 776 * {@link libsbmlConstants#SBML_COMPARTMENT_VOLUME_RULE SBML_COMPARTMENT_VOLUME_RULE}, 777 * {@link libsbmlConstants#SBML_PARAMETER_RULE SBML_PARAMETER_RULE}, 778 * {@link libsbmlConstants#SBML_SPECIES_CONCENTRATION_RULE SBML_SPECIES_CONCENTRATION_RULE}, or 779 * {@link libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN}). 780 */ public 781 int getL1TypeCode() { 782 return libsbmlJNI.Rule_getL1TypeCode(swigCPtr, this); 783 } 784 785 786/** 787 * Returns the XML element name of this object. 788 <p> 789 * The returned value can be any of a number of different strings, 790 * depending on the SBML Level in use and the kind of {@link Rule} object this 791 * is. The rules as of libSBML version 5.13.0 792 793 * are the following: 794 * <ul> 795 * <li> (Level 2 and 3) RateRule: returns <code>'rateRule'</code> 796 * <li> (Level 2 and 3) AssignmentRule: returns <code>'assignmentRule'</code> 797 * <li> (Level 2 and 3) AlgebraicRule: returns <code>'algebraicRule'</code> 798 * <li> (Level 1 Version 1) SpecieConcentrationRule: returns <code>'specieConcentrationRule'</code> 799 * <li> (Level 1 Version 2) SpeciesConcentrationRule: returns <code>'speciesConcentrationRule'</code> 800 * <li> (Level 1) CompartmentVolumeRule: returns <code>'compartmentVolumeRule'</code> 801 * <li> (Level 1) ParameterRule: returns <code>'parameterRule'</code> 802 * <li> Unknown rule type: returns <code>'unknownRule'</code> 803 * </ul> 804 <p> 805 * Beware that the last (<code>'unknownRule'</code>) is not a valid SBML element 806 * name. 807 <p> 808 * @return the name of this element 809 */ public 810 String getElementName() { 811 return libsbmlJNI.Rule_getElementName(swigCPtr, this); 812 } 813 814 815/** 816 * Sets the SBML Level 1 type code for this {@link Rule}. 817 <p> 818 * @param type the SBML Level 1 type code for this {@link Rule}. The allowable 819 * values are {@link libsbmlConstants#SBML_COMPARTMENT_VOLUME_RULE SBML_COMPARTMENT_VOLUME_RULE}, 820 * {@link libsbmlConstants#SBML_PARAMETER_RULE SBML_PARAMETER_RULE}, and 821 * {@link libsbmlConstants#SBML_SPECIES_CONCENTRATION_RULE SBML_SPECIES_CONCENTRATION_RULE}. 822 <p> 823 * <p> 824 * @return integer value indicating success/failure of the 825 * function. The possible values 826 * returned by this function are: 827 * <ul> 828 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 829 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 830 * if given <code>type</code> value is not one of the above. 831 * </ul> 832 */ public 833 int setL1TypeCode(int type) { 834 return libsbmlJNI.Rule_setL1TypeCode(swigCPtr, this, type); 835 } 836 837 838/** 839 * Predicate returning <code>true</code> if all the required elements for this {@link Rule} 840 * object have been set. 841 <p> 842 * The only required element for a {@link Rule} object is the 'math' subelement. 843 <p> 844 * @return a boolean value indicating whether all the required 845 * elements for this object have been defined. 846 */ public 847 boolean hasRequiredElements() { 848 return libsbmlJNI.Rule_hasRequiredElements(swigCPtr, this); 849 } 850 851 852/** 853 * Predicate returning <code>true</code> if all the required attributes for this {@link Rule} 854 * object have been set. 855 <p> 856 * The required attributes for a {@link Rule} object depend on the type of {@link Rule} 857 * it is. For {@link AssignmentRule} and {@link RateRule} objects (and SBML 858 * Level 1's SpeciesConcentrationRule, CompartmentVolumeRule, and 859 * ParameterRule objects), the required attribute is 'variable'; for 860 * {@link AlgebraicRule} objects, there is no required attribute. 861 <p> 862 * @return <code>true</code> if the required attributes have been set, <code>false</code> 863 * otherwise. 864 */ public 865 boolean hasRequiredAttributes() { 866 return libsbmlJNI.Rule_hasRequiredAttributes(swigCPtr, this); 867 } 868 869 870/** 871 * <p> 872 * Replaces all uses of a given <code>SIdRef</code> type attribute value with another 873 * value. 874 <p> 875 * <p> 876 * In SBML, object identifiers are of a data type called <code>SId</code>. 877 * In SBML Level 3, an explicit data type called <code>SIdRef</code> was 878 * introduced for attribute values that refer to <code>SId</code> values; in 879 * previous Levels of SBML, this data type did not exist and attributes were 880 * simply described to as 'referring to an identifier', but the effective 881 * data type was the same as <code>SIdRef</code>in Level 3. These and 882 * other methods of libSBML refer to the type <code>SIdRef</code> for all 883 * Levels of SBML, even if the corresponding SBML specification did not 884 * explicitly name the data type. 885 <p> 886 * This method works by looking at all attributes and (if appropriate) 887 * mathematical formulas in MathML content, comparing the referenced 888 * identifiers to the value of <code>oldid</code>. If any matches are found, the 889 * matching values are replaced with <code>newid</code>. The method does <em>not</em> 890 * descend into child elements. 891 <p> 892 * @param oldid the old identifier 893 * @param newid the new identifier 894 */ public 895 void renameSIdRefs(String oldid, String newid) { 896 libsbmlJNI.Rule_renameSIdRefs(swigCPtr, this, oldid, newid); 897 } 898 899 900/** 901 * <p> 902 * Replaces all uses of a given <code>UnitSIdRef</code> type attribute value with 903 * another value. 904 <p> 905 * <p> 906 * In SBML, unit definitions have identifiers of type <code>UnitSId</code>. In 907 * SBML Level 3, an explicit data type called <code>UnitSIdRef</code> was 908 * introduced for attribute values that refer to <code>UnitSId</code> values; in 909 * previous Levels of SBML, this data type did not exist and attributes were 910 * simply described to as 'referring to a unit identifier', but the effective 911 * data type was the same as <code>UnitSIdRef</code> in Level 3. These and 912 * other methods of libSBML refer to the type <code>UnitSIdRef</code> for all 913 * Levels of SBML, even if the corresponding SBML specification did not 914 * explicitly name the data type. 915 <p> 916 * This method works by looking at all unit identifier attribute values 917 * (including, if appropriate, inside mathematical formulas), comparing the 918 * referenced unit identifiers to the value of <code>oldid</code>. If any matches 919 * are found, the matching values are replaced with <code>newid</code>. The method 920 * does <em>not</em> descend into child elements. 921 <p> 922 * @param oldid the old identifier 923 * @param newid the new identifier 924 */ public 925 void renameUnitSIdRefs(String oldid, String newid) { 926 libsbmlJNI.Rule_renameUnitSIdRefs(swigCPtr, this, oldid, newid); 927 } 928 929 930/** * @internal */ public 931 String getId() { 932 return libsbmlJNI.Rule_getId(swigCPtr, this); 933 } 934 935 936/** * @internal */ public 937 void replaceSIDWithFunction(String id, ASTNode function) { 938 libsbmlJNI.Rule_replaceSIDWithFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 939 } 940 941 942/** * @internal */ public 943 void divideAssignmentsToSIdByFunction(String id, ASTNode function) { 944 libsbmlJNI.Rule_divideAssignmentsToSIdByFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 945 } 946 947 948/** * @internal */ public 949 void multiplyAssignmentsToSIdByFunction(String id, ASTNode function) { 950 libsbmlJNI.Rule_multiplyAssignmentsToSIdByFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 951 } 952 953}