First login?
Lost password?
 
 
cellml-tools-developers AT lists.cellml.org 
A list for the developers of CellML tools

Text archives Help


Re: [[cellml-dev] ] Feedback on libCellML design document


Chronological Thread 
  • From: David Nickerson <david.nickerson AT gmail.com>
  • To: cellml-tools-developers AT lists.cellml.org
  • Subject: Re: [[cellml-dev] ] Feedback on libCellML design document
  • Date: Wed, 28 Jan 2015 23:21:19 +1300
Hi Randall,

Thanks for rebooting this discussion. Some feedback below from an
initial read through the document, in document order rather than any
kind of severity or priority. Obviously more feedback to follow
depending on responses to some of my questions below and if I get a
chance for a more thorough read through the current document.

But before that, I think it is important to be very clear that any
existing code will not have an impact on the design of the object
model. Obviously the code you have already written will help inform
any discussion and decisions, but libCellML is starting with a clean
slate and should not be limited in any fashion simply because some
prototype/exploratory code has been developed.

Structure overview
-------------------------

One of the most important changes being introduced in CellML 1.2 is
the separation of the core language specification from secondary
specifications that place limits on generality of the mathematical
flexibility of the core specification. This isn't mentioned anywhere
in this document, and it seems like such a fundamental part that it
should be - but maybe I am missing something? It seems that in this
proposal, fundamental parts of libCellML are generated from a schema,
its not clear to me how that can work. Conceivably, it might be
possible to create an XML schema for the entirety of CellML 1.2 and
generate code from that, I guess, but what happens to that code base
when users require extra or different secondary specs? or when CellML
1.3 or 2.0 is under development and libCellML needs to support that as
well as 1.2? is it just a case of being able to define the validation
rules at run-time or similar, based on the exact secondary
specifications being used in a particular instance?

More detail on the proposed approach might help clarify things.

Namespaces
------------------

The image seems to show the nested namespaces that you also describe
in other emails in this thread, but the text doesn't make any mention
of the libcellml namespace. I agree with Hugh's comments that there
really is no need for nested namespaces. If utility methods or objects
are important enough to expose in the public API, then I have no
problem with them being in a single libcellml namespace.

Overview of object model
----------------------------------

I like this image, it seems to have all the objects that I would like
to see in libCellML. Although 'unit' should be 'units' to match the
CellML specifications. There are some consistency issues in the names
and errors in the cardinalities, but they are minor issues that are
probably corrected in the code.

Model class
----------------

I don't like the idea of an "addImport" for the model. For me this is
the same as the discussion on a connection object, and the concept of
an import element is a property of the XML serialisation. It makes
more sense to me that users of libCellML are going to want to create
components that are actually references to external components rather
than wanting to go through the hassle of worrying about importing
instances of XML documents as a separate process to defining the
actual component.

I also like Hugh's notion of a serialise method which takes in a
serialiser configuration rather than a getXML method.

Variable object model
-----------------------------

As per other emails in this thread, I'm not sure where the real and
boolean variables and codomains are coming from?

As for the model object, it should be "units" rather than "unit".

Encapsulation
-------------------

This seems to make sense to me. The detection of cycles is a
validation rule and there isn't a reason for the object model itself
to enforce validity at all times, so that is fine with me.

Units of measure
-----------------------

This mostly seems fine to me, although again it should be "units"
rather than "unit" as these have very different meanings in the CellML
specifications. And switching to units would also bring in some
consistency with the "UnitsReference".

As mentioned above, I would prefer to see imports handled directly by
components and units, and so attributes like source URL and reference
to the units name in the source document would need to be added. And
also constructors for the case of creating a new local and remote
units would be required. It would be good to see such methods added to
the design document.

Imports - Components
-----------------------------

Its not clear where the Imports object is coming from? it is not shown
in the overview, but a model has an addImport method...

Again, as above, I would prefer to see imports handled directly as
components and units. The concept of an import object seems
unnecessary to me. There is no reason a imported component couldn't
store its source URL itself.

Model manager
---------------------

I'm struggling to see the need for a model manager in libCellML, This
seems like something that a tool which uses libCellML should take care
of if needed. If there is some reason why having a special object to
create models is needed, that would be useful information to add to
the design document.


Cheers,
Andre.

On Wed, Jan 28, 2015 at 10:49 AM, Randall Britten
<r.britten AT auckland.ac.nz>
wrote:
> Hi
>
> The latest version of the libCellML design document is available here:
> https://github.com/codecurve/libcellml/blob/uml01/docs/source/design.rst
>
> The design document does not completely match the design of the C++ code in
> my fork, since our aim at the moment is to get community feedback on the
> design, rather than to document the code.
>
> Please send feedback, I’ll aim to reply within a day when applicable.
>
> Regards,
> Randall Britten



--


David Nickerson
about.me/david.nickerson

Archive powered by MHonArc 2.6.18.

Top of page