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