001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 3.0.8 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>algebraic rule</em> representing <em>0 = f(<b>W</b>)</em>. 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 * <p> 245 * @throws SBMLConstructorException 246 * Thrown if the given <code>level</code> and <code>version</code> combination are invalid 247 * or if this object is incompatible with the given level and version. 248 <p> 249 * <p> 250 * @note Attempting to add an object to an {@link SBMLDocument} having a different 251 * combination of SBML Level, Version and XML namespaces than the object 252 * itself will result in an error at the time a caller attempts to make the 253 * addition. A parent object must have compatible Level, Version and XML 254 * namespaces. (Strictly speaking, a parent may also have more XML 255 * namespaces than a child, but the reverse is not permitted.) The 256 * restriction is necessary to ensure that an SBML model has a consistent 257 * overall structure. This requires callers to manage their objects 258 * carefully, but the benefit is increased flexibility in how models can be 259 * created by permitting callers to create objects bottom-up if desired. In 260 * situations where objects are not yet attached to parents (e.g., 261 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 262 * libSBML determine such things as whether it is valid to assign a 263 * particular value to an attribute. 264 */ public 265 AlgebraicRule(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 266 this(libsbmlJNI.new_AlgebraicRule__SWIG_0(level, version), true); 267 } 268 269 270/** 271 * Creates a new {@link AlgebraicRule} object using the given {@link SBMLNamespaces} object 272 * <code>sbmlns</code>. 273 <p> 274 * <p> 275 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces 276 * information. It is used to communicate the SBML Level, Version, and (in 277 * Level 3) packages used in addition to SBML Level 3 Core. A 278 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an 279 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object 280 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments. 281 <p> 282 * @param sbmlns an {@link SBMLNamespaces} object. 283 <p> 284 * <p> 285 * @throws SBMLConstructorException 286 * Thrown if the given <code>sbmlns</code> is inconsistent or incompatible 287 * with this object. 288 <p> 289 * <p> 290 * @note Attempting to add an object to an {@link SBMLDocument} having a different 291 * combination of SBML Level, Version and XML namespaces than the object 292 * itself will result in an error at the time a caller attempts to make the 293 * addition. A parent object must have compatible Level, Version and XML 294 * namespaces. (Strictly speaking, a parent may also have more XML 295 * namespaces than a child, but the reverse is not permitted.) The 296 * restriction is necessary to ensure that an SBML model has a consistent 297 * overall structure. This requires callers to manage their objects 298 * carefully, but the benefit is increased flexibility in how models can be 299 * created by permitting callers to create objects bottom-up if desired. In 300 * situations where objects are not yet attached to parents (e.g., 301 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 302 * libSBML determine such things as whether it is valid to assign a 303 * particular value to an attribute. 304 */ public 305 AlgebraicRule(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException { 306 this(libsbmlJNI.new_AlgebraicRule__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true); 307 } 308 309 310/** 311 * Creates and returns a deep copy of this {@link AlgebraicRule} object. 312 <p> 313 * @return the (deep) copy of this {@link Rule} object. 314 */ public 315 AlgebraicRule cloneObject() { 316 long cPtr = libsbmlJNI.AlgebraicRule_cloneObject(swigCPtr, this); 317 return (cPtr == 0) ? null : new AlgebraicRule(cPtr, true); 318 } 319 320 321/** 322 * Predicate returning <code>true</code> if all the required attributes for this 323 * {@link AlgebraicRule} object have been set. 324 <p> 325 * In SBML Levels 2–3, there is no required attribute 326 * for an {@link AlgebraicRule} object. For Level 1, the only required 327 * attribute is 'formula'. 328 <p> 329 * @return <code>true</code> if the required attributes have been set, <code>false</code> 330 * otherwise. 331 */ public 332 boolean hasRequiredAttributes() { 333 return libsbmlJNI.AlgebraicRule_hasRequiredAttributes(swigCPtr, this); 334 } 335 336}