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