
A Using The CellML 1.0 DTDA.1 IntroductionThis section contains some recommendations on the use and referencing of the CellML 1.0 DTD, the full text of which is given in Appendix A.6. The document rules and processor behaviour described in this section are not required in valid CellML documents and from CellML compliant processing software, respectively. A.2 The CellML DOCTYPE declarationCellML documents that reference the CellML 1.0 DTD should contain a DOCTYPE declaration of the following form:
" CellML document authors may change the value of the system identifier to point to a copy of the DTD cached on a local filesystem if this is available. This specification does not define a public identifier for CellML 1.0. For interoperability, CellML document authors should not define one unless specifically needed for a parser that makes use of SGML catalog files. A.3 CellML without a DTDCellML documents are not required to contain a DOCTYPE declaration. In the absence of a DTD, CellML processing software needs to take into account the following important points:
The CellML DTD does not define the default values for CellML attributes that are defined in the specification. With or without a DTD, CellML processing software is responsible for setting these values, if not specified. A.4 Use of MathML within CellMLThe CellML 1.0 DTD provides facilities for including the MathML 2.0 DTD using a relative path. The reference to the MathML DTD is inside a conditional section of the CellML DTD, and by default the reference is ignored. CellML document authors with a copy of both the CellML and MathML DTDs on the local filesystem may validate against both by causing the contents of the conditional section to be included using a DOCTYPE declaration of the following form: The MathML 2.0 DTD is not on the CellML website, so DOCTYPE declarations of this form will fail when referencing the DTD on the CellML website. The MathML 2.0 DTDs are available as a ZIP archive, a link to which is given in Appendix A.6 of the MathML 2.0 Recommendation.
The CellML specification requires a A.5 Treatment of namespaces
In Section 2.2.2, it was suggested that the root element of a CellML document set the default namespace and map the A.6 The CellML 1.0 DTDThe CellML 1.0 DTD is available at the following URI: The CellML 1.0 DTD does not attempt to declare or reference declarations for the metadata framework elements in the RDF namespace. It also doesn't declare the default values of any of the attributes on the CellML elements. For convenient reference, the text of the DTD is given below. B Scripting functionality in CellMLB.1 IntroductionMathML can be extended by defining new operators, the behaviour of which is not defined in MathML. These operators could be used to call functions implemented in software (i.e., implicitly) or defined using a scripting language (i.e., explicitly). CellML 1.0 does not require processing software to implement support for scripting functionality. This section contains some recommendations on best practices for adding scripting functionality to CellML. For the purposes of this discussion, it is assumed that scripting functionality will be implemented via function calls. Software that extends the functionality of MathML in other ways should extrapolate these recommendations as appropriate. B.2 Availability of scriptsFunctions referenced in a CellML document that are defined using nonMathML syntax should be identified by, and accessible via, a URI. A function could, for instance, be accessible via HTTP from a database using a CGI script that takes an SQL expression as an argument. B.3 Embedding scripts in CellML
Functions should be defined within elements in an applicationspecific extension namespace, if the functions are embedded within CellML documents. If the embedded script is only referenced by a single component, the script should be defined within the corresponding B.4 Preferred scripting languageImplementors considering adding scripting functionality to CellML processing software are encouraged to use ECMAScript. It is anticipated that, when scripting functionality is officially endorsed by a future version of CellML, ECMAScript will be the scripting language that processing software is required to implement. ECMAScript is the recommended language because it is simple, standardised, and open source interpreting libraries are freely available. ECMA is an international industry association that develops standards in information and communication for the European union. ECMA took the scripting language that Netscape developed for adding interactive content to its web browser and developed the formal language specification ECMA262 (ECMAScript Language Specification). B.5 Referencing scripts from MathML
The MathML 2.0 Recommendation defines a B.5.1 The

Operator  Restrictions 

<times> , <divide> , <abs> , <floor> , <ceiling>
 There are no restrictions on the units of operands for these operators. 
<eq> , <neq> , <gt> , <lt> , <geq> , <leq> , <plus> , <minus>
 These operators, if applied to more than one operand, require all of their operands to have either equivalent units references, as defined in Appendix C.2.1, or to reference units that have dimensional equivalence, as defined in Appendix C.2.2. 
<and> , <or> , <xor> , <not>

These operators require their operands to have units of cellml:boolean , as defined in Section 5.5.2.

<exp> , <ln> , <factorial> , <sin> , <cos> , <tan> , <sec> , <csc> , <cot> , <sinh> , <cosh> , <tanh> , <sech> , <csch> , <coth> , <arcsin> , <arccos> , <arctan> , <arccosh> , <arccot> , <arccoth> , <arccsc> , <arccsch> , <arcsec> , <arcsech> , <arcsinh> , <arctanh>

These operators require their operands to have units of dimensionless .

<power>

This is a binary arithmetic operator. Its first operand may have any units, and its second operand must have units of dimensionless .

<root>

This is a qualified unary operator. Its operand may have any units. The value of the <degree> qualifier element, if present, must have units of dimensionless .

<log>

This is a qualified unary operator. Its operand must have units of dimensionless . The value of the <logbase> qualifier element, if present, must have units of dimensionless .

<diff>

The operand of this operator may have any units (this is the variable with respect to which differentiation occurs). The value of the <bvar> qualifier element, if present, may have any units. The value of a <degree> qualifier element within the <bvar> qualifier element, if present, must have units of dimensionless .

C.3.3 Applying operators to units definitions
The section defines the units resulting from the application of MathML operators to a collection of terms, each with known units. This is needed for units definition conversion and equation dimension checking, as described in Appendix C.3.5 and Appendix C.3.6, respectively. The units on each of the terms in the collection must satisfy the restrictions defined in Appendix C.3.2 for the current operator.
The full set of units calculation rules are described in Table 6.
Operator  Result Units 

<eq> , <neq> , <gt> , <lt> , <geq> , <leq> , <and> , <or> , <xor> , <not>

The result of these operators has units of cellml:boolean .

<exp> , <ln> , <log> , <factorial> , <sin> , <cos> , <tan> , <sec> , <csc> , <cot> , <sinh> , <cosh> , <tanh> , <sech> , <csch> , <coth> , <arcsin> , <arccos> , <arctan> , <arccosh> , <arccot> , <arccoth> , <arccsc> , <arccsch> , <arcsec> , <arcsech> , <arcsinh> , <arctanh>

The result of these operators has units of dimensionless .

<plus> , <minus> , <abs> , <floor> , <ceiling>
 The result of these operators has the same units as the operands. 
<times>
 The result of this operator has units that are the product of the units on the operands. This product may be simplified according to the rules outlined in Appendix C.3.1. 
<divide>
 The result of this operator has units that are the quotient of the units on the first and second operands. This quotient may be simplified according to the rules outlined in Appendix C.3.1. 
<power>

The result of this operator has units that are the units on the first operand raised to the power of the second operand. If the first operand has units of dimensionless , the result also has units of dimensionless .

<root>

The result of this operator has units that are the units on the first operand raised to one over the value of the <degree> qualifier element (the default value of which is 2.0). If the first operand has units of dimensionless , the result also has units of dimensionless .

<diff>

The result of this operator has units that are the quotient of the units of the term in the <bvar> qualifier element over the units of the operand raised to the value of the <degree> qualifier element inside the <bvar> qualifier element (the default value of which is 1.0). This quotient may be simplified according to the rules outlined in Appendix C.3.1.

C.3.4 Expansion of units definitions
This section presents the recommended algorithm for expanding a given units definition into an expression that relates the defined units to only SI and userdefined base units. This algorithm may be used in the conversion of units definitions and equation dimension checking, algorithms for which are defined in Appendix C.3.5 and Appendix C.3.6, respectively. Examples of the expansion of units definitions are given in Appendix C.4.2.
The specific steps in the algorithm depend on whether the units definition to be expanded is simple or complex, as defined in Section 5.2.2. Both derivations use recursive methods. At each step, any units that are not base units are replaced with expansions based on the appropriate definition.
Expansion of simple units definitions
The formula relating a variable x_{U} with units of U
(where U
are simple units), to a variable x_{1} with units of u_{1}
(the subunits referenced by the units
attribute on the <unit>
element inside the units definition for U
), is given in Equation 9. This is based on the simple units definition formula given in Equation 3.
(9) 
m_{1}, p_{1} and o_{1} correspond to the multiplier
, prefix
and offset
attributes on the <unit>
element, respectively.
The formula relating a variable with units of u_{1}
to its subunits u_{2}
, as referenced in the units definition for u_{1}
, is given in Equation 10.
(10) 
Equation 10 can be substituted into Equation 9 to give Equation 11.
(11) 
The expression defining each new set of units in terms of its subunits can be substituted into the current expression recursively until an expression is reached that relates x_{U} to x_{n} with units u_{n}
, which are SI or userdefined base units. At this point expansion stops, and the resulting expression can be simplified. This simplification combines multiplier, prefix and offset terms and combines their units based on the rules defined in Appendix C.3.3. The result is an expression of the form given in Equation 12.
(12) 
The values of m_{t} and o_{t} are given by Equation 13 and Equation 14, respectively.
(13) 
(14) 
Expansion of complex units definitions
The formula relating a variable x_{U} with complex units U
to a variable x_{A} with units that are the product of the subunits referenced in the units definition for U
is given in Equation 15. This is based on the complex units definition formula given in Equation 4.
(15) 
The m_{Ai}, p_{Ai}, u_{Ai}
and e_{Ai} refer to the values of the multiplier
, prefix
, units
and exponent
attributes on the ith <unit>
element inside the units definition for U
, respectively. If, at the first step, the cth set of units referenced is not SI or userdefined base units, the formula relating u_{Ac}
to the cth set of units referenced to its subunits is given in
Equation 16.
(16) 
Note that if u_{Ac}
is a simple units definition, then the right hand side of Equation 16 will take the form of a simple units definition, but without the constant offset term.
An expansion for x_{A} that incorporates the expansion for u_{Ac}
is obtained by multiplying both sides of Equation 16 by unitary coefficients with units of the product of all of the units referenced on the right hand side of Equation 15 with the exception of u_{Ac}
. Expansion of units definitions involves constructing expansions for the variable on the right hand side. The expansion continues recursively as long as any of the units on the right hand side of Equation 15 are not SI or userdefined base units. The resulting expansion can be simplified by combining multiplier and prefix terms to give an expression with the form given in Equation 17.
(17) 
u_{Ii}
corresponds to the units referenced by the ith units definition referenced in the Ith definition to be expanded, and m_{t} is given by Equation 18.
(18) 
m_{Ii}, p_{Ii} and e_{Ii} correspond to the values of the multiplier
, prefix
and exponent
attributes on the ith <unit>
element in the Ith definition to be expanded.
C.3.5 Conversion between units definitions
This section presents an algorithm that specifies a possible method for converting a variable's value from one set of units to another. An example demonstrating the use of this algorithm is given in Appendix C.4.3.
If the two variable declarations that are to be mapped both reference equivalent units definitions as defined in Appendix C.2.1, then there is a onetoone mapping between the the variable's value in both components.
If the two variable declarations that are to be mapped reference different units definitions, then software may choose to calculate a conversion formula as follows. Given a variable x with units U_{x}
, the value of which is to be passed to a variable y with units U_{y}
, the following steps should be followed:

The units definitions for
U_{x}
andU_{y}
are fully expanded and simplified according to the algorithm presented in Appendix C.3.4. This yields expressions for x and y in terms of x_{n} and y_{n}, the units of which are products of only SI and userdefined base units. The expression for x will be of the form given in Equation 19 ifU_{x}
is a simple units definition, or of the form given in Equation 20 ifU_{x}
is a complex units definition.(19) (20) In Equation 19,
u_{x}
corresponds to the base units referenced in the full expansion ofU_{x}
, whereas in Equation 20,u_{x}
corresponds to the product of all of the base units in the full expansion raised to the appropriate exponents. 
It should be considered an error if the units for x_{n} (
u_{x}
) and y_{n} (u_{y}
) do not have equivalent dimensions as defined in Appendix C.2.2. 
The expansion of x is inverted to give an expression for x_{n}. The inverted forms of Equation 19 and Equation 20 are given in Equation 21 and Equation 22, respectively.
(21) (22) The appropriate expression for x_{n} can then be substituted for y_{n} in the expansion of y. This yields an equation for y in terms of x, which can be used to convert variable values.
C.3.6 Equation dimension checking
This section presents an algorithm that can be used to verify that an equation is consistent with respect to the dimensions of the units definitions referenced by all numbers and variables. An example that demonstrates the process of equation dimension checking for an equation defined in MathML and CellML is given in Appendix C.4.4.
This algorithm relies on the restrictions and behaviour of the different operators with respect to units defined in Appendix C.3.2 and Appendix C.3.3. Future versions of the specification may extend this algorithm to handle other operators. The steps in the algorithm are:

The equation is split into a tree of terms, in which each parent term is obtained by the application of a single operator to its children. The root of the tree is the entire equation, which is created by applying a relational operator (typically the equals operator) to its child terms. All other terms in the tree are created by applying arithmetic operators to child terms.

The units definitions for the terms at the leaves of the tree (which will be variables, numbers, or MathML constants elements) are expanded into functions of the SI and userdefined base units, using the algorithm presented in Appendix C.3.4.

Starting at the leaves of the tree, sets of child terms are recursively removed from the tree and units assigned to the parent terms. The removal of each set of terms follows the following steps:

The child terms are compared against the restrictions described in Appendix C.3.2 for the current operator. It should be considered an error if they do not satisfy these restrictions, in which case the equation has inconsistent dimensions.

Units are assigned to the parent term as defined in Appendix C.3.3 for the current operator.

 The equation has selfconsistent dimensions if no inconsistencies were found during the recursive removal of child terms during the traversal from leaves to root.
C.4 Examples
C.4.1 Userdefined units and new base units
In Figure 17, the example units definitions given in Section 5.3 are reproduced. These examples are used in the subsequent advanced examples.
C.4.2 Expansion of userdefined units
In this section, the expansion of userdefined units according to the algorithm described in Appendix C.3.4 is demonstrated for each of the units definitions given in Figure 17.
The first <units>
element in Figure 17 defines units named pH
, and defines a base_units
attribute with a value of "
yes
"
. This indicates that it should be treated by processing software as if it were an SI base unit, and that it cannot be expanded.
The definition of inch
in Figure 17 is a simple units definition as it references only a single unit with an exponent of one. When the appropriate terms are substituted into Equation 3, the conversion from metre
to inch
is given by Equation 23. metre
is a SI base unit, so no further expansion is necessary.
(23) 
The definition of fahrenheit
is in terms of celsius
, which is an SI derived unit. The expansion from celsius
to kelvin
, an SI base unit, is obtained from Section 2.1.1.5 of the SI standard, and is given in Equation 24.
(24) 
The first step in the expansion of the fahrenheit
definition is given in Equation 25.
(25) 
The x_{c} term can be replaced with the expansion of the celsius
definition from Equation 24, as shown in Equation 26.
(26) 
The 1.0 and 273.15 terms can be multiplied by the 1.8. The units on the resulting terms are the products of the units on the operands, as described in Appendix C.3.3, and these can be simplified according to the rules given in Appendix C.3.1. The final expansion of fahrenheit is given in Equation 27
(27) 
celsius_per_centimetre
is the first of the complex units definitions given in Figure 17. The first step in the expansion of this definition is given by Equation 28, which is obtained by substituting the appropriate terms in Equation 4.
(28) 
The expansion of the x_{old} term, which has units that are a product, is not obvious. This term must be expanded to continue. metre
is an SI base unit, so need not be expanded. However, celsius
is an SI derived unit, the expansion of which is given in Equation 24. Because this expansion is to be substituted into a complex units definition, the offset term is dropped. The next step in the expansion makes use of the modified celsius definition in Equation 29 and the identity in Equation 30.
(29) 
(30) 
The result of multiplying Equation 30 and Equation 29 is given in Equation 31.
(31) 
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}. The result is given in Equation 32, where the scale factors have also been multiplied.
(32) 
z_{new} from Equation 32 can be substituted in place of Equation 28, and the result simplified to give the complete expansion of celsius_per_centimetre
shown in Equation 33.
(33) 
The definition of fahrenheit_per_inch
can be handled in the same way. The first step in the expansion is given by Equation 34.
(34) 
The expansion of x_{old} requires the removal of the offset from the expansion of fahrenheit
from Equation 27 and the inversion of the expansion of inch
from Equation 23. These are given in Equation 35 and Equation 36, respectively.
(35) 
(36) 
Multiplying Equation 35 and Equation 36 and simplifying yields Equation 37.
(37) 
z_{new} from Equation 37 can be substituted into Equation 34 in place of x_{old} and the result simplified to give the complete expansion of fahrenheit_per_inch
in Equation 38.
(38) 
The first step in the expansion of pH_per_celsius
is given in Equation 39.
(39) 
When userdefined base units are referenced in a simple or complex units definition, they are treated in the same way as SI base units, and not expanded. The final expansion into a combination of userdefined and SI base units is given in Equation 40.
(40) 
C.4.3 Conversion between units definitions
In this section, the algorithm defined in Appendix C.3.5 for converting a variable's value from one set of units to another is presented with respect to a practical example. Figure 18 contains part of a CellML model definition, consisting of two components and one connection. The legacy_imperial
component defines a variable x
with units of fahrenheit_per_inch
. The modern_si
component defines a variable y
with units of celsius_per_centimetre
. A connection between the two components maps x
to y
.
The CellML definitions of both fahrenheit_per_inch
and celsius_per_centimetre
are given in Figure 17. It was shown how to obtain expressions that relate each of these units definitions to the SI base units in Appendix C.4.2. These expressions are reproduced in Equation 41 and Equation 42, respectively.
(41) 
(42) 
The value of x is transferred to the variable y in the mapping. Therefore an equation expressing celsius_per_centimetre
in terms of fahrenheit_per_inch
is needed. This can be obtained by rearranging Equation 41 for w_{kpm}, substituting the resulting expression in place of z_{kpm} in Equation 42, and simplifying the result according to the rules defined in Appendix C.3.1. This gives the expression in Equation 43.
(43) 
C.4.4 Equation dimension checking
In this section, the algorithm defined in Appendix C.3.6 for checking that an equation has consistent units is presented with respect to a practical example. Figure 19 contains the definition of a CellML component sodium_channel_m_gate
. This component defines three sets of units (per_millisecond
, millivolt
, and per_millivolt
), two variables (V
and alpha_m
) and an equation that calculates the value of alpha_m
.
Equation 44 gives the equation in Figure 19, where units have been omitted. Equation 45 gives the same equation, with the units associated with each number and variable are included. The first 1.0 in the equation is included specifically for units consistency. It would be possible to associate more complex units with the 0.1 in the numerator of the equation, but this would not accurately reflect the intent of the original model authors. CellML processing software is free to find this and similar terms that do not affect the mathematics and ignore them when interpreting the equation.
(44) 
(45) 
The first step in the algorithm proposed in Appendix C.3.6 for verifying that a given equation has consistent dimensions is to convert the equation into a tree of equation parts. Equation 45 can be broken up into the tree shown in Figure 20.
At each branch in the tree, a single operator is applied to the child nodes, combining them into a larger parent equation part. Each equation part in the tree has units associated with it. In the case of leaf nodes, these units are obtained from the MathML equation definition. Parent nodes have units defined by the operator and the units on their child nodes, as described in Appendix C.3.3. Dimension checking begins at the leaf nodes, which are recursively removed as the units are evaluated for their parent nodes, which in turn become leaf nodes, as described in Appendix C.3.6.
In the equation tree diagram in Figure 20, the application of each operator to a set of child nodes is denoted by a number in square brackets, where the number reflects the order in which the operations are processed. These operations are discussed below.

The
<plus>
operator combines the variable "V" and the number "25.0
" that occur in the denominator of the fraction in Equation 45. The<plus>
operator requires all of its operands to be dimensionally equivalent, as described in Appendix C.2.2. The resulting equation part will have the same units as the operands. Both "V" and "25.0
" have units ofmillivolt
, and so the parent equation part "V +25.0
" also has units ofmillivolt
. 
The
<times>
operator (which is not explicitly rendered in Equation 45) multiplies the "V +25.0
" term that is the result of the first operation by the number "0.1
" which has units ofper_millivolt
. The<times>
operator can be applied to any operands, independent of their units, and the resulting equation part has units that are the product of the units on the operands. In this case, the resultant "0.1(
V +25.0)
" term has units that are the product ofmillivolt
andper_millivolt
, which simplifies todimensionless
(as described in Appendix C.3.1). 
The
<exp>
operator is a unary arithmetic operator and its operand must have units ofdimensionless
. The result of applying the operator, in this case "exp(0.1(
V +25.0))
", also has units ofdimensionless
. 
The
<minus>
operator subtracts the number "1.0
", which has units ofdimensionless
, from the term resulting from operation 3. The<minus>
operator requires both its operands to have the same units and the result assumes those units. 
The
<plus>
operator is applied to the variable "V" and the number "25.0
" from the numerator of the fraction in Equation 45. Units are handled as in operation 1.  Exactly as in operation 2, where the operands are now in the numerator of the fraction in Equation 45.

The
<divide>
operator is applied to the results of operations 6 and 4, which both have units ofdimensionless
. The<divide>
operator can be applied to any operands, independent of their units, and the result has the quotient of the units on the operands. In this case, the resulting fraction has units ofdimensionless
. 
The
<times>
operator is applied to the number "1.0
", which has units ofper_millisecond
and the result of operation 7, which has units ofdimensionless
. The resulting term has units ofper_millisecond
. 
Finally, the
<equals>
operator is applied to the variable "alpha_m" and the term resulting from operation 8. The<equals>
operator requires that its operands have dimensionally equivalent units.
D Changes
D.1 Changes between 2 March 2001 Draft and the 18 May 2001 Final Draft

Language Syntax Changes
 CellML Identifiers — The definition of a CellML identifier was changed to be consistent with the Systems Biology Markup Language (SBML) specification.
 Namespaces — It was decided to base the CellML namespaces on a version number rather than a date. The CellML specification does not define the metadata namespaces now. For more detailed information see the meeting minutes from 7 May 2001
 Connections — The syntax used to pass the values of variables between components was completely revised. The new scheme has more meaningful element and attribute names, is selfconsistent, and is more concise. For more detailed information see the meeting minutes from 13 March 2001 and 21 March 2001.
 Mathematics — The rules regarding the use of MathML in a CellML document were overhauled, and a number of recommendations were added. In particular a subset of the MathML content markup elements was defined and discussion of scripting functionality was moved to an appendix. See the meeting minutes from 21 March 2001, 2 April 2001, and 5 April 2001for more information.
 Units — Complete worked examples of units conversion and equation dimension checking were added, and complete algorithms for these processes were added to the appendices. See the meeting minutes from 21 March 2001 for more information.
 Grouping — The grouping syntax was completely overhauled to allow a complete hierarchy to be specified within a single group. See the meeting minutes from 14 March 2001, and 21 March 2001for more information.

Editorial Changes
 Conformance Levels amd Terminology — The idea of two conformance levels was discarded, and instead this specification now consists of rules and recommendations. The conformance section was removed from the introduction and a new terminology section was added which properly defines what is expected of valid CellML documents and CellMLcompliant processing software. See the meeting minutes from 22 April 2001 for more information.
 Syntax Related Changes — Major editorial changes were made to properly document the syntax changes described above.
 Many minor editorial changes, too numerous to list here, have been made to all sections of the specification.
 