libcellml Documentation

Transcription

1 libcellml Documentation Release 0.1 David Nickerson, Randall Britten August 27, 2014

2

3 Contents 1 Introducing the libcellml project The motivation for the libcellml project Status of CellML Expected availability libcellml Roadmap High level objectives Environment Milestone 0: setting up development environment (timeframe: 8 working days) Milestone 1: starting to get useful code (timeframe:? months) Milestone 2: toward simulation support (timeframe:? months) Milestone 3: functional library for tool developers (timeframe:? months) Milestone 4: advanced capabilities (timeframe:? months) Milestone 5: broadening accessibility (timeframe:? months) libcellml Object Model Introduction Preamble Overview of object model Model class Details for variable object model Encapsulation Units of measure Imports Stand-alone methods Todo Indices and tables 15 i

4 ii

5 Contents: Contents 1

6 2 Contents

7 CHAPTER 1 Introducing the libcellml project Randall Britten, 27 August 2014 The libcellml project aims to provide a library for working with CellML, focussed on CellML 1.2, but with limited support for older formats (i.e. CellML 1.0 and 1.1). 1.1 The motivation for the libcellml project A fresh start at creating core software support for tool developers that would like to make use of the CellML standard in their tools. LibCellML will be implemented in a manner that makes it easier and more natural to work with than the previous CellML API project. Some further information is available in the libcellml Roadmap. 1.2 Status of CellML 1.2 There is not yet a document that represents CellML 1.2 will differ from the previous version. However, the following are good sources for indicating what CellML 1.2 might look like: 1. Starting point document for editorial board working draft. This currently describes CellML 1.1 minus reactions. The aim is to incrementally edit this with version history mapping to the relevant tracker items so that a good provenance record is available. 2. An reporting on the planning for CellML 1.2 at the 2012 CellML workshop 3. A rendering of one proposal from previous work towards a draft of CellML 1.2 that was done before the editorial board process was in place. Note however that this assumes the use of MathML 3. In conjunction with this, there is this draft of a secondary specification which captures the types of models usually represented using previous versions of CellML. The editorial board plans to use some of the text from these drafts. 1.3 Expected availability At this stage, it has been decided to undertake the libcellml project based on rough time estimates only, hence there is very little certainty yet as to when the first versions that are practically useful will be available. The libcellml project will aim to deliver some functionality as early as possible. An iterative development methodology will aim to provide updated versions with additional functionality regularly. Again, please see libcellml Roadmap. 3

8 4 Chapter 1. Introducing the libcellml project

9 CHAPTER 2 libcellml Roadmap David Nickerson, 9 June 2014 Contributions from Alan Garny, Jonathan Cooper, Mike Cooling, Tommy Yu, Hugh Sorby, Randall Britten and the CellML Community but no time yet for full consensus. These requirements and milestones are derived from the CellML API May 2014 Requirements collected from the CellML community, with input from the primary target users (application developers) and the CellML Editorial Board. Previous editorial board discussions have also been incorporated into this roadmap. Clearly the milestones defined below are to be worked on in numerical order and previous milestones will be completed before work on subsequent milestones begins. Each milestone may consist of several releases and future requirements may impact the design and implementation of earlier releases of libcellml. Major changes in the API will be accepted upto the release of libcellml version Contents libcellml Roadmap High level objectives Environment * Requirements Milestone 0: setting up development environment (timeframe: 8 working days) Milestone 1: starting to get useful code (timeframe:? months) Milestone 2: toward simulation support (timeframe:? months) Milestone 3: functional library for tool developers (timeframe:? months) Milestone 4: advanced capabilities (timeframe:? months) Milestone 5: broadening accessibility (timeframe:? months) 2.1 High level objectives 1. Focus on CellML 1.2 and beyond. 1. The implementation of libcellml should be driven by the requirements for supporting 1.2 and future versions. 2. Implementing support for core+secondary specs is likely to be a big challenge for libcellml. 1. libcellml should be designed to support the core spec with the flexibility for extra restrictions/constraints coming from the secondary specification. 2. multiple secondary specifications could be used in one model. 5

10 3. secondary specifications may exist for a period of time before they are integrated or consolidated into a new CellML version (if at all, there is still a lot to learn about how secondary specifications will evolve) 1. libcellml should always be able to import earlier version models. 2. To begin with, libcellml must be able to export 1.2 models to 1.1 (probably using API marked as deprecated from the beginning and removed once Milestone 3 is achieved). 1. Develop the libcellml API as work progresses through the milestones outlined below. 2.2 Environment This section will specify the environment for the development of libcellml. GitHub to host the primary libcellml source repository and issue tracker under the CellML organisation (editorial board members) Development language: C++ with SWIG bindings Build: CMake for generating cross-platform build rules Test: Using Buildbot on the BaTS to run continuous integration testing Test: Unit testing to use gtest Documentation: Written in re-structured text. Documentation: API and source code examples will be documented using c++-style doxygen comments Requirements Documentation: Made available on readthedocs.org. readthedocs uses Sphinx for generating documentation. Development: Agile and test driven development where: Functionality more important than API stability in early releases. Release early and often Development: Code review prior to acceptance into the primary repository using the pull request feature on GitHub Development: Objectives are added and broken down into incremental tasks Development: A single task should be no more than two weeks Development: The next objective to be worked on is discussed and agreed with the community before work is started on an objective We should avoid using non-standard system libraries unless there is a compelling reason. Once features are available the API can be fine tuned in consultation with the CellML community. 2.3 Milestone 0: setting up development environment (timeframe: 8 working days) To be completed on Tuesday 2nd September Share an UML-esque document with the community via github describing CellML specific object model. 6 Chapter 2. libcellml Roadmap

11 The form of the API to libcellml should not be dictated by the XML serialisation but by the objects tool developers desire to work with. 2. Setup the cross platform build and test environment using the ABI s build and test server (BaTS) Builds required: Windows 64 bit, OSX 10.9, Ubuntu bit 3. Document the development process/workflow How we are to implement agile and test driven development How code reviews are done 2.4 Milestone 1: starting to get useful code (timeframe:? months) 1. Create a CellML 1.2 model from scratch and save it to XML (a) create a new model, add imports, components, variables, and math. (b) the first test case? 2. Load a CellML 1.2 model, make changes, save it. (a) ability to preserve underlying XML structure/ordering for documents read in and written out. 3. Load a CellML 1.2 model and validate it (a) this is important to get out early as it will help make sure the normative specification is complete and sensible. (b) will ensure we can test models as we work on getting the specification completed (c.f. the error ridden examples from 1.0 and 1.1 specifications). (c) includes proper units validation of the mathematics. (d) libcellml should have a validation framework based on the core specification and then secondary specs can add their specific rules 4. for 1.2 this is mainly the mathematics, so core validation can probably validate the model but need the actual restricted subset of mathml from the secondary spec is needed to fully validate units consistency. 5. Import CellML 1.0/1.1 models. 6. Export to CellML 1.1 in order to use model in existing tools (e.g., simulation, annotation, NeSI), preserving model and XML structure/ordering/modularity where possible. 7. Platform support: OS X, Linux, Windows (a) native installers (using CPack, pip) (b) easy to setup build environment (good documentation) 8. Language support: C++, Python, Java, Matlab 9. Documentation available (a) API (b) Tutorials/documented code examples (c) Integrating libcellml into various common IDEs (Visual Studio, Eclipse, Qt Creator, NetBeans... ) 2.4. Milestone 1: starting to get useful code (timeframe:? months) 7

12 2.5 Milestone 2: toward simulation support (timeframe:? months) 1. Conversion to intermediate representation (a) Conversion to CellMLstructureless mathematics (just the maths) into an intermediate representation that can be transformed / analysed by other tools. With units. (b) Ability to maintain the CellML structure (as much as possible), perhaps via object annotation (e.g., COR) (c) Will form the basis for tools using libcellml to perform numerical simulation. 2. Improved support for model authoring/editing/manipulation (a) Provide an events system to monitor changes in the model (b) provide access to data contained in CellML models in external namespaces (RDF, extensions, etc). 3. Documentation, documentation, documentation. 2.6 Milestone 3: functional library for tool developers (timeframe:? months) 1. Establish the process/api required to generate procedural code from the intermediate representation (a) Generic code vs solver specific code. (b) Could be a role for being informed from SED-ML what solver is to be used and customising generated code appropriately. (c) Would be a tool sitting on top of libcellml, not directly part of it. 2. Being able to run simulations with CellML 1.2 (a) while not directly part of libcellml, helping tool developers get to the point where they can execute simulations is critically important. (b) CellML 1.2 will not be released until we can do this (in addition to the other requirements above) 2.7 Milestone 4: advanced capabilities (timeframe:? months) 1. High order model manipulation (recall discussion with Andrew McCulloch at the 8th workshop) (a) again, outside core libcellml, but helping tool developers provide these kinds of services is very important. 2.8 Milestone 5: broadening accessibility (timeframe:? months) 1. Support for more platforms (a) Android, ios 2. and languages (a) JS, C#/.NET, C, Fortran[ XX] 8 Chapter 2. libcellml Roadmap

13 CHAPTER 3 libcellml Object Model Randall Britten, 26 August Introduction The object model is (currently) a very high level conceptual design. The focus has been on a design to support the initial use case from the roadmap (i.e. Create model, save as XML. An isvalid method does not yet exist in the design, since the validate use case follows later). 3.2 Preamble UML images are created using Eclipse/Papyrus. Some detail may not show in the diagrams, or be explained in this text, so if you are in doubt, please refer to the model details in Eclipse/Papyrus. Collections are often indicated as an association from one class to another (or the same class if the containment is recursive) on a class diagram. At this stage, methods for adding and removing from the collection are omitted from the diagram. Often, some of the member operations and properties of a class are hidden on some of the diagrams on which it appears. Also, a class may be shown multiple times on the same diagram. Remember to pay attention to the arrows indicating navigability of associations, as well as the cardinality of the association ends. It was realised recently that some cases where UML classes have been specified should perhaps be interfaces. 3.3 Overview of object model Shown in this overview: 1. A model has a collection of components and a collection of units. 2. A component has a collection of variables, and a collection of Maths objects. This design does not yet have any details for how maths is represented, it will probably be the abstract syntax tree (AST) of the MathML. 3. A component also has a collection of the units defined within the component. 9

14 3.4 Model class 1. getxml returns the XML serialisation for the model as text (alternate representations should be considered, e.g. AST or DOM). 2. addimport creates the Import object with just the URL provided as a string. 3.5 Details for variable object model 1. Variables may be real or boolean. (Real is taken to mean that the codomain is real. Thus state variables are treated as real variables, even though they are actually real valued functions of the variable of integration (VOI). Constant real values fall into this category (i.e. real is isomorphic to () -> reals, where () is the nullary Cartesian product). 2. Only real variables have units. 3. Variables have a collection (which may be empty) of the variables to which they are connected. Note that this is not normalised at this conceptual level, (i.e. From A you can see B in the list of connected variables, and from B you can see A in the set of connected variables. Nevertheless, the implementation is likely to be normalised, and the XML representation likewise will have a normalised representation, where a connection element indicates that A is connected to B. 3.6 Encapsulation 1. A component object has a collection of components that are encapsulated by it. This is recursive. Note: the design allows for cycles, but the spec does not. 10 Chapter 3. libcellml Object Model

15 3.6. Encapsulation 11

16 3.7 Units of measure 1. The base class has a property for the unit name, and a boolean flag to indicate whether the unit is built-in. 2. Units may be either base units or derived units. 3. A derived unit has a collection of UnitsReference objects that represent the definition of the derived unit. 3.8 Imports 1. The component class has a subtype for imported components. 2. An imported component s local name is the stored by the inherited name attribute, the name of the component in the imported file is stored in the remotename attribute. 3.9 Stand-alone methods Methods not shown on UML yet, but would be useful. 1. getbuiltinunits() : [Unit] - returns a collection of the built-in units Todo 1. Some documentation of classes, operations etc in this document probably belong as documentation in the Papyrus model, and eventually as the Doxygen comments on the C++ code, Python docs, Java docs etc. 2. Details of math representation an utilities 3. Details of XML representation and utilities 12 Chapter 3. libcellml Object Model

17 4. Change classes to interfaces where appropriate Todo 13

18 14 Chapter 3. libcellml Object Model

19 CHAPTER 4 Indices and tables genindex modindex search 15