Chronological Thread 

< Chronological >      < Thread >

---

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

---

• [[cellml-dev] ] Feedback on libCellML design document, Randall Britten, 01/28/2015
  • Re: [[cellml-dev] ] Feedback on libCellML design document, Hugh Sorby, 01/28/2015
    • Re: [[cellml-dev] ] Feedback on libCellML design document, Randall Britten, 01/28/2015
      • Re: [[cellml-dev] ] Feedback on libCellML design document, David Nickerson, 01/28/2015
      • Re: [[cellml-dev] ] Feedback on libCellML design document, Hugh Sorby, 01/28/2015
        • Re: [[cellml-dev] ] Feedback on libCellML design document, Randall Britten, 01/29/2015
  • Re: [[cellml-dev] ] Feedback on libCellML design document, David Nickerson, 01/28/2015
    • Re: [[cellml-dev] ] Feedback on libCellML design document, Randall Britten, 01/29/2015
      • Re: [[cellml-dev] ] Feedback on libCellML design document, David Nickerson, 01/29/2015
  • <Possible follow-up(s)>
  • Re: [[cellml-dev] ] Feedback on libCellML design document, Randall Britten, 01/28/2015

---

Archive powered by MHonArc 2.6.18.