Chronological Thread 

< Chronological >      < Thread >

---

Hi Richard,

With regards to Unit/Units, see for example
https://en.wikipedia.org/wiki/SI_derived_unit which consistently uses
singular and plural in the way that I described. Given that we are going
to finalise the CellML 1.2 spec in light of what we learn from LibCellML,
there is an opportunity to fix the spec too. I don’t think it is
worthwhile spending the time trying to survey how common it is in the body
of scientific literature to use the plural to refer to the singular for
the term unit, so I think it is better to just do what is obviously more
correct.

Please see the e-mail I sent (that you just missed) regarding more
explanation of the benefits of using sub-namespaces.

My hunch is still that Manager will be necessary, it depends somewhat on
the question regarding how serialisation and deserialisation work in the
context of imports, as well as some other factors.

The “just in time” (what you mean by JIT, I assume) use of lower level
objects is consistent with the higher level API using the lower level API.
The section isn’t “vague”, it’s at exactly the expected level considering
the stage of the project and the document in which it resides, and the
fact that the accompanying code itself provides more detail. Further work
on coding how serialisation and deserialisation work will inform further
iteration on this aspect of the design. For example, we might consider
the visitor pattern in future.

Regards,
Randall

On 3/02/15 12:16 pm, "Richard Christie"
<r.christie AT auckland.ac.nz>
wrote:

>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
>

---

• Re: [[cellml-dev] ] Feedback on libCellML design document, Randall Britten, 02/03/2015
  • <Possible follow-up(s)>
  • RE: [[cellml-dev] ] Feedback on libCellML design document, Richard Christie, 02/03/2015
    • Re: [[cellml-dev] ] Feedback on libCellML design document, Randall Britten, 02/03/2015
      • Re: [[cellml-dev] ] Feedback on libCellML design document, David Nickerson, 02/03/2015
        • Re: [[cellml-dev] ] Feedback on libCellML design document, Randall Britten, 02/03/2015
          • Re: [[cellml-dev] ] Feedback on libCellML design document, Randall Britten, 02/04/2015
            • Re: [[cellml-dev] ] Feedback on libCellML design document, David Nickerson, 02/04/2015
              • Re: [[cellml-dev] ] Feedback on libCellML design document, Randall Britten, 02/09/2015
              • Re: [[cellml-dev] ] Feedback on libCellML design document, David Nickerson, 02/10/2015
              • Re: [[cellml-dev] ] Feedback on libCellML design document, Randall Britten, 02/12/2015

---

Archive powered by MHonArc 2.6.18.