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