2.6. The unit
element¶
A unit
element information item (referred to in this specification as a unit
element) is an element in the CellML namespace with a local name equal to unit
, which appears as a child of a units
element.
Every
unit
element MUST contain aunits
attribute.The value of the
units
attribute MUST be a valid units reference, as defined in 3.2 Units references.For the purpose of the constraint in the next paragraph, the
units
element inclusion digraph SHALL be defined as a conceptual digraph which SHALL contain one node for everyunits
element in the CellML model.The
units
element inclusion digraph SHALL contain an arc fromunits
element A tounits
element B if and only ifunits
element A contains aunit
element with aunits
attribute value that is identical to thename
attribute value ofunits
element B.
The element inclusion digraph MUST NOT contain any cycles.
See more
A Units
item is simply a collection of Unit
items, each with a prefix
, multiplier
, and exponent
.
They can be nested and contain multiple generations of inheritance, which means that there’s always a possibility of circular definitions: these are not permitted.
For example, the first definition is valid:
<!-- Defining new base units called A: -->
<units name="A"/>
<!-- Defining new units called B, equivalent to 1000.A^2 -->
<units name="B">
<unit units="A" prefix="kilo" exponent="2"/>
</units>
<!-- Defining new units called C, equivalent to B^3/ms or (1000)^3.A^6/ms -->
<units name="C">
<unit units="B" exponent="3"/>
<unit units="second" prefix="milli" exponent="-1"/>
</units>
The second definition creates a circular dependency, and is not valid:
<!-- Defining units called A which depend on units B: -->
<units name="A">
<unit units="B" exponent="2"/>
</units>
<!-- Defining units called B which depend on units C: -->
<units name="B">
<unit units="C" prefix="kilo" exponent="-2"/>
</units>
<!-- Defining units called C which depend on A: -->
<units name="C">
<unit units="A" prefix="mega"/>
<unit units="second" prefix="milli" exponent="-1"/>
</units>
A
unit
element MAY contain any of the following attributes:The
prefix
attribute. If present, the value of the attribute MUST meet the constraints specified in 3.3 Interpretation of units elements.
The
multiplier
attribute. If present, the value of the attribute MUST be a real number string.
The
exponent
attribute. If present, the value of the attribute MUST be a real number string.
See more
There are two items related to units in CellML, and their naming can be confusing!
The plural form, units
, represents the units to be used in the model by being assigned to variable
and cn
elements.
A units
item is a collection of smaller unit
items which transform the base dimensionality into the form required by the final units by way of prefixes, multipliers, and exponents.
In the example, we’ll need to use two of the built-in base units, metre
and second
, and manipulate them to form cm3/s.
This is done by including child unit
items.
First, we need to change the base units of metre
into cm3/s:
<units name="cm3_per_second">
<unit units="metre" prefix="centi" exponent="3"> <!-- The default multiplier is 1. -->
...
</units>
Next, we include the time dependency, changing the built-in units second
into s-1.
Note that sibling unit
items within a parent units
item are simply multplied together to form the final representation:
<units name="cm3_per_second">
<unit units="metre" prefix="centi" exponent="3"> <!-- Note default multiplier of 1. -->
<unit units="second" exponent="-1"> <!-- Note default prefix of 0, default multiplier of 1. -->
</units>
This is exactly equivalent to the alterantives below:
<units name="cm3_per_second">
<unit units="metre" prefix="-2" exponent="3"> <!-- A prefix can be specified as a power of 10. -->
<unit units="second" exponent="-1">
</units>
<!-- or ... -->
<units name="cm3_per_second">
<unit units="metre" exponent="3" multiplier="0.01"> <!-- A multiplier is specified instead of a prefix. -->
<unit units="second" exponent="-1">
</units>
<!-- or ... -->
<units name="cm3_per_second">
<unit units="metre" prefix="centi"> <!-- Note default exponent of 1 ... -->
<unit units="metre" prefix="-1"> <!-- ... is repeated ... -->
<unit units="metre" multiplier="0.01"> <!-- ... to give the equivalent power of 3. -->
<unit units="second" exponent="-1">
</units>
For more information on units
items please refer to the previous section.