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