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