Detailed Description

An SBML species – a pool of entities.

A species in SBML refers to a pool of entities that (a) are considered indistinguishable from each other for the purposes of the model, (b) participate in reactions, and (c) are located in a specific compartment. The SBML Species_t object class is intended to represent these pools.

As with other major constructs in SBML, Species_t has a mandatory attribute, "id", used to give the species type an identifier in the model. The identifier must be a text string conforming to the identifer syntax permitted in SBML. Species_t also has an optional "name" attribute, of type string. The "id" and "name" must be used according to the guidelines described in the SBML specifications.

The required attribute "compartment" is used to identify the compartment in which the species is located. The attribute's value must be the identifier of an existing Compartment_t object. It is important to note that there is no default value for the "compartment" attribute on Species_t; every species in an SBML model must be assigned a compartment explicitly. (This also implies that every model with one or more Species_t objects must define at least one Compartment_t object.)

The initial amount and concentration of a species

The optional attributes "initialAmount" and "initialConcentration", both having a data type of double, can be used to set the initial quantity of the species in the compartment where the species is located. These attributes are mutually exclusive; i.e., only one can have a value on any given instance of a Species_t object. Missing "initialAmount" and "initialConcentration" values implies that their values either are unknown, or to be obtained from an external source, or determined by an InitialAssignment_t or other SBML construct elsewhere in the model.

A species' initial quantity in SBML is set by the "initialAmount" or "initialConcentration" attribute exactly once. If the "constant" attribute is true, then the value of the species' quantity is fixed and cannot be changed except by an InitialAssignment_t. These methods differ in that the "initialAmount" and "initialConcentration" attributes can only be used to set the species quantity to a literal floating-point number, whereas the use of an InitialAssignment_t object allows the value to be set using an arbitrary mathematical expression (which, thanks to MathML's expressiveness, may evaluate to a rational number). If the species' "constant" attribute is false, the species' quantity value may be overridden by an InitialAssignment_t or changed by AssignmentRule_t or AlgebraicRule_t, and in addition, for t > 0, it may also be changed by a RateRule_t, Event_t objects, and as a result of being a reactant or product in one or more Reaction_t objects. (However, some constructs are mutually exclusive; see the SBML specifications for the precise details.) It is not an error to define "initialAmount" or "initialConcentration" on a species and also redefine the value using an InitialAssignment_t, but the "initialAmount" or "initialConcentration" setting in that case is ignored. The SBML specifications provide additional information about the semantics of assignments, rules and values for simulation time t $\leq$ 0.

SBML Level 2 additionally stipulates that in cases where a species' compartment has a "spatialDimensions" value of 0 (zero), the species cannot have a value for "initialConcentration" because the concepts of concentration and density break down when a container has zero dimensions.

The units of a species' amount or concentration

When the attribute "initialAmount" is set, the unit of measurement associated with the value of "initialAmount" is specified by the Species_t attribute "substanceUnits". When the "initialConcentration" attribute is set, the unit of measurement associated with this concentration value is {unit of amount} divided by {unit of size}, where the {unit of amount} is specified by the Species_t "substanceUnits" attribute, and the {unit of size} is specified by the "units" attribute of the Compartment_t object in which the species is located. Note that in either case, a unit of amount is involved and determined by the "substanceUnits" attribute. Note these two attributes alone do not determine the units of the species when the species identifier appears in a mathematical expression; that aspect is determined by the attribute "hasOnlySubstanceUnits" discussed below.

In SBML Level 3, if the "substanceUnits" attribute is not set on a given Species_t object instance, then the unit of amount for that species is inherited from the "substanceUnits" attribute on the enclosing Model_t object instance. If that attribute on Model_t is not set either, then the unit associated with the species' quantity is undefined.

In SBML Level 2, if the "substanceUnits" attribute is not set on a given Species_t object instance, then the unit of amount for that species is taken from the predefined SBML unit identifier "substance". The value assigned to "substanceUnits" must be chosen from one of the following possibilities: one of the base unit identifiers defined in SBML, the built-in unit identifier "substance", or the identifier of a new unit defined in the list of unit definitions in the enclosing Model_t object. The chosen units for "substanceUnits" must be be "dimensionless", "mole", "item", "kilogram", "gram", or units derived from these.

As noted at the beginning of this section, simply setting "initialAmount" or "initialConcentration" alone does not determine whether a species identifier represents an amount or a concentration when it appears elsewhere in an SBML model. The role of the attribute "hasOnlySubstanceUnits" is to indicate whether the units of the species, when the species identifier appears in mathematical formulas, are intended to be concentration or amount. The attribute takes on a boolean value. In SBML Level 3, the attribute has no default value and must always be set in a model; in SBML Level 2, it has a default value of false.

The units of the species are used in the following ways:

When the species' identifier appears in a MathML formula, it represents the species' quantity, and the unit of measurement associated with the quantity is as described above.
The "math" elements of AssignmentRule_t, InitialAssignment_t and EventAssignment_t objects referring to this species should all have the same units as the unit of measurement associated with the species quantity.
In a RateRule_t object that defines the rate of change of the species' quantity, the unit associated with the rule's "math" element should be equal to the unit of the species' quantity divided by the model-wide unit of time; in other words, {unit of species quantity}/{unit of time}.

The "constant" and "boundaryCondition" attributes

The Species_t object class has two boolean attributes named "constant" and "boundaryCondition", used to indicate whether and how the quantity of that species can vary during a simulation. In SBML Level 2 they are optional; in SBML Level 3 they are mandatory. The following table shows how to interpret the combined values of these attributes.

Interpretation of species' `constant` and `boundaryCondition` attributes.
`constant` value	`boundaryCondition` value	Can have assignment or rate rule?	Can be reactant or product?	Species' quantity can be changed by
`true`	`true`	no	yes	(never changes)
`false`	`true`	yes	yes	rules and events
`true`	`false`	no	no	(never changes)
`false`	`false`	yes	yes	reactions or rules (but not both at the same time), and events

By default, when a species is a product or reactant of one or more reactions, its quantity is determined by those reactions. In SBML, it is possible to indicate that a given species' quantity is not determined by the set of reactions even when that species occurs as a product or reactant; i.e., the species is on the boundary of the reaction system, and its quantity is not determined by the reactions. The boolean attribute "boundaryCondition" can be used to indicate this. A value of false indicates that the species is part of the reaction system. In SBML Level 2, the attribute has a default value of false, while in SBML Level 3, it has no default.

The "constant" attribute indicates whether the species' quantity can be changed at all, regardless of whether by reactions, rules, or constructs other than InitialAssignment_t. A value of false indicates that the species' quantity can be changed. (This is also a common value because the purpose of most simulations is precisely to calculate changes in species quantities.) In SBML Level 2, the attribute has a default value of false, while in SBML Level 3, it has no default. Note that the initial quantity of a species can be set by an InitialAssignment_t irrespective of the value of the "constant" attribute.

In practice, a "boundaryCondition" value of true means a differential equation derived from the reaction definitions should not be generated for the species. However, the species' quantity may still be changed by AssignmentRule_t, RateRule_t, AlgebraicRule_t, Event_t, and InitialAssignment_t constructs if its "constant" attribute is false. Conversely, if the species' "constant" attribute is true, then its value cannot be changed by anything except InitialAssignment_t.

A species having "boundaryCondition"=false and "constant"=false can appear as a product and/or reactant of one or more reactions in the model. If the species is a reactant or product of a reaction, it must not also appear as the target of any AssignmentRule_t or RateRule_t object in the model. If instead the species has "boundaryCondition"= false and "constant"=true, then it cannot appear as a reactant or product, or as the target of any AssignmentRule_t, RateRule_t or EventAssignment_t object in the model.

Finally, it is worth clarifying that while the constant and boundaryCondition attributes restrict whether and how the species amount changes, the same is not true of a species' concentration. In SBML, the concentration of a species is a quantity that depends on the size of the compartment in which it is located. A compartment's size may change, and therefore, so can the concentration of a species even if the amount of the species remains unchanged. A species' concentration may therefore vary even if the Species_t object's constant attribute is set to true in a model.

The conversionFactor attribute in SBML Level 3

In SBML Level 3, Species_t has an additional optional attribute, "conversionFactor", that defines a conversion factor that applies to a particular species. The value must be the identifier of a Parameter_t object instance defined in the model. That Parameter_t object must be a constant, meaning its "constant" attribute must be set to true. If a given Species_t object definition defines a value for its "conversionFactor" attribute, it takes precedence over any factor defined by the Model_t object's "conversionFactor" attribute.

The unit of measurement associated with a species' quantity can be different from the unit of extent of reactions in the model. SBML Level 3 avoids implicit unit conversions by providing an explicit way to indicate any unit conversion that might be required. The use of a conversion factor in computing the effects of reactions on a species' quantity is explained in detail in the SBML Level 3 specification document. Because the value of the "conversionFactor" attribute is the identifier of a Parameter_t object, and because parameters can have units attached to them, the transformation from reaction extent units to species units can be completely specified using this approach.

Note that the unit conversion factor is only applied when calculating the effect of a reaction on a species. It is not used in any rules or other SBML constructs that affect the species, and it is also not used when the value of the species is referenced in a mathematical expression.

The speciesType attribute in SBML Level 2 Versions 2–4

In SBML Level 2 Versions 2–4, each species in a model may optionally be designated as belonging to a particular species type. The optional attribute "speciesType" is used to identify the species type of the chemical entities that make up the pool represented by the Species_t objects. The attribute's value must be the identifier of an existing SpeciesType_t object in the model. If the "speciesType" attribute is not present on a particular species definition, it means the pool contains chemical entities of a type unique to that pool; in effect, a virtual species type is assumed for that species, and no other species can belong to that species type. The value of "speciesType" attributes on species have no effect on the numerical interpretation of a model; simulators and other numerical analysis software may ignore "speciesType" attributes.

There can be only one species of a given species type in any given compartment of a model. More specifically, for all Species_t objects having a value for the "speciesType" attribute, the pair

("speciesType" attribute value, "compartment" attribute value)

must be unique across the set of all Species_t object in a model.

The spatialSizeUnits attribute in SBML Level 2 Versions 1–2

In versions of SBML Level 2 before Version 3, the class Species_t included an attribute called "spatialSizeUnits", which allowed explicitly setting the units of size for initial concentration. LibSBML retains this attribute for compatibility with older definitions of Level 2, but its use is strongly discouraged because many software tools do no properly interpret this unit declaration and it is incompatible with all SBML specifications after Level 2 Version 3.

Additional considerations for interpreting the numerical value of a species

Species_t are unique in SBML in that they have a kind of duality: a species identifier may stand for either substance amount (meaning, a count of the number of individual entities) or a concentration or density (meaning, amount divided by a compartment size). The previous sections explain the meaning of a species identifier when it is referenced in a mathematical formula or in rules or other SBML constructs; however, it remains to specify what happens to a species when the compartment in which it is located changes in size.

When a species definition has a "hasOnlySubstanceUnits" attribute value of false and the size of the compartment in which the species is located changes, the default in SBML is to assume that it is the concentration that must be updated to account for the size change. This follows from the principle that, all other things held constant, if a compartment simply changes in size, the size change does not in itself cause an increase or decrease in the number of entities of any species in that compartment. In a sense, the default is that the amount of a species is preserved across compartment size changes. Upon such size changes, the value of the concentration or density must be recalculated from the simple relationship concentration = amount / size if the value of the concentration is needed (for example, if the species identifier appears in a mathematical formula or is otherwise referenced in an SBML construct). There is one exception: if the species' quantity is determined by an AssignmentRule_t, RateRule_t, AlgebraicRule_t, or an EventAssignment_t and the species has a "hasOnlySubstanceUnits" attribute value of false, it means that the concentration is assigned by the rule or event; in that case, the amount must be calculated when the compartment size changes. (Events also require additional care in this situation, because an event with multiple assignments could conceivably reassign both a species quantity and a compartment size simultaneously. Please refer to the SBML specifications for the details.)

Note that the above only matters if a species has a "hasOnlySubstanceUnits" attribute value of false, meaning that the species identifier refers to a concentration wherever the identifier appears in a mathematical formula. If instead the attribute's value is true, then the identifier of the species always stands for an amount wherever it appears in a mathematical formula or is referenced by an SBML construct. In that case, there is never a question about whether an assignment or event is meant to affect the amount or concentration: it is always the amount.

A particularly confusing situation can occur when the species has "constant" attribute value of true in combination with a "hasOnlySubstanceUnits" attribute value of false. Suppose this species is given a value for "initialConcentration". Does a "constant" value of true mean that the concentration is held constant if the compartment size changes? No; it is still the amount that is kept constant across a compartment size change. The fact that the species was initialized using a concentration value is irrelevant.

Examples:: addCVTerms.c, addingEvidenceCodes_2.c, appendAnnotation.c, createExampleSBML.c, printAnnotation.c, printNotes.c, printUnits.c, spec_example1.c, unsetAnnotation.c, and unsetNotes.c.

Public Member Functions
Species_t *	Species_clone (const Species_t *s)
	Creates a deep copy of the given Species_t structure. More...

Species_t *	Species_create (unsigned int level, unsigned int version)
	Creates a new Species_t structure using the given SBML `level` and `version` values. More...

Species_t *	Species_createWithNS (SBMLNamespaces_t *sbmlns)
	Creates a new Species_t structure using the given SBMLNamespaces_t structure. More...

void	Species_free (Species_t *s)
	Frees the given Species_t structure. More...

int	Species_getBoundaryCondition (const Species_t *s)
	Get the value of the "boundaryCondition" attribute. More...

int	Species_getCharge (const Species_t *s)
	Get the value of the "charge" attribute. More...

const char *	Species_getCompartment (const Species_t *s)
	Get the compartment in which this species is located. More...

int	Species_getConstant (const Species_t *s)
	Get the value of the "constant" attribute. More...

const char *	Species_getConversionFactor (const Species_t *s)
	Get the value of the "conversionFactor" attribute. More...

UnitDefinition_t *	Species_getDerivedUnitDefinition (Species_t *s)
	Constructs and returns a UnitDefinition_t structure that expresses the units of this Species_t structure. More...

int	Species_getHasOnlySubstanceUnits (const Species_t *s)
	Get the value of the "hasOnlySubstanceUnits" attribute. More...

const char *	Species_getId (const Species_t *s)
	Takes a Species_t structure and returns its identifier. More...

double	Species_getInitialAmount (const Species_t *s)
	Get the value of the "initialAmount" attribute. More...

double	Species_getInitialConcentration (const Species_t *s)
	Get the value of the "initialConcentration" attribute. More...

const char *	Species_getName (const Species_t *s)
	Takes a Species_t structure and returns its name. More...

const XMLNamespaces_t *	Species_getNamespaces (Species_t *s)
	Returns a list of XMLNamespaces_t associated with this Species_t structure. More...

const char *	Species_getSpatialSizeUnits (const Species_t *s)
	Get the value of the "spatialSizeUnits" attribute. More...

const char *	Species_getSpeciesType (const Species_t *s)
	Get the species type of this Species_t structure, as indicated by the Species_t structure's "speciesType" attribute value. More...

const char *	Species_getSubstanceUnits (const Species_t *s)
	Get the value of the "substanceUnit" attribute. More...

const char *	Species_getUnits (const Species_t *s)
	(SBML Level 1 only) Get the value of the "units" attribute. More...

int	Species_hasRequiredAttributes (Species_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether all the required attributes for this Species_t structure have been set. More...

void	Species_initDefaults (Species_t *s)
	Initializes the attributes of the given Species_t structure to the defaults defined in the specification of the relevant Level/Version of SBML. More...

int	Species_isSetBoundaryCondition (const Species_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the attribute "boundaryCondition" of the given Species_t structure is set. More...

int	Species_isSetCharge (const Species_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the attribute "charge" of the given Species_t structure is set. More...

int	Species_isSetCompartment (const Species_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the attribute "compartment" of the given Species_t structure is set. More...

int	Species_isSetConstant (const Species_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the attribute "constant" of the given Species_t structure is set. More...

int	Species_isSetConversionFactor (const Species_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the attribute "conversionFactor" of the given Species_t structure is set. More...

int	Species_isSetHasOnlySubstanceUnits (const Species_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the attribute "hasOnlySubstanceUnits" of the given Species_t structure is set. More...

int	Species_isSetId (const Species_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the attribute "id" of the given Species_t structure is set. More...

int	Species_isSetInitialAmount (const Species_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the attribute "initialAmount" of the given Species_t structure is set. More...

int	Species_isSetInitialConcentration (const Species_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the attribute "compartment" of the given Species_t structure is set. More...

int	Species_isSetName (const Species_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the attribute "name" of the given Species_t structure is set. More...

int	Species_isSetSpatialSizeUnits (const Species_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the attribute "spatialSizeUnits" of the given Species_t structure is set. More...

int	Species_isSetSpeciesType (const Species_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the attribute "speciesType" of the given Species_t structure is set. More...

int	Species_isSetSubstanceUnits (const Species_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the attribute "substanceUnits" of the given Species_t structure is set. More...

int	Species_isSetUnits (const Species_t *s)
	(SBML Level 1 only) Predicate returning `1` (true) or `0` (false) depending on whether the attribute "units" of the given Species_t structure is set. More...

int	Species_setBoundaryCondition (Species_t *s, int value)
	Sets the "boundaryCondition" attribute of the given Species_t structure. More...

int	Species_setCharge (Species_t *s, int value)
	Sets the "charge" attribute of the given Species_t structure. More...

int	Species_setCompartment (Species_t s, const char sid)
	Sets the "compartment" attribute of the given Species_t structure. More...

int	Species_setConstant (Species_t *s, int value)
	Sets the "constant" attribute of the given Species_t structure. More...

int	Species_setConversionFactor (Species_t s, const char sid)
	Sets the "conversionFactor" attribute of the given Species_t structure. More...

int	Species_setHasOnlySubstanceUnits (Species_t *s, int value)
	Sets the "hasOnlySubstanceUnits" attribute of the given Species_t structure. More...

int	Species_setId (Species_t s, const char sid)
	Sets the "id" attribute of the given Species_t structure. More...

int	Species_setInitialAmount (Species_t *s, double value)
	Sets the "initialAmount" attribute value of the given Species_t structure. More...

int	Species_setInitialConcentration (Species_t *s, double value)
	Sets the "initialConcentration" attribute value of the given Species_t structure. More...

int	Species_setName (Species_t s, const char name)
	Sets the "name" attribute of the given Species_t structure. More...

int	Species_setSpatialSizeUnits (Species_t s, const char sid)
	Sets the "spatialSizeUnits" attribute of the given Species_t structure. More...

int	Species_setSpeciesType (Species_t s, const char sid)
	Sets the "speciesType" attribute of the given Species_t structure. More...

int	Species_setSubstanceUnits (Species_t s, const char sid)
	Sets the "substanceUnits" attribute of the given Species_t structure. More...

int	Species_setUnits (Species_t s, const char sname)
	(SBML Level 1 only) Sets the "units" attribute of the given Species_t structure. More...

int	Species_unsetBoundaryCondition (Species_t *s)
	Unsets the "boundaryCondition" attribute of the given Species_t structure. More...

int	Species_unsetCharge (Species_t *s)
	Unsets the "charge" attribute of the given Species_t structure. More...

int	Species_unsetCompartment (Species_t *s)
	Unsets the "compartment" attribute of the given Species_t structure. More...

int	Species_unsetConstant (Species_t *c)
	Unsets the value of the "constant" attribute of the given Species_t structure. More...

int	Species_unsetConversionFactor (Species_t *s)
	Unsets the "conversionFactor" attribute of the given Species_t structure. More...

int	Species_unsetHasOnlySubstanceUnits (Species_t *s)
	Unsets the "hasOnlySubstanceUnits" attribute of the given Species_t structure. More...

int	Species_unsetId (Species_t *s)
	Unsets the "id" attribute of the given Species_t structure. More...

int	Species_unsetInitialAmount (Species_t *s)
	Unsets the "initialAmount" attribute of the given Species_t structure. More...

int	Species_unsetInitialConcentration (Species_t *s)
	Unsets the "initialConcentration" attribute of the given Species_t structure. More...

int	Species_unsetName (Species_t *s)
	Unsets the "name" attribute of the given Species_t structure. More...

int	Species_unsetSpatialSizeUnits (Species_t *s)
	Unsets the "spatialSizeUnits" attribute of the given Species_t structure. More...

int	Species_unsetSpeciesType (Species_t *s)
	Unsets the "speciesType" attribute of the given Species_t structure. More...

int	Species_unsetSubstanceUnits (Species_t *s)
	Unsets the "substanceUnits" attribute of the given Species_t structure. More...

int	Species_unsetUnits (Species_t *s)
	Unsets the "units" attribute of the given Species_t structure. More...

Member Function Documentation

Species_t * Species_clone ( const Species_t * s )

Creates a deep copy of the given Species_t structure.

Parameters

s	the Species_t structure to be copied.

Returns: a (deep) copy of the given Species_t structure.

Species_t * Species_create	(	unsigned int	level,
		unsigned int	version
	)

Creates a new Species_t structure using the given SBML level and version values.

Parameters

level	an unsigned int, the SBML Level to assign to this Species_t.
version	an unsigned int, the SBML Version to assign to this Species_t.

Returns: a pointer to the newly created Species_t structure.

Note: Attempting to add an object to an SBMLDocument_t having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument_t), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Species_t * Species_createWithNS ( SBMLNamespaces_t * sbmlns )

Creates a new Species_t structure using the given SBMLNamespaces_t structure.

Parameters

sbmlns SBMLNamespaces_t, a pointer to an SBMLNamespaces_t structure to assign to this Species_t.

Returns: a pointer to the newly created Species_t structure.

Note: Attempting to add an object to an SBMLDocument_t having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument_t), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

void Species_free ( Species_t * s )

Frees the given Species_t structure.

Parameters

s	the Species_t structure to be freed.

int Species_getBoundaryCondition ( const Species_t * s )

Get the value of the "boundaryCondition" attribute.

Parameters

s	the Species_t structure.

Returns: 1 (true) or 0 (false) depending on the value of the given Species_t structure's "boundaryCondition" attribute value.

int Species_getCharge ( const Species_t * s )

Get the value of the "charge" attribute.

Parameters

s	the Species_t structure.

Returns: the charge of the given Species_t structure.

Note: Beginning in SBML Level 2 Version 2, the "charge" attribute on Species_t is deprecated and its use strongly discouraged. Its presence is considered a misfeature in earlier definitions of SBML because its implications for the mathematics of a model were never defined, and in any case, no known modeling system ever used it. Instead, models take account of charge values directly in their definitions of species by (for example) having separate species identities for the charged and uncharged versions of the same species. This allows the condition to affect model mathematics directly. LibSBML retains this method for easier compatibility with SBML Level 1.

const char * Species_getCompartment ( const Species_t * s )

Get the compartment in which this species is located.

Parameters

s	the Species_t structure.

Returns: the value of the "compartment" attribute of the given Species_t structure, as a string.

int Species_getConstant ( const Species_t * s )

Get the value of the "constant" attribute.

Parameters

s	the Species_t structure.

Returns: 1 (true) or 0 (false) depending on the value of the given Species_t structure's "constant" attribute value.

const char * Species_getConversionFactor ( const Species_t * s )

Get the value of the "conversionFactor" attribute.

Parameters

s	the Species_t structure.

Returns: the "conversionFactor" attribute of the given Species_t structure, as a string.

UnitDefinition_t * Species_getDerivedUnitDefinition ( Species_t * s )

Constructs and returns a UnitDefinition_t structure that expresses the units of this Species_t structure.

Parameters

s	the Species_t structure whose units are to be returned.

Returns: a UnitDefinition_t structure that expresses the units of this Species_t strucuture.

Note: This function returns the units of the Species_t expressed as a UnitDefinition_t. The units may be those explicitly declared or those derived from the default units of the Model_t containing this Species_t and it's Compartment_t.

Note that the functionality that facilitates unit analysis depends on the model as a whole. Thus, in cases where the structure has not been added to a model or the model itself is incomplete, unit analysis is not possible and this method will return NULL.

Examples:: printUnits.c.

int Species_getHasOnlySubstanceUnits ( const Species_t * s )

Get the value of the "hasOnlySubstanceUnits" attribute.

Parameters

s	the Species_t structure.

Returns: 1 (true) or 0 (false) depending on the value of the given Species_t structure's "hasOnlySubstanceUnits" attribute value.

const char * Species_getId ( const Species_t * s )

Takes a Species_t structure and returns its identifier.

Parameters

s	the Species_t structure whose identifier is sought.

Returns: the identifier of the Species_t structure s, as a pointer to a string.

Examples:: printAnnotation.c, and printNotes.c.

double Species_getInitialAmount ( const Species_t * s )

Get the value of the "initialAmount" attribute.

Parameters

s	the Species_t structure.

Returns: the "initialAmount" attribute of the given Species_t structure, as a floating point number.

double Species_getInitialConcentration ( const Species_t * s )

Get the value of the "initialConcentration" attribute.

Parameters

s	the Species_t structure.

Returns: the "initialConcentration" of the given Species_t structure, as a floating point number.

const char * Species_getName ( const Species_t * s )

Takes a Species_t structure and returns its name.

Parameters

s	the Species_t structure whose name is sought.

Returns: the name of the Species_t structure s, as a pointer to a string.

const XMLNamespaces_t * Species_getNamespaces ( Species_t * s )

Returns a list of XMLNamespaces_t associated with this Species_t structure.

Parameters

s	the Species_t structure.

Returns: pointer to the XMLNamespaces_t structure associated with this structure

const char * Species_getSpatialSizeUnits ( const Species_t * s )

Get the value of the "spatialSizeUnits" attribute.

Parameters

s	the Species_t structure.

Returns: the spatialSizeUnits of the given Species_t.

Warning: In versions of SBML Level 2 before Version 3, the class Species_t included an attribute called "spatialSizeUnits", which allowed explicitly setting the units of size for initial concentration. This attribute was removed in SBML Level 2 Version 3. LibSBML retains this attribute for compatibility with older definitions of Level 2, but its use is strongly discouraged because it is incompatible with levels and versions of SBML beyond Level 2 Version 2.

const char * Species_getSpeciesType ( const Species_t * s )

Get the species type of this Species_t structure, as indicated by the Species_t structure's "speciesType" attribute value.

Parameters

s	the Species_t structure.

Returns: the value of the "speciesType" attribute of the Species_t structure s as a string.

const char * Species_getSubstanceUnits ( const Species_t * s )

Get the value of the "substanceUnit" attribute.

Parameters

s	the Species_t structure.

Returns: the "substanceUnits" attribute of the given Species_t structure, as a string.

const char * Species_getUnits ( const Species_t * s )

(SBML Level 1 only) Get the value of the "units" attribute.

Parameters

s	the Species_t structure.

Returns: the units of the given Species_t structure.

int Species_hasRequiredAttributes ( Species_t * s )

Predicate returning 1 (true) or 0 (false) depending on whether all the required attributes for this Species_t structure have been set.

The required attributes for a Species_t structure are:

id (name L1)
compartment
initialAmount (L1 only)
hasOnlySubstanceUnits (L3 on)
boundaryCondition (L3 on)
constant (L3 on)

Parameters

s	the Species_t structure to check.

Returns: a true if all the required attributes for this structure have been defined, 0 (false) otherwise.

void Species_initDefaults ( Species_t * s )

Initializes the attributes of the given Species_t structure to the defaults defined in the specification of the relevant Level/Version of SBML.

sets "boundaryCondition" to true
(Level 2 only) sets "constant" to false
(Level 2 only) sets "hasOnlySubstanceUnits" to false

Parameters

s	the Species_t structure.

int Species_isSetBoundaryCondition ( const Species_t * s )

Predicate returning 1 (true) or 0 (false) depending on whether the attribute "boundaryCondition" of the given Species_t structure is set.

Parameters

s	the Species_t structure.

Returns: 1 (true) if the "boundaryCondition" attribute of the given Species_t structure is set, 0 (false) otherwise.

int Species_isSetCharge ( const Species_t * s )

Predicate returning 1 (true) or 0 (false) depending on whether the attribute "charge" of the given Species_t structure is set.

Parameters

s	the Species_t structure.

Returns: 1 (true) if the "charge" attribute of the given Species_t structure is set, 0 (false) otherwise.

Note: Beginning in SBML Level 2 Version 2, the "charge" attribute on Species_t in SBML is deprecated and its use strongly discouraged. Its presence is considered a misfeature in earlier definitions of SBML because its implications for the mathematics of a model were never defined, and in any case, no known modeling system ever used it. Instead, models take account of charge values directly in their definitions of species by (for example) having separate species identities for the charged and uncharged versions of the same species. This allows the condition to affect model mathematics directly. LibSBML retains this method for easier compatibility with SBML Level 1.

int Species_isSetCompartment ( const Species_t * s )

Predicate returning 1 (true) or 0 (false) depending on whether the attribute "compartment" of the given Species_t structure is set.

Parameters

s	the Species_t structure.

Returns: 1 (true) if the "compartment" attribute of the given Species_t structure is set, 0 (false) otherwise.

int Species_isSetConstant ( const Species_t * s )

Predicate returning 1 (true) or 0 (false) depending on whether the attribute "constant" of the given Species_t structure is set.

Parameters

s	the Species_t structure.

Returns: 1 (true) if the "constant" attribute of the given Species_t structure is set, 0 (false) otherwise.

int Species_isSetConversionFactor ( const Species_t * s )

Predicate returning 1 (true) or 0 (false) depending on whether the attribute "conversionFactor" of the given Species_t structure is set.

Parameters

s	the Species_t structure.

Returns: 1 (true) if the "conversionFactor" attribute of the given Species_t structure is set, 0 (false) otherwise.

int Species_isSetHasOnlySubstanceUnits ( const Species_t * s )

Predicate returning 1 (true) or 0 (false) depending on whether the attribute "hasOnlySubstanceUnits" of the given Species_t structure is set.

Parameters

s	the Species_t structure.

Returns: 1 (true) if the "hasOnlySubstanceUnits" attribute of the given Species_t structure is set, 0 (false) otherwise.

int Species_isSetId ( const Species_t * s )

Predicate returning 1 (true) or 0 (false) depending on whether the attribute "id" of the given Species_t structure is set.

Parameters

s	the Species_t structure.

Returns: 1 (true) if the "id" attribute of the given Species_t structure is set, 0 (false) otherwise.

int Species_isSetInitialAmount ( const Species_t * s )

Predicate returning 1 (true) or 0 (false) depending on whether the attribute "initialAmount" of the given Species_t structure is set.

Parameters

s	the Species_t structure.

Returns: 1 (true) if the "initialAmount" attribute of the given Species_t structure is set, 0 (false) otherwise.

Note: In SBML Level 1, Species_t' "initialAmount" is required and therefore should always be set. (However, in Level 1, the attribute has no default value either, so this method will not return nonzero until a value has been assigned.) In SBML Level 2, "initialAmount" is optional and as such may or may not be set.

int Species_isSetInitialConcentration ( const Species_t * s )

Predicate returning 1 (true) or 0 (false) depending on whether the attribute "compartment" of the given Species_t structure is set.

Parameters

s	the Species_t structure.

Returns: 1 (true) if the "compartment" attribute of the given Species_t structure is set, 0 (false) otherwise.

int Species_isSetName ( const Species_t * s )

Predicate returning 1 (true) or 0 (false) depending on whether the attribute "name" of the given Species_t structure is set.

Parameters

s	the Species_t structure.

Returns: 1 (true) if the "name" attribute of the given Species_t structure is set, 0 (false) otherwise.

int Species_isSetSpatialSizeUnits ( const Species_t * s )

Predicate returning 1 (true) or 0 (false) depending on whether the attribute "spatialSizeUnits" of the given Species_t structure is set.

Parameters

s	the Species_t structure.

Returns: 1 (true) if the "spatialSizeUnits" attribute of the given Species_t structure is set, 0 (false) otherwise.

Warning: In versions of SBML Level 2 before Version 3, the class Species_t included an attribute called "spatialSizeUnits", which allowed explicitly setting the units of size for initial concentration. This attribute was removed in SBML Level 2 Version 3. LibSBML retains this attribute for compatibility with older definitions of Level 2, but its use is strongly discouraged because it is incompatible with levels and versions of SBML beyond Level 2 Version 2.

int Species_isSetSpeciesType ( const Species_t * s )

Predicate returning 1 (true) or 0 (false) depending on whether the attribute "speciesType" of the given Species_t structure is set.

Parameters

s	the Species_t structure.

Returns: 1 (true) if the "speciesType" attribute of the given Species_t structure is set, 0 (false) otherwise.

int Species_isSetSubstanceUnits ( const Species_t * s )

Predicate returning 1 (true) or 0 (false) depending on whether the attribute "substanceUnits" of the given Species_t structure is set.

Parameters

s	the Species_t structure.

Returns: 1 (true) if the "substanceUnits" attribute of the given Species_t structure is set, 0 (false) otherwise.

int Species_isSetUnits ( const Species_t * s )

(SBML Level 1 only) Predicate returning 1 (true) or 0 (false) depending on whether the attribute "units" of the given Species_t structure is set.

Parameters

s	the Species_t structure.

Returns: 1 (true) if the "units" attribute of the given Species_t structure is set, 0 (false) otherwise.

int Species_setBoundaryCondition	(	Species_t *	s,
		int	value
	)

Sets the "boundaryCondition" attribute of the given Species_t structure.

Parameters

s	the Species_t structure.
value	`nonzero` to indicate true, `zero` to indicate false.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Examples:: spec_example1.c.

int Species_setCharge	(	Species_t *	s,
		int	value
	)

Sets the "charge" attribute of the given Species_t structure.

Parameters

s	the Species_t structure.
value	the value of charge to assign to the "charge" attribute.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Beginning in SBML Level 2 Version 2, the "charge" attribute on Species_t in SBML is deprecated and its use strongly discouraged. Its presence is considered a misfeature in earlier definitions of SBML because its implications for the mathematics of a model were never defined, and in any case, no known modeling system ever used it. Instead, models take account of charge values directly in their definitions of species by (for example) having separate species identities for the charged and uncharged versions of the same species. This allows the condition to affect model mathematics directly. LibSBML retains this method for easier compatibility with SBML Level 1.

int Species_setCompartment	(	Species_t *	s,
		const char *	sid
	)

Sets the "compartment" attribute of the given Species_t structure.

This function copies the string given in compartment. If the string is NULL, this function is equivalent to calling Species_unsetCompartment().

Parameters

s	the Species_t structure.
sid	the identifer to which the "compartment" attribute should be set.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Using this function with an sid of NULL is equivalent to unsetting the "compartment" attribute.

Examples:: createExampleSBML.c, and spec_example1.c.

int Species_setConstant	(	Species_t *	s,
		int	value
	)

Sets the "constant" attribute of the given Species_t structure.

Parameters

s	the Species_t structure.
value	`nonzero` to indicate true, `zero` to indicate false.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Examples:: spec_example1.c.

int Species_setConversionFactor	(	Species_t *	s,
		const char *	sid
	)

Sets the "conversionFactor" attribute of the given Species_t structure.

This function copies the string given in sid. If the string is NULL, this function is equivalent to calling Species_unsetConversionFactor().

Parameters

s	the Species_t structure.
sid	the identifer to which the "conversionFactor" attribute should be set.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Using this function with an sid of NULL is equivalent to unsetting the "conversionFactor" attribute.

int Species_setHasOnlySubstanceUnits	(	Species_t *	s,
		int	value
	)

Sets the "hasOnlySubstanceUnits" attribute of the given Species_t structure.

Parameters

s	the Species_t structure.
value	`nonzero` to indicate true, `zero` to indicate false.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Examples:: spec_example1.c.

int Species_setId	(	Species_t *	s,
		const char *	sid
	)

Sets the "id" attribute of the given Species_t structure.

This function copies the string given in sid. If the string is NULL, this function is equivalent to calling Species_unsetId().

Parameters

s	the Species_t structure.
sid	the identifier string to which the "id" attribute should be set.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Using this function with an sid of NULL is equivalent to unsetting the "id" attribute.

Examples:: createExampleSBML.c, and spec_example1.c.

int Species_setInitialAmount	(	Species_t *	s,
		double	value
	)

Sets the "initialAmount" attribute value of the given Species_t structure.

As a side-effect, calling this function also unsets the "initialConcentration" attribute.

Parameters

s	the Species_t structure.
value	the numerical value for the "initialAmount" attribute.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Examples:: createExampleSBML.c.

int Species_setInitialConcentration	(	Species_t *	s,
		double	value
	)

Sets the "initialConcentration" attribute value of the given Species_t structure.

As a side-effect, calling this function also unsets the "initialAmount" attribute.

Parameters

s	the Species_t structure.
value	the numerical value for the "initialConcentration" attribute.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Examples:: createExampleSBML.c.

int Species_setName	(	Species_t *	s,
		const char *	name
	)

Sets the "name" attribute of the given Species_t structure.

This function copies the string given in name. If the string is NULL, this function is equivalent to calling Species_unsetName().

Parameters

s	the Species_t structure.
name	the name string to which the "name" attribute should be set.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Using this function with the name set to NULL is equivalent to unsetting the "name" attribute.

Examples:: createExampleSBML.c.

int Species_setSpatialSizeUnits	(	Species_t *	s,
		const char *	sid
	)

Sets the "spatialSizeUnits" attribute of the given Species_t structure.

This function copies the string given in sid. If the string is NULL, this function is equivalent to calling Species_unsetSpatialSizeUnits().

Parameters

s	the Species_t structure.
sid	the identifer to which the "spatialSizeUnits" attribute should be set.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Using this function with an sid of NULL is equivalent to unsetting the "spatialSizeUnits" attribute.

Warning: In versions of SBML Level 2 before Version 3, the class Species_t included an attribute called "spatialSizeUnits", which allowed explicitly setting the units of size for initial concentration. This attribute was removed in SBML Level 2 Version 3. LibSBML retains this attribute for compatibility with older definitions of Level 2, but its use is strongly discouraged because it is incompatible with levels and versions of SBML beyond Level 2 Version 2.

int Species_setSpeciesType	(	Species_t *	s,
		const char *	sid
	)

Sets the "speciesType" attribute of the given Species_t structure.

This function copies the string given in sid. If the string is NULL, this function is equivalent to calling Species_unsetSpeciesType().

Parameters

s	the Species_t structure.
sid	the identifer to which the "speciesType" attribute should be set.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Using this function with an sid of NULL is equivalent to unsetting the "speciesType" attribute.

int Species_setSubstanceUnits	(	Species_t *	s,
		const char *	sid
	)

Sets the "substanceUnits" attribute of the given Species_t structure.

This function copies the string given in sid. If the string is NULL, this function is equivalent to calling Species_unsetSubstanceUnits().

Parameters

s	the Species_t structure.
sid	the identifer to which the "substanceUnits" attribute should be set.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Using this function with an sid of NULL is equivalent to unsetting the "substanceUnits" attribute.

int Species_setUnits	(	Species_t *	s,
		const char *	sname
	)

(SBML Level 1 only) Sets the "units" attribute of the given Species_t structure.

This function copies the string given in sid. If the string is NULL, this function is equivalent to calling Species_unsetUnits().

Parameters

s	the Species_t structure.
sname	the identifer to which the "units" attribute should be set.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Using this function with an sname of NULL is equivalent to unsetting the "units" attribute.

int Species_unsetBoundaryCondition ( Species_t * s )

Unsets the "boundaryCondition" attribute of the given Species_t structure.

Parameters

s	the Species_t structure whose attribute is to be unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Species_unsetCharge ( Species_t * s )

Unsets the "charge" attribute of the given Species_t structure.

Parameters

s	the Species_t structure whose attribute is to be unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Beginning in SBML Level 2 Version 2, the "charge" attribute on Species_t in SBML is deprecated and its use strongly discouraged. Its presence is considered a misfeature in earlier definitions of SBML because its implications for the mathematics of a model were never defined, and in any case, no known modeling system ever used it. Instead, models take account of charge values directly in their definitions of species by (for example) having separate species identities for the charged and uncharged versions of the same species. This allows the condition to affect model mathematics directly. LibSBML retains this method for easier compatibility with SBML Level 1.

int Species_unsetCompartment ( Species_t * s )

Unsets the "compartment" attribute of the given Species_t structure.

Parameters

s	the Species_t structure whose attribute is to be unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Species_unsetConstant ( Species_t * c )

Unsets the value of the "constant" attribute of the given Species_t structure.

Parameters

c	the Species_t structure.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Species_unsetConversionFactor ( Species_t * s )

Unsets the "conversionFactor" attribute of the given Species_t structure.

Parameters

s	the Species_t structure whose attribute is to be unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Species_unsetHasOnlySubstanceUnits ( Species_t * s )

Unsets the "hasOnlySubstanceUnits" attribute of the given Species_t structure.

Parameters

s	the Species_t structure whose attribute is to be unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Species_unsetId ( Species_t * s )

Unsets the "id" attribute of the given Species_t structure.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Species_unsetInitialAmount ( Species_t * s )

Unsets the "initialAmount" attribute of the given Species_t structure.

Parameters

s	the Species_t structure whose attribute is to be unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Species_unsetInitialConcentration ( Species_t * s )

Unsets the "initialConcentration" attribute of the given Species_t structure.

Parameters

s	the Species_t structure whose attribute is to be unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Species_unsetName ( Species_t * s )

Unsets the "name" attribute of the given Species_t structure.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Species_unsetSpatialSizeUnits ( Species_t * s )

Unsets the "spatialSizeUnits" attribute of the given Species_t structure.

Parameters

s	the Species_t structure whose attribute is to be unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Warning: In versions of SBML Level 2 before Version 3, the class Species_t included an attribute called "spatialSizeUnits", which allowed explicitly setting the units of size for initial concentration. This attribute was removed in SBML Level 2 Version 3. LibSBML retains this attribute for compatibility with older definitions of Level 2, but its use is strongly discouraged because it is incompatible with levels and versions of SBML beyond Level 2 Version 2.

int Species_unsetSpeciesType ( Species_t * s )

Unsets the "speciesType" attribute of the given Species_t structure.

Parameters

s	the Species_t structure whose attribute is to be unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Species_unsetSubstanceUnits ( Species_t * s )

Unsets the "substanceUnits" attribute of the given Species_t structure.

Parameters

s	the Species_t structure whose attribute is to be unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Species_unsetUnits ( Species_t * s )

Unsets the "units" attribute of the given Species_t structure.

Parameters

s	the Species_t structure whose attribute is to be unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Detailed Description

The initial amount and concentration of a species

The units of a species' amount or concentration

The "constant" and "boundaryCondition" attributes

The conversionFactor attribute in SBML Level 3

The speciesType attribute in SBML Level 2 Versions 2–4

The spatialSizeUnits attribute in SBML Level 2 Versions 1–2

Additional considerations for interpreting the numerical value of a species

Public Member Functions

Member Function Documentation