1 /* ---------------------------------------------------------------------------- 2 * This file was automatically generated by SWIG (http://www.swig.org). 3 * Version 4.0.2 4 * 5 * Do not make changes to this file unless you know what you are doing--modify 6 * the SWIG interface file instead. 7 * ----------------------------------------------------------------------------- */ 8 9 package org.sbml.libsbml; 10 11 /** 12 * An SBML <em>species</em> – a pool of entities. 13 <p> 14 * A <em>species</em> in SBML refers to a pool of entities that (a) are 15 * considered indistinguishable from each other for the purposes of the 16 * model, (b) participate in reactions, and (c) are located in a specific 17 * <em>compartment</em>. The SBML {@link Species} object class is intended to represent 18 * these pools. 19 <p> 20 * As with other major constructs in SBML, {@link Species} has a mandatory 21 * attribute, 'id', used to give the species type an identifier in the 22 * model. The identifier must be a text string conforming to the identifer 23 * syntax permitted in SBML. {@link Species} also has an optional 'name' 24 * attribute, of type <code>string.</code> The 'id' and 'name' must be used 25 * according to the guidelines described in the SBML specifications. 26 <p> 27 * The required attribute 'compartment' is used to identify the compartment 28 * in which the species is located. The attribute's value must be the 29 * identifier of an existing {@link Compartment} object. It is important to note 30 * that there is no default value for the 'compartment' attribute on 31 * {@link Species}; every species in an SBML model must be assigned a compartment 32 * <em>explicitly</em>. (This also implies that every model with one or more 33 * {@link Species} objects must define at least one {@link Compartment} object.) 34 <p> 35 * <h2>The initial amount and concentration of a species</h2> 36 <p> 37 * The optional attributes 'initialAmount' and 'initialConcentration', both 38 * having a data type of <code>double</code>, can be used to set the <em>initial</em> 39 * quantity of the species in the compartment where the species is located. 40 * These attributes are mutually exclusive; i.e., <em>only one</em> can 41 * have a value on any given instance of a {@link Species} object. Missing 42 * 'initialAmount' and 'initialConcentration' values implies that their 43 * values either are unknown, or to be obtained from an external source, or 44 * determined by an {@link InitialAssignment} or other SBML construct elsewhere in 45 * the model. 46 <p> 47 * A species' initial quantity in SBML is set by the 'initialAmount' or 48 * 'initialConcentration' attribute exactly once. If the 'constant' 49 * attribute is <code>true</code>, then the value of the species' quantity is fixed 50 * and cannot be changed except by an {@link InitialAssignment}. These methods 51 * differ in that the 'initialAmount' and 'initialConcentration' attributes 52 * can only be used to set the species quantity to a literal floating-point 53 * number, whereas the use of an {@link InitialAssignment} object allows the value 54 * to be set using an arbitrary mathematical expression (which, thanks to 55 * MathML's expressiveness, may evaluate to a rational number). If the 56 * species' 'constant' attribute is <code>false</code>, the species' quantity value 57 * may be overridden by an {@link InitialAssignment} or changed by {@link AssignmentRule} 58 * or {@link AlgebraicRule}, and in addition, for <em>t > 0</em>, it may also be 59 * changed by a {@link RateRule}, {@link Event} objects, and as a result of being a 60 * reactant or product in one or more {@link Reaction} objects. (However, some 61 * constructs are mutually exclusive; see the SBML specifications for the 62 * precise details.) It is not an error to define 'initialAmount' or 63 * 'initialConcentration' on a species and also redefine the value using an 64 * {@link InitialAssignment}, but the 'initialAmount' or 'initialConcentration' 65 * setting in that case is ignored. The SBML specifications provide 66 * additional information about the semantics of assignments, rules and 67 * values for simulation time <em>t</em> ≤ <em>0</em>. 68 <p> 69 * SBML Level 2 additionally stipulates that in cases where a species' 70 * compartment has a 'spatialDimensions' value of <code>0</code> (zero), the species 71 * cannot have a value for 'initialConcentration' because the concepts of 72 * concentration and density break down when a container has zero 73 * dimensions. 74 <p> 75 * <h2>The units of a species' amount or concentration</h2> 76 <p> 77 * When the attribute 'initialAmount' is set, the unit of measurement 78 * associated with the value of 'initialAmount' is specified by the {@link Species} 79 * attribute 'substanceUnits'. When the 'initialConcentration' attribute 80 * is set, the unit of measurement associated with this concentration value 81 * is {<em>unit of amount</em>} divided by {<em>unit of size</em>}, where 82 * the {<em>unit of amount</em>} is specified by the {@link Species} 83 * 'substanceUnits' attribute, and the {<em>unit of size</em>} is specified 84 * by the 'units' attribute of the {@link Compartment} object in which the species 85 * is located. Note that in either case, a unit of <em>amount</em> is 86 * involved and determined by the 'substanceUnits' attribute. Note 87 * <strong>these two attributes alone do not determine the units of the 88 * species when the species identifier appears in a mathematical 89 * expression</strong>; <em>that</em> aspect is determined by the attribute 90 * 'hasOnlySubstanceUnits' discussed below. 91 <p> 92 * In SBML Level 3, if the 'substanceUnits' attribute is not set on a 93 * given {@link Species} object instance, then the unit of <em>amount</em> for that 94 * species is inherited from the 'substanceUnits' attribute on the 95 * enclosing {@link Model} object instance. If that attribute on {@link Model} is not set 96 * either, then the unit associated with the species' quantity is 97 * undefined. 98 <p> 99 * In SBML Level 2, if the 'substanceUnits' attribute is not set on a 100 * given {@link Species} object instance, then the unit of <em>amount</em> for that 101 * species is taken from the predefined SBML unit identifier 102 * <code>'substance'.</code> The value assigned to 'substanceUnits' must be chosen from 103 * one of the following possibilities: one of the base unit identifiers 104 * defined in SBML, the built-in unit identifier <code>'substance'</code>, or the 105 * identifier of a new unit defined in the list of unit definitions in the 106 * enclosing {@link Model} object. The chosen units for 'substanceUnits' must be 107 * be <code>'dimensionless'</code>, <code>'mole'</code>, <code>'item'</code>, <code>'kilogram'</code>, <code>'gram'</code>, 108 * or units derived from these. 109 <p> 110 * As noted at the beginning of this section, simply setting 111 * 'initialAmount' or 'initialConcentration' alone does <em>not</em> determine 112 * whether a species identifier represents an amount or a concentration 113 * when it appears elsewhere in an SBML model. The role of the attribute 114 * 'hasOnlySubstanceUnits' is to indicate whether the units of the species, 115 * when the species identifier appears in mathematical formulas, are 116 * intended to be concentration or amount. The attribute takes on a 117 * boolean value. In SBML Level 3, the attribute has no default value 118 * and must always be set in a model; in SBML Level 2, it has a 119 * default value of <code>false.</code> 120 <p> 121 * The <em>units of the species</em> are used in the following ways: 122 * <ul> 123 <p> 124 * <li> When the species' identifier appears in a MathML formula, it 125 * represents the species' quantity, and the unit of measurement associated 126 * with the quantity is as described above. 127 <p> 128 * <li> The 'math' elements of {@link AssignmentRule}, {@link InitialAssignment} and 129 * {@link EventAssignment} objects referring to this species should all have the 130 * same units as the unit of measurement associated with the species 131 * quantity. 132 <p> 133 * <li> In a {@link RateRule} object that defines the rate of change of the 134 * species' quantity, the unit associated with the rule's 'math' element 135 * should be equal to the unit of the species' quantity divided by the 136 * model-wide unit of <em>time</em>; in other words, {<em>unit of species 137 * quantity</em>}/{<em>unit of time</em>}. 138 <p> 139 * </ul> 140 <p> 141 * <h2>The 'constant' and 'boundaryCondition' attributes</h2> 142 <p> 143 * The {@link Species} object class has two boolean attributes named 'constant' and 144 * 'boundaryCondition', used to indicate whether and how the quantity of 145 * that species can vary during a simulation. In SBML Level 2 they 146 * are optional; in SBML Level 3 they are mandatory. The following 147 * table shows how to interpret the combined values of these attributes. 148 <p> 149 * <table border="0" class="centered text-table width80 normal-font alt-row-colors"> 150 <caption class="top-caption">Interpretation 151 of species' <code>constant</code> and <code>boundaryCondition</code> 152 attributes.</caption> 153 <tr> 154 <th align="left" valign="bottom"> 155 <code>constant</code><br>value 156 </th> 157 <th align="left" valign="bottom"> 158 <code>boundaryCondition</code><br>value 159 </th> 160 <th align="left" valign="bottom"> 161 Can have<br>assignment<br>or rate rule? 162 </th> 163 <th align="left" valign="bottom"> 164 Can be<br>reactant<br>or product? 165 </th> 166 <th align="left" valign="bottom"> 167 Species' quantity<br>can be changed by 168 </th> 169 </tr> 170 <tr> 171 <td><code>true</code></td> 172 <td><code>true</code></td> 173 <td>no</td> 174 <td>yes</td> 175 <td>(never changes)</td> 176 </tr> 177 <tr> 178 <td><code>false</code></td> 179 <td><code>true</code></td> 180 <td>yes</td> 181 <td>yes</td> 182 <td>rules and events</td> 183 </tr> 184 <tr> 185 <td><code>true</code></td> 186 <td><code>false</code></td> 187 <td>no</td> 188 <td>no</td> 189 <td>(never changes)</td> 190 </tr> 191 <tr> 192 <td><code>false</code></td> 193 <td><code>false</code></td> 194 <td>yes</td> 195 <td>yes</td> 196 <td>reactions <em>or</em> rules (but not both at the same time), and events</td> 197 </tr> 198 </table> 199 200 201 <p> 202 * By default, when a species is a product or reactant of one or more 203 * reactions, its quantity is determined by those reactions. In SBML, it 204 * is possible to indicate that a given species' quantity is <em>not</em> 205 * determined by the set of reactions even when that species occurs as a 206 * product or reactant; i.e., the species is on the <em>boundary</em> of 207 * the reaction system, and its quantity is not determined by the 208 * reactions. The boolean attribute 'boundaryCondition' can be used to 209 * indicate this. A value of <code>false</code> indicates that the species <em>is</em> 210 * part of the reaction system. In SBML Level 2, the attribute has a 211 * default value of <code>false</code>, while in SBML Level 3, it has no 212 * default. 213 <p> 214 * The 'constant' attribute indicates whether the species' quantity can be 215 * changed at all, regardless of whether by reactions, rules, or constructs 216 * other than {@link InitialAssignment}. A value of <code>false</code> indicates that the 217 * species' quantity can be changed. (This is also a common value because 218 * the purpose of most simulations is precisely to calculate changes in 219 * species quantities.) In SBML Level 2, the attribute has a default 220 * value of <code>false</code>, while in SBML Level 3, it has no default. Note 221 * that the initial quantity of a species can be set by an 222 * {@link InitialAssignment} irrespective of the value of the 'constant' attribute. 223 <p> 224 * In practice, a 'boundaryCondition' value of <code>true</code> means a differential 225 * equation derived from the reaction definitions should not be generated 226 * for the species. However, the species' quantity may still be changed by 227 * {@link AssignmentRule}, {@link RateRule}, {@link AlgebraicRule}, {@link Event}, and {@link InitialAssignment} 228 * constructs if its 'constant' attribute is <code>false.</code> Conversely, if the 229 * species' 'constant' attribute is <code>true</code>, then its value cannot be 230 * changed by anything except {@link InitialAssignment}. 231 <p> 232 * A species having 'boundaryCondition'=<code>false</code> and 'constant'=<code>false</code> 233 * can appear as a product and/or reactant of one or more reactions in the 234 * model. If the species is a reactant or product of a reaction, it must 235 * <em>not</em> also appear as the target of any {@link AssignmentRule} or {@link RateRule} 236 * object in the model. If instead the species has 'boundaryCondition'= 237 * <code>false</code> and 'constant'=<code>true</code>, then it cannot appear as a reactant or 238 * product, or as the target of any {@link AssignmentRule}, {@link RateRule} or 239 * {@link EventAssignment} object in the model. 240 <p> 241 * Finally, it is worth clarifying that while the constant and 242 * boundaryCondition attributes restrict whether and how the species 243 * amount changes, the same is not true of a species' concentration. In 244 * SBML, the concentration of a species is a quantity that depends on the 245 * size of the compartment in which it is located. A compartment's size 246 * may change, and therefore, so can the concentration of a species even 247 * if the amount of the species remains unchanged. A species' concentration 248 * may therefore vary even if the {@link Species} object's constant attribute is 249 * set to <code>true</code> in a model. 250 <p> 251 * <h2>The conversionFactor attribute in SBML Level 3</h2> 252 <p> 253 * In SBML Level 3, {@link Species} has an additional optional attribute, 254 * 'conversionFactor', that defines a conversion factor that applies to a 255 * particular species. The value must be the identifier of a {@link Parameter} 256 * object instance defined in the model. That {@link Parameter} object must be a 257 * constant, meaning its 'constant' attribute must be set to <code>true.</code> 258 * If a given {@link Species} object definition defines a value for its 259 * 'conversionFactor' attribute, it takes precedence over any factor 260 * defined by the {@link Model} object's 'conversionFactor' attribute. 261 <p> 262 * The unit of measurement associated with a species' quantity can be 263 * different from the unit of extent of reactions in the model. SBML 264 * Level 3 avoids implicit unit conversions by providing an explicit 265 * way to indicate any unit conversion that might be required. The use of 266 * a conversion factor in computing the effects of reactions on a species' 267 * quantity is explained in detail in the SBML Level 3 specification 268 * document. Because the value of the 'conversionFactor' attribute is the 269 * identifier of a {@link Parameter} object, and because parameters can have units 270 * attached to them, the transformation from reaction extent units to 271 * species units can be completely specified using this approach. 272 <p> 273 * Note that the unit conversion factor is <strong>only applied when 274 * calculating the effect of a reaction on a species</strong>. It is not 275 * used in any rules or other SBML constructs that affect the species, and 276 * it is also not used when the value of the species is referenced in a 277 * mathematical expression. 278 <p> 279 * <h2>The speciesType attribute in SBML Level 2 Versions 2–4</h2> 280 <p> 281 * In SBML Level 2 Versions 2–4, each species in a model 282 * may optionally be designated as belonging to a particular species type. 283 * The optional attribute 'speciesType' is used to identify the species 284 * type of the chemical entities that make up the pool represented by the 285 * {@link Species} objects. The attribute's value must be the identifier of an 286 * existing {@link SpeciesType} object in the model. If the 'speciesType' 287 * attribute is not present on a particular species definition, it means 288 * the pool contains chemical entities of a type unique to that pool; in 289 * effect, a virtual species type is assumed for that species, and no other 290 * species can belong to that species type. The value of 'speciesType' 291 * attributes on species have no effect on the numerical interpretation of 292 * a model; simulators and other numerical analysis software may ignore 293 * 'speciesType' attributes. 294 <p> 295 * There can be only one species of a given species type in any given 296 * compartment of a model. More specifically, for all {@link Species} objects 297 * having a value for the 'speciesType' attribute, the pair 298 * <center> 299 * ('speciesType' attribute value, 'compartment' attribute value) 300 * </center> 301 <p> 302 * must be unique across the set of all {@link Species} object in a model. 303 <p> 304 * <h2>The spatialSizeUnits attribute in SBML Level 2 Versions 1–2</h2> 305 <p> 306 * In versions of SBML Level 2 before Version 3, the class 307 * {@link Species} included an attribute called 'spatialSizeUnits', which allowed 308 * explicitly setting the units of size for initial concentration. LibSBML 309 * retains this attribute for compatibility with older definitions of 310 * Level 2, but its use is strongly discouraged because many software 311 * tools do no properly interpret this unit declaration and it is 312 * incompatible with all SBML specifications after Level 2 313 * Version 3. 314 <p> 315 * <h2>Additional considerations for interpreting the numerical value of a species</h2> 316 <p> 317 * {@link Species} are unique in SBML in that they have a kind of duality: a 318 * species identifier may stand for either substance amount (meaning, a 319 * count of the number of individual entities) or a concentration or 320 * density (meaning, amount divided by a compartment size). The previous 321 * sections explain the meaning of a species identifier when it is 322 * referenced in a mathematical formula or in rules or other SBML 323 * constructs; however, it remains to specify what happens to a species 324 * when the compartment in which it is located changes in size. 325 <p> 326 * When a species definition has a 'hasOnlySubstanceUnits' attribute value 327 * of <code>false</code> and the size of the compartment in which the species is 328 * located changes, the default in SBML is to assume that it is the 329 * concentration that must be updated to account for the size change. This 330 * follows from the principle that, all other things held constant, if a 331 * compartment simply changes in size, the size change does not in itself 332 * cause an increase or decrease in the number of entities of any species 333 * in that compartment. In a sense, the default is that the <em>amount</em> of 334 * a species is preserved across compartment size changes. Upon such size 335 * changes, the value of the concentration or density must be recalculated 336 * from the simple relationship <em>concentration = amount / size</em> if 337 * the value of the concentration is needed (for example, if the species 338 * identifier appears in a mathematical formula or is otherwise referenced 339 * in an SBML construct). There is one exception: if the species' quantity 340 * is determined by an {@link AssignmentRule}, {@link RateRule}, {@link AlgebraicRule}, or an 341 * {@link EventAssignment} and the species has a 'hasOnlySubstanceUnits' attribute 342 * value of <code>false</code>, it means that the <em>concentration</em> is assigned 343 * by the rule or event; in that case, the <em>amount</em> must be 344 * calculated when the compartment size changes. (Events also require 345 * additional care in this situation, because an event with multiple 346 * assignments could conceivably reassign both a species quantity and a 347 * compartment size simultaneously. Please refer to the SBML 348 * specifications for the details.) 349 <p> 350 * Note that the above only matters if a species has a 351 * 'hasOnlySubstanceUnits' attribute value of <code>false</code>, meaning that the 352 * species identifier refers to a concentration wherever the identifier 353 * appears in a mathematical formula. If instead the attribute's value is 354 * <code>true</code>, then the identifier of the species <em>always</em> stands for 355 * an amount wherever it appears in a mathematical formula or is referenced 356 * by an SBML construct. In that case, there is never a question about 357 * whether an assignment or event is meant to affect the amount or 358 * concentration: it is always the amount. 359 <p> 360 * A particularly confusing situation can occur when the species has 361 * 'constant' attribute value of <code>true</code> in combination with a 362 * 'hasOnlySubstanceUnits' attribute value of <code>false.</code> Suppose this 363 * species is given a value for 'initialConcentration'. Does a 'constant' 364 * value of <code>true</code> mean that the concentration is held constant if the 365 * compartment size changes? No; it is still the amount that is kept 366 * constant across a compartment size change. The fact that the species 367 * was initialized using a concentration value is irrelevant. 368 */ 369 370 public class Species extends SBase { 371 private long swigCPtr; 372 Species(long cPtr, boolean cMemoryOwn)373 protected Species(long cPtr, boolean cMemoryOwn) 374 { 375 super(libsbmlJNI.Species_SWIGUpcast(cPtr), cMemoryOwn); 376 swigCPtr = cPtr; 377 } 378 getCPtr(Species obj)379 protected static long getCPtr(Species obj) 380 { 381 return (obj == null) ? 0 : obj.swigCPtr; 382 } 383 getCPtrAndDisown(Species obj)384 protected static long getCPtrAndDisown (Species obj) 385 { 386 long ptr = 0; 387 388 if (obj != null) 389 { 390 ptr = obj.swigCPtr; 391 obj.swigCMemOwn = false; 392 } 393 394 return ptr; 395 } 396 397 @SuppressWarnings("deprecation") finalize()398 protected void finalize() { 399 delete(); 400 } 401 delete()402 public synchronized void delete() { 403 if (swigCPtr != 0) { 404 if (swigCMemOwn) { 405 swigCMemOwn = false; 406 libsbmlJNI.delete_Species(swigCPtr); 407 } 408 swigCPtr = 0; 409 } 410 super.delete(); 411 } 412 413 414 /** 415 * Creates a new {@link Species} using the given SBML <code>level</code> and <code>version</code> 416 * values. 417 <p> 418 * @param level a long integer, the SBML Level to assign to this {@link Species}. 419 <p> 420 * @param version a long integer, the SBML Version to assign to this 421 * {@link Species}. 422 <p> 423 * <p> 424 * @throws SBMLConstructorException 425 * Thrown if the given <code>level</code> and <code>version</code> combination are invalid 426 * or if this object is incompatible with the given level and version. 427 <p> 428 * <p> 429 * @note Attempting to add an object to an {@link SBMLDocument} having a different 430 * combination of SBML Level, Version and XML namespaces than the object 431 * itself will result in an error at the time a caller attempts to make the 432 * addition. A parent object must have compatible Level, Version and XML 433 * namespaces. (Strictly speaking, a parent may also have more XML 434 * namespaces than a child, but the reverse is not permitted.) The 435 * restriction is necessary to ensure that an SBML model has a consistent 436 * overall structure. This requires callers to manage their objects 437 * carefully, but the benefit is increased flexibility in how models can be 438 * created by permitting callers to create objects bottom-up if desired. In 439 * situations where objects are not yet attached to parents (e.g., 440 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 441 * libSBML determine such things as whether it is valid to assign a 442 * particular value to an attribute. 443 */ public Species(long level, long version)444 Species(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 445 this(libsbmlJNI.new_Species__SWIG_0(level, version), true); 446 } 447 448 449 /** 450 * Creates a new {@link Species} using the given {@link SBMLNamespaces} object 451 * <code>sbmlns</code>. 452 <p> 453 * <p> 454 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces 455 * information. It is used to communicate the SBML Level, Version, and (in 456 * Level 3) packages used in addition to SBML Level 3 Core. A 457 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an 458 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object 459 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments. 460 <p> 461 * It is worth emphasizing that although this constructor does not take 462 * an identifier argument, in SBML Level 2 and beyond, the 'id' 463 * (identifier) attribute of a {@link Species} is required to have a value. 464 * Thus, callers are cautioned to assign a value after calling this 465 * constructor. Setting the identifier can be accomplished using the 466 * method {@link Species#setId(String)}. 467 <p> 468 * @param sbmlns an {@link SBMLNamespaces} object. 469 <p> 470 * <p> 471 * @throws SBMLConstructorException 472 * Thrown if the given <code>sbmlns</code> is inconsistent or incompatible 473 * with this object. 474 <p> 475 * <p> 476 * @note Attempting to add an object to an {@link SBMLDocument} having a different 477 * combination of SBML Level, Version and XML namespaces than the object 478 * itself will result in an error at the time a caller attempts to make the 479 * addition. A parent object must have compatible Level, Version and XML 480 * namespaces. (Strictly speaking, a parent may also have more XML 481 * namespaces than a child, but the reverse is not permitted.) The 482 * restriction is necessary to ensure that an SBML model has a consistent 483 * overall structure. This requires callers to manage their objects 484 * carefully, but the benefit is increased flexibility in how models can be 485 * created by permitting callers to create objects bottom-up if desired. In 486 * situations where objects are not yet attached to parents (e.g., 487 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 488 * libSBML determine such things as whether it is valid to assign a 489 * particular value to an attribute. 490 */ public Species(SBMLNamespaces sbmlns)491 Species(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException { 492 this(libsbmlJNI.new_Species__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true); 493 } 494 495 496 /** 497 * Copy constructor; creates a copy of this {@link Species} object. 498 <p> 499 * @param orig the object to copy. 500 */ public Species(Species orig)501 Species(Species orig) throws org.sbml.libsbml.SBMLConstructorException { 502 this(libsbmlJNI.new_Species__SWIG_2(Species.getCPtr(orig), orig), true); 503 } 504 505 506 /** 507 * Creates and returns a deep copy of this {@link Species} object. 508 <p> 509 * @return the (deep) copy of this {@link Species} object. 510 */ public cloneObject()511 Species cloneObject() { 512 long cPtr = libsbmlJNI.Species_cloneObject(swigCPtr, this); 513 return (cPtr == 0) ? null : new Species(cPtr, true); 514 } 515 516 517 /** 518 * Initializes the fields of this {@link Species} object to 'typical' defaults 519 * values. 520 <p> 521 * The SBML {@link Species} component has slightly different aspects and 522 * default attribute values in different SBML Levels and Versions. 523 * This method sets the values to certain common defaults, based 524 * mostly on what they are in SBML Level 2. Specifically: 525 * <ul> 526 * <li> Sets 'boundaryCondition' to <code>false</code> 527 * <li> Sets 'constant' to <code>false</code> 528 * <li> sets 'hasOnlySubstanceUnits' to <code>false</code> 529 * <li> (Applies to Level 3 models only) Sets attribute 'substanceUnits' to <code>mole</code> 530 * </ul> 531 */ public initDefaults()532 void initDefaults() { 533 libsbmlJNI.Species_initDefaults(swigCPtr, this); 534 } 535 536 537 /** 538 * Returns the value of the 'id' attribute of this {@link Species}. 539 <p> 540 * @note Because of the inconsistent behavior of this function with 541 * respect to assignments and rules, it is now recommended to 542 * use the getIdAttribute() function instead. 543 <p> 544 * <p> 545 * The identifier given by an object's 'id' attribute value 546 * is used to identify the object within the SBML model definition. 547 * Other objects can refer to the component using this identifier. The 548 * data type of 'id' is always <code>SId</code> or a type derived 549 * from that, such as <code>UnitSId</code>, depending on the object in 550 * question. All data types are defined as follows: 551 * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'> 552 * letter .= 'a'..'z','A'..'Z' 553 * digit .= '0'..'9' 554 * idChar .= letter | digit | '_' 555 * SId .= ( letter | '_' ) idChar* 556 * </pre> 557 * The characters <code>(</code> and <code>)</code> are used for grouping, 558 * the character <code>*</code> 'zero or more times', and the character 559 * <code>|</code> indicates logical 'or'. The equality of SBML identifiers 560 * is determined by an exact character sequence match; i.e., comparisons must 561 * be performed in a case-sensitive manner. This applies to all uses of 562 * <code>SId</code>, <code>SIdRef</code>, and derived types. 563 <p> 564 * Users need to be aware of some important API issues that are the result of 565 * the history of SBML and libSBML. Prior to SBML Level 3 566 * Version 2, SBML defined 'id' and 'name' attributes on only a subset 567 * of SBML objects. To simplify the work of programmers, libSBML's API 568 * provided get, set, check, and unset on the {@link SBase} object class itself 569 * instead of on individual subobject classes. This made the 570 * get/set/etc. methods uniformly available on all objects in the libSBML 571 * API. LibSBML simply returned empty strings or otherwise did not act when 572 * the methods were applied to SBML objects that were not defined by the SBML 573 * specification to have 'id' or 'name' attributes. Additional complications 574 * arose with the rule and assignment objects: {@link InitialAssignment}, 575 * {@link EventAssignment}, {@link AssignmentRule}, and {@link RateRule}. In early versions of SBML, 576 * the rule object hierarchy was different, and in addition, then as now, 577 * they possess different attributes: 'variable' (for the rules and event 578 * assignments), 'symbol' (for initial assignments), or neither (for 579 * algebraic rules). Prior to SBML Level 3 Version 2, getId() 580 * would always return an empty string, and isSetId() would always return 581 * <code>false</code> for objects of these classes. 582 <p> 583 * With the addition of 'id' and 'name' attributes on {@link SBase} in Level 3 584 * Version 2, it became necessary to introduce a new way to interact 585 * with the attributes more consistently in libSBML to avoid breaking 586 * backward compatibility in the behavior of the original 'id' methods. For 587 * this reason, libSBML provides four functions (getIdAttribute(), 588 * setIdAttribute(String), isSetIdAttribute(), and 589 * unsetIdAttribute()) that always act on the actual 'id' attribute inherited 590 * from {@link SBase}, regardless of the object's type. <strong>These new methods 591 * should be used instead of the older getId()/setId()/etc. methods</strong> 592 * unless the old behavior is somehow necessary. Regardless of the Level and 593 * Version of the SBML, these functions allow client applications to use more 594 * generalized code in some situations (for instance, when manipulating 595 * objects that are all known to have identifiers). If the object in 596 * question does not posess an 'id' attribute according to the SBML 597 * specification for the Level and Version in use, libSBML will not allow the 598 * identifier to be set, nor will it read or write 'id' attributes for those 599 * objects. 600 <p> 601 * @return the id of this {@link Species}. 602 <p> 603 * @see #getIdAttribute() 604 * @see #setIdAttribute(String sid) 605 * @see #isSetIdAttribute() 606 * @see #unsetIdAttribute() 607 */ public getId()608 String getId() { 609 return libsbmlJNI.Species_getId(swigCPtr, this); 610 } 611 612 613 /** 614 * Returns the value of the 'name' attribute of this {@link Species} object. 615 <p> 616 * <p> 617 * <p> 618 * In SBML Level 3 Version 2, the 'id' and 'name' attributes were 619 * moved to {@link SBase} directly, instead of being defined individually for many 620 * (but not all) objects. LibSBML has for a long time provided functions 621 * defined on {@link SBase} itself to get, set, and unset those attributes, which 622 * would fail or otherwise return empty strings if executed on any object 623 * for which those attributes were not defined. Now that all {@link SBase} objects 624 * define those attributes, those functions now succeed for any object with 625 * the appropriate level and version. 626 <p> 627 * The 'name' attribute is 628 * optional and is not intended to be used for cross-referencing purposes 629 * within a model. Its purpose instead is to provide a human-readable 630 * label for the component. The data type of 'name' is the type 631 * <code>string</code> defined in XML Schema. SBML imposes no 632 * restrictions as to the content of 'name' attributes beyond those 633 * restrictions defined by the <code>string</code> type in XML Schema. 634 <p> 635 * The recommended practice for handling 'name' is as follows. If a 636 * software tool has the capability for displaying the content of 'name' 637 * attributes, it should display this content to the user as a 638 * component's label instead of the component's 'id'. If the user 639 * interface does not have this capability (e.g., because it cannot 640 * display or use special characters in symbol names), or if the 'name' 641 * attribute is missing on a given component, then the user interface 642 * should display the value of the 'id' attribute instead. (Script 643 * language interpreters are especially likely to display 'id' instead of 644 * 'name'.) 645 <p> 646 * As a consequence of the above, authors of systems that automatically 647 * generate the values of 'id' attributes should be aware some systems 648 * may display the 'id''s to the user. Authors therefore may wish to 649 * take some care to have their software create 'id' values that are: (a) 650 * reasonably easy for humans to type and read; and (b) likely to be 651 * meaningful, for example by making the 'id' attribute be an abbreviated 652 * form of the name attribute value. 653 <p> 654 * An additional point worth mentioning is although there are 655 * restrictions on the uniqueness of 'id' values, there are no 656 * restrictions on the uniqueness of 'name' values in a model. This 657 * allows software applications leeway in assigning component identifiers. 658 <p> 659 * Regardless of the level and version of the SBML, these functions allow 660 * client applications to use more generalized code in some situations 661 * (for instance, when manipulating objects that are all known to have 662 * names). If the object in question does not posess a 'name' attribute 663 * according to the SBML specification for the Level and Version in use, 664 * libSBML will not allow the name to be set, nor will it read or 665 * write 'name' attributes for those objects. 666 <p> 667 * @return the name of this SBML object, or the empty string if not set or unsettable. 668 <p> 669 * @see #getIdAttribute() 670 * @see #isSetName() 671 * @see #setName(String sid) 672 * @see #unsetName() 673 */ public getName()674 String getName() { 675 return libsbmlJNI.Species_getName(swigCPtr, this); 676 } 677 678 679 /** 680 * Get the type of this {@link Species} object object. 681 <p> 682 * @return the value of the 'speciesType' attribute of this 683 * {@link Species} as a string. 684 <p> 685 * @note The 'speciesType' attribute is only available in SBML 686 * Level 2 Versions 2–4. 687 */ public getSpeciesType()688 String getSpeciesType() { 689 return libsbmlJNI.Species_getSpeciesType(swigCPtr, this); 690 } 691 692 693 /** 694 * Get the compartment in which this species is located. 695 <p> 696 * The compartment is designated by its identifier. 697 <p> 698 * @return the value of the 'compartment' attribute of this {@link Species} 699 * object, as a string. 700 */ public getCompartment()701 String getCompartment() { 702 return libsbmlJNI.Species_getCompartment(swigCPtr, this); 703 } 704 705 706 /** 707 * Get the value of the 'initialAmount' attribute. 708 <p> 709 * @return the initialAmount of this {@link Species}, as a floating point number. 710 */ public getInitialAmount()711 double getInitialAmount() { 712 return libsbmlJNI.Species_getInitialAmount(swigCPtr, this); 713 } 714 715 716 /** 717 * Get the value of the 'initialConcentration' attribute. 718 <p> 719 * @return the initialConcentration of this {@link Species},, as a floating point 720 * number. 721 <p> 722 * @note The attribute 'initialConcentration' is only available in SBML 723 * Level 2 and 3. It does not exist on {@link Species} in Level 1. 724 */ public getInitialConcentration()725 double getInitialConcentration() { 726 return libsbmlJNI.Species_getInitialConcentration(swigCPtr, this); 727 } 728 729 730 /** 731 * Get the value of the 'substanceUnits' attribute. 732 <p> 733 * @return the value of the 'substanceUnits' attribute of this {@link Species}, 734 * as a string. An empty string indicates that no units have been 735 * assigned. 736 <p> 737 * <p> 738 * @note There is an important distinction to be made between <em>no units 739 * assigned</em>, and assuming a value without units has any specific unit 740 * such as <code>dimensionless</code>. In SBML, default units are never 741 * attributed to numbers, and numbers without units are not automatically 742 * assumed to have the unit <code>dimensionless</code>. Please consult the 743 * relevant SBML specification document for a more in-depth explanation of 744 * this topic and the SBML unit system. 745 <p> 746 * @see #isSetSubstanceUnits() 747 * @see #setSubstanceUnits(String sid) 748 */ public getSubstanceUnits()749 String getSubstanceUnits() { 750 return libsbmlJNI.Species_getSubstanceUnits(swigCPtr, this); 751 } 752 753 754 /** 755 * Get the value of the 'spatialSizeUnits' attribute. 756 <p> 757 * @return the value of the 'spatialSizeUnits' attribute of this {@link Species} 758 * object, as a string. 759 <p> 760 * <p> 761 * @warning <span class='warning'>In versions of SBML Level 2 before 762 * Version 3, the class {@link Species} included an attribute called 763 * 'spatialSizeUnits', which allowed explicitly setting the units of size for 764 * initial concentration. This attribute was removed in SBML Level 2 765 * Version 3. LibSBML retains this attribute for compatibility with 766 * older definitions of Level 2, but its use is strongly discouraged 767 * because it is incompatible with levels and versions of SBML beyond 768 * Level 2 Version 2.</span> 769 */ public getSpatialSizeUnits()770 String getSpatialSizeUnits() { 771 return libsbmlJNI.Species_getSpatialSizeUnits(swigCPtr, this); 772 } 773 774 775 /** 776 * Get the value of the 'units' attribute. 777 <p> 778 * @return the units of this {@link Species} (L1 only). 779 <p> 780 * <p> 781 * @note The 'units' attribute is defined only in SBML Level 1. In 782 * SBML Level 2 and Level 3, it has been replaced by a 783 * combination of 'substanceUnits' and the units of the {@link Compartment} 784 * object in which a species is located. In SBML Level 2 785 * Versions 1–2, an additional attribute 'spatialSizeUnits' 786 * helps determine the units of the species quantity, but this attribute 787 * was removed in later versions of SBML Level 2. 788 */ public getUnits()789 String getUnits() { 790 return libsbmlJNI.Species_getUnits(swigCPtr, this); 791 } 792 793 794 /** 795 * Get the value of the 'hasOnlySubstanceUnits' attribute. 796 <p> 797 * @return <code>true</code> if this {@link Species}' 'hasOnlySubstanceUnits' attribute 798 * value is <code>true</code>, <code>false</code> otherwise. 799 <p> 800 * @note The 'hasOnlySubstanceUnits' attribute does not exist in SBML 801 * Level 1. 802 */ public getHasOnlySubstanceUnits()803 boolean getHasOnlySubstanceUnits() { 804 return libsbmlJNI.Species_getHasOnlySubstanceUnits(swigCPtr, this); 805 } 806 807 808 /** 809 * Get the value of the 'boundaryCondition' attribute. 810 <p> 811 * @return <code>true</code> if this {@link Species}' 'boundaryCondition' attribute value 812 * is <code>true</code>, <code>false</code> otherwise. 813 */ public getBoundaryCondition()814 boolean getBoundaryCondition() { 815 return libsbmlJNI.Species_getBoundaryCondition(swigCPtr, this); 816 } 817 818 819 /** 820 * Get the value of the 'charge' attribute. 821 <p> 822 * @return the charge of this {@link Species} object. 823 <p> 824 * <p> 825 * @note Beginning in SBML Level 2 Version 2, the 'charge' 826 * attribute on {@link Species} is deprecated and in SBML Level 3 it does 827 * not exist at all. Its use strongly discouraged. Its presence is 828 * considered a misfeature in earlier definitions of SBML because its 829 * implications for the mathematics of a model were never defined, and in 830 * any case, no known modeling system ever used it. Instead, models take 831 * account of charge values directly in their definitions of species by 832 * (for example) having separate species identities for the charged and 833 * uncharged versions of the same species. This allows the condition to 834 * affect model mathematics directly. LibSBML retains this method for 835 * easier compatibility with SBML Level 1. 836 */ public getCharge()837 int getCharge() { 838 return libsbmlJNI.Species_getCharge(swigCPtr, this); 839 } 840 841 842 /** 843 * Get the value of the 'constant' attribute. 844 <p> 845 * @return <code>true</code> if this {@link Species}'s 'constant' attribute value is 846 * <code>true</code>, <code>false</code> otherwise. 847 <p> 848 * @note The attribute 'constant' is only available in SBML Levels 2 849 * and 3. It does not exist on {@link Species} in Level 1. 850 */ public getConstant()851 boolean getConstant() { 852 return libsbmlJNI.Species_getConstant(swigCPtr, this); 853 } 854 855 856 /** 857 * Get the value of the 'conversionFactor' attribute. 858 <p> 859 * @return the conversionFactor of this {@link Species}, as a string. 860 <p> 861 * @note The 'conversionFactor' attribute was introduced in SBML 862 * Level 3. It does not exist on {@link Species} in SBML Levels 1 863 * and 2. 864 */ public getConversionFactor()865 String getConversionFactor() { 866 return libsbmlJNI.Species_getConversionFactor(swigCPtr, this); 867 } 868 869 870 /** 871 * Predicate returning <code>true</code> if this 872 * {@link Species} object's 'id' attribute is set. 873 <p> 874 * <p> 875 * <p> 876 * The identifier given by an object's 'id' attribute value 877 * is used to identify the object within the SBML model definition. 878 * Other objects can refer to the component using this identifier. The 879 * data type of 'id' is always <code>SId</code> or a type derived 880 * from that, such as <code>UnitSId</code>, depending on the object in 881 * question. All data types are defined as follows: 882 * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'> 883 * letter .= 'a'..'z','A'..'Z' 884 * digit .= '0'..'9' 885 * idChar .= letter | digit | '_' 886 * SId .= ( letter | '_' ) idChar* 887 * </pre> 888 * The characters <code>(</code> and <code>)</code> are used for grouping, 889 * the character <code>*</code> 'zero or more times', and the character 890 * <code>|</code> indicates logical 'or'. The equality of SBML identifiers 891 * is determined by an exact character sequence match; i.e., comparisons must 892 * be performed in a case-sensitive manner. This applies to all uses of 893 * <code>SId</code>, <code>SIdRef</code>, and derived types. 894 <p> 895 * Users need to be aware of some important API issues that are the result of 896 * the history of SBML and libSBML. Prior to SBML Level 3 897 * Version 2, SBML defined 'id' and 'name' attributes on only a subset 898 * of SBML objects. To simplify the work of programmers, libSBML's API 899 * provided get, set, check, and unset on the {@link SBase} object class itself 900 * instead of on individual subobject classes. This made the 901 * get/set/etc. methods uniformly available on all objects in the libSBML 902 * API. LibSBML simply returned empty strings or otherwise did not act when 903 * the methods were applied to SBML objects that were not defined by the SBML 904 * specification to have 'id' or 'name' attributes. Additional complications 905 * arose with the rule and assignment objects: {@link InitialAssignment}, 906 * {@link EventAssignment}, {@link AssignmentRule}, and {@link RateRule}. In early versions of SBML, 907 * the rule object hierarchy was different, and in addition, then as now, 908 * they possess different attributes: 'variable' (for the rules and event 909 * assignments), 'symbol' (for initial assignments), or neither (for 910 * algebraic rules). Prior to SBML Level 3 Version 2, getId() 911 * would always return an empty string, and isSetId() would always return 912 * <code>false</code> for objects of these classes. 913 <p> 914 * With the addition of 'id' and 'name' attributes on {@link SBase} in Level 3 915 * Version 2, it became necessary to introduce a new way to interact 916 * with the attributes more consistently in libSBML to avoid breaking 917 * backward compatibility in the behavior of the original 'id' methods. For 918 * this reason, libSBML provides four functions (getIdAttribute(), 919 * setIdAttribute(String), isSetIdAttribute(), and 920 * unsetIdAttribute()) that always act on the actual 'id' attribute inherited 921 * from {@link SBase}, regardless of the object's type. <strong>These new methods 922 * should be used instead of the older getId()/setId()/etc. methods</strong> 923 * unless the old behavior is somehow necessary. Regardless of the Level and 924 * Version of the SBML, these functions allow client applications to use more 925 * generalized code in some situations (for instance, when manipulating 926 * objects that are all known to have identifiers). If the object in 927 * question does not posess an 'id' attribute according to the SBML 928 * specification for the Level and Version in use, libSBML will not allow the 929 * identifier to be set, nor will it read or write 'id' attributes for those 930 * objects. 931 <p> 932 * @return <code>true</code> if the 'id' attribute of this SBML object is 933 * set, <code>false</code> otherwise. 934 <p> 935 * @note Because of the inconsistent behavior of this function with 936 * respect to assignments and rules, it is recommended that callers 937 * use isSetIdAttribute() instead. 938 <p> 939 * @see #getIdAttribute() 940 * @see #setIdAttribute(String sid) 941 * @see #unsetIdAttribute() 942 * @see #isSetIdAttribute() 943 */ public isSetId()944 boolean isSetId() { 945 return libsbmlJNI.Species_isSetId(swigCPtr, this); 946 } 947 948 949 /** 950 * Predicate returning <code>true</code> if this 951 * {@link Species} object's 'name' attribute is set. 952 <p> 953 * <p> 954 * <p> 955 * In SBML Level 3 Version 2, the 'id' and 'name' attributes were 956 * moved to {@link SBase} directly, instead of being defined individually for many 957 * (but not all) objects. LibSBML has for a long time provided functions 958 * defined on {@link SBase} itself to get, set, and unset those attributes, which 959 * would fail or otherwise return empty strings if executed on any object 960 * for which those attributes were not defined. Now that all {@link SBase} objects 961 * define those attributes, those functions now succeed for any object with 962 * the appropriate level and version. 963 <p> 964 * The 'name' attribute is 965 * optional and is not intended to be used for cross-referencing purposes 966 * within a model. Its purpose instead is to provide a human-readable 967 * label for the component. The data type of 'name' is the type 968 * <code>string</code> defined in XML Schema. SBML imposes no 969 * restrictions as to the content of 'name' attributes beyond those 970 * restrictions defined by the <code>string</code> type in XML Schema. 971 <p> 972 * The recommended practice for handling 'name' is as follows. If a 973 * software tool has the capability for displaying the content of 'name' 974 * attributes, it should display this content to the user as a 975 * component's label instead of the component's 'id'. If the user 976 * interface does not have this capability (e.g., because it cannot 977 * display or use special characters in symbol names), or if the 'name' 978 * attribute is missing on a given component, then the user interface 979 * should display the value of the 'id' attribute instead. (Script 980 * language interpreters are especially likely to display 'id' instead of 981 * 'name'.) 982 <p> 983 * As a consequence of the above, authors of systems that automatically 984 * generate the values of 'id' attributes should be aware some systems 985 * may display the 'id''s to the user. Authors therefore may wish to 986 * take some care to have their software create 'id' values that are: (a) 987 * reasonably easy for humans to type and read; and (b) likely to be 988 * meaningful, for example by making the 'id' attribute be an abbreviated 989 * form of the name attribute value. 990 <p> 991 * An additional point worth mentioning is although there are 992 * restrictions on the uniqueness of 'id' values, there are no 993 * restrictions on the uniqueness of 'name' values in a model. This 994 * allows software applications leeway in assigning component identifiers. 995 <p> 996 * Regardless of the level and version of the SBML, these functions allow 997 * client applications to use more generalized code in some situations 998 * (for instance, when manipulating objects that are all known to have 999 * names). If the object in question does not posess a 'name' attribute 1000 * according to the SBML specification for the Level and Version in use, 1001 * libSBML will not allow the name to be set, nor will it read or 1002 * write 'name' attributes for those objects. 1003 <p> 1004 * @return <code>true</code> if the 'name' attribute of this SBML object is 1005 * set, <code>false</code> otherwise. 1006 <p> 1007 * @see #getName() 1008 * @see #setName(String sid) 1009 * @see #unsetName() 1010 */ public isSetName()1011 boolean isSetName() { 1012 return libsbmlJNI.Species_isSetName(swigCPtr, this); 1013 } 1014 1015 1016 /** 1017 * Predicate returning <code>true</code> if this {@link Species} object's 1018 * 'speciesType' attribute is set. 1019 <p> 1020 * @return <code>true</code> if the 'speciesType' attribute of this {@link Species} is 1021 * set, <code>false</code> otherwise. 1022 <p> 1023 * @note The 'speciesType' attribute is only available in SBML 1024 * Level 2 Versions 2–4. 1025 */ public isSetSpeciesType()1026 boolean isSetSpeciesType() { 1027 return libsbmlJNI.Species_isSetSpeciesType(swigCPtr, this); 1028 } 1029 1030 1031 /** 1032 * Predicate returning <code>true</code> if this 1033 * {@link Species} object's 'compartment' attribute is set. 1034 <p> 1035 * @return <code>true</code> if the 'compartment' attribute of this {@link Species} is 1036 * set, <code>false</code> otherwise. 1037 */ public isSetCompartment()1038 boolean isSetCompartment() { 1039 return libsbmlJNI.Species_isSetCompartment(swigCPtr, this); 1040 } 1041 1042 1043 /** 1044 * Predicate returning <code>true</code> if this 1045 * {@link Species} object's 'initialAmount' attribute is set. 1046 <p> 1047 * @return <code>true</code> if the 'initialAmount' attribute of this {@link Species} is 1048 * set, <code>false</code> otherwise. 1049 <p> 1050 * @note In SBML Level 1, {@link Species}' 'initialAmount' is required and 1051 * therefore <em>should always be set</em>. (However, in Level 1, the 1052 * attribute has no default value either, so this method will not return 1053 * <code>true</code> until a value has been assigned.) In SBML Level 2, 1054 * 'initialAmount' is optional and as such may or may not be set. 1055 */ public isSetInitialAmount()1056 boolean isSetInitialAmount() { 1057 return libsbmlJNI.Species_isSetInitialAmount(swigCPtr, this); 1058 } 1059 1060 1061 /** 1062 * Predicate returning <code>true</code> if this 1063 * {@link Species} object's 'initialConcentration' attribute is set. 1064 <p> 1065 * @return <code>true</code> if the 'initialConcentration' attribute of this {@link Species} is 1066 * set, <code>false</code> otherwise. 1067 <p> 1068 * @note The attribute 'initialConcentration' is only available in SBML 1069 * Level 2 and 3. It does not exist on {@link Species} in Level 1. 1070 */ public isSetInitialConcentration()1071 boolean isSetInitialConcentration() { 1072 return libsbmlJNI.Species_isSetInitialConcentration(swigCPtr, this); 1073 } 1074 1075 1076 /** 1077 * Predicate returning <code>true</code> if this 1078 * {@link Species} object's 'substanceUnits' attribute is set. 1079 <p> 1080 * @return <code>true</code> if the 'substanceUnits' attribute of this {@link Species} is 1081 * set, <code>false</code> otherwise. 1082 */ public isSetSubstanceUnits()1083 boolean isSetSubstanceUnits() { 1084 return libsbmlJNI.Species_isSetSubstanceUnits(swigCPtr, this); 1085 } 1086 1087 1088 /** 1089 * Predicate returning <code>true</code> if this 1090 * {@link Species} object's 'spatialSizeUnits' attribute is set. 1091 <p> 1092 * @return <code>true</code> if the 'spatialSizeUnits' attribute of this {@link Species} is 1093 * set, <code>false</code> otherwise. 1094 <p> 1095 * <p> 1096 * @warning <span class='warning'>In versions of SBML Level 2 before 1097 * Version 3, the class {@link Species} included an attribute called 1098 * 'spatialSizeUnits', which allowed explicitly setting the units of size for 1099 * initial concentration. This attribute was removed in SBML Level 2 1100 * Version 3. LibSBML retains this attribute for compatibility with 1101 * older definitions of Level 2, but its use is strongly discouraged 1102 * because it is incompatible with levels and versions of SBML beyond 1103 * Level 2 Version 2.</span> 1104 */ public isSetSpatialSizeUnits()1105 boolean isSetSpatialSizeUnits() { 1106 return libsbmlJNI.Species_isSetSpatialSizeUnits(swigCPtr, this); 1107 } 1108 1109 1110 /** 1111 * Predicate returning <code>true</code> if 1112 * this {@link Species} object's 'units' attribute is set. 1113 <p> 1114 * @return <code>true</code> if the 'units' attribute of this {@link Species} is 1115 * set, <code>false</code> otherwise. 1116 */ public isSetUnits()1117 boolean isSetUnits() { 1118 return libsbmlJNI.Species_isSetUnits(swigCPtr, this); 1119 } 1120 1121 1122 /** 1123 * Predicate returning <code>true</code> if this 1124 * {@link Species} object's 'charge' attribute is set. 1125 <p> 1126 * @return <code>true</code> if the 'charge' attribute of this {@link Species} is 1127 * set, <code>false</code> otherwise. 1128 <p> 1129 * <p> 1130 * @note Beginning in SBML Level 2 Version 2, the 'charge' 1131 * attribute on {@link Species} is deprecated and in SBML Level 3 it does 1132 * not exist at all. Its use strongly discouraged. Its presence is 1133 * considered a misfeature in earlier definitions of SBML because its 1134 * implications for the mathematics of a model were never defined, and in 1135 * any case, no known modeling system ever used it. Instead, models take 1136 * account of charge values directly in their definitions of species by 1137 * (for example) having separate species identities for the charged and 1138 * uncharged versions of the same species. This allows the condition to 1139 * affect model mathematics directly. LibSBML retains this method for 1140 * easier compatibility with SBML Level 1. 1141 */ public isSetCharge()1142 boolean isSetCharge() { 1143 return libsbmlJNI.Species_isSetCharge(swigCPtr, this); 1144 } 1145 1146 1147 /** 1148 * Predicate returning <code>true</code> if this 1149 * {@link Species} object's 'conversionFactor' attribute is set. 1150 <p> 1151 * @return <code>true</code> if the 'conversionFactor' attribute of this {@link Species} is 1152 * set, <code>false</code> otherwise. 1153 <p> 1154 * @note The 'conversionFactor' attribute was introduced in SBML 1155 * Level 3. It does not exist on {@link Species} in SBML Levels 1 1156 * and 2. 1157 */ public isSetConversionFactor()1158 boolean isSetConversionFactor() { 1159 return libsbmlJNI.Species_isSetConversionFactor(swigCPtr, this); 1160 } 1161 1162 1163 /** 1164 * Predicate returning <code>true</code> if this 1165 * {@link Species} object's 'boundaryCondition' attribute is set. 1166 <p> 1167 * @return <code>true</code> if the 'boundaryCondition' attribute of this {@link Species} is 1168 * set, <code>false</code> otherwise. 1169 */ public isSetBoundaryCondition()1170 boolean isSetBoundaryCondition() { 1171 return libsbmlJNI.Species_isSetBoundaryCondition(swigCPtr, this); 1172 } 1173 1174 1175 /** 1176 * Predicate returning <code>true</code> if this 1177 * {@link Species} object's 'hasOnlySubstanceUnits' attribute is set. 1178 <p> 1179 * @return <code>true</code> if the 'hasOnlySubstanceUnits' attribute of this {@link Species} is 1180 * set, <code>false</code> otherwise. 1181 <p> 1182 * @note The 'hasOnlySubstanceUnits' attribute does not exist in SBML 1183 * Level 1. 1184 */ public isSetHasOnlySubstanceUnits()1185 boolean isSetHasOnlySubstanceUnits() { 1186 return libsbmlJNI.Species_isSetHasOnlySubstanceUnits(swigCPtr, this); 1187 } 1188 1189 1190 /** 1191 * Predicate returning <code>true</code> if this 1192 * {@link Species} object's 'constant' attribute is set. 1193 <p> 1194 * @return <code>true</code> if the 'constant' attribute of this {@link Species} is 1195 * set, <code>false</code> otherwise. 1196 <p> 1197 * @note The attribute 'constant' is only available in SBML Levels 2 1198 * and 3. It does not exist on {@link Species} in Level 1. 1199 */ public isSetConstant()1200 boolean isSetConstant() { 1201 return libsbmlJNI.Species_isSetConstant(swigCPtr, this); 1202 } 1203 1204 1205 /** 1206 * Sets the value of the 'id' attribute of this {@link Species}. 1207 <p> 1208 * <p> 1209 * The string <code>sid</code> is copied. 1210 <p> 1211 * <p> 1212 * The identifier given by an object's 'id' attribute value 1213 * is used to identify the object within the SBML model definition. 1214 * Other objects can refer to the component using this identifier. The 1215 * data type of 'id' is always <code>SId</code> or a type derived 1216 * from that, such as <code>UnitSId</code>, depending on the object in 1217 * question. All data types are defined as follows: 1218 * <pre style='margin-left: 2em; border: none; font-weight: bold; color: black'> 1219 * letter .= 'a'..'z','A'..'Z' 1220 * digit .= '0'..'9' 1221 * idChar .= letter | digit | '_' 1222 * SId .= ( letter | '_' ) idChar* 1223 * </pre> 1224 * The characters <code>(</code> and <code>)</code> are used for grouping, 1225 * the character <code>*</code> 'zero or more times', and the character 1226 * <code>|</code> indicates logical 'or'. The equality of SBML identifiers 1227 * is determined by an exact character sequence match; i.e., comparisons must 1228 * be performed in a case-sensitive manner. This applies to all uses of 1229 * <code>SId</code>, <code>SIdRef</code>, and derived types. 1230 <p> 1231 * Users need to be aware of some important API issues that are the result of 1232 * the history of SBML and libSBML. Prior to SBML Level 3 1233 * Version 2, SBML defined 'id' and 'name' attributes on only a subset 1234 * of SBML objects. To simplify the work of programmers, libSBML's API 1235 * provided get, set, check, and unset on the {@link SBase} object class itself 1236 * instead of on individual subobject classes. This made the 1237 * get/set/etc. methods uniformly available on all objects in the libSBML 1238 * API. LibSBML simply returned empty strings or otherwise did not act when 1239 * the methods were applied to SBML objects that were not defined by the SBML 1240 * specification to have 'id' or 'name' attributes. Additional complications 1241 * arose with the rule and assignment objects: {@link InitialAssignment}, 1242 * {@link EventAssignment}, {@link AssignmentRule}, and {@link RateRule}. In early versions of SBML, 1243 * the rule object hierarchy was different, and in addition, then as now, 1244 * they possess different attributes: 'variable' (for the rules and event 1245 * assignments), 'symbol' (for initial assignments), or neither (for 1246 * algebraic rules). Prior to SBML Level 3 Version 2, getId() 1247 * would always return an empty string, and isSetId() would always return 1248 * <code>false</code> for objects of these classes. 1249 <p> 1250 * With the addition of 'id' and 'name' attributes on {@link SBase} in Level 3 1251 * Version 2, it became necessary to introduce a new way to interact 1252 * with the attributes more consistently in libSBML to avoid breaking 1253 * backward compatibility in the behavior of the original 'id' methods. For 1254 * this reason, libSBML provides four functions (getIdAttribute(), 1255 * setIdAttribute(String), isSetIdAttribute(), and 1256 * unsetIdAttribute()) that always act on the actual 'id' attribute inherited 1257 * from {@link SBase}, regardless of the object's type. <strong>These new methods 1258 * should be used instead of the older getId()/setId()/etc. methods</strong> 1259 * unless the old behavior is somehow necessary. Regardless of the Level and 1260 * Version of the SBML, these functions allow client applications to use more 1261 * generalized code in some situations (for instance, when manipulating 1262 * objects that are all known to have identifiers). If the object in 1263 * question does not posess an 'id' attribute according to the SBML 1264 * specification for the Level and Version in use, libSBML will not allow the 1265 * identifier to be set, nor will it read or write 'id' attributes for those 1266 * objects. 1267 <p> 1268 * @param sid the string to use as the identifier of this object. 1269 <p> 1270 * <p> 1271 * @return integer value indicating success/failure of the 1272 * function. The possible values 1273 * returned by this function are: 1274 * <ul> 1275 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1276 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 1277 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 1278 * 1279 * </ul> <p> 1280 * @see #getIdAttribute() 1281 * @see #setIdAttribute(String sid) 1282 * @see #isSetIdAttribute() 1283 * @see #unsetIdAttribute() 1284 */ public setId(String sid)1285 int setId(String sid) { 1286 return libsbmlJNI.Species_setId(swigCPtr, this, sid); 1287 } 1288 1289 1290 /** 1291 * Sets the value of the 'name' attribute of this {@link Species}. 1292 <p> 1293 * <p> 1294 * The string in <code>name</code> is copied. 1295 <p> 1296 * @param name the new name for the SBML object. 1297 <p> 1298 * <p> 1299 * @return integer value indicating success/failure of the 1300 * function. The possible values 1301 * returned by this function are: 1302 * <ul> 1303 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1304 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 1305 * 1306 * </ul> 1307 */ public setName(String name)1308 int setName(String name) { 1309 return libsbmlJNI.Species_setName(swigCPtr, this, name); 1310 } 1311 1312 1313 /** 1314 * Sets the 'speciesType' attribute of this {@link Species} object. 1315 <p> 1316 * @param sid the identifier of a {@link SpeciesType} object defined elsewhere 1317 * in this {@link Model}. 1318 <p> 1319 * <p> 1320 * @return integer value indicating success/failure of the 1321 * function. The possible values 1322 * returned by this function are: 1323 * <ul> 1324 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1325 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 1326 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 1327 * 1328 * </ul> <p> 1329 * @note The 'speciesType' attribute is only available in SBML 1330 * Level 2 Versions 2–4. 1331 */ public setSpeciesType(String sid)1332 int setSpeciesType(String sid) { 1333 return libsbmlJNI.Species_setSpeciesType(swigCPtr, this, sid); 1334 } 1335 1336 1337 /** 1338 * Sets the 'compartment' attribute of this {@link Species} object. 1339 <p> 1340 * @param sid the identifier of a {@link Compartment} object defined elsewhere 1341 * in this {@link Model}. 1342 <p> 1343 * <p> 1344 * @return integer value indicating success/failure of the 1345 * function. The possible values 1346 * returned by this function are: 1347 * <ul> 1348 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1349 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 1350 * </ul> 1351 */ public setCompartment(String sid)1352 int setCompartment(String sid) { 1353 return libsbmlJNI.Species_setCompartment(swigCPtr, this, sid); 1354 } 1355 1356 1357 /** 1358 * Sets the 'initialAmount' attribute of this {@link Species} and marks the field 1359 * as set. 1360 <p> 1361 * This method also unsets the 'initialConcentration' attribute. 1362 <p> 1363 * @param value the value to which the 'initialAmount' attribute should 1364 * be set. 1365 <p> 1366 * <p> 1367 * @return integer value indicating success/failure of the 1368 * function. The possible values 1369 * returned by this function are: 1370 * <ul> 1371 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1372 * </ul> 1373 */ public setInitialAmount(double value)1374 int setInitialAmount(double value) { 1375 return libsbmlJNI.Species_setInitialAmount(swigCPtr, this, value); 1376 } 1377 1378 1379 /** 1380 * Sets the 'initialConcentration' attribute of this {@link Species} and marks 1381 * the field as set. 1382 <p> 1383 * This method also unsets the 'initialAmount' attribute. 1384 <p> 1385 * @param value the value to which the 'initialConcentration' attribute 1386 * should be set. 1387 <p> 1388 * <p> 1389 * @return integer value indicating success/failure of the 1390 * function. The possible values 1391 * returned by this function are: 1392 * <ul> 1393 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1394 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 1395 * 1396 * </ul> <p> 1397 * @note The attribute 'initialConcentration' is only available in SBML 1398 * Level 2 and 3. It does not exist on {@link Species} in Level 1. 1399 */ public setInitialConcentration(double value)1400 int setInitialConcentration(double value) { 1401 return libsbmlJNI.Species_setInitialConcentration(swigCPtr, this, value); 1402 } 1403 1404 1405 /** 1406 * Sets the 'substanceUnits' attribute of this {@link Species} object. 1407 <p> 1408 * @param sid the identifier of the unit to use. 1409 <p> 1410 * <p> 1411 * @return integer value indicating success/failure of the 1412 * function. The possible values 1413 * returned by this function are: 1414 * <ul> 1415 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1416 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 1417 * </ul> 1418 */ public setSubstanceUnits(String sid)1419 int setSubstanceUnits(String sid) { 1420 return libsbmlJNI.Species_setSubstanceUnits(swigCPtr, this, sid); 1421 } 1422 1423 1424 /** 1425 * (SBML Level 2 Versions 1–2) Sets the 'spatialSizeUnits' attribute of this {@link Species} object. 1426 <p> 1427 * @param sid the identifier of the unit to use. 1428 <p> 1429 * <p> 1430 * @return integer value indicating success/failure of the 1431 * function. The possible values 1432 * returned by this function are: 1433 * <ul> 1434 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1435 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 1436 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 1437 * 1438 * </ul> <p> 1439 * <p> 1440 * @warning <span class='warning'>In versions of SBML Level 2 before 1441 * Version 3, the class {@link Species} included an attribute called 1442 * 'spatialSizeUnits', which allowed explicitly setting the units of size for 1443 * initial concentration. This attribute was removed in SBML Level 2 1444 * Version 3. LibSBML retains this attribute for compatibility with 1445 * older definitions of Level 2, but its use is strongly discouraged 1446 * because it is incompatible with levels and versions of SBML beyond 1447 * Level 2 Version 2.</span> 1448 */ public setSpatialSizeUnits(String sid)1449 int setSpatialSizeUnits(String sid) { 1450 return libsbmlJNI.Species_setSpatialSizeUnits(swigCPtr, this, sid); 1451 } 1452 1453 1454 /** 1455 * (SBML Level 1 only) Sets the units of this {@link Species} object. 1456 <p> 1457 * @param sname the identifier of the unit to use. 1458 <p> 1459 * <p> 1460 * @return integer value indicating success/failure of the 1461 * function. The possible values 1462 * returned by this function are: 1463 * <ul> 1464 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1465 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 1466 * </ul> 1467 */ public setUnits(String sname)1468 int setUnits(String sname) { 1469 return libsbmlJNI.Species_setUnits(swigCPtr, this, sname); 1470 } 1471 1472 1473 /** 1474 * Sets the 'hasOnlySubstanceUnits' attribute of this {@link Species} object. 1475 <p> 1476 * @param value boolean value for the 'hasOnlySubstanceUnits' attribute. 1477 <p> 1478 * <p> 1479 * @return integer value indicating success/failure of the 1480 * function. The possible values 1481 * returned by this function are: 1482 * <ul> 1483 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1484 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 1485 * 1486 * </ul> <p> 1487 * @note The 'hasOnlySubstanceUnits' attribute does not exist in SBML 1488 * Level 1. 1489 */ public setHasOnlySubstanceUnits(boolean value)1490 int setHasOnlySubstanceUnits(boolean value) { 1491 return libsbmlJNI.Species_setHasOnlySubstanceUnits(swigCPtr, this, value); 1492 } 1493 1494 1495 /** 1496 * Sets the 'boundaryCondition' attribute of this {@link Species} object. 1497 <p> 1498 * @param value boolean value for the 'boundaryCondition' attribute. 1499 <p> 1500 * <p> 1501 * @return integer value indicating success/failure of the 1502 * function. The possible values 1503 * returned by this function are: 1504 * <ul> 1505 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1506 * </ul> 1507 */ public setBoundaryCondition(boolean value)1508 int setBoundaryCondition(boolean value) { 1509 return libsbmlJNI.Species_setBoundaryCondition(swigCPtr, this, value); 1510 } 1511 1512 1513 /** 1514 * Sets the 'charge' attribute of this {@link Species} object. 1515 <p> 1516 * @param value an integer to which to set the 'charge' to. 1517 <p> 1518 * <p> 1519 * @note Beginning in SBML Level 2 Version 2, the 'charge' 1520 * attribute on {@link Species} is deprecated and in SBML Level 3 it does 1521 * not exist at all. Its use strongly discouraged. Its presence is 1522 * considered a misfeature in earlier definitions of SBML because its 1523 * implications for the mathematics of a model were never defined, and in 1524 * any case, no known modeling system ever used it. Instead, models take 1525 * account of charge values directly in their definitions of species by 1526 * (for example) having separate species identities for the charged and 1527 * uncharged versions of the same species. This allows the condition to 1528 * affect model mathematics directly. LibSBML retains this method for 1529 * easier compatibility with SBML Level 1. 1530 <p> 1531 * <p> 1532 * @return integer value indicating success/failure of the 1533 * function. The possible values 1534 * returned by this function are: 1535 * <ul> 1536 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1537 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 1538 * </ul> 1539 */ public setCharge(int value)1540 int setCharge(int value) { 1541 return libsbmlJNI.Species_setCharge(swigCPtr, this, value); 1542 } 1543 1544 1545 /** 1546 * Sets the 'constant' attribute of this {@link Species} object. 1547 <p> 1548 * @param value a boolean value for the 'constant' attribute. 1549 <p> 1550 * <p> 1551 * @return integer value indicating success/failure of the 1552 * function. The possible values 1553 * returned by this function are: 1554 * <ul> 1555 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1556 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 1557 * 1558 * </ul> <p> 1559 * @note The attribute 'constant' is only available in SBML Levels 2 1560 * and 3. It does not exist on {@link Species} in Level 1. 1561 */ public setConstant(boolean value)1562 int setConstant(boolean value) { 1563 return libsbmlJNI.Species_setConstant(swigCPtr, this, value); 1564 } 1565 1566 1567 /** 1568 * Sets the value of the 'conversionFactor' attribute of this {@link Species} object. 1569 <p> 1570 * The string in <code>sid</code> is copied. 1571 <p> 1572 * @param sid the new conversionFactor for the {@link Species}. 1573 <p> 1574 * <p> 1575 * @return integer value indicating success/failure of the 1576 * function. The possible values 1577 * returned by this function are: 1578 * <ul> 1579 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1580 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 1581 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 1582 * 1583 * </ul> <p> 1584 * @note The 'conversionFactor' attribute was introduced in SBML 1585 * Level 3. It does not exist on {@link Species} in SBML Levels 1 1586 * and 2. 1587 */ public setConversionFactor(String sid)1588 int setConversionFactor(String sid) { 1589 return libsbmlJNI.Species_setConversionFactor(swigCPtr, this, sid); 1590 } 1591 1592 1593 /** 1594 * Unsets the value of the 'name' attribute of this {@link Species} object. 1595 <p> 1596 * <p> 1597 * <p> 1598 * In SBML Level 3 Version 2, the 'id' and 'name' attributes were 1599 * moved to {@link SBase} directly, instead of being defined individually for many 1600 * (but not all) objects. LibSBML has for a long time provided functions 1601 * defined on {@link SBase} itself to get, set, and unset those attributes, which 1602 * would fail or otherwise return empty strings if executed on any object 1603 * for which those attributes were not defined. Now that all {@link SBase} objects 1604 * define those attributes, those functions now succeed for any object with 1605 * the appropriate level and version. 1606 <p> 1607 * The 'name' attribute is 1608 * optional and is not intended to be used for cross-referencing purposes 1609 * within a model. Its purpose instead is to provide a human-readable 1610 * label for the component. The data type of 'name' is the type 1611 * <code>string</code> defined in XML Schema. SBML imposes no 1612 * restrictions as to the content of 'name' attributes beyond those 1613 * restrictions defined by the <code>string</code> type in XML Schema. 1614 <p> 1615 * The recommended practice for handling 'name' is as follows. If a 1616 * software tool has the capability for displaying the content of 'name' 1617 * attributes, it should display this content to the user as a 1618 * component's label instead of the component's 'id'. If the user 1619 * interface does not have this capability (e.g., because it cannot 1620 * display or use special characters in symbol names), or if the 'name' 1621 * attribute is missing on a given component, then the user interface 1622 * should display the value of the 'id' attribute instead. (Script 1623 * language interpreters are especially likely to display 'id' instead of 1624 * 'name'.) 1625 <p> 1626 * As a consequence of the above, authors of systems that automatically 1627 * generate the values of 'id' attributes should be aware some systems 1628 * may display the 'id''s to the user. Authors therefore may wish to 1629 * take some care to have their software create 'id' values that are: (a) 1630 * reasonably easy for humans to type and read; and (b) likely to be 1631 * meaningful, for example by making the 'id' attribute be an abbreviated 1632 * form of the name attribute value. 1633 <p> 1634 * An additional point worth mentioning is although there are 1635 * restrictions on the uniqueness of 'id' values, there are no 1636 * restrictions on the uniqueness of 'name' values in a model. This 1637 * allows software applications leeway in assigning component identifiers. 1638 <p> 1639 * Regardless of the level and version of the SBML, these functions allow 1640 * client applications to use more generalized code in some situations 1641 * (for instance, when manipulating objects that are all known to have 1642 * names). If the object in question does not posess a 'name' attribute 1643 * according to the SBML specification for the Level and Version in use, 1644 * libSBML will not allow the name to be set, nor will it read or 1645 * write 'name' attributes for those objects. 1646 <p> 1647 * <p> 1648 * @return integer value indicating success/failure of the 1649 * function. The possible values 1650 * returned by this function are: 1651 * <ul> 1652 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1653 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 1654 * 1655 * </ul> <p> 1656 * @see #getName() 1657 * @see #setName(String sid) 1658 * @see #isSetName() 1659 */ public unsetName()1660 int unsetName() { 1661 return libsbmlJNI.Species_unsetName(swigCPtr, this); 1662 } 1663 1664 1665 /** 1666 * Unsets the value of the 'constant' attribute of this {@link Species} object. 1667 <p> 1668 * <p> 1669 * @return integer value indicating success/failure of the 1670 * function. The possible values 1671 * returned by this function are: 1672 * <ul> 1673 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1674 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 1675 * 1676 * </ul> <p> 1677 * @see #isSetConstant() 1678 * @see #setConstant(boolean) 1679 * @see #getConstant() 1680 */ public unsetConstant()1681 int unsetConstant() { 1682 return libsbmlJNI.Species_unsetConstant(swigCPtr, this); 1683 } 1684 1685 1686 /** 1687 * Unsets the 'speciesType' attribute value of this {@link Species} object. 1688 <p> 1689 * <p> 1690 * @return integer value indicating success/failure of the 1691 * function. The possible values 1692 * returned by this function are: 1693 * <ul> 1694 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1695 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 1696 * 1697 * </ul> <p> 1698 * @note The attribute 'speciesType' is only available in SBML 1699 * Level 2 Versions 2–4. 1700 */ public unsetSpeciesType()1701 int unsetSpeciesType() { 1702 return libsbmlJNI.Species_unsetSpeciesType(swigCPtr, this); 1703 } 1704 1705 1706 /** 1707 * Unsets the 'initialAmount' attribute value of this {@link Species} object. 1708 <p> 1709 * <p> 1710 * @return integer value indicating success/failure of the 1711 * function. The possible values 1712 * returned by this function are: 1713 * <ul> 1714 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1715 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 1716 * </ul> 1717 */ public unsetInitialAmount()1718 int unsetInitialAmount() { 1719 return libsbmlJNI.Species_unsetInitialAmount(swigCPtr, this); 1720 } 1721 1722 1723 /** 1724 * Unsets the 'initialConcentration' attribute value of this {@link Species} object. 1725 <p> 1726 * <p> 1727 * @return integer value indicating success/failure of the 1728 * function. The possible values 1729 * returned by this function are: 1730 * <ul> 1731 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1732 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 1733 * 1734 * </ul> <p> 1735 * @note The attribute 'initialConcentration' is only available in SBML 1736 * Level 2 and 3. It does not exist on {@link Species} in Level 1. 1737 */ public unsetInitialConcentration()1738 int unsetInitialConcentration() { 1739 return libsbmlJNI.Species_unsetInitialConcentration(swigCPtr, this); 1740 } 1741 1742 1743 /** 1744 * Unsets the 'substanceUnits' attribute value of this {@link Species} object. 1745 <p> 1746 * <p> 1747 * @return integer value indicating success/failure of the 1748 * function. The possible values 1749 * returned by this function are: 1750 * <ul> 1751 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1752 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 1753 * </ul> 1754 */ public unsetSubstanceUnits()1755 int unsetSubstanceUnits() { 1756 return libsbmlJNI.Species_unsetSubstanceUnits(swigCPtr, this); 1757 } 1758 1759 1760 /** 1761 * Unsets the 'spatialSizeUnits' attribute value of this {@link Species} object. 1762 <p> 1763 * <p> 1764 * @return integer value indicating success/failure of the 1765 * function. The possible values 1766 * returned by this function are: 1767 * <ul> 1768 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1769 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 1770 * 1771 * </ul> <p> 1772 * <p> 1773 * @warning <span class='warning'>In versions of SBML Level 2 before 1774 * Version 3, the class {@link Species} included an attribute called 1775 * 'spatialSizeUnits', which allowed explicitly setting the units of size for 1776 * initial concentration. This attribute was removed in SBML Level 2 1777 * Version 3. LibSBML retains this attribute for compatibility with 1778 * older definitions of Level 2, but its use is strongly discouraged 1779 * because it is incompatible with levels and versions of SBML beyond 1780 * Level 2 Version 2.</span> 1781 */ public unsetSpatialSizeUnits()1782 int unsetSpatialSizeUnits() { 1783 return libsbmlJNI.Species_unsetSpatialSizeUnits(swigCPtr, this); 1784 } 1785 1786 1787 /** 1788 * Unsets the 'units' attribute value of this {@link Species} object. 1789 <p> 1790 * <p> 1791 * @return integer value indicating success/failure of the 1792 * function. The possible values 1793 * returned by this function are: 1794 * <ul> 1795 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1796 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 1797 * </ul> 1798 */ public unsetUnits()1799 int unsetUnits() { 1800 return libsbmlJNI.Species_unsetUnits(swigCPtr, this); 1801 } 1802 1803 1804 /** 1805 * Unsets the 'charge' attribute 1806 * value of this {@link Species} object. 1807 <p> 1808 * <p> 1809 * @return integer value indicating success/failure of the 1810 * function. The possible values 1811 * returned by this function are: 1812 * <ul> 1813 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1814 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 1815 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 1816 * 1817 * </ul> <p> 1818 * <p> 1819 * @note Beginning in SBML Level 2 Version 2, the 'charge' 1820 * attribute on {@link Species} is deprecated and in SBML Level 3 it does 1821 * not exist at all. Its use strongly discouraged. Its presence is 1822 * considered a misfeature in earlier definitions of SBML because its 1823 * implications for the mathematics of a model were never defined, and in 1824 * any case, no known modeling system ever used it. Instead, models take 1825 * account of charge values directly in their definitions of species by 1826 * (for example) having separate species identities for the charged and 1827 * uncharged versions of the same species. This allows the condition to 1828 * affect model mathematics directly. LibSBML retains this method for 1829 * easier compatibility with SBML Level 1. 1830 */ public unsetCharge()1831 int unsetCharge() { 1832 return libsbmlJNI.Species_unsetCharge(swigCPtr, this); 1833 } 1834 1835 1836 /** 1837 * Unsets the 'conversionFactor' attribute value of this {@link Species} object. 1838 <p> 1839 * <p> 1840 * @return integer value indicating success/failure of the 1841 * function. The possible values 1842 * returned by this function are: 1843 * <ul> 1844 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1845 * <li> {@link libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE} 1846 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 1847 * 1848 * </ul> <p> 1849 * @note The 'conversionFactor' attribute was introduced in SBML 1850 * Level 3. It does not exist on {@link Species} in SBML Levels 1 1851 * and 2. 1852 */ public unsetConversionFactor()1853 int unsetConversionFactor() { 1854 return libsbmlJNI.Species_unsetConversionFactor(swigCPtr, this); 1855 } 1856 1857 1858 /** 1859 * Unsets the 'compartment' attribute value of this {@link Species} object. 1860 <p> 1861 * <p> 1862 * @return integer value indicating success/failure of the 1863 * function. The possible values 1864 * returned by this function are: 1865 * <ul> 1866 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1867 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 1868 * </ul> 1869 */ public unsetCompartment()1870 int unsetCompartment() { 1871 return libsbmlJNI.Species_unsetCompartment(swigCPtr, this); 1872 } 1873 1874 1875 /** 1876 * Unsets the 'boundaryCondition' attribute value of this {@link Species} object. 1877 <p> 1878 * <p> 1879 * @return integer value indicating success/failure of the 1880 * function. The possible values 1881 * returned by this function are: 1882 * <ul> 1883 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1884 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 1885 * </ul> 1886 */ public unsetBoundaryCondition()1887 int unsetBoundaryCondition() { 1888 return libsbmlJNI.Species_unsetBoundaryCondition(swigCPtr, this); 1889 } 1890 1891 1892 /** 1893 * Unsets the 'hasOnlySubstanceUnits' attribute value of this {@link Species} object. 1894 <p> 1895 * <p> 1896 * @return integer value indicating success/failure of the 1897 * function. The possible values 1898 * returned by this function are: 1899 * <ul> 1900 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 1901 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 1902 * </ul> 1903 */ public unsetHasOnlySubstanceUnits()1904 int unsetHasOnlySubstanceUnits() { 1905 return libsbmlJNI.Species_unsetHasOnlySubstanceUnits(swigCPtr, this); 1906 } 1907 1908 1909 /** 1910 * Constructs and returns a {@link UnitDefinition} that corresponds to the units 1911 * of this {@link Species}' amount or concentration. 1912 <p> 1913 * {@link Species} in SBML have an attribute ('substanceUnits') for declaring the 1914 * units of measurement intended for the species' amount or concentration 1915 * (depending on which one applies). In the absence of a value given for 1916 * 'substanceUnits', the units are taken from the enclosing {@link Model}'s 1917 * definition of <code>'substance'</code> or <code>'substance'</code>/<em>(size of the 1918 * compartment)</em> in which the species is located, or finally, if 1919 * these are not redefined by the {@link Model}, the relevant SBML default units 1920 * for those quantities. Following that procedure, the method 1921 * {@link Species#getDerivedUnitDefinition()} 1922 * returns a {@link UnitDefinition} based on the 1923 * interpreted units of this species's amount or concentration. 1924 <p> 1925 * Note that the functionality that facilitates unit analysis depends 1926 * on the model as a whole. Thus, in cases where the object has not 1927 * been added to a model or the model itself is incomplete, 1928 * unit analysis is not possible and this method will return <code>null.</code> 1929 <p> 1930 * Note also that unit declarations for {@link Species} are in terms of the 1931 * <em>identifier</em> of a unit, but this method returns a {@link UnitDefinition} object, 1932 * not a unit identifier. It does this by constructing an appropriate 1933 * {@link UnitDefinition}. Callers may find this particularly useful when used 1934 * in conjunction with the helper methods on {@link UnitDefinition} for comparing 1935 * different {@link UnitDefinition} objects. 1936 <p> 1937 * In SBML Level 2 specifications prior to Version 3, {@link Species} 1938 * includes an additional attribute named 'spatialSizeUnits', which 1939 * allows explicitly setting the units of size for initial concentration. 1940 * The {@link Species#getDerivedUnitDefinition()} 1941 * takes this into account for models 1942 * expressed in SBML Level 2 Versions 1 and 2. 1943 <p> 1944 * @return a {@link UnitDefinition} that expresses the units of this 1945 * {@link Species}, or <code>null</code> if one cannot be constructed. 1946 <p> 1947 * @see #getSubstanceUnits() 1948 */ public getDerivedUnitDefinition()1949 UnitDefinition getDerivedUnitDefinition() { 1950 long cPtr = libsbmlJNI.Species_getDerivedUnitDefinition__SWIG_0(swigCPtr, this); 1951 return (cPtr == 0) ? null : new UnitDefinition(cPtr, false); 1952 } 1953 1954 1955 /** 1956 * Returns the libSBML type code for this SBML object. 1957 <p> 1958 * <p> 1959 * LibSBML attaches an identifying code to every kind of SBML object. These 1960 * are integer constants known as <em>SBML type codes</em>. The names of all 1961 * the codes begin with the characters <code>SBML_</code>. 1962 * In the Java language interface for libSBML, the 1963 * type codes are defined as static integer constants in the interface class 1964 * {@link libsbmlConstants}. Note that different Level 3 1965 * package plug-ins may use overlapping type codes; to identify the package 1966 * to which a given object belongs, call the 1967 * <code>{@link SBase#getPackageName()} 1968 * </code> 1969 * method on the object. 1970 <p> 1971 * The exception to this is lists: all SBML-style list elements have the type 1972 * {@link libsbmlConstants#SBML_LIST_OF SBML_LIST_OF}, regardless of what package they 1973 * are from. 1974 <p> 1975 * @return the SBML type code for this object: 1976 * {@link libsbmlConstants#SBML_SPECIES SBML_SPECIES} (default). 1977 <p> 1978 * <p> 1979 * @warning <span class='warning'>The specific integer values of the possible 1980 * type codes may be reused by different libSBML plug-ins for SBML Level 3. 1981 * packages, To fully identify the correct code, <strong>it is necessary to 1982 * invoke both getPackageName() and getTypeCode()</strong> (or 1983 * {@link ListOf#getItemTypeCode()}).</span> 1984 <p> 1985 * @see #getElementName() 1986 * @see #getPackageName() 1987 */ public getTypeCode()1988 int getTypeCode() { 1989 return libsbmlJNI.Species_getTypeCode(swigCPtr, this); 1990 } 1991 1992 1993 /** 1994 * Returns the XML element name of this object, which for {@link Species}, is 1995 * always <code>'species'.</code> 1996 <p> 1997 * @return the name of this element, i.e., <code>'species'.</code> 1998 */ public getElementName()1999 String getElementName() { 2000 return libsbmlJNI.Species_getElementName(swigCPtr, this); 2001 } 2002 2003 2004 /** 2005 * Predicate returning <code>true</code> if 2006 * all the required attributes for this {@link Species} object 2007 * have been set. 2008 <p> 2009 * The required attributes for a {@link Species} object are: 2010 * <ul> 2011 * <li> 'id' (or 'name' in SBML Level 1) 2012 * <li> 'compartment' 2013 * <li> 'initialAmount' (required in SBML Level 1 only; optional otherwise) 2014 * <li> 'hasOnlySubstanceUnits' (required in SBML Level 3; optional in SBML Level 2) 2015 * <li> 'boundaryCondition' (required in SBML Level 3; optional in Levels 1 and 2) 2016 * <li> 'constant' (required in SBML Level 3; optional in SBML Level 2) 2017 * 2018 * </ul> <p> 2019 * @return <code>true</code> if the required attributes have been set, <code>false</code> 2020 * otherwise. 2021 */ public hasRequiredAttributes()2022 boolean hasRequiredAttributes() { 2023 return libsbmlJNI.Species_hasRequiredAttributes(swigCPtr, this); 2024 } 2025 2026 2027 /** 2028 * <p> 2029 * Replaces all uses of a given <code>SIdRef</code> type attribute value with another 2030 * value. 2031 <p> 2032 * <p> 2033 * In SBML, object identifiers are of a data type called <code>SId</code>. 2034 * In SBML Level 3, an explicit data type called <code>SIdRef</code> was 2035 * introduced for attribute values that refer to <code>SId</code> values; in 2036 * previous Levels of SBML, this data type did not exist and attributes were 2037 * simply described to as 'referring to an identifier', but the effective 2038 * data type was the same as <code>SIdRef</code> in Level 3. These and 2039 * other methods of libSBML refer to the type <code>SIdRef</code> for all 2040 * Levels of SBML, even if the corresponding SBML specification did not 2041 * explicitly name the data type. 2042 <p> 2043 * This method works by looking at all attributes and (if appropriate) 2044 * mathematical formulas in MathML content, comparing the referenced 2045 * identifiers to the value of <code>oldid</code>. If any matches are found, the 2046 * matching values are replaced with <code>newid</code>. The method does <em>not</em> 2047 * descend into child elements. 2048 <p> 2049 * @param oldid the old identifier. 2050 * @param newid the new identifier. 2051 */ public renameSIdRefs(String oldid, String newid)2052 void renameSIdRefs(String oldid, String newid) { 2053 libsbmlJNI.Species_renameSIdRefs(swigCPtr, this, oldid, newid); 2054 } 2055 2056 2057 /** 2058 * <p> 2059 * Replaces all uses of a given <code>UnitSIdRef</code> type attribute value with 2060 * another value. 2061 <p> 2062 * <p> 2063 * In SBML, unit definitions have identifiers of type <code>UnitSId</code>. In 2064 * SBML Level 3, an explicit data type called <code>UnitSIdRef</code> was 2065 * introduced for attribute values that refer to <code>UnitSId</code> values; in 2066 * previous Levels of SBML, this data type did not exist and attributes were 2067 * simply described to as 'referring to a unit identifier', but the effective 2068 * data type was the same as <code>UnitSIdRef</code> in Level 3. These and 2069 * other methods of libSBML refer to the type <code>UnitSIdRef</code> for all 2070 * Levels of SBML, even if the corresponding SBML specification did not 2071 * explicitly name the data type. 2072 <p> 2073 * This method works by looking at all unit identifier attribute values 2074 * (including, if appropriate, inside mathematical formulas), comparing the 2075 * referenced unit identifiers to the value of <code>oldid</code>. If any matches 2076 * are found, the matching values are replaced with <code>newid</code>. The method 2077 * does <em>not</em> descend into child elements. 2078 <p> 2079 * @param oldid the old identifier. 2080 * @param newid the new identifier. 2081 */ public renameUnitSIdRefs(String oldid, String newid)2082 void renameUnitSIdRefs(String oldid, String newid) { 2083 libsbmlJNI.Species_renameUnitSIdRefs(swigCPtr, this, oldid, newid); 2084 } 2085 2086 } 2087