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 *  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 * In SBML Level&nbsp;2 and Level&nbsp;3 Version&nbsp;1, the 'math'
054 * subelement of the {@link AlgebraicRule} is required.  In SBML Level&nbsp;3
055 * Version&nbsp;2, this rule is relaxed, and the subelement is
056 * optional.  If an {@link AlgebraicRule} with no 'math' child is present
057 * in the model, no additional mathematical constraints on the model are
058 * added by the rule.  This may represent a situation where the model itself
059 * is unfinished, or the missing information may be provided by an
060 * SBML Level&nbsp;3 package.
061 <p>
062 * Finally, any symbol that appears as the target of a rateOf csymbol 
063 * ({@link libsbmlConstants#AST_FUNCTION_RATE_OF AST_FUNCTION_RATE_OF}, introduced in 
064 * SBML Level&nbsp;3 Version&nbsp;2) may 
065 * not be determined by an {@link AlgebraicRule}. This is because the rateOf 
066 * csymbol is defined as applying only to symbols whose rates of change 
067 * are easily determinable.
068 <p>
069 * Users should note that these rules about what symbols may not be 
070 * determined by an {@link AlgebraicRule} may be used to discover what symbol 
071 * is being determined by an {@link AlgebraicRule}. If three symbols appear in 
072 * the math element of an {@link AlgebraicRule}, the first of which is flagged 
073 * constant=<code>true</code>, and the second of which appears as the target of a
074 * rateOf csymbol, one may conclude that the {@link AlgebraicRule} must be used 
075 * to determine the value of the third symbol. This is, in fact, a 
076 * principle use (outside of validation) of the constant attribute: its 
077 * use in allowing software to properly identify the dependent variable 
078 * in an {@link AlgebraicRule}.
079 <p>
080 * <p>
081 * <h2>General summary of SBML rules</h2>
082 <p>
083 * In SBML Level&nbsp;3 as well as Level&nbsp;2, rules are separated into three
084 * subclasses for the benefit of model analysis software.  The three
085 * subclasses are based on the following three different possible functional
086 * forms (where <em>x</em> is a variable, <em>f</em> is some arbitrary
087 * function returning a numerical result, <b><em>V</em></b> is a vector of
088 * variables that does not include <em>x</em>, and <b><em>W</em></b> is a
089 * vector of variables that may include <em>x</em>):
090 <p>
091 * <table border='0' cellpadding='0' class='centered' style='font-size: small'>
092 * <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>
093 * <tr><td><em>Assignment:</em></td><td>left-hand side is a scalar:</td><td><em>x = f(<b>V</b>)</em></td></tr>
094 * <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>
095 * </table>
096 <p>
097 * In their general form given above, there is little to distinguish
098 * between <em>assignment</em> and <em>algebraic</em> rules.  They are treated as
099 * separate cases for the following reasons:
100 <p>
101 * <ul>
102 * <li> <em>Assignment</em> rules can simply be evaluated to calculate
103 * intermediate values for use in numerical methods.  They are statements
104 * of equality that hold at all times.  (For assignments that are only
105 * performed once, see {@link InitialAssignment}.)
106<p>
107 * <li> SBML needs to place restrictions on assignment rules, for example
108 * the restriction that assignment rules cannot contain algebraic loops.
109 <p>
110 * <li> Some simulators do not contain numerical solvers capable of solving
111 * unconstrained algebraic equations, and providing more direct forms such
112 * as assignment rules may enable those simulators to process models they
113 * could not process if the same assignments were put in the form of
114 * general algebraic equations;
115 <p>
116 * <li> Those simulators that <em>can</em> solve these algebraic equations make a
117 * distinction between the different categories listed above; and
118 <p>
119 * <li> Some specialized numerical analyses of models may only be applicable
120 * to models that do not contain <em>algebraic</em> rules.
121 *
122 * </ul> <p>
123 * The approach taken to covering these cases in SBML is to define an
124 * abstract {@link Rule} structure containing a subelement, 'math', to hold the
125 * right-hand side expression, then to derive subtypes of {@link Rule} that add
126 * attributes to distinguish the cases of algebraic, assignment and rate
127 * rules.  The 'math' subelement must contain a MathML expression defining the
128 * mathematical formula of the rule.  This MathML formula must return a
129 * numerical value.  The formula can be an arbitrary expression referencing
130 * the variables and other entities in an SBML model.
131 <p>
132 * Each of the three subclasses of {@link Rule} (AssignmentRule, {@link AlgebraicRule},
133 * {@link RateRule}) inherit the the 'math' subelement and other fields from {@link SBase}.
134 * The {@link AssignmentRule} and {@link RateRule} classes add an additional attribute,
135 * 'variable'.  See the definitions of {@link AssignmentRule}, {@link AlgebraicRule} and
136 * {@link RateRule} for details about the structure and interpretation of each one.
137 <p>
138 * <h2>Additional restrictions on SBML rules</h2>
139 <p>
140 * An important design goal of SBML rule semantics is to ensure that a
141 * model's simulation and analysis results will not be dependent on when or
142 * how often rules are evaluated.  To achieve this, SBML needs to place two
143 * restrictions on rule use.  The first concerns algebraic loops in the system
144 * of assignments in a model, and the second concerns overdetermined systems.
145 <p>
146 * <h3>A model must not contain algebraic loops</h3>
147 <p>
148 * The combined set of {@link InitialAssignment}, {@link AssignmentRule} and {@link KineticLaw}
149 * objects in a model constitute a set of assignment statements that should be
150 * considered as a whole.  (A {@link KineticLaw} object is counted as an assignment
151 * because it assigns a value to the symbol contained in the 'id' attribute of
152 * the {@link Reaction} object in which it is defined.)  This combined set of
153 * assignment statements must not contain algebraic loops&mdash;dependency
154 * chains between these statements must terminate.  To put this more formally,
155 * consider a directed graph in which nodes are assignment statements and
156 * directed arcs exist for each occurrence of an SBML species, compartment or
157 * parameter symbol in an assignment statement's 'math' subelement.  Let the
158 * directed arcs point from the statement assigning the symbol to the
159 * statements that contain the symbol in their 'math' subelement expressions.
160 * This graph must be acyclic.
161 <p>
162 * Similarly, the combined set of {@link RateRule} and {@link Reaction} objects constitute 
163 * a set of definitions for the rates of change of various model entities 
164 * (namely, the objects identified by the values of the 'variable' attributes 
165 * of the {@link RateRule} objects, and the 'species' attributes of the {@link SpeciesReference} 
166 * objects in each {@link Reaction}).  In SBML Level&nbsp;3 Version&nbsp;2, these rates 
167 * of change may be referenced directly 
168 * using the <em>rateOf</em> csymbol, but may not thereby contain algebraic 
169 * loops&mdash;dependency chains between these statements must terminate.  More 
170 * formally, consider a directed graph in which the nodes are the definitions 
171 * of different variables' rates of change, and directed arcs exist for each 
172 * occurrence of a variable referenced by a <em>rateOf</em> csymbol from any 
173 * {@link RateRule} or {@link KineticLaw} object in the model.  Let the directed arcs point 
174 * from the variable referenced by the <em>rateOf</em> csymbol (call it 
175 * <em>x</em>) to the variable(s) determined by the 'math' expression in which
176 * <em>x</em> appears.  This graph must be acyclic.
177 <p>
178 * SBML does not specify when or how often rules should be evaluated.
179 * Eliminating algebraic loops ensures that assignment statements can be
180 * evaluated any number of times without the result of those evaluations
181 * changing.  As an example, consider the set of equations <em>x = x + 1</em>,
182 * <em>y = z + 200</em> and <em>z = y + 100</em>.  If this set of equations
183 * were interpreted as a set of assignment statements, it would be invalid
184 * because the rule for <em>x</em> refers to <em>x</em> (exhibiting one type
185 * of loop), and the rule for <em>y</em> refers to <em>z</em> while the rule
186 * for <em>z</em> refers back to <em>y</em> (exhibiting another type of loop).
187 * Conversely, the following set of equations would constitute a valid set of
188 * assignment statements: <em>x = 10</em>, <em>y = z + 200</em>, and <em>z = x
189 * + 100</em>.
190 <p>
191 * <h3>A model must not be overdetermined</h3>
192 <p>
193 * An SBML model must not be overdetermined; that is, a model must not
194 * define more equations than there are unknowns in a model.  A valid SBML model
195 * that does not contain {@link AlgebraicRule} structures cannot be overdetermined.
196 <p>
197 * LibSBML implements the static analysis procedure described in
198 * Appendix&nbsp;B of the SBML Level&nbsp;3
199 * specification for assessing whether a model is overdetermined.
200 <p>
201 * (In summary, assessing whether a given continuous, deterministic,
202 * mathematical model is overdetermined does not require dynamic analysis; it
203 * can be done by analyzing the system of equations created from the model.
204 * One approach is to construct a bipartite graph in which one set of vertices
205 * represents the variables and the other the set of vertices represents the
206 * equations.  Place edges between vertices such that variables in the system
207 * are linked to the equations that determine them.  For algebraic equations,
208 * there will be edges between the equation and each variable occurring in the
209 * equation.  For ordinary differential equations (such as those defined by
210 * rate rules or implied by the reaction rate definitions), there will be a
211 * single edge between the equation and the variable determined by that
212 * differential equation.  A mathematical model is overdetermined if the
213 * maximal matchings of the bipartite graph contain disconnected vertexes
214 * representing equations.  If one maximal matching has this property, then
215 * all the maximal matchings will have this property; i.e., it is only
216 * necessary to find one maximal matching.)
217 <p>
218 * <h2>Rule types for SBML Level 1</h2>
219 <p>
220 * SBML Level 1 uses a different scheme than SBML Level 2 and Level 3 for
221 * distinguishing rules; specifically, it uses an attribute whose value is
222 * drawn from an enumeration of 3 values.  LibSBML supports this using methods
223 * that work with the enumeration values  listed below.
224 <p>
225 * <ul>
226 * <li> {@link libsbmlConstants#RULE_TYPE_RATE RULE_TYPE_RATE}: Indicates
227 * the rule is a 'rate' rule.
228 * <li> {@link libsbmlConstants#RULE_TYPE_SCALAR RULE_TYPE_SCALAR}:
229 * Indicates the rule is a 'scalar' rule.
230 * <li> {@link libsbmlConstants#RULE_TYPE_INVALID RULE_TYPE_INVALID}:
231 * Indicates the rule type is unknown or not yet set.
232 *
233 * </ul>
234 */
235
236public class AlgebraicRule extends Rule {
237   private long swigCPtr;
238
239   protected AlgebraicRule(long cPtr, boolean cMemoryOwn)
240   {
241     super(libsbmlJNI.AlgebraicRule_SWIGUpcast(cPtr), cMemoryOwn);
242     swigCPtr = cPtr;
243   }
244
245   protected static long getCPtr(AlgebraicRule obj)
246   {
247     return (obj == null) ? 0 : obj.swigCPtr;
248   }
249
250   protected static long getCPtrAndDisown (AlgebraicRule obj)
251   {
252     long ptr = 0;
253
254     if (obj != null)
255     {
256       ptr             = obj.swigCPtr;
257       obj.swigCMemOwn = false;
258     }
259
260     return ptr;
261   }
262
263  protected void finalize() {
264    delete();
265  }
266
267  public synchronized void delete() {
268    if (swigCPtr != 0) {
269      if (swigCMemOwn) {
270        swigCMemOwn = false;
271        libsbmlJNI.delete_AlgebraicRule(swigCPtr);
272      }
273      swigCPtr = 0;
274    }
275    super.delete();
276  }
277
278  
279/**
280   * Creates a new {@link AlgebraicRule} object using the given SBML <code>level</code> and 
281   * <code>version</code> values.
282   <p>
283   * @param level the SBML Level to assign to this {@link AlgebraicRule} object.
284   <p>
285   * @param version the SBML Version to assign to this {@link AlgebraicRule} object.
286   <p>
287   * <p>
288 * @throws SBMLConstructorException
289 * Thrown if the given <code>level</code> and <code>version</code> combination are invalid
290 * or if this object is incompatible with the given level and version.
291   <p>
292   * <p>
293 * @note Attempting to add an object to an {@link SBMLDocument} having a different
294 * combination of SBML Level, Version and XML namespaces than the object
295 * itself will result in an error at the time a caller attempts to make the
296 * addition.  A parent object must have compatible Level, Version and XML
297 * namespaces.  (Strictly speaking, a parent may also have more XML
298 * namespaces than a child, but the reverse is not permitted.)  The
299 * restriction is necessary to ensure that an SBML model has a consistent
300 * overall structure.  This requires callers to manage their objects
301 * carefully, but the benefit is increased flexibility in how models can be
302 * created by permitting callers to create objects bottom-up if desired.  In
303 * situations where objects are not yet attached to parents (e.g.,
304 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
305 * libSBML determine such things as whether it is valid to assign a
306 * particular value to an attribute.
307   */ public
308 AlgebraicRule(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
309    this(libsbmlJNI.new_AlgebraicRule__SWIG_0(level, version), true);
310  }
311
312  
313/**
314   * Creates a new {@link AlgebraicRule} object using the given {@link SBMLNamespaces} object
315   * <code>sbmlns</code>.
316   <p>
317   * <p>
318 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces
319 * information.  It is used to communicate the SBML Level, Version, and (in
320 * Level&nbsp;3) packages used in addition to SBML Level&nbsp;3 Core.  A
321 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an
322 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object
323 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments. 
324   <p>
325   * @param sbmlns an {@link SBMLNamespaces} object.
326   <p>
327   * <p>
328 * @throws SBMLConstructorException
329 * Thrown if the given <code>sbmlns</code> is inconsistent or incompatible
330 * with this object.
331   <p>
332   * <p>
333 * @note Attempting to add an object to an {@link SBMLDocument} having a different
334 * combination of SBML Level, Version and XML namespaces than the object
335 * itself will result in an error at the time a caller attempts to make the
336 * addition.  A parent object must have compatible Level, Version and XML
337 * namespaces.  (Strictly speaking, a parent may also have more XML
338 * namespaces than a child, but the reverse is not permitted.)  The
339 * restriction is necessary to ensure that an SBML model has a consistent
340 * overall structure.  This requires callers to manage their objects
341 * carefully, but the benefit is increased flexibility in how models can be
342 * created by permitting callers to create objects bottom-up if desired.  In
343 * situations where objects are not yet attached to parents (e.g.,
344 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help
345 * libSBML determine such things as whether it is valid to assign a
346 * particular value to an attribute.
347   */ public
348 AlgebraicRule(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
349    this(libsbmlJNI.new_AlgebraicRule__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
350  }
351
352  
353/**
354   * Creates and returns a deep copy of this {@link AlgebraicRule} object.
355   <p>
356   * @return the (deep) copy of this {@link Rule} object.
357   */ public
358 AlgebraicRule cloneObject() {
359    long cPtr = libsbmlJNI.AlgebraicRule_cloneObject(swigCPtr, this);
360    return (cPtr == 0) ? null : new AlgebraicRule(cPtr, true);
361  }
362
363  
364/**
365   * Predicate returning <code>true</code> if all the required attributes for this
366   * {@link AlgebraicRule} object have been set.
367   <p>
368   * In SBML Levels&nbsp;2&ndash;3, there is no required attribute
369   * for an {@link AlgebraicRule} object.  For Level&nbsp;1, the only required
370   * attribute is 'formula'.
371   <p>
372   * @return <code>true</code> if the required attributes have been set, <code>false</code>
373   * otherwise.
374   */ public
375 boolean hasRequiredAttributes() {
376    return libsbmlJNI.AlgebraicRule_hasRequiredAttributes(swigCPtr, this);
377  }
378
379}