Thanks to everyone who responded to this issue. We do appreciate your
NOTE: There are a couple more questions at the end of this email :-)
We have considered everyone's comments and anticipate doing the following:
Additions to API
1) A new function on an SBMLDocument - checkInternalConsistency; which
runs consistency checks on the internal representation of the model. It
is limited to reporting things that are not caught by the existing
consistency validators. Thus it will report that a FunctionDefinition
has an sboTerm set - even though the document is an L2V1 document. [This
NOTE: This is already implemented and in svn if anyone wants to give it
2) Two new constructors for each SBML component.
The first taking a level, version and optionally a set of XMLNamespaces.
This creates an object that knows it's intended level/version/xmlns
without belonging to a document.
The second takes an SBMLDocument * and creates the object with the
sbml document pointer set to the argument. Note the created object would
still need to be added to the model within the document.
Whilst we agree with Stefan that only allowing people to construct
objects within a designated document would eliminate a number of
problems; we feel that to remove any other constructors would be too
much of a backward compatability issue. Also we acknowledge Lucian's
point that sometimes you dont want to place an object within a document;
since libSBML has always allowed this - we wont change it now.
Changes to API
1) setXXX/addXXX functions will all change their return type from void
to unsigned int.
The code within the function will perform checks to establish whether
performing the function is valid.
If it is valid the set/add will be done and 0 returned.
If the function to be performed is not valid then the set/add will NOT
be done and an integer greater than 0 will be returned. In most cases
the return is likely to
be 1 but there are cases where there are different reasons why it is not
valid to perform the action and different values can be returned to
could return 1 - indicating that 4 is not a valid value for
could return 2 - indicating that is not valid to set spatialDimensions
in a l1 compartment
NOTE: this change will apply to ALL set/add functions not just those
related to SBML components i.e. the return type of setAttributes on an
XMLNode will also change from void to an unsigned int.
2) The setLevelAndVersion function on a document is currently an anomaly
since it does return a bool based on whether the conversion has been
performed. Changing the return type of this function will allow more
constructive failure information to be returned, however it may have
more of an impact on existing code.
QUESTION: Do we make this change ??
Release of new API
We agree that any changes to the API must be a 3.3 release BUT we also
have support for L2V4 that will hopefully be released soon; which would
also require a new minor version. At this stage from a work scheduling point
of view it would suit us best to bundle both the new API and L2V4 support
into one release.
QUESTION: Does anyone have a major problem with this ?