001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 2.0.12
004 *
005 * Do not make changes to this file unless you know what you are doing--modify
006 * the SWIG interface file instead.
007 * ----------------------------------------------------------------------------- */
008
009package org.sbml.libsbml;
010
011/** 
012 *  Implementation of SBML's Species construct.
013 <p>
014 * A <em>species</em> in SBML refers to a pool of entities that (a) are
015 * considered indistinguishable from each other for the purposes of the
016 * model, (b) participate in reactions, and (c) are located in a specific
017 * <em>compartment</em>.  The SBML {@link Species} object class is intended to represent
018 * these pools.
019 <p>
020 * As with other major constructs in SBML, {@link Species} has a mandatory
021 * attribute, 'id', used to give the species type an identifier in the
022 * model.  The identifier must be a text string conforming to the identifer
023 * syntax permitted in SBML.  {@link Species} also has an optional 'name'
024 * attribute, of type <code>string.</code>  The 'id' and 'name' must be used
025 * according to the guidelines described in the SBML specifications.
026 <p>
027 * The required attribute 'compartment' is used to identify the compartment
028 * in which the species is located.  The attribute's value must be the
029 * identifier of an existing {@link Compartment} object.  It is important to note
030 * that there is no default value for the 'compartment' attribute on
031 * {@link Species}; every species in an SBML model must be assigned a compartment
032 * <em>explicitly</em>.  (This also implies that every model with one or more
033 * {@link Species} objects must define at least one {@link Compartment} object.)
034 <p>
035 <p>
036 * <h2>The initial amount and concentration of a species</h2>
037 <p>
038 * The optional attributes 'initialAmount' and 'initialConcentration', both
039 * having a data type of <code>double</code>, can be used to set the <em>initial</em>
040 * quantity of the species in the compartment where the species is located.
041 * These attributes are mutually exclusive; i.e., <em>only one</em> can
042 * have a value on any given instance of a {@link Species} object.  Missing
043 * 'initialAmount' and 'initialConcentration' values implies that their
044 * values either are unknown, or to be obtained from an external source, or
045 * determined by an {@link InitialAssignment} or other SBML construct elsewhere in
046 * the model.
047 <p>
048 * A species' initial quantity in SBML is set by the 'initialAmount' or
049 * 'initialConcentration' attribute exactly once.  If the 'constant'
050 * attribute is <code>true</code>, then the value of the species' quantity is fixed
051 * and cannot be changed except by an {@link InitialAssignment}.  These methods
052 * differ in that the 'initialAmount' and 'initialConcentration' attributes
053 * can only be used to set the species quantity to a literal floating-point
054 * number, whereas the use of an {@link InitialAssignment} object allows the value
055 * to be set using an arbitrary mathematical expression (which, thanks to
056 * MathML's expressiveness, may evaluate to a rational number).  If the
057 * species' 'constant' attribute is <code>false</code>, the species' quantity value
058 * may be overridden by an {@link InitialAssignment} or changed by {@link AssignmentRule}
059 * or {@link AlgebraicRule}, and in addition, for <em>t &gt; 0</em>, it may also be
060 * changed by a {@link RateRule}, {@link Event} objects, and as a result of being a
061 * reactant or product in one or more {@link Reaction} objects.  (However, some
062 * constructs are mutually exclusive; see the SBML specifications for the
063 * precise details.)  It is not an error to define 'initialAmount' or
064 * 'initialConcentration' on a species and also redefine the value using an
065 * {@link InitialAssignment}, but the 'initialAmount' or 'initialConcentration'
066 * setting in that case is ignored.  The SBML specifications provide
067 * additional information about the semantics of assignments, rules and
068 * values for simulation time <em>t</em> &#8804; <em>0</em>.
069 <p>
070 * SBML Level&nbsp;2 additionally stipulates that in cases where a species'
071 * compartment has a 'spatialDimensions' value of <code>0</code> (zero), the species
072 * cannot have a value for 'initialConcentration' because the concepts of
073 * concentration and density break down when a container has zero
074 * dimensions.
075 <p>
076 * <h2>The units of a species' amount or concentration</h2>
077 <p>
078 * When the attribute 'initialAmount' is set, the unit of measurement
079 * associated with the value of 'initialAmount' is specified by the {@link Species}
080 * attribute 'substanceUnits'.  When the 'initialConcentration' attribute
081 * is set, the unit of measurement associated with this concentration value
082 * is {<em>unit of amount</em>} divided by {<em>unit of size</em>}, where
083 * the {<em>unit of amount</em>} is specified by the {@link Species}
084 * 'substanceUnits' attribute, and the {<em>unit of size</em>} is specified
085 * by the 'units' attribute of the {@link Compartment} object in which the species
086 * is located.  Note that in either case, a unit of <em>amount</em> is
087 * involved and determined by the 'substanceUnits' attribute.  Note
088 * <strong>these two attributes alone do not determine the units of the
089 * species when the species identifier appears in a mathematical
090 * expression</strong>; <em>that</em> aspect is determined by the attribute
091 * 'hasOnlySubstanceUnits' discussed below.
092 <p>
093 * In SBML Level&nbsp;3, if the 'substanceUnits' attribute is not set on a
094 * given {@link Species} object instance, then the unit of <em>amount</em> for that
095 * species is inherited from the 'substanceUnits' attribute on the
096 * enclosing {@link Model} object instance.  If that attribute on {@link Model} is not set
097 * either, then the unit associated with the species' quantity is
098 * undefined.
099 <p>
100 * In SBML Level&nbsp;2, if the 'substanceUnits' attribute is not set on a
101 * given {@link Species} object instance, then the unit of <em>amount</em> for that
102 * species is taken from the predefined SBML unit identifier 
103 * <code>'substance'.</code>  The value assigned to 'substanceUnits' must be chosen from
104 * one of the following possibilities: one of the base unit identifiers
105 * defined in SBML, the built-in unit identifier <code>'substance'</code>, or the
106 * identifier of a new unit defined in the list of unit definitions in the
107 * enclosing {@link Model} object.  The chosen units for 'substanceUnits' must be
108 * be <code>'dimensionless'</code>, <code>'mole'</code>, <code>'item'</code>, <code>'kilogram'</code>, <code>'gram'</code>,
109 * or units derived from these.
110 <p>
111 * As noted at the beginning of this section, simply setting
112 * 'initialAmount' or 'initialConcentration' alone does <em>not</em> determine
113 * whether a species identifier represents an amount or a concentration
114 * when it appears elsewhere in an SBML model.  The role of the attribute
115 * 'hasOnlySubstanceUnits' is to indicate whether the units of the species,
116 * when the species identifier appears in mathematical formulas, are
117 * intended to be concentration or amount.  The attribute takes on a
118 * boolean value.  In SBML Level&nbsp;3, the attribute has no default value
119 * and must always be set in a model; in SBML Level&nbsp;2, it has a
120 * default value of <code>false.</code>
121 <p>
122 * The <em>units of the species</em> are used in the following ways:
123 * <ul>
124<p>
125 * <li> When the species' identifier appears in a MathML formula, it
126 * represents the species' quantity, and the unit of measurement associated
127 * with the quantity is as described above.
128 <p>
129 * <li> The 'math' elements of {@link AssignmentRule}, {@link InitialAssignment} and
130 * {@link EventAssignment} objects referring to this species should all have the
131 * same units as the unit of measurement associated with the species
132 * quantity.
133 <p>
134 * <li> In a {@link RateRule} object that defines the rate of change of the
135 * species' quantity, the unit associated with the rule's 'math' element
136 * should be equal to the unit of the species' quantity divided by the
137 * model-wide unit of <em>time</em>; in other words, {<em>unit of species
138 * quantity</em>}/{<em>unit of time</em>}.
139 <p>
140 * </ul>
141 <p>
142 <p>
143 * <h2>The 'constant' and 'boundaryCondition' attributes</h2>
144 <p>
145 * The {@link Species} object class has two boolean attributes named 'constant' and
146 * 'boundaryCondition', used to indicate whether and how the quantity of
147 * that species can vary during a simulation.  In SBML Level&nbsp;2 they
148 * are optional; in SBML Level&nbsp;3 they are mandatory.  The following
149 * table shows how to interpret the combined values of these attributes.
150 <p>
151 * <table border="0" class="centered text-table width80 normal-font alt-row-colors">
152<caption class="top-caption">Interpretation
153of species' <code>constant</code> and <code>boundaryCondition</code>
154attributes.</caption>
155 <tr>
156     <th align="left" valign="bottom">
157       <code>constant</code><br>value
158     </th>
159     <th align="left" valign="bottom">
160       <code>boundaryCondition</code><br>value
161     </th>
162     <th align="left" valign="bottom">
163       Can have<br>assignment<br>or rate rule?
164     </th>
165     <th align="left" valign="bottom">
166       Can be<br>reactant<br>or product?
167     </th>
168     <th align="left" valign="bottom">
169       Species' quantity<br>can be changed by
170     </th>
171 </tr>
172 <tr>
173     <td><code>true</code></td>
174     <td><code>true</code></td>
175     <td>no</td>
176     <td>yes</td>
177     <td>(never changes)</td>
178 </tr>
179 <tr>
180     <td><code>false</code></td>
181     <td><code>true</code></td>
182     <td>yes</td>
183     <td>yes</td>
184     <td>rules and events</td>
185 </tr>
186 <tr>
187     <td><code>true</code></td>
188     <td><code>false</code></td>
189     <td>no</td>
190     <td>no</td>
191     <td>(never changes)</td>
192 </tr>
193 <tr>
194     <td><code>false</code></td>
195     <td><code>false</code></td>
196     <td>yes</td>
197     <td>yes</td>
198     <td>reactions <em>or</em> rules (but not both at the same time), and events</td>
199 </tr>
200</table>
201
202
203 <p>
204 * By default, when a species is a product or reactant of one or more
205 * reactions, its quantity is determined by those reactions.  In SBML, it
206 * is possible to indicate that a given species' quantity is <em>not</em>
207 * determined by the set of reactions even when that species occurs as a
208 * product or reactant; i.e., the species is on the <em>boundary</em> of
209 * the reaction system, and its quantity is not determined by the
210 * reactions.  The boolean attribute 'boundaryCondition' can be used to
211 * indicate this.  A value of <code>false</code> indicates that the species <em>is</em>
212 * part of the reaction system.  In SBML Level&nbsp;2, the attribute has a
213 * default value of <code>false</code>, while in SBML Level&nbsp;3, it has no
214 * default.
215 <p>
216 * The 'constant' attribute indicates whether the species' quantity can be
217 * changed at all, regardless of whether by reactions, rules, or constructs
218 * other than {@link InitialAssignment}.  A value of <code>false</code> indicates that the
219 * species' quantity can be changed.  (This is also a common value because
220 * the purpose of most simulations is precisely to calculate changes in
221 * species quantities.)  In SBML Level&nbsp;2, the attribute has a default
222 * value of <code>false</code>, while in SBML Level&nbsp;3, it has no default.  Note
223 * that the initial quantity of a species can be set by an
224 * {@link InitialAssignment} irrespective of the value of the 'constant' attribute.
225 <p>
226 * In practice, a 'boundaryCondition' value of <code>true</code> means a differential
227 * equation derived from the reaction definitions should not be generated
228 * for the species.  However, the species' quantity may still be changed by
229 * {@link AssignmentRule}, {@link RateRule}, {@link AlgebraicRule}, {@link Event}, and {@link InitialAssignment}
230 * constructs if its 'constant' attribute is <code>false.</code>  Conversely, if the
231 * species' 'constant' attribute is <code>true</code>, then its value cannot be
232 * changed by anything except {@link InitialAssignment}.
233 <p>
234 * A species having 'boundaryCondition'=<code>false</code> and 'constant'=<code>false</code>
235 * can appear as a product and/or reactant of one or more reactions in the
236 * model.  If the species is a reactant or product of a reaction, it must
237 * <em>not</em> also appear as the target of any {@link AssignmentRule} or {@link RateRule}
238 * object in the model.  If instead the species has 'boundaryCondition'=
239 * <code>false</code> and 'constant'=<code>true</code>, then it cannot appear as a reactant or
240 * product, or as the target of any {@link AssignmentRule}, {@link RateRule} or
241 * {@link EventAssignment} object in the model.
242 <p>
243 <p>
244 * <h2>The conversionFactor attribute in SBML Level&nbsp;3</h2>
245 <p>
246 * In SBML Level&nbsp;3, {@link Species} has an additional optional attribute,
247 * 'conversionFactor', that defines a conversion factor that applies to a
248 * particular species.  The value must be the identifier of a {@link Parameter}
249 * object instance defined in the model.  That {@link Parameter} object must be a
250 * constant, meaning its 'constant' attribute must be set to <code>true.</code>
251 * If a given {@link Species} object definition defines a value for its
252 * 'conversionFactor' attribute, it takes precedence over any factor
253 * defined by the {@link Model} object's 'conversionFactor' attribute.
254 <p>
255 * The unit of measurement associated with a species' quantity can be
256 * different from the unit of extent of reactions in the model.  SBML
257 * Level&nbsp;3 avoids implicit unit conversions by providing an explicit
258 * way to indicate any unit conversion that might be required.  The use of
259 * a conversion factor in computing the effects of reactions on a species'
260 * quantity is explained in detail in the SBML Level&nbsp;3 specification
261 * document.  Because the value of the 'conversionFactor' attribute is the
262 * identifier of a {@link Parameter} object, and because parameters can have units
263 * attached to them, the transformation from reaction extent units to
264 * species units can be completely specified using this approach.
265 <p>
266 * Note that the unit conversion factor is <strong>only applied when
267 * calculating the effect of a reaction on a species</strong>.  It is not
268 * used in any rules or other SBML constructs that affect the species, and
269 * it is also not used when the value of the species is referenced in a
270 * mathematical expression.
271 <p>
272 <p>
273 * <h2>The speciesType attribute in SBML Level&nbsp;2 Versions&nbsp;2&ndash;4</h2>
274 <p>
275 * In SBML Level&nbsp;2 Versions&nbsp;2&ndash;4, each species in a model
276 * may optionally be designated as belonging to a particular species type.
277 * The optional attribute 'speciesType' is used to identify the species
278 * type of the chemical entities that make up the pool represented by the
279 * {@link Species} objects.  The attribute's value must be the identifier of an
280 * existing {@link SpeciesType} object in the model.  If the 'speciesType'
281 * attribute is not present on a particular species definition, it means
282 * the pool contains chemical entities of a type unique to that pool; in
283 * effect, a virtual species type is assumed for that species, and no other
284 * species can belong to that species type.  The value of 'speciesType'
285 * attributes on species have no effect on the numerical interpretation of
286 * a model; simulators and other numerical analysis software may ignore
287 * 'speciesType' attributes.
288 <p>
289 * There can be only one species of a given species type in any given
290 * compartment of a model.  More specifically, for all {@link Species} objects
291 * having a value for the 'speciesType' attribute, the pair
292 * <center>
293 * ('speciesType' attribute value, 'compartment' attribute value)
294 * </center>
295 <p>
296 * must be unique across the set of all {@link Species} object in a model.
297 <p>
298 <p>
299 * <h2>The spatialSizeUnits attribute in SBML Level&nbsp;2 Versions&nbsp;1&ndash;2</h2>
300 <p>
301 * In versions of SBML Level&nbsp;2 before Version&nbsp;3, the class
302 * {@link Species} included an attribute called 'spatialSizeUnits', which allowed
303 * explicitly setting the units of size for initial concentration.  LibSBML
304 * retains this attribute for compatibility with older definitions of
305 * Level&nbsp;2, but its use is strongly discouraged because many software
306 * tools do no properly interpret this unit declaration and it is
307 * incompatible with all SBML specifications after Level&nbsp;2
308 * Version&nbsp;3.
309 <p>
310 <p>
311 * <h2>Additional considerations for interpreting the numerical value of a species</h2>
312 <p>
313 * {@link Species} are unique in SBML in that they have a kind of duality: a
314 * species identifier may stand for either substance amount (meaning, a
315 * count of the number of individual entities) or a concentration or
316 * density (meaning, amount divided by a compartment size).  The previous
317 * sections explain the meaning of a species identifier when it is
318 * referenced in a mathematical formula or in rules or other SBML
319 * constructs; however, it remains to specify what happens to a species
320 * when the compartment in which it is located changes in size.
321 <p>
322 * When a species definition has a 'hasOnlySubstanceUnits' attribute value
323 * of <code>false</code> and the size of the compartment in which the species is
324 * located changes, the default in SBML is to assume that it is the
325 * concentration that must be updated to account for the size change.  This
326 * follows from the principle that, all other things held constant, if a
327 * compartment simply changes in size, the size change does not in itself
328 * cause an increase or decrease in the number of entities of any species
329 * in that compartment.  In a sense, the default is that the <em>amount</em> of
330 * a species is preserved across compartment size changes.  Upon such size
331 * changes, the value of the concentration or density must be recalculated
332 * from the simple relationship <em>concentration = amount / size</em> if
333 * the value of the concentration is needed (for example, if the species
334 * identifier appears in a mathematical formula or is otherwise referenced
335 * in an SBML construct).  There is one exception: if the species' quantity
336 * is determined by an {@link AssignmentRule}, {@link RateRule}, {@link AlgebraicRule}, or an
337 * {@link EventAssignment} and the species has a 'hasOnlySubstanceUnits' attribute
338 * value of <code>false</code>, it means that the <em>concentration</em> is assigned
339 * by the rule or event; in that case, the <em>amount</em> must be
340 * calculated when the compartment size changes.  (Events also require
341 * additional care in this situation, because an event with multiple
342 * assignments could conceivably reassign both a species quantity and a
343 * compartment size simultaneously.  Please refer to the SBML
344 * specifications for the details.)
345 <p>
346 * Note that the above only matters if a species has a
347 * 'hasOnlySubstanceUnits' attribute value of <code>false</code>, meaning that the
348 * species identifier refers to a concentration wherever the identifier
349 * appears in a mathematical formula.  If instead the attribute's value is
350 * <code>true</code>, then the identifier of the species <em>always</em> stands for
351 * an amount wherever it appears in a mathematical formula or is referenced
352 * by an SBML construct.  In that case, there is never a question about
353 * whether an assignment or event is meant to affect the amount or
354 * concentration: it is always the amount.
355 <p>
356 * A particularly confusing situation can occur when the species has
357 * 'constant' attribute value of <code>true</code> in combination with a
358 * 'hasOnlySubstanceUnits' attribute value of <code>false.</code>  Suppose this
359 * species is given a value for 'initialConcentration'.  Does a 'constant'
360 * value of <code>true</code> mean that the concentration is held constant if the
361 * compartment size changes?  No; it is still the amount that is kept
362 * constant across a compartment size change.  The fact that the species
363 * was initialized using a concentration value is irrelevant.
364 */
365
366public class Species extends SBase {
367   private long swigCPtr;
368
369   protected Species(long cPtr, boolean cMemoryOwn)
370   {
371     super(libsbmlJNI.Species_SWIGUpcast(cPtr), cMemoryOwn);
372     swigCPtr = cPtr;
373   }
374
375   protected static long getCPtr(Species obj)
376   {
377     return (obj == null) ? 0 : obj.swigCPtr;
378   }
379
380   protected static long getCPtrAndDisown (Species obj)
381   {
382     long ptr = 0;
383
384     if (obj != null)
385     {
386       ptr             = obj.swigCPtr;
387       obj.swigCMemOwn = false;
388     }
389
390     return ptr;
391   }
392
393  protected void finalize() {
394    delete();
395  }
396
397  public synchronized void delete() {
398    if (swigCPtr != 0) {
399      if (swigCMemOwn) {
400        swigCMemOwn = false;
401        libsbmlJNI.delete_Species(swigCPtr);
402      }
403      swigCPtr = 0;
404    }
405    super.delete();
406  }
407
408  
409/**
410   * Creates a new {@link Species} using the given SBML <code>level</code> and <code>version</code>
411   * values.
412   <p>
413   * @param level a long integer, the SBML Level to assign to this {@link Species}
414   <p>
415   * @param version a long integer, the SBML Version to assign to this
416   * {@link Species}
417   <p>
418   * @throws SBMLConstructorException 
419   * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind
420   * of SBML object, are either invalid or mismatched with respect to the
421   * parent {@link SBMLDocument} object.
422   <p>
423   * <p>
424 * @note Upon the addition of a {@link Species} object to an {@link SBMLDocument} (e.g.,
425 * using {@link Model#addSpecies(Species s)}), the SBML Level, SBML Version and XML
426 * namespace of the document <em>override</em> the values used when creating
427 * the {@link Species} object via this constructor.  This is necessary to ensure
428 * that an SBML document is a consistent structure.  Nevertheless, the
429 * ability to supply the values at the time of creation of a {@link Species} is
430 * an important aid to producing valid SBML.  Knowledge of the intented
431 * SBML Level and Version determine whether it is valid to assign a
432 * particular value to an attribute, or whether it is valid to add an
433 * object to an existing {@link SBMLDocument}.
434   */ public
435 Species(long level, long version) throws org.sbml.libsbml.SBMLConstructorException {
436    this(libsbmlJNI.new_Species__SWIG_0(level, version), true);
437  }
438
439  
440/**
441   * Creates a new {@link Species} using the given {@link SBMLNamespaces} object
442   * <code>sbmlns</code>.
443   <p>
444   * <p>
445 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces
446 * information.  It is used to communicate the SBML Level, Version, and (in
447 * Level&nbsp;3) packages used in addition to SBML Level&nbsp;3 Core.  A
448 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an
449 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object
450 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments. 
451   <p>
452   * It is worth emphasizing that although this constructor does not take
453   * an identifier argument, in SBML Level&nbsp;2 and beyond, the 'id'
454   * (identifier) attribute of a {@link Species} is required to have a value.
455   * Thus, callers are cautioned to assign a value after calling this
456   * constructor.  Setting the identifier can be accomplished using the
457   * method {@link Species#setId(String id)}.
458   <p>
459   * @param sbmlns an {@link SBMLNamespaces} object.
460   <p>
461   * @throws SBMLConstructorException 
462   * Thrown if the given <code>level</code> and <code>version</code> combination, or this kind
463   * of SBML object, are either invalid or mismatched with respect to the
464   * parent {@link SBMLDocument} object.
465   <p>
466   * <p>
467 * @note Upon the addition of a {@link Species} object to an {@link SBMLDocument} (e.g.,
468 * using {@link Model#addSpecies(Species s)}), the SBML Level, SBML Version and XML
469 * namespace of the document <em>override</em> the values used when creating
470 * the {@link Species} object via this constructor.  This is necessary to ensure
471 * that an SBML document is a consistent structure.  Nevertheless, the
472 * ability to supply the values at the time of creation of a {@link Species} is
473 * an important aid to producing valid SBML.  Knowledge of the intented
474 * SBML Level and Version determine whether it is valid to assign a
475 * particular value to an attribute, or whether it is valid to add an
476 * object to an existing {@link SBMLDocument}.
477   */ public
478 Species(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException {
479    this(libsbmlJNI.new_Species__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true);
480  }
481
482  
483/**
484   * Copy constructor; creates a copy of this {@link Species} object.
485   <p>
486   * @param orig the object to copy.
487   <p>
488   * @throws SBMLConstructorException 
489   * Thrown if the argument <code>orig</code> is <code>null.</code>
490   */ public
491 Species(Species orig) throws org.sbml.libsbml.SBMLConstructorException {
492    this(libsbmlJNI.new_Species__SWIG_2(Species.getCPtr(orig), orig), true);
493  }
494
495  
496/**
497   * Creates and returns a deep copy of this {@link Species} object.
498   <p>
499   * @return a (deep) copy of this {@link Species} object.
500   */ public
501 Species cloneObject() {
502    long cPtr = libsbmlJNI.Species_cloneObject(swigCPtr, this);
503    return (cPtr == 0) ? null : new Species(cPtr, true);
504  }
505
506  
507/**
508   * Initializes the fields of this {@link Species} object to 'typical' defaults
509   * values.
510   <p>
511   * The SBML {@link Species} component has slightly different aspects and
512   * default attribute values in different SBML Levels and Versions.
513   * This method sets the values to certain common defaults, based
514   * mostly on what they are in SBML Level&nbsp;2.  Specifically:
515   * <ul>
516   * <li> Sets 'boundaryCondition' to <code>false</code>
517   * <li> Sets 'constant' to <code>false</code>
518   * <li> sets 'hasOnlySubstanceUnits' to <code>false</code>
519   * <li> (Applies to Level&nbsp;3 models only) Sets attribute 'substanceUnits' to <code>mole</code>
520   * </ul>
521   */ public
522 void initDefaults() {
523    libsbmlJNI.Species_initDefaults(swigCPtr, this);
524  }
525
526  
527/**
528   * Returns the value of the 'id' attribute of this {@link Species} object.
529   <p>
530   * @return the id of this {@link Species} object.
531   */ public
532 String getId() {
533    return libsbmlJNI.Species_getId(swigCPtr, this);
534  }
535
536  
537/**
538   * Returns the value of the 'name' attribute of this {@link Species} object.
539   <p>
540   * @return the name of this {@link Species} object.
541   */ public
542 String getName() {
543    return libsbmlJNI.Species_getName(swigCPtr, this);
544  }
545
546  
547/**
548   * Get the type of this {@link Species} object object.
549   <p>
550   * @return the value of the 'speciesType' attribute of this
551   * {@link Species} as a string.
552   <p>
553   * @note The 'speciesType' attribute is only available in SBML
554   * Level&nbsp;2 Versions&nbsp;2&ndash;4.
555   */ public
556 String getSpeciesType() {
557    return libsbmlJNI.Species_getSpeciesType(swigCPtr, this);
558  }
559
560  
561/**
562   * Get the compartment in which this species is located.
563   <p>
564   * The compartment is designated by its identifier.
565   <p>
566   * @return the value of the 'compartment' attribute of this {@link Species}
567   * object, as a string.
568   */ public
569 String getCompartment() {
570    return libsbmlJNI.Species_getCompartment(swigCPtr, this);
571  }
572
573  
574/**
575   * Get the value of the 'initialAmount' attribute.
576   <p>
577   * @return the initialAmount of this {@link Species}, as a float-point number.
578   */ public
579 double getInitialAmount() {
580    return libsbmlJNI.Species_getInitialAmount(swigCPtr, this);
581  }
582
583  
584/**
585   * Get the value of the 'initialConcentration' attribute.
586   <p>
587   * @return the initialConcentration of this {@link Species},, as a float-point
588   * number.
589   <p>
590   * @note The attribute 'initialConcentration' is only available in SBML
591   * Level&nbsp;2 and&nbsp;3.  It does not exist on {@link Species} in Level&nbsp;1.
592   */ public
593 double getInitialConcentration() {
594    return libsbmlJNI.Species_getInitialConcentration(swigCPtr, this);
595  }
596
597  
598/**
599   * Get the value of the 'substanceUnits' attribute.
600   <p>
601   * @return the value of the 'substanceUnits' attribute of this {@link Species},
602   * as a string.  An empty string indicates that no units have been
603   * assigned.
604   <p>
605   * <p>
606 * @note There is an important distinction to be made between <em>no units
607 * assigned</em>, and assuming a value without units has any specific unit
608 * such as <code>dimensionless</code>.  In SBML, default units are never
609 * attributed to numbers, and numbers without units are not automatically
610 * assumed to have the unit <code>dimensionless</code>.  Please consult the
611 * relevant SBML specification document for a more in-depth explanation of
612 * this topic and the SBML unit system.
613   <p>
614   * @see #isSetSubstanceUnits()
615   * @see #setSubstanceUnits(String sid)
616   */ public
617 String getSubstanceUnits() {
618    return libsbmlJNI.Species_getSubstanceUnits(swigCPtr, this);
619  }
620
621  
622/**
623   * Get the value of the 'spatialSizeUnits' attribute.
624   <p>
625   * @return the value of the 'spatialSizeUnits' attribute of this {@link Species}
626   * object, as a string.
627   <p>
628   * <p>
629 * @warning <span class='warning'>In versions of SBML Level&nbsp;2 before
630 * Version&nbsp;3, the class {@link Species} included an attribute called
631 * 'spatialSizeUnits', which allowed explicitly setting the units of size for
632 * initial concentration.  This attribute was removed in SBML Level&nbsp;2
633 * Version&nbsp;3.  LibSBML retains this attribute for compatibility with
634 * older definitions of Level&nbsp;2, but its use is strongly discouraged
635 * because it is incompatible with Level&nbsp;2 Version&nbsp;3 and
636 * Level&nbsp;2 Version&nbsp;4.</span>
637   */ public
638 String getSpatialSizeUnits() {
639    return libsbmlJNI.Species_getSpatialSizeUnits(swigCPtr, this);
640  }
641
642  
643/**
644   * Get the value of the 'units' attribute.
645   <p>
646   * @return the units of this {@link Species} (L1 only).
647   <p>
648   * <p>
649 * @note The 'units' attribute is defined only in SBML Level&nbsp;1.  In
650 * SBML Level&nbsp;2 and Level&nbsp;3, it has been replaced by a
651 * combination of 'substanceUnits' and the units of the {@link Compartment}
652 * object in which a species is located.  In SBML Level&nbsp;2
653 * Versions&nbsp;1&ndash;2, an additional attribute 'spatialSizeUnits'
654 * helps determine the units of the species quantity, but this attribute
655 * was removed in later versions of SBML Level&nbsp;2. 
656   */ public
657 String getUnits() {
658    return libsbmlJNI.Species_getUnits(swigCPtr, this);
659  }
660
661  
662/**
663   * Get the value of the 'hasOnlySubstanceUnits' attribute.
664   <p>
665   * @return <code>true</code> if this {@link Species}' 'hasOnlySubstanceUnits' attribute
666   * value is nonzero, <code>false</code> otherwise.
667   <p>
668   * @note The 'hasOnlySubstanceUnits' attribute does not exist in SBML
669   * Level&nbsp;1.
670   */ public
671 boolean getHasOnlySubstanceUnits() {
672    return libsbmlJNI.Species_getHasOnlySubstanceUnits(swigCPtr, this);
673  }
674
675  
676/**
677   * Get the value of the 'boundaryCondition' attribute.
678   <p>
679   * @return <code>true</code> if this {@link Species}' 'boundaryCondition' attribute value
680   * is nonzero, <code>false</code> otherwise.
681   */ public
682 boolean getBoundaryCondition() {
683    return libsbmlJNI.Species_getBoundaryCondition(swigCPtr, this);
684  }
685
686  
687/**
688   * Get the value of the 'charge' attribute.
689   <p>
690   * @return the charge of this {@link Species} object.
691   <p>
692   * <p>
693 * @note Beginning in SBML Level&nbsp;2 Version&nbsp;2, the 'charge'
694 * attribute on {@link Species} is deprecated and in SBML Level&nbsp;3 it does
695 * not exist at all.  Its use strongly discouraged.  Its presence is
696 * considered a misfeature in earlier definitions of SBML because its
697 * implications for the mathematics of a model were never defined, and in
698 * any case, no known modeling system ever used it.  Instead, models take
699 * account of charge values directly in their definitions of species by
700 * (for example) having separate species identities for the charged and
701 * uncharged versions of the same species.  This allows the condition to
702 * affect model mathematics directly.  LibSBML retains this method for
703 * easier compatibility with SBML Level&nbsp;1.
704   */ public
705 int getCharge() {
706    return libsbmlJNI.Species_getCharge(swigCPtr, this);
707  }
708
709  
710/**
711   * Get the value of the 'constant' attribute.
712   <p>
713   * @return <code>true</code> if this {@link Species}'s 'constant' attribute value is
714   * nonzero, <code>false</code> otherwise.
715   <p>
716   * @note The attribute 'constant' is only available in SBML Levels&nbsp;2
717   * and&nbsp;3.  It does not exist on {@link Species} in Level&nbsp;1.
718   */ public
719 boolean getConstant() {
720    return libsbmlJNI.Species_getConstant(swigCPtr, this);
721  }
722
723  
724/**
725   * Get the value of the 'conversionFactor' attribute.
726   <p>
727   * @return the conversionFactor of this {@link Species}, as a string.
728   <p>
729   * @note The 'conversionFactor' attribute was introduced in SBML
730   * Level&nbsp;3.  It does not exist on {@link Species} in SBML Levels&nbsp;1
731   * and&nbsp;2.
732   */ public
733 String getConversionFactor() {
734    return libsbmlJNI.Species_getConversionFactor(swigCPtr, this);
735  }
736
737  
738/**
739   * Predicate returning <code>true</code> if this
740   * {@link Species} object's 'id' attribute is set.
741   <p>
742   * @return <code>true</code> if the 'id' attribute of this {@link Species} is
743   * set, <code>false</code> otherwise.
744   */ public
745 boolean isSetId() {
746    return libsbmlJNI.Species_isSetId(swigCPtr, this);
747  }
748
749  
750/**
751   * Predicate returning <code>true</code> if this
752   * {@link Species} object's 'name' attribute is set.
753   <p>
754   * @return <code>true</code> if the 'name' attribute of this {@link Species} is
755   * set, <code>false</code> otherwise.
756   */ public
757 boolean isSetName() {
758    return libsbmlJNI.Species_isSetName(swigCPtr, this);
759  }
760
761  
762/**
763   * Predicate returning <code>true</code> if this {@link Species} object's
764   * 'speciesType' attribute is set.
765   <p>
766   * @return <code>true</code> if the 'speciesType' attribute of this {@link Species} is
767   * set, <code>false</code> otherwise.
768   <p>
769   * @note The 'speciesType' attribute is only available in SBML
770   * Level&nbsp;2 Versions&nbsp;2&ndash;4.
771   */ public
772 boolean isSetSpeciesType() {
773    return libsbmlJNI.Species_isSetSpeciesType(swigCPtr, this);
774  }
775
776  
777/**
778   * Predicate returning <code>true</code> if this
779   * {@link Species} object's 'compartment' attribute is set.
780   <p>
781   * @return <code>true</code> if the 'compartment' attribute of this {@link Species} is
782   * set, <code>false</code> otherwise.
783   */ public
784 boolean isSetCompartment() {
785    return libsbmlJNI.Species_isSetCompartment(swigCPtr, this);
786  }
787
788  
789/**
790   * Predicate returning <code>true</code> if this
791   * {@link Species} object's 'initialAmount' attribute is set.
792   <p>
793   * @return <code>true</code> if the 'initialAmount' attribute of this {@link Species} is
794   * set, <code>false</code> otherwise.
795   <p>
796   * @note In SBML Level&nbsp;1, {@link Species}' 'initialAmount' is required and
797   * therefore <em>should always be set</em>.  (However, in Level&nbsp;1, the
798   * attribute has no default value either, so this method will not return
799   * <code>true</code> until a value has been assigned.)  In SBML Level&nbsp;2,
800   * 'initialAmount' is optional and as such may or may not be set.
801   */ public
802 boolean isSetInitialAmount() {
803    return libsbmlJNI.Species_isSetInitialAmount(swigCPtr, this);
804  }
805
806  
807/**
808   * Predicate returning <code>true</code> if this
809   * {@link Species} object's 'initialConcentration' attribute is set.
810   <p>
811   * @return <code>true</code> if the 'initialConcentration' attribute of this {@link Species} is
812   * set, <code>false</code> otherwise.
813   <p>
814   * @note The attribute 'initialConcentration' is only available in SBML
815   * Level&nbsp;2 and&nbsp;3.  It does not exist on {@link Species} in Level&nbsp;1.
816   */ public
817 boolean isSetInitialConcentration() {
818    return libsbmlJNI.Species_isSetInitialConcentration(swigCPtr, this);
819  }
820
821  
822/**
823   * Predicate returning <code>true</code> if this
824   * {@link Species} object's 'substanceUnits' attribute is set.
825   <p>
826   * @return <code>true</code> if the 'substanceUnits' attribute of this {@link Species} is
827   * set, <code>false</code> otherwise.
828   */ public
829 boolean isSetSubstanceUnits() {
830    return libsbmlJNI.Species_isSetSubstanceUnits(swigCPtr, this);
831  }
832
833  
834/**
835   * Predicate returning <code>true</code> if this
836   * {@link Species} object's 'spatialSizeUnits' attribute is set.
837   <p>
838   * @return <code>true</code> if the 'spatialSizeUnits' attribute of this {@link Species} is
839   * set, <code>false</code> otherwise.
840   <p>
841   * <p>
842 * @warning <span class='warning'>In versions of SBML Level&nbsp;2 before
843 * Version&nbsp;3, the class {@link Species} included an attribute called
844 * 'spatialSizeUnits', which allowed explicitly setting the units of size for
845 * initial concentration.  This attribute was removed in SBML Level&nbsp;2
846 * Version&nbsp;3.  LibSBML retains this attribute for compatibility with
847 * older definitions of Level&nbsp;2, but its use is strongly discouraged
848 * because it is incompatible with Level&nbsp;2 Version&nbsp;3 and
849 * Level&nbsp;2 Version&nbsp;4.</span>
850   */ public
851 boolean isSetSpatialSizeUnits() {
852    return libsbmlJNI.Species_isSetSpatialSizeUnits(swigCPtr, this);
853  }
854
855  
856/**
857   * Predicate returning <code>true</code> if
858   * this {@link Species} object's 'units' attribute is set.
859   <p>
860   * @return <code>true</code> if the 'units' attribute of this {@link Species} is
861   * set, <code>false</code> otherwise.
862   */ public
863 boolean isSetUnits() {
864    return libsbmlJNI.Species_isSetUnits(swigCPtr, this);
865  }
866
867  
868/**
869   * Predicate returning <code>true</code> if this
870   * {@link Species} object's 'charge' attribute is set.
871   <p>
872   * @return <code>true</code> if the 'charge' attribute of this {@link Species} is
873   * set, <code>false</code> otherwise.
874   <p>
875   * <p>
876 * @note Beginning in SBML Level&nbsp;2 Version&nbsp;2, the 'charge'
877 * attribute on {@link Species} is deprecated and in SBML Level&nbsp;3 it does
878 * not exist at all.  Its use strongly discouraged.  Its presence is
879 * considered a misfeature in earlier definitions of SBML because its
880 * implications for the mathematics of a model were never defined, and in
881 * any case, no known modeling system ever used it.  Instead, models take
882 * account of charge values directly in their definitions of species by
883 * (for example) having separate species identities for the charged and
884 * uncharged versions of the same species.  This allows the condition to
885 * affect model mathematics directly.  LibSBML retains this method for
886 * easier compatibility with SBML Level&nbsp;1. 
887   */ public
888 boolean isSetCharge() {
889    return libsbmlJNI.Species_isSetCharge(swigCPtr, this);
890  }
891
892  
893/**
894   * Predicate returning <code>true</code> if this
895   * {@link Species} object's 'conversionFactor' attribute is set.
896   <p>
897   * @return <code>true</code> if the 'conversionFactor' attribute of this {@link Species} is
898   * set, <code>false</code> otherwise.
899   <p>
900   * @note The 'conversionFactor' attribute was introduced in SBML
901   * Level&nbsp;3.  It does not exist on {@link Species} in SBML Levels&nbsp;1
902   * and&nbsp;2.
903   */ public
904 boolean isSetConversionFactor() {
905    return libsbmlJNI.Species_isSetConversionFactor(swigCPtr, this);
906  }
907
908  
909/**
910   * Predicate returning <code>true</code> if this
911   * {@link Species} object's 'boundaryCondition' attribute is set.
912   <p>
913   * @return <code>true</code> if the 'boundaryCondition' attribute of this {@link Species} is
914   * set, <code>false</code> otherwise.
915   */ public
916 boolean isSetBoundaryCondition() {
917    return libsbmlJNI.Species_isSetBoundaryCondition(swigCPtr, this);
918  }
919
920  
921/**
922   * Predicate returning <code>true</code> if this
923   * {@link Species} object's 'hasOnlySubstanceUnits' attribute is set.
924   <p>
925   * @return <code>true</code> if the 'hasOnlySubstanceUnits' attribute of this {@link Species} is
926   * set, <code>false</code> otherwise.
927   <p>
928   * @note The 'hasOnlySubstanceUnits' attribute does not exist in SBML
929   * Level&nbsp;1.
930   */ public
931 boolean isSetHasOnlySubstanceUnits() {
932    return libsbmlJNI.Species_isSetHasOnlySubstanceUnits(swigCPtr, this);
933  }
934
935  
936/**
937   * Predicate returning <code>true</code> if this
938   * {@link Species} object's 'constant' attribute is set.
939   <p>
940   * @return <code>true</code> if the 'constant' attribute of this {@link Species} is
941   * set, <code>false</code> otherwise.
942   <p>
943   * @note The attribute 'constant' is only available in SBML Levels&nbsp;2
944   * and&nbsp;3.  It does not exist on {@link Species} in Level&nbsp;1.
945   */ public
946 boolean isSetConstant() {
947    return libsbmlJNI.Species_isSetConstant(swigCPtr, this);
948  }
949
950  
951/**
952   * Sets the value of the 'id' attribute of this {@link Species} object.
953   <p>
954   * The string <code>sid</code> is copied.
955   <p>
956   * <p>
957 * SBML has strict requirements for the syntax of identifiers, that is, the
958 * values of the 'id' attribute present on most types of SBML objects.
959 * The following is a summary of the definition of the SBML identifier type 
960 * <code>SId</code>, which defines the permitted syntax of identifiers.  We
961 * express the syntax using an extended form of BNF notation: 
962 * <pre style='margin-left: 2em; border: none; font-weight: bold; font-size: 13px; color: black'>
963 * letter .= 'a'..'z','A'..'Z'
964 * digit  .= '0'..'9'
965 * idChar .= letter | digit | '_'
966 * SId    .= ( letter | '_' ) idChar*
967 * </pre>
968 * The characters <code>(</code> and <code>)</code> are used for grouping, the
969 * character <code>*</code> 'zero or more times', and the character
970 * <code>|</code> indicates logical 'or'.  The equality of SBML identifiers is
971 * determined by an exact character sequence match; i.e., comparisons must be
972 * performed in a case-sensitive manner.  In addition, there are a few
973 * conditions for the uniqueness of identifiers in an SBML model.  Please
974 * consult the SBML specifications for the exact details of the uniqueness
975 * requirements.
976   <p>
977   * @param sid the string to use as the identifier of this {@link Species}
978   <p>
979   * @return integer value indicating success/failure of the
980   * function.  The possible values
981   * returned by this function are:
982   * <ul>
983   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
984   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE }
985   * </ul>
986   */ public
987 int setId(String sid) {
988    return libsbmlJNI.Species_setId(swigCPtr, this, sid);
989  }
990
991  
992/**
993   * Sets the value of the 'name' attribute of this {@link Species} object.
994   <p>
995   * The string in <code>name</code> is copied.
996   <p>
997   * @param name the new name for the {@link Species}
998   <p>
999   * @return integer value indicating success/failure of the
1000   * function.  The possible values
1001   * returned by this function are:
1002   * <ul>
1003   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1004   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE }
1005   * </ul>
1006   */ public
1007 int setName(String name) {
1008    return libsbmlJNI.Species_setName(swigCPtr, this, name);
1009  }
1010
1011  
1012/**
1013   * Sets the 'speciesType' attribute of this {@link Species} object.
1014   <p>
1015   * @param sid the identifier of a {@link SpeciesType} object defined elsewhere
1016   * in this {@link Model}.
1017   <p>
1018   * @return integer value indicating success/failure of the
1019   * function.  The possible values
1020   * returned by this function are:
1021   * <ul>
1022   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1023   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE }
1024   * <li> {@link  libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE }
1025   *
1026   * </ul> <p>
1027   * @note The 'speciesType' attribute is only available in SBML
1028   * Level&nbsp;2 Versions&nbsp;2&ndash;4.
1029   */ public
1030 int setSpeciesType(String sid) {
1031    return libsbmlJNI.Species_setSpeciesType(swigCPtr, this, sid);
1032  }
1033
1034  
1035/**
1036   * Sets the 'compartment' attribute of this {@link Species} object.
1037   <p>
1038   * @param sid the identifier of a {@link Compartment} object defined elsewhere
1039   * in this {@link Model}.
1040   <p>
1041   * @return integer value indicating success/failure of the
1042   * function.  The possible values
1043   * returned by this function are:
1044   * <ul>
1045   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1046   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE }
1047   * </ul>
1048   */ public
1049 int setCompartment(String sid) {
1050    return libsbmlJNI.Species_setCompartment(swigCPtr, this, sid);
1051  }
1052
1053  
1054/**
1055   * Sets the 'initialAmount' attribute of this {@link Species} and marks the field
1056   * as set.
1057   <p>
1058   * This method also unsets the 'initialConcentration' attribute.
1059   <p>
1060   * @param value the value to which the 'initialAmount' attribute should
1061   * be set.
1062   <p>
1063   * @return integer value indicating success/failure of the
1064   * function.  The possible values
1065   * returned by this function are:
1066   * <ul>
1067   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1068   * </ul>
1069   */ public
1070 int setInitialAmount(double value) {
1071    return libsbmlJNI.Species_setInitialAmount(swigCPtr, this, value);
1072  }
1073
1074  
1075/**
1076   * Sets the 'initialConcentration' attribute of this {@link Species} and marks
1077   * the field as set.
1078   <p>
1079   * This method also unsets the 'initialAmount' attribute.
1080   <p>
1081   * @param value the value to which the 'initialConcentration' attribute
1082   * should be set.
1083   <p>
1084   * @return integer value indicating success/failure of the
1085   * function.  The possible values
1086   * returned by this function are:
1087   * <ul>
1088   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1089   * <li> {@link  libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE }
1090   *
1091   * </ul> <p>
1092   * @note The attribute 'initialConcentration' is only available in SBML
1093   * Level&nbsp;2 and&nbsp;3.  It does not exist on {@link Species} in Level&nbsp;1.
1094   */ public
1095 int setInitialConcentration(double value) {
1096    return libsbmlJNI.Species_setInitialConcentration(swigCPtr, this, value);
1097  }
1098
1099  
1100/**
1101   * Sets the 'substanceUnits' attribute of this {@link Species} object.
1102   <p>
1103   * @param sid the identifier of the unit to use.
1104   <p>
1105   * @return integer value indicating success/failure of the
1106   * function.  The possible values
1107   * returned by this function are:
1108   * <ul>
1109   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1110   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE }
1111   * </ul>
1112   */ public
1113 int setSubstanceUnits(String sid) {
1114    return libsbmlJNI.Species_setSubstanceUnits(swigCPtr, this, sid);
1115  }
1116
1117  
1118/**
1119   * (SBML Level&nbsp;2 Versions&nbsp;1&ndash;2) Sets the 'spatialSizeUnits' attribute of this {@link Species} object.
1120   <p>
1121   * @param sid the identifier of the unit to use.
1122   <p>
1123   * @return integer value indicating success/failure of the
1124   * function.  The possible values
1125   * returned by this function are:
1126   * <ul>
1127   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1128   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE }
1129   * <li> {@link  libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE }
1130   *
1131   * </ul> <p>
1132   * <p>
1133 * @warning <span class='warning'>In versions of SBML Level&nbsp;2 before
1134 * Version&nbsp;3, the class {@link Species} included an attribute called
1135 * 'spatialSizeUnits', which allowed explicitly setting the units of size for
1136 * initial concentration.  This attribute was removed in SBML Level&nbsp;2
1137 * Version&nbsp;3.  LibSBML retains this attribute for compatibility with
1138 * older definitions of Level&nbsp;2, but its use is strongly discouraged
1139 * because it is incompatible with Level&nbsp;2 Version&nbsp;3 and
1140 * Level&nbsp;2 Version&nbsp;4.</span>
1141   */ public
1142 int setSpatialSizeUnits(String sid) {
1143    return libsbmlJNI.Species_setSpatialSizeUnits(swigCPtr, this, sid);
1144  }
1145
1146  
1147/**
1148   * (SBML Level&nbsp;1 only) Sets the units of this {@link Species} object.
1149   <p>
1150   * @param sname the identifier of the unit to use.
1151   <p>
1152   * @return integer value indicating success/failure of the
1153   * function.  The possible values
1154   * returned by this function are:
1155   * <ul>
1156   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1157   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE }
1158   * </ul>
1159  */ public
1160 int setUnits(String sname) {
1161    return libsbmlJNI.Species_setUnits(swigCPtr, this, sname);
1162  }
1163
1164  
1165/**
1166   * Sets the 'hasOnlySubstanceUnits' attribute of this {@link Species} object.
1167   <p>
1168   * @param value boolean value for the 'hasOnlySubstanceUnits' attribute.
1169   <p>
1170   * @return integer value indicating success/failure of the
1171   * function.  The possible values
1172   * returned by this function are:
1173   * <ul>
1174   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1175   * <li> {@link  libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE }
1176   *
1177   * </ul> <p>
1178   * @note The 'hasOnlySubstanceUnits' attribute does not exist in SBML
1179   * Level&nbsp;1.
1180   */ public
1181 int setHasOnlySubstanceUnits(boolean value) {
1182    return libsbmlJNI.Species_setHasOnlySubstanceUnits(swigCPtr, this, value);
1183  }
1184
1185  
1186/**
1187   * Sets the 'boundaryCondition' attribute of this {@link Species} object.
1188   <p>
1189   * @param value boolean value for the 'boundaryCondition' attribute.
1190   <p>
1191   * @return integer value indicating success/failure of the
1192   * function.  The possible values
1193   * returned by this function are:
1194   * <ul>
1195   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1196   * </ul>
1197   */ public
1198 int setBoundaryCondition(boolean value) {
1199    return libsbmlJNI.Species_setBoundaryCondition(swigCPtr, this, value);
1200  }
1201
1202  
1203/**
1204   * Sets the 'charge' attribute of this {@link Species} object.
1205   <p>
1206   * @param value an integer to which to set the 'charge' to.
1207   <p>
1208   * <p>
1209 * @note Beginning in SBML Level&nbsp;2 Version&nbsp;2, the 'charge'
1210 * attribute on {@link Species} is deprecated and in SBML Level&nbsp;3 it does
1211 * not exist at all.  Its use strongly discouraged.  Its presence is
1212 * considered a misfeature in earlier definitions of SBML because its
1213 * implications for the mathematics of a model were never defined, and in
1214 * any case, no known modeling system ever used it.  Instead, models take
1215 * account of charge values directly in their definitions of species by
1216 * (for example) having separate species identities for the charged and
1217 * uncharged versions of the same species.  This allows the condition to
1218 * affect model mathematics directly.  LibSBML retains this method for
1219 * easier compatibility with SBML Level&nbsp;1. 
1220   <p>
1221   * @return integer value indicating success/failure of the
1222   * function.  The possible values
1223   * returned by this function are:
1224   * <ul>
1225   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1226   * <li> {@link  libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE }
1227   * </ul>
1228   */ public
1229 int setCharge(int value) {
1230    return libsbmlJNI.Species_setCharge(swigCPtr, this, value);
1231  }
1232
1233  
1234/**
1235   * Sets the 'constant' attribute of this {@link Species} object.
1236   <p>
1237   * @param value a boolean value for the 'constant' attribute
1238   <p>
1239   * @return integer value indicating success/failure of the
1240   * function.  The possible values
1241   * returned by this function are:
1242   * <ul>
1243   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1244   * <li> {@link  libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE }
1245   *
1246   * </ul> <p>
1247   * @note The attribute 'constant' is only available in SBML Levels&nbsp;2
1248   * and&nbsp;3.  It does not exist on {@link Species} in Level&nbsp;1.
1249   */ public
1250 int setConstant(boolean value) {
1251    return libsbmlJNI.Species_setConstant(swigCPtr, this, value);
1252  }
1253
1254  
1255/**
1256   * Sets the value of the 'conversionFactor' attribute of this {@link Species} object.
1257   <p>
1258   * The string in <code>sid</code> is copied.
1259   <p>
1260   * @param sid the new conversionFactor for the {@link Species}
1261   <p>
1262   * @return integer value indicating success/failure of the
1263   * function.  The possible values
1264   * returned by this function are:
1265   * <ul>
1266   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1267   * <li> {@link  libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE }
1268   * <li> {@link  libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE }
1269   *
1270   * </ul> <p>
1271   * @note The 'conversionFactor' attribute was introduced in SBML
1272   * Level&nbsp;3.  It does not exist on {@link Species} in SBML Levels&nbsp;1
1273   * and&nbsp;2.
1274   */ public
1275 int setConversionFactor(String sid) {
1276    return libsbmlJNI.Species_setConversionFactor(swigCPtr, this, sid);
1277  }
1278
1279  
1280/**
1281   * Unsets the value of the 'name' attribute of this {@link Species} object.
1282   <p>
1283   * @return integer value indicating success/failure of the
1284   * function.  The possible values
1285   * returned by this function are:
1286   * <ul>
1287   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1288   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
1289   * </ul>
1290   */ public
1291 int unsetName() {
1292    return libsbmlJNI.Species_unsetName(swigCPtr, this);
1293  }
1294
1295  
1296/**
1297   * Unsets the 'speciesType' attribute value of this {@link Species} object.
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_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
1305   *
1306   * </ul> <p>
1307   * @note The attribute 'speciesType' is only available in SBML
1308   * Level&nbsp;2 Versions&nbsp;2&ndash;4.
1309   */ public
1310 int unsetSpeciesType() {
1311    return libsbmlJNI.Species_unsetSpeciesType(swigCPtr, this);
1312  }
1313
1314  
1315/**
1316   * Unsets the 'initialAmount' attribute value of this {@link Species} object.
1317   <p>
1318   * @return integer value indicating success/failure of the
1319   * function.  The possible values
1320   * returned by this function are:
1321   * <ul>
1322   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1323   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
1324   * </ul>
1325   */ public
1326 int unsetInitialAmount() {
1327    return libsbmlJNI.Species_unsetInitialAmount(swigCPtr, this);
1328  }
1329
1330  
1331/**
1332   * Unsets the 'initialConcentration' attribute value of this {@link Species} object.
1333   <p>
1334   * @return integer value indicating success/failure of the
1335   * function.  The possible values
1336   * returned by this function are:
1337   * <ul>
1338   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1339   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
1340   *
1341   * </ul> <p>
1342   * @note The attribute 'initialConcentration' is only available in SBML
1343   * Level&nbsp;2 and&nbsp;3.  It does not exist on {@link Species} in Level&nbsp;1.
1344   */ public
1345 int unsetInitialConcentration() {
1346    return libsbmlJNI.Species_unsetInitialConcentration(swigCPtr, this);
1347  }
1348
1349  
1350/**
1351   * Unsets the 'substanceUnits' attribute value of this {@link Species} object.
1352   <p>
1353   * @return integer value indicating success/failure of the
1354   * function.  The possible values
1355   * returned by this function are:
1356   * <ul>
1357   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1358   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
1359   * </ul>
1360   */ public
1361 int unsetSubstanceUnits() {
1362    return libsbmlJNI.Species_unsetSubstanceUnits(swigCPtr, this);
1363  }
1364
1365  
1366/**
1367   * Unsets the 'spatialSizeUnits' attribute value of this {@link Species} object.
1368   <p>
1369   * @return integer value indicating success/failure of the
1370   * function.  The possible values
1371   * returned by this function are:
1372   * <ul>
1373   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1374   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
1375   *
1376   * </ul> <p>
1377   * <p>
1378 * @warning <span class='warning'>In versions of SBML Level&nbsp;2 before
1379 * Version&nbsp;3, the class {@link Species} included an attribute called
1380 * 'spatialSizeUnits', which allowed explicitly setting the units of size for
1381 * initial concentration.  This attribute was removed in SBML Level&nbsp;2
1382 * Version&nbsp;3.  LibSBML retains this attribute for compatibility with
1383 * older definitions of Level&nbsp;2, but its use is strongly discouraged
1384 * because it is incompatible with Level&nbsp;2 Version&nbsp;3 and
1385 * Level&nbsp;2 Version&nbsp;4.</span>
1386   */ public
1387 int unsetSpatialSizeUnits() {
1388    return libsbmlJNI.Species_unsetSpatialSizeUnits(swigCPtr, this);
1389  }
1390
1391  
1392/**
1393   * Unsets the 'units' attribute value of this {@link Species} object.
1394   <p>
1395   * @return integer value indicating success/failure of the
1396   * function.  The possible values
1397   * returned by this function are:
1398   * <ul>
1399   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1400   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
1401   * </ul>
1402   */ public
1403 int unsetUnits() {
1404    return libsbmlJNI.Species_unsetUnits(swigCPtr, this);
1405  }
1406
1407  
1408/**
1409   * Unsets the 'charge' attribute
1410   * value of this {@link Species} object.
1411   <p>
1412   * @return integer value indicating success/failure of the
1413   * function.  The possible values
1414   * returned by this function are:
1415   * <ul>
1416   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1417   * <li> {@link  libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE }
1418   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
1419   *
1420   * </ul> <p>
1421   * <p>
1422 * @note Beginning in SBML Level&nbsp;2 Version&nbsp;2, the 'charge'
1423 * attribute on {@link Species} is deprecated and in SBML Level&nbsp;3 it does
1424 * not exist at all.  Its use strongly discouraged.  Its presence is
1425 * considered a misfeature in earlier definitions of SBML because its
1426 * implications for the mathematics of a model were never defined, and in
1427 * any case, no known modeling system ever used it.  Instead, models take
1428 * account of charge values directly in their definitions of species by
1429 * (for example) having separate species identities for the charged and
1430 * uncharged versions of the same species.  This allows the condition to
1431 * affect model mathematics directly.  LibSBML retains this method for
1432 * easier compatibility with SBML Level&nbsp;1. 
1433   */ public
1434 int unsetCharge() {
1435    return libsbmlJNI.Species_unsetCharge(swigCPtr, this);
1436  }
1437
1438  
1439/**
1440   * Unsets the 'conversionFactor' attribute value of this {@link Species} object.
1441   <p>
1442   * @return integer value indicating success/failure of the
1443   * function. The possible values
1444   * returned by this function are:
1445   * <ul>
1446   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS }
1447   * <li> {@link  libsbmlConstants#LIBSBML_UNEXPECTED_ATTRIBUTE LIBSBML_UNEXPECTED_ATTRIBUTE }
1448   * <li> {@link  libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED }
1449   *
1450   * </ul> <p>
1451   * @note The 'conversionFactor' attribute was introduced in SBML
1452   * Level&nbsp;3.  It does not exist on {@link Species} in SBML Levels&nbsp;1
1453   * and&nbsp;2.
1454   */ public
1455 int unsetConversionFactor() {
1456    return libsbmlJNI.Species_unsetConversionFactor(swigCPtr, this);
1457  }
1458
1459  
1460/**
1461   * Constructs and returns a {@link UnitDefinition} that corresponds to the units
1462   * of this {@link Species}' amount or concentration.
1463   <p>
1464   * {@link Species} in SBML have an attribute ('substanceUnits') for declaring the
1465   * units of measurement intended for the species' amount or concentration
1466   * (depending on which one applies).  In the absence of a value given for
1467   * 'substanceUnits', the units are taken from the enclosing {@link Model}'s
1468   * definition of <code>'substance'</code> or <code>'substance'</code>/<em>(size of the
1469   * compartment)</em> in which the species is located, or finally, if
1470   * these are not redefined by the {@link Model}, the relevant SBML default units
1471   * for those quantities.  Following that procedure, the method
1472   * {@link Species#getDerivedUnitDefinition()}
1473   * returns a {@link UnitDefinition} based on the
1474   * interpreted units of this species's amount or concentration.
1475   <p>
1476   * Note that the functionality that facilitates unit analysis depends 
1477   * on the model as a whole.  Thus, in cases where the object has not 
1478   * been added to a model or the model itself is incomplete,
1479   * unit analysis is not possible and this method will return <code>null.</code>
1480   <p>
1481   * Note also that unit declarations for {@link Species} are in terms of the 
1482   * <em>identifier</em> of a unit, but this method returns a {@link UnitDefinition} object,
1483   * not a unit identifier.  It does this by constructing an appropriate
1484   * {@link UnitDefinition}.  Callers may find this particularly useful when used
1485   * in conjunction with the helper methods on {@link UnitDefinition} for comparing
1486   * different {@link UnitDefinition} objects.
1487   <p>
1488   * In SBML Level&nbsp;2 specifications prior to Version&nbsp;3, {@link Species}
1489   * includes an additional attribute named 'spatialSizeUnits', which
1490   * allows explicitly setting the units of size for initial concentration.
1491   * The {@link Species#getDerivedUnitDefinition()}
1492   * takes this into account for models
1493   * expressed in SBML Level&nbsp;2 Versions&nbsp;1 and&nbsp;2.
1494   <p>
1495   * @return a {@link UnitDefinition} that expresses the units of this 
1496   * {@link Species}, or <code>null</code> if one cannot be constructed.
1497   <p>
1498   * @see #getSubstanceUnits()
1499   */ public
1500 UnitDefinition getDerivedUnitDefinition() {
1501    long cPtr = libsbmlJNI.Species_getDerivedUnitDefinition__SWIG_0(swigCPtr, this);
1502    return (cPtr == 0) ? null : new UnitDefinition(cPtr, false);
1503  }
1504
1505  
1506/**
1507   * Returns the libSBML type code for this SBML object.
1508   <p>
1509   * <p>
1510 * LibSBML attaches an identifying code to every kind of SBML object.  These
1511 * are integer constants known as <em>SBML type codes</em>.  The names of all
1512 * the codes begin with the characters &ldquo;<code>SBML_</code>&rdquo;. 
1513 * In the Java language interface for libSBML, the
1514 * type codes are defined as static integer constants in the interface class
1515 * {@link libsbmlConstants}.    Note that different Level&nbsp;3 
1516 * package plug-ins may use overlapping type codes; to identify the package
1517 * to which a given object belongs, call the <code>getPackageName()</code>
1518 * method on the object.
1519   <p>
1520   * @return the SBML type code for this object:
1521   * {@link  libsbmlConstants#SBML_SPECIES SBML_SPECIES} (default).
1522   <p>
1523   * <p>
1524 * @warning <span class='warning'>The specific integer values of the possible
1525 * type codes may be reused by different Level&nbsp;3 package plug-ins.
1526 * Thus, to identifiy the correct code, <strong>it is necessary to invoke
1527 * both getTypeCode() and getPackageName()</strong>.</span>
1528   <p>
1529   * @see #getElementName()
1530   * @see #getPackageName()
1531   */ public
1532 int getTypeCode() {
1533    return libsbmlJNI.Species_getTypeCode(swigCPtr, this);
1534  }
1535
1536  
1537/**
1538   * Returns the XML element name of this object, which for {@link Species}, is
1539   * always <code>'species'.</code>
1540   <p>
1541   * @return the name of this element, i.e., <code>'species'.</code>
1542   */ public
1543 String getElementName() {
1544    return libsbmlJNI.Species_getElementName(swigCPtr, this);
1545  }
1546
1547  
1548/**
1549   * Predicate returning <code>true</code> if
1550   * all the required attributes for this {@link Species} object
1551   * have been set.
1552   <p>
1553   * @note The required attributes for a {@link Species} object are:
1554   * <ul>
1555   * <li> 'id' (or 'name' in SBML Level&nbsp;1)
1556   * <li> 'compartment'
1557   * <li> 'initialAmount' (required in SBML Level&nbsp;1 only; optional otherwise)
1558   * <li> 'hasOnlySubstanceUnits' (required in SBML Level&nbsp;3; optional in SBML Level&nbsp;2)
1559   * <li> 'boundaryCondition' (required in SBML Level&nbsp;3; optional in Levels&nbsp;1 and&nbsp;2)
1560   * <li> 'constant' (required in SBML Level&nbsp;3; optional in SBML Level&nbsp;2)
1561   *
1562   * </ul> <p>
1563   * @return a boolean value indicating whether all the required
1564   * attributes for this object have been defined.
1565   */ public
1566 boolean hasRequiredAttributes() {
1567    return libsbmlJNI.Species_hasRequiredAttributes(swigCPtr, this);
1568  }
1569
1570  
1571/**
1572   * Renames all the <code>SIdRef</code> attributes on this element, including any
1573   * found in MathML.
1574   <p>
1575   * <p>
1576 * In SBML, object identifiers are of a data type called <code>SId</code>.
1577 * In SBML Level&nbsp;3, an explicit data type called <code>SIdRef</code> was
1578 * introduced for attribute values that refer to <code>SId</code> values; in
1579 * previous Levels of SBML, this data type did not exist and attributes were
1580 * simply described to as 'referring to an identifier', but the effective
1581 * data type was the same as <code>SIdRef</code>in Level&nbsp;3.  These and
1582 * other methods of libSBML refer to the type <code>SIdRef</code> for all
1583 * Levels of SBML, even if the corresponding SBML specification did not
1584 * explicitly name the data type.
1585   <p>
1586   * This method works by looking at all attributes and (if appropriate)
1587   * mathematical formulas, comparing the identifiers to the value of 
1588   * <code>oldid</code>.  If any matches are found, the matching identifiers are replaced
1589   * with <code>newid</code>.  The method does <em>not</em> descend into child elements.
1590   <p>
1591   * @param oldid the old identifier
1592   * @param newid the new identifier
1593   */ public
1594 void renameSIdRefs(String oldid, String newid) {
1595    libsbmlJNI.Species_renameSIdRefs(swigCPtr, this, oldid, newid);
1596  }
1597
1598  
1599/**
1600   * Renames all the <code>UnitSIdRef</code> attributes on this element.
1601   <p>
1602   * <p>
1603 * In SBML, unit definitions have identifiers of type <code>UnitSId</code>.  In
1604 * SBML Level&nbsp;3, an explicit data type called <code>UnitSIdRef</code> was
1605 * introduced for attribute values that refer to <code>UnitSId</code> values; in
1606 * previous Levels of SBML, this data type did not exist and attributes were
1607 * simply described to as 'referring to a unit identifier', but the effective
1608 * data type was the same as <code>UnitSIdRef</code> in Level&nbsp;3.  These and
1609 * other methods of libSBML refer to the type <code>UnitSIdRef</code> for all
1610 * Levels of SBML, even if the corresponding SBML specification did not
1611 * explicitly name the data type.
1612   <p>
1613   * This method works by looking at all unit identifier attribute values
1614   * (including, if appropriate, inside mathematical formulas), comparing the
1615   * unit identifiers to the value of <code>oldid</code>.  If any matches are found,
1616   * the matching identifiers are replaced with <code>newid</code>.  The method does
1617   * <em>not</em> descend into child elements.
1618   <p>
1619   * @param oldid the old identifier
1620   * @param newid the new identifier
1621   */ public
1622 void renameUnitSIdRefs(String oldid, String newid) {
1623    libsbmlJNI.Species_renameUnitSIdRefs(swigCPtr, this, oldid, newid);
1624  }
1625
1626}