CellML 2.0.1

Abstract We present here CellML 2.0.1, an XML-based language for describing and exchanging mathematical models of physiological systems. MathML embedded in CellML documents is used to define the underlying mathematics of models. Models consist of a network of reusable components, each with variables and equations giving relationships between those variables. Models may import other models to create systems of increasing complexity. CellML 2.0.1 is defined by the normative specification presented here, prescribing the CellML syntax and the rules by which it should be used. The normative specification is intended primarily for the developers of software tools which directly consume CellML syntax. Users of CellML models may prefer to browse the informative rendering of the specification (https://cellml.org/specifications/cellml_2.0/) which extends the normative specification with explanations of the rules combined with examples of their usage. This version improves the identification of rule statements and corrects errata present in the CellML 2.0 specification.


CellML information sets 1.2.1 CellML and XML
1. Every CellML infoset SHALL be represented in an XML information set which conforms with the well-formedness requirements of XML 1.1 [5].
2. In this document, the remaining provisions relating to CellML infosets SHALL be interpreted as additional constraints on the XML information set represented by a CellML infoset.

The model element
The top-level element information item in a CellML infoset MUST be an element in the CellML namespace with a local name equal to model. In this specification, the top-level element is referred to as the model element.
1. Every model element MUST contain a name attribute.
1. The value of the name attribute MUST be a CellML identifier.

2.
A model element MAY contain one or more additional specific element children, each of which MUST be of one of the following types: 1. A component element;

A connection element;
3. An encapsulation element; 4. An import element; or 5. A units element.

3.
A model element MUST NOT contain more than one encapsulation elements.

The import element
An import element information item (referred to in this specification as an import element) is an element in the CellML namespace with a local name equal to import, which appears as a child of a model element.
1. Every import element MUST contain an attribute in the namespace http://www.w3.org/1999/ xlink, with a local name equal to href.
1. The value of this attribute SHALL be a valid locator href, as defined in Section 5.4 of the XLink specification [6].
2. The href attribute SHALL be treated according to the XLink specification [6], by applying the rules for simple-type elements.
3. When describing an import element or one of its children, the phrase "imported CellML infoset" SHALL refer to the CellML infoset obtained by parsing the document referenced by the href attribute.
2. Every import element MAY contain one or more specific element children, each of which MUST be of one of the following types: 1. An import component element; or 2. An import units element.
3. Any CellML infoset imported, directly or indirectly, by the imported CellML infoset MUST NOT be semantically equivalent to the importing CellML infoset (see 1.2.3.3 regarding semantic equivalence).

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.
2. 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.

The units element
A units element information item (referred to in this specification as a units element) is an element in the CellML namespace with a local name equal to units, which appears as a child of a model element.
1. Every 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 element or import units element in the CellML infoset.
2. The value of the name attribute MUST NOT be identical to the name of any of the units listed in Table 3

The unit element
A unit element information item (referred to in this specification as a unit element) is an element in the CellML namespace with a local name equal to unit, which appears as a child of a units element.
1. Every unit element MUST contain a units attribute. 3. The units element inclusion digraph MUST NOT contain any cycles.

2.
A unit element MAY contain any of the following attributes: 1. The prefix attribute.
1. If present, the value of the attribute MUST meet the constraints specified in 3.3 Interpretation of units elements.
1. If present, the value of the attribute MUST be a real number string.
1. If present, the value of the attribute MUST be a real number string.
Note: For the purpose of this specification, the units element inclusion digraph SHALL be defined as a conceptual digraph which SHALL contain one node for every units element in the CellML model.

The component element
A component element information item (referred to in this specification as a component element) is an element in the CellML namespace with a local name equal to component, which appears as a child of a model element.

The variable element
A variable element information item (referred to in this specification as a variable element) is an element in the CellML namespace with a local name equal to variable, which appears as a child of a component element.
1. Every variable element MUST have exactly one of each of the following attributes: 1. The 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 on any sibling variable element.
1. The value of the units attribute MUST be a valid units reference, as defined in 3.2 Units references.
2. Every variable element MAY contain one or more of the following attributes: 1. The interface attribute.
1. If the attribute is present, it MUST have value of public, private, public_and_private, or none.
1. If the attribute is present, it MUST meet the requirements described by 3.6 Interpretation of ini-tial_value attributes.

The reset element
A reset element information item (referred to in this specification as a reset element) is an element in the CellML namespace with a local name equal to reset, which appears as a child of a component element.
1. Every reset element MUST have exactly one of each of the following attributes: 1. The variable attribute.
1. The value of the variable attribute MUST be a valid variable reference, as defined in 3.5 Variable references.
1. The value of the test_variable attribute MUST be a valid variable reference, as defined in 3.5 Variable references.
1. The value of the order attribute MUST be an integer string.
2. The value of the order attribute MUST be unique for all reset elements with variable attributes that reference variables in the same equivalent variable set (see 3.10 Interpretation of map_variables elements).

2.
A reset element MUST contain exactly two element children, which MUST be one of each of the following types: 1. A reset_value element; and 2. A test_value element.

The test_value element
A test_value element information item (referred to in this specification as a test_value element) is an element in the CellML namespace with a local name equal to test_value, which appears as a child of a reset element.
1. A test_value element MUST contain exactly one math element child.

The reset_value element
A reset_value element information item (referred to in this specification as a reset_value element) is an element in the CellML namespace with a local name equal to reset_value, which appears as a child of a reset element.
1. A reset_value element MUST contain exactly one math element child.

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 cn element MUST be one of the following types: real or e-notation.

The encapsulation element
An encapsulation element information item (referred to in this specification as an encapsulation element) is an element in the CellML namespace with a local name equal to encapsulation, which appears as a child of a model element.
1. An encapsulation element MAY contain one or more component_ref element children.

The connection element
A connection element information item (referred to in this specification as a connection element) is an element in the CellML namespace with a local name equal to connection, which appears as a child of a model element.
1. Each connection element MUST contain a component_1 attribute.
1. The value of the component_1 attribute MUST be a valid component reference, as defined in 3.4 Component references.
2. Each connection element MUST contain a component_2 attribute.
1. The value of the component_2 attribute MUST be a valid component reference, as defined in 3.4 Component references.
3. The value of the component_1 attribute MUST NOT be identical to the value of the component_2 attribute.
4. A CellML infoset MUST NOT contain more than one connection element with a given pair of components referenced by the component_1 and component_2 attribute values, in any order.

Variable references
A "variable reference" is an attribute value that specifies a CellML variable.
1. A variable reference SHALL be a CellML identifier.
2. The variable identified by a variable reference SHALL be determined as follows: 1. If present in a descendant of a component element, then it SHALL refer to the variable of the same name within that component.
2. If present in the variable_1 attribute of a map_variables element, then it SHALL refer to the variable of the same name in the component identified by the component_1 attribute in the same map_variables element.
3. If present in the variable_2 attribute of a map_variables element, then it SHALL refer to the variable of the same name in the component identified by the component_2 attribute in the same map_variables element.
3. If no variable can be identified using the rules above, then the attribute value SHALL NOT be a valid variable reference.