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