/* ----------------------------------------------------------------------------
 * This file was automatically generated by SWIG (http://www.swig.org).
 * Version 2.0.0
 *
 * Do not make changes to this file unless you know what you are doing--modify
 * the SWIG interface file instead.
 * ----------------------------------------------------------------------------- */

package org.sbml.libsbml;

/** 
 * LibSBML implementation of SBML's AlgebraicRule construct.
 * <p>
 * The rule type {@link AlgebraicRule} is derived from the parent class {@link Rule}.  It
 * is used to express equations that are neither assignments of model
 * variables nor rates of change.  {@link AlgebraicRule} does not add any
 * attributes to the basic {@link Rule}; its role is simply to distinguish this
 * case from the other cases.
 * <p>
 * In the context of a simulation, algebraic rules are in effect at all
 * times, <em>t</em> &#8805; <em>0</em>.  For purposes of evaluating
 * expressions that involve the delay 'csymbol' (see the SBML
 * specification), algebraic rules are considered to apply also at
 * <em>t</em> &#8804; <em>0</em>.  Please consult the relevant SBML
 * specification for additional information about the semantics of
 * assignments, rules, and entity values for simulation time <em>t</em>
 * &#8804; <em>0</em>.
 * <p>
 * An SBML model must not be overdetermined.  The ability to define
 * arbitrary algebraic expressions in an SBML model introduces the
 * possibility that a model is mathematically overdetermined by the overall
 * system of equations constructed from its rules, reactions and events.
 * Therefore, if an algebraic rule is introduced in a model, for at least
 * one of the entities referenced in the rule's 'math' element the value of
 * that entity must not be completely determined by other constructs in the
 * model.  This means that at least this entity must not have the attribute
 * 'constant'=<code>true</code> and there must also not be a rate rule or assignment
 * rule for it.  Furthermore, if the entity is a {@link Species} object, its value
 * must not be determined by reactions, which means that it must either
 * have the attribute 'boundaryCondition'=<code>true</code> or else not be involved
 * in any reaction at all.  These restrictions are explained in more detail
 * in the SBML specification documents.
 * <p>
 * In SBML Levels 2 and&nbsp;3, {@link Reaction} object identifiers can be
 * referenced in the 'math' expression of an algebraic rule, but reaction
 * rates can never be <em>determined</em> by algebraic rules.  This is true
 * even when a reaction does not contain a {@link KineticLaw} element.  (In such
 * cases of missing {@link KineticLaw} elements, the model is valid but incomplete;
 * the rates of reactions lacking kinetic laws are simply undefined, and
 * not determined by the algebraic rule.)
 * <p>
 * <p>
 * <h2>General summary of SBML rules</h2>
 * <p>
 * In SBML Level&nbsp;3 as well as Level&nbsp;2, rules are separated into
 * three subclasses for the benefit of model analysis software.  The three
 * subclasses are based on the following three different possible
 * functional forms (where <em>x</em> is a variable, <em>f</em> is some
 * arbitrary function returning a numerical result, <b><em>V</em></b> is a
 * vector of variables that does not include <em>x</em>, and
 * <b><em>W</em></b> is a vector of variables that may include <em>x</em>):
 * <p>
 * <center>
 * <table border='0' cellpadding='0' style='font-size: small'>
 * <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>
 * <tr><td><em>Assignment:</em></td><td>left-hand side is a scalar:</td><td><em>x = f(<b>V</b>)</em></td></tr>
 * <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>
 * </table>
 * </center>
 * <p>
 * In their general form given above, there is little to distinguish
 * between <em>assignment</em> and <em>algebraic</em> rules.  They are treated as
 * separate cases for the following reasons:
 * <p>
 * <ul>
 * <li> <em>Assignment</em> rules can simply be evaluated to calculate
 * intermediate values for use in numerical methods.  They are statements
 * of equality that hold at all times.  (For assignments that are only
 * performed once, see {@link InitialAssignment}.)<p>
 * <p>
 * <li> SBML needs to place restrictions on assignment rules, for example
 * the restriction that assignment rules cannot contain algebraic loops.<p>
 * <p>
 * <li> Some simulators do not contain numerical solvers capable of solving
 * unconstrained algebraic equations, and providing more direct forms such
 * as assignment rules may enable those simulators to process models they
 * could not process if the same assignments were put in the form of
 * general algebraic equations;<p>
 * <p>
 * <li> Those simulators that <em>can</em> solve these algebraic equations make a
 * distinction between the different categories listed above; and<p>
 * <p>
 * <li> Some specialized numerical analyses of models may only be applicable
 * to models that do not contain <em>algebraic</em> rules.
 * </ul>
 * <p>
 * The approach taken to covering these cases in SBML is to define an
 * abstract {@link Rule} structure containing a subelement, 'math', to hold the
 * right-hand side expression, then to derive subtypes of {@link Rule} that add
 * attributes to distinguish the cases of algebraic, assignment and rate
 * rules.  The 'math' subelement must contain a MathML expression defining the
 * mathematical formula of the rule.  This MathML formula must return a
 * numerical value.  The formula can be an arbitrary expression referencing
 * the variables and other entities in an SBML model.
 * <p>
 * Each of the three subclasses of {@link Rule} (AssignmentRule, {@link AlgebraicRule},
 * {@link RateRule}) inherit the the 'math' subelement and other fields from {@link SBase}.
 * The {@link AssignmentRule} and {@link RateRule} classes add an additional attribute,
 * 'variable'.  See the definitions of {@link AssignmentRule}, {@link AlgebraicRule} and
 * {@link RateRule} for details about the structure and interpretation of each one.
 * <p>
 * <h2>Additional restrictions on SBML rules</h2>
 * <p>
 * An important design goal of SBML rule semantics is to ensure that a
 * model's simulation and analysis results will not be dependent on when or
 * how often rules are evaluated.  To achieve this, SBML needs to place two
 * restrictions on rule use.  The first concerns algebraic loops in the system
 * of assignments in a model, and the second concerns overdetermined systems.
 * <p>
 * <h3>A model must not contain algebraic loops</h3>
 * <p>
 * The combined set of {@link InitialAssignment}, {@link AssignmentRule} and {@link KineticLaw}
 * objects in a model constitute a set of assignment statements that should be
 * considered as a whole.  (A {@link KineticLaw} object is counted as an assignment
 * because it assigns a value to the symbol contained in the 'id' attribute of
 * the {@link Reaction} object in which it is defined.)  This combined set of
 * assignment statements must not contain algebraic loops&mdash;dependency
 * chains between these statements must terminate.  To put this more formally,
 * consider a directed graph in which nodes are assignment statements and
 * directed arcs exist for each occurrence of an SBML species, compartment or
 * parameter symbol in an assignment statement's 'math' subelement.  Let the
 * directed arcs point from the statement assigning the symbol to the
 * statements that contain the symbol in their 'math' subelement expressions.
 * This graph must be acyclic.
 * <p>
 * SBML does not specify when or how often rules should be evaluated.
 * Eliminating algebraic loops ensures that assignment statements can be
 * evaluated any number of times without the result of those evaluations
 * changing.  As an example, consider the set of equations <em>x = x + 1</em>,
 * <em>y = z + 200</em> and <em>z = y + 100</em>.  If this set of equations
 * were interpreted as a set of assignment statements, it would be invalid
 * because the rule for <em>x</em> refers to <em>x</em> (exhibiting one type
 * of loop), and the rule for <em>y</em> refers to <em>z</em> while the rule
 * for <em>z</em> refers back to <em>y</em> (exhibiting another type of loop).
 * Conversely, the following set of equations would constitute a valid set of
 * assignment statements: <em>x = 10</em>, <em>y = z + 200</em>, and <em>z = x
 * + 100</em>.
 * <p>
 * <h3>A model must not be overdetermined</h3>
 * <p>
 * An SBML model must not be overdetermined; that is, a model must not
 * define more equations than there are unknowns in a model.  An SBML model
 * that does not contain {@link AlgebraicRule} structures cannot be overdetermined.
 * <p>
 * LibSBML implements the static analysis procedure described in Appendix
 * B of the SBML Level&nbsp;3 Version&nbsp;1 Core specification for assessing
 * whether a model is overdetermined.
 * <p>
 * (In summary, assessing whether a given continuous, deterministic,
 * mathematical model is overdetermined does not require dynamic analysis; it
 * can be done by analyzing the system of equations created from the model.
 * One approach is to construct a bipartite graph in which one set of vertices
 * represents the variables and the other the set of vertices represents the
 * equations.  Place edges between vertices such that variables in the system
 * are linked to the equations that determine them.  For algebraic equations,
 * there will be edges between the equation and each variable occurring in the
 * equation.  For ordinary differential equations (such as those defined by
 * rate rules or implied by the reaction rate definitions), there will be a
 * single edge between the equation and the variable determined by that
 * differential equation.  A mathematical model is overdetermined if the
 * maximal matchings of the bipartite graph contain disconnected vertexes
 * representing equations.  If one maximal matching has this property, then
 * all the maximal matchings will have this property; i.e., it is only
 * necessary to find one maximal matching.)
 * <p>
 * <p>
 * <h2>{@link Rule} types for SBML Level 1</h2>
 * <p>
 * SBML Level 1 uses a different scheme than SBML Level&nbsp;2 and
 * Level&nbsp;3 for distinguishing rules; specifically, it uses an
 * attribute whose value is drawn from an enumeration of 3 values.  LibSBML
 * supports this using methods that work with the enumeration
 * values  listed in the following table.  
 * <p>
 * <p>
 * <center>
 * <table width='90%' cellspacing='1' cellpadding='1' border='0' class='normal-font'>
 *  <tr style='background: lightgray' class='normal-font'>
 *      <td><strong>Enumerator</strong></td>
 *      <td><strong>Meaning</strong></td>
 *  </tr>
 * <tr><td><code>{@link  libsbmlConstants#RULE_TYPE_RATE RULE_TYPE_RATE}</code></td><td>Indicates the rule is a 'rate' rule.</td>
 * <tr><td><code>{@link  libsbmlConstants#RULE_TYPE_SCALAR RULE_TYPE_SCALAR}</code></td><td>Indicates the rule is a 'scalar' rule.</td>
 * <tr><td><code>{@link  libsbmlConstants#RULE_TYPE_INVALID RULE_TYPE_INVALID}</code></td><td>Indicates the rule type is unknown or not
 * yet set.</td>
 * </table>
 * </center>
 * <p>
 * <!-- leave this next break as-is to work around some doxygen bug -->
 */

public class AlgebraicRule extends Rule {
   private long swigCPtr;

   protected AlgebraicRule(long cPtr, boolean cMemoryOwn)
   {
     super(libsbmlJNI.AlgebraicRule_SWIGUpcast(cPtr), cMemoryOwn);
     swigCPtr = cPtr;
   }

   protected static long getCPtr(AlgebraicRule obj)
   {
     return (obj == null) ? 0 : obj.swigCPtr;
   }

   protected static long getCPtrAndDisown (AlgebraicRule obj)
   {
     long ptr = 0;

     if (obj != null)
     {
       ptr             = obj.swigCPtr;
       obj.swigCMemOwn = false;
     }

     return ptr;
   }

  protected void finalize() {
    delete();
  }

  public synchronized void delete() {
    if (swigCPtr != 0) {
      if (swigCMemOwn) {
        swigCMemOwn = false;
        libsbmlJNI.delete_AlgebraicRule(swigCPtr);
      }
      swigCPtr = 0;
    }
    super.delete();
  }

  
  /**
   * Creates a new {@link AlgebraicRule} using the given SBML <code>level</code> and <code>version</code>
   * values.
   * <p>
   * @param level a long integer, the SBML Level to assign to this {@link AlgebraicRule}
   * <p>
   * @param version a long integer, the SBML Version to assign to this
   * {@link AlgebraicRule}
   * <p>
   * @note Upon the addition of an {@link AlgebraicRule} object to an {@link SBMLDocument}
   * (e.g., using&nbsp; {@link Model#addRule(Rule r)}), the SBML Level, SBML Version
   * and XML namespace of the document <em>override</em> the values used
   * when creating the {@link AlgebraicRule} object via this constructor.  This is
   * necessary to ensure that an SBML document is a consistent structure.
   * Nevertheless, the ability to supply the values at the time of creation
   * of a {@link AlgebraicRule} is an important aid to producing valid SBML.
   * Knowledge of the intented SBML Level and Version determine whether it
   * is valid to assign a particular value to an attribute, or whether it
   * is valid to add an object to an existing {@link SBMLDocument}.
   */
 public AlgebraicRule(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
    this(libsbmlJNI.new_AlgebraicRule__SWIG_0(level, version), true);
  }

  
  /**
   * Creates a new {@link AlgebraicRule} using the given {@link SBMLNamespaces} object
   * <code>sbmlns</code>.
   * <p>
   * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces
   * information.  It is used to communicate the SBML Level, Version, and
   * (in Level&nbsp;3) packages used in addition to SBML Level&nbsp;3 Core.
   * A common approach to using this class constructor is to create an
   * {@link SBMLNamespaces} object somewhere in a program, once, then pass it to
   * object constructors such as this one when needed.
   * <p>
   * @param sbmlns an {@link SBMLNamespaces} object.
   * <p>
   * @note Upon the addition of a {@link AlgebraicRule} object to an {@link SBMLDocument}
   * (e.g., using&nbsp; {@link Model#addRule(Rule r)}, the SBML XML namespace of the
   * document <em>overrides</em> the value used when creating the {@link AlgebraicRule}
   * object via this constructor.  This is necessary to ensure that an SBML
   * document is a consistent structure.  Nevertheless, the ability to
   * supply the values at the time of creation of a {@link AlgebraicRule} is an
   * important aid to producing valid SBML.  Knowledge of the intented SBML
   * Level and Version determine whether it is valid to assign a particular
   * value to an attribute, or whether it is valid to add an object to an
   * existing {@link SBMLDocument}.
   */
 public AlgebraicRule(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
    this(libsbmlJNI.new_AlgebraicRule__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
  }

  
  /**
   * Creates and returns a deep copy of this {@link Rule}.
   * <p>
   * @return a (deep) copy of this {@link Rule}.
   */
 public AlgebraicRule cloneObject() {
    long cPtr = libsbmlJNI.AlgebraicRule_cloneObject(swigCPtr, this);
    return (cPtr == 0) ? null : new AlgebraicRule(cPtr, true);
  }

  
  /**
   * Predicate returning <code>true</code> if
   * all the required attributes for this {@link AlgebraicRule} object
   * have been set.
   * <p>
   * @note In SBML Levels&nbsp;2&ndash;3, there is no required attribute
   * for an {@link AlgebraicRule} object.  For Level&nbsp;1, the only required
   * attribute is 'formula'.
   * <p>
   * @return <code>true</code> if the required attributes have been set, <code>false</code>
   * otherwise.
   */
 public boolean hasRequiredAttributes() {
    return libsbmlJNI.AlgebraicRule_hasRequiredAttributes(swigCPtr, this);
  }

}
