libSBML C API  libSBML 5.8.0 C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Unit_t Class Reference

Detailed Description

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:

amperefaradjouleluxradianvolt
avogadrogramkatalmetresecondwatt
becquerelgraykelvinmolesiemensweber
candelahenrykilogramnewtonsievert
coulombhertzlitreohmsteradian
dimensionlessitemlumenpascaltesla

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 $\times$ 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.

Unit identification codes

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.

  • The unit 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_AMPEREThe ampere unit.
UNIT_KIND_AVOGADROThe unit dimensionless multiplied by the numerical value of Avogadro's constant. (Only usable in SBML Level 3 models.)
UNIT_KIND_BECQUERELThe becquerel unit.
UNIT_KIND_CANDELAThe candela unit.
UNIT_KIND_CELSIUSThe Celsius unit. (Only usable in SBML Level 1 and SBML Level 2 Version 1 models.)
UNIT_KIND_COULOMBThe coulomb unit.
UNIT_KIND_DIMENSIONLESSA pseudo-unit indicating a dimensionless quantity.
UNIT_KIND_FARADThe farad unit.
UNIT_KIND_GRAMThe gram unit.
UNIT_KIND_GRAYThe gray unit.
UNIT_KIND_HENRYThe henry unit.
UNIT_KIND_HERTZThe hertz unit.
UNIT_KIND_ITEMA pseudo-unit representing a single "thing".
UNIT_KIND_JOULEThe joule unit.
UNIT_KIND_KATALThe katal unit.
UNIT_KIND_KELVINThe kelvin unit.
UNIT_KIND_KILOGRAMThe kilogram unit.
UNIT_KIND_LITERAlternate spelling of litre.
UNIT_KIND_LITREThe litre unit.
UNIT_KIND_LUMENThe lumen unit.
UNIT_KIND_LUXThe lux unit.
UNIT_KIND_METERAlternate spelling of metre.
UNIT_KIND_METREThe metre unit.
UNIT_KIND_MOLEThe mole unit.
UNIT_KIND_NEWTONThe newton unit.
UNIT_KIND_OHMThe ohm unit.
UNIT_KIND_PASCALThe pascal unit.
UNIT_KIND_RADIANThe radian unit.
UNIT_KIND_SECONDThe second unit.
UNIT_KIND_SIEMENSThe siemens unit.
UNIT_KIND_SIEVERTThe sievert unit.
UNIT_KIND_STERADIANThe steradian unit.
UNIT_KIND_TESLAThe tesla unit.
UNIT_KIND_VOLTThe volt unit.
UNIT_KIND_WATTThe watt unit.
UNIT_KIND_WEBERThe weber unit.
UNIT_KIND_INVALIDMarker used by libSBML to indicate an invalid or unset unit.