3.3. Interpretation of units elements

  1. The units element SHALL be interpreted as the product of its unit element children, according to the following rules:

    1. The prefix term is a conceptual property of unit elements.

      1. If the unit element does not have a prefix attribute, then the prefix term SHALL have value 0.

      2. If the prefix attribute has a value which is an integer string, then the value of the prefix term SHALL be the numerical value of that string.

      3. If the prefix attribute has a value which is not an integer string, then the attribute MUST have a value taken from the “Name” column of Table 3.2: Prefix values, and the prefix term SHALL have the value taken from the “Value” column of the same row.

    2. The exponent term is a conceptual property of unit elements.

      1. If a unit element has no exponent attribute, then the exponent term SHALL have value 1.0.

      2. If a unit element has an exponent attribute, then the exponent term MUST be a real number string, and the value of the exponent term SHALL be the numerical value of that string.

    3. The multiplier term is a conceptual property of unit elements.

      1. If a unit element has no multiplier attribute, then the multiplier term SHALL have value 1.0.

      2. If a unit element has a multiplier attribute, then the multiplier MUST be a real number string, and the value of the multiplier term SHALL be the numerical value of that string.

    4. The relationship between the product, \(P\), of numerical values given in each and every child unit element’s units attribute, to a numerical value, \(x\), with units given by the encompassing units element, SHALL be

      \[x[u_x] = {\dfrac {1} {m_1 \dotsm m_n(10^{p_1})^{e_1} \dotsm (10^{p_1})^{e_n}}} { \left[ \dfrac {u_x}{u^{e_1} \dotsm u^{e_n}} \right ] }P \left[ u^{e_1} \dotsm u^{e_n} \right]\]

      where \(u_x\) denotes the units of the units element; \(p_i\), \(e_i\), \(m_i\) and \(u_i\) refer to the prefix, exponent and multiplier terms and units of the \(i^{th}\) unit child element, respectively. Square brackets encompass the units of numerical values.

See more

Prefixes

The prefix term is different from the other attributes of a unit element in that it can accept both a string (the name of the prefix from the Prefix table) or an integer (the base 10 log equivalent to the prefix). It’s also different because it will become invalid if a non-integer real number is used.

For example, these are equivalent:

<!-- This is valid ... -->
<unit units="myOtherUnits" prefix="3">

<!-- ... is the same as ... -->
<unit units="myOtherUnits" prefix="kilo">

<!-- ... and the same as this. -->
<unit units="myOtherUnits" multiplier="1000.0">

<!-- BUT this is not valid, the prefix MUST be an integer or prefix name only! -->
<unit units="myOtherUnits" prefix="3.">

Note: These examples are only equivalent because the exponent in each case is 1.

Multipliers and exponents

As you might expect, both the exponent and multiplier attributes must be valid real numbers, which could include an integers. (This is in contrast to the prefix which must be an integer or a named prefix.)

All three attributes can be combined in different ways to give the same effective outcome. The examples below all define a units item equivalent to a 330 mL bottle of beer.

<!-- The prefix can be an integer or a named prefix: -->
<units name="bottle_of_beer">
    <unit units="metre" prefix="-2" exponent="3.0" multiplier="330" />
</units>
<units name="bottle_of_beer">
    <unit units="metre" prefix="centi" exponent="3.0" multiplier="330" />
</units>

<!-- Note that exponents are added to the combination of prefix and units terms
     only, not to the muptiplier:
        i.e.: this is (0.33)*((deci)(metre))^3
-->
<units name="bottle_of_beer">
    <unit units="metre" prefix="deci" exponent="3.0" multiplier="0.33"/>
</units>

<!-- A missing prefix has no effect: -->
<units name="bottle_of_beer">
    <unit units="metre" exponent="3.0" multiplier="3.3e-4"/>
</units>

<!-- Repeated unit items can be included:
        - the three centimetres together give 1 mL, and
        - the dimensionless multiplier makes them 330 mL.
-->
<units name="bottle_of_beer">
    <unit units="metre" prefix="centi"/>
    <unit units="metre" prefix="centi"/>
    <unit units="metre" prefix="centi"/>
    <unit units="dimensionless" multiplier="330.0"/>
</units>

Note: All spellings of built-in units and prefixes must be UK (not US) English, i.e.: metre (not meter), litre (not liter), and deca (not deka).

Combinations

Once you’ve read above how single unit items can be combined to form a units item, you’ll also need to define how units items can be used to form generations of units. Using the same example of the 330mL beer bottle as before, here are alternative, but equivalent, definitions.

<units name="bottle_of_beer">
    <unit units="millilitre" multiplier="330">
</units>

<!-- Of course, we need to define the "millilitre" unit before the above is valid: -->
<units name="millilitre">
    <unit units="litre" prefix="milli" />   <!-- Note UK spelling! -->
</units>
<!-- The above is equivalent to: -->
<units name="millilitre">
    <unit units="metre" prefix="centi" exponent="3.0" />   <!-- Note UK spelling! -->
</units>

But we can also use child units in conjunction with exponents too. In this situation you’ll need to understand the equation above. Let’s start by defining a centimeter:

<units name="centimeter">
    <unit units="metre" multiplier="0.01"/>
</units>
<!-- ... or ... -->
<units name="centimeter">
    <unit units="metre" prefix="centi"/>
</units>
<!-- ... or ... -->
<units name="centimeter">
    <unit units="metre" prefix="-2"/>
</units>

Now cube it to get the units of millilitres:

<units name="millilitre">
    <unit units="centimetre" exponent="3.0"/>
</units>

This is equivalent to creating the units of (10-6)(metre)3, because the effect of the exponent is applied to the combination of units and prefix, but not to the multiplier. For example:

<!-- So this ... -->
<units name="millilitre">
    <unit units="metre" exponent="3.0" multiplier="1e-6" />
</units>

<!-- ... is equivalent to this: -->
<units name="millilitre">
    <units units="metre" exponent="3.0" prefix="-2" />
</units>

It’s good to get your head around the difference between how the multiplier and prefix terms work, or your scaling might not be quite what you expect (and your beer disappointing).

  1. For the purposes of this specification, the “irreducible units” of a model SHALL consist of:

    1. The units defined in a model that are not defined in terms of other units (i.e. the set of units elements in the CellML model which have no unit child elements).

    2. The built-in irreducible units (those built-in units with “-” in the “Unit reduction tuple” column of Table 3.1: Built-in units) referenced by variables or other units in the model.

See more

The terms “irreducible units” and “unit reduction” really need to be understood together, but before either make sense we need to explain the concept of “base units”. In the physical world there are seven base units defined in the SI (Système International d’Unités) system. These are:

Symbol

Name

Base quantity

s

second

time

m

metre

length

kg

kilogram

mass

A

ampere

electric current

K

kelvin

thermodynamic temperature

mol

mole

amount of substance

cd

candela

luminous intensity

Some of the units listed in the Built-in Units table are these base units, but others are combinations of them included for convenience. Only those rows in the table which have no entries in the “Unit reduction” column are “irreducible” or base units.

In the CellML 2.0 world you are able to also define your own base units. These are units items which you create which do not reference any child unit items (thus rendering them “irreducible”). For example:

<!-- Define a new base unit called "egg".
     It's a base unit because it has no child unit items. -->
<units name="egg">
</units>

<!-- Define other units which use this new base unit. -->
<units name="dozen_eggs">
  <unit units="egg" multiplier="12" />
</units>

<!-- Combine the new base unit with existing built-in units: eggs/m^2. -->
<units name="eggs_per_square_metre">
  <unit units="egg" />
  <unit units="metre" exponent="-2" />
</units>

The terms “irreducible units” and “unit reduction” are used when discussing situations where the units of two variables must be equivalent. It makes no sense to equate a variable with units of seconds to another with units of kilograms, for example. The same is true for more complicated versions of units, as outlined in the next section.

  1. The “unit reduction” is a conceptual property of units elements. It consists of a set of tuples where each tuple is composed of a “unit name” and a real-valued “exponent”. The set of tuples SHALL be determined as follows:

    1. If the units element has no unit child elements, then the set of tuples SHALL have a single member, which SHALL consist of the name of the units element and the exponent 1.0.

    2. If the units element has one or more unit child elements, then the set of tuples SHALL consist of the entire collection of tuples given by all unit child elements.

      Tuples for each unit child element SHALL be determined as follows:

      1. If the units reference of the unit child element is to a single unit which is an irreducible unit, then the set of tuples SHALL have a single member, which SHALL consist of the name of the irreducible unit being referenced and the exponent 1.0.

      1. If the units reference of the unit child element is to built-in units other than an irreducible unit, then the tuples SHALL be derived directly from Table 3.1: Built-in units. Specifically, the set of tuples SHALL consist of the tuples given in the “Unit reduction tuple” column of the row for which the value in the “Name” column is identical to the name of the units reference.

      1. If the units reference of the unit child element is to a unit which is neither built-in, nor an irreducible unit, then the set of tuples SHALL be defined recursively as the set of tuples for the units element so referenced.

      2. The exponents of each tuple in the set for the current unit element, as derived by following rules 3.3.3.2.1, 3.3.3.2.2 or 3.3.3.2.3 above, SHALL be multiplied by the exponent term of the current, referencing, unit element.

    3. Tuples which have the unit name of “dimensionless” SHALL be removed from the set of tuples. Note that this can result in the set of tuples being empty.

    4. If the set of tuples contains tuples which have the same unit name, then those tuples SHALL be combined into a single tuple with that unit name and an exponent being the sum of those tuples’ exponents. If the resulting tuple’s exponent is zero, then the tuple SHALL be removed from the set of tuples. Note that this can result in the set of tuples being empty.

See more

Unit reduction

As discussed in the previous “See more” block, “irreducible” or “base” units are those fundamental quantities which cannot be expressed in any other way. This includes user-defined base units too. The “unit reduction” of any units item is simply a recipe for how any units item is constructed from these “base unit” ingredients.

For example, the units “metres per second” could be written:

  • m/s,

  • m⋅s-1,

  • product[ (metre)^1 , (second)^-1 ], or

  • product[ power(metre, 1) , power(second, -2) ].

This final list of tuples - representing the base unit and its exponent - is referred to as the unit reduction tuples for the units element. Some other examples are given below.

Related to :hardcodedref:`3.3.3.2.1`:

<!-- Unit reduction: [ (metre, 1), (second, -1) ] -->
<units name="metres_per_second">
  <unit units="metre">
  <unit units="second" exponent="-1>
</units>

Related to :hardcodedref:`3.3.3.2.2`: joules are equivalent to kg⋅m2⋅s:sup:−2, and the extra “per second” takes the effective exponent for second to -3.

<!-- Unit reduction: [ (kilogram, 1), (metre, 2), (second, -3) ] -->
<units name="joules_per_second">
  <unit units="joule" />
  <unit units="second" exponent="-1" />
</units>

Related to :hardcodedref:`3.3.3.2.3 and 4`: The concentration of apples per litre of cider is expressed using the custom base units apple, the custom derived units bushell_of_apples and the built-in convenience units of litre, the last being equivalent to 0.001m3. Note that:

  • scaling does not affect the unit reduction tuples,

  • the custom derived units bushell_of_apples do not appear because it can be further reduced to apple, and

  • the final exponent of the metre base unit comes from applying 3.3.3.2.4 and multiplying the exponent of the litre reduction tuple (metre, 3) with the exponent given in the cider_concentration tuple (litre, -1) to give a (metre, -3) in the final unit reduction tuple set.

<!-- Unit reduction: [ (apple, 1), (metre, -3) ] -->

<units name="apple" />

<units name="bushell_of_apples">
  <unit units="apple" multiplier="1000" />
</units>

<units name="cider_concentration">
  <unit units="bushell_of_apples" multiplier="0.5" />
  <unit units="litre" exponent="-1" />
</units>

Dimensionless base units

You may have noticed in the Built-in Units that there is an entry labelled dimensionless.

This is provided for convenience, and doesn’t take part in determining the unit reduction for any units items. Together with the next point, this means that the all unit reduction tuples represent the minimum possible description of a units item. For example, this units item has the unit reduction of (metre, 1):

<!-- The "dimensionless" base units do not appear in the unit reduction. -->
<units name="metres_by_dimensionless">
  <unit units="metre">
  <unit units="dimensionless" exponent="3">
</units>

Combining unit reductions

As outlined above, the built-in base units dimensionless do not contribute to the unit reduction tuple set. This holds for built-in units which are effectively dimensionless (like radian and steradian) but also for situations in which base units’ exponents could be simplified or cancelled. For example, all of the units items below have identical unit reduction tuples of (metre, 1), (second, -1):

<units name="metres_per_second">
    <unit units="metre">
    <unit units="second" exponent="-1">
</units>

Here the metre exponents of 3 and -4 reduce to 1:

<units name="metres_per_second_too">
    <unit units="metre" exponent="4">
    <unit units="second" exponent="-1">
    <unit units="metre" exponent="-3">
</units>

Here the steradian inclusion has no effect on the final unit reduction as its own units cancel out:

<units name="metres_per_second_too">
    <unit units="metre" exponent="1">
    <unit units="second" exponent="-1">
    <unit units="steradian" exponent="-3">
</units>

Finally a complicated one with the same outcome. Note that even though there are some irreducible units used, they end up with an exponent of 0 in the tuple, and are therefore removed from the final unit reduction. Note that a volt V is equivalent to m2·kg·s-3·A-1.

<units name="orange" />

<units name="cubed_oranges">
    <unit units="orange" exponent="3" />
</units>

<units name="mega_amps_per_gram">
    <unit units="ampere" prefix="mega" exponent="1" />
    <unit units="gram" exponent="-1" />
</units>

<units name="acceleration_units">
    <unit units="metre" prefix="milli" />
    <unit units="second" exponent="-2" />
</units>

<!-- Finally, combining these gives a units item with the same reduction as above -->
<units name="believe_it_or_not">
    <unit units="orange" exponent="-3" />
    <unit units="cubed_oranges" prefix="mega" />
    <unit units="volt" prefix="zepto" />
    <unit units="acceleration_units" exponent="-1" />
    <unit units="mega_amps_per_gram" multiplier="3.14159" />
</units>
Table 3.2 Prefix values

Name

Value

yotta

24

zetta

21

exa

18

peta

15

tera

12

giga

9

mega

6

kilo

3

hecto

2

deca

1

deci

−1

centi

−2

milli

−3

micro

−6

nano

−9

pico

−12

femto

−15

atto

−18

zepto

−21

yocto

−24