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&nbsp;3
020 * Version&nbsp;1 Core definition (which is in turn is very similar to the
021 * Level&nbsp;2 Version&nbsp;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&nbsp;3 as well as Level&nbsp;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&mdash;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&nbsp;B of the SBML Level&nbsp;3 Version&nbsp;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&nbsp;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&nbsp;2
262   * and&nbsp;3.  In SBML Level&nbsp;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&nbsp;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&nbsp;1's
282 * SpeciesConcentrationRule the attribute is 'species', for
283 * CompartmentVolumeRule it is 'compartment', etc.)  In SBML Levels&nbsp;2
284 * and&nbsp;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&nbsp;1 rules or Level&nbsp;2&ndash;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&nbsp;1 ParameterRule
306   * objects only.  It is not present in SBML Levels&nbsp;2 and&nbsp;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&nbsp;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&nbsp;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&nbsp;2
347   * and&nbsp;3.  In SBML Level&nbsp;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&nbsp;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&nbsp;1's
366 * SpeciesConcentrationRule the attribute is 'species', for
367 * CompartmentVolumeRule it is 'compartment', etc.)  In SBML Levels&nbsp;2
368 * and&nbsp;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&nbsp;1 rules or Level&nbsp;2&ndash;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&nbsp;1 ParameterRule
390   * objects only.  It is not present in SBML Levels&nbsp;2 and&nbsp;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&nbsp;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&nbsp;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&nbsp;2
443   * and&nbsp;3.  In SBML Level&nbsp;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&nbsp;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&nbsp;1's
462 * SpeciesConcentrationRule the attribute is 'species', for
463 * CompartmentVolumeRule it is 'compartment', etc.)  In SBML Levels&nbsp;2
464 * and&nbsp;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&nbsp;1 rules or Level&nbsp;2&ndash;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&nbsp;1 ParameterRule
503   * objects only.  It is not present in SBML Levels&nbsp;2 and&nbsp;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&nbsp;1 ParameterRule
523   * objects only.  It is not present in SBML Levels&nbsp;2 and&nbsp;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>&lt;ci&gt;</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&nbsp;1.  In SBML Level&nbsp;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&nbsp;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&nbsp;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&nbsp;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&nbsp;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&nbsp;2&ndash;3) or has a 'type' attribute value of <code>'rate'</code>
671   * (SBML Level&nbsp;1).
672   <p>
673   * @return <code>true</code> if this {@link Rule} is a {@link RateRule} (Level&nbsp;2) or has
674   * type 'rate' (Level&nbsp;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&nbsp;2&ndash;3) or has a 'type' attribute value of <code>'scalar'</code>
684   * (SBML Level&nbsp;1).
685   <p>
686   * @return <code>true</code> if this {@link Rule} is an {@link AssignmentRule} (Level&nbsp;2) or has
687   * type 'scalar' (Level&nbsp;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&nbsp;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&nbsp;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 &ldquo;<code>SBML_</code>&rdquo;. 
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&nbsp;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&nbsp;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&nbsp;1 type code for this {@link Rule} object.
748   <p>
749   * This method only applies to SBML Level&nbsp;1 model objects.  If this
750   * is not an SBML Level&nbsp;1 rule object, this method will return {@link 
751   * libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN}.
752   <p>
753   * @return the SBML Level&nbsp;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&nbsp;2 and&nbsp;3) RateRule: returns <code>'rateRule'</code>
776   * <li> (Level&nbsp;2 and&nbsp;3) AssignmentRule: returns <code>'assignmentRule'</code> 
777   * <li> (Level&nbsp;2 and&nbsp;3) AlgebraicRule: returns <code>'algebraicRule'</code>
778   * <li> (Level&nbsp;1 Version&nbsp;1) SpecieConcentrationRule: returns <code>'specieConcentrationRule'</code>
779   * <li> (Level&nbsp;1 Version&nbsp;2) SpeciesConcentrationRule: returns <code>'speciesConcentrationRule'</code>
780   * <li> (Level&nbsp;1) CompartmentVolumeRule: returns <code>'compartmentVolumeRule'</code>
781   * <li> (Level&nbsp;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&nbsp;1 type code for this {@link Rule}.
797   <p>
798   * @param type the SBML Level&nbsp;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&nbsp1'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&nbsp;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&nbsp;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&nbsp;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&nbsp;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}