Detailed Description

An SBML compartment, where species are located.

A compartment in SBML represents a bounded space in which species are located. Compartments do not necessarily have to correspond to actual structures inside or outside of a biological cell.

It is important to note that although compartments are optional in the overall definition of Model_t, every species in an SBML model must be located in a compartment. This in turn means that if a model defines any species, the model must also define at least one compartment. The reason is simply that species represent physical things, and therefore must exist somewhere. Compartments represent the somewhere.

Compartment_t has one required attribute, "id", to give the compartment a unique identifier by which other parts of an SBML model definition can refer to it. A compartment can also have an optional "name" attribute of type string. Identifiers and names must be used according to the guidelines described in the SBML specifications.

Compartment_t also has an optional attribute "spatialDimensions" that is used to indicate the number of spatial dimensions possessed by the compartment. Most modeling scenarios involve compartments with integer values of "spatialDimensions" of 3 (i.e., a three-dimensional compartment, which is to say, a volume), or 2 (a two-dimensional compartment, a surface), or 1 (a one-dimensional compartment, a line). In SBML Level 3, the type of this attribute is double, there are no restrictions on the permitted values of the "spatialDimensions" attribute, and there are no default values. In SBML Level 2, the value must be a positive integer, and the default value is 3; the permissible values in SBML Level 2 are 3, 2, 1, and 0 (for a point).

Another optional attribute on Compartment_t is "size", representing the initial total size of that compartment in the model. The "size" attribute must be a floating-point value and may represent a volume (if the compartment is a three-dimensional one), or an area (if the compartment is two-dimensional), or a length (if the compartment is one-dimensional). There is no default value of compartment size in SBML Level 2 or Level 3. In particular, a missing "size" value does not imply that the compartment size is 1. (This is unlike the definition of compartment "volume" in SBML Level 1.) When the compartment's "spatialDimensions" attribute does not have a value of 0, a missing value of "size" for a given compartment signifies that the value either is unknown, or to be obtained from an external source, or determined by an InitialAssignment_t, AssignmentRule_t, AlgebraicRule_t or RateRule_t structure elsewhere in the model. In SBML Level 2, there are additional special requirements on the values of "size"; we discuss them in a separate section below.

The units associated with a compartment's "size" attribute value may be set using the optional attribute "units". The rules for setting and using compartment size units differ between SBML Level 2 and Level 3, and are discussed separately below.

Finally, the Compartment_t attribute named "constant" is used to indicate whether the compartment's size stays constant after simulation begins. A value of true indicates the compartment's "size" cannot be changed by any other construct except InitialAssignment_t; a value of false indicates the compartment's "size" can be changed by other constructs in SBML. In SBML Level 2, there is an additional explicit restriction that if "spatialDimensions"="0", the value cannot be changed by InitialAssignment_t either. Further, in Level 2, "constant" is optional, and has a default value of true. In SBML Level 3, there is no default value for the "constant" attribute, and it is required.

Additional considerations in SBML Level 2

In SBML Level 2, the default units of compartment size, and the kinds of units allowed as values of the attribute "units", interact with the number of spatial dimensions of the compartment. The value of the "units" attribute of a Compartment_t structure must be one of the base units (see Unit_t), or the predefined unit identifiers volume, area, length or dimensionless, or a new unit defined by a UnitDefinition_t structure in the enclosing Model_t, subject to the restrictions detailed in the following table:

Restrictions on values permitted for compartment `size` and `units` attributes.
Value of `spatialDimensions`	`size` allowed?	`units` allowed?	Allowable kinds of units	Default value of attribute `units`
`3`	yes	yes	units of volume, or `dimensionless`	`volume`
`2`	yes	yes	units of area, or `dimensionless`	`area`
`1`	yes	yes	units of length, or `dimensionless`	`length`
`0`	no	no	(no units allowed)

In SBML Level 2, the units of the compartment size, as defined by the "units" attribute or (if "units" is not set) the default value listed in the table above, are used in the following ways when the compartment has a "spatialDimensions" value greater than 0:

The value of the "units" attribute is used as the units of the compartment identifier when the identifier appears as a numerical quantity in a mathematical formula expressed in MathML.
The math element of an AssignmentRule_t or InitialAssignment_t referring to this compartment must (in Level 2 Versions 1-3) or should (in Level 2 Version 4) have identical units.
In RateRule_t objects that set the rate of change of the compartment's size, the units of the rule's math element must (in Level 2 Versions 1–3) or should (in Level 2 Version 4) be identical to the compartment's units (whether defined by the "units" attribute or by taking the default value from the Model_t) divided by the default time units. (In other words, the units for the rate of change of compartment size are compartment size/time units.
When a Species_t is to be treated in terms of concentrations or density, the units of the spatial size portion of the concentration value (i.e., the denominator in the units formula substance/size) are those indicated by the value of the "units" attribute on the compartment in which the species is located.

Compartments with "spatialDimensions"=0 require special treatment in this framework. As implied above, the "size" attribute must not have a value on an SBML Level 2 Compartment_t structure if the "spatialDimensions" attribute has a value of 0. An additional related restriction is that the "constant" attribute must default to or be set to true if the value of the "spatialDimensions" attribute is 0, because a zero-dimensional compartment cannot ever have a size.

If a compartment has no size or dimensional units, how should such a compartment's identifier be interpreted when it appears in mathematical formulas? The answer is that such a compartment's identifier should not appear in mathematical formulas in the first place—it has no value, and its value cannot change. Note also that a zero-dimensional compartment is a point, and species located at points can only be described in terms of amounts, not spatially-dependent measures such as concentration. Since SBML KineticLaw_t formulas are already in terms of substance/time and not (say) concentration/time, volume or other factors in principle are not needed for species located in zero-dimensional compartments.

Finally, in SBML Level 2 Versions 2–4, each compartment in a model may optionally be designated as belonging to a particular compartment type. The optional attribute "compartmentType" is used identify the compartment type represented by the Compartment_t structure. The "compartmentType" attribute's value must be the identifier of a CompartmentType_t instance defined in the model. If the "compartmentType" attribute is not present on a particular compartment definition, a unique virtual compartment type is assumed for that compartment, and no other compartment can belong to that compartment type. The values of "compartmentType" attributes on compartments have no effect on the numerical interpretation of a model. Simulators and other numerical analysis software may ignore "compartmentType" attributes. The "compartmentType" attribute and the CompartmentType_t structures are not present in SBML Level 3 Core nor in SBML Level 1.

Additional considerations in SBML Level 3

One difference between SBML Level 3 and lower Levels of SBML is that there are no restrictions on the permissible values of the "spatialDimensions" attribute, and there is no default value defined for the attribute. The value of "spatialDimensions" does not have to be an integer, either; this is to allow for the possibility of representing structures with fractal dimensions.

The number of spatial dimensions possessed by a compartment cannot enter into mathematical formulas, and therefore cannot directly alter the numerical interpretation of a model. However, the value of "spatialDimensions" does affect the interpretation of the units associated with a compartment's size. Specifically, the value of "spatialDimensions" is used to select among the Model_t attributes "volumeUnits", "areaUnits" and "lengthUnits" when a Compartment_t object does not define a value for its "units" attribute.

The "units" attribute may be left unspecified for a given compartment in a model; in that case, the compartment inherits the unit of measurement specified by one of the attributes on the enclosing Model_t structure instance. The applicable attribute on Model_t depends on the value of the compartment's "spatialDimensions" attribute; the relationship is shown in the table below. If the Model_t structure does not define the relevant attribute ("volumeUnits", "areaUnits" or "lengthUnits") for a given "spatialDimensions" value, the unit associated with that Compartment_t structure's size is undefined. If a given Compartment_t's "units" are left unset and the "spatialDimensions" either has a value other than 1, 2, or 3 or is left unset itself (as it has no default value), then no unit can be chosen from among the Model_t's "volumeUnits", "areaUnits" or "lengthUnits" attributes (even if the Model_t instance provides values for those attributes), because there is no basis to select between them. Leaving the units of compartments' sizes undefined in an SBML model does not render the model invalid; however, as a matter of best practice, we strongly recommend that all models specify the units of measurement for all compartment sizes.

Interpretation of the Compartment_t "units" attribute.
Value of attribute "spatialDimensions"	Attribute of Model_t used for inheriting the unit	Recommended candidate units
`3`	"volumeUnits"	units of volume, or `dimensionless`
`2`	"areaUnits"	units of area, or `dimensionless`
`1`	"lengthUnits"	units of length, or `dimensionless`
other	no units inherited	no specific recommendations

The unit of measurement associated with a compartment's size, as defined by the "units" attribute or (if "units" is not set) the inherited value from Model_t according to the table above, is used in the following ways:

When the identifier of the compartment appears as a numerical quantity in a mathematical formula expressed in MathML, it represents the size of the compartment, and the unit associated with the size is the value of the "units" attribute.
When a Species_t is to be treated in terms of concentrations or density, the unit associated with the spatial size portion of the concentration value (i.e., the denominator in the formula amount/size) is specified by the value of the "units" attribute on the compartment in which the species is located.
The "math" elements of AssignmentRule_t, InitialAssignment_t and EventAssignment_t structures setting the value of the compartment size should all have the same units as the unit associated with the compartment's size.
In a RateRule_t structure that defines a rate of change for a compartment's size, the unit of the rule's "math" element should be identical to the compartment's "units" attribute divided by the model-wide unit of time. (In other words, {unit of compartment size}/{unit of time}.)

Other aspects of Compartment_t

In SBML Level 1 and Level 2, Compartment_t has an optional attribute named "outside", whose value can be the identifier of another Compartment_t structure defined in the enclosing Model_t structure. Doing so means that the other compartment contains it or is outside of it. This enables the representation of simple topological relationships between compartments, for those simulation systems that can make use of the information (e.g., for drawing simple diagrams of compartments). It is worth noting that in SBML, there is no relationship between compartment sizes when compartment positioning is expressed using the "outside" attribute. The size of a given compartment does not in any sense include the sizes of other compartments having it as the value of their "outside" attributes. In other words, if a compartment B has the identifier of compartment A as its "outside" attribute value, the size of A does not include the size of B. The compartment sizes are separate.

In Level 2, there are two restrictions on the "outside" attribute. First, because a compartment with "spatialDimensions" of 0 has no size, such a compartment cannot act as the container of any other compartment except compartments that also have "spatialDimensions" values of 0. Second, the directed graph formed by representing Compartment_t structures as vertexes and the "outside" attribute values as edges must be acyclic. The latter condition is imposed to prevent a compartment from being contained inside itself. In the absence of a value for "outside", compartment definitions in SBML Level 2 do not have any implied spatial relationships between each other.

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

Public Member Functions
Compartment_t *	Compartment_clone (const Compartment_t *c)
	Creates a deep copy of the given Compartment_t structure. More...

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

Compartment_t *	Compartment_createWithNS (SBMLNamespaces_t *sbmlns)
	Creates a new Compartment_t structure using the given SBMLNamespaces_t structure, `sbmlns`. More...

void	Compartment_free (Compartment_t *c)
	Frees the given Compartment_t structure. More...

const char *	Compartment_getCompartmentType (const Compartment_t *c)
	Get the value of the "compartmentType" attribute of the given Compartment_t structure. More...

int	Compartment_getConstant (const Compartment_t *c)
	Get the value of the "constant" attribute of the given Compartment_t structure. More...

UnitDefinition_t *	Compartment_getDerivedUnitDefinition (Compartment_t *c)
	Constructs and returns a UnitDefinition_t that corresponds to the units of the given Compartment_t structure's designated size. More...

const char *	Compartment_getId (const Compartment_t *c)
	Returns the value of the "id" attribute of the given Compartment_t structure. More...

const char *	Compartment_getName (const Compartment_t *c)
	Returns the value of the "name" attribute of the given Compartment_t structure. More...

const XMLNamespaces_t *	Compartment_getNamespaces (Compartment_t *c)
	Returns a list of XMLNamespaces_t structures associated with the given Compartment_t structure. More...

const char *	Compartment_getOutside (const Compartment_t *c)
	Get the identifier, if any, of the compartment that is designated as being outside of the given Compartment_t structure. More...

double	Compartment_getSize (const Compartment_t *c)
	Get the size of the given Compartment_t structure. More...

unsigned int	Compartment_getSpatialDimensions (const Compartment_t *c)
	Get the number of spatial dimensions of the given Compartment_t structure. More...

double	Compartment_getSpatialDimensionsAsDouble (const Compartment_t *c)
	Get the number of spatial dimensions of the given Compartment_t structure, as a double. More...

const char *	Compartment_getUnits (const Compartment_t *c)
	Get the units of the given Compartment_t structure's size. More...

double	Compartment_getVolume (const Compartment_t *c)
	Get the volume of the given Compartment_t structure. More...

int	Compartment_hasRequiredAttributes (Compartment_t *c)
	Predicate returning `1` (true) or `0` (false) depending on whether all the required attributes for the given Compartment_t structure have been set. More...

void	Compartment_initDefaults (Compartment_t *c)
	Initializes the fields of the given Compartment_t structure to "typical" default values. More...

int	Compartment_isSetCompartmentType (const Compartment_t *c)
	Predicate returning `1` (true) if the given Compartment_t structure's "compartmentType" attribute is set. More...

int	Compartment_isSetConstant (const Compartment_t *c)
	Predicate returning `1` (true) if the given Compartment_t structure's "constant" attribute is set. More...

int	Compartment_isSetId (const Compartment_t *c)
	Predicate returning `1` (true) if the given Compartment_t structure's "id" attribute is set. More...

int	Compartment_isSetName (const Compartment_t *c)
	Predicate returning `1` (true) if the given Compartment_t structure's "name" attribute is set. More...

int	Compartment_isSetOutside (const Compartment_t *c)
	Predicate returning `1` (true) if the given Compartment_t structure's "outside" attribute is set. More...

int	Compartment_isSetSize (const Compartment_t *c)
	Predicate returning `1` (true) if the given Compartment_t structure's "size" attribute is set. More...

int	Compartment_isSetSpatialDimensions (const Compartment_t *c)
	Predicate returning `1` (true) if the given Compartment_t structure's "spatialDimensions" attribute is set. More...

int	Compartment_isSetUnits (const Compartment_t *c)
	Predicate returning `1` (true) if the given Compartment_t structure's "units" attribute is set. More...

int	Compartment_isSetVolume (const Compartment_t *c)
	Predicate returning `1` (true) if the given Compartment_t structures's "volume" attribute is set. More...

int	Compartment_setCompartmentType (Compartment_t c, const char sid)
	Sets the "compartmentType" attribute of the given Compartment_t structure. More...

int	Compartment_setConstant (Compartment_t *c, int value)
	Sets the value of the "constant" attribute of the given Compartment_t structure. More...

int	Compartment_setId (Compartment_t c, const char sid)
	Sets the value of the "id" attribute of the given Compartment_t structure. More...

int	Compartment_setName (Compartment_t c, const char name)
	Sets the "name" attribute of the given Compartment_t structure. More...

int	Compartment_setOutside (Compartment_t c, const char sid)
	Sets the "outside" attribute of the given Compartment_t structure. More...

int	Compartment_setSize (Compartment_t *c, double value)
	Sets the "size" attribute (or "volume" in SBML Level 1) of the given Compartment_t structure. More...

int	Compartment_setSpatialDimensions (Compartment_t *c, unsigned int value)
	Sets the "spatialDimensions" attribute of the given Compartment_t structure. More...

int	Compartment_setSpatialDimensionsAsDouble (Compartment_t *c, double value)
	Sets the "spatialDimensions" attribute of the given Compartment_t structure. More...

int	Compartment_setUnits (Compartment_t c, const char sid)
	Sets the "units" attribute of the given Compartment_t structure. More...

int	Compartment_setVolume (Compartment_t *c, double value)
	Sets the "volume" attribute (or "size" in SBML Level 2) of the given Compartment_t structure. More...

int	Compartment_unsetCompartmentType (Compartment_t *c)
	Unsets the value of the "compartmentType" attribute of the given Compartment_t structure. More...

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

int	Compartment_unsetName (Compartment_t *c)
	Unsets the "name" attribute of the given Compartment_t structure. More...

int	Compartment_unsetOutside (Compartment_t *c)
	Unsets the value of the "outside" attribute of the given Compartment_t structure. More...

int	Compartment_unsetSize (Compartment_t *c)
	Unsets the value of the "size" attribute of the given Compartment_t structure. More...

int	Compartment_unsetSpatialDimensions (Compartment_t *c)
	Unsets the value of the "spatialDimensions" attribute of the given Compartment_t structure. More...

int	Compartment_unsetUnits (Compartment_t *c)
	Unsets the value of the "units" attribute of the given Compartment_t structure. More...

int	Compartment_unsetVolume (Compartment_t *c)
	(For SBML Level 1) Unsets the value of the "volume" attribute of the given Compartment_t structure. More...

Member Function Documentation

Compartment_t * Compartment_clone ( const Compartment_t * c )

Creates a deep copy of the given Compartment_t structure.

Parameters

c	the Compartment_t structure to be copied.

Returns: a (deep) copy of the given Compartment_t structure, or a null pointer if a failure occurred.

Compartment_t * Compartment_create	(	unsigned int	level,
		unsigned int	version
	)

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

Parameters

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

Returns: the newly-created Compartment_t structure, or a null pointer if an error occurred during constructions.

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.

Compartment_t * Compartment_createWithNS ( SBMLNamespaces_t * sbmlns )

Creates a new Compartment_t structure using the given SBMLNamespaces_t structure, sbmlns.

: The SBMLNamespaces_t object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces_t facilities is to create an SBMLNamespaces_t object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces_t as arguments.

It is worth emphasizing that although this constructor does not take an identifier argument, in SBML Level 2 and beyond, the "id" (identifier) attribute of a Compartment_t instance is required to have a value. Thus, callers are cautioned to assign a value after calling this constructor. Setting the identifier can be accomplished using the method Compartment_setId().

Parameters

sbmlns an SBMLNamespaces_t structure.

Returns: the newly-created Compartment_t structure, or a null pointer if an error occurred during constructions

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 Compartment_free ( Compartment_t * c )

Frees the given Compartment_t structure.

Parameters

c	the Compartment_t structure to be freed.

const char * Compartment_getCompartmentType ( const Compartment_t * c )

Get the value of the "compartmentType" attribute of the given Compartment_t structure.

Parameters

c	the Compartment_t structure.

Returns: the value of the "compartmentType" attribute of the Compartment_t structure c as a string.

Note: The "compartmentType" attribute is only available in SBML Level 2 Versions 2–4.

int Compartment_getConstant ( const Compartment_t * c )

Get the value of the "constant" attribute of the given Compartment_t structure.

Parameters

c	the Compartment_t structure.

Returns: 1 (true) if this compartment's size is flagged as being constant, 0 (false) otherwise.

UnitDefinition_t * Compartment_getDerivedUnitDefinition ( Compartment_t * c )

Constructs and returns a UnitDefinition_t that corresponds to the units of the given Compartment_t structure's designated size.

: Compartments in SBML have an attribute ("units") for declaring the units of measurement intended for the value of the compartment's size. In the absence of a value given for this attribute, the units are inherited from values either defined on the enclosing Model_t (in SBML Level 3) or in defaults (in SBML Level 2). This method returns a UnitDefinition_t structure based on how this compartment's units are interpreted according to the relevant SBML guidelines, or it returns NULL if no units have been declared and no defaults are defined by the relevant SBML specification.

Note that unit declarations for Compartment_t structures are specified in terms of the identifier of a unit, but this method returns a structure, not a unit identifier. It does this by constructing an appropriate UnitDefinition_t structure. For SBML Level 2 models, it will do this even when the value of the "units" attribute is one of the special SBML Level 2 unit identifiers "substance", "volume", "area", "length" or "time". Callers may find this useful in conjunction with the helper methods provided by the UnitDefinition_t structure for comparing different UnitDefinition_t objects.

Parameters

c	the Compartment_t structure whose units are to be returned.

Returns: a UnitDefinition_t structure that expresses the units of the given Compartment_t structure.

Note: The libSBML system for unit analysis depends on the model as a whole. In cases where the Compartment_t structure has not yet been added to a model, or the model itself is incomplete, unit analysis is not possible, and consequently this method will return NULL.

See also: Compartment_isSetUnits(); Compartment_getUnits()

Examples:: printUnits.c.

const char * Compartment_getId ( const Compartment_t * c )

Returns the value of the "id" attribute of the given Compartment_t structure.

Parameters

c	the Compartment_t structure.

Returns: the id of this structure.

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

const char * Compartment_getName ( const Compartment_t * c )

Returns the value of the "name" attribute of the given Compartment_t structure.

Parameters

c	the Compartment_t structure.

Returns: the name of the Compartment_t structure c, as a pointer to a string.

const XMLNamespaces_t * Compartment_getNamespaces ( Compartment_t * c )

Returns a list of XMLNamespaces_t structures associated with the given Compartment_t structure.

Parameters

c	the Compartment_t structure.

Returns: pointer to the XMLNamespaces_t structure associated with this SBML structure

const char * Compartment_getOutside ( const Compartment_t * c )

Get the identifier, if any, of the compartment that is designated as being outside of the given Compartment_t structure.

Parameters

c	the Compartment_t structure.

Returns: the value of the "outside" attribute of this Compartment_t structure.

Note: The "outside" attribute is defined in SBML Level 1 and Level 2, but does not exist in SBML Level 3.

double Compartment_getSize ( const Compartment_t * c )

Get the size of the given Compartment_t structure.

: In SBML Level 1, compartments are always three-dimensional constructs and only have volumes, whereas in SBML Level 2 and higher, compartments may be other than three-dimensional, and therefore the "volume" attribute is named "size" in Level 2 and above. LibSBML provides both Compartment_getSize() and Compartment_getVolume()

for easier support of different SBML Levels.

Parameters

c	the Compartment_t structure.

Returns: the value of the "size" attribute ("volume" in Level 1) of the Compartment_t structure c as a floating point number.

Note: This method is identical to Compartment_getVolume().

See also: Compartment_isSetSize(); Compartment_getVolume()

unsigned int Compartment_getSpatialDimensions ( const Compartment_t * c )

Get the number of spatial dimensions of the given Compartment_t structure.

Parameters

c	the Compartment_t structure.

Returns: the value of the "spatialDimensions" attribute of the Compartment_t structure c as an unsigned integer

Note: In SBML Level 3, the data type of the "spatialDimensions" attribute is double, whereas in Level 2, it is integer. To avoid backward compatibility issues, libSBML provides two separate methods for obtaining the value as either an integer or a type double, for models where it is relevant.

See also: Compartment_getSpatialDimensionsAsDouble()

double Compartment_getSpatialDimensionsAsDouble ( const Compartment_t * c )

Get the number of spatial dimensions of the given Compartment_t structure, as a double.

Parameters

c	the Compartment_t structure.

Returns: the value of the "spatialDimensions" attribute of the Compartment_t structure c as a double.

Note: In SBML Level 3, the data type of the "spatialDimensions" attribute is double, whereas in Level 2, it is integer. To avoid backward compatibility issues, libSBML provides two separate methods for obtaining the value as either an integer or a type double, for models where it is relevant.

See also: Compartment_getSpatialDimensions()

const char * Compartment_getUnits ( const Compartment_t * c )

Get the units of the given Compartment_t structure's size.

The value of an SBML compartment's "units" attribute establishes the unit of measurement associated with the compartment's size.

Parameters

c	the Compartment_t structure.

Returns: the value of the "units" attribute of the Compartment_t structure, as a string. An empty string indicates that no units have been assigned to the value of the size.

Note: There is an important distinction to be made between no units assigned, and assuming a value without units has any specific unit such as dimensionless. In SBML, default units are never attributed to numbers, and numbers without units are not automatically assumed to have the unit dimensionless. Please consult the relevant SBML specification document for a more in-depth explanation of this topic and the SBML unit system.

See also: Compartment_isSetUnits(); Compartment_setUnits(); Compartment_getSize()

double Compartment_getVolume ( const Compartment_t * c )

Get the volume of the given Compartment_t structure.

: In SBML Level 1, compartments are always three-dimensional constructs and only have volumes, whereas in SBML Level 2 and higher, compartments may be other than three-dimensional, and therefore the "volume" attribute is named "size" in Level 2 and above. LibSBML provides both Compartment_getSize() and Compartment_getVolume()

for easier support of different SBML Levels.

Parameters

c	the Compartment_t structure.

Returns: the value of the "volume" attribute ("size" in Level 2) of c, as a floating-point number.

Note: The attribute "volume" only exists by that name in SBML Level 1. In Level 2 and above, the equivalent attribute is named "size". In SBML Level 1, a compartment's volume has a default value (1.0) and therefore methods such as Compartment_isSetVolume() will always return true for a Level 1 model. In Level 2, a compartment's size (the equivalent of SBML Level 1's "volume") is optional and has no default value, and therefore may or may not be set.; This method is identical to Compartment_getSize().

See also: Compartment_isSetVolume(); Compartment_getSize()

int Compartment_hasRequiredAttributes ( Compartment_t * c )

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

The required attributes for a Compartment_t structure are:

id (name in SBML Level 1 only)
constant (in SBML Level 3 only)

Parameters

c	the Compartment_t structure to check.

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

void Compartment_initDefaults ( Compartment_t * c )

Initializes the fields of the given Compartment_t structure to "typical" default values.

The SBML Compartment_t component has slightly different aspects and default attribute values in different SBML Levels and Versions. This method sets the values to certain common defaults, based mostly on what they are in SBML Level 2. Specifically:

Sets attribute "spatialDimensions" to 3
Sets attribute "constant" to 1 (true)
(Applies to Level 1 models only) Sets attribute "volume" to 1.0
(Applies to Level 3 models only) Sets attribute "units" to litre

Parameters

c	the Compartment_t structure.

int Compartment_isSetCompartmentType ( const Compartment_t * c )

Predicate returning 1 (true) if the given Compartment_t structure's "compartmentType" attribute is set.

Parameters

c	the Compartment_t structure.

Returns: 1 (true) if the "compartmentType" attribute of this Compartment_t structure is set, 0 (false) otherwise.

Note: The "compartmentType" attribute is only available in SBML Level 2 Versions 2–4.

int Compartment_isSetConstant ( const Compartment_t * c )

Predicate returning 1 (true) if the given Compartment_t structure's "constant" attribute is set.

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

int Compartment_isSetId ( const Compartment_t * c )

Predicate returning 1 (true) if the given Compartment_t structure's "id" attribute is set.

Parameters

c	the Compartment_t structure.

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

int Compartment_isSetName ( const Compartment_t * c )

Predicate returning 1 (true) if the given Compartment_t structure's "name" attribute is set.

Parameters

c	the Compartment_t structure.

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

int Compartment_isSetOutside ( const Compartment_t * c )

Predicate returning 1 (true) if the given Compartment_t structure's "outside" attribute is set.

Parameters

c	the Compartment_t structure.

Returns: 1 (true) if the "outside" attribute of this Compartment_t structure is set, 0 (false) otherwise.

Note: The "outside" attribute is defined in SBML Level 1 and Level 2, but does not exist in SBML Level 3.

int Compartment_isSetSize ( const Compartment_t * c )

Predicate returning 1 (true) if the given Compartment_t structure's "size" attribute is set.

This method is similar but not identical to Compartment_isSetVolume(). The latter should be used in the context of SBML Level 1 models instead of Compartment_isSetSize() because Compartment_isSetVolume() performs extra processing to take into account the difference in default values between SBML Levels 1 and 2.

Parameters

c	the Compartment_t structure.

Returns: 1 (true) if the "size" attribute ("volume" in Level 2) of this Compartment_t structure is set, 0 (false) otherwise.

See also: Compartment_isSetVolume(); Compartment_setSize()

int Compartment_isSetSpatialDimensions ( const Compartment_t * c )

Predicate returning 1 (true) if the given Compartment_t structure's "spatialDimensions" attribute is set.

Parameters

c	the Compartment_t structure.

Returns: 1 (true) if the "spatialDimensions" attribute of this Compartment_t structure is set, 0 (false) otherwise.

int Compartment_isSetUnits ( const Compartment_t * c )

Predicate returning 1 (true) if the given Compartment_t structure's "units" attribute is set.

Parameters

c	the Compartment_t structure.

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

Note: There is an important distinction to be made between no units assigned, and assuming a value without units has any specific unit such as dimensionless. In SBML, default units are never attributed to numbers, and numbers without units are not automatically assumed to have the unit dimensionless. Please consult the relevant SBML specification document for a more in-depth explanation of this topic and the SBML unit system.

int Compartment_isSetVolume ( const Compartment_t * c )

Predicate returning 1 (true) if the given Compartment_t structures's "volume" attribute is set.

This method is similar but not identical to Compartment_isSetSize(). The latter should not be used in the context of SBML Level 1 models because the present method performs extra processing to take into account the difference in default values between SBML Levels 1 and 2.

Parameters

c	the Compartment_t structure.

Returns: 1 (true) if the "volume" attribute ("size" in Level 2 and above) of this Compartment_t structure is set, 0 (false) otherwise.

Note: The attribute "volume" only exists by that name in SBML Level 1. In Level 2 and above, the equivalent attribute is named "size". In SBML Level 1, a compartment's volume has a default value (1.0) and therefore methods such as Compartment_isSetVolume() will always return true for a Level 1 model. In Level 2, a compartment's size (the equivalent of SBML Level 1's "volume") is optional and has no default value, and therefore may or may not be set.

See also: Compartment_isSetSize(); Compartment_setVolume()

int Compartment_setCompartmentType	(	Compartment_t *	c,
		const char *	sid
	)

Sets the "compartmentType" attribute of the given Compartment_t structure.

Parameters

c	the Compartment_t structure.
sid	the identifier of a CompartmentType_t structure defined elsewhere in the enclosing Model_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:

Note: Using this function with a null pointer for sid is equivalent to unsetting the value of the "compartmentType" attribute.; The "compartmentType" attribute is only available in SBML Level 2 Versions 2–4.

int Compartment_setConstant	(	Compartment_t *	c,
		int	value
	)

Sets the value of the "constant" attribute of the given Compartment_t structure.

Parameters

c	the Compartment_t structure.
value	an integer indicating whether the size/volume of the compartment `c` should be considered constant (indicated by a nonzero `value`) or variable (`value` is zero).

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 Compartment_setId	(	Compartment_t *	c,
		const char *	sid
	)

Sets the value of the "id" attribute of the given Compartment_t structure.

The string sid is copied.

The identifier given by an object's "id" attribute value is used to identify the object within the SBML model definition. Other objects can refer to the component using this identifier. The data type of "id" is always SId or a type derived from that, such as UnitSId, depending on the object in question. All data types are defined as follows:

     letter ::= 'a'..'z','A'..'Z'
     digit  ::= '0'..'9'
     idChar ::= letter | digit | '_'
     SId    ::= ( letter | '_' ) idChar*

The characters ( and ) are used for grouping, the character * "zero or more times", and the character | indicates logical "or". The equality of SBML identifiers is determined by an exact character sequence match; i.e., comparisons must be performed in a case-sensitive manner. This applies to all uses of SId, SIdRef, and derived types.

Users need to be aware of some important API issues that are the result of the history of SBML and libSBML. Prior to SBML Level 3 Version 2, SBML defined "id" and "name" attributes on only a subset of SBML objects. To simplify the work of programmers, libSBML's API provided get, set, check, and unset on the SBase_t object class itself instead of on individual subobject classes. This made the get/set/etc. methods uniformly available on all objects in the libSBML API. LibSBML simply returned empty strings or otherwise did not act when the methods were applied to SBML objects that were not defined by the SBML specification to have "id" or "name" attributes. Additional complications arose with the rule and assignment objects: InitialAssignment_t, EventAssignment_t, AssignmentRule_t, and RateRule_t. In early versions of SBML, the rule object hierarchy was different, and in addition, then as now, they possess different attributes: "variable" (for the rules and event assignments), "symbol" (for initial assignments), or neither (for algebraic rules). Prior to SBML Level 3 Version 2, getId() would always return an empty string, and isSetId() would always return false for objects of these classes.

With the addition of "id" and "name" attributes on SBase_t in Level 3 Version 2, it became necessary to introduce a new way to interact with the attributes more consistently in libSBML to avoid breaking backward compatibility in the behavior of the original "id" methods. For this reason, libSBML provides four functions (getIdAttribute(), setIdAttribute(), isSetIdAttribute(), and unsetIdAttribute()) that always act on the actual "id" attribute inherited from SBase_t, regardless of the object's type. These new methods should be used instead of the older getId()/setId()/etc. methods unless the old behavior is somehow necessary. Regardless of the Level and Version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an "id" attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write "id" attributes for those objects.

Parameters

c	the Compartment_t structure.
sid	the identifier to which the structures "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 a null pointer for sid is equivalent to unsetting the "id" attribute.

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

int Compartment_setName	(	Compartment_t *	c,
		const char *	name
	)

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

This function copies the string given in name. If the string is a null pointer, this function is equivalent to calling Compartment_unsetName().

Parameters

c	the Compartment_t structure.
name	the string to which the structures "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 a null pointer for name is equivalent to unsetting the value of the "name" attribute.

int Compartment_setOutside	(	Compartment_t *	c,
		const char *	sid
	)

Sets the "outside" attribute of the given Compartment_t structure.

Parameters

c	the Compartment_t structure.
sid	the identifier of a compartment that encloses this one. The string will be copied.

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 a null pointer for sid is equivalent to unsetting the value of the "outside" attribute.

int Compartment_setSize	(	Compartment_t *	c,
		double	value
	)

Sets the "size" attribute (or "volume" in SBML Level 1) of the given Compartment_t structure.

Parameters

c	the Compartment_t structure.
value	a `double` representing the size of the given Compartment_t structure in whatever units are in effect.

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:

See also: Compartment_isSetSize(); Compartment_setVolume()

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

int Compartment_setSpatialDimensions	(	Compartment_t *	c,
		unsigned int	value
	)

Sets the "spatialDimensions" attribute of the given Compartment_t structure.

Parameters

c	the Compartment_t structure.
value	an unsigned integer indicating the number of dimensions of the given compartment.

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 Compartment_setSpatialDimensionsAsDouble	(	Compartment_t *	c,
		double	value
	)

Sets the "spatialDimensions" attribute of the given Compartment_t structure.

Parameters

c	the Compartment_t structure.
value	a double indicating the number of dimensions of the given compartment.

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 Compartment_setUnits	(	Compartment_t *	c,
		const char *	sid
	)

Sets the "units" attribute of the given Compartment_t structure.

Parameters

c	the Compartment_t structure.
sid	the identifier of the defined units to use. The string will be copied.

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 a null pointer for sid is equivalent to unsetting the value of the "units" attribute.

int Compartment_setVolume	(	Compartment_t *	c,
		double	value
	)

Sets the "volume" attribute (or "size" in SBML Level 2) of the given Compartment_t structure.

This method is identical to Compartment_setSize() and is provided for compatibility between SBML Level 1 and higher Levels of SBML.

Parameters

c	the Compartment_t structure.
value	a `double` representing the volume of the given Compartment_t structure in whatever units are in effect.

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: The attribute "volume" only exists by that name in SBML Level 1. In Level 2 and above, the equivalent attribute is named "size". In SBML Level 1, a compartment's volume has a default value (1.0) and therefore methods such as Compartment_isSetVolume() will always return true for a Level 1 model. In Level 2, a compartment's size (the equivalent of SBML Level 1's "volume") is optional and has no default value, and therefore may or may not be set.

See also: Compartment_isSetVolume(); Compartment_setSize()

int Compartment_unsetCompartmentType ( Compartment_t * c )

Unsets the value of the "compartmentType" attribute of the given Compartment_t structure.

Parameters

c	the Compartment_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 Compartment_unsetConstant ( Compartment_t * c )

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

Parameters

c	the Compartment_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 Compartment_unsetName ( Compartment_t * c )

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

Parameters

c	the Compartment_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 Compartment_unsetOutside ( Compartment_t * c )

Unsets the value of the "outside" attribute of the given Compartment_t structure.

Parameters

c	the Compartment_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 Compartment_unsetSize ( Compartment_t * c )

Unsets the value of the "size" attribute of the given Compartment_t structure.

In SBML Level 1, a compartment's volume has a default value (1.0) and therefore should always be set. Calling this method on a Level 1 model resets the value to 1.0 rather than actually unsetting it. In Level 2, a compartment's "size" is optional with no default value, and unsetting it will result in the compartment having no defined size.

Parameters

c	the Compartment_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 Compartment_unsetSpatialDimensions ( Compartment_t * c )

Unsets the value of the "spatialDimensions" attribute of the given Compartment_t structure.

In SBML Levels prior to Level 3, compartments must always have a value for the number of dimensions. Consequently, calling this method on a model of SBML Level 1–2 will result in a return value of LIBSBML_UNEXPECTED_ATTRIBUTE

Parameters

c	the Compartment_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 Compartment_unsetUnits ( Compartment_t * c )

Unsets the value of the "units" attribute of the given Compartment_t structure.

Parameters

c	the Compartment_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 Compartment_unsetVolume ( Compartment_t * c )

(For SBML Level 1) Unsets the value of the "volume" attribute of the given Compartment_t structure.

This method is identical to Compartment_unsetSize(). Please refer to that method's documentation for more information about its behavior.

Parameters

c	the Compartment_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:

Note: The attribute "volume" only exists by that name in SBML Level 1. In Level 2 and above, the equivalent attribute is named "size". In SBML Level 1, a compartment's volume has a default value (1.0) and therefore methods such as Compartment_isSetVolume() will always return true for a Level 1 model. In Level 2, a compartment's size (the equivalent of SBML Level 1's "volume") is optional and has no default value, and therefore may or may not be set.

See also: Compartment_unsetSize()

Detailed Description

Additional considerations in SBML Level 2

Additional considerations in SBML Level 3

Other aspects of Compartment_t

Public Member Functions

Member Function Documentation