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