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