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 RateRule construct.
014 * <p>
015 * The rule type {@link RateRule} is derived from the parent class {@link Rule}.  It is
016 * used to express equations that determine the rates of change of
017 * variables.  The left-hand side (the 'variable' attribute) can refer to
018 * the identifier of a species, compartment, or parameter (but not a
019 * reaction).  The entity identified must have its 'constant' attribute set
020 * to <code>false.</code>  The effects of a {@link RateRule} are in general terms the same,
021 * but differ in the precise details depending on which variable is being
022 * set:
023 * <p>
024 * <ul> <li> <em>In the case of a species</em>, a {@link RateRule} sets the rate of
025 * change of the species' quantity (<em>concentration</em> or <em>amount of
026 * substance</em>) to the value determined by the formula in the 'math'
027 * subelement of the {@link RateRule} object.  The overall units of the formula in
028 * 'math' <em>should</em> (in SBML Level&nbsp;2 Version&nbsp;4 and in SBML Level&nbsp;3) or 
029 * <em>must</em> (in SBML releases prior to Level&nbsp;2 version&nbsp;4) be equal to
030 * the unit of <em>species quantity</em> divided by the model-wide unit of
031 * <em>time</em>.  <em>Restrictions</em>: There must not be both a {@link RateRule}
032 * 'variable' attribute and a {@link SpeciesReference} 'species' attribute having
033 * the same value, unless that species has its 'boundaryCondition'
034 * attribute is set to <code>true.</code>  This means a rate rule cannot be defined
035 * for a species that is created or destroyed in a reaction, unless that
036 * species is defined as a boundary condition in the model.
037 * <p>
038 * <li> (For SBML Level&nbsp;3 only) <em>In the case of a species
039 * reference</em>, a {@link RateRule} sets the rate of change of the stoichiometry
040 * of the referenced reactant or product to the value determined by the
041 * formula in 'math'.  The unit associated with the value produced by the
042 * 'math' formula should be consistent with the unit 'dimensionless'
043 * divided by the model-wide unit of <em>time</em>.
044 * <p>
045 * <li> <em>In the case of a compartment</em>, a {@link RateRule} sets the rate of
046 * change of the compartment's size to the value determined by the formula
047 * in the 'math' subelement of the {@link RateRule} object.  The overall units of
048 * the formula <em>should</em> (in SBML Level&nbsp;2 Version&nbsp;4 and in SBML
049 * Level&nbsp;3) or <em>must</em> (in SBML releases prior to Level&nbsp;2
050 * version&nbsp;4) be the units of the compartment's <em>size</em> divided
051 * by the model-wide unit of <em>time</em>.
052 * <p>
053 * <li> <em>In the case of a parameter</em>, a {@link RateRule} sets the rate of
054 * change of the parameter's value to that determined by the formula in the
055 * 'math' subelement of the {@link RateRule} object.  The overall units of the
056 * formula <em>should</em> (in SBML Level&nbsp;2 Version&nbsp;4 and in SBML
057 * Level&nbsp;3) or <em>must</em> (in SBML releases prior to Level&nbsp;2
058 * version&nbsp;4) be the {@link Parameter} object's 'unit' attribute value divided
059 * by the model-wide unit of <em>time</em>.  </ul>
060 * <p>
061 * In the context of a simulation, rate rules are in effect for simulation
062 * time <em>t</em> &lt; <em>0</em>.  Please consult the relevant SBML
063 * specification for additional information about the semantics of
064 * assignments, rules, and entity values for simulation time <em>t</em>
065 * &#8804; <em>0</em>.
066 * <p>
067 * As mentioned in the description of {@link AssignmentRule}, a model must not
068 * contain more than one {@link RateRule} or {@link AssignmentRule} object having the same
069 * value of 'variable'; in other words, in the set of all assignment rules
070 * and rate rules in an SBML model, each variable appearing in the
071 * left-hand sides can only appear once.  This simply follows from the fact
072 * that an indeterminate system would result if a model contained more than
073 * one assignment rule for the same variable or both an assignment rule and
074 * a rate rule for the same variable.
075 * <p>
076 * <h2>General summary of SBML rules</h2>
077 * <p>
078 * In SBML Level&nbsp;3 as well as Level&nbsp;2, rules are separated into three
079subclasses for the benefit of model analysis software.  The three
080subclasses are based on the following three different possible functional
081forms (where <em>x</em> is a variable, <em>f</em> is some arbitrary
082function returning a numerical result, <b><em>V</em></b> is a vector of
083variables that does not include <em>x</em>, and <b><em>W</em></b> is a
084vector of variables that may include <em>x</em>):
085
086<center>
087<table border='0' cellpadding='0' style='font-size: small'>
088<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>
089<tr><td><em>Assignment:</em></td><td>left-hand side is a scalar:</td><td><em>x = f(<b>V</b>)</em></td></tr>
090<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>
091</table>
092</center>
093
094In their general form given above, there is little to distinguish
095between <em>assignment</em> and <em>algebraic</em> rules.  They are treated as
096separate cases for the following reasons:
097
098<ul>
099<li> <em>Assignment</em> rules can simply be evaluated to calculate
100intermediate values for use in numerical methods.  They are statements
101of equality that hold at all times.  (For assignments that are only
102performed once, see {@link InitialAssignment}.)<p>
103
104<li> SBML needs to place restrictions on assignment rules, for example
105the restriction that assignment rules cannot contain algebraic loops.<p>
106
107<li> Some simulators do not contain numerical solvers capable of solving
108unconstrained algebraic equations, and providing more direct forms such
109as assignment rules may enable those simulators to process models they
110could not process if the same assignments were put in the form of
111general algebraic equations;<p>
112
113<li> Those simulators that <em>can</em> solve these algebraic equations make a
114distinction between the different categories listed above; and<p>
115
116<li> Some specialized numerical analyses of models may only be applicable
117to models that do not contain <em>algebraic</em> rules.
118</ul>
119
120The approach taken to covering these cases in SBML is to define an
121abstract {@link Rule} structure containing a subelement, 'math', to hold the
122right-hand side expression, then to derive subtypes of {@link Rule} that add
123attributes to distinguish the cases of algebraic, assignment and rate
124rules.  The 'math' subelement must contain a MathML expression defining the
125mathematical formula of the rule.  This MathML formula must return a
126numerical value.  The formula can be an arbitrary expression referencing
127the variables and other entities in an SBML model.
128
129Each of the three subclasses of {@link Rule} (AssignmentRule, {@link AlgebraicRule},
130{@link RateRule}) inherit the the 'math' subelement and other fields from {@link SBase}.
131The {@link AssignmentRule} and {@link RateRule} classes add an additional attribute,
132'variable'.  See the definitions of {@link AssignmentRule}, {@link AlgebraicRule} and
133{@link RateRule} for details about the structure and interpretation of each one.
134
135 * <p>
136 * <h2>Additional restrictions on SBML rules</h2>
137 * <p>
138 * An important design goal of SBML rule semantics is to ensure that a
139model's simulation and analysis results will not be dependent on when or
140how often rules are evaluated.  To achieve this, SBML needs to place two
141restrictions on rule use.  The first concerns algebraic loops in the system
142of assignments in a model, and the second concerns overdetermined systems.
143
144<h3><a class='anchor' id='no-algebraic-loops'>A model must not contain
145algebraic loops</a></h3>
146
147The combined set of {@link InitialAssignment}, {@link AssignmentRule} and {@link KineticLaw}
148objects in a model constitute a set of assignment statements that should be
149considered as a whole.  (A {@link KineticLaw} object is counted as an assignment
150because it assigns a value to the symbol contained in the 'id' attribute of
151the {@link Reaction} object in which it is defined.)  This combined set of
152assignment statements must not contain algebraic loops&mdash;dependency
153chains between these statements must terminate.  To put this more formally,
154consider a directed graph in which nodes are assignment statements and
155directed arcs exist for each occurrence of an SBML species, compartment or
156parameter symbol in an assignment statement's 'math' subelement.  Let the
157directed arcs point from the statement assigning the symbol to the
158statements that contain the symbol in their 'math' subelement expressions.
159This graph must be acyclic.
160
161SBML does not specify when or how often rules should be evaluated.
162Eliminating algebraic loops ensures that assignment statements can be
163evaluated any number of times without the result of those evaluations
164changing.  As an example, consider the set of equations <em>x = x + 1</em>,
165<em>y = z + 200</em> and <em>z = y + 100</em>.  If this set of equations
166were interpreted as a set of assignment statements, it would be invalid
167because the rule for <em>x</em> refers to <em>x</em> (exhibiting one type
168of loop), and the rule for <em>y</em> refers to <em>z</em> while the rule
169for <em>z</em> refers back to <em>y</em> (exhibiting another type of loop).
170Conversely, the following set of equations would constitute a valid set of
171assignment statements: <em>x = 10</em>, <em>y = z + 200</em>, and <em>z = x
172+ 100</em>.
173
174<h3><a class='anchor' id='no-overdetermined'>A model must not be
175overdetermined</a></h3>
176
177An SBML model must not be overdetermined; that is, a model must not
178define more equations than there are unknowns in a model.  An SBML model
179that does not contain {@link AlgebraicRule} structures cannot be overdetermined.
180
181LibSBML implements the static analysis procedure described in
182Appendix&nbsp;B of the SBML Level&nbsp;3 Version&nbsp;1 Core
183specification for assessing whether a model is overdetermined.
184
185(In summary, assessing whether a given continuous, deterministic,
186mathematical model is overdetermined does not require dynamic analysis; it
187can be done by analyzing the system of equations created from the model.
188One approach is to construct a bipartite graph in which one set of vertices
189represents the variables and the other the set of vertices represents the
190equations.  Place edges between vertices such that variables in the system
191are linked to the equations that determine them.  For algebraic equations,
192there will be edges between the equation and each variable occurring in the
193equation.  For ordinary differential equations (such as those defined by
194rate rules or implied by the reaction rate definitions), there will be a
195single edge between the equation and the variable determined by that
196differential equation.  A mathematical model is overdetermined if the
197maximal matchings of the bipartite graph contain disconnected vertexes
198representing equations.  If one maximal matching has this property, then
199all the maximal matchings will have this property; i.e., it is only
200necessary to find one maximal matching.)
201
202 * <p>
203 * <h2>Rule types for SBML Level 1</h2>
204 * <p>
205 * SBML Level 1 uses a different scheme than SBML Level 2 and Level 3 for
206 * distinguishing rules; specifically, it uses an attribute whose value is
207 * drawn from an enumeration of 3 values.  LibSBML supports this using methods
208 * that work with the enumeration values  listed below.
209 * <p>
210 * <ul>
211 * <li> {@link  libsbmlConstants#RULE_TYPE_RATE RULE_TYPE_RATE}: Indicates
212 * the rule is a 'rate' rule.
213 * <li> {@link  libsbmlConstants#RULE_TYPE_SCALAR RULE_TYPE_SCALAR}:
214 * Indicates the rule is a 'scalar' rule.
215 * <li> {@link  libsbmlConstants#RULE_TYPE_INVALID RULE_TYPE_INVALID}:
216 * Indicates the rule type is unknown or not yet set.
217 * </ul>
218 * <p>
219 * <!-- leave this next break as-is to work around some doxygen bug -->
220 */
221
222public class RateRule extends Rule {
223   private long swigCPtr;
224
225   protected RateRule(long cPtr, boolean cMemoryOwn)
226   {
227     super(libsbmlJNI.RateRule_SWIGUpcast(cPtr), cMemoryOwn);
228     swigCPtr = cPtr;
229   }
230
231   protected static long getCPtr(RateRule obj)
232   {
233     return (obj == null) ? 0 : obj.swigCPtr;
234   }
235
236   protected static long getCPtrAndDisown (RateRule obj)
237   {
238     long ptr = 0;
239
240     if (obj != null)
241     {
242       ptr             = obj.swigCPtr;
243       obj.swigCMemOwn = false;
244     }
245
246     return ptr;
247   }
248
249  protected void finalize() {
250    delete();
251  }
252
253  public synchronized void delete() {
254    if (swigCPtr != 0) {
255      if (swigCMemOwn) {
256        swigCMemOwn = false;
257        libsbmlJNI.delete_RateRule(swigCPtr);
258      }
259      swigCPtr = 0;
260    }
261    super.delete();
262  }
263
264  
265/**
266   * Creates a new {@link RateRule} using the given SBML <code>level</code> and <code>version</code>
267   * values.
268   * <p>
269   * @param level a long integer, the SBML Level to assign to this {@link RateRule}
270   * <p>
271   * @param version a long integer, the SBML Version to assign to this
272   * {@link RateRule}
273   * <p>
274   * @throws SBMLConstructorException 
275   * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind
276   * of SBML object, are either invalid or mismatched with respect to the
277   * parent {@link SBMLDocument} object.
278   * <p>
279   * @note Upon the addition of a {@link RateRule} object to an {@link SBMLDocument}
280   * (e.g., using&nbsp; {@link Model#addRule(Rule r)}, the SBML Level, SBML Version
281   * and XML namespace of the document <em>override</em> the values used
282   * when creating the {@link RateRule} object via this constructor.  This is
283   * necessary to ensure that an SBML document is a consistent structure.
284   * Nevertheless, the ability to supply the values at the time of creation
285   * of a {@link RateRule} is an important aid to producing valid SBML.  Knowledge
286   * of the intented SBML Level and Version determine whether it is valid
287   * to assign a particular value to an attribute, or whether it is valid
288   * to add an object to an existing {@link SBMLDocument}.
289  */ public
290 RateRule(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
291    this(libsbmlJNI.new_RateRule__SWIG_0(level, version), true);
292  }
293
294  
295/**
296   * Creates a new {@link RateRule} using the given {@link SBMLNamespaces} object
297   * <code>sbmlns</code>.
298   * <p>
299   * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces
300   * information.  It is used to communicate the SBML Level, Version, and
301   * (in Level&nbsp;3) packages used in addition to SBML Level&nbsp;3 Core.
302   * A common approach to using this class constructor is to create an
303   * {@link SBMLNamespaces} object somewhere in a program, once, then pass it to
304   * object constructors such as this one when needed.
305   * <p>
306   * @param sbmlns an {@link SBMLNamespaces} object.
307   * <p>
308   * @throws SBMLConstructorException 
309   * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind
310   * of SBML object, are either invalid or mismatched with respect to the
311   * parent {@link SBMLDocument} object.
312   * <p>
313   * @note Upon the addition of a {@link RateRule} object to an {@link SBMLDocument} (e.g.,
314   * using {@link Model#addRule(Rule r)}, the SBML XML namespace of the document
315   * <em>overrides</em> the value used when creating the {@link RateRule} object via
316   * this constructor.  This is necessary to ensure that an SBML document
317   * is a consistent structure.  Nevertheless, the ability to supply the
318   * values at the time of creation of a {@link RateRule} is an important aid to
319   * producing valid SBML.  Knowledge of the intented SBML Level and
320   * Version determine whether it is valid to assign a particular value to
321   * an attribute, or whether it is valid to add an object to an existing
322   * {@link SBMLDocument}.
323   */ public
324 RateRule(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
325    this(libsbmlJNI.new_RateRule__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
326  }
327
328  
329/**
330   * Creates and returns a deep copy of this {@link Rule}.
331   * <p>
332   * @return a (deep) copy of this {@link Rule}.
333   */ public
334 RateRule cloneObject() {
335    long cPtr = libsbmlJNI.RateRule_cloneObject(swigCPtr, this);
336    return (cPtr == 0) ? null : new RateRule(cPtr, true);
337  }
338
339  
340/**
341   * Predicate returning <code>true</code> if
342   * all the required attributes for this {@link RateRule} object
343   * have been set.
344   * <p>
345   * @note In SBML Levels&nbsp;2&ndash;3, the only required attribute for a
346   * {@link RateRule} object is 'variable'.  For Level&nbsp;1, where the equivalent
347   * attribute is known by different names ('compartment', 'species', or
348   * 'name', depending on the type of object), there is an additional
349   * required attribute called 'formula'.
350   * <p>
351   * @return <code>true</code> if the required attributes have been set, <code>false</code>
352   * otherwise.
353   */ public
354 boolean hasRequiredAttributes() {
355    return libsbmlJNI.RateRule_hasRequiredAttributes(swigCPtr, this);
356  }
357
358  
359/**
360   * Renames all the SIdRef attributes on this element, including any found in MathML
361   */ public
362 void renameSIdRefs(String oldid, String newid) {
363    libsbmlJNI.RateRule_renameSIdRefs(swigCPtr, this, oldid, newid);
364  }
365
366}