Meeting Minutes 20 March 2001 Units Definition and Examples

Get the PDF!

1  Introduction

Throughout January and February 2001, one of the biggest headaches for Warren was the specification of a units system for CellML. The problem was that he needed to completely define how a units definition should be recursively expanded in order that the conversion of variable values from one set of units to another would be consistent across all applications. Warren tried to pass his problems on to as many other people as possible, but few really cared. It was not until 20 March 2001 that some real progress was made, with the help of Poul Nielsen.

In this document, a range of test units definitions are expanded to demonstrate thoroughly how the proposed expansion technique should be applied.

2  Simple Units Definitions

2.1  What the spec says

To quote from the 2001-03-02 draft of the CellML specification:

A `simple units' definition occurs when units are defined as a linear function of some previously defined simple units or base units. This occurs when a <units> element contains only a single child <unit> element, that <unit> element has an exponent attribute value of "1.0", and the units definition referenced by the units attribute is one of the SI or user-defined base units or is itself a simple units definition. These are the only conditions under which a <unit> element may define an offset attribute. The formula that expresses how the old units (referenced by the value of the units attribute on the <unit> element) are transformed into the new units (defined by the value of the name attribute on the parent <units> element) is given below:

(1)

Terms in square brackets represent the units associated with a term in the expression, xold is the value to be transformed from the old units, xnew is the resulting value in the new units, Units are the units being defined, and multiplier, prefix, units, and offset correspond to the values of the appropriate attributes on the <unit> element.

2.2  What the spec should say

The formula is wrong. The prefix is just another multiplier, and the units previously associated with the multiplier should really be associated with the product of the prefix and multiplier. The correct formula follows.

(2)

A proposal for the complete discussion of user-defined simple and complex units is given in Section 4.

2.3  Examples

Simple units definitions are fairly easy to deal with, because the units of the variables in the equations never feature any products. We will look at an expansion of the units definition for degrees fahrenheit given below.

<units name="fahrenheit">
  <unit multiplier="1.8" units="celsius" offset="32.0" />
</units>

The expansion follows, where we have abbreviated the name of the units being defined (fahrenheit) to fnht to save space.

(3)

3  Complex Units Definition

3.1  What the spec said

Quoting from the 2001-03-02 draft of the CellML specification:

`Complex units' are the product of multiple base quantities, and are created by placing several <unit> elements inside a single <units> element, or by defining an exponent attribute with a value other than "1.0" on any <unit> element. The conversion between the new units and the product of the constituent units is given by the formula below.

(4)

The mn, pn, un, and en terms refer to the values of the multiplier, prefix, units, and exponent attributes on the n-th <unit> element respectively. Note that this specification forbids offset attributes from being defined on any unit elements that occur inside a complex units definition.

It is very important to note that when a complex units definition references a simple units definition, any offset associated with the simple units definition is removed. This means that the conversions such as the one between degrees Fahrenheit per inch and degrees Celsius per centimetre involve only a scale factor.

3.2  What the spec should say

The formula should be re-arranged so that the prefixes and multipliers are all lumped into a single term which has units representing the entire conversion from the units being defined to the products of all of the constituent units, as shown below.

(5)

A proposal for the complete discussion of user-defined simple and complex units is given in Section 4.

3.3  Examples

First of all we will revisit the definitions of the convenience units defined in the CellML specification. The CellML versions of these units definitions and the associated equations are.

<units name="celsius">
  <unit units="kelvin" offset="-273.15" />
</units>

(6)

<units name="gram">
  <unit multiplier="0.001" units="kilogram" />
</units>

(7)

<units name="litre">
  <unit multiplier="1000" prefix="centi" units="metre" exponent="3" />
</units>

(8)

Now we'll work through some other examples to thoroughly demonstrate the expansion of units definitions into their constituent base units. First we define an inch.

<units name="inch">
  <unit multiplier="2.54" prefix="centi" units="metre" />
</units>

(9)

Next we define the units of celsius_per_centimetre, which we will abbreviate to cpcm in the mathematics, in order to save space. Note that the definition of celsius given in Equation 6 involves an offset. This offset is ignored when the definition is substituted into the complex units definition.

<units name="celsius_per_centimetre">
  <unit units="celsius" />
  <unit prefix="centi" units="metre" exponent="-1" />
</units>

(10)

Now things we get more interesting: we expand the definition of fahrenheit_per_inch, which we will abbreviate to fpi to save space. This expansion is handled in steps.

<units name="fahrenheit_per_inch">
  <unit units="fahrenheit" />
  <unit units="inch" exponent="-1" />
</units>

(11)

In Equation 11, there is no obvious substitution for the x_old term, which has units that are the product of two non-base units definitions. We must expand this term to continue. In order to do this, let's invert the definition of inch given in Equation 9. We introduce the variables y_new and y_old here to represent the unknown values with inverted units.

(12)

Now let's consider the multiplication of the definition of fahrenheit given in Equation 3 and the inverted inch definition given in Equation 12, where we abbreviate fahrenheit and inch to f and i respectively. Note that the offset from the definition of fahrenheit has been dropped. The variables v_new and v_old are introduced to represent the unknown temperature values.

(13)

The v_new and y_new variables can be multiplied together to produce a new unknown z_new which has units which are the product of the units on v_new and y_new. Similarly z_old is the product of v_old and y_old.

(14)

Now we can substitute z_new from Equation 14 into Equation 11 in place of x_old and simplify the result to give a complete expansion of fahrenheit_per_inch.

(15)

In the last example, we'll look at the expansion of the units definition for millimolar, which will be found in the majority of models defined using CellML. A CellML definition is given below.

<units name="millimolar">
  <unit prefix="milli" units="mole" />
  <unit units="litre" exponent="-1" />
</units>

The initial expansion is shown below.

(16)

We can create an expansion for x_old by inverting the definition for litre given in Equation 8, and multiplying each side of the equation by 1.0 mole. These terms are absorbed into the variables, and the conversion factor is multiplied by 1.0 mole/mole to keep the units consistent.

(17)

(18)

Substituting Equation 18 into Equation 16 gives the result below.

(19)

4  New Units Discussion

The full introduction of simple and complex units definitions at the end of Section 5.2.3 in the 2001-03-02 draft of the specification should read:

A simple units definition occurs when units are defined as a linear function of some previously defined simple units or base units. In a simple units definition, a <units> element contains only a single child <unit> element, that <unit> element has an exponent attribute value of "1.0", and the units definition referenced by the units attribute is one of the SI or user-defined base units or is itself a simple units definition. These are the only conditions under which a <unit> element may define an offset attribute with a value other than "0.0". The formula that expresses how the old units (referenced by the value of the units attribute on the <unit> element) are transformed into the new units (defined by the value of the name attribute on the parent <units> element) is given below.

(20)

Terms in square brackets represent the units associated with values in the expression, which are italicized. x_old is the value to be transformed from the old units, and x_new is the resulting value in the new units. Units are the units being defined, and multiplier, prefix, units and offset correspond to the values of the appropriate attributes on the <unit> element.

Complex units are the product of multiple units. In a complex units definition, a units element contains multiple child unit elements, or some unit element defines an exponent attribute with a value other than 1.0. The conversion between the new units and the product of the constituent units is given by the formula below.

(21)

The m_i, p_i, u_i, and e_i terms refer to the values of the multiplier, prefix, units and exponent attributes on the i-th <unit> element respectively.

The offset attribute may not be defined on any <unit> elements that occur inside a complex units definition. When a complex units definition references a simple units definition, any offset associated with the simple units definition is removed. This means that conversions such as the one between degrees Fahrenheit per inch and degrees Celsius per centimetre involve only a scale factor.