CellML API
The architecture of the CellML API and its implementation
The CellML API package can be divided into two parts: the API itself, which is a set of interface definitions, and the reference implementation of the API (the CellML API Implementation). The API itself describes a contract between an API implementation and an application, and so you can (and are encouraged to) use this API even if you don't use the reference implementation; this way, code written for one API implementation can be more easily adapted to run on another one.
The API interfaces
The API itself is described using Interface Definition Language (IDL), an Object Management Group (OMG) standard. The most important structure defined in IDL is the interface. An interface is an abstract property that an object (defined in an implementation) can support. Interfaces have a hierarchy, meaning that to support an interface, an object must also support all ancestors of that interface in the inheritance hierarchy. Interfaces define a series of operations and attributes. Note: Objects can, and often do, support multiple interfaces from different inheritance hierarchies.
Operations represent something that you can request an object supporting the interface do, giving it zero or more inputs of types defined in the IDL file, and getting zero or more outputs. Operations have a series of parameters, which may be in, out, or in/out, and a return value (which may be void), of fixed type defined in the IDL file.
Attributes represent a property of the object supporting the interface. Attributes can be read-only, meaning that the value can be retrieved but not changed directly through the attribute, or read-write, meaning that the value can be retrieved or set. Attributes have a fixed type defined in the IDL file.
In the CellML API, interfaces, attributes and operations are documented using Doxygen comments, to define their semantics. These are comments are automatically processed along with the IDL definitions, and used to generate the online documentation for the CellML API.
All IDL files in the CellML API can be found in the interfaces directory of the API source tree.
Every interface in the CellML API inherits from the interface XPCOM::IObject, defined in xpcom.idl. This interface defines the fundamental operations and attributes that can be performed on any object. Because this interface is so low-level, language bindings treat this interface in special ways, and so this interface is not presented as consistently between languages as other interfaces are. The basic attributes and operations of XPCOM::IObject are: The add_ref and release_ref operations: Memory management in the CellML API is based on reference counting; these operations increase and decrease the reference count. In many language bindings (for example, the Java and Python language bindings), these are called and implemented as appropriate for the user, and cannot be called manually. In the C++ binding, a header file provides utilities that mean the user rarely needs to call these manually. The query_interface operation: An object can support multiple interfaces; this operation is used to retrieve a different interface of the same object. The exact semantics vary by language; in the Python bindings, calling this interface manually is neither required nor useful, because the binding will dynamically dispatch an operation or attribute reference to the right interface. In Java, query_interface is not accessible as a property on an object, but instead, as a static method on the target interface. In C++, query_interface returns an object which can be recast to the appropriate type, but utilities are provided so the user never needs to worry about the details. Refer to the documentation on the applicable language binding for more information. The objid attribute provides a unique identifier for the underlying object, as a string. This is useful for comparing whether two pointers or references to an object is identical, and for putting objects in a hash table. The supported_interfaces attribute provides a list of interface names supported by an object.
The API is divided up into core and extension modules. CellML_APISPEC.idl contains the core of the CellML API itself - this references the standard W3C defined DOM and MathML interfaces. Other files define extensions to the CellML API that implementations may optionally provide (and which the reference implementation does provide).
The API reference implementation
All parts of the API are implemented in the reference implementation. The source code for the core part of the API can be found in sources directory, under further subdirectories. The cellml subdirectory provides the CellML core implementation. The dom and dom_direct subdirectories contain the implementation of the W3C Document Object Model; note that the DOM implementation is called dom_direct because it does not wrap any other DOM implementation; the API has been designed so that an alternative DOM implementation that wraps another implementation could be used as an alternative. The rdf subdirectory contains the implementation of RDF and RDF/XML, which, if enabled, is compiled into the CellML API implementation core libraries. The mathml subdirectory contains the W3C MathML DOM implementation. The cellml_context subdirectory contains code that can be used to let users of the CellML API communicate a list of models that are currently open, supported modules, and annotations on services.
Other services are provided in other toplevel directories. Refer to the corresponding IDL files for details of what these services do.
The CellML API comes with testcases that can be used to check that the code performs as expected (unit tests) and that problems which occurred in the past are not re-occurring. Tests live in the tests directory. There are several types of tests that are performed: direct API tests are defined using CppUnit, and are all linked together to produce the RunTestBin binary. Indirect tests use test programs that do things like convert CellML models into C, or run a simulation. Shell scripts are defined that run these programs over a series of models, and check the output matches what is expected.
Language bindings
The CellML API implementation includes code to transform the IDL files to produce header files for languages like C++, and to produce bridges to allow the API to be used from other languages. This code is written in Python as a series of omniidl modules, and is stored in simple_interface_generators in the source tree. The omniidl backend modules are stored in simple_interface_generators/omniidl_be, while language specific glue code is stored in simple_interface_generators/glue.
Build system
The CellML API makes use of a CMake-based build system. The build subdirectory contains the core CMake files whose utility spans multiple modules; these are ultimately included by CMakeLists.txt in the root of the source tree. CMake files for each individual module are stored in the subdirectory for that module.
When source code is committed to the repository, it is automatically built on multiple platforms by the buildbots. The buildbots retrieve the source code every minute from a local cache of the source code repository (which is itself updated every minute); once they detect that the tree has been stable for
Communications about the API and its implementation
A developer list, open to anyone interested, called cellm, is provided for discussion about CellML tools, including the CellML API. Subscribe at l-to ols-d evel opers @cel lml.o rghttp://lists.cellml.org/mailman/listinfo/cellml-tools-developers . Important issues of broader interest to the CellML Community are discussed on cellm, which is also open to the public - subscribe at l-di scuss ion@ cellm l.or ghttp://lists.cellml.org/mailman/listinfo/cellml-discussion .
Bugs, feature requests, questions, and design discussions can be entered and tracked at https://tracker.physiomeproject.org/ - such bugs, feature requests, questions, and design discussions are collectively called tracker items, and are given a unique number. Anyone can view the contents of the tracker, and anyone can sign up for an account and use that account to create tracker items. When prompted, choose CellML as the Classification, and CellML API as the product.
API Release Schedule
The CellML API has a nominal release schedule of one release every 3 months. However, due to the small size of the team working on the CellML API, releases are often deferred to ensure that the feature set provided by new releases in sensible and coherent, major bugs have been fixed, and that the code base is sufficiently stable.