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: Richard Christie <r.christie AT auckland.ac.nz>
  • To: Randall Britten <r.britten AT auckland.ac.nz>, "cellml-tools-developers AT cellml.org" <cellml-tools-developers AT cellml.org>
  • Subject: RE: [[cellml-dev] ] Feedback on libCellML design document
  • Date: Mon, 2 Feb 2015 23:16:45 +0000
  • Accept-language: en-GB, en-NZ, en-US
Hi Randall,

I don't think you're going to get traction with changing the name 'Units' to
'Unit', as that is what they are called in the science literature and in the
CellML spec. I agree that having a class defined with the plural is
annoying/limiting when defining names of collection objects and APIs, but
there are solutions e.g. getUnitsCount() instead of getNumberOfUnits() (c.f.
getNumberOfComponents for "Component"), getUnitsList() instead of getUnits().

Like others, I also don't see the need for sub-namespaces, and the Model
Manager object is not properly justified. Better to keep it simple until the
need for these arises. My understanding is that the core libcellml is going
to be pretty tight and simple; other services such as code generation would
be independent libraries and would not share the same top-level namespace.

In 'Structure overview' you state the API makes use of lower-level APIs for
working with CellML DOM and XML DOM trees, and in your previous
communications you have indicated that underneath the high-level object
interfaces are representations in the lower level objects. However, in your
serialisation test the lower level objects are only generated JIT for writing
to XML. This section is vague about the intentions here. Is all this not just
an implementation detail - should this section be removed?

Cheers,
Richard

-----Original Message-----
From: Randall Britten
[mailto:r.britten AT auckland.ac.nz]

Sent: Thursday, 29 January 2015 4:33 p.m.
To:
cellml-tools-developers AT cellml.org
Subject: Re: [[cellml-dev] ] Feedback on libCellML design document

Hi Andre

I¹m not sure what the destiny of the existing libCellML C++ code in my fork
is. I don¹t see any reason why it shouldn¹t be included as part of
libCellML, but if for some reason it doesn¹t get included, it nevertheless
already has had some impact on the libCellML design, by virtue of the fact
that it has shed light on a lot of design questions already. Again, this is
one of the key aspects of the agile methodology: you learn more from actual
working code than you can from working theoretically. I agree that existing
code should pose no limit on the design. Where we see an opportunity for a
better design, we should usually refactor our existing design (sometimes that
may be impractical, but I am not aware of any currently proposed design
suggestions that would be impractical at this early stage).

My understanding of how secondary specifications will work is based on hours
of design discussions had with most of the key contributors to CellML years
ago (including yourself). This was captured in one of the CellML v1.2 drafts:
³
3. Secondary specifications

1. A CellML Secondary Specification SHALL be a document that places
additional restrictions on the structure and interpretation of CellML
Models and CellML Infosets.


2. CellML Secondary Specifications MUST NOT conflict with, or override, any
of the assertions or requirements in this specification.


3. CellML Processing software MUST either:


1. support one or more specific CellML Secondary
Specifications, and correctly process all models that comply both with
this specification and with one or more of the selected CellML Secondary
Specifications, or,


2. correctly process all models that comply with this specification.


4. Despite the previous paragraph, CellML Secondary Specifications
MAY identify particular unambiguously defined subsets of all CellML
Models as being optional for implementors, and CellML Processing
Software MAY choose to exercise such options.
²
Full doc at http://codecurve.github.io/cellml-core-spec/#idm179951603232

The way I understand it, processing for the core spec is more general than
processing for secondary specs, so my approach has been to focus initially on
the core spec. In other words, since any document that complies with a
secondary spec also complies with the core spec, it will be able to be
processed by software that complies with the core spec. I expect the same is
true regarding an XML schema: any document that complies with a secondary
spec will also comply with an XML schema that represents the core spec
(within the limits of the XML schemas technologies). The approach of
generating low level XML structure handling from a schema seems very
promising from my limited experience with it so far, and offers a huge saving
w.r.t. development time/costs. I suggest we run with it as long as we can,
but if it ever turns out to be more of a hinderance than a help, then we
should consider alternatives.

Good point though that some mention of handling of secondary spec issues
could go in the design doc, since I haven¹t been working on use cases yet
related to secondary specs, there hasn¹t been a need to yet (again, that fits
with my understanding of how the agile methodology works).

One option for v1.2 and future versions of CellML (e.g. 1.3, 2.0, 77.2.9
etc) and future versions of secondary specifications is to specify validation
rules which can¹t be expressed in the various XML schema technologies using a
domain specific language (DSL) and processing of the DSL.

Namespaces
----------
Regarding nested namespaces, these would map well to other languages (e.g.
Java, Python), where the corresponding concepts (e.g. Packages, modules) have
more features than just for the avoidance of name collisions. Since having
them has virtually no cost, and potential future benefits, I suggest we keep
them. I¹ve made mention of the nesting in an update to the text (not pushed
yet), but bear in mind, as I¹ve said in numerous places that keeping
everything in sync is going to add up to a lot of effort, and that it really
is only truly important when the aim of the document is to explain the API to
users when we make releases, so it seems appropriate for this stage where the
design is still in flux to not spend exorbitant amounts of energy and time
trying to keep every last detail in sync.

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

I¹m glad that you like the overview class diagram :-)

With regards to naming of classes, attributes, etc, I think these are very
minor issues, and easy to fix, and certainly don¹t expect them to be the
focus of the discussion of the design document, but I will tidy them up, not
top priority though IMHO. Again, please do have a look at the C++ code or
Doxygen for a better idea of the names that have been used. The design
document that you are viewing served to get things going, and as explained
above, the effort to keep it in sync minute-by-minute with all the minor
details would be prohibitive.

With regards to the Model::addImport method, I think your suggestion is
interesting and I don¹t foresee any problems doing it the way that you have
suggested. I will need to give it some further thought. Ditto for imported
units.

With regards to a separate method for XML serialisation, it seems we all
agree, and in fact I had planned to implement that from some time ago, and
finally did it yesterday before generating the Doxygen for upload, haven¹t
had a chance to update the design doc yet.

Variables
---------
My response to Hugh has URLs to the draft CellML spec that I¹ve used as a
guide.
You asked earlier about where this traces back to (boolean and real types).
I think most of it came out of discussions, there are some traces of this in
the tracker, e.g. :
https://tracker.physiomeproject.org/show_bug.cgi?id=47#c15
And
https://tracker.physiomeproject.org/show_bug.cgi?id=1543
But overall, the process all happened a few years ago, and the doc was
distributed publicly to the CellML community a few years ago, and comments
and feedback on the document processed, so I think the best record of the
decisions is the document itself, as well as its version history (see
https://github.com/A1kmm/cellml-core-spec). You even made a few commits
yourself early on. I¹ve never really understood why you seem to want to
discard so much of this progress, it certainly does not seem to be in the
best interests of the CellML community.

Unit vs Units
-------------
I think Unit is a better name than Units. The plural is suitable for a
collection. It seems more correct, since we say things like ³a gram is a
*unit* of measure. Litres and seconds are also *units*².

Manager
-------
Needed for keeping references to multiple models that may have references to
each other due to imports, especially as such links might be in flux as model
structure gets edited by a user modifying models. Might not be needed if
your approach to imports could work, as I said, I¹m giving this some thought.

Thanks again for your feedback.

Regards,
Randall






On 28/01/15 11:21 pm, "David Nickerson"
<david.nickerson AT gmail.com>
wrote:

>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