CellML 2.0

Abstract We present here CellML 2.0, 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 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 document is the normative version of the CellML Specification, defining the CellML syntax and the rules by which it should be used.It is intended primarily for the developers of software tools which directly consume CellML syntax.
Users of CellML models may prefer the informative version of the CellML Specification, which is available at https: //cellml.org/specifications/cellml_2.0/.

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

Specific information items
1.For the purposes of this specification, a specific information item is one of the following (see https://www.w3.org/TR/2004/REC-xml-infoset-20040204/ for definitions): 1.A document information item; 2. An element information item; 3. An attribute information item; 4. A processing instruction information item; 5. An unexpanded entity reference information item; 6.A document type declaration information item; 7. An unparsed entity information item; or 8.A notational information item.
2. Specific information items MUST NOT appear in a CellML infoset except where explicitly allowed by this specification, or where allowed by a normative specification referenced by this specification.

3.
The order in which specific information items appear, as children of an element information item defined in this specification, SHALL NOT affect the semantic interpretation of the CellML model.

Non-specific information items
1.For the purposes of this specification, a non-specific information item is one of the following (see https://www.w3.org/TR/2004/REC-xml-infoset-20040204/ for definitions): 1.A comment information item; 2. A namespace information item; or 3. A character information item.
2. An element information item in the CellML namespace MUST NOT contain any character information items, except for whitespace characters.
3. Two CellML infosets SHALL be deemed semantically equivalent if one can be transformed into the other by making zero or more of the following changes: 1. Adding, removing, and/or modifying comment information items.
2. Changing (inserting, removing, and/or modifying) one or more namespace information items, and/or modifying the prefix of one or more information items, without changing the namespace that any information item is in.
3. The following paragraph applies to character information items which are the direct child of an element information item in the CellML namespace, or in the MathML namespace: inserting or removing character information items that consist entirely of whitespace characters, changing the number of whitespace characters in such an information item, or changing the number of whitespace characters at the beginning or end of any character information item.

Use of namespaces
1. Element information items in a CellML infoset MUST belong to one of the following namespaces, unless explicitly indicated otherwise: 1.The CellML namespace; or 2. The MathML namespace.
2. Attribute information items in a CellML element MUST NOT be prefixed with a namespace, unless explicitly indicated otherwise.

XML ID Attributes
1. Any element information item in the CellML namespace MAY contain an attribute with local name id.This attribute SHALL be treated as having attribute type ID, as defined in Section 3.3.1 of XML 1.1 [5].

Data representation formats in CellML
The following data representation formats are defined for use in this specification: 1.A CellML identifier: 1. SHALL consist of a single Basic Latin alphabetical character, which MAY be followed by any combination of Basic Latin alphanumerical characters and/or Basic Latin underscores.
2. SHALL, when comparing two identifiers, be considered identical to another identifier if and only if both identifiers are identical sequences of characters.
2. An integer string: 1. SHALL be a base 10 representation of an integer.
2. MAY begin with a single Basic Latin plus character U+002B or a single Basic Latin hyphen-minus character U+002D as the sign indicator.
3. SHALL, other than the sign indicator, consist of one or more digits.
3. A basic real number string: 1. SHALL be a base 10 representation of a real number.
2. MAY begin with a single Basic Latin plus character U+002B or a single Basic Latin hyphen-minus character U+002D as the sign indicator.
3. MAY contain a single decimal point separator, which SHALL be the Basic Latin full stop character U+002E.
4. SHALL, other than the sign indicator and the decimal point separator, consist of one or more digits.

A real number string:
1. SHALL be a base 10 representation of a real number r = s × 10 e where s is the significand, a real number, and e is the exponent, an integer.
2. The representation of the number SHALL be the representation of the significand, optionally followed by a representation of the exponent.
3. The significand SHALL be represented as a basic real number string.
4. An exponent SHALL be represented by an exponent separator character, followed by the integer string representation of the value of the exponent.The exponent separator character SHALL be either the Basic Latin "E" character U+0045 or the Basic Latin "e" character U+0065.
5. If the exponent representation is omitted, the exponent shall be zero.

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.
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; 2. 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.
The value of this attribute SHALL be a valid locator href, as defined in Section 5.4 of the XLink specification [6].
The href attribute SHALL be treated according to the XLink specification [6], by applying the rules for simple-type elements.
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.
The value of the name attribute MUST be a CellML identifier.
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.
The value of the units_ref attribute MUST be a CellML identifier.
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 import component element
An import component element information item (referred to in this specification as an import component element) is an element in the CellML namespace with a local name equal to component, which appears as a child of an import element.
1. Every import component element MUST contain a name attribute.
The value of the name attribute MUST be a CellML identifier.
The value of the name attribute MUST NOT be identical to the value of the name attribute of any other component or import component element in the CellML infoset.
2. Every import component element MUST contain a component_ref attribute.
The value of the component_ref attribute MUST be a CellML identifier.
The value of the component_ref attribute MUST be identical to the value of the name attribute on a component or import component 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.
The value of the name attribute MUST be a CellML identifier.
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.1: Built-in units (see 3.2 Units references).
3. A units element MAY contain one or more unit element children.

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].
2. Each element child of a math element MUST have an element-type name that is listed in Table 2.1: The math element.
3. The contents of a MathML ci element MUST be a valid variable reference, as defined in 3.5 Variable references.
4. A MathML cn element MUST have an attribute in the CellML namespace, with a local name equal to units.
The value of the units attribute MUST be a valid units reference, as defined in 3.2 Units references.

5.
A cn element MUST be base 10, and MUST be of the following types: real or e-notation.

The component_ref element
A component_ref element information item (referred to in this specification as a component_ref element) is an element in the CellML namespace with a local name equal to component_ref, which appears as a child of an encapsulation element.
1. Every component_ref element MUST contain a component attribute.
The value of the component attribute MUST be a valid component reference, as defined in 3.4 Component references.
The value of the component attribute MUST NOT be identical to the value of the component attribute on any other component_ref element in the CellML infoset.
2. Every component_ref element MAY in turn 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.
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.
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.
5. A connection element MAY contain one or more map_variables element children.
3. 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.
4. 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.

Component references
A "component reference" is an attribute value that specifies a CellML component.
1.A component reference SHALL be a CellML identifier.
2. The component identified by a component reference SHALL be determined as follows: 1.If the component reference is identical to the value of the name attribute of a component element in the same infoset, then it SHALL refer to the component specified by that element.
2. If the component reference is identical to the value of the name attribute of an import component element in the same infoset, then it SHALL refer to a component from the infoset defined by the import component element (see 3.1 Interpretation of import elements).The component specified SHALL then be determined by treating the value of the component_ref attribute on the import component element as a component reference within the imported infoset.If necessary, this rule SHALL be applied recursively.
3. If no component can be identified using the rules above, the attribute value SHALL NOT be a valid component reference.

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.When present in a descendant of a component element, it SHALL refer to the variable of the same name within that component.
2. When present in the variable_1 attribute of a map_variables element, 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. When present in the variable_2 attribute of a map_variables element, 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, the attribute value SHALL NOT be a valid variable reference.

Interpretation of encapsulation elements
1.For the purposes of this specification, there SHALL be a conceptual "encapsulation digraph" in which there is exactly one node for every component in the CellML model.

2.
Where a component_ref element appears as a child of another component_ref element, there SHALL be an arc in the encapsulation digraph, and that arc SHALL be from the node corresponding to the component referenced by the parent component_ref element, and to the node corresponding to the component referenced by the child component_ref element.
3. The "encapsulated set" for a component A SHALL be the set of all components B such that there exists an arc in the encapsulation digraph from the node corresponding to A to the node corresponding to B.
4. The "encapsulation parent" for a component A SHALL be the component corresponding to the node which is the parent node in the encapsulation digraph of the node corresponding to A. A component SHALL NOT appear as child of more than one encapsulation parent.
5. The "sibling set" for a component A SHALL be the set of all components which have the same encapsulation parent as A, or in the case that A has no encapsulation parent, SHALL be the set of all components which do not have an encapsulation parent.
6.The "hidden set" for a component A SHALL be the set of all components B where component B is not in the encapsulated set for component A, and component B is not the encapsulation parent of component A, and component B is not in the sibling set for component A.
11.The variable elements in a CellML model SHALL be treated as belonging to a single "equivalent variable set".Each set of equivalent variables is the set of all variable elements for which the corresponding nodes in the variable equivalence network form a connected subgraph.Each set of equivalent variables represents one variable in the underlying mathematical model.