LibSBML Release Notes
libSBML NEWS -- History of user-visible changes
======================================================================
Version 5.3.0 (2011-12-23)
======================================================================
STABLE RELEASE
* New features
- Errors reported by the matlab binding function 'OutputSBML'
have been improved to provide information about why the
structure is invalid.
- There is a new virtual function on an SBase object 'setElementText'.
This enables a user to store text that the read functions encounter
within an XML element. Previously such text was ignored as no such
text existed as a part of an SBML Core element. Some L3 packages
may use this XML feature and can thus utilize this function.
- There is a new function on an ASTNode 'returnsBoolean' that returns
a predicate indicating that the math of the ASTNode will return a
boolean result or not. The function has an argument of type Model
with a default value of NULL. Where necessary, that is, when the
ASTNode involves a call to a user defined function, the check is
done in the context of the supplied argument Model or the parent
Model of the particular ASTNode if no argument is supplied.
- There are new functions to facilitate the use of packages. The
SBMLExtensionRegistry has a 'disableUnusedPackages' function which
disables registered packages that are not being used by the target
SBMLDocument. The base SBMLExtension class has a function 'isInUse'
that will establish whether a package is being used by the target
document.
* Bug fixes
- The conversion code incorrectly converted an L3 model where the
stoichiometry was changed by a RateRule. This has been fixed.
- Conversion from L3 to L2 was failing to write out the spatialDimensions
attribute of a Compartment regardless of the value. It now
correctly writes out a non default value.
- The RegisterConverters class was not included in the
LIBSBML_CPP_NAMESPACE. This has been corrected. Thanks to
Christoph Flamm for letting us know.
- There was a slight discrepancy in how the assignment operator
for the SBMLExtensionNamespaces was behaving depending on OS.
This has been sorted so that behaviour is the same for all.
- Tracker issue #3438777
The XercesParser was failing to find the line and column number
definitions with some compilers. This is now fixed. Thanks to
David Fange for reporting it.
- Tracker issue #3441615
There was an issue with SWIG, C# and MSVC compilers caused by
conflict with MS MFC and GDI classes. This has been fixed by
explicilty excluding these classes. Thanks to Totte Karlsson
for reporting this.
- Tracker issue #3461400
Writing out an L2 model with Layout annotation caused duplicate
annotations to be written out. This has been fixed. Thanks to
Raimund Rönn for reporting the problem.
- Tracker issue #3462055
A couple of typos have been corrected. Thanks to Raimund Rönn
for taking the time to report these.
- The documentation for Python did not omit internal libSBML
methods. This is now fixed, and the docs more properly reflect
the public libSBML API.
- We have fixed a number of errors in the Python API documentation,
such as return values being reported as "char" when in fact they
were strings, and have filled out more of the missing
documentation.
- We have fixed many other small documentation bugs and filled out
more of the missing documentation.
* Miscellaneous
- The matlab binding contains a function 'isSBML_Model' that checks
that the structure contains all the fields that are expected
in an SBML model. This function is used by OutputSBML to determine
if the model can be written out. Previously this function would
only report that a model was valid if each of the substructures had
the expected fields and no additional fields. This behaviour has
changed to allow users to include extra information within the
structure. Thus a model is considered invalid if it does not have
all the expected fields; additional fields are ignored.
- The libSBML examples code has been ported to all language bindings;
so all examples exist in each language.
- The API manuals for languages besides Java now feature a more
modern and attractive appearance.
* Configuration/build system changes
- Using CMake to link against the static runtime libraries on windows
when using libxml2 it was necessary to manually add links to other
libraries. The build system now takes care of these.
EXPERIMENTAL RELEASE
* New features
- There is now code to support the L3 render package.
======================================================================
Version 5.2.0 (2011-11-11)
======================================================================
* Download directory structure
- Prior to this release we have provided stable libSBML source
code and associated binary installers, but only provided the
source code of the L3 packages that are in beta development.
In response to requests to provide binaries including the package
code, we have slightly reorganised the directory structure of
the 5.2.0 release.
The top level directory remains as expected
https://sourceforge.net/projects/sbml/files/libsbml/5.2.0
This directory contains two sub-directories 'stable' and
'experimental'.
1) files/libsbml/5.2.0/stable
This directory contains the source code and various binary
installers arranged in a structure identical to that used
in the 5.1.0-b0 and 5.0.0 releases.
2) files/libsbml/5.2.0/experimental
This directory also contains two subdirectories.
a) files/libsbml/5.2.0/experimental/src
This directory contains the archives of the beta source
code for the L3 packages; similar to those previously contained
in the separate top level directory /5.1-packages-beta/.
b) files/libsbml/5.2.0/experimental/binaries
This directory contains binaries that include the stable
source code plus the beta code for ALL of the packages. It
should be noted that these binaries may be untested and
are provided 'as-is' to facilitate experimentation with L3 packages.
* New features
- There is a new method 'removeFromParentAndDelete()' that enables
the complete removal of child objects from any SBase object.
- There is a new method 'getAllElements()' that returns a List
containing all the children, both direct and indirect, of the
object on which it is invoked.
- There are new methods that will rename any references to
SId and UnitSId throughout the model.
- A new converter has been added that will convert the units
of a model to base SI units.
- A new converter has been added that will order AssignmentRules
and InitialAssignments in such a way that forward references
are avoided.
- The validation API has been refactored to facilitate the use of
third-party validators. The existing API has been maintained; in
addition, it is now possible to call any external validator,
regardless of programming language, using the new validator API.
- There is a new UserData object on the SBase class. This
facilitates storing additional application-specific information
that may be useful to particular software.
- A new function, appendFrom(ListOf *), on the ListOf class allows
the contents of one ListOf object to be appended to another.
- There are new functions getNumRegisteredPackages() and
getRegisteredPackageName(index) that allow the user to establish
which Level 3 packages have been enabled in the instance of the
libSBML library being used.
- The C API for interacting with the package plugin mechanism
has been expanded.
* Bug fixes
- The functions that add SBase objects were only checking that the
object being added had the correct Level and Version of SBML. It
failed to check that any SBML namespaces used also matched. This has
been corrected.
- Error checking failed to catch SBML L3 models with an empty
. Fixed.
- If the units of an object referred to a UnitDefinition that had no
, the warnings generated by the unit checking code
were inconsistent. These have now been standardized.
- The UnitDefinition::isVariantOfMass() function did not check that
the exponent of any unit was '1'. This has been fixed.
- The postal address for the Free Software Foundation was out of
date in all files where it was mentioned. Fixed.
- It was (erroneously) possible to allow the SBML namespace to be
replaced and lead to the production of a document with no SBML
namespace. Fixed.
- Some of the older libSBML C code called the exit() function when a
memory allocation error occurred. This is not an ideal way to
handle a problem. Since the functionality has existed in libSBML
for many years it has been removed from a standard build but can
be reenabled using a configuration flag should any users wish to
do so.
- The point at which an MSVC call to the c_str() function tidies up its
memory usage when running in debug mode is different to the point at
which the memory is tidied up when running in release mode or with other
C compilers. This means that a C function that returns a char * which
is created using c_str() will return an invalid pointer. Unit testing
does not highlight this issue as it only occurs in an MSVC Debug build.
Duplicating the string before returning it solves the problem.
LibSBML-5.1.0-b0 had three new functions where the string duplication
was missing. This has now been fixed.
- In the layout code, adding a to a produced
an element with the wrong name. This has been fixed; a fix that
revealed further issues with the constructors for packageNamespaces.
This issue has also been fixed. Thanks to Chris Myers for reporting
the original problem.
- There were inconsistencies arising from the naming of functions
related to packages; some being named doPkgFoobar and others
doPackageFoobar. All of these functions now use the doPackageFoobar
naming format. Existing functions using the Pkg format will still
work but should be considered deprecated.
- The text of many SBML validation and consistency-checking error
messages have been edited to hopefully improve readability,
clarity and consistency.
- All example files have been overhauled and new ones added.
- Users reported that some of the SBML files in the "test-data"
directories were invalid, not realizing that this was actually
intentional because the files are used for testing libSBML. In
order to avoid confusion, the files containing invalid SBML have
been renamed to append '-invalid' to their file names.
- The files located in the validator/test-data directory, used for
testing the SBML validation code, have been reorganised into
smaller subdirectories. The new subdirectories group the files
according to the type of validation being tested.
- Configuration/build system changes
======================================================================
Version 5.1.0-b0 (2011-08-25)
======================================================================
This release includes a provisional implementation of support for an
SBML Level 3 package for "layout" based on code from Ralph Gauges of
the COPASI group. No other packages are included with this release;
this applies to the "groups" package as well, which was in the beta
release but is not in this release. However, the SVN repository on
SourceForge has a branch for packages where ongoing development is
proceeding, and as specifications and code for SBML Level 3 packages
are settled, future libSBML releases will include stable versions of
packages as they become available. Source code for beta versions of
packages will also be made available from a separate download area,
http://sf.net/projects/sbml/files/libsbml/5.1-packages-beta
- The inline formula code will now deal with a unary plus.
- There is a new API for performing conversions between SBML Levels,
Versions, and SBML Level 3 packages on an SBML Document. Existing
functions such as setLevelAndVersion() have been reimplemented
using the new API and so will continue to work as expected. The
new API will facilitate the introduction of conversion routines
that deal with Level 3 packages.
- The MATLAB_SBML Structure produced using the MATLAB/Octave bindings
now includes fields for the SBML Level and Version on all
sub-structures.
- There are new functions getElementBySId() and getElementByMetaId()
that will traverse the entire document and return a pointer to an
SBase object with the SId or MetaId supplied.
- There are new functions on the SBO class to reflect the new top-level
names introduced in the SBO ontology.
- There were a couple of places where the clone methods failed to
create a proper copy. These have been fixed. Thanks to Nicolas
Rodriguez for reporting this.
- The introduction of the ability to place a units attribute from
the SBML L3V1 core namespace into a MathML element meant that
the code for reading and writing MathML needed to be fully aware
of which SBML namespaces it was working with. This has been done.
- Tracker issue #3296228
Importing a file with a large number of validation errors into
MATLAB was causing memory issues within MATLAB. The handling of
errors has been improved to avoid this situation.
- Necessary updates to support the latest version of swig.
- Configuration/build system changes
- The introduction of Mac OS X 10.7 Lion produced issues with both
XCode 4.0 and MATLAB. These have been addressed.
======================================================================
Version 5.0.0 (2011-04-14)
======================================================================
This is the first release of libSBML-5.0.0.
There are three types of potential changes in this release compared to
the beta 5.0.0 release: changes that relate to support for SBML Levels
1, 2 and Level 3 Core; changes that relate to support for L3 packages,
and changes that were introduced in libSBML-4.3.1. These are listed
separately below for convenience.
This release includes a provisional implementation of support for an
SBML Level 3 package for "layout" based on code from Ralph Gauges of
the COPASI group. No other packages are included with this release;
this applies to the "groups" package as well, which was in the beta
release but is not in this release. However, the SVN repository on
SourceForge has a branch for packages where ongoing development is
proceeding, and as specifications and code for SBML Level 3 packages
are settled, future libSBML releases will include stable versions of
packages as they become available. Source code for beta versions of
packages will also be made available from a separate download area,
http://sf.net/projects/sbml/files/libsbml/5.0-packages-beta
-------------------------
Known limitations
-------------------------
At present, libSBML 5 will not attempt to convert a model between SBML
Levels (e.g., from Level 3 to Level 2) if the model uses SBML Level 3
packages. This applies to SBML layout elements and annotations too.
Our aim is to support conversion between L2 layout annotations and the
L3 layout package, but this functionality will be introduced in a
future release of libSBML.
--------------------------------------
SBML Level 3 Package extension changes
--------------------------------------
- The extension mechanism for supporting SBML Level 3 packages now
includes a full C API.
- LibSBML now has greatly improved detection and error reporting of
unimplemented/unknown SBML Level 3 packages.
- The "layout" extension now provides more seamless access to L2
layout annotations in L2 models.
- There is now more detailed and integrated documentation describing
the use of CMake as an alternative to GNU make for building and
installing libSBML.
-------------------------------
General libsbml-core changes
-------------------------------
- There are now functions will set the Qualifier on a CVTerm from a
string; in addition to the existing functions that use values from
the enumeration of QualifierTypes.
- SBML L2 contains an number of attributes that have default values.
LibSBML does not write these values out. This behaviour has
changed slightly for libSBML-5. If a user explicitly sets the
value of an attribute to be the default value; then it will be
written out. For example setting the spatialDimensions of an L2
to be '3' will result in a document where this is
explicitly written.
- In SBML L3, it is possible to have a compartment with no
spatialDimensions attribute declared. LibSBML-4 would not convert
such a model to L2, since an L2 compartment has spatialDimensions
'3' by default. This behaviour has been altered for libSBML-5 and
if the user opts for nonstrict units when applying the conversion
function, a compartment with no spatialDimensions declared will be
converted.
- There are additional functions XMLNamespaces::getNumNamespaces and
XMLAttributes::getNumAttributes. These are aliases for the existing
getLength functions but are more in keeping with the rest of the API.
- The conversion functions for converting an L2 model to L3 were
failing to set the stoichiometry value. This has been fixed.
- The internalConsistencyCheck was failing to report when required
attributes or elements were missing from an object. This has been
corrected.
- The XMLConstructorException was not exposed. It is now.
- Configuration/build system changes
- The header files libsbml-config-win and libsbml-config-unix have
been replaced with a single libsbml-config-common file.
- The organization of the source directories has been radically
changed, moving the previous directories src/annotation, src/math,
etc., to become subdirectories of src/sbml. This allows us to
entirely avoid a step that was previously to create a copy of all
the header files into /include. That copy operation lead
to a lot of wasted time when debugging code and accidentally
making changes to the wrong file.
- The 'win' directory that previously containing MSVC project files
has been removed. The addition of packages made maintaining this
directory problematic. The CMake build system provides an easy
alternative for generating any project files required.
-------------------------------
Libsbml-core changes from 4.3.x
-------------------------------
Also available in Version 4.3.1 (Released 2011-03-29)
- There is now API documentation for the MATLAB and Octave bindings.
- Certain versions of the libxml2 parser fail to catch a prefix
being assigned to an empty namespace. Additional code has
been included to catch this error if the version of libxml2 has
not reported it.
- The improved build of the MATLAB interface proved unsuccessful
in cases where the user had a startup.m file that changed
directory. This has been corrected.
- The SyntaxChecker::hasExpectedXHTMLSyntax(xhtml) function had not
applied the relaxation on the XHTML restrictions for SBML
Level 3. This has been sorted out.
- The SyntaxChecker::isValidSBMLSId(string) function was incorrectly
reporting that an empty string was a valid id. This has been corrected.
- Choosing --enable-universal-binary on MacOS 10.5 now includes all
three of the following architectures: i386, x86_64, ppc. It
previously only selected i386 and ppc.
Also available in Version 4.3.0 (Released 2011-03-04)
- There was some disagreement about what libsbml when asked to write
out a required attribute in Level 3 where the value of the attribute
had not in fact been set. Following discussion within the libSBML
team and subsequently the libsbml-development mailing list it was
decided that the appropriate behaviour was to ignore the attribute
when writing out the model and thus not inadvertently give the
impression it has a value.
- Conversion from Level 3 to Level 2 involving variable stoichiometry
has now been implemented and this feature of L3 can now be converted
to L2.
- There is a getSupportedNamespaces function on the SBMLNamepaces
class which returns a List of the SBMLNamespaces supported by
this version of libSBML.
- Tracker issue #2082682
The unit checking of math involving the root function has been
fully addressed. Previously unit checking was only applied to
the expression root(n, x) if n was an integer. It can now handle
any value of n including an expression.
- Checking of the units of measurement in math expressions has been
further improved to provide checking to a deeper level with the
overall math of the model. Thus, the units of the expression a^b
can now be validated even if the value of b is assigned b = c and
the model states elsewhere that c = 2.
- SBML Level 3 has no default attribute values and thus a number of
new isSetXYZ functions were introduced in libSBML-4.1.0. Users
pointed out it was inconsistent that these functions returned
'false' for a Level 2 model in which the attribute concerned *did*
have a default value. Thus, any newly introduced isSetXYZ
function that deals with an attribute that had a default value in
Level 2 will now return 'true' regardless of whether the user has
explicitly set the function or not.
- The MATLAB and Octave bindings now include the function
OutputSBML() for writing the structure used in these environments
back to SBML. This function has previously shipped as part of
SBMLToolbox.
- There is an additional constructor for an SBMLDocument object that
takes an instance of SBMLNamespaces as its argument. This is similar
to the constructors for all SBML objects.
- There is now a custom manifest file included in the Java JAR file.
It contains the version number of the libSBML release. An example
program demonstrating how to access the information is included
as the file examples/java/printLibSBMLVersion.java.
- An API manual for the C# language bindings is now available. It
is not as complete as the C++ and Java versions, but it is quite
close.
- The InternalConsistency validator was failing to report the absence
of required attributes or elements within an in-memory model.
This has been sorted out with a large number of tests added.
- Tracker issue #2960646
When writing out an SBML model containing the root function
Octave was failing to convert the formula into the appropriate
MathML. This has been fixed.
- The code that checks for allowed functions in a Level 1
document was reporting an error if it encountered one of the
predefined functions. This has been corrected.
- Checking for NULL references has been greatly improved
throughout.
- The appendNotes function was not correctly checking for the
xhtml namespaces declared at the top level. This has been
fixed.
- In some cases the facility to create new 'Bags' within CVTerms
was not performing as expected. This has been sorted out.
- Validation previously failed to report an error if a lambda
function contained only arguments and no actual function
body. This has been fixed.
- LibSBML checks that each element within a model being read has
the correct default namespace. However, if the namespace had been
'declared' via a prefix this check was not being performed.
This has been corrected.
- The code that checked that the top-level elements of an annotation
had unique namespaces was incorrectly comparing prefixes rather
than actual XML namespaces. This has been fixed. Thanks to
Waclaw Kusnierczyk for reporting this and supplying the fix.
- The XML namespace for a
