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 a units attribute.
1. The value of the units attribute MUST be a valid units reference, as defined in 3.2 Units references.
1. The units element inclusion digraph SHALL contain an arc from units element A to units element B if and only if units element A contains a unit element with a units attribute value that is identical to the name attribute value of units element B.
1. The units element inclusion digraph MUST NOT contain any cycles.

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:
1. The prefix attribute.
  1. If present, the value of the attribute MUST meet the constraints specified in 3.3 Interpretation of units elements.
1. The multiplier attribute.
  1. If present, the value of the attribute MUST be a real number string.
1. The exponent attribute.
  1. If present, the value of the attribute MUST be a real number string.

Note

For the purpose of this specification, the units element inclusion digraph SHALL be defined as a conceptual digraph which SHALL contain one node for every units element in the CellML model.

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 cm³/s. This is done by including child unit items. First, we need to change the base units of metre into cm³/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 2.5 The units element.

2.6. The unit element¶

2.6. The `unit` element¶