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>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 * In SBML Level 2 and Level 3 Version 1, the 'math' 054 * subelement of the {@link AlgebraicRule} is required. In SBML Level 3 055 * Version 2, this rule is relaxed, and the subelement is 056 * optional. If an {@link AlgebraicRule} with no 'math' child is present 057 * in the model, no additional mathematical constraints on the model are 058 * added by the rule. This may represent a situation where the model itself 059 * is unfinished, or the missing information may be provided by an 060 * SBML Level 3 package. 061 <p> 062 * Finally, any symbol that appears as the target of a rateOf csymbol 063 * ({@link libsbmlConstants#AST_FUNCTION_RATE_OF AST_FUNCTION_RATE_OF}, introduced in 064 * SBML Level 3 Version 2) may 065 * not be determined by an {@link AlgebraicRule}. This is because the rateOf 066 * csymbol is defined as applying only to symbols whose rates of change 067 * are easily determinable. 068 <p> 069 * Users should note that these rules about what symbols may not be 070 * determined by an {@link AlgebraicRule} may be used to discover what symbol 071 * is being determined by an {@link AlgebraicRule}. If three symbols appear in 072 * the math element of an {@link AlgebraicRule}, the first of which is flagged 073 * constant=<code>true</code>, and the second of which appears as the target of a 074 * rateOf csymbol, one may conclude that the {@link AlgebraicRule} must be used 075 * to determine the value of the third symbol. This is, in fact, a 076 * principle use (outside of validation) of the constant attribute: its 077 * use in allowing software to properly identify the dependent variable 078 * in an {@link AlgebraicRule}. 079 <p> 080 * <p> 081 * <h2>General summary of SBML rules</h2> 082 <p> 083 * In SBML Level 3 as well as Level 2, rules are separated into three 084 * subclasses for the benefit of model analysis software. The three 085 * subclasses are based on the following three different possible functional 086 * forms (where <em>x</em> is a variable, <em>f</em> is some arbitrary 087 * function returning a numerical result, <b><em>V</em></b> is a vector of 088 * variables that does not include <em>x</em>, and <b><em>W</em></b> is a 089 * vector of variables that may include <em>x</em>): 090 <p> 091 * <table border='0' cellpadding='0' class='centered' style='font-size: small'> 092 * <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> 093 * <tr><td><em>Assignment:</em></td><td>left-hand side is a scalar:</td><td><em>x = f(<b>V</b>)</em></td></tr> 094 * <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> 095 * </table> 096 <p> 097 * In their general form given above, there is little to distinguish 098 * between <em>assignment</em> and <em>algebraic</em> rules. They are treated as 099 * separate cases for the following reasons: 100 <p> 101 * <ul> 102 * <li> <em>Assignment</em> rules can simply be evaluated to calculate 103 * intermediate values for use in numerical methods. They are statements 104 * of equality that hold at all times. (For assignments that are only 105 * performed once, see {@link InitialAssignment}.) 106<p> 107 * <li> SBML needs to place restrictions on assignment rules, for example 108 * the restriction that assignment rules cannot contain algebraic loops. 109 <p> 110 * <li> Some simulators do not contain numerical solvers capable of solving 111 * unconstrained algebraic equations, and providing more direct forms such 112 * as assignment rules may enable those simulators to process models they 113 * could not process if the same assignments were put in the form of 114 * general algebraic equations; 115 <p> 116 * <li> Those simulators that <em>can</em> solve these algebraic equations make a 117 * distinction between the different categories listed above; and 118 <p> 119 * <li> Some specialized numerical analyses of models may only be applicable 120 * to models that do not contain <em>algebraic</em> rules. 121 * 122 * </ul> <p> 123 * The approach taken to covering these cases in SBML is to define an 124 * abstract {@link Rule} structure containing a subelement, 'math', to hold the 125 * right-hand side expression, then to derive subtypes of {@link Rule} that add 126 * attributes to distinguish the cases of algebraic, assignment and rate 127 * rules. The 'math' subelement must contain a MathML expression defining the 128 * mathematical formula of the rule. This MathML formula must return a 129 * numerical value. The formula can be an arbitrary expression referencing 130 * the variables and other entities in an SBML model. 131 <p> 132 * Each of the three subclasses of {@link Rule} (AssignmentRule, {@link AlgebraicRule}, 133 * {@link RateRule}) inherit the the 'math' subelement and other fields from {@link SBase}. 134 * The {@link AssignmentRule} and {@link RateRule} classes add an additional attribute, 135 * 'variable'. See the definitions of {@link AssignmentRule}, {@link AlgebraicRule} and 136 * {@link RateRule} for details about the structure and interpretation of each one. 137 <p> 138 * <h2>Additional restrictions on SBML rules</h2> 139 <p> 140 * An important design goal of SBML rule semantics is to ensure that a 141 * model's simulation and analysis results will not be dependent on when or 142 * how often rules are evaluated. To achieve this, SBML needs to place two 143 * restrictions on rule use. The first concerns algebraic loops in the system 144 * of assignments in a model, and the second concerns overdetermined systems. 145 <p> 146 * <h3>A model must not contain algebraic loops</h3> 147 <p> 148 * The combined set of {@link InitialAssignment}, {@link AssignmentRule} and {@link KineticLaw} 149 * objects in a model constitute a set of assignment statements that should be 150 * considered as a whole. (A {@link KineticLaw} object is counted as an assignment 151 * because it assigns a value to the symbol contained in the 'id' attribute of 152 * the {@link Reaction} object in which it is defined.) This combined set of 153 * assignment statements must not contain algebraic loops—dependency 154 * chains between these statements must terminate. To put this more formally, 155 * consider a directed graph in which nodes are assignment statements and 156 * directed arcs exist for each occurrence of an SBML species, compartment or 157 * parameter symbol in an assignment statement's 'math' subelement. Let the 158 * directed arcs point from the statement assigning the symbol to the 159 * statements that contain the symbol in their 'math' subelement expressions. 160 * This graph must be acyclic. 161 <p> 162 * Similarly, the combined set of {@link RateRule} and {@link Reaction} objects constitute 163 * a set of definitions for the rates of change of various model entities 164 * (namely, the objects identified by the values of the 'variable' attributes 165 * of the {@link RateRule} objects, and the 'species' attributes of the {@link SpeciesReference} 166 * objects in each {@link Reaction}). In SBML Level 3 Version 2, these rates 167 * of change may be referenced directly 168 * using the <em>rateOf</em> csymbol, but may not thereby contain algebraic 169 * loops—dependency chains between these statements must terminate. More 170 * formally, consider a directed graph in which the nodes are the definitions 171 * of different variables' rates of change, and directed arcs exist for each 172 * occurrence of a variable referenced by a <em>rateOf</em> csymbol from any 173 * {@link RateRule} or {@link KineticLaw} object in the model. Let the directed arcs point 174 * from the variable referenced by the <em>rateOf</em> csymbol (call it 175 * <em>x</em>) to the variable(s) determined by the 'math' expression in which 176 * <em>x</em> appears. This graph must be acyclic. 177 <p> 178 * SBML does not specify when or how often rules should be evaluated. 179 * Eliminating algebraic loops ensures that assignment statements can be 180 * evaluated any number of times without the result of those evaluations 181 * changing. As an example, consider the set of equations <em>x = x + 1</em>, 182 * <em>y = z + 200</em> and <em>z = y + 100</em>. If this set of equations 183 * were interpreted as a set of assignment statements, it would be invalid 184 * because the rule for <em>x</em> refers to <em>x</em> (exhibiting one type 185 * of loop), and the rule for <em>y</em> refers to <em>z</em> while the rule 186 * for <em>z</em> refers back to <em>y</em> (exhibiting another type of loop). 187 * Conversely, the following set of equations would constitute a valid set of 188 * assignment statements: <em>x = 10</em>, <em>y = z + 200</em>, and <em>z = x 189 * + 100</em>. 190 <p> 191 * <h3>A model must not be overdetermined</h3> 192 <p> 193 * An SBML model must not be overdetermined; that is, a model must not 194 * define more equations than there are unknowns in a model. A valid SBML model 195 * that does not contain {@link AlgebraicRule} structures cannot be overdetermined. 196 <p> 197 * LibSBML implements the static analysis procedure described in 198 * Appendix B of the SBML Level 3 199 * specification for assessing whether a model is overdetermined. 200 <p> 201 * (In summary, assessing whether a given continuous, deterministic, 202 * mathematical model is overdetermined does not require dynamic analysis; it 203 * can be done by analyzing the system of equations created from the model. 204 * One approach is to construct a bipartite graph in which one set of vertices 205 * represents the variables and the other the set of vertices represents the 206 * equations. Place edges between vertices such that variables in the system 207 * are linked to the equations that determine them. For algebraic equations, 208 * there will be edges between the equation and each variable occurring in the 209 * equation. For ordinary differential equations (such as those defined by 210 * rate rules or implied by the reaction rate definitions), there will be a 211 * single edge between the equation and the variable determined by that 212 * differential equation. A mathematical model is overdetermined if the 213 * maximal matchings of the bipartite graph contain disconnected vertexes 214 * representing equations. If one maximal matching has this property, then 215 * all the maximal matchings will have this property; i.e., it is only 216 * necessary to find one maximal matching.) 217 <p> 218 * <h2>Rule types for SBML Level 1</h2> 219 <p> 220 * SBML Level 1 uses a different scheme than SBML Level 2 and Level 3 for 221 * distinguishing rules; specifically, it uses an attribute whose value is 222 * drawn from an enumeration of 3 values. LibSBML supports this using methods 223 * that work with the enumeration values listed below. 224 <p> 225 * <ul> 226 * <li> {@link libsbmlConstants#RULE_TYPE_RATE RULE_TYPE_RATE}: Indicates 227 * the rule is a 'rate' rule. 228 * <li> {@link libsbmlConstants#RULE_TYPE_SCALAR RULE_TYPE_SCALAR}: 229 * Indicates the rule is a 'scalar' rule. 230 * <li> {@link libsbmlConstants#RULE_TYPE_INVALID RULE_TYPE_INVALID}: 231 * Indicates the rule type is unknown or not yet set. 232 * 233 * </ul> 234 */ 235 236public class AlgebraicRule extends Rule { 237 private long swigCPtr; 238 239 protected AlgebraicRule(long cPtr, boolean cMemoryOwn) 240 { 241 super(libsbmlJNI.AlgebraicRule_SWIGUpcast(cPtr), cMemoryOwn); 242 swigCPtr = cPtr; 243 } 244 245 protected static long getCPtr(AlgebraicRule obj) 246 { 247 return (obj == null) ? 0 : obj.swigCPtr; 248 } 249 250 protected static long getCPtrAndDisown (AlgebraicRule obj) 251 { 252 long ptr = 0; 253 254 if (obj != null) 255 { 256 ptr = obj.swigCPtr; 257 obj.swigCMemOwn = false; 258 } 259 260 return ptr; 261 } 262 263 protected void finalize() { 264 delete(); 265 } 266 267 public synchronized void delete() { 268 if (swigCPtr != 0) { 269 if (swigCMemOwn) { 270 swigCMemOwn = false; 271 libsbmlJNI.delete_AlgebraicRule(swigCPtr); 272 } 273 swigCPtr = 0; 274 } 275 super.delete(); 276 } 277 278 279/** 280 * Creates a new {@link AlgebraicRule} object using the given SBML <code>level</code> and 281 * <code>version</code> values. 282 <p> 283 * @param level the SBML Level to assign to this {@link AlgebraicRule} object. 284 <p> 285 * @param version the SBML Version to assign to this {@link AlgebraicRule} object. 286 <p> 287 * <p> 288 * @throws SBMLConstructorException 289 * Thrown if the given <code>level</code> and <code>version</code> combination are invalid 290 * or if this object is incompatible with the given level and version. 291 <p> 292 * <p> 293 * @note Attempting to add an object to an {@link SBMLDocument} having a different 294 * combination of SBML Level, Version and XML namespaces than the object 295 * itself will result in an error at the time a caller attempts to make the 296 * addition. A parent object must have compatible Level, Version and XML 297 * namespaces. (Strictly speaking, a parent may also have more XML 298 * namespaces than a child, but the reverse is not permitted.) The 299 * restriction is necessary to ensure that an SBML model has a consistent 300 * overall structure. This requires callers to manage their objects 301 * carefully, but the benefit is increased flexibility in how models can be 302 * created by permitting callers to create objects bottom-up if desired. In 303 * situations where objects are not yet attached to parents (e.g., 304 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 305 * libSBML determine such things as whether it is valid to assign a 306 * particular value to an attribute. 307 */ public 308 AlgebraicRule(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 309 this(libsbmlJNI.new_AlgebraicRule__SWIG_0(level, version), true); 310 } 311 312 313/** 314 * Creates a new {@link AlgebraicRule} object using the given {@link SBMLNamespaces} object 315 * <code>sbmlns</code>. 316 <p> 317 * <p> 318 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces 319 * information. It is used to communicate the SBML Level, Version, and (in 320 * Level 3) packages used in addition to SBML Level 3 Core. A 321 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an 322 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object 323 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments. 324 <p> 325 * @param sbmlns an {@link SBMLNamespaces} object. 326 <p> 327 * <p> 328 * @throws SBMLConstructorException 329 * Thrown if the given <code>sbmlns</code> is inconsistent or incompatible 330 * with this object. 331 <p> 332 * <p> 333 * @note Attempting to add an object to an {@link SBMLDocument} having a different 334 * combination of SBML Level, Version and XML namespaces than the object 335 * itself will result in an error at the time a caller attempts to make the 336 * addition. A parent object must have compatible Level, Version and XML 337 * namespaces. (Strictly speaking, a parent may also have more XML 338 * namespaces than a child, but the reverse is not permitted.) The 339 * restriction is necessary to ensure that an SBML model has a consistent 340 * overall structure. This requires callers to manage their objects 341 * carefully, but the benefit is increased flexibility in how models can be 342 * created by permitting callers to create objects bottom-up if desired. In 343 * situations where objects are not yet attached to parents (e.g., 344 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 345 * libSBML determine such things as whether it is valid to assign a 346 * particular value to an attribute. 347 */ public 348 AlgebraicRule(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException { 349 this(libsbmlJNI.new_AlgebraicRule__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true); 350 } 351 352 353/** 354 * Creates and returns a deep copy of this {@link AlgebraicRule} object. 355 <p> 356 * @return the (deep) copy of this {@link Rule} object. 357 */ public 358 AlgebraicRule cloneObject() { 359 long cPtr = libsbmlJNI.AlgebraicRule_cloneObject(swigCPtr, this); 360 return (cPtr == 0) ? null : new AlgebraicRule(cPtr, true); 361 } 362 363 364/** 365 * Predicate returning <code>true</code> if all the required attributes for this 366 * {@link AlgebraicRule} object have been set. 367 <p> 368 * In SBML Levels 2–3, there is no required attribute 369 * for an {@link AlgebraicRule} object. For Level 1, the only required 370 * attribute is 'formula'. 371 <p> 372 * @return <code>true</code> if the required attributes have been set, <code>false</code> 373 * otherwise. 374 */ public 375 boolean hasRequiredAttributes() { 376 return libsbmlJNI.AlgebraicRule_hasRequiredAttributes(swigCPtr, this); 377 } 378 379}