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&nbsp;3
020 * 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 * 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&nbsp;3 Version&nbsp;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&mdash;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&nbsp;B of the SBML Level&nbsp;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&nbsp;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&nbsp;2
276   * and&nbsp;3.  In SBML Level&nbsp;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&nbsp;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&nbsp;1's
296 * SpeciesConcentrationRule the attribute is 'species', for
297 * CompartmentVolumeRule it is 'compartment', etc.)  In SBML Levels&nbsp;2
298 * and&nbsp;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&nbsp;1 rules or Level&nbsp;2&ndash;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&nbsp;1 ParameterRule
325   * objects only.  It is not present in SBML Levels&nbsp;2 and&nbsp;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&nbsp;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&nbsp;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&nbsp;2
366   * and&nbsp;3.  In SBML Level&nbsp;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&nbsp;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&nbsp;1's
385 * SpeciesConcentrationRule the attribute is 'species', for
386 * CompartmentVolumeRule it is 'compartment', etc.)  In SBML Levels&nbsp;2
387 * and&nbsp;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&nbsp;1 rules or Level&nbsp;2&ndash;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&nbsp;1 ParameterRule
409   * objects only.  It is not present in SBML Levels&nbsp;2 and&nbsp;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&nbsp;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&nbsp;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&nbsp;2
464   * and&nbsp;3.  In SBML Level&nbsp;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&nbsp;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&nbsp;1's
483 * SpeciesConcentrationRule the attribute is 'species', for
484 * CompartmentVolumeRule it is 'compartment', etc.)  In SBML Levels&nbsp;2
485 * and&nbsp;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&nbsp;1 rules or Level&nbsp;2&ndash;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&nbsp;1 ParameterRule
526   * objects only.  It is not present in SBML Levels&nbsp;2 and&nbsp;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&nbsp;1 ParameterRule
569   * objects only.  It is not present in SBML Levels&nbsp;2 and&nbsp;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>&lt;ci&gt;</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&nbsp;1.  In SBML Level&nbsp;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&nbsp;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&nbsp;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&nbsp;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&nbsp;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&nbsp;2&ndash;3) or has a 'type' attribute value of <code>'rate'</code>
715   * (SBML Level&nbsp;1).
716   <p>
717   * @return <code>true</code> if this {@link Rule} is a {@link RateRule} (Level&nbsp;2) or has
718   * type 'rate' (Level&nbsp;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&nbsp;2&ndash;3) or has a 'type' attribute value of <code>'scalar'</code>
728   * (SBML Level&nbsp;1).
729   <p>
730   * @return <code>true</code> if this {@link Rule} is an {@link AssignmentRule} (Level&nbsp;2) or has
731   * type 'scalar' (Level&nbsp;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&nbsp;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&nbsp;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&nbsp;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&nbsp;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&nbsp;1 type code for this {@link Rule} object.
794   <p>
795   * This method only applies to SBML Level&nbsp;1 model objects.  If this is
796   * not an SBML Level&nbsp;1 rule object, this method will return
797   * {@link libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN}.
798   <p>
799   * @return the SBML Level&nbsp;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&nbsp;2 and&nbsp;3) RateRule: returns <code>'rateRule'</code>
820   * <li> (Level&nbsp;2 and&nbsp;3) AssignmentRule: returns <code>'assignmentRule'</code> 
821   * <li> (Level&nbsp;2 and&nbsp;3) AlgebraicRule: returns <code>'algebraicRule'</code>
822   * <li> (Level&nbsp;1 Version&nbsp;1) SpecieConcentrationRule: returns <code>'specieConcentrationRule'</code>
823   * <li> (Level&nbsp;1 Version&nbsp;2) SpeciesConcentrationRule: returns <code>'speciesConcentrationRule'</code>
824   * <li> (Level&nbsp;1) CompartmentVolumeRule: returns <code>'compartmentVolumeRule'</code>
825   * <li> (Level&nbsp;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&nbsp;1 type code for this {@link Rule}.
841   <p>
842   * @param type the SBML Level&nbsp;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&nbsp;2 and Level&nbsp;3 Version&nbsp;1.  In SBML Level&nbsp;3
868   * Version&nbsp;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&nbsp;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&nbsp;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&nbsp;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&nbsp;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&nbsp;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}