3.3. Interpretation of units
elements¶
The
units
element SHALL be interpreted as the product of itsunit
element children, according to the following rules:The prefix term is a conceptual property of
unit
elements.If the
unit
element does not have aprefix
attribute, then the prefix term SHALL have value 0.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.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.
The exponent term is a conceptual property of
unit
elements.If a
unit
element has noexponent
attribute, then the exponent term SHALL have value 1.0.If a
unit
element has anexponent
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.
The multiplier term is a conceptual property of
unit
elements.If a
unit
element has nomultiplier
attribute, then the multiplier term SHALL have value 1.0.If a
unit
element has amultiplier
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.
The relationship between the product, \(P\), of numerical values given in each and every child
unit
element’sunits
attribute, to a numerical value, \(x\), with units given by the encompassingunits
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).
For the purposes of this specification, the “irreducible units” of a model SHALL consist of:
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 nounit
child elements).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.
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:If the
units
element has nounit
child elements, then the set of tuples SHALL have a single member, which SHALL consist of the name of theunits
element and the exponent 1.0.If the
units
element has one or moreunit
child elements, then the set of tuples SHALL consist of the entire collection of tuples given by allunit
child elements.Tuples for each
unit
child element SHALL be determined as follows: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.
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.
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 theunits
element so referenced.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.
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.
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`: joule
s 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 toapple
, andthe 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 thecider_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>
Name |
Value |
|
24 |
|
21 |
|
18 |
|
15 |
|
12 |
|
9 |
|
6 |
|
3 |
|
2 |
|
1 |
|
−1 |
|
−2 |
|
−3 |
|
−6 |
|
−9 |
|
−12 |
|
−15 |
|
−18 |
|
−21 |
|
−24 |