Chronological Thread 

< Chronological >      < Thread >

---

Hi all,

I am going through Jonathan's e-mail to make sure we have tracker items
for everything raised. I am annotating his e-mail with tracker item
numbers. If I missed any issues that were described somewhere please
feel free to file tracker items on them.

Best wishes,
Andrew

Catherine Lloyd wrote:
> Just incase that wasn't clear, here is Jonathan's feedback.
>
> Best wishes
> Catherine
>
>
> Begin forwarded message:
>
>> *From: *Jonathan Cooper <jonathan.cooper at comlab.ox.ac.uk
>> <mailto:jonathan.cooper at comlab.ox.ac.uk>>
>> *Date: *19 September 2008 4:04:41 AM
>> *To: *Catherine Lloyd <c.lloyd at auckland.ac.nz
>> <mailto:c.lloyd at auckland.ac.nz>>
>> *Subject: **Evaluation of the CellML API*
>>
>> Hi Catherine,
>>
>> I thought it was about time I sent you my thoughts so far on the
>> CellML API. For many of the issues I've discovered I have raised
>> items in the bug tracker, but I also have more general comments which
>> didn't seem appropriate to raise there.
>>
The aim to use the tracker for any issue which will ever eventually be
resolved (not only 'bugs'); we can also have 'meta' tracker items. For
this reason, I am opening a number of additional tracker items in
response to this e-mail.

>> I trust you'll be able to forward them to the appropriate place.
>>

It is worth noting that cellml-tools-developers at cellml.org is a good
mailing list to be on, and to send comments to, for anyone working on
CellML tools. The list is open for anyone to join, and it is also
publicly archived.

>> There is much that is good about the API, and I have eventually
>> managed to do some useful things with it (as an experiment while
>> learning the API, I have written a small program to convert a model
>> from CellML 1.1 to 1.0; I can send the source code if that would be
>> of interest). The services implemented seem sensible, and many of
>> the algorithms one would want to use in processing a CellML document
>> are available, with the notable exception of convenient
>> metadata-related functionality (although this is being worked on).
>>
Tracker item 358, although we might also need other ones for more
specific APIs.
>>
>> However, it is hard to give a thorough evaluation, since it is very
>> difficult for a newcomer to get to grips with using the API. My main
>> comments are thus related to documentation, with some suggestions for
>> improvements to the core API. I have not looked at most of the
>> associated services in as much detail.
>>
>> The documentation (for developers) is very poor (contrast libSBML,
>> for example, which has extensive docs including pages to get you
>> started easily). I would particularly like to see high-level
>> documentation, describing the architecture of the API and the various
>> services provided, how they work together, and what algorithms are used.
New tracker item 1395.
>> If we want greater community involvement in developing and using the
>> API and related tools & services, work on developer-oriented
>> documentation is crucial. Providing a fully featured and easy to use
>> API is a major step to encouraging more developers to support CellML.
>> (Providing other language bindings is related to this point. Have the
>> libSBML developers been asked about their experiences in this respect?)
>>
>> There is some basic documentation out there, but it is scattered all
>> over the place. Collating it in a central location on the cellml.org
>> site would be a good start. For example:
>>
>> *
>>
>> While reading about PCEnv, I also found
>> http://www.cellml.org/tools/CellMLToolsPlan which gives a nice
>> overview of the main parts of the API used by PCEnv, and how
>> CORBA fits in to the picture. More along these lines would be
>> nice; perhaps a 'just enough CORBA to understand the API' guide
>> (i.e. the implications of CORBA restrictions on the design of
>> the Physiome CellML Mapping)?
>>
>> *
>>
>> Some of Andrew's emails have more information, for example on
>> CCGS refactoring, AnnoTools, CUSES, CeVAS
>>
>> <http://www.cellml.org/pipermail/cellml-discussion/2007-May/000592.html>,
>> MaLaES
>>
>> <http://www.cellml.org/pipermail/cellml-discussion/2007-May/000586.html>,
>> types (TLCS)
>>
>> <http://www.cellml.org/pipermail/cellml-discussion/2008-July/001319.html>.
>>
>>
>> *
>>
>> There is a little more documentation on the CORBA mapping here
>>
>> <https://svn.physiomeproject.org/svn/physiome/simple_interface_generators/trunk/docs/>.
>> This includes some discussion of reference counting and
>> policies for memory management. (Incidentally, the docs here
>>
>> <https://svn.physiomeproject.org/svn/physiome/simple_interface_generators/trunk/docs/MemoryManagement.txt>
>> and here
>>
>> <https://svn.physiomeproject.org/svn/physiome/simple_interface_generators/trunk/docs/PassingObjectReferences.txt>
>> are inconsistent as regards who retains ownership in the event
>> of exceptions.)
>>
>> *
>>
>> The IDL files also have basic documentation, but this isn't
>> sufficient to allow easy use. Hyperlinked versions would be a
>> start (tracker item 1344
>> <https://tracker.physiomeproject.org/show_bug.cgi?id=1344>).
>>
>> *
>>
>> I've written some notes as I was learning how the API works;
>> these are attached, and you are welcome to use them however you
>> wish.
>>
>> The source code isn't particularly well commented, which makes the
>> lack of documentation more of an issue.
>>
>> There are also several specific areas where I'd like to see
>> additional functionality, for which I have not yet opened tickets. I
>> can either do so, or discuss them by email first, at your
>> preference. Some of them have been inspired by features of libSBML,
>> which I have also been looking at, and there is also at least one
>> area where there is the possibility for libSBML to benefit from ideas
>> in the CellML API. Do you have existing links through which this
>> could be discussed?
The tracker is a good place to suggest ideas for discussion (with one
tracker item per idea). It is possible that there are already tracker
items for some of these ideas.

>>
>> I trust you had a good visit at Manchester.
>>
>> Jonathan
>>
>>
>> Imports
>>
>> A discussion of the semantics of <import> elements, and how imports
>> are dealt with by the CellML API.
>>
>> An <import> element essentially acts to set up a 'template instance'
>> of the model it references. This template can be used to create units
>> and components (and associated connections) in the importing model,
>> by including <units> and <component> elements within the <import>
>> element. If the same model is referenced by /n/ <import> elements,
>> then /n/ templates are set up. This allows the same component to be
>> safely imported /n/ times (see tracker item 1352
>> <https://tracker.physiomeproject.org/show_bug.cgi?id=1352> for more
>> discussion on this point - note that while it is not illegal to
>> reference the same component multiple times in a single import, it
>> won't work, and will be illegal in CellML 1.2).
>>
>> In the API, there is a strong distinction in behaviour depending on
>> whether imports have been instantiated or not. An <import> element is
>> instantiated by loading the referenced model as a distinct instance
>> of cellml_api::Model (CellMLImport.importedModel), with its own
>> unique identification number (CellMLImport.uniqueIdentifier). If the
>> same model is imported /n/ times, you get /n/ Model instances, each
>> with a different id.
>>
>> The case where an import is not instantiated is easier to comprehend.
>> In this case the referenced model is not loaded. The only access to
>> imported components is then via their ImportComponent object. Since
>> the referenced model has not been loaded, we know nothing about the
>> internals of the component (for example whether it has variables) -
>> we only know what is declared in the importing model, for example its
>> name (as given in the importing model) and componentRef.
>>
>> Note that ImportComponent inherits from CellMLComponent, and so
>> shares all its attributes. However, note that those attributes
>> describe the component as it exists in the /importing/ model, not as
>> it is defined in the model it is imported from. For example, its name
>> is that given by the name attribute on the <component> element inside
>> the <import> element, and so may differ from the name it is given in
>> the model which defines it. Also, attributes such as parentElement
>> and modelElement are resolved within the importing model, and so
>> refer to the <import> element and the importing Model, respectively.
>> If the import has not yet been instantiated, then many of the
>> attributes from the CellMLComponent interface will raise a
>> CellMLException when accessed, since the information required to
>> determine their values is not available. The attributes name,
>> parentElement, and modelElement are safe to access.
>>
>> When an import is instantiated, the referenced model is loaded, and
>> so we have a new Model object representing it, along with
>> CellMLComponents, etc. (possibly also ImportComponents if it also
>> imports models). For each ImportComponent in our importing model, one
>> of these components in the imported model will be the 'template' for
>> it - which one can be determined by CeVAS's algorithm, described
>> elsewhere <#CeVAS>. This is used to fill in the internal details
>> (e.g. variables & maths) of the ImportComponent; its name,
>> modelElement, etc. are still that given by the importing model.
>> Properties of the template component still reflect its place in the
>> imported model; from its point of view there is no importing model.
>> Note that objects for internal details of the ImportComponent, such
>> as its variables and mathematics, just reference the template
>> component - exactly the same CellMLVariable objects are used, for
>> example. Similarly encapsulationChildren contains actual component
>> objects from the imported model, rather than copies, and
>> ImportComponent.connections references the template rather than the
>> ImportComponent. (Incidentally, accessing CellMLComponent.connections
>> on imported components that are not templates for an ImportComponent
>> (e.g. encapsulated children of such a template component) appears to
>> always raise an exception.)
>>
New tracker item 1396.
>>
>> Other attributes also change their values after imports have been
>> instantiated. For example Model.connections always gives the set of
>> connections defined directly within the model. However, prior to
>> instantiation these reference the ImportComponent objects within the
>> model, whereas after instantiation they reference the template
>> components. Prior to instantiation accessing
>> CellMLImport.importedConnections raises an exception; afterwards
>> these connections reference template components.
>>
>> It is the fact that template components do not reference the
>> importing model in any way that gives rise to the sometimes confusing
>> behaviour of allComponents. The localComponents attribute on a model
>> fetches just those components directly defined in the model.
>> modelComponents will also return the ImportComponent objects defined;
>> what these contain will depend on whether the import has been
>> instantiated, as described above. On the other hand, allComponents
>> will only give you an ImportComponent if the corresponding import has
>> not been instantiated - if it has then you will get the template
>> component instead. You will also get every component defined in the
>> imported model, even if it is not used by the importing model.
>> Furthermore, if the same model is loaded via /n/ <import> elements,
>> you will get /n/ copies of each of its components. Since components
>> not used by the importing model do not have a name in that model (and
>> indeed components used only because their encapsulation parent was
>> imported also don't have a name in the importing model),
>> allComponents.getComponent must be passed the name used in the model
>> which originally defined the component; this is also implied by the
>> fact that it contains the template component, not the ImportComponent.
>>
>>
>> CeVAS
>>
>> The CeVAS, or CellML Variable Association Service, provides services
>> which make it easier to work out which variables are the same (i.e.
>> connected), and so reduces the complexity of working with models
>> which have mathematics spread across multiple components, possibly
>> imported from multiple documents. This is done in 2 primary stages:
>> firstly working out which components are relevant to the use of the
>> model (ignoring unused components in imported models), and secondly
>> using a disjoint-sets algorithm to collect connected variables into
>> sets. In performing this task CeVAS doesn't use many of the 'helpful'
>> attributes in the API (such as CellMLComponent.connections), but
>> implements its own algorithms, described here.
>>
>> The 'relevant' components returned by CeVAS are always 'real'
>> components, that is it will not return an ImportComponent, but rather
>> the CellMLComponent providing a template for it (see also the
>> discussion on imports <#imports>). This real component is found by
>> the following algorithm:
>>
>> 1.
>>
>> If the component /c/ doesn't expose the ImportComponent
>> interface, we're done.
>>
>> 2.
>>
>> Otherwise, get the parentElement and query it for the
>> CellMLImport interface (which will succeed).
>>
>> 3.
>>
>> Then get the importedModel from that, and its modelComponents.
>> Find the component there with name /c/->componentRef (using
>> getComponent) and repeat from step 1.
>>
>> When finding the relevant components for a model, CeVAS first adds
>> the real components for all members of Model.modelComponents. Each
>> imported model touched in this process (termed a relevant model) is
>> queued, and the groups defined in it used to locate relevant
>> encapsulated components (i.e. CeVAS doesn't use
>> CellMLComponent.encapsulationChildren). The encapsulation tree is
>> walked, and components are looked up by finding the componentName on
>> ComponentRefs in modelComponents and using the algorithm above to
>> find the real component. This real component is then looked up in the
>> set of relevant components to determine if it is relevant; if it is
>> then its children found by walking the encapsulation tree are also
>> marked as relevant.
>>
>> Once relevant components are found, CeVAS then works out which
>> variables are connected, using a disjoint-set data structure
>> <http://en.wikipedia.org/wiki/Disjoint-set_data_structure> (merging
>> sets when a connection is found). The structure is initialised with
>> singleton sets for each variable defined in each relevant component,
>> and a mapping varToDSMap is created from each variable object to the
>> disjoint set containing it. CeVAS then iterates over connections
>> defined in relevant models, and over variable maps within these. It
>> uses MapVariables.firstVariable and MapVariables.secondVariable to
>> find the associated CellMLVariable objects, and looks them up in
>> varToDSMap - if either is not found, then this is not a connection
>> between 2 relevant components; otherwise the associated disjoint sets
>> are merged. After all connections are processed, the disjoint sets
>> are converted into cellml_services::ConnectedVariableSet objects, for
>> user convenience.
>>
>

---

• [cellml-dev] Fwd: Evaluation of the CellML API, Andrew Miller, 09/24/2008

---

Archive powered by MHonArc 2.6.18.