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