001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 2.0.11 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 * 013 * Implementation of SBML's InitialAssignment construct. 014 * <p> 015 * SBML Level 2 Versions 2–4 and SBML Level 3 provide two ways of assigning initial 016 * values to entities in a model. The simplest and most basic is to set 017 * the values of the appropriate attributes in the relevant components; for 018 * example, the initial value of a model parameter (whether it is a 019 * constant or a variable) can be assigned by setting its 'value' attribute 020 * directly in the model definition. However, this approach is not 021 * suitable when the value must be calculated, because the initial value 022 * attributes on different components such as species, compartments, and 023 * parameters are single values and not mathematical expressions. In those 024 * situations, the {@link InitialAssignment} construct can be used; it permits the 025 * calculation of the value of a constant or the initial value of a 026 * variable from the values of <em>other</em> quantities in a model. 027 * <p> 028 * As explained below, the provision of {@link InitialAssignment} does not mean 029 * that models necessarily must use this construct when defining initial 030 * values of quantities in a model. If a value can be set directly using 031 * the relevant attribute of a component in a model, then that 032 * approach may be more efficient and more portable to other software 033 * tools. {@link InitialAssignment} should be used when the other mechanism is 034 * insufficient for the needs of a particular model. 035 * <p> 036 * The {@link InitialAssignment} construct has some similarities to {@link AssignmentRule}. 037 * The main differences are: (a) an {@link InitialAssignment} can set the value of 038 * a constant whereas an {@link AssignmentRule} cannot, and (b) unlike 039 * {@link AssignmentRule}, an {@link InitialAssignment} definition only applies up to and 040 * including the beginning of simulation time, i.e., <em>t ≤ 0</em>, 041 * while an {@link AssignmentRule} applies at all times. 042 * <p> 043 * {@link InitialAssignment} has a required attribute, 'symbol', whose value must 044 * follow the guidelines for identifiers described in the SBML 045 * specification (e.g., Section 3.3 in the Level 2 Version 4 046 * specification). The value of this attribute in an {@link InitialAssignment} 047 * object can be the identifier of a {@link Compartment}, {@link Species} or global 048 * {@link Parameter} elsewhere in the model. The {@link InitialAssignment} defines the 049 * initial value of the constant or variable referred to by the 'symbol' 050 * attribute. (The attribute's name is 'symbol' rather than 'variable' 051 * because it may assign values to constants as well as variables in a 052 * model.) Note that an initial assignment cannot be made to reaction 053 * identifiers, that is, the 'symbol' attribute value of an 054 * {@link InitialAssignment} cannot be an identifier that is the 'id' attribute 055 * value of a {@link Reaction} object in the model. This is identical to a 056 * restriction placed on rules. 057 * <p> 058 * {@link InitialAssignment} also has a required 'math' subelement that contains a 059 * MathML expression used to calculate the value of the constant or the 060 * initial value of the variable. The units of the value computed by the 061 * formula in the 'math' subelement should (in SBML Level 2 062 * Version 4 and in SBML Level 3) or must (in previous Versions) be identical to be the 063 * units associated with the identifier given in the 'symbol' attribute. 064 * (That is, the units are the units of the species, compartment, or 065 * parameter, as appropriate for the kind of object identified by the value 066 * of 'symbol'.) 067 * <p> 068 * {@link InitialAssignment} was introduced in SBML Level 2 Version 2. It is not 069 * available in SBML Level 2 Version 1 nor in any version of Level 1. 070 * <p> 071 * <h2>Semantics of Initial Assignments</h2> 072 * <p> 073 * The value calculated by an {@link InitialAssignment} object overrides the value 074 * assigned to the given symbol by the object defining that symbol. For 075 * example, if a compartment's 'size' attribute is set in its definition, 076 * and the model also contains an {@link InitialAssignment} having that 077 * compartment's identifier as its 'symbol' attribute value, then the 078 * interpretation is that the 'size' assigned in the {@link Compartment} object 079 * should be ignored and the value assigned based on the computation 080 * defined in the {@link InitialAssignment}. Initial assignments can take place 081 * for {@link Compartment}, {@link Species} and global {@link Parameter} objects regardless of the 082 * value of their 'constant' attribute. 083 * <p> 084 * The actions of all {@link InitialAssignment} objects are in general terms 085 * the same, but differ in the precise details depending on the type 086 * of variable being set: 087 * <ul> 088 * <li> <em>In the case of a species</em>, an {@link InitialAssignment} sets the 089 * referenced species' initial quantity (concentration or amount of 090 * substance) to the value determined by the formula in the 'math' 091 * subelement. The overall units of the formula should (in SBML 092 * Level 2 Version 4 and in SBML Level 3) or must (in previous Versions) be the same 093 * as the units specified for the species. 094 * <p> 095 * <li> <em>In the case of a compartment</em>, an {@link InitialAssignment} sets 096 * the referenced compartment's initial size to the size determined by the 097 * formula in 'math'. The overall units of the formula should (in SBML 098 * Level 2 Version 4 and in SBML Level 3) or must (in previous Versions) be the same 099 * as the units specified for the size of the compartment. 100 * <p> 101 * <li> <em>In the case of a parameter</em>, an {@link InitialAssignment} sets the 102 * referenced parameter's initial value to that determined by the formula 103 * in 'math'. The overall units of the formula should (in SBML 104 * Level 2 Version 4 and SBML Level 3) or must (in previous Versions) be the same 105 * as the units defined for the parameter. </ul> 106 * <p> 107 * In the context of a simulation, initial assignments establish values 108 * that are in effect prior to and including the start of simulation time, 109 * i.e., <em>t ≤ 0</em>. Section 3.4.8 in the SBML Level 2 110 * Version 4 and SBML Level 3 Version 1 Core specifications provides information about the interpretation of 111 * assignments, rules, and entity values for simulation time up to and 112 * including the start time <em>t = 0</em>; this is important for 113 * establishing the initial conditions of a simulation if the model 114 * involves expressions containing the <em>delay</em> 'csymbol'. 115 * <p> 116 * There cannot be two initial assignments for the same symbol in a model; 117 * that is, a model must not contain two or more {@link InitialAssignment} objects 118 * that both have the same identifier as their 'symbol' attribute value. A 119 * model must also not define initial assignments <em>and</em> assignment 120 * rules for the same entity. That is, there cannot be <em>both</em> an 121 * {@link InitialAssignment} and an {@link AssignmentRule} for the same symbol in a model, 122 * because both kinds of constructs apply prior to and at the start of 123 * simulated time—allowing both to exist for a given symbol would 124 * result in indeterminism). 125 * <p> 126 * The ordering of {@link InitialAssignment} objects is not significant. The 127 * combined set of {@link InitialAssignment}, {@link AssignmentRule} and {@link KineticLaw} 128 * objects form a set of assignment statements that must be considered as a 129 * whole. The combined set of assignment statements should not contain 130 * algebraic loops: a chain of dependency between these statements should 131 * terminate. (More formally, consider the directed graph of assignment 132 * statements where nodes are a model's assignment statements and directed 133 * arcs exist for each occurrence of a symbol in an assignment statement 134 * 'math' attribute. The directed arcs in this graph start from the 135 * statement assigning the symbol and end at the statement that contains 136 * the symbol in their math elements. Such a graph must be acyclic.) 137 * <p> 138 * Finally, it is worth being explicit about the expected behavior in the 139 * following situation. Suppose (1) a given symbol has a value <em>x</em> 140 * assigned to it in its definition, and (2) there is an initial assignment 141 * having the identifier as its 'symbol' value and reassigning the value to 142 * <em>y</em>, <em>and</em> (3) the identifier is also used in the 143 * mathematical formula of a second initial assignment. What value should 144 * the second initial assignment use? It is <em>y</em>, the value assigned 145 * to the symbol by the first initial assignment, not whatever value was 146 * given in the symbol's definition. This follows directly from the 147 * behavior described above: if an {@link InitialAssignment} object exists for a 148 * given symbol, then the symbol's value is overridden by that initial 149 * assignment. 150 * <p> 151 * <!---------------------------------------------------------------------- --> 152 * <p> 153 */ 154 155public class InitialAssignment extends SBase { 156 private long swigCPtr; 157 158 protected InitialAssignment(long cPtr, boolean cMemoryOwn) 159 { 160 super(libsbmlJNI.InitialAssignment_SWIGUpcast(cPtr), cMemoryOwn); 161 swigCPtr = cPtr; 162 } 163 164 protected static long getCPtr(InitialAssignment obj) 165 { 166 return (obj == null) ? 0 : obj.swigCPtr; 167 } 168 169 protected static long getCPtrAndDisown (InitialAssignment obj) 170 { 171 long ptr = 0; 172 173 if (obj != null) 174 { 175 ptr = obj.swigCPtr; 176 obj.swigCMemOwn = false; 177 } 178 179 return ptr; 180 } 181 182 protected void finalize() { 183 delete(); 184 } 185 186 public synchronized void delete() { 187 if (swigCPtr != 0) { 188 if (swigCMemOwn) { 189 swigCMemOwn = false; 190 libsbmlJNI.delete_InitialAssignment(swigCPtr); 191 } 192 swigCPtr = 0; 193 } 194 super.delete(); 195 } 196 197 198/** 199 * Creates a new {@link InitialAssignment} using the given SBML <code>level</code> and <code>version</code> 200 * values. 201 * <p> 202 * @param level a long integer, the SBML Level to assign to this {@link InitialAssignment} 203 * <p> 204 * @param version a long integer, the SBML Version to assign to this 205 * {@link InitialAssignment} 206 * <p> 207 * @throws SBMLConstructorException 208 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 209 * of SBML object, are either invalid or mismatched with respect to the 210 * parent {@link SBMLDocument} object. 211 * <p> 212 * @note Upon the addition of a {@link InitialAssignment} object to an 213 * {@link SBMLDocument} (e.g., using {@link Model#addInitialAssignment(InitialAssignment ia)}), the SBML 214 * Level, SBML Version and XML namespace of the document 215 * <em>override</em> the values used when creating the {@link InitialAssignment} object 216 * via this constructor. This is necessary to ensure that an SBML 217 * document is a consistent structure. Nevertheless, the ability to 218 * supply the values at the time of creation of a {@link InitialAssignment} is an 219 * important aid to producing valid SBML. Knowledge of the intented SBML 220 * Level and Version determine whether it is valid to assign a particular 221 * value to an attribute, or whether it is valid to add an object to an 222 * existing {@link SBMLDocument}. 223 */ public 224 InitialAssignment(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 225 this(libsbmlJNI.new_InitialAssignment__SWIG_0(level, version), true); 226 } 227 228 229/** 230 * Creates a new {@link InitialAssignment} using the given {@link SBMLNamespaces} object 231 * <code>sbmlns</code>. 232 * <p> 233 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces 234 * information. It is used to communicate the SBML Level, Version, and 235 * (in Level 3) packages used in addition to SBML Level 3 Core. 236 * A common approach to using this class constructor is to create an 237 * {@link SBMLNamespaces} object somewhere in a program, once, then pass it to 238 * object constructors such as this one when needed. 239 * <p> 240 * @param sbmlns an {@link SBMLNamespaces} object. 241 * <p> 242 * @throws SBMLConstructorException 243 * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind 244 * of SBML object, are either invalid or mismatched with respect to the 245 * parent {@link SBMLDocument} object. 246 * <p> 247 * @note Upon the addition of a {@link InitialAssignment} object to an 248 * {@link SBMLDocument} (e.g., using {@link Model#addInitialAssignment(InitialAssignment ia)}), the SBML XML 249 * namespace of the document <em>overrides</em> the value used when creating 250 * the {@link InitialAssignment} object via this constructor. This is necessary 251 * to ensure that an SBML document is a consistent structure. 252 * Nevertheless, the ability to supply the values at the time of creation 253 * of a {@link InitialAssignment} is an important aid to producing valid SBML. 254 * Knowledge of the intented SBML Level and Version determine whether it 255 * is valid to assign a particular value to an attribute, or whether it 256 * is valid to add an object to an existing {@link SBMLDocument}. 257 */ public 258 InitialAssignment(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException { 259 this(libsbmlJNI.new_InitialAssignment__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true); 260 } 261 262 263/** 264 * Copy constructor; creates a copy of this {@link InitialAssignment}. 265 * <p> 266 * @param orig the object to copy. 267 * <p> 268 * @throws SBMLConstructorException 269 * Thrown if the argument <code>orig</code> is <code>null.</code> 270 */ public 271 InitialAssignment(InitialAssignment orig) throws org.sbml.libsbml.SBMLConstructorException { 272 this(libsbmlJNI.new_InitialAssignment__SWIG_2(InitialAssignment.getCPtr(orig), orig), true); 273 } 274 275 276/** 277 * Creates and returns a deep copy of this {@link InitialAssignment}. 278 * <p> 279 * @return a (deep) copy of this {@link InitialAssignment}. 280 */ public 281 InitialAssignment cloneObject() { 282 long cPtr = libsbmlJNI.InitialAssignment_cloneObject(swigCPtr, this); 283 return (cPtr == 0) ? null : new InitialAssignment(cPtr, true); 284 } 285 286 287/** 288 * Get the value of the 'symbol' attribute of this {@link InitialAssignment}. 289 * <p> 290 * @return the identifier string stored as the 'symbol' attribute value 291 * in this {@link InitialAssignment}. 292 */ public 293 String getSymbol() { 294 return libsbmlJNI.InitialAssignment_getSymbol(swigCPtr, this); 295 } 296 297 298/** 299 * Get the mathematical formula of this {@link InitialAssignment}. 300 * <p> 301 * @return an {@link ASTNode}, the value of the 'math' subelement of this 302 * {@link InitialAssignment} 303 */ public 304 ASTNode getMath() { 305 long cPtr = libsbmlJNI.InitialAssignment_getMath(swigCPtr, this); 306 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 307 } 308 309 310/** 311 * Predicate returning <code>true</code> if this 312 * {@link InitialAssignment}'s 'symbol' attribute is set. 313 * <p> 314 * @return <code>true</code> if the 'symbol' attribute of this {@link InitialAssignment} 315 * is set, <code>false</code> otherwise. 316 */ public 317 boolean isSetSymbol() { 318 return libsbmlJNI.InitialAssignment_isSetSymbol(swigCPtr, this); 319 } 320 321 322/** 323 * Predicate returning <code>true</code> if this 324 * {@link InitialAssignment}'s 'math' subelement contains a value. 325 * <p> 326 * @return <code>true</code> if the 'math' for this {@link InitialAssignment} is set, 327 * <code>false</code> otherwise. 328 */ public 329 boolean isSetMath() { 330 return libsbmlJNI.InitialAssignment_isSetMath(swigCPtr, this); 331 } 332 333 334/** 335 * Sets the 'symbol' attribute value of this {@link InitialAssignment}. 336 * <p> 337 * @param sid the identifier of a {@link Species}, {@link Compartment} or {@link Parameter} 338 * object defined elsewhere in this {@link Model}. 339 * <p> 340 * @return integer value indicating success/failure of the 341 * function. The possible values 342 * returned by this function are: 343 * <ul> 344 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 345 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE } 346 * </ul> 347 */ public 348 int setSymbol(String sid) { 349 return libsbmlJNI.InitialAssignment_setSymbol(swigCPtr, this, sid); 350 } 351 352 353/** 354 * Sets the 'math' subelement of this {@link InitialAssignment}. 355 * <p> 356 * The AST passed in <code>math</code> is copied. 357 * <p> 358 * @param math an AST containing the mathematical expression to 359 * be used as the formula for this {@link InitialAssignment}. 360 * <p> 361 * @return integer value indicating success/failure of the 362 * function. The possible values 363 * returned by this function are: 364 * <ul> 365 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS } 366 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT } 367 * </ul> 368 */ public 369 int setMath(ASTNode math) { 370 return libsbmlJNI.InitialAssignment_setMath(swigCPtr, this, ASTNode.getCPtr(math), math); 371 } 372 373 374/** 375 * Calculates and returns a {@link UnitDefinition} that expresses the units 376 * of measurement assumed for the 'math' expression of this 377 * {@link InitialAssignment}. 378 * <p> 379 * The units are calculated based on the mathematical expression in the 380 * {@link InitialAssignment} and the model quantities referenced by 381 * <code><ci></code> elements used within that expression. The 382 * {@link InitialAssignment#getDerivedUnitDefinition()} 383 * method returns the calculated units. 384 * <p> 385 * Note that the functionality that facilitates unit analysis depends 386 * on the model as a whole. Thus, in cases where the object has not 387 * been added to a model or the model itself is incomplete, 388 * unit analysis is not possible and this method will return <code>null.</code> 389 * <p> 390 * @warning Note that it is possible the 'math' expression in the 391 * {@link InitialAssignment} contains pure numbers or parameters with undeclared 392 * units. In those cases, it is not possible to calculate the units of 393 * the overall expression without making assumptions. LibSBML does not 394 * make assumptions about the units, and 395 * {@link InitialAssignment#getDerivedUnitDefinition()} 396 * only returns the units as far as it is able to determine them. For 397 * example, in an expression <em>X + Y</em>, if <em>X</em> has 398 * unambiguously-defined units and <em>Y</em> does not, it will return 399 * the units of <em>X</em>. <strong>It is important that callers also 400 * invoke the method</strong> 401 * {@link InitialAssignment#containsUndeclaredUnits()} 402 * <strong>to determine whether this situation holds</strong>. Callers 403 * may wish to take suitable actions in those scenarios. 404 * <p> 405 * @return a {@link UnitDefinition} that expresses the units of the math 406 * expression of this {@link InitialAssignment}, or <code>null</code> if one cannot be constructed. 407 * <p> 408 * @see #containsUndeclaredUnits() 409 */ public 410 UnitDefinition getDerivedUnitDefinition() { 411 long cPtr = libsbmlJNI.InitialAssignment_getDerivedUnitDefinition__SWIG_0(swigCPtr, this); 412 return (cPtr == 0) ? null : new UnitDefinition(cPtr, false); 413 } 414 415 416/** 417 * Predicate returning <code>true</code> if 418 * the math expression of this {@link InitialAssignment} contains 419 * parameters/numbers with undeclared units. 420 * <p> 421 * @return <code>true</code> if the math expression of this {@link InitialAssignment} 422 * includes parameters/numbers 423 * with undeclared units, <code>false</code> otherwise. 424 * <p> 425 * @note A return value of <code>true</code> indicates that the {@link UnitDefinition} 426 * returned by 427 * {@link InitialAssignment#getDerivedUnitDefinition()} 428 * may not accurately represent the units of the expression. 429 * <p> 430 * @see #getDerivedUnitDefinition() 431 */ public 432 boolean containsUndeclaredUnits() { 433 return libsbmlJNI.InitialAssignment_containsUndeclaredUnits__SWIG_0(swigCPtr, this); 434 } 435 436 437/** 438 * Returns the libSBML type code for this SBML object. 439 * <p> 440 * LibSBML attaches an identifying code to every 441 * kind of SBML object. These are known as <em>SBML type codes</em>. In 442 * other languages, the set of type codes is stored in an enumeration; in 443 * the Java language interface for libSBML, the type codes are defined as 444 * static integer constants in the interface class {@link 445 * libsbmlConstants}. The names of the type codes all begin with the 446 * characters <code>SBML_.</code> 447 * <p> 448 * @return the SBML type code for this object, or {@link libsbmlConstants#SBML_UNKNOWN SBML_UNKNOWN} (default). 449 * <p> 450 * @see #getElementName() 451 */ public 452 int getTypeCode() { 453 return libsbmlJNI.InitialAssignment_getTypeCode(swigCPtr, this); 454 } 455 456 457/** 458 * Returns the XML element name of this object, which for 459 * {@link InitialAssignment}, is always <code>'initialAssignment'.</code> 460 * <p> 461 * @return the name of this element, i.e., <code>'initialAssignment'.</code> 462 */ public 463 String getElementName() { 464 return libsbmlJNI.InitialAssignment_getElementName(swigCPtr, this); 465 } 466 467 468/** 469 * Predicate returning <code>true</code> if 470 * all the required attributes for this {@link InitialAssignment} object 471 * have been set. 472 * <p> 473 * @note The required attributes for an {@link InitialAssignment} object are: 474 * <ul> 475 * <li> 'symbol' 476 * </ul> 477 * <p> 478 * @return a boolean value indicating whether all the required 479 * attributes for this object have been defined. 480 */ public 481 boolean hasRequiredAttributes() { 482 return libsbmlJNI.InitialAssignment_hasRequiredAttributes(swigCPtr, this); 483 } 484 485 486/** 487 * Predicate returning <code>true</code> if 488 * all the required elements for this {@link InitialAssignment} object 489 * have been set. 490 * <p> 491 * @note The required elements for a {@link InitialAssignment} object are: 492 * <ul> 493 * <li> 'math' 494 * </ul> 495 * <p> 496 * @return a boolean value indicating whether all the required 497 * elements for this object have been defined. 498 */ public 499 boolean hasRequiredElements() { 500 return libsbmlJNI.InitialAssignment_hasRequiredElements(swigCPtr, this); 501 } 502 503 504/** 505 * Predicate returning <code>true</code> if 506 * all the required elements for this {@link InitialAssignment} object 507 * have been set. 508 * <p> 509 * @note The required elements for a {@link InitialAssignment} object are: 510 * <ul> 511 * <li> 'math' 512 * </ul> 513 * <p> 514 * @return a boolean value indicating whether all the required 515 * elements for this object have been defined. 516 */ public 517 String getId() { 518 return libsbmlJNI.InitialAssignment_getId(swigCPtr, this); 519 } 520 521 522/** 523 * Renames all the SIdRef attributes on this element, including any found in MathML 524 */ public 525 void renameSIdRefs(String oldid, String newid) { 526 libsbmlJNI.InitialAssignment_renameSIdRefs(swigCPtr, this, oldid, newid); 527 } 528 529 530/** 531 * Renames all the UnitSIdRef attributes on this element 532 */ public 533 void renameUnitSIdRefs(String oldid, String newid) { 534 libsbmlJNI.InitialAssignment_renameUnitSIdRefs(swigCPtr, this, oldid, newid); 535 } 536 537 538/** 539 * Replace all nodes with the name 'id' from the child 'math' object with the provided function. 540 * <p> 541 * @internal 542 */ public 543 void replaceSIDWithFunction(String id, ASTNode function) { 544 libsbmlJNI.InitialAssignment_replaceSIDWithFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 545 } 546 547 548/** 549 * If this assignment assigns a value to the 'id' element, replace the 'math' object with the function (existing/function). 550 * @internal 551 */ public 552 void divideAssignmentsToSIdByFunction(String id, ASTNode function) { 553 libsbmlJNI.InitialAssignment_divideAssignmentsToSIdByFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 554 } 555 556 557/** 558 * If this assignment assigns a value to the 'id' element, replace the 'math' object with the function (existing*function). 559 * @internal 560 */ public 561 void multiplyAssignmentsToSIdByFunction(String id, ASTNode function) { 562 libsbmlJNI.InitialAssignment_multiplyAssignmentsToSIdByFunction(swigCPtr, this, id, ASTNode.getCPtr(function), function); 563 } 564 565}