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