libSBML C API
libSBML 5.8.0 C API
|
Implementation of SBML's Unit construct.
The SBML unit definition facility uses two classes of objects, UnitDefinition and Unit. The approach to defining units in SBML is compositional; for example, meter second –2 is constructed by combining a Unit object representing meter with another Unit object representing second –2. The combination is wrapped inside a UnitDefinition, which provides for assigning an identifier and optional name to the combination. The identifier can then be referenced from elsewhere in a model. Thus, the UnitDefinition class is the container, and Unit instances are placed inside UnitDefinition instances.
A Unit structure has four attributes named "kind", "exponent", "scale" and "multiplier". It represents a (possibly transformed) reference to a base unit. The attribute "kind" on Unit indicates the chosen base unit. Its value must be one of the text strings listed below; this list corresponds to SBML Level 3 Version 1 Core:
ampere | farad | joule | lux | radian | volt |
avogadro | gram | katal | metre | second | watt |
becquerel | gray | kelvin | mole | siemens | weber |
candela | henry | kilogram | newton | sievert | |
coulomb | hertz | litre | ohm | steradian | |
dimensionless | item | lumen | pascal | tesla |
A few small differences exist between the Level 3 list of base units and the list defined in other Level/Version combinations of SBML. Specifically, Levels of SBML before Level 3 do not define avogadro
; conversely, Level 2 Version 1 defines Celsius
, and Level 1 defines celsius
, meter
, and liter
, none of which are available in Level 3. In libSBML, each of the predefined base unit names is represented by an enumeration value whose name begins with the characters UNIT_KIND_
, discussed in a separate section below.
The attribute named "exponent" on Unit represents an exponent on the unit. In SBML Level 2, the attribute is optional and has a default value of 1
(one); in SBML Level 3, the attribute is mandatory and there is no default value. A Unit structure also has an attribute called "scale"; its value must be an integer exponent for a power-of-ten multiplier used to set the scale of the unit. For example, a unit having a "kind" value of gram
and a "scale" value of -3
signifies 10 –3 gram, or milligrams. In SBML Level 2, the attribute is optional and has a default value of
0
(zero), because 10 0 = 1; in SBML Level 3, the attribute is mandatory and has no default value. Lastly, the attribute named "multiplier" can be used to multiply the unit by a real-numbered factor; this enables the definition of units that are not power-of-ten multiples of SI units. For instance, a multiplier of 0.3048 could be used to define foot
as a measure of length in terms of a metre
. The "multiplier" attribute is optional in SBML Level 2, where it has a default value of 1
(one); in SBML Level 3, the attribute is mandatory and has not default value.
As discussed above, SBML defines a set of base units which serves as the starting point for new unit definitions. This set of base units consists of the SI units and a small number of additional convenience units.
As a consequence of the fact that libSBML supports models in all Levels and Versions of SBML, libSBML's set of UNIT_KIND_
values is a union of all the possible base unit names defined in the different SBML specifications. However, not every base unit is allowed in every Level+Version combination of SBML. Note in particular the following exceptions:
The alternate spelling "meter"
is included in addition to the official SI spelling "metre"
. This spelling is only permitted in SBML Level 1 models.
The alternate spelling "liter"
is included in addition to the official SI spelling "litre"
. This spelling is only permitted in SBML Level 1 models.
The unit "Celsius"
is included because of its presence in specifications of SBML prior to SBML Level 2 Version 3.
avogadro
was introduced in SBML Level 3, and is only permitted for use in SBML Level 3 models. The table below lists the unit constants defined in libSBML, and their meanings.
Enumerator | Meaning |
---|---|
UNIT_KIND_AMPERE | The ampere unit. |
UNIT_KIND_AVOGADRO | The unit
dimensionless multiplied by the numerical value of Avogadro's
constant. (Only usable in SBML Level 3 models.) |
UNIT_KIND_BECQUEREL | The becquerel unit. |
UNIT_KIND_CANDELA | The candela unit. |
UNIT_KIND_CELSIUS | The Celsius unit. (Only usable in SBML Level 1 and SBML Level 2 Version 1 models.) |
UNIT_KIND_COULOMB | The coulomb unit. |
UNIT_KIND_DIMENSIONLESS | A pseudo-unit indicating a dimensionless quantity. |
UNIT_KIND_FARAD | The farad unit. |
UNIT_KIND_GRAM | The gram unit. |
UNIT_KIND_GRAY | The gray unit. |
UNIT_KIND_HENRY | The henry unit. |
UNIT_KIND_HERTZ | The hertz unit. |
UNIT_KIND_ITEM | A pseudo-unit representing a single "thing". |
UNIT_KIND_JOULE | The joule unit. |
UNIT_KIND_KATAL | The katal unit. |
UNIT_KIND_KELVIN | The kelvin unit. |
UNIT_KIND_KILOGRAM | The kilogram unit. |
UNIT_KIND_LITER | Alternate spelling of litre. |
UNIT_KIND_LITRE | The litre unit. |
UNIT_KIND_LUMEN | The lumen unit. |
UNIT_KIND_LUX | The lux unit. |
UNIT_KIND_METER | Alternate spelling of metre. |
UNIT_KIND_METRE | The metre unit. |
UNIT_KIND_MOLE | The mole unit. |
UNIT_KIND_NEWTON | The newton unit. |
UNIT_KIND_OHM | The ohm unit. |
UNIT_KIND_PASCAL | The pascal unit. |
UNIT_KIND_RADIAN | The radian unit. |
UNIT_KIND_SECOND | The second unit. |
UNIT_KIND_SIEMENS | The siemens unit. |
UNIT_KIND_SIEVERT | The sievert unit. |
UNIT_KIND_STERADIAN | The steradian unit. |
UNIT_KIND_TESLA | The tesla unit. |
UNIT_KIND_VOLT | The volt unit. |
UNIT_KIND_WATT | The watt unit. |
UNIT_KIND_WEBER | The weber unit. |
UNIT_KIND_INVALID | Marker used by libSBML to indicate an invalid or unset unit. |