2.3. The import units element

An import units element information item (referred to in this specification as an import units element) is an element in the CellML namespace with a local name equal to units, which appears as a child of an import element.

  1. Every import units element MUST contain a name attribute.

    1. The value of the name attribute MUST be a CellML identifier.

    2. The value of the name attribute MUST NOT be identical to the value of the name attribute of any other units or import units element in the CellML infoset.

    3. The value of the name attribute MUST NOT be identical to the name of any of the units listed in Table 3.1: Built-in units (see 3.2 Units references).

Read more

Importing units means that you’re assured of consistency between your models, and allows for a more modular reuse of the components which use them. There are three ingredients required in importing any item:

  • A destination item in the importing model (this is the units item called smallPotOfPaint in the example below).

  • A file to import from, specified using the xlink:href attribute of the parent import block. This is discussed in more detail in 2.2 The import element. In the example below this is the paint_pot_sizes.cellml file.

  • The specific item name to retrieve from the imported file. In the example below this is the twoLitrePot value passed to the units_ref attribute.

Thus we can read the import statement below as: “retrieve the units named twoLitrePot from the file paint_pot_sizes.cellml, and store it here in this model under the name potOfPaint”.

<import xlink:href="paint_pot_sizes.cellml" xmlns:xlink="http://www.w3.org/1999/xlink">
   <units units_ref="twoLitrePot" name="potOfPaint"/>
</import>

Note that if you’ve already defined the namespace inside the <model> tags then you would not need to repeat it here.

Imported items have the same restrictions as concrete items regarding the uniqueness of their names. In the example below, the name potOfPaint is used for the locally defined units in line 2, but the same name is used as the name for the imported units in line 6. This is not permitted as it violates the unique name requirement.

<model name="paintingTheHouse">
  <units name="potOfPaint">
    <unit units="metre" exponent="3" multiplier="0.002">
  </units>

  <!-- This destination name conflicts with the locally defined name above -->
  <import xlink:href="paint_pot_sizes.cellml" xmlns:xlink="http://www.w3.org/1999/xlink">
    <units units_ref="twoLitrePot" name="potOfPaint"/>
  </import>
  <component name="paintCalculator">
    ...
  </component>
</model>

  1. Every import units element MUST contain a units_ref attribute.

    1. The value of the units_ref attribute MUST be a CellML identifier.

    2. The value of the units_ref attribute MUST be identical to the value of the name attribute on a units or import units element in the imported CellML infoset.