Chronological Thread 

< Chronological >      < Thread >

---

Hi Andre

Regarding namespaces, it is not true that their sole purpose is to avoid
name collisions. While that is true at a technical level, it does not
take some important aspects into consideration. The reason I have so far
separated libcellml into two sub-namespaces is to aid documentation, in
the spirit of having the code be as self-documenting as possible (for more
info on the benefits of code being self-documenting, see the book
“Refactoring”, by Martin Fowler).

The purposes of the libcellml::model namespace is to collect together
entities directly related to defining CellML 1.2 models, the goal here is
to stay close to the “business domain”.
The purpose of the libcellml::general namespace is to collect together the
various support entities (e.g. things that are more related to
implementation details. Getting the libcellml version string is a good
example, so is Manager, if we do eventually decide to keep it).

Other codebases achieve this by having conventions such as cumbersome
identifier prefixes, which mean that function names are always very
verbose, whereas namespaces and judicious use of “using namespace”
directives allows for shorter names to be used most of the time, which
also make code more readable.

Regards,
Randall



On 29/01/15 7:36 pm, "David Nickerson"
<david.nickerson AT gmail.com>
wrote:

>Hi Randall,
>
>Thanks for the quick response.
>
>I still don't believe the schema generated approach is going to be a
>viable and maintainable long term solution, but if you think its best
>to go down that road for now and switch it over later, then I see no
>problem going with that at this early design stage. Obviously we'll
>see how things go when the code gets reviewed and pulled into the
>prime repository.
>
>I guess you'll need time to wrap your head around my desired method
>for handling imports, and presuming we decide to go that route it will
>definitely make the Model Manager irrelevant. And without a model
>manager, there seems little point in the general namespace and so we
>can simplify things greatly by adopting the single libcellml namespace
>that seems to be the preferred approach. At least until such time as
>it can be shown that multiple namespaces are required.
>
>The remaining issues are, as you say, relatively minor and impact
>implementation rather than the high level design so I don't want to
>distract you from coming to the conclusion that my proposed approach
>for dealing with imports is totally awesome :)
>
>
>Cheers,
>Andre.
>
>
>On Thu, Jan 29, 2015 at 4:33 PM, Randall Britten
><r.britten AT auckland.ac.nz>
> wrote:
>> 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.rs
>>>>t
>>>>
>>>> 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
>>
>
>
>
>--
>
>
>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.