2.12. The math element

A math element information item (referred to in this specification as a math element) is an element in the MathML namespace, which appears as a child of a component element, a test_value element, or a reset_value element.

  1. A math element MUST be the top-level element of a Content MathML tree, as described in MathML 2.0 [7].

See more

Because MathML is an entire language in its own right, we just don’t have the ability to go through all its general aspects here. Some great general resources are available on the MathML 2.0 site, and we’ll discuss below the more CellML specific restrictions in the other “See more” sections.

Please note that MathML 2 content markup is the only syntax used in CellML, even though more recent versions (MathML 3 and MathML 4) are available.

  1. Each element child of a math element MUST have an element-type name that is listed in Table 2.1: Supported MathML elements.

See more

Probably the biggest aspect of CellML’s restrictions of MathML is that it is confined to using only MathML2 content markup. No form of presentation markup is permitted, and only the version MathML2 is allowed (i.e.: not MathML 3 or greater).

The basics

The types of block can be divided into two broad categories: operation items and information items. For example, the calculation of Einstein’s \(E=mc^2\) could be represented by:

<math>
  <apply><eq/>
    <ci>E</ci>
    <apply><times/>
      <ci>m</ci>
      <apply><power/>
        <ci>c</ci>
        <cn cellml:units="dimensionless">2</cn>
      </apply>
    </apply>
  </apply>
</math>

The code below is similar, but with the mistakes as listed:

<math>
  <apply><eq/>

    <!-- The line below is not valid because <ci> elements cannot specify units;
         their units are taken from the units of the variable
         (even though in this case, E really does have units Joules). -->

    <ci cellml:units="joule">E</ci>

    <!-- The <apply> operation below is missing an operation argument (it should be <times/>) -->
    <apply>
      <ci>m</ci>
      <apply><power/>
        <ci>c</ci>

        <!-- The contents of a <cn> block below must be a real number, not a variable. -->
        <!-- It must also define units in the cellml namespace, i.e.: units:cellml="myUnits". -->
        <cn>variable_with_value_of_two</cn>

      </apply>
    </apply>
  </apply>
</math>

  1. The contents of a MathML ci element MUST be a valid variable reference, as defined in 3.5 Variable references.

See more

Consider the same \(E=mc^2\) formula as earlier, but now the value of mass m is calculated in another component:

<component name="mass_into_energy">

  <!-- The local variables for energy E and speed of light c are listed here ... -->
  <variable name="E" units="joule"/>
  <variable name="c" units="metres_per_second"/>
  <!-- ... but the variable for mass calculated in another component. -->

  <math>
    <apply><eq/>
      <ci>E</ci>
      <apply><times/>
        <ci>m</ci>
        <apply><power/>
          <ci>c</ci>
          <cn cellml:units="dimensionless">2</cn>
        </apply>
      </apply>
    </apply>
  </math>
</component>
<component name="calculate_mass">
  <variable name="m" units="kilograms" initial_value="54" />
</component>

This situation is not valid, as the math block in component mass_into_energy doesn’t have access to the variable m in the component calculate_mass. To get around this, you would need to create a new local variable within the mass_into_energy component, and use a connection element to link it to the mass variable m in the other component. The valid form of the model is shown below. You can read more about connections in 2.15 The connection element, and the interface_type attribute in 2.8 The variable element.

<component name="mass_into_energy">
  <variable name="E" units="joule"/>
  <variable name="c" units="metres_per_second"/>
  <!-- A new local variable named m is created here with a public interface type. -->
  <variable name="m" units="kilograms" interface_type="public"/>
  <math>
    <apply><eq/>
      <ci>E</ci>
      <apply><times/>
        <ci>m</ci>
        <apply><power/>
          <ci>c</ci>
          <cn cellml:units="dimensionless">2</cn>
        </apply>
      </apply>
    </apply>
  </math>
</component>
<component name="calculate_mass">
  <variable name="mass" units="kilograms" initial_value="54" />
</component>
<!-- A connection element is created which links components "calculate_mass" and "mass_into_energy". -->
<connection component_1="mass_into_energy" component_2="calculate_mass">
  <!-- A map_variable pair is created which links the "m" variables in each of the connected components. -->
  <map_variables variable_1="m" variable_2="m" />
</connection>

  1. A MathML cn element MUST have an attribute in the CellML namespace, with a local name equal to units.

    1. The value of the units attribute MUST be a valid units reference, as defined in 3.2 Units references.

  1. A MathML cn element MUST be base 10.

    1. A cn element MUST be one of the following types: real or e-notation.

See more

Constants using the <cn> tags

When specifying a constant with <cn>, its real number value is given between the tags, and its units are specified as an attribute.

<!-- These are valid: Note the cellml namespace for the units. -->
<cn cellml:units="customUnitsDefinedInTheModel">35.3</cn> <!-- Units which exist in the model are permitted. -->
<cn cellml:units="litre">10</cn> <!-- Built-in units (with UK spelling) are permitted. -->
<cn cellml:units="dimensionless">3.14159e+03</cn> <!-- Scientific or e-notation is permitted. -->

Please note that the units name specified must refer to a units element that exists in the model element, or be one from the Built-in Units table.

<!-- These are not valid: -->
<cn cellml:units="unitsThatDontExist">35.3</cn> <!-- The units reference must exist in the model. -->
<cn>42</cn> <!-- Units must be specified. -->
<cn some_other_namespace:units="some_units">502.642</cn> <!-- Units must be in the cellml namespace. -->
<cn cellml:units="meter">26.6</cn> <!-- Built-in unit names must be in UK spelling, i.e.: metre, litre. -->
<cn cellml:units="dimensionless">3,000</cn> <!-- Must be a valid real number string, the comma separator is not permitted. -->
<cn cellml:units="dimensionless">+4.0</cn> <!-- The plus sign indicator is not permitted except in e-notation exponents. -->
<cn cellml:units="dimensionless">0x235abc</cn> <!-- The value must be in base 10. -->
<cn cellml:units="dimensionless">i_am_a_variable</cn> <!-- Only real number values are permitted in <cn> blocks. -->

Dimensional consistency (or, how to write nonsense maths)

For a model to have a valid CellML syntax, it needs to follow the MathML rules outlined above. But it’s still possible to create nonsense (should you so desire … ), and one great way to create nonsense is to have MathML statements which have inconsistent units. Consider again Einstein’s equation \(E=mc^2\). Now imagine that encode it into CellML like this:

<variable name="E" units="joule"/>
<variable name="c" units="lumen"/>
<variable name="m" units="weber"/>
<math>
  <apply><eq/>
    <!-- Nonsense alert!  Left hand side units of joules ... -->
    <ci>E</ci>
    <!-- ... but right hand side units of (weber).(lumen)^(volt)! -->
    <apply><times/>
      <ci>m</ci>
      <apply><power/>
        <ci>c</ci>
        <!-- Nonesense alert!  Units in an exponent? -->
        <cn cellml:units="volt">2</cn>
      </apply>
    </apply>
  </apply>
</math>

Believe it or not, this is valid! (Perhaps it’s better to say it’s not invalid). It’s clearly nonsense, but it doesn’t actually violate any syntax rules. The only instance where you will create an invalid model by assigning units to variables is when you need to form a map_variables pair with a variable in another component. In this case, each variable must have an equivalent unit reduction or it won’t be valid CellML.

Table 2.1 Supported MathML elements

Element Category

Element List

Simple Operands

ci, cn, sep

Basic Structural

apply, piecewise, piece, otherwise

Relational and Logical Operators
eq, neq, gt, lt, geq,
leq, and, or, xor, not

Arithmetic Operators
plus, minus, times, divide,
power, root, abs,
exp, ln, log,
floor, ceiling,
min, max, rem

Calculus Elements

diff

Qualifier Elements

bvar, logbase, degree

Trigonometric Operators
sin, cos, tan, sec, csc, cot,
sinh, cosh, tanh, sech, csch, coth,
arcsin, arccos, arctan,
arcsec, arccsc, arccot,
arcsinh, arccosh, arctanh,
arcsech, arccsch, arccoth

Mathematical and Logical Constants
pi, exponentiale, notanumber,
infinity, true, false