/** @page libsbml-python-reading-files Reading and writing SBML content

@tableofcontents

This section summarizes how to read and write SBML content using the
facilities provided by libSBML.  This is only a basic orientation to these
essential facilities of libSBML, and is far from exhaustive in its coverage.
Readers are directed to the rest of this manual for more details about using
libSBML's many features and facilities.  Please use the navigation bar near
the top of the page and the table of contents in the left-hand column for
navigating to other parts of this manual.

@section rf-started Getting started: the 1-minute introduction

In LibSBML, the class @link libsbml.SBMLDocument SBMLDocument@endlink is
used as a top-level container for storing SBML content and data associated
with it (such as warnings and error messages).  Here is a simple example to
start this discussion, using Python in interactive mode:
@code{.py}
>>> from libsbml import *
>>> reader = SBMLReader()
>>> document = reader.readSBML("examples/sample-models/from-spec/level-2/enzymekinetics.xml")
>>> document.getNumErrors()
0
>>>
@endcode

The code above illustrates probably the simplest possible use of libSBML:
reading a model and printing any errors or warnings encountered.  The code
begins with a Python <code>import</code> command to load the libSBML API
into the running Python interpreter.  Next, it instantiates an @link
libsbml.SBMLReader SBMLReader@endlink object and stores it in a variable
called <code>reader</code>.  Then, it uses this object to read an SBML
model stored in a file, creating an @link libsbml.SBMLDocument
SBMLDocument@endlink object in the process and storing it in the variable
<code>document</code>.  Finally, it calls on the @link
libsbml.SBMLDocument.getNumErrors() SBMLDocument.getNumErrors()@endlink
method to check if any errors were encountered.


@section rf-reading Reading SBML

SBML may be read from a file or an in-memory character string into an @link
libsbml.SBMLDocument SBMLDocument@endlink object.  LibSBML defines two basic,
convenient, global functions for reading SBML:

@li @link libsbml.readSBMLFromFile() readSBMLFromFile(string
filename)@endlink.  This function takes a file name, attempts to read an
SBML document from the file, and returns a @link libsbml.SBMLDocument
SBMLDocument@endlink object if successful.
@li @link libsbml.readSBMLFromString() readSBMLFromString(string
xml)@endlink.  This function takes a string assumed to contain XML content,
attempts to read an SBML document from the string, and returns a @link
libsbml.SBMLDocument SBMLDocument@endlink object if successful.

The model may be in any SBML Level and Version combination.
LibSBML implements an unified object model for SBML that encompasses 
all SBML Levels, so applications generally do not need to
worry about differences in syntax between these definitions of SBML when
reading and writing models.  (However, applications still need to be
concerned about the @em constructs used and how they are interpreted, since
there are substantial differences between SBML Level&nbsp;1,
Level&nbsp;2, and Level&nbsp;3!)


@section rf-sbmldocument The SBMLDocument container

As might be deduced from the examples so far, an @link libsbml.SBMLDocument
SBMLDocument@endlink object in libSBML represents a whole SBML model and its
associated data.  The @link libsbml.SBMLDocument SBMLDocument@endlink class
corresponds roughly to the class <i>Sbml</i> defined in the SBML Level&nbsp;2
specification, but it does not have a direct correspondence in SBML
Level&nbsp;1.  (Nevertheless, it is created by libSBML no matter whether the
model is Level&nbsp;1, Level&nbsp;2 or Level&nbsp;3.)

@link libsbml.SBMLDocument SBMLDocument@endlink is derived from @link
libsbml.SBase SBase@endlink, so that it contains the usual @link
libsbml.SBase SBase@endlink attributes (in SBML Level&nbsp;2
Version&nbsp;3) of "metaid" and "sboTerm", as well as the subelements
"notes" and "annotation".  It also contains the attributes "level" and
"version" indicating the Level and Version of the SBML read.  @link
libsbml.SBase SBase@endlink (and thus its subclasses such as @link
libsbml.SBMLDocument SBMLDocument@endlink) provides methods for querying
this information:
@li @link libsbml.SBMLDocument.getLevel() SBMLDocument.getLevel()@endlink
returns the SBML Level of the model.
@li @link libsbml.SBMLDocument.getVersion()
SBMLDocument.getVersion()@endlink returns the SBML Version within the Level
of the model.

Of course, the whole point of reading an SBML file or data stream is to get
at the SBML model it contains.  The following method allows access to the
Model object within an SBML document:

@li @link libsbml.SBMLDocument.getModel() SBMLDocument.getModel()@endlink
returns a libsbml::Model object for the SBML model contained in the
@link libsbml.SBMLDocument SBMLDocument@endlink.

Here is an example of using this:
@code{.py}
>>> from libsbml import *
>>> reader = SBMLReader()
>>> document = reader.readSBMLFromFile("examples/sample-models/from-spec/level-2/enzymekinetics.xml")
>>> model = document.getModel()
>>> model.getNumSpecies()
4
>>> 
@endcode

@link libsbml.SBMLDocument SBMLDocument@endlink also acts to log any
problems encountered while reading the model from the file or data stream.
Whether the problems are warnings or errors, they are reported through a
single common interface involving the object class @link libsbml.SBMLError
SBMLError@endlink.  The example earlier on this page already showed some of
the methods available for accessing errors and warnings; here is a slightly
more complete list:

@li @link libsbml.SBMLDocument.getNumErrors()
SBMLDocument.getNumErrors()@endlink returns a count of the diagnostic
messages logged during while attempting to read an SBML model using either
libsbml::readSBMLFromFile() or libsbml::readSBMLFromString().
@li @link libsbml.SBMLDocument.getError() SBMLDocument.getError(int
n)@endlink returns the error indexed by integer @c n in the error log.  The
@link libsbml.SBMLError SBMLError@endlink object class provides methods
for displaying an error message, assessing the severity of the problem
encountered, and for finding out the line and column number of where the
problem occurred in the SBML input.
@li @link libsbml.SBMLDocument.printErrors()
SBMLDocument.printErrors()@endlink prints to standard output all of the
errors and diagnostics logged with the given @link libsbml.SBMLDocument
SBMLDocument@endlink().
@li @link libsbml.SBMLDocument.printErrors() SBMLDocument.printErrors(ostream stream)@endlink is
identical to the method above, but prints all of the diagnostics to the
given output stream instead of the terminal.

Finally, another set of @link libsbml.SBMLDocument SBMLDocument@endlink
methods worth mentioning in the context of reading SBML are those for
running consistency-checking and validation rules on the SBML content.
These methods assess whether the SBML is legal according to basic rules
listed in the SBML Level&nbsp;2 and Level&nbsp;3 specification documents.
Note that they are mostly structural checks, in the sense that they can
indicate whether the SBML is properly constructed; they cannot tell if a
model is nonsense.  (But at least they can assess whether it's
syntactically correct nonsense!).

@li @link libsbml.SBMLDocument.checkConsistency()
SBMLDocument.checkConsistency()@endlink performs a set of structural and
mathematical checks on the SBML content and reports the number of failed
checks (errors) encountered.  Use the @link
libsbml.SBMLDocument.getNumErrors() SBMLDocument.getNumErrors()@endlink and
@link libsbml.SBMLDocument.getError() SBMLDocument.getError(int n)@endlink
interfaces to examine the individual errors.
@li @link libsbml.SBMLDocument.checkL1Compatibility()
SBMLDocument.checkL1Compatibility()@endlink peforms a set of semantic
consistency checks on the document to establish whether it can be converted
to SBML Level&nbsp;1, and returns the number of failures.  If all the
checks succeed, it returns 0.
@li @link libsbml.SBMLDocument.checkL2v1Compatibility()
SBMLDocument.checkL2v1Compatibility()@endlink peforms a set of semantic
consistency checks on the document to establish whether it can be converted
to SBML Level&nbsp;2 Version 1, and returns the number of failures.  If all
the checks succeed, it returns 0.
@li @link libsbml.SBMLDocument.checkL2v2Compatibility()
SBMLDocument.checkL2v2Compatibility()@endlink peforms a set of semantic
consistency checks on the document to establish whether it can be converted
to SBML Level&nbsp;2 Version&nbsp;2, and returns the number of failures.
If all the checks succeed, it returns 0.
@li @link libsbml.SBMLDocument.checkL2v3Compatibility()
SBMLDocument.checkL2v3Compatibility()@endlink peforms a set of semantic
consistency checks on the document to establish whether it can be converted
to SBML Level&nbsp;2 Version&nbsp;3, and returns the number of failures.
If all the checks succeed, it returns 0.
@li @link libsbml.SBMLDocument.checkL2v4Compatibility()
SBMLDocument.checkL2v4Compatibility()@endlink peforms a set of semantic
consistency checks on the document to establish whether it can be converted
to SBML Level&nbsp;2 Version&nbsp;4, and returns the number of failures.
If all the checks succeed, it returns 0.
@li @link libsbml.SBMLDocument.checkL3v1Compatibility()
SBMLDocument.checkL3v1Compatibility()@endlink peforms a set of semantic
consistency checks on the document to establish whether it can be converted
to SBML Level&nbsp;3 Version&nbsp;1, and returns the number of failures.
If all the checks succeed, it returns 0.

At the time of this release of libSBML, the most recent release of SBML is
Level&nbsp;3 Version&nbsp;2 Core Release&nbsp;2.


@section rf-writing Writing SBML

Writing SBML is, in the end, a very simple matter in libSBML.  The library
provides the following methods for this purposes:

@li @link libsbml.writeSBMLToFile() writeSBMLToFile(SBMLDocument d, string filename)@endlink 
writes the given SBML document to a file, and returns either @c 1 on
success or @c 0 on failure.  Reasons for failure can be, for example, that
the named file could not be opened for writing.
@li @link libsbml.writeSBMLToString() libsbml.writeSBMLToString(SBMLDocument d)@endlink returns
the given SBML document as a character string, or returns an empty string
if a failure occurred.
@li @link libsbml.writeSBML() libsbml.writeSBML(SBMLDocument d, ostream stream)@endlink
writes the given SBML document to an <code>ostream</code> output stream,
and returns either @c 1 on success or @c 0 on failure.



*/