           libsbml NEWS -- History of user-visible changes


=== Version 2.2.0 ===

* New Features:

    - Perl

      A full libSBML Perl API was contributed by Christoph Flamm and
      Rainer Machne.  For more information, see
      bindings/perl/README.txt.

      The Perl API is not yet integrated into the libSBML 'configure'
      system.  To build and install it, after installing libSBML,
      change to bindings/perl and follow the CPAN-style build
      instructions in the README.txt file.

    - Lisp

      A full libSBML Lisp API was contributed by Martin Ginkel.
      For more information, see bindings/lisp/README.txt.

    - Windows Installation Program

      Sarah Keating created Windows setup programs in two flavors:
      libsbml-2.2.0-win-xerces.exe and libsbml-2.2.0-win-expat.exe.

    - XML namespace definitions may be retrieved from or added to any
      SBML object.  It's good practice, however, to put namespaces
      only on the top-level <sbml> element.  For example:

        SBMLDocument d;
        d.getNamespaces().add("jd", "http://www.sbml.org/2001/ns/jdesigner");

      To find out if an SBML object (XML element) has any namespaces
      defined, use hasNamespaces(), for e.g.:

        if (d.hasNamespaces()) ...


* Bug Fixes:

    - <notes> and <annotation> elements on the top-level <sbml>
      element were not being written-out for L2 documents.  Thanks to
      Damon Hachmeister for reporting this bug.

    - <csymbol> delay functions were being handled incorrectly
      throughout libSBML as symbols (similar to <csymbol> time, which
      is a symbol) instead of functions.  The fix results in three
      changes:

        1. The ASTNodeType AST_NAME_DELAY is changed to
           AST_FUNCTION_DELAY.

        2. As a result of (1), ASTNode.isFunction() will now return
           true for delay function nodes.

        3. The infix expression parser will parse:

             delay(...)

           as an AST_FUNCTION_DELAY (This does not mean delay
           functions must be called "delay" in MathML, it simply means
           if you want to create them in infix, you need to use the
           name "delay").

      I'm reasonably confident the effect of these changes on existing
      code will be minimal.  My guess is that if anyone had been using
      this aspect of libSBML, they would have reported it as a bug.
      Thanks to Sarah Keating for reporting this bug.

    - The consistency checks were referencing ids instead of names
      when checking L1 models.  Thanks to Jo Matthews, Mike Hucka, and
      Manuel Martin for reporting this bug.

    - XML namespace definitions were not being preserved when writing
      out an SBML document.  Thanks to Jo Matthews, Michael Lawrence,
      and Herbert Sauro for reporting this bug.


* Changes:

    - The API SBMLDocument.validate() has been deprecated and will be
      removed in a future release of libSBML.  Use
      SBMLDocument.checkConsistency() instead.

    - A HTML version of the libSBML Developer's Manual is now available.
      Thanks to Mike Hucka for working that out.


* Released October 6, 2004




=== Version 2.1.0 ===

* New Features:

    - C++

      While it's always been possible to call the C API from C++ code,
      this version of libSBML features a true object-oriented API that
      mirrors the SBML specifications.  To get a feel for the C++ API,
      see src/TestReadFromFile5.cpp.

      For those that prefer the straight C API, it's still available
      and over 730 unit tests prove its backward compatible with
      previous releases.

    - Java

      A full libSBML Java API is also available.  See:

        docs/formatted/java.txt  -  For more information
        bindings/java/Test.java  -  For example code

    - Python

      A full libSBML Python API is also available. See:

        docs/formatted/python.txt  -  For more information
        bindings/python/accept.py  -  For example code


    - Validation Engine / Consistency Checks

      In addition to validating an SBML document against the SBML XML
      Schema, we've added a (customizable) validation engine.

      Currently libSBML comes pre-configured with 39 consistency check
      rules described at:

        http://sbml.org/wiki/Semantic_Validation

      To test whether or not an SBML document violates any of these
      consistency checks, simply load an SBML document, d, and call:

        SBMLDocument_validate(d)  -  C
        d.validate()              -  C++, Java, Python

      Every violation adds an error message to the SBML document
      (accessible with getNumErrors() and getError()) and validate()
      returns the total number of errors found.

      The ability to add your own rules is still a bit rough around
      the edges.  The API was started before libSBML was ported to
      C++, so new rules must be written in C or C++ (no Java or
      Python).  If you're interested, please see
      src/ValidationRules.c.


    - Additional Convenience Functions:

      It's now possible retrieve objects from a Model either via their
      ordinal position or their SId.  In C++, Java, and Python the
      same method name is overloaded to take either an integer or a
      string:

        int   n;
        Model m;

        m.getXXX(n);
        m.getXXX("SomeSId");

      In C, two separate functions are provided:

        Model_getXXX(n);
        Model_getXXXById("SomeSId");


* Bug Fixes:

    - All bugs reported for the libSBML betas, 2.0.4 and 2.0.5, have
      been fixed.

    - Infix formula strings with grouped non-associative operators of
      the same precedence were being formatted incorrectly.  That is:

        "a - (b - c)"  ->  "a - b - c"
        "a - (b / c)"  ->  "a / b / c"

      To be clear, the formula string would parse correctly, but would
      be written out incorrectly.  Thanks to Rainer Machne for
      reporting this bug.

    - Double precision numbers (in attribute values, infix formulas,
      or MathML) were being printed to a maximum precision of six
      digits.  This artifically low limit has been increased to 15
      digits (the maximum precision possible for an IEEE-754 doubles).
      Thanks to Tatsuya Ishida for reporting this bug.

    - MathML incorrectly nested inside <notes> or <annotation>
      elements would cause libSBML to crash.  Thanks to Adam Halasz
      reporting this bug.

    - Negative numbers in MathML <cn> elements were being incorrectly
      parsed.  Thanks to Nadia Ugel and Victoria Gor, both of whom
      independently discovered and reported this bug.

    - A <rateRule> element would be written without the closing angle
      bracket (!) if it had a note and/or annotation associated with
      it.  Thanks to Konstantin Kozlov for reporting this bug and
      providing a fix.

    - A MathML expression involving a <csymbol> did not "reduce" to
      the correct syntax tree when it was the last argument of an
      <apply>.  Thanks to Jacek Puchalka for reporting this bug and
      providing a fix.


* Changes:

    - SBMLTypes.h now includes MathMLDocument.h, MathMLReader.h and
      MathMLWriter.h

    - Mike Hucka rewrote the entire build/make system.  It no longer uses
      automake or libtool; as a result, it is smaller, leaner and faster.
      Other features include changes to configure to add --with-python,
      --with-java, --with-matlab.

    - Mike Hucka updated the libsbml-manual.tex to make it reflect the
      current state of the API.  Mike also created a new LaTeX class file
      called sbmlmanual.tex, available in the docs/src/tex subdirectory.

    - In order to make the generation of the manuals self-contained, we've
      put all the necessary LaTeX class files and extensions they use in
      docs/src/tex.  This bloats the distribution, but is the only safe way
      to ensure that people can actually make the docs.

    - Mike Hucka also updated the doxygen documentation configuration and
      the makefile that drives it.  However, it's still not ready for
      prime-time and we are not yet distributing it as a standard part of
      the regular distributions.

* Released July 23, 2004




=== Version 2.0.3 ===

* Major New Features:

    - Stephan Hoops has contributed a port of libsbml to use the Expat
      XML parser library as an alternative to Xerces.  To build
      libsbml to use Expat:

        ./configure --with-expat[=PATH]

      All checks but one pass with Expat enabled (See Bugs below).
      There are currently two caveats to using Expat with libsbml:

        1.  libsbml *will not* be able to validate SBML and MathML
            content against an XML Schema.  Expat has no facilities
            for XML Schema validation.

        2.  XML entity references (e.g. &#160;), which are most likely
            to occur in XHTML <notes> sections, will be output as
            their UTF-8 byte sequence instead of the more human
            readable entity reference (see Bugs below for more
            information).

    - Rainer Machne has contributed an example program that evaluates
      infix expressions and prints their results using the libsbml AST
      API.  See examples/evaluateMath.c.


* Bug Fixes:

    - The correct namespace is now output for both SBML Level 1 and
      Level 2 documents.  This bug was introduced as a result of a bug
      fix in the 2.0.1 release which output only Level 1 namespaces.
      The bug is fixed now.  Honest.  Thanks to Akira Funahashi for
      reporting this bug.

    - XML entity references (e.g. &#160;), which are most likely to
      occur in XHTML <notes> sections, are now output using the same
      entity reference notation instead the corresponding UTF-8 byte
      sequence.  Thanks to Jo Matthews for reporting this bug.

      NOTE: This bug has not yet been fixed in the Expat version of
      libsbml.  While Expat reads and writes UTF-8 by default, it
      comes with no APIs to manipulate or translate Unicode encodings.
      Writing such a conversion routine and ensuring it is
      cross-platform is non-trivial and would hold up this release of
      libsbml for too long.

* Released December 19, 2003




=== Version 2.0.2 ===

* Major New Features:

    - Sarah Keating has contributed a Matlab interface to libsbml and
      tools to load, store and view (via a Matlab GUI) a database of
      models (from a .mat file).  See the README.txt in
      bindings/matlab/SBMLToolbox for build instructions and
      additional information.

* Bug Fixes:

    - Writing SBML L2 documents with FunctionDefinitions would cause
      libsbml to crash (segfault).  The cause was a typo in
      SBMLFormatter.cpp where a call to listOfUnitDefinitions() should
      have been (and is now) listOfFunctionDefinitions() (Thanks to Jo
      Matthews for reporting an anomaly that led to the discovery of
      this bug).

* Released October 24, 2003




=== Version 2.0.1 ===

* Bug Fixes:

    - The correct namespace is now output for SBML Level 2 documents.

    - The MathMLHandler now correctly constructs ASTs for calls to
      user-defined function containing numeric arguments (Thanks to
      Colin Gillespie for reporting an anomaly that lead to the
      discovery of this bug).

    - SBML_formulaToString() did not correctly reproduce (sub)
      expressions with operators of the same precedence, but modified
      associativity.  For example, "1 / (2 * 3)" was correctly parsed
      (in infix or MathML) but incorrectly converted to "1 / 2 * 3".
      This bug has been fixed!

* Major New Features:

    - When reading SBML Level 2, MathML expressions are automatically
      converted to and stored as SBML L1 infix expressions for maximum
      backward compatibility with L1.  That is, either XXX_getMath()
      or XXX_getFormula() may be used.  There is no need to call
      SBML_formulaToString() under most circumstances.

    - SBML_convertToL2(SBase_t *sb) converts any SBML Level 1 object
      and its subordinate objects to SBML Level 2.  Currently this
      function:

        - Converts name fields to id fields

        - Adds ModifierSpeciesReferences when converting Reactions
          (via SBML_addModifiersToReaction(Reaction_t *r, const Model_t *m))

      In the future this function will also:

        - Add FunctionDefinitions for L1 predefined functions

     SBMLDocument_setLevel() calls SBML_convertToL2() automatically
     when the current level is 1 and the new level is 2.

* Major New APIs:

    - char *
      writeMathMLToString (MathMLDocument_t *d)
  
    - unsigned int
      Model_getNumSpeciesWithBoundaryCondition (const Model_t *m)

    - Species_t *
      Model_getSpeciesById (const Model_t *m, const char *sid)
 
    - SpeciesReference_t *
      Reaction_getReactantById (const Reaction_t *r, const char *sid)

    - SpeciesReference_t *
      Reaction_getProductById (const Reaction_t *r, const char *sid)

    - ModifierSpeciesReference_t *
      Reaction_getModifierById (const Reaction_t *r, const char *sid)

    - unsigned int
      ListOf_countIf (const ListOf_t *lo, ListItemPredicate p);

    - void *
      ListOf_find (const ListOf_t *lo, const void *item1, ListItemComparator c)

    - List_t *
      ASTNode_getListOfNodes (const ASTNode_t *node, ASTNodePredicate p)

    Where ListItemPredicate, ListItemComparator and ASTNodePredicate
    are pointers to functions with a particular signature.  This
    allows for convenient and powerful Lisp map-like or C++ STL
    operations over a container (In fact, the XXX_countIf() name was
    inspired by the C++ STL).  For example,
    Model_getNumSpeciesWithBoundaryCondition() (above) is implemented
    simply as follows:

      return ListOf_countIf( m->species,
                            (ListItemPredicate) Species_getBoundaryCondition );


* New example program:

    - translateMath.c is an interactive console program that translates infix
      formulas into MathML and vice-versa.

* Improved Windows build and binary distribution:

    - Andrew Finney constructed an MSVC++ project file and a set of
      batch files to build both regular and debug versions of libsbml
      and all example programs.

    - Xerces-C++ 2.2.0 headers, DLLs and .lib files are included with
      the Windows distribution (libsbml-2.0.1.zip; see the win32/
      subdirectory).

* Minor improvements:

  - Public API header files no longer include references to C-specific
    header files (e.g. stdio.h).  This should make it easier for
    automated tools to read these header files and generate API
    bindings for other languages (e.g. Delphi; Thanks to Herbert Sauro
    for suggesting this).

  - SBMLTypes.h now #includes both SBMLReader.h and SBMLWriter.h.

  - Internal utility classes and functions are now officially public.
    See List.h, Stack.h, StringBuffer.h and util.h.

* Released August 6, 2003




=== Version 2.0.0 ===

* Near complete L2 support.  The two features not yet supported are:

    1. RDF (although the metaid attribute is read, stored and written)

    2. Processing of the MathML <semantic> element (for annotating
       MathML elements with additional content, e.g. TeX).


* New L2 Structures:

    - FunctionDefinition
    - Event
    - EventAssignment
    - SimpleSpeciesReference    (abstract)
    - ModifierSpeciesReference
    - AssignmentRule            (no longer abstract)
    - RateRule

    - MathML and L1 infix expressions (when parsed) are both stored in
      the same Abstract Syntax Tree (AST) structure ASTNode.

    - ListOf stores lists of others SBML objects and may contain a
      metaid, notes or annotations.


* New L2 Functions:

    - The getters, setters, isSet and unset functions are too numerous
      to mention here.  Like L1, they parallel the UML structures
      defined in the SBML specification.  All L1 functions are kept
      for backward compatibility (see below).

    - Any structure containing a list now has a getListOfXXX()
      function which returns the corresponding ListOf structure.

    - There are currently three convenience functions for converting
      between SBML infix and MathML formulae:

        - ASTNode_t        *SBML_parseFormula(const char *formula)
        - char             *SBML_formulaToString(const ASTNode_t *math)
        - MathMLDocument_t *readMathMLFromString(cont char *xml)

      Again, these are provided purely for convenience.  Under normal
      circumstances, libsbml performs all conversions behind the
      scenes when necessary.


* L1 to L2 Changes:

  libsbml stores both L1 and L2 models in the same memory structure.
  While the L1 getters, setters, isSet and unset functions exist for
  backward compatibility there are some changes of which users of
  previous versions of libsbml should be aware:

    - Compartment:

        - .volume has been renamed to .size.

    - Species:

        - .units has been renamed to .substanceUnits.

        - .initialAmount and .initialConcentration are stored in a
          union called .initial with discriminators .Amount and
          .Concentration.

    - Reaction:

        - .fast is optional in L2 which introduces Reaction_isSet /
          unsetFast() functions.

    - SpeciesReference:

        - .stoichiometry is now of type double which necessitated a
          change in the signature of the getter and setter functions.

        - The use of .denominator is deprecated in L2.

          However, libsbml still uses denominator in L2 models.  When
          reading a <stoichiometry Math> if the content is a single
          <CNN type='rational'>, libsbml will discard the
          stoichiometry Math and set stoichiometry and denominator
          directly.  Similarly, libsbml will write <stoichiometryMath>
          in L2 documents if the .stoichiometryMath field is not set
          and the denominator is not 1.

    - CompartmentVolumeRule:
    - SpeciesConcentrationRule:
    - ParameterRule:

        - .compartment, .species and .parameter have all been renamed
          to .variable.

    - The XXX_createWith() functions now set the .id field instead of
      the .name field.

    - List_t has been replaced by ListOf_t to store a metaid, notes,
      and annotations.  ListOf_t is simply a wrapper around List_t.


* SBMLReader allows you to set up to three Schema filenames (one each
  for L1v1, L1v2 and L2v1) and it will automatically use the
  appropriate Schema for the SBML document being read.

* A simple command-line executable that converts L1 models to L2 was
  added to the examples/ subdirectory.

* A new subdirectory, xml-schemas/, contains schemas for SBML L1v1,
  L1v2, L2v1 and MathML 2.

* Xerces-C 2.3.0 is now supported by libsbml.  Older versions of
  Xerces-C (2.2.0 and 2.1.0) are still supported.


* Released July 23, 2003




=== Version 1.1.2 ===

* A new subdirectory, examples, contains a few small programs that
  demonstrate how libsbml may be used.

* IEEE-754 NaN, +Inf, -Inf and -0.0 are handled correctly and
  consistently on all supported platforms.  In previous versions, these
  values were not represented, read or written correctly on native
  Windows and under Cygwin.

  When writing these values to XML, libsbml now strictly adheres to the
  XML Schema specification for doubles, namely exactly: "NaN", "INF",
  "-INF" and "-0".

* The build platform was upgraded to Libtool 1.5.  This means dynamic
  libraries will build correctly on all platforms: Linux (.so),
  Solaris (.so), Cygwin (.DLL) and MacOS X (.dylib).

* SBMLWriter now defaults to an output encoding of UTF-8.

* SBML_parseFormula() now returns NULL if the formula contains an
  error.  The next version of libsbml will return the position of the
  syntax error.

* Added method: SBMLDocument_setModel().

* To build and run the libsbml test suite now requires an explicit
  configure option:

    ./configure  --enable-check

  In addition, 'check' needs to be installed (http://check.sf.net/).
  Under Cygwin ONLY, due to a limitation of Libtool, if libsbml is
  built with --check-enabled, a DLL cannot be built.  So, after
  testing, re-run configure without enabling check then 'make' and
  'make install' as usual.

  Running the test suite on any platform is completely optional.
  Libsbml is tested on all supported platforms before it is released.


* Released June 6, 2003




=== Version 1.1.0 ====

* A Developer's Manual (DRAFT) is available in docs/formatted/.

* Formula strings may optionally be parsed into abstract syntax trees.
  See ASTNode.h, and SBML_parseFormula() in FormulaParser.h.

* XXX_isSetYYY() and XXX_unsetYYY() methods are available for optional
  fields without default values.

* XXX_getYYY() and XXX_setYYY() methods are available for every field.

* SBML (XML) namespace handling is much improved.

* '<annotations>' is treated as a synonym for the correct form
  '<annotation>' (singular).

* Notes and annotations on the top-level <sbml> element are read-in
  and stored (SBMLDocument_t now "inherits" from SBase_t), but not
  written.  When this occurs, a warning message is logged.

* Builds successfully on Solaris 2.8.

* SBML documents may now be validated against their XML schema.  This
  is still off by default.  To turn validation on see
  SBMLReader_create(), SBMLReader_readSBML() and possibly SBMLReader.h
  for more information.

* Three new convenience functions exist to quickly print warnings,
  errors and fatal errors that occurred while reading an SBMLDocument.
  The prototype for this class of function is:

    SBMLDocument_printXXXs(SBMLDocument_t *d, FILE *stream).

  Where XXX is Warning, Error or Fatal.


* Released May 11, 2003.




=== Version 1.0.1 ====

* The build system detects and supports Xerces-C 2.1.0, Xerces-C 2.2.0
  compiled with or without namespace support.

* Released March 14, 2003.




=== Version 1.0.0 ===

* Initial release, March 12, 2003.
