libSBML Python API  5.11.0
Core libSBML

SBML Level 3 introduced a modular architecture, in which SBML Level 3 Core is usable in its own right (much like SBML Levels 1 and 2 before it), and optional SBML Level 3 Packages add features to this Core. To support this architecture, libSBML is itself divided into a core libSBML and optional extensions.

Differences between core libSBML and extensions to libSBML

Core libSBML corresponds to the features of SBML Levels 1 to 3 Core; they are always available, and do not require applications to understand more than the SBML core specifications. The classes listed on the rest of page constitute libSBML's implementation of SBML Levels 1–3, without any SBML Level 3 packages.

By contrast, the libSBML extensions are plug-ins that each implement support for a given SBML Level 3 package. Separate pages of this API manual describe the libSBML extensions for those SBML Level 3 packages that are supported at this time. They are grouped under the section titled Level 3 Extensions. The stable releases of libSBML only include extensions for officially-released package specifications; additional, experimental extensions may be available for other Level 3 packages that may not yet have been finalized by the SBML community. You can find copies of these experimental extensions at the download site for libSBML on SourceForge.net.

Summary of core SBML objects implemented in libSBML

Each type of component in a plain SBML model (i.e., one that does not use any SBML packages) is described using a specific type of SBML data object that organizes the relevant information. The top level of an SBML model definition consists of lists of these components, with every list being optional. The next table enumerates the lists and objects defined by core SBML; also shown are the SBML Level+Version combinations for which they are valid.

SBML components and corresponding libSBML objects. The meaning of expressions such as “L2V4” is as follows: “Lx” = SBML Level x, and “Vy” = Version y within a given SBML Level.
Level & Version LibSBML container object LibSBML data object(s)
L2V1+ ListOfFunctionDefinitionsFunctionDefinition
L2V1+ ListOfUnitDefinitionsUnitDefinition
L2V2–L2V4 ListOfCompartmentTypesCompartmentType
L1+ ListOfCompartmentsCompartment
L2V2–L2V4 ListOfSpeciesTypesSpeciesType
L1+ ListOfSpeciesSpecies
L1+ ListOfParametersParameter
L2V2+ ListOfInitialAssignmentsInitialAssignment
L1+ ListOfRulesAssignmentRule, AlgebraicRule, RateRule
L2V2+ ListOfConstraintsConstraint
L1+ ListOfReactionsReaction
L2V1+ ListOfEventsEvent

The list of classes below constitutes the public API of core libSBML. The list includes classes that are not defined in any SBML specification; these utility classes are provided by libSBML to implement various kinds of functionality useful in the context of working with SBML content. More...

Classes

class  libsbml.AlgebraicRule
  An SBML algebraic rule representing 0 = f(W). More...
 
class  libsbml.AssignmentRule
  An SBML assignment rule representing x = f(Y). More...
 
class  libsbml.ASTNode
  Abstract Syntax Trees for mathematical expressions. More...
 
class  libsbml.Compartment
  An SBML compartment, where species are located. More...
 
class  libsbml.CompartmentType
  A compartment type in SBML Level 2. More...
 
class  libsbml.Constraint
  An SBML constraint, for stating validity assumptions. More...
 
class  libsbml.ConversionOption
  A single configuration setting for an SBML converter. More...
 
class  libsbml.ConversionProperties
  Set of configuration option values for a converter. More...
 
class  libsbml.CVTerm
  A MIRIAM-compliant controlled vocabulary term. More...
 
class  libsbml.Date
  A MIRIAM-compliant date representation. More...
 
class  libsbml.Delay
  A delay on the time of execution of an SBML event. More...
 
class  libsbml.ElementFilter
  Base class for filter functions. More...
 
class  libsbml.Event
  A discontinuous SBML event. More...
 
class  libsbml.EventAssignment
  An assignment to a variable by an SBML event. More...
 
class  libsbml.FunctionDefinition
  A user-defined function in an SBML model. More...
 
class  libsbml.InitialAssignment
  An SBML initial assignment, evaluated once only. More...
 
class  libsbml.KineticLaw
  The rate expression for an SBML reaction. More...
 
class  libsbml.L3ParserSettings
  Controls the behavior of the Level 3 formula parser. More...
 
class  libsbml.ListOf
  Parent class for libSBML's 'ListOfXYZ' classes. More...
 
class  libsbml.ListOfCompartments
  A list of Compartment objects. More...
 
class  libsbml.ListOfCompartmentTypes
  A list of CompartmentType objects. More...
 
class  libsbml.ListOfConstraints
  A list of Constraint objects. More...
 
class  libsbml.ListOfEventAssignments
  A list of EventAssignment objects. More...
 
class  libsbml.ListOfEvents
  A list of Event objects. More...
 
class  libsbml.ListOfFunctionDefinitions
  A list of FunctionDefinition objects. More...
 
class  libsbml.ListOfInitialAssignments
  A list of InitialAssignment objects. More...
 
class  libsbml.ListOfLocalParameters
  A list of LocalParameter objects. More...
 
class  libsbml.ListOfParameters
  A list of Parameter objects. More...
 
class  libsbml.ListOfReactions
  A list of Reaction objects. More...
 
class  libsbml.ListOfRules
  A list of Rule objects. More...
 
class  libsbml.ListOfSpecies
  A list of Species objects. More...
 
class  libsbml.ListOfSpeciesReferences
  A list of SpeciesReference objects. More...
 
class  libsbml.ListOfSpeciesTypes
  A list of SpeciesType objects. More...
 
class  libsbml.ListOfUnitDefinitions
  A list of UnitDefinition objects. More...
 
class  libsbml.ListOfUnits
  A list of Unit objects. More...
 
class  libsbml.LocalParameter
  A parameter inside an SBML reaction definition. More...
 
class  libsbml.Model
  An SBML model. More...
 
class  libsbml.ModelCreator
  MIRIAM-compliant data about a model's creator. More...
 
class  libsbml.ModelHistory
  MIRIAM-compliant data about a model's history. More...
 
class  libsbml.ModifierSpeciesReference
  A reference to an SBML modifier species. More...
 
class  libsbml.Parameter
  An SBML parameter: a named symbol with a value. More...
 
class  libsbml.Priority
  The priority of execution of an SBML event. More...
 
class  libsbml.RateRule
  An SBML rate rule representing dx/dt = f(Y). More...
 
class  libsbml.RDFAnnotationParser
  MIRIAM-compliant RDF annotation reader/writer. More...
 
class  libsbml.Reaction
  An SBML reaction between species in an SBML model. More...
 
class  libsbml.RenderPkgNamespaces
  Set of SBML Level + Version + namespace triples. More...
 
class  libsbml.Rule
  Parent class for SBML rules in libSBML. More...
 
class  libsbml.SBase
  SBML's SBase class, base class of most SBML objects. More...
 
class  libsbml.SBasePlugin
  Base class for extending SBML objects in packages. More...
 
class  libsbml.SBMLConverter
  Base class for SBML converters. More...
 
class  libsbml.SBMLConverterRegistry
  Registry of all libSBML SBML converters. More...
 
class  libsbml.SBMLDocument
  Overall SBML container object. More...
 
class  libsbml.SBMLDocumentPlugin
  Base class for extending SBMLDocument in packages. More...
 
class  libsbml.SBMLError
  An error, warning or other diagnostic. More...
 
class  libsbml.SBMLErrorLog
  Log of diagnostics reported during processing. More...
 
class  libsbml.SBMLExtensionException
  Exception used by package extensions More...
 
class  libsbml.SBMLExtensionRegistry
  Registry where package extensions are registered. More...
 
class  libsbml.SBMLFunctionDefinitionConverter
  Converter to expand user-defined functions in-line. More...
 
class  libsbml.SBMLIdConverter
  Converter for replacing object identifiers. More...
 
class  libsbml.SBMLInferUnitsConverter
  Converter for inferring and setting parameter units. More...
 
class  libsbml.SBMLInitialAssignmentConverter
  Converter that removes SBML initial assignments. More...
 
class  libsbml.SBMLLevelVersionConverter
  Whole-document SBML Level/Version converter. More...
 
class  libsbml.SBMLLocalParameterConverter
  Converter to turn local parameters into global ones. More...
 
class  libsbml.SBMLNamespaces
  Set of SBML Level + Version + namespace triples. More...
 
class  libsbml.SBMLReactionConverter
  Converter to replace reactions with SBML rate rules. More...
 
class  SBMLReader
  File and text-string SBML reader. More...
 
class  libsbml.SBMLReader
  File and text-string SBML reader. More...
 
class  libsbml.SBMLRuleConverter
  Converter that sorts SBML rules and assignments. More...
 
class  libsbml.SBMLStripPackageConverter
  Converter that removes SBML Level 3 packages. More...
 
class  libsbml.SBMLUnitsConverter
  Converts a model's existing units to SI units. More...
 
class  libsbml.SBMLValidator
  Base class for SBML validators. More...
 
class  SBMLWriter
  File and text-string SBML writer. More...
 
class  libsbml.SBMLWriter
  File and text-string SBML writer. More...
 
class  libsbml.SBO
  Facilities for using the Systems Biology Ontology. More...
 
class  libsbml.SimpleSpeciesReference
  Abstract class for references to species in reactions. More...
 
class  libsbml.Species
  An SBML species – a pool of entities. More...
 
class  libsbml.SpeciesReference
  A reference to an SBML species in a reaction. More...
 
class  libsbml.SpeciesType
  A species type in SBML Level 2. More...
 
class  libsbml.StoichiometryMath
  Stochiometry expressions in SBML Level 2 reactions. More...
 
class  libsbml.SyntaxChecker
  Methods for checking the validity of SBML identifiers. More...
 
class  libsbml.Trigger
  The trigger expression for an SBML event. More...
 
class  libsbml.Unit
  A single unit referenced in an SBML unit definition. More...
 
class  libsbml.UnitDefinition
  A definition of a unit used in an SBML model. More...
 
class  libsbml.XMLAttributes
  A list of attributes on an XML element. More...
 
class  libsbml.XMLError
  XML-level errors, warnings and other diagnostics. More...
 
class  libsbml.XMLErrorLog
  Log of diagnostics reported during XML processing. More...
 
class  libsbml.XMLInputStream
  An interface to an XML input stream. More...
 
class  libsbml.XMLNamespaces
  An XML Namespace. More...
 
class  libsbml.XMLNode
  A node in libSBML's XML document tree. More...
 
class  libsbml.XMLOutputStream
  Interface to an XML output stream. More...
 
class  libsbml.XMLToken
  A token in an XML stream. More...
 
class  libsbml.XMLTriple
  A qualified XML name. More...
 

Functions

def libsbml.ElementFilter.__init__ (self)
  Base class for filter functions. More...
 
def libsbml.SBMLReader.__init__ (self)
  File and text-string SBML reader. More...
 
def libsbml.SBMLWriter.__init__ (self)
  File and text-string SBML writer. More...
 
def libsbml.ListOf.__init__ (self, args)
  Parent class for libSBML's 'ListOfXYZ' classes. More...
 
def libsbml.Model.__init__ (self, args)
  An SBML model. More...
 
def libsbml.FunctionDefinition.__init__ (self, args)
  A user-defined function in an SBML model. More...
 
def libsbml.ListOfFunctionDefinitions.__init__ (self, args)
  A list of FunctionDefinition objects. More...
 
def libsbml.Unit.__init__ (self, args)
  A single unit referenced in an SBML unit definition. More...
 
def libsbml.ListOfUnits.__init__ (self, args)
  A list of Unit objects. More...
 
def libsbml.UnitDefinition.__init__ (self, args)
  A definition of a unit used in an SBML model. More...
 
def libsbml.ListOfUnitDefinitions.__init__ (self, args)
  A list of UnitDefinition objects. More...
 
def libsbml.CompartmentType.__init__ (self, args)
  A compartment type in SBML Level 2. More...
 
def libsbml.ListOfCompartmentTypes.__init__ (self, args)
  A list of CompartmentType objects. More...
 
def libsbml.SpeciesType.__init__ (self, args)
  A species type in SBML Level 2. More...
 
def libsbml.ListOfSpeciesTypes.__init__ (self, args)
  A list of SpeciesType objects. More...
 
def libsbml.Compartment.__init__ (self, args)
  An SBML compartment, where species are located. More...
 
def libsbml.ListOfCompartments.__init__ (self, args)
  A list of Compartment objects. More...
 
def libsbml.Species.__init__ (self, args)
  An SBML species – a pool of entities. More...
 
def libsbml.ListOfSpecies.__init__ (self, args)
  A list of Species objects. More...
 
def libsbml.Parameter.__init__ (self, args)
  An SBML parameter: a named symbol with a value. More...
 
def libsbml.ListOfParameters.__init__ (self, args)
  A list of Parameter objects. More...
 
def libsbml.LocalParameter.__init__ (self, args)
  A parameter inside an SBML reaction definition. More...
 
def libsbml.ListOfLocalParameters.__init__ (self, args)
  A list of LocalParameter objects. More...
 
def libsbml.InitialAssignment.__init__ (self, args)
  An SBML initial assignment, evaluated once only. More...
 
def libsbml.ListOfInitialAssignments.__init__ (self, args)
  A list of InitialAssignment objects. More...
 
def libsbml.ListOfRules.__init__ (self, args)
  A list of Rule objects. More...
 
def libsbml.AlgebraicRule.__init__ (self, args)
  An SBML algebraic rule representing 0 = f(W). More...
 
def libsbml.AssignmentRule.__init__ (self, args)
  An SBML assignment rule representing x = f(Y). More...
 
def libsbml.RateRule.__init__ (self, args)
  An SBML rate rule representing dx/dt = f(Y). More...
 
def libsbml.Constraint.__init__ (self, args)
  An SBML constraint, for stating validity assumptions. More...
 
def libsbml.ListOfConstraints.__init__ (self, args)
  A list of Constraint objects. More...
 
def libsbml.Reaction.__init__ (self, args)
  An SBML reaction between species in an SBML model. More...
 
def libsbml.ListOfReactions.__init__ (self, args)
  A list of Reaction objects. More...
 
def libsbml.KineticLaw.__init__ (self, args)
  The rate expression for an SBML reaction. More...
 
def libsbml.SpeciesReference.__init__ (self, args)
  A reference to an SBML species in a reaction. More...
 
def libsbml.ListOfSpeciesReferences.__init__ (self, args)
  A list of SpeciesReference objects. More...
 
def libsbml.ModifierSpeciesReference.__init__ (self, args)
  A reference to an SBML modifier species. More...
 
def libsbml.Event.__init__ (self, args)
  A discontinuous SBML event. More...
 
def libsbml.ListOfEvents.__init__ (self, args)
  A list of Event objects. More...
 
def libsbml.EventAssignment.__init__ (self, args)
  An assignment to a variable by an SBML event. More...
 
def libsbml.ListOfEventAssignments.__init__ (self, args)
  A list of EventAssignment objects. More...
 
def libsbml.Trigger.__init__ (self, args)
  The trigger expression for an SBML event. More...
 
def libsbml.Delay.__init__ (self, args)
  A delay on the time of execution of an SBML event. More...
 
def libsbml.Priority.__init__ (self, args)
  The priority of execution of an SBML event. More...
 
def libsbml.StoichiometryMath.__init__ (self, args)
  Stochiometry expressions in SBML Level 2 reactions. More...
 
def libsbml.SBMLNamespaces.__init__ (self, args)
  Set of SBML Level + Version + namespace triples. More...
 
def libsbml.ConversionOption.__init__ (self, args)
  A single configuration setting for an SBML converter. More...
 
def libsbml.ConversionProperties.__init__ (self, args)
  Set of configuration option values for a converter. More...
 
def libsbml.SBMLConverter.__init__ (self, args)
  Base class for SBML converters. More...
 
def libsbml.SBMLFunctionDefinitionConverter.__init__ (self, args)
  Converter to expand user-defined functions in-line. More...
 
def libsbml.SBMLIdConverter.__init__ (self, args)
  Converter for replacing object identifiers. More...
 
def libsbml.SBMLInferUnitsConverter.__init__ (self, args)
  Converter for inferring and setting parameter units. More...
 
def libsbml.SBMLInitialAssignmentConverter.__init__ (self, args)
  Converter that removes SBML initial assignments. More...
 
def libsbml.SBMLLevelVersionConverter.__init__ (self, args)
  Whole-document SBML Level/Version converter. More...
 
def libsbml.SBMLLocalParameterConverter.__init__ (self, args)
  Converter to turn local parameters into global ones. More...
 
def libsbml.SBMLReactionConverter.__init__ (self, args)
  Converter to replace reactions with SBML rate rules. More...
 
def libsbml.SBMLRuleConverter.__init__ (self, args)
  Converter that sorts SBML rules and assignments. More...
 
def libsbml.SBMLStripPackageConverter.__init__ (self, args)
  Converter that removes SBML Level 3 packages. More...
 
def libsbml.SBMLUnitsConverter.__init__ (self, args)
  Converts a model's existing units to SI units. More...
 
def libsbml.SBMLValidator.__init__ (self, args)
  Base class for SBML validators. More...
 
def libsbml.XMLAttributes.__init__ (self, args)
  A list of attributes on an XML element. More...
 
def libsbml.XMLNamespaces.__init__ (self, args)
  An XML Namespace. More...
 
def libsbml.XMLToken.__init__ (self, args)
  A token in an XML stream. More...
 
def libsbml.XMLNode.__init__ (self, args)
  A node in libSBML's XML document tree. More...
 
def libsbml.XMLTriple.__init__ (self, args)
  A qualified XML name. More...
 
def libsbml.XMLOutputStream.__init__ (self, args)
  Interface to an XML output stream. More...
 
def libsbml.XMLInputStream.__init__ (self, args)
  An interface to an XML input stream. More...
 
def libsbml.XMLError.__init__ (self, args)
  XML-level errors, warnings and other diagnostics. More...
 
def libsbml.SBMLError.__init__ (self, args)
  An error, warning or other diagnostic. More...
 
def libsbml.CVTerm.__init__ (self, args)
  A MIRIAM-compliant controlled vocabulary term. More...
 
def libsbml.Date.__init__ (self, args)
  A MIRIAM-compliant date representation. More...
 
def libsbml.ModelCreator.__init__ (self, args)
  MIRIAM-compliant data about a model's creator. More...
 
def libsbml.ModelHistory.__init__ (self, args)
  MIRIAM-compliant data about a model's history. More...
 
def libsbml.SBMLDocumentPlugin.__init__ (self, args)
  Base class for extending SBMLDocument in packages. More...
 
def libsbml.SBMLExtensionException.__init__ (self, errmsg)
  Exception used by package extensions More...
 
def libsbml.ASTNode.__init__ (self, args)
  Abstract Syntax Trees for mathematical expressions. More...
 
def libsbml.L3ParserSettings.__init__ (self, args)
  Controls the behavior of the Level 3 formula parser. More...
 
def libsbml.RenderPkgNamespaces.__init__ (self, args)
  Set of SBML Level + Version + namespace triples. More...
 
def libsbml.SBase.clone (self)
  SBML's SBase class, base class of most SBML objects. More...
 
def libsbml.Rule.clone (self)
  Parent class for SBML rules in libSBML. More...
 
def libsbml.RDFAnnotationParser.createAnnotation ()
  MIRIAM-compliant RDF annotation reader/writer. More...
 
def libsbml.SBMLDocument.getDefaultLevel ()
  Overall SBML container object. More...
 
def libsbml.SBasePlugin.getElementNamespace (self)
  Base class for extending SBML objects in packages. More...
 
def libsbml.SBMLErrorLog.getError (self, n)
  Log of diagnostics reported during processing. More...
 
def libsbml.SimpleSpeciesReference.getId (self)
  Abstract class for references to species in reactions. More...
 
def libsbml.SBMLConverterRegistry.getInstance ()
  Registry of all libSBML SBML converters. More...
 
def libsbml.SBMLExtensionRegistry.getInstance ()
  Registry where package extensions are registered. More...
 
def libsbml.XMLErrorLog.getNumErrors (self)
  Log of diagnostics reported during XML processing. More...
 
def libsbml.SBO.isQuantitativeParameter (term)
  Facilities for using the Systems Biology Ontology. More...
 
def libsbml.SyntaxChecker.isValidSBMLSId (sid)
  Methods for checking the validity of SBML identifiers. More...
 

Detailed Description

SBML Level 3 introduced a modular architecture, in which SBML Level 3 Core is usable in its own right (much like SBML Levels 1 and 2 before it), and optional SBML Level 3 Packages add features to this Core. To support this architecture, libSBML is itself divided into a core libSBML and optional extensions.

Differences between core libSBML and extensions to libSBML

Core libSBML corresponds to the features of SBML Levels 1 to 3 Core; they are always available, and do not require applications to understand more than the SBML core specifications. The classes listed on the rest of page constitute libSBML's implementation of SBML Levels 1–3, without any SBML Level 3 packages.

By contrast, the libSBML extensions are plug-ins that each implement support for a given SBML Level 3 package. Separate pages of this API manual describe the libSBML extensions for those SBML Level 3 packages that are supported at this time. They are grouped under the section titled Level 3 Extensions. The stable releases of libSBML only include extensions for officially-released package specifications; additional, experimental extensions may be available for other Level 3 packages that may not yet have been finalized by the SBML community. You can find copies of these experimental extensions at the download site for libSBML on SourceForge.net.

Summary of core SBML objects implemented in libSBML

Each type of component in a plain SBML model (i.e., one that does not use any SBML packages) is described using a specific type of SBML data object that organizes the relevant information. The top level of an SBML model definition consists of lists of these components, with every list being optional. The next table enumerates the lists and objects defined by core SBML; also shown are the SBML Level+Version combinations for which they are valid.

SBML components and corresponding libSBML objects. The meaning of expressions such as “L2V4” is as follows: “Lx” = SBML Level x, and “Vy” = Version y within a given SBML Level.
Level & Version LibSBML container object LibSBML data object(s)
L2V1+ ListOfFunctionDefinitionsFunctionDefinition
L2V1+ ListOfUnitDefinitionsUnitDefinition
L2V2–L2V4 ListOfCompartmentTypesCompartmentType
L1+ ListOfCompartmentsCompartment
L2V2–L2V4 ListOfSpeciesTypesSpeciesType
L1+ ListOfSpeciesSpecies
L1+ ListOfParametersParameter
L2V2+ ListOfInitialAssignmentsInitialAssignment
L1+ ListOfRulesAssignmentRule, AlgebraicRule, RateRule
L2V2+ ListOfConstraintsConstraint
L1+ ListOfReactionsReaction
L2V1+ ListOfEventsEvent

The list of classes below constitutes the public API of core libSBML. The list includes classes that are not defined in any SBML specification; these utility classes are provided by libSBML to implement various kinds of functionality useful in the context of working with SBML content.

Function Documentation

def libsbml.ElementFilter.__init__ (   self)

Base class for filter functions.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.

Some libSBML objects provide the ability to return lists of components. To provide callers with greater control over exactly what is returned, these methods take optional arguments in the form of filters. The ElementFilter class is the parent class for these filters.

Creates a new ElementFilter object.

__init__()   ElementFilter
def libsbml.SBMLReader.__init__ (   self)

File and text-string SBML reader.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The SBMLReader class provides the main interface for reading SBML content from files and strings. The methods for reading SBML all return an SBMLDocument object representing the results. In the case of failures (such as if the SBML contains errors or a file cannot be read), the errors will be recorded with the SBMLErrorLog object kept in the SBMLDocument returned by SBMLReader. Consequently, immediately after calling a method on SBMLReader, callers should always check for errors and warnings using the methods for this purpose provided by SBMLDocument.

For convenience as well as easy access from other languages besides C++, this file also defines two global functions, readSBML() and readSBMLFromString(). They are equivalent to creating an SBMLReader object and then calling the SBMLReader.readSBML() and SBMLReader.readSBMLFromString() methods, respectively.

Support for reading compressed files

LibSBML provides support for reading (as well as writing) compressed SBML files. The process is transparent to the calling application—the application does not need to do anything deliberate to invoke the functionality. If a given SBML filename ends with an extension for the gzip, zip or bzip2 compression formats (respectively, .gz, .zip, or .bz2), then the methods SBMLReader.readSBML() and SBMLWriter.writeSBML() will automatically decompress and compress the file while reading and writing it. If the filename has no such extension, it will be read and written uncompressed as normal.

The compression feature requires that the zlib (for gzip and zip formats) and/or bzip2 (for bzip2 format) be available on the system running libSBML, and that libSBML was configured with their support compiled-in. Please see the libSBML installation instructions for more information about this. The methods hasZlib() and hasBzip2() can be used by an application to query at run-time whether support for the compression libraries is available in the present copy of libSBML.

Support for compression is not mandated by the SBML standard, but applications may find it helpful, particularly when large SBML models are being communicated across data links of limited bandwidth.

Creates a new SBMLReader object and returns it.

__init__()   SBMLReader

The libSBML SBMLReader object offers methods for reading SBML in XML form from files and text strings.

def libsbml.SBMLWriter.__init__ (   self)

File and text-string SBML writer.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The SBMLWriter class is the converse of SBMLReader, and provides the main interface for serializing SBML models into XML and writing the result to an output stream or to files and text strings. The methods for writing SBML all take an SBMLDocument object and a destination. They return a boolean or integer value to indicate success or failure.

Support for writing compressed files

LibSBML provides support for writing (as well as reading) compressed SBML files. The process is transparent to the calling application—the application does not need to do anything deliberate to invoke the functionality. If a given SBML filename ends with an extension for the gzip, zip or bzip2 compression formats (respectively, ".gz", ".zip", or ".bz2"), then the methods SBMLWriter.writeSBML() and SBMLReader.readSBML() will automatically compress and decompress the file while writing and reading it. If the filename has no such extension, it will be written and read uncompressed as normal.

The compression feature requires that the zlib (for gzip and zip formats) and/or bzip2 (for bzip2 format) be available on the system running libSBML, and that libSBML was configured with their support compiled-in. Please see the libSBMLinstallation instructions for more information about this. The methods SBMLWriter.hasZlib() and SBMLWriter.hasBzip2() can be used by an application to query at run-time whether support for the compression libraries is available in the present copy of libSBML.

Support for compression is not mandated by the SBML standard, but applications may find it helpful, particularly when large SBML models are being communicated across data links of limited bandwidth.

Creates a new SBMLWriter.

__init__()   SBMLWriter

The libSBML SBMLWriter objects offer methods for writing SBML in XML form to files and text strings.

def libsbml.ListOf.__init__ (   self,
  args 
)

Parent class for libSBML's 'ListOfXYZ' classes.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The ListOf class in libSBML is a utility class that serves as the parent class for implementing the ListOf__ classes. It provides methods for working generically with the various SBML lists of objects in a program. LibSBML uses this separate list class rather than ordinary Python lists, so that it can provide the methods and features associated with SBase.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOf
__init__(long level)   ListOf
__init__()   ListOf
__init__(SBMLNamespaces sbmlns)   ListOf
__init__(ListOf orig)   ListOf

Each variant is described separately below.


Method variant with the following signature:
ListOf(ListOf orig)

Copy constructor; creates a copy of this ListOf.

Parameters
origthe ListOf instance to copy.

Method variant with the following signature:
ListOf(SBMLNamespaces sbmlns)

Creates a new ListOf with a given SBMLNamespaces object.

Parameters
sbmlnsthe set of SBML namespaces that this ListOf should contain.
Note
Bare ListOf objects are impossible to add to SBML models. The ListOf class is simply the base of other classes in libSBML. Calling programs are not intended to create bare ListOf objects themselves.
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
ListOf(long level = SBML_DEFAULT_LEVEL, long version = SBML_DEFAULT_VERSION)

Creates a new ListOf object.

Parameters
levelthe SBML Level; if not assigned, defaults to the value of SBMLDocument.getDefaultLevel().
versionthe Version within the SBML Level; if not assigned, defaults to the value of SBMLDocument.getDefaultVersion().
Note
Bare ListOf objects are impossible to add to SBML models. The ListOf class is simply the base of other classes in libSBML. Calling programs are not intended to create bare ListOf objects themselves.
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.Model.__init__ (   self,
  args 
)

An SBML model.

In an SBML model definition, a single object of class Model serves as the overall container for the lists of the various model components. All of the lists are optional, but if a given list container is present within the model, the list must not be empty; that is, it must have length one or more. The following are the components and lists permitted in different Levels and Versions of SBML in version 5.11.0 of libSBML:

Although all the lists are optional, there are dependencies between SBML components such that defining some components requires defining others. An example is that defining a species requires defining a compartment, and defining a reaction requires defining a species. The dependencies are explained in more detail in the SBML specifications.

In addition to the above lists and attributes, the Model class in both SBML Level 2 and Level 3 has the usual two attributes of 'id' and 'name', and both are optional. As is the case for other SBML components with 'id' and 'name' attributes, they must be used according to the guidelines described in the SBML specifications. (Within the frameworks of SBML Level 2 and Level 3 Version 1 Core, a Model object identifier has no assigned meaning, but extension packages planned for SBML Level 3 are likely to make use of this identifier.)

Finally, SBML Level 3 has introduced a number of additional Model attributes. They are discussed in a separate section below.

Approaches to creating objects using the libSBML API

LibSBML provides two main mechanisms for creating objects: class constructors (e.g., Species.Species() ), and createObject() methods (such as Model.createSpecies()) provided by certain Object classes such as Model. These multiple mechanisms are provided by libSBML for flexibility and to support different use-cases, but they also have different implications for the overall model structure.

In general, the recommended approach is to use the createObject() methods. These methods both create an object and link it to the parent in one step. Here is an example:

1 # Create an SBMLDocument object in Level 3 Version 1 format.
2 # Make sure to check for possible failures.
3 
4 try:
5  sbmlDoc = SBMLDocument(3, 1)
6 except ValueError:
7  print('Could not create SBMLDocument object')
8  sys.exit(1)
9 
10 # Create a Model object inside the SBMLDocument object and set its
11 # identifier, checking the returned values. The call to setId() returns a
12 # status code to indicate whether the assignment was successful.
13 
14 model = sbmlDoc.createModel()
15 if model == None:
16  # Do something to handle the error here.
17  print('Unable to create Model object.')
18  sys.exit(1)
19 
20 status = model.setId('BestModelEver')
21 if status != LIBSBML_OPERATION_SUCCESS:
22  # Do something to handle the error here.
23  print('Unable to set identifier on the Model object')
24  sys.exit(1)
25 
26 # Create a Species object inside the Model and set its identifier.
27 # Again, the setId() returns a status code to indicate whether the
28 # assignment was successful.
29 
30 sp = model.createSpecies()
31 if sp == None:
32  # Do something to handle the error here.
33  print('Unable to create Species object.')
34  sys.exit(1)
35 
36 status = sp.setId('BestSpeciesEver')
37 if status != LIBSBML_OPERATION_SUCCESS:
38  # Do something to handle the error here.
39  print('Unable to set identifier on the Species object')
40  sys.exit(1)

The createObject() methods return a pointer to the object created, but they also add the object to the relevant list of object instances contained in the parent. (These lists become the <listOfObjects> elements in the finished XML rendition of SBML.) In the example above, Model.createSpecies() adds the created species directly to the <listOfSpeciesgt; list in the model. Subsequently, methods called on the species change the species in the model (which is what is expected in most situations).

Consistency and adherence to SBML specifications

To make it easier for applications to do whatever they need, libSBML version 5.11.0 is relatively lax when it comes to enforcing correctness and completeness of models during model construction and editing. Essentially, libSBML will not in most cases check automatically that a model's components have valid attribute values, or that the overall model is consistent and free of errors—even obvious errors such as duplication of identifiers. This allows applications great leeway in how they build their models, but it means that software authors must take deliberate steps to ensure that the model will be, in the end, valid SBML. These steps include such things as keeping track of the identifiers used in a model, manually performing updates in certain situations where an entity is referenced in more than one place (e.g., a species that is referenced by multiple SpeciesReference objects), and so on.

That said, libSBML does provide powerful features for deliberately performing validation of SBML when an application decides it is time to do so. The interfaces to these facilities are on the SBMLDocument class, in the form of SBMLDocument.checkInternalConsistency() and SBMLDocument.checkConsistency(). Please refer to the documentation for SBMLDocument for more information about this.

While applications may play fast and loose and live like free spirits during the construction and editing of SBML models, they should always make sure to call SBMLDocument.checkInternalConsistency() and/or SBMLDocument.checkConsistency() before writing out the final version of an SBML model.

Model attributes introduced in SBML Level 3

As mentioned above, the Model class has a number of optional attributes in SBML Level 3 Version 1 Core. These are 'substanceUnits', 'timeUnits', 'volumeUnits', 'areaUnits', 'lengthUnits', 'extentUnits', and 'conversionFactor. The following provide more information about them.

The 'substanceUnits' attribute

The 'substanceUnits' attribute is used to specify the unit of measurement associated with substance quantities of Species objects that do not specify units explicitly. If a given Species object definition does not specify its unit of substance quantity via the 'substanceUnits' attribute on the Species object instance, then that species inherits the value of the Model 'substanceUnits' attribute. If the Model does not define a value for this attribute, then there is no unit to inherit, and all species that do not specify individual 'substanceUnits' attribute values then have no declared units for their quantities. The SBML Level 3 Version 1 Core specification provides more details.

Note that when the identifier of a species appears in a model's mathematical expressions, the unit of measurement associated with that identifier is not solely determined by setting 'substanceUnits' on Model or Species. Please see the discussion about units given in the documentation for the Species class.

The 'timeUnits' attribute

The 'timeUnits' attribute on SBML Level 3's Model object is used to specify the unit in which time is measured in the model. This attribute on Model is the only way to specify a unit for time in a model. It is a global attribute; time is measured in the model everywhere in the same way. This is particularly relevant to Reaction and RateRule objects in a model: all Reaction and RateRule objects in SBML define per-time values, and the unit of time is given by the 'timeUnits' attribute on the Model object instance. If the Model 'timeUnits' attribute has no value, it means that the unit of time is not defined for the model's reactions and rate rules. Leaving it unspecified in an SBML model does not result in an invalid model in SBML Level 3; however, as a matter of best practice, we strongly recommend that all models specify units of measurement for time.

The 'volumeUnits', 'areaUnits', and 'lengthUnits' attributes

The attributes 'volumeUnits', 'areaUnits' and 'lengthUnits' together are used to set the units of measurements for the sizes of Compartment objects in an SBML Level 3 model when those objects do not otherwise specify units. The three attributes correspond to the most common cases of compartment dimensions: 'volumeUnits' for compartments having a 'spatialDimensions' attribute value of '3', 'areaUnits' for compartments having a 'spatialDimensions' attribute value of '2', and 'lengthUnits' for compartments having a 'spatialDimensions' attribute value of '1'. The attributes are not applicable to compartments whose 'spatialDimensions' attribute values are not one of '1', '2' or '3'.

If a given Compartment object instance does not provide a value for its 'units' attribute, then the unit of measurement of that compartment's size is inherited from the value specified by the Model 'volumeUnits', 'areaUnits' or 'lengthUnits' attribute, as appropriate based on the Compartment object's 'spatialDimensions' attribute value. If the Model object does not define the relevant attribute, then there are no units to inherit, and all Compartment objects that do not set a value for their 'units' attribute then have no units associated with their compartment sizes.

The use of three separate attributes is a carry-over from SBML Level 2. Note that it is entirely possible for a model to define a value for two or more of the attributes 'volumeUnits', 'areaUnits' and 'lengthUnits' simultaneously, because SBML models may contain compartments with different numbers of dimensions.

The 'extentUnits' attribute

Reactions are processes that occur over time. These processes involve events of some sort, where a single ``reaction event'' is one in which some set of entities (known as reactants, products and modifiers in SBML) interact, once. The extent of a reaction is a measure of how many times the reaction has occurred, while the time derivative of the extent gives the instantaneous rate at which the reaction is occurring. Thus, what is colloquially referred to as the 'rate of the reaction' is in fact equal to the rate of change of reaction extent.

In SBML Level 3, the combination of 'extentUnits' and 'timeUnits' defines the units of kinetic laws in SBML and establishes how the numerical value of each KineticLaw object's mathematical formula is meant to be interpreted in a model. The units of the kinetic laws are taken to be 'extentUnits' divided by 'timeUnits'.

Note that this embodies an important principle in SBML Level 3 models: all reactions in an SBML model must have the same units for the rate of change of extent. In other words, the units of all reaction rates in the model must be the same. There is only one global value for 'extentUnits' and one global value for 'timeUnits'.

The 'conversionFactor' attribute

The attribute 'conversionFactor' in SBML Level 3's Model object defines a global value inherited by all Species object instances that do not define separate values for their 'conversionFactor' attributes. The value of this attribute must refer to a Parameter object instance defined in the model. The Parameter object in question must be a constant; ie it must have its 'constant' attribute value set to 'True'.

If a given Species object definition does not specify a conversion factor via the 'conversionFactor' attribute on Species, then the species inherits the conversion factor specified by the Model 'conversionFactor' attribute. If the Model does not define a value for this attribute, then there is no conversion factor to inherit. More information about conversion factors is provided in the SBML Level 3 Version 1 specification.

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   Model
__init__(SBMLNamespaces sbmlns)   Model
__init__(Model orig)   Model

Each variant is described separately below.


Method variant with the following signature:
Model(Model orig)

Copy constructor; creates a (deep) copy of the given Model object.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
Model(SBMLNamespaces sbmlns)

Creates a new Model using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
Model(long level, long version)

Creates a new Model using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this Model
versiona long integer, the SBML Version to assign to this Model
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.FunctionDefinition.__init__ (   self,
  args 
)

A user-defined function in an SBML model.

The FunctionDefinition structure associates an identifier with a function definition. This identifier can then be used as the function called in subsequent MathML content elsewhere in an SBML model.

FunctionDefinition has one required attribute, 'id', to give the function a unique identifier by which other parts of an SBML model definition can refer to it. A FunctionDefinition instance can also have an optional 'name' attribute of type string. Identifiers and names must be used according to the guidelines described in the SBML specification (e.g., Section 3.3 in the Level 2 Version 4 specification).

FunctionDefinition has a required 'math' subelement containing a MathML expression defining the function body. The content of this element can only be a MathML 'lambda' element. The 'lambda' element must begin with zero or more 'bvar' elements, followed by any other of the elements in the MathML subset allowed in SBML Level 2 except 'lambda' (i.e., a 'lambda' element cannot contain another 'lambda' element). This is the only place in SBML where a 'lambda' element can be used. The function defined by a FunctionDefinition is only available for use in other MathML elements that follow the FunctionDefinition definition in the model. (These restrictions prevent recursive and mutually-recursive functions from being expressed.)

A further restriction on the content of 'math' is that it cannot contain references to variables other than the variables declared to the 'lambda' itself. That is, the contents of MathML 'ci' elements inside the body of the 'lambda' can only be the variables declared by its 'bvar' elements, or the identifiers of other FunctionDefinition instances in the model. This means must be written so that all variables or parameters used in the MathML content are passed to them via their function parameters. In SBML Level 2, this restriction applies also to the MathML csymbol elements for time and delay; in SBML Level 3, it additionally applies to the csymbol element for avogadro.

Note
Function definitions (also informally known as user-defined functions) were introduced in SBML Level 2. They have purposefully limited capabilities. A function cannot reference parameters or other model quantities outside of itself; values must be passed as parameters to the function. Moreover, recursive and mutually-recursive functions are not permitted. The purpose of these limitations is to balance power against complexity of implementation. With the restrictions as they are, function definitions could be implemented as textual substitutions—they are simply macros. Software implementations therefore do not need the full function-definition machinery typically associated with programming languages.

Another important point to note is FunctionDefinition does not have a separate attribute for defining the units of the value returned by the function. The units associated with the function's return value, when the function is called from within MathML expressions elsewhere in SBML, are simply the overall units of the expression in FunctionDefinition's 'math' subelement when applied to the arguments supplied in the call to the function. Ascertaining these units requires performing dimensional analysis on the expression. (Readers may wonder why there is no attribute. The reason is that having a separate attribute for declaring the units would not only be redundant, but also lead to the potential for having conflicting information. In the case of a conflict between the declared units and those of the value actually returned by the function, the only logical resolution rule would be to assume that the correct units are those of the expression anyway.)

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   FunctionDefinition
__init__(SBMLNamespaces sbmlns)   FunctionDefinition
__init__(FunctionDefinition orig)   FunctionDefinition

Each variant is described separately below.


Method variant with the following signature:
FunctionDefinition(FunctionDefinition orig)

Copy constructor; creates a copy of this FunctionDefinition.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
FunctionDefinition(SBMLNamespaces sbmlns)

Creates a new FunctionDefinition using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
FunctionDefinition(long level, long version)

Creates a new FunctionDefinition using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this FunctionDefinition
versiona long integer, the SBML Version to assign to this FunctionDefinition
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.ListOfFunctionDefinitions.__init__ (   self,
  args 
)

A list of FunctionDefinition objects.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOfFunctionDefinitions
__init__(SBMLNamespaces sbmlns)   ListOfFunctionDefinitions

Each variant is described separately below.


Method variant with the following signature:
ListOfFunctionDefinitions(SBMLNamespaces sbmlns)

Creates a new ListOfFunctionDefinitions object.

The object is constructed such that it is valid for the SBML Level and Version combination determined by the SBMLNamespaces object in sbmlns.

Parameters
sbmlnsan SBMLNamespaces object that is used to determine the characteristics of the ListOfFunctionDefinitions object to be created.

Method variant with the following signature:
ListOfFunctionDefinitions(long level, long version)

Creates a new ListOfFunctionDefinitions object.

The object is constructed such that it is valid for the given SBML Level and Version combination.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
def libsbml.Unit.__init__ (   self,
  args 
)

A single unit referenced in an SBML unit definition.

The SBML unit definition facility uses two classes of objects, UnitDefinition and Unit. The approach to defining units in SBML is compositional; for example, meter second –2 is constructed by combining a Unit object representing meter with another Unit object representing second –2. The combination is wrapped inside a UnitDefinition, which provides for assigning an identifier and optional name to the combination. The identifier can then be referenced from elsewhere in a model. Thus, the UnitDefinition class is the container, and Unit instances are placed inside UnitDefinition instances.

A Unit has four attributes named 'kind', 'exponent', 'scale' and 'multiplier'. It represents a (possibly transformed) reference to a base unit. The attribute 'kind' on Unit indicates the chosen base unit. Its value must be one of the text strings listed below; this list corresponds to SBML Level 3 Version 1 Core:

amperefaradjouleluxradianvolt
avogadrogramkatalmetresecondwatt
becquerelgraykelvinmolesiemensweber
candelahenrykilogramnewtonsievert
coulombhertzlitreohmsteradian
dimensionlessitemlumenpascaltesla

A few small differences exist between the Level 3 list of base units and the list defined in other Level/Version combinations of SBML. Specifically, Levels of SBML before Level 3 do not define avogadro; conversely, Level 2 Version 1 defines Celsius, and Level 1 defines celsius, meter, and liter, none of which are available in Level 3. In libSBML, each of the predefined base unit names is represented by an enumeration value whose name begins with the characters UNIT_KIND_, discussed in a separate section below.

The attribute named 'exponent' on Unit represents an exponent on the unit. In SBML Level 2, the attribute is optional and has a default value of 1 (one); in SBML Level 3, the attribute is mandatory and there is no default value. A Unit also has an attribute called 'scale'; its value must be an integer exponent for a power-of-ten multiplier used to set the scale of the unit. For example, a unit having a 'kind' value of gram and a 'scale' value of -3 signifies 10 –3 * gram, or milligrams. In SBML Level 2, the attribute is optional and has a default value of 0 (zero), because 10 0 = 1; in SBML Level 3, the attribute is mandatory and has no default value. Lastly, the attribute named 'multiplier' can be used to multiply the unit by a real-numbered factor; this enables the definition of units that are not power-of-ten multiples of SI units. For instance, a multiplier of 0.3048 could be used to define foot as a measure of length in terms of a metre. The 'multiplier' attribute is optional in SBML Level 2, where it has a default value of 1 (one); in SBML Level 3, the attribute is mandatory and has not default value.

Unit identification codes

As discussed above, SBML defines a set of base units which serves as the starting point for new unit definitions. This set of base units consists of the SI units and a small number of additional convenience units.

In SBML Level 2 Versions before Version 3, there existed an enumeration of units called UnitKind. In Version 3, this enumeration was removed and the identifier class UnitSId redefined to include the previous UnitKind values as reserved symbols. This change has no net effect on permissible models, their representation or their syntax. The purpose of the change in the SBML specification was simply to clean up an inconsistency about the contexts in which these values were usable. However, libSBML maintains UnitKind in the form of of a set of static integer constants whose names begin with the characters UNIT_KIND_. These constants are defined in the class libsbml.

As a consequence of the fact that libSBML supports models in all Levels and Versions of SBML, libSBML's set of UNIT_KIND_ values is a union of all the possible base unit names defined in the different SBML specifications. However, not every base unit is allowed in every Level+Version combination of SBML. Note in particular the following exceptions:

  • The alternate spelling 'meter' is included in addition to the official SI spelling 'metre'. This spelling is only permitted in SBML Level 1 models.

  • The alternate spelling 'liter' is included in addition to the official SI spelling 'litre'. This spelling is only permitted in SBML Level 1 models.

  • The unit 'Celsius' is included because of its presence in specifications of SBML prior to SBML Level 2 Version 3.

  • The unit avogadro was introduced in SBML Level 3, and is only permitted for use in SBML Level 3 models.

The table below lists the unit constants defined in libSBML, and their meanings.

Enumerator Meaning
UNIT_KIND_AMPEREThe ampere unit.
UNIT_KIND_AVOGADROThe unit dimensionless multiplied by the numerical value of Avogadro's constant. (Only usable in SBML Level 3 models.)
UNIT_KIND_BECQUERELThe becquerel unit.
UNIT_KIND_CANDELAThe candela unit.
UNIT_KIND_CELSIUSThe Celsius unit. (Only usable in SBML Level 1 and SBML Level 2 Version 1 models.)
UNIT_KIND_COULOMBThe coulomb unit.
UNIT_KIND_DIMENSIONLESSA pseudo-unit indicating a dimensionless quantity.
UNIT_KIND_FARADThe farad unit.
UNIT_KIND_GRAMThe gram unit.
UNIT_KIND_GRAYThe gray unit.
UNIT_KIND_HENRYThe henry unit.
UNIT_KIND_HERTZThe hertz unit.
UNIT_KIND_ITEMA pseudo-unit representing a single "thing".
UNIT_KIND_JOULEThe joule unit.
UNIT_KIND_KATALThe katal unit.
UNIT_KIND_KELVINThe kelvin unit.
UNIT_KIND_KILOGRAMThe kilogram unit.
UNIT_KIND_LITERAlternate spelling of litre.
UNIT_KIND_LITREThe litre unit.
UNIT_KIND_LUMENThe lumen unit.
UNIT_KIND_LUXThe lux unit.
UNIT_KIND_METERAlternate spelling of metre.
UNIT_KIND_METREThe metre unit.
UNIT_KIND_MOLEThe mole unit.
UNIT_KIND_NEWTONThe newton unit.
UNIT_KIND_OHMThe ohm unit.
UNIT_KIND_PASCALThe pascal unit.
UNIT_KIND_RADIANThe radian unit.
UNIT_KIND_SECONDThe second unit.
UNIT_KIND_SIEMENSThe siemens unit.
UNIT_KIND_SIEVERTThe sievert unit.
UNIT_KIND_STERADIANThe steradian unit.
UNIT_KIND_TESLAThe tesla unit.
UNIT_KIND_VOLTThe volt unit.
UNIT_KIND_WATTThe watt unit.
UNIT_KIND_WEBERThe weber unit.
UNIT_KIND_INVALIDMarker used by libSBML to indicate an invalid or unset unit.

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   Unit
__init__(SBMLNamespaces sbmlns)   Unit
__init__(Unit orig)   Unit

Each variant is described separately below.


Method variant with the following signature:
Unit(SBMLNamespaces sbmlns)

Creates a new Unit using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
Unit(Unit orig)

Copy constructor; creates a copy of this Unit.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
Unit(long level, long version)

Creates a new Unit using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this Unit
versiona long integer, the SBML Version to assign to this Unit
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.ListOfUnits.__init__ (   self,
  args 
)

A list of Unit objects.

ListOfUnits is entirely contained within UnitDefinition.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOfUnits
__init__(SBMLNamespaces sbmlns)   ListOfUnits

Each variant is described separately below.


Method variant with the following signature:
ListOfUnits(SBMLNamespaces sbmlns)

Creates a new ListOfUnits object.

The object is constructed such that it is valid for the SBML Level and Version combination determined by the SBMLNamespaces object in sbmlns.

Parameters
sbmlnsan SBMLNamespaces object that is used to determine the characteristics of the ListOfUnits object to be created.

Method variant with the following signature:
ListOfUnits(long level, long version)

Creates a new ListOfUnits object.

The object is constructed such that it is valid for the given SBML Level and Version combination.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
def libsbml.UnitDefinition.__init__ (   self,
  args 
)

A definition of a unit used in an SBML model.

Units of measurement may be supplied in a number of contexts in an SBML model. The SBML unit definition facility uses two classes of objects, UnitDefinition and Unit. The approach to defining units in SBML is compositional; for example, meter second –2 is constructed by combining a Unit object representing meter with another Unit object representing second –2. The combination is wrapped inside a UnitDefinition, which provides for assigning an identifier and optional name to the combination. The identifier can then be referenced from elsewhere in a model. Thus, the UnitDefinition class is the container, and Unit instances are placed inside UnitDefinition instances.

Two points are worth discussing in the context of SBML units. First, unit declarations in SBML models are optional. The consequence of this is that a model must be numerically self-consistent independently of unit declarations, for the benefit of software tools that cannot interpret or manipulate units. Unit declarations in SBML are thus more akin to a type of annotation; they can indicate intentions, and can be used by model readers for checking the consistency of the model, labeling simulation output, etc., but any transformations of values implied by different units must be incorporated explicitly into a model.

Second, the vast majority of situations that require new SBML unit definitions involve simple multiplicative combinations of base units and factors. An example is moles per litre per second. What distinguishes these sorts of unit definitions from more complex ones is that they may be expressed without the use of an additive offset from a zero point. The use of offsets complicates all unit definition systems, yet in the domain of SBML, the real-life cases requiring offsets are few (and in fact, to the best of our knowledge, only involve temperature). Consequently, the SBML unit system has been consciously designed to simplify implementation of unit support for the most common cases in systems biology. The cost of this simplification is to require units with offsets to be handled explicitly by the modeler.

Summary of the UnitDefinition construct

UnitDefinition has two attributes and one subelement. The two attributes are 'id' and 'name', and the subelement is ListOfUnits.

The required attribute 'id' and optional attribute 'name' are both strings. The 'id' attribute is used to give the defined unit a unique identifier by which other parts of an SBML model definition can refer to it. The 'name' attribute is intended to be used for giving the unit definition an optional human-readable name. Please see the next section for information about the values permitted for 'id'.

A UnitDefinition must contain exactly one ListOfUnits, and this list must contain one or more Unit definitions; see the definitions of these other object classes for more information about them. The following example illustrates a complete unit definition (when written in XML) when they all the pieces are combined together. This defines 'mmls' to be millimoles per litre per second.

 <listOfUnitDefinitions>
 <unitDefinition id='mmls'>
     <listOfUnits>
         <unit kind='mole'   scale='-3'/>
         <unit kind='litre'  exponent='-1'/>
         <unit kind='second' exponent='-1'/>
     </listOfUnits>
 </unitDefinition>
 </listOfUnitDefinitions>

Special considerations for Unit object identifiers

The attribute 'id' in UnitDefinition cannot be given simply any value, and the precise details of the values permitted differ slightly between Levels of SBML:

  • The 'id' of a UnitDefinition must not contain a value from the list of SBML's predefined base unit names (i.e., the strings gram, litre, etc.). In SBML Level 3, this list consists of the following:

    amperefaradjouleluxradianvolt
    avogadrogramkatalmetresecondwatt
    becquerelgraykelvinmolesiemensweber
    candelahenrykilogramnewtonsievert
    coulombhertzlitreohmsteradian
    dimensionlessitemlumenpascaltesla

    This list of predefined base units is nearly identical in SBML Level 2 Version 4, the exception being that Level 2 does not define avogadro. SBML Level 2 Version 1 (and only this Level+Version combination) provides an additional predefined unit name, Celsius, not available in Level 3. Finally, SBML Level 1 Versions 2–3 provide two more additional predefined unit names, meter and liter. This is explained in somewhat greater detail in the description of the Unit class.

    • In SBML Level 2 (all Versions), there is an additional set of reserved identifiers: substance, volume, area, length, and time. Using one of these values for the attribute 'id' of a UnitDefinition has the effect of redefining the model-wide default units for the corresponding quantities. The list of special unit names in SBML Level 2 is given in the table below:
    Identifier Possible scalable units Default units
    substancemole, item, gram, kilogram, dimensionlessmole
    volumelitre, cubic metre, dimensionlesslitre
    areasquare metre, dimensionlesssquare metre
    lengthmetre, dimensionlessmetre
    timesecond, dimensionlesssecond

    Also, SBML Level 2 imposes two limitations on redefining the predefined unit substance, volume, area, length, and time: (1) The UnitDefinition of a predefined SBML unit can only contain a single Unit object within it. (2) The value of the 'kind' attribute in a Unit instance must be drawn from one of the values in the second column of the table above.

    The special unit names substance, volume, area, length, and time are not defined by SBML Level 3, which uses a different approach to setting model-wide inherited units.

Further comments about SBML's unit definition system

The vast majority of modeling situations requiring new SBML unit definitions involve simple multiplicative combinations of base units and factors. An example of this might be moles per litre per second. What distinguishes these sorts of simpler unit definitions from more complex ones is that they may be expressed without the use of an additive offset from a zero point. The use of offsets complicates all unit definition systems, yet in the domain of SBML the real-life cases requiring offsets are few (and in fact, to the best of our knowledge, only involve temperature). Consequently, the SBML unit system has been consciously designed in a way that attempts to simplify implementation of unit support for the most common cases in systems biology.

As of SBML Level 2 Version 2, Unit no longer has the attribute called 'offset' introduced in SBML Level 2 Version 1. It turned out that the general case involving units with offsets was incorrectly defined, and few (if any) developers even attempted to support offset-based units in their software. In the development of Level 2 Version 2, a consensus among SBML developers emerged that a fully generalized unit scheme is so confusing and complicated that it actually impedes interoperability. SBML Level 2 Version 2, Version 3 and Version 4 acknowledge this reality by reducing and simplifying the unit system, specifically by removing the 'offset' attribute on Unit and Celsius as a pre-defined unit.

The following guidelines suggest methods for handling units that do require the use of zero offsets for their definitions:

  • Handling Celsius. A model in which certain quantities are temperatures measured in degrees Celsius can be converted straightforwardly to a model in which those temperatures are in kelvin. A software tool could do this by performing a straightforward substitution using the following relationship: T kelvin = TCelsius + 273.15. In every mathematical formula of the model where a quantity (call it x) in degrees Celsius appears, replace x with xk+ 273.15, where xk is now in kelvin. An alternative approach would be to use a FunctionDefinition object to define a function encapsulating this relationship above and then using that in the rest of the model as needed. Since Celsius is a commonly-used unit, software tools could help users by providing users with the ability to express temperatures in Celsius in the tools' interfaces, and making substitutions automatically when writing out the SBML.

  • Other units requiring offsets. One approach to handling other kinds of units is to use a FunctionDefinition to define a function encapsulating the necessary mathematical relationship, then substituting a call to this function wherever the original quantity appeared in the model. For example, here is a possible definition for converting Fahrenheit to Celsius degrees:

     <functionDefinition id='Fahrenheit_to_kelvin'>
     <math xmlns='http://www.w3.org/1998/Math/MathML'>
         <lambda>
             <bvar><ci> temp_in_fahrenheit </ci></bvar>
             <apply>
                 <divide/>
                 <apply>
                     <plus/>
                     <ci> temp_in_fahrenheit </ci>
                     <cn> 459.67 </cn>
                 </apply>
                 <cn> 1.8 </cn>
             </apply>
         </lambda>
     </math>
     </functionDefinition>

  • An alternative approach not requiring the use of function definitions is to use an AssignmentRule for each variable in Fahrenheit units. The AssignmentRule could compute the conversion from Fahrenheit to (say) kelvin, assign its value to a variable (in Kelvin units), and then that variable could be used elsewhere in the model.

  • Still another approach is to rewrite the mathematical formulas of a model to directly incorporate the conversion formula wherever the original quantity appeared.

Please consult the SBML specifications for more information about this and other issues involving units.

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   UnitDefinition
__init__(SBMLNamespaces sbmlns)   UnitDefinition
__init__(UnitDefinition orig)   UnitDefinition

Each variant is described separately below.


Method variant with the following signature:
UnitDefinition(SBMLNamespaces sbmlns)

Creates a new UnitDefinition using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
UnitDefinition(long level, long version)

Creates a new UnitDefinition using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this UnitDefinition
versiona long integer, the SBML Version to assign to this UnitDefinition
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
UnitDefinition(UnitDefinition orig)

Copy constructor; creates a copy of this UnitDefinition.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.
def libsbml.ListOfUnitDefinitions.__init__ (   self,
  args 
)

A list of UnitDefinition objects.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOfUnitDefinitions
__init__(SBMLNamespaces sbmlns)   ListOfUnitDefinitions

Each variant is described separately below.


Method variant with the following signature:
ListOfUnitDefinitions(SBMLNamespaces sbmlns)

Creates a new ListOfUnitDefinitions object.

The object is constructed such that it is valid for the SBML Level and Version combination determined by the SBMLNamespaces object in sbmlns.

Parameters
sbmlnsan SBMLNamespaces object that is used to determine the characteristics of the ListOfUnitDefinitions object to be created.

Method variant with the following signature:
ListOfUnitDefinitions(long level, long version)

Creates a new ListOfUnitDefinitions object.

The object is constructed such that it is valid for the given SBML Level and Version combination.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
def libsbml.CompartmentType.__init__ (   self,
  args 
)

A compartment type in SBML Level 2.

SBML Level 2 Versions 2–4 provide the compartment type as a grouping construct that can be used to establish a relationship between multiple Compartment objects. A CompartmentType object only has an identity, and this identity can only be used to indicate that particular Compartment objects in the model belong to this type. This may be useful for conveying a modeling intention, such as when a model contains many similar compartments, either by their biological function or the reactions they carry. Without a compartment type construct, it would be impossible within SBML itself to indicate that all of the compartments share an underlying conceptual relationship because each SBML compartment must be given a unique and separate identity. Compartment types have no mathematical meaning in SBML—they have no effect on a model's mathematical interpretation. Simulators and other numerical analysis software may ignore CompartmentType definitions and references to them in a model.

There is no mechanism in SBML Level 2 for representing hierarchies of compartment types. One CompartmentType instance cannot be the subtype of another CompartmentType instance; SBML provides no means of defining such relationships.

As with other major structures in SBML, CompartmentType has a mandatory attribute, 'id', used to give the compartment type an identifier. The identifier must be a text string conforming to the identifer syntax permitted in SBML. CompartmentType also has an optional 'name' attribute, of type string. The 'id' and 'name' must be used according to the guidelines described in the SBML specification (e.g., Section 3.3 in the Level 2 Version 4 specification).

CompartmentType was introduced in SBML Level 2 Version 2. It is not available in SBML Level 1 nor in Level 3.

See also
Compartment
ListOfCompartmentTypes
SpeciesType
ListOfSpeciesTypes

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   CompartmentType
__init__(SBMLNamespaces sbmlns)   CompartmentType
__init__(CompartmentType orig)   CompartmentType

Each variant is described separately below.


Method variant with the following signature:
CompartmentType(SBMLNamespaces sbmlns)

Creates a new CompartmentType object using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.

It is worth emphasizing that although this constructor does not take an identifier argument, in SBML Level 2 and beyond, the 'id' (identifier) attribute of a CompartmentType object is required to have a value. Thus, callers are cautioned to assign a value after calling this constructor. Setting the identifier can be accomplished using the method setId().

Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
CompartmentType(CompartmentType orig)

Copy constructor; creates a copy of this CompartmentType object.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
CompartmentType(long level, long version)

Creates a new CompartmentType object using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this CompartmentType
versiona long integer, the SBML Version to assign to this CompartmentType
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.ListOfCompartmentTypes.__init__ (   self,
  args 
)

A list of CompartmentType objects.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOfCompartmentTypes
__init__(SBMLNamespaces sbmlns)   ListOfCompartmentTypes

Each variant is described separately below.


Method variant with the following signature:
ListOfCompartmentTypes(SBMLNamespaces sbmlns)

Creates a new ListOfCompartmentTypes object.

The object is constructed such that it is valid for the SBML Level and Version combination determined by the SBMLNamespaces object in sbmlns.

Parameters
sbmlnsan SBMLNamespaces object that is used to determine the characteristics of the ListOfCompartmentTypes object to be created.

Method variant with the following signature:
ListOfCompartmentTypes(long level, long version)

Creates a new ListOfCompartmentTypes object.

The object is constructed such that it is valid for the given SBML Level and Version combination.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
def libsbml.SpeciesType.__init__ (   self,
  args 
)

A species type in SBML Level 2.

The term species type refers to reacting entities independent of location. These include simple ions (e.g., protons, calcium), simple molecules (e.g., glucose, ATP), large molecules (e.g., RNA, polysaccharides, and proteins), and others.

SBML Level 2 Versions 2–4 provide an explicit SpeciesType class of object to enable Species objects of the same type to be related together. SpeciesType is a conceptual construct; the existence of SpeciesType objects in a model has no effect on the model's numerical interpretation. Except for the requirement for uniqueness of species/species type combinations located in compartments, simulators and other numerical analysis software may ignore SpeciesType definitions and references to them in a model.

There is no mechanism in SBML Level 2 for representing hierarchies of species types. One SpeciesType object cannot be the subtype of another SpeciesType object; SBML provides no means of defining such relationships.

As with other major structures in SBML, SpeciesType has a mandatory attribute, 'id', used to give the species type an identifier. The identifier must be a text string conforming to the identifer syntax permitted in SBML. SpeciesType also has an optional 'name' attribute, of type string. The 'id' and 'name' must be used according to the guidelines described in the SBML specification (e.g., Section 3.3 in the Level 2 Version 4 specification).

SpeciesType was introduced in SBML Level 2 Version 2. It is not available in SBML Level 1 nor in Level 3.

See also
Species
ListOfSpeciesTypes
CompartmentType
ListOfCompartmentTypes

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   SpeciesType
__init__(SBMLNamespaces sbmlns)   SpeciesType
__init__(SpeciesType orig)   SpeciesType

Each variant is described separately below.


Method variant with the following signature:
SpeciesType(SpeciesType orig)

Copy constructor; creates a copy of this SpeciesType.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
SpeciesType(SBMLNamespaces sbmlns)

Creates a new SpeciesType using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.

It is worth emphasizing that although this constructor does not take an identifier argument, in SBML Level 2 and beyond, the 'id' (identifier) attribute of a SpeciesType object is required to have a value. Thus, callers are cautioned to assign a value after calling this constructor. Setting the identifier can be accomplished using the method SBase.setId().

Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
SpeciesType(long level, long version)

Creates a new SpeciesType using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this SpeciesType
versiona long integer, the SBML Version to assign to this SpeciesType
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.ListOfSpeciesTypes.__init__ (   self,
  args 
)

A list of SpeciesType objects.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOfSpeciesTypes
__init__(SBMLNamespaces sbmlns)   ListOfSpeciesTypes

Each variant is described separately below.


Method variant with the following signature:
ListOfSpeciesTypes(SBMLNamespaces sbmlns)

Creates a new ListOfSpeciesTypes object.

The object is constructed such that it is valid for the SBML Level and Version combination determined by the SBMLNamespaces object in sbmlns.

Parameters
sbmlnsan SBMLNamespaces object that is used to determine the characteristics of the ListOfSpeciesTypes object to be created.

Method variant with the following signature:
ListOfSpeciesTypes(long level, long version)

Creates a new ListOfSpeciesTypes object.

The object is constructed such that it is valid for the given SBML Level and Version combination.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
def libsbml.Compartment.__init__ (   self,
  args 
)

An SBML compartment, where species are located.

A compartment in SBML represents a bounded space in which species are located. Compartments do not necessarily have to correspond to actual structures inside or outside of a biological cell.

It is important to note that although compartments are optional in the overall definition of Model, every species in an SBML model must be located in a compartment. This in turn means that if a model defines any species, the model must also define at least one compartment. The reason is simply that species represent physical things, and therefore must exist somewhere. Compartments represent the somewhere.

Compartment has one required attribute, 'id', to give the compartment a unique identifier by which other parts of an SBML model definition can refer to it. A compartment can also have an optional 'name' attribute of type string. Identifiers and names must be used according to the guidelines described in the SBML specifications.

Compartment also has an optional attribute 'spatialDimensions' that is used to indicate the number of spatial dimensions possessed by the compartment. Most modeling scenarios involve compartments with integer values of 'spatialDimensions' of 3 (i.e., a three-dimensional compartment, which is to say, a volume), or 2 (a two-dimensional compartment, a surface), or 1 (a one-dimensional compartment, a line). In SBML Level 3, the type of this attribute is float, there are no restrictions on the permitted values of the 'spatialDimensions' attribute, and there are no default values. In SBML Level 2, the value must be a positive integer, and the default value is 3; the permissible values in SBML Level 2 are 3, 2, 1, and 0 (for a point).

Another optional attribute on Compartment is 'size', representing the initial total size of that compartment in the model. The 'size' attribute must be a floating-point value and may represent a volume (if the compartment is a three-dimensional one), or an area (if the compartment is two-dimensional), or a length (if the compartment is one-dimensional). There is no default value of compartment size in SBML Level 2 or Level 3. In particular, a missing 'size' value does not imply that the compartment size is 1. (This is unlike the definition of compartment 'volume' in SBML Level 1.) When the compartment's 'spatialDimensions' attribute does not have a value of 0, a missing value of 'size' for a given compartment signifies that the value either is unknown, or to be obtained from an external source, or determined by an InitialAssignment, AssignmentRule, AlgebraicRule or RateRule object elsewhere in the model. In SBML Level 2, there are additional special requirements on the values of 'size'; we discuss them in a separate section below.

The units associated with a compartment's 'size' attribute value may be set using the optional attribute 'units'. The rules for setting and using compartment size units differ between SBML Level 2 and Level 3, and are discussed separately below.

Finally, the optional Compartment attribute named 'constant' is used to indicate whether the compartment's size stays constant after simulation begins. A value of True indicates the compartment's 'size' cannot be changed by any other construct except InitialAssignment; a value of False indicates the compartment's 'size' can be changed by other constructs in SBML. In SBML Level 2, there is an additional explicit restriction that if 'spatialDimensions'='0', the value cannot be changed by InitialAssignment either. Further, in Level 2, 'constant' has a default value of True. In SBML Level 3, there is no default value for the 'constant' attribute.

Additional considerations in SBML Level 2

In SBML Level 2, the default units of compartment size, and the kinds of units allowed as values of the attribute 'units', interact with the number of spatial dimensions of the compartment. The value of the 'units' attribute of a Compartment object must be one of the base units (see Unit), or the predefined unit identifiers volume, area, length or dimensionless, or a new unit defined by a UnitDefinition object in the enclosing Model, subject to the restrictions detailed in the following table:

Restrictions on values permitted for compartment size and units attributes.
Value of
spatialDimensions
size
allowed?
units
allowed?
Allowable kinds of units Default value of attribute units
3 yes yes units of volume, or dimensionless volume
2 yes yes units of area, or dimensionless area
1 yes yes units of length, or dimensionless length
0 no no (no units allowed)

In SBML Level 2, the units of the compartment size, as defined by the 'units' attribute or (if 'units' is not set) the default value listed in the table above, are used in the following ways when the compartment has a 'spatialDimensions' value greater than 0:

  • The value of the 'units' attribute is used as the units of the compartment identifier when the identifier appears as a numerical quantity in a mathematical formula expressed in MathML.

  • The math element of an AssignmentRule or InitialAssignment referring to this compartment must have identical units.

  • In RateRule objects that set the rate of change of the compartment's size, the units of the rule's math element must be identical to the compartment's 'units' attribute divided by the default time units. (In other words, the units for the rate of change of compartment size are compartment size/time units.

  • When a Species is to be treated in terms of concentrations or density, the units of the spatial size portion of the concentration value (i.e., the denominator in the units formula substance/size) are those indicated by the value of the 'units' attribute on the compartment in which the species is located.

Compartments with 'spatialDimensions'=0 require special treatment in this framework. As implied above, the 'size' attribute must not have a value on an SBML Level 2 Compartment object if the 'spatialDimensions' attribute has a value of 0. An additional related restriction is that the 'constant' attribute must default to or be set to True if the value of the 'spatialDimensions' attribute is 0, because a zero-dimensional compartment cannot ever have a size.

If a compartment has no size or dimensional units, how should such a compartment's identifier be interpreted when it appears in mathematical formulas? The answer is that such a compartment's identifier should not appear in mathematical formulas in the first place—it has no value, and its value cannot change. Note also that a zero-dimensional compartment is a point, and species located at points can only be described in terms of amounts, not spatially-dependent measures such as concentration. Since SBML KineticLaw formulas are already in terms of substance/time and not (say) concentration/time, volume or other factors in principle are not needed for species located in zero-dimensional compartments.

Finally, in SBML Level 2 Versions 2–4, each compartment in a model may optionally be designated as belonging to a particular compartment type. The optional attribute 'compartmentType' is used identify the compartment type represented by the Compartment structure. The 'compartmentType' attribute's value must be the identifier of a CompartmentType instance defined in the model. If the 'compartmentType' attribute is not present on a particular compartment definition, a unique virtual compartment type is assumed for that compartment, and no other compartment can belong to that compartment type. The values of 'compartmentType' attributes on compartments have no effect on the numerical interpretation of a model. Simulators and other numerical analysis software may ignore 'compartmentType' attributes. The 'compartmentType' attribute and the CompartmentType class of objects are not present in SBML Level 3 Core nor in SBML Level 1.

Additional considerations in SBML Level 3

One difference between SBML Level 3 and lower Levels of SBML is that there are no restrictions on the permissible values of the 'spatialDimensions' attribute, and there is no default value defined for the attribute. The value of 'spatialDimensions' does not have to be an integer, either; this is to allow for the possibility of representing structures with fractal dimensions.

The number of spatial dimensions possessed by a compartment cannot enter into mathematical formulas, and therefore cannot directly alter the numerical interpretation of a model. However, the value of 'spatialDimensions' does affect the interpretation of the units associated with a compartment's size. Specifically, the value of 'spatialDimensions' is used to select among the Model attributes 'volumeUnits', 'areaUnits' and 'lengthUnits' when a Compartment structure does not define a value for its 'units' attribute.

The 'units' attribute may be left unspecified for a given compartment in a model; in that case, the compartment inherits the unit of measurement specified by one of the attributes on the enclosing Model object instance. The applicable attribute on Model depends on the value of the compartment's 'spatialDimensions' attribute; the relationship is shown in the table below. If the Model object does not define the relevant attribute ('volumeUnits', 'areaUnits' or 'lengthUnits') for a given 'spatialDimensions' value, the unit associated with that Compartment object's size is undefined. If both 'spatialDimensions' and 'units' are left unset on a given Compartment object instance, then no unit can be chosen from among the Model's 'volumeUnits', 'areaUnits' or 'lengthUnits' attributes (even if the Model instance provides values for those attributes), because there is no basis to select between them and there is no default value of 'spatialDimensions'. Leaving the units of compartments' sizes undefined in an SBML model does not render the model invalid; however, as a matter of best practice, we strongly recommend that all models specify the units of measurement for all compartment sizes.

Interpretation of the Compartment 'units' attribute.
Value of attribute
'spatialDimensions'
Attribute of Model used
for inheriting the unit
Recommended candidate units
3 "volumeUnits" units of volume, or dimensionless
2 "areaUnits" units of area, or dimensionless
1 "lengthUnits" units of length, or dimensionless
other no units inherited no specific recommendations

The unit of measurement associated with a compartment's size, as defined by the 'units' attribute or (if 'units' is not set) the inherited value from Model according to the table above, is used in the following ways:

  • When the identifier of the compartment appears as a numerical quantity in a mathematical formula expressed in MathML, it represents the size of the compartment, and the unit associated with the size is the value of the 'units' attribute.

  • When a Species is to be treated in terms of concentrations or density, the unit associated with the spatial size portion of the concentration value (i.e., the denominator in the formula amount/size) is specified by the value of the 'units' attribute on the compartment in which the species is located.

  • The 'math' elements of AssignmentRule, InitialAssignment and EventAssignment objects setting the value of the compartment size should all have the same units as the unit associated with the compartment's size.

  • In a RateRule object that defines a rate of change for a compartment's size, the unit of the rule's 'math' element should be identical to the compartment's 'units' attribute divided by the model-wide unit of time. (In other words, {unit of compartment size}/{unit of time}.)

Other aspects of Compartment

In SBML Level 1 and Level 2, Compartment has an optional attribute named 'outside', whose value can be the identifier of another Compartment object defined in the enclosing Model object. Doing so means that the other compartment contains it or is outside of it. This enables the representation of simple topological relationships between compartments, for those simulation systems that can make use of the information (e.g., for drawing simple diagrams of compartments). It is worth noting that in SBML, there is no relationship between compartment sizes when compartment positioning is expressed using the 'outside' attribute. The size of a given compartment does not in any sense include the sizes of other compartments having it as the value of their 'outside' attributes. In other words, if a compartment B has the identifier of compartment A as its 'outside' attribute value, the size of A does not include the size of B. The compartment sizes are separate.

In Level 2, there are two restrictions on the 'outside' attribute. First, because a compartment with 'spatialDimensions' of 0 has no size, such a compartment cannot act as the container of any other compartment except compartments that also have 'spatialDimensions' values of 0. Second, the directed graph formed by representing Compartment structures as vertexes and the 'outside' attribute values as edges must be acyclic. The latter condition is imposed to prevent a compartment from being contained inside itself. In the absence of a value for 'outside', compartment definitions in SBML Level 2 do not have any implied spatial relationships between each other.

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   Compartment
__init__(SBMLNamespaces sbmlns)   Compartment
__init__(Compartment orig)   Compartment

Each variant is described separately below.


Method variant with the following signature:
Compartment(Compartment orig)

Copy constructor.

This creates a copy of a Compartment object.

Parameters
origthe Compartment instance to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
Compartment(SBMLNamespaces sbmlns)

Creates a new Compartment object using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.

It is worth emphasizing that although this constructor does not take an identifier argument, in SBML Level 2 and beyond, the 'id' (identifier) attribute of a Compartment object is required to have a value. Thus, callers are cautioned to assign a value after calling this constructor. Setting the identifier can be accomplished using the method setId().

Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
Compartment(long level, long version)

Creates a new Compartment object using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this Compartment
versiona long integer, the SBML Version to assign to this Compartment
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.ListOfCompartments.__init__ (   self,
  args 
)

A list of Compartment objects.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOfCompartments
__init__(SBMLNamespaces sbmlns)   ListOfCompartments

Each variant is described separately below.


Method variant with the following signature:
ListOfCompartments(SBMLNamespaces sbmlns)

Creates a new ListOfCompartments object.

The object is constructed such that it is valid for the SBML Level and Version combination determined by the SBMLNamespaces object in sbmlns.

Parameters
sbmlnsan SBMLNamespaces object that is used to determine the characteristics of the ListOfCompartments object to be created.

Method variant with the following signature:
ListOfCompartments(long level, long version)

Creates a new ListOfCompartments object.

The object is constructed such that it is valid for the given SBML Level and Version combination.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
def libsbml.Species.__init__ (   self,
  args 
)

An SBML species – a pool of entities.

A species in SBML refers to a pool of entities that (a) are considered indistinguishable from each other for the purposes of the model, (b) participate in reactions, and (c) are located in a specific compartment. The SBML Species object class is intended to represent these pools.

As with other major constructs in SBML, Species has a mandatory attribute, 'id', used to give the species type an identifier in the model. The identifier must be a text string conforming to the identifer syntax permitted in SBML. Species also has an optional 'name' attribute, of type string. The 'id' and 'name' must be used according to the guidelines described in the SBML specifications.

The required attribute 'compartment' is used to identify the compartment in which the species is located. The attribute's value must be the identifier of an existing Compartment object. It is important to note that there is no default value for the 'compartment' attribute on Species; every species in an SBML model must be assigned a compartment explicitly. (This also implies that every model with one or more Species objects must define at least one Compartment object.)

The initial amount and concentration of a species

The optional attributes 'initialAmount' and 'initialConcentration', both having a data type of float, can be used to set the initial quantity of the species in the compartment where the species is located. These attributes are mutually exclusive; i.e., only one can have a value on any given instance of a Species object. Missing 'initialAmount' and 'initialConcentration' values implies that their values either are unknown, or to be obtained from an external source, or determined by an InitialAssignment or other SBML construct elsewhere in the model.

A species' initial quantity in SBML is set by the 'initialAmount' or 'initialConcentration' attribute exactly once. If the 'constant' attribute is True, then the value of the species' quantity is fixed and cannot be changed except by an InitialAssignment. These methods differ in that the 'initialAmount' and 'initialConcentration' attributes can only be used to set the species quantity to a literal floating-point number, whereas the use of an InitialAssignment object allows the value to be set using an arbitrary mathematical expression (which, thanks to MathML's expressiveness, may evaluate to a rational number). If the species' 'constant' attribute is False, the species' quantity value may be overridden by an InitialAssignment or changed by AssignmentRule or AlgebraicRule, and in addition, for t > 0, it may also be changed by a RateRule, Event objects, and as a result of being a reactant or product in one or more Reaction objects. (However, some constructs are mutually exclusive; see the SBML specifications for the precise details.) It is not an error to define 'initialAmount' or 'initialConcentration' on a species and also redefine the value using an InitialAssignment, but the 'initialAmount' or 'initialConcentration' setting in that case is ignored. The SBML specifications provide additional information about the semantics of assignments, rules and values for simulation time t <= 0.

SBML Level 2 additionally stipulates that in cases where a species' compartment has a 'spatialDimensions' value of 0 (zero), the species cannot have a value for 'initialConcentration' because the concepts of concentration and density break down when a container has zero dimensions.

The units of a species' amount or concentration

When the attribute 'initialAmount' is set, the unit of measurement associated with the value of 'initialAmount' is specified by the Species attribute 'substanceUnits'. When the 'initialConcentration' attribute is set, the unit of measurement associated with this concentration value is {unit of amount} divided by {unit of size}, where the {unit of amount} is specified by the Species 'substanceUnits' attribute, and the {unit of size} is specified by the 'units' attribute of the Compartment object in which the species is located. Note that in either case, a unit of amount is involved and determined by the 'substanceUnits' attribute. Note these two attributes alone do not determine the units of the species when the species identifier appears in a mathematical expression; that aspect is determined by the attribute 'hasOnlySubstanceUnits' discussed below.

In SBML Level 3, if the 'substanceUnits' attribute is not set on a given Species object instance, then the unit of amount for that species is inherited from the 'substanceUnits' attribute on the enclosing Model object instance. If that attribute on Model is not set either, then the unit associated with the species' quantity is undefined.

In SBML Level 2, if the 'substanceUnits' attribute is not set on a given Species object instance, then the unit of amount for that species is taken from the predefined SBML unit identifier 'substance'. The value assigned to 'substanceUnits' must be chosen from one of the following possibilities: one of the base unit identifiers defined in SBML, the built-in unit identifier 'substance', or the identifier of a new unit defined in the list of unit definitions in the enclosing Model object. The chosen units for 'substanceUnits' must be be 'dimensionless', 'mole', 'item', 'kilogram', 'gram', or units derived from these.

As noted at the beginning of this section, simply setting 'initialAmount' or 'initialConcentration' alone does not determine whether a species identifier represents an amount or a concentration when it appears elsewhere in an SBML model. The role of the attribute 'hasOnlySubstanceUnits' is to indicate whether the units of the species, when the species identifier appears in mathematical formulas, are intended to be concentration or amount. The attribute takes on a boolean value. In SBML Level 3, the attribute has no default value and must always be set in a model; in SBML Level 2, it has a default value of False.

The units of the species are used in the following ways:

  • When the species' identifier appears in a MathML formula, it represents the species' quantity, and the unit of measurement associated with the quantity is as described above.

  • The 'math' elements of AssignmentRule, InitialAssignment and EventAssignment objects referring to this species should all have the same units as the unit of measurement associated with the species quantity.

  • In a RateRule object that defines the rate of change of the species' quantity, the unit associated with the rule's 'math' element should be equal to the unit of the species' quantity divided by the model-wide unit of time; in other words, {unit of species quantity}/{unit of time}.

The 'constant' and 'boundaryCondition' attributes

The Species object class has two boolean attributes named 'constant' and 'boundaryCondition', used to indicate whether and how the quantity of that species can vary during a simulation. In SBML Level 2 they are optional; in SBML Level 3 they are mandatory. The following table shows how to interpret the combined values of these attributes.

Interpretation of species' constant and boundaryCondition attributes.
constant
value
boundaryCondition
value
Can have
assignment
or rate rule?
Can be
reactant
or product?
Species' quantity
can be changed by
true true no yes (never changes)
false true yes yes rules and events
true false no no (never changes)
false false yes yes reactions or rules (but not both at the same time), and events

By default, when a species is a product or reactant of one or more reactions, its quantity is determined by those reactions. In SBML, it is possible to indicate that a given species' quantity is not determined by the set of reactions even when that species occurs as a product or reactant; i.e., the species is on the boundary of the reaction system, and its quantity is not determined by the reactions. The boolean attribute 'boundaryCondition' can be used to indicate this. A value of False indicates that the species is part of the reaction system. In SBML Level 2, the attribute has a default value of False, while in SBML Level 3, it has no default.

The 'constant' attribute indicates whether the species' quantity can be changed at all, regardless of whether by reactions, rules, or constructs other than InitialAssignment. A value of False indicates that the species' quantity can be changed. (This is also a common value because the purpose of most simulations is precisely to calculate changes in species quantities.) In SBML Level 2, the attribute has a default value of False, while in SBML Level 3, it has no default. Note that the initial quantity of a species can be set by an InitialAssignment irrespective of the value of the 'constant' attribute.

In practice, a 'boundaryCondition' value of True means a differential equation derived from the reaction definitions should not be generated for the species. However, the species' quantity may still be changed by AssignmentRule, RateRule, AlgebraicRule, Event, and InitialAssignment constructs if its 'constant' attribute is False. Conversely, if the species' 'constant' attribute is True, then its value cannot be changed by anything except InitialAssignment.

A species having 'boundaryCondition'=False and 'constant'=False can appear as a product and/or reactant of one or more reactions in the model. If the species is a reactant or product of a reaction, it must not also appear as the target of any AssignmentRule or RateRule object in the model. If instead the species has 'boundaryCondition'=False and 'constant'=True, then it cannot appear as a reactant or product, or as the target of any AssignmentRule, RateRule or EventAssignment object in the model.

The conversionFactor attribute in SBML Level 3

In SBML Level 3, Species has an additional optional attribute, 'conversionFactor', that defines a conversion factor that applies to a particular species. The value must be the identifier of a Parameter object instance defined in the model. That Parameter object must be a constant, meaning its 'constant' attribute must be set to True. If a given Species object definition defines a value for its 'conversionFactor' attribute, it takes precedence over any factor defined by the Model object's 'conversionFactor' attribute.

The unit of measurement associated with a species' quantity can be different from the unit of extent of reactions in the model. SBML Level 3 avoids implicit unit conversions by providing an explicit way to indicate any unit conversion that might be required. The use of a conversion factor in computing the effects of reactions on a species' quantity is explained in detail in the SBML Level 3 specification document. Because the value of the 'conversionFactor' attribute is the identifier of a Parameter object, and because parameters can have units attached to them, the transformation from reaction extent units to species units can be completely specified using this approach.

Note that the unit conversion factor is only applied when calculating the effect of a reaction on a species. It is not used in any rules or other SBML constructs that affect the species, and it is also not used when the value of the species is referenced in a mathematical expression.

The speciesType attribute in SBML Level 2 Versions 2–4

In SBML Level 2 Versions 2–4, each species in a model may optionally be designated as belonging to a particular species type. The optional attribute 'speciesType' is used to identify the species type of the chemical entities that make up the pool represented by the Species objects. The attribute's value must be the identifier of an existing SpeciesType object in the model. If the 'speciesType' attribute is not present on a particular species definition, it means the pool contains chemical entities of a type unique to that pool; in effect, a virtual species type is assumed for that species, and no other species can belong to that species type. The value of 'speciesType' attributes on species have no effect on the numerical interpretation of a model; simulators and other numerical analysis software may ignore 'speciesType' attributes.

There can be only one species of a given species type in any given compartment of a model. More specifically, for all Species objects having a value for the 'speciesType' attribute, the pair

('speciesType' attribute value, 'compartment' attribute value)

must be unique across the set of all Species object in a model.

The spatialSizeUnits attribute in SBML Level 2 Versions 1–2

In versions of SBML Level 2 before Version 3, the class Species included an attribute called 'spatialSizeUnits', which allowed explicitly setting the units of size for initial concentration. LibSBML retains this attribute for compatibility with older definitions of Level 2, but its use is strongly discouraged because many software tools do no properly interpret this unit declaration and it is incompatible with all SBML specifications after Level 2 Version 3.

Additional considerations for interpreting the numerical value of a species

Species are unique in SBML in that they have a kind of duality: a species identifier may stand for either substance amount (meaning, a count of the number of individual entities) or a concentration or density (meaning, amount divided by a compartment size). The previous sections explain the meaning of a species identifier when it is referenced in a mathematical formula or in rules or other SBML constructs; however, it remains to specify what happens to a species when the compartment in which it is located changes in size.

When a species definition has a 'hasOnlySubstanceUnits' attribute value of False and the size of the compartment in which the species is located changes, the default in SBML is to assume that it is the concentration that must be updated to account for the size change. This follows from the principle that, all other things held constant, if a compartment simply changes in size, the size change does not in itself cause an increase or decrease in the number of entities of any species in that compartment. In a sense, the default is that the amount of a species is preserved across compartment size changes. Upon such size changes, the value of the concentration or density must be recalculated from the simple relationship concentration = amount / size if the value of the concentration is needed (for example, if the species identifier appears in a mathematical formula or is otherwise referenced in an SBML construct). There is one exception: if the species' quantity is determined by an AssignmentRule, RateRule, AlgebraicRule, or an EventAssignment and the species has a 'hasOnlySubstanceUnits' attribute value of False, it means that the concentration is assigned by the rule or event; in that case, the amount must be calculated when the compartment size changes. (Events also require additional care in this situation, because an event with multiple assignments could conceivably reassign both a species quantity and a compartment size simultaneously. Please refer to the SBML specifications for the details.)

Note that the above only matters if a species has a 'hasOnlySubstanceUnits' attribute value of False, meaning that the species identifier refers to a concentration wherever the identifier appears in a mathematical formula. If instead the attribute's value is True, then the identifier of the species always stands for an amount wherever it appears in a mathematical formula or is referenced by an SBML construct. In that case, there is never a question about whether an assignment or event is meant to affect the amount or concentration: it is always the amount.

A particularly confusing situation can occur when the species has 'constant' attribute value of True in combination with a 'hasOnlySubstanceUnits' attribute value of False. Suppose this species is given a value for 'initialConcentration'. Does a 'constant' value of True mean that the concentration is held constant if the compartment size changes? No; it is still the amount that is kept constant across a compartment size change. The fact that the species was initialized using a concentration value is irrelevant.

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   Species
__init__(SBMLNamespaces sbmlns)   Species
__init__(Species orig)   Species

Each variant is described separately below.


Method variant with the following signature:
Species(SBMLNamespaces sbmlns)

Creates a new Species using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.

It is worth emphasizing that although this constructor does not take an identifier argument, in SBML Level 2 and beyond, the 'id' (identifier) attribute of a Species is required to have a value. Thus, callers are cautioned to assign a value after calling this constructor. Setting the identifier can be accomplished using the method Species.setId().

Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
Species(Species orig)

Copy constructor; creates a copy of this Species object.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
Species(long level, long version)

Creates a new Species using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this Species
versiona long integer, the SBML Version to assign to this Species
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.ListOfSpecies.__init__ (   self,
  args 
)

A list of Species objects.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOfSpecies
__init__(SBMLNamespaces sbmlns)   ListOfSpecies

Each variant is described separately below.


Method variant with the following signature:
ListOfSpecies(SBMLNamespaces sbmlns)

Creates a new ListOfSpecies object.

The object is constructed such that it is valid for the SBML Level and Version combination determined by the SBMLNamespaces object in sbmlns.

Parameters
sbmlnsan SBMLNamespaces object that is used to determine the characteristics of the ListOfSpecies object to be created.

Method variant with the following signature:
ListOfSpecies(long level, long version)

Creates a new ListOfSpecies object.

The object is constructed such that it is valid for the given SBML Level and Version combination.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
def libsbml.Parameter.__init__ (   self,
  args 
)

An SBML parameter: a named symbol with a value.

A Parameter is used in SBML to define a symbol associated with a value; this symbol can then be used in mathematical formulas in a model. By default, parameters have constant value for the duration of a simulation, and for this reason are called parameters instead of variables in SBML, although it is crucial to understand that SBML parameters represent both concepts. Whether a given SBML parameter is intended to be constant or variable is indicated by the value of its 'constant' attribute.

SBML's Parameter has a required attribute, 'id', that gives the parameter a unique identifier by which other parts of an SBML model definition can refer to it. A parameter can also have an optional 'name' attribute of type string. Identifiers and names must be used according to the guidelines described in the SBML specifications.

The optional attribute 'value' determines the value (of type float) assigned to the parameter. A missing value for 'value' implies that the value either is unknown, or to be obtained from an external source, or determined by an initial assignment. The unit of measurement associated with the value of the parameter can be specified using the optional attribute 'units'. Here we only mention briefly some notable points about the possible unit choices, but readers are urged to consult the SBML specification documents for more information:

  • In SBML Level 3, there are no constraints on the units that can be assigned to parameters in a model; there are also no units to inherit from the enclosing Model object (unlike the case for, e.g., Species and Compartment).

  • In SBML Level 2, the value assigned to the parameter's 'units' attribute must be chosen from one of the following possibilities: one of the base unit identifiers defined in SBML; one of the built-in unit identifiers 'substance', 'time', 'volume', 'area' or 'length'; or the identifier of a new unit defined in the list of unit definitions in the enclosing Model structure. There are no constraints on the units that can be chosen from these sets. There are no default units for parameters.

The Parameter structure has another boolean attribute named 'constant' that is used to indicate whether the parameter's value can vary during a simulation. (In SBML Level 3, the attribute is mandatory and must be given a value; in SBML Levels below Level 3, the attribute is optional.) A value of True indicates the parameter's value cannot be changed by any construct except InitialAssignment. Conversely, if the value of 'constant' is False, other constructs in SBML, such as rules and events, can change the value of the parameter.

SBML Level 3 uses a separate object class, LocalParameter, for parameters that are local to a Reaction's KineticLaw. In Levels prior to SBML Level 3, the Parameter class is used both for definitions of global parameters, as well as reaction-local parameters stored in a list within KineticLaw objects. Parameter objects that are local to a reaction (that is, those defined within the KineticLaw structure of a Reaction) cannot be changed by rules and therefore are implicitly always constant; consequently, in SBML Level 2, parameter definitions within Reaction structures should not have their 'constant' attribute set to False.

What if a global parameter has its 'constant' attribute set to False, but the model does not contain any rules, events or other constructs that ever change its value over time? Although the model may be suspect, this situation is not strictly an error. A value of False for 'constant' only indicates that a parameter can change value, not that it must.

As with all other major SBML components, Parameter is derived from SBase, and the methods defined on SBase are available on Parameter.

Note
The use of the term parameter in SBML sometimes leads to confusion among readers who have a particular notion of what something called 'parameter' should be. It has been the source of heated debate, but despite this, no one has yet found an adequate replacement term that does not have different connotations to different people and hence leads to confusion among some subset of users. Perhaps it would have been better to have two constructs, one called constants and the other called variables. The current approach in SBML is simply more parsimonious, using a single Parameter construct with the boolean flag 'constant' indicating which flavor it is. In any case, readers are implored to look past their particular definition of a parameter and simply view SBML's Parameter as a single mechanism for defining both constants and (additional) variables in a model. (We write additional because the species in a model are usually considered to be the central variables.) After all, software tools are not required to expose to users the actual names of particular SBML constructs, and thus tools can present to their users whatever terms their designers feel best matches their target audience.
See also
ListOfParameters

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   Parameter
__init__(SBMLNamespaces sbmlns)   Parameter
__init__(Parameter orig)   Parameter

Each variant is described separately below.


Method variant with the following signature:
Parameter(SBMLNamespaces sbmlns)

Creates a new Parameter using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.

It is worth emphasizing that although this constructor does not take an identifier argument, in SBML Level 2 and beyond, the 'id' (identifier) attribute of a Parameter is required to have a value. Thus, callers are cautioned to assign a value after calling this constructor if no identifier is provided as an argument. Setting the identifier can be accomplished using the method setId().

Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
Parameter(Parameter orig)

Copy constructor; creates a copy of a Parameter.

Parameters
origthe Parameter instance to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
Parameter(long level, long version)

Creates a new Parameter using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this Parameter
versiona long integer, the SBML Version to assign to this Parameter
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.ListOfParameters.__init__ (   self,
  args 
)

A list of Parameter objects.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOfParameters
__init__(SBMLNamespaces sbmlns)   ListOfParameters

Each variant is described separately below.


Method variant with the following signature:
ListOfParameters(SBMLNamespaces sbmlns)

Creates a new ListOfParameters object.

The object is constructed such that it is valid for the SBML Level and Version combination determined by the SBMLNamespaces object in sbmlns.

Parameters
sbmlnsan SBMLNamespaces object that is used to determine the characteristics of the ListOfParameters object to be created.

Method variant with the following signature:
ListOfParameters(long level, long version)

Creates a new ListOfParameters object.

The object is constructed such that it is valid for the given SBML Level and Version combination.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
def libsbml.LocalParameter.__init__ (   self,
  args 
)

A parameter inside an SBML reaction definition.

LocalParameter has been introduced in SBML Level 3 to serve as the object class for parameter definitions that are intended to be local to a Reaction. Objects of class LocalParameter never appear at the Model level; they are always contained within ListOfLocalParameters lists which are in turn contained within KineticLaw objects.

Like its global Parameter counterpart, the LocalParameter object class is used to define a symbol associated with a value; this symbol can then be used in a model's mathematical formulas (and specifically, for LocalParameter, reaction rate formulas). Unlike Parameter, the LocalParameter class does not have a 'constant' attribute: local parameters within reactions are always constant.

LocalParameter has one required attribute, 'id', to give the parameter a unique identifier by which other parts of an SBML model definition can refer to it. A parameter can also have an optional 'name' attribute of type string. Identifiers and names must be used according to the guidelines described in the SBML specifications.

The optional attribute 'value' determines the value (of type float) assigned to the parameter. A missing value for 'value' implies that the value either is unknown, or to be obtained from an external source, or determined by an initial assignment. The unit of measurement associated with the value of the parameter can be specified using the optional attribute 'units'. Here we only mention briefly some notable points about the possible unit choices, but readers are urged to consult the SBML specification documents for more information:

  • In SBML Level 3, there are no constraints on the units that can be assigned to parameters in a model; there are also no units to inherit from the enclosing Model object.

  • In SBML Level 2, the value assigned to the parameter's 'units' attribute must be chosen from one of the following possibilities: one of the base unit identifiers defined in SBML; one of the built-in unit identifiers 'substance', 'time', 'volume', 'area' or 'length'; or the identifier of a new unit defined in the list of unit definitions in the enclosing Model structure. There are no constraints on the units that can be chosen from these sets. There are no default units for local parameters.

As with all other major SBML components, LocalParameter is derived from SBase, and the methods defined on SBase are available on LocalParameter.

Warning
LibSBML derives LocalParameter from Parameter; however, this does not precisely match the object hierarchy defined by SBML Level 3, where LocalParameter is derived directly from SBase and not Parameter. We believe this arrangement makes it easier for libSBML users to program applications that work with both SBML Level 2 and SBML Level 3, but programmers should also keep in mind this difference exists. A side-effect of libSBML's scheme is that certain methods on LocalParameter that are inherited from Parameter do not actually have relevance to LocalParameter objects. An example of this is the methods pertaining to Parameter's attribute 'constant' (i.e., isSetConstant(), setConstant(), and getConstant()).
See also
ListOfLocalParameters
KineticLaw

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   LocalParameter
__init__(SBMLNamespaces sbmlns)   LocalParameter
__init__(LocalParameter orig)   LocalParameter
__init__(Parameter orig)   LocalParameter

Each variant is described separately below.


Method variant with the following signature:
LocalParameter(Parameter orig)

Copy constructor; creates a LocalParameter object by copying the attributes of a given Parameter object.

Parameters
origthe Parameter instance to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
LocalParameter(SBMLNamespaces sbmlns)

Creates a new LocalParameter object with the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.

It is worth emphasizing that although this constructor does not take an identifier argument, in SBML Level 2 and beyond, the 'id' (identifier) attribute of a LocalParameter is required to have a value. Thus, callers are cautioned to assign a value after calling this constructor if no identifier is provided as an argument. Setting the identifier can be accomplished using the method setId().

Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
LocalParameter(LocalParameter orig)

Copy constructor; creates a copy of a given LocalParameter object.

Parameters
origthe LocalParameter instance to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
LocalParameter(long level, long version)

Creates a new LocalParameter object with the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this LocalParameter.
versiona long integer, the SBML Version to assign to this LocalParameter.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.ListOfLocalParameters.__init__ (   self,
  args 
)

A list of LocalParameter objects.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOfLocalParameters
__init__(SBMLNamespaces sbmlns)   ListOfLocalParameters

Each variant is described separately below.


Method variant with the following signature:
ListOfLocalParameters(SBMLNamespaces sbmlns)

Creates a new ListOfLocalParameters object.

The object is constructed such that it is valid for the SBML Level and Version combination determined by the SBMLNamespaces object in sbmlns.

Parameters
sbmlnsan SBMLNamespaces object that is used to determine the characteristics of the ListOfLocalParameters object to be created.

Method variant with the following signature:
ListOfLocalParameters(long level, long version)

Creates a new ListOfLocalParameters object.

The object is constructed such that it is valid for the given SBML Level and Version combination.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
def libsbml.InitialAssignment.__init__ (   self,
  args 
)

An SBML initial assignment, evaluated once only.

SBML Level 2 Versions 2–4 and SBML Level 3 provide two ways of assigning initial values to entities in a model. The simplest and most basic is to set the values of the appropriate attributes in the relevant components; for example, the initial value of a model parameter (whether it is a constant or a variable) can be assigned by setting its 'value' attribute directly in the model definition. However, this approach is not suitable when the value must be calculated, because the initial value attributes on different components such as species, compartments, and parameters are single values and not mathematical expressions. In those situations, the InitialAssignment construct can be used; it permits the calculation of the value of a constant or the initial value of a variable from the values of other quantities in a model.

As explained below, the provision of InitialAssignment does not mean that models necessarily must use this construct when defining initial values of quantities in a model. If a value can be set directly using the relevant attribute of a component in a model, then that approach may be more efficient and more portable to other software tools. InitialAssignment should be used when the other mechanism is insufficient for the needs of a particular model.

The InitialAssignment construct has some similarities to AssignmentRule. The main differences are: (a) an InitialAssignment can set the value of a constant whereas an AssignmentRule cannot, and (b) unlike AssignmentRule, an InitialAssignment definition only applies up to and including the beginning of simulation time, i.e., t <= 0, while an AssignmentRule applies at all times.

InitialAssignment has a required attribute, 'symbol', whose value must follow the guidelines for identifiers described in the SBML specification (e.g., Section 3.3 in the Level 2 Version 4 specification). The value of this attribute in an InitialAssignment object can be the identifier of a Compartment, Species or global Parameter elsewhere in the model. The InitialAssignment defines the initial value of the constant or variable referred to by the 'symbol' attribute. (The attribute's name is 'symbol' rather than 'variable' because it may assign values to constants as well as variables in a model.) Note that an initial assignment cannot be made to reaction identifiers, that is, the 'symbol' attribute value of an InitialAssignment cannot be an identifier that is the 'id' attribute value of a Reaction object in the model. This is identical to a restriction placed on rules.

InitialAssignment also has a required 'math' subelement that contains a MathML expression used to calculate the value of the constant or the initial value of the variable. The units of the value computed by the formula in the 'math' subelement should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in previous Versions) be identical to be the units associated with the identifier given in the 'symbol' attribute. (That is, the units are the units of the species, compartment, or parameter, as appropriate for the kind of object identified by the value of 'symbol'.)

InitialAssignment was introduced in SBML Level 2 Version 2. It is not available in SBML Level 2 Version 1 nor in any version of Level 1.

Semantics of Initial Assignments

The value calculated by an InitialAssignment object overrides the value assigned to the given symbol by the object defining that symbol. For example, if a compartment's 'size' attribute is set in its definition, and the model also contains an InitialAssignment having that compartment's identifier as its 'symbol' attribute value, then the interpretation is that the 'size' assigned in the Compartment object should be ignored and the value assigned based on the computation defined in the InitialAssignment. Initial assignments can take place for Compartment, Species and global Parameter objects regardless of the value of their 'constant' attribute.

The actions of all InitialAssignment objects are in general terms the same, but differ in the precise details depending on the type of variable being set:

  • In the case of a species, an InitialAssignment sets the referenced species' initial quantity (concentration or amount of substance) to the value determined by the formula in the 'math' subelement. The overall units of the formula should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in previous Versions) be the same as the units specified for the species.

  • In the case of a compartment, an InitialAssignment sets the referenced compartment's initial size to the size determined by the formula in 'math'. The overall units of the formula should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in previous Versions) be the same as the units specified for the size of the compartment.

  • In the case of a parameter, an InitialAssignment sets the referenced parameter's initial value to that determined by the formula in 'math'. The overall units of the formula should (in SBML Level 2 Version 4 and SBML Level 3) or must (in previous Versions) be the same as the units defined for the parameter.

In the context of a simulation, initial assignments establish values that are in effect prior to and including the start of simulation time, i.e., t <= 0. Section 3.4.8 in the SBML Level 2 Version 4 and SBML Level 3 Version 1 Core specifications provides information about the interpretation of assignments, rules, and entity values for simulation time up to and including the start time t = 0; this is important for establishing the initial conditions of a simulation if the model involves expressions containing the delay 'csymbol'.

There cannot be two initial assignments for the same symbol in a model; that is, a model must not contain two or more InitialAssignment objects that both have the same identifier as their 'symbol' attribute value. A model must also not define initial assignments and assignment rules for the same entity. That is, there cannot be both an InitialAssignment and an AssignmentRule for the same symbol in a model, because both kinds of constructs apply prior to and at the start of simulated time—allowing both to exist for a given symbol would result in indeterminism).

The ordering of InitialAssignment objects is not significant. The combined set of InitialAssignment, AssignmentRule and KineticLaw objects form a set of assignment statements that must be considered as a whole. The combined set of assignment statements should not contain algebraic loops: a chain of dependency between these statements should terminate. (More formally, consider the directed graph of assignment statements where nodes are a model's assignment statements and directed arcs exist for each occurrence of a symbol in an assignment statement 'math' attribute. The directed arcs in this graph start from the statement assigning the symbol and end at the statement that contains the symbol in their math elements. Such a graph must be acyclic.)

Finally, it is worth being explicit about the expected behavior in the following situation. Suppose (1) a given symbol has a value x assigned to it in its definition, and (2) there is an initial assignment having the identifier as its 'symbol' value and reassigning the value to y, and (3) the identifier is also used in the mathematical formula of a second initial assignment. What value should the second initial assignment use? It is y, the value assigned to the symbol by the first initial assignment, not whatever value was given in the symbol's definition. This follows directly from the behavior described above: if an InitialAssignment object exists for a given symbol, then the symbol's value is overridden by that initial assignment.

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   InitialAssignment
__init__(SBMLNamespaces sbmlns)   InitialAssignment
__init__(InitialAssignment orig)   InitialAssignment

Each variant is described separately below.


Method variant with the following signature:
InitialAssignment(SBMLNamespaces sbmlns)

Creates a new InitialAssignment using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
InitialAssignment(InitialAssignment orig)

Copy constructor; creates a copy of this InitialAssignment.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
InitialAssignment(long level, long version)

Creates a new InitialAssignment using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this InitialAssignment
versiona long integer, the SBML Version to assign to this InitialAssignment
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.ListOfInitialAssignments.__init__ (   self,
  args 
)

A list of InitialAssignment objects.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOfInitialAssignments
__init__(SBMLNamespaces sbmlns)   ListOfInitialAssignments

Each variant is described separately below.


Method variant with the following signature:
ListOfInitialAssignments(SBMLNamespaces sbmlns)

Creates a new ListOfInitialAssignments object.

The object is constructed such that it is valid for the SBML Level and Version combination determined by the SBMLNamespaces object in sbmlns.

Parameters
sbmlnsan SBMLNamespaces object that is used to determine the characteristics of the ListOfInitialAssignments object to be created.

Method variant with the following signature:
ListOfInitialAssignments(long level, long version)

Creates a new ListOfInitialAssignments object.

The object is constructed such that it is valid for the given SBML Level and Version combination.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
def libsbml.ListOfRules.__init__ (   self,
  args 
)

A list of Rule objects.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOfRules
__init__(SBMLNamespaces sbmlns)   ListOfRules

Each variant is described separately below.


Method variant with the following signature:
ListOfRules(SBMLNamespaces sbmlns)

Creates a new ListOfRules object.

The object is constructed such that it is valid for the SBML Level and Version combination determined by the SBMLNamespaces object in sbmlns.

Parameters
sbmlnsan SBMLNamespaces object that is used to determine the characteristics of the ListOfRules object to be created.

Method variant with the following signature:
ListOfRules(long level, long version)

Creates a new ListOfRules object.

The object is constructed such that it is valid for the given SBML Level and Version combination.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
def libsbml.AlgebraicRule.__init__ (   self,
  args 
)

An SBML algebraic rule representing 0 = f(W).

The rule type AlgebraicRule is derived from the parent class Rule. It is used to express equations that are neither assignments of model variables nor rates of change. AlgebraicRule does not add any attributes to the basic Rule; its role is simply to distinguish this case from the other cases.

In the context of a simulation, algebraic rules are in effect at all times, t >= 0. For purposes of evaluating expressions that involve the delay 'csymbol' (see the SBML specification), algebraic rules are considered to apply also at t <= 0. Please consult the relevant SBML specification for additional information about the semantics of assignments, rules, and entity values for simulation time t <= 0.

An SBML model must not be overdetermined. The ability to define arbitrary algebraic expressions in an SBML model introduces the possibility that a model is mathematically overdetermined by the overall system of equations constructed from its rules, reactions and events. Therefore, if an algebraic rule is introduced in a model, for at least one of the entities referenced in the rule's 'math' element the value of that entity must not be completely determined by other constructs in the model. This means that at least this entity must not have the attribute 'constant'=True and there must also not be a rate rule or assignment rule for it. Furthermore, if the entity is a Species object, its value must not be determined by reactions, which means that it must either have the attribute 'boundaryCondition'=True or else not be involved in any reaction at all. These restrictions are explained in more detail in the SBML specification documents.

In SBML Levels 2 and 3, Reaction object identifiers can be referenced in the 'math' expression of an algebraic rule, but reaction rates can never be determined by algebraic rules. This is true even when a reaction does not contain a KineticLaw object. (In such cases of missing kinetic law definitions, the model is valid but incomplete; the rates of reactions lacking kinetic laws are simply undefined, and not determined by the algebraic rule.)

General summary of SBML rules

In SBML Level 3 as well as Level 2, rules are separated into three subclasses for the benefit of model analysis software. The three subclasses are based on the following three different possible functional forms (where x is a variable, f is some arbitrary function returning a numerical result, V is a vector of variables that does not include x, and W is a vector of variables that may include x):

Algebraic:left-hand side is zero0 = f(W)
Assignment:left-hand side is a scalar:x = f(V)
Rate:left-hand side is a rate-of-change:dx/dt = f(W)

In their general form given above, there is little to distinguish between assignment and algebraic rules. They are treated as separate cases for the following reasons:

  • Assignment rules can simply be evaluated to calculate intermediate values for use in numerical methods. They are statements of equality that hold at all times. (For assignments that are only performed once, see InitialAssignment.)
  • SBML needs to place restrictions on assignment rules, for example the restriction that assignment rules cannot contain algebraic loops.
  • Some simulators do not contain numerical solvers capable of solving unconstrained algebraic equations, and providing more direct forms such as assignment rules may enable those simulators to process models they could not process if the same assignments were put in the form of general algebraic equations;
  • Those simulators that can solve these algebraic equations make a distinction between the different categories listed above; and
  • Some specialized numerical analyses of models may only be applicable to models that do not contain algebraic rules.

The approach taken to covering these cases in SBML is to define an abstract Rule structure containing a subelement, 'math', to hold the right-hand side expression, then to derive subtypes of Rule that add attributes to distinguish the cases of algebraic, assignment and rate rules. The 'math' subelement must contain a MathML expression defining the mathematical formula of the rule. This MathML formula must return a numerical value. The formula can be an arbitrary expression referencing the variables and other entities in an SBML model.

Each of the three subclasses of Rule (AssignmentRule, AlgebraicRule, RateRule) inherit the the 'math' subelement and other fields from SBase. The AssignmentRule and RateRule classes add an additional attribute, 'variable'. See the definitions of AssignmentRule, AlgebraicRule and RateRule for details about the structure and interpretation of each one.

Additional restrictions on SBML rules

An important design goal of SBML rule semantics is to ensure that a model's simulation and analysis results will not be dependent on when or how often rules are evaluated. To achieve this, SBML needs to place two restrictions on rule use. The first concerns algebraic loops in the system of assignments in a model, and the second concerns overdetermined systems.

A model must not contain algebraic loops

The combined set of InitialAssignment, AssignmentRule and KineticLaw objects in a model constitute a set of assignment statements that should be considered as a whole. (A KineticLaw object is counted as an assignment because it assigns a value to the symbol contained in the 'id' attribute of the Reaction object in which it is defined.) This combined set of assignment statements must not contain algebraic loops—dependency chains between these statements must terminate. To put this more formally, consider a directed graph in which nodes are assignment statements and directed arcs exist for each occurrence of an SBML species, compartment or parameter symbol in an assignment statement's 'math' subelement. Let the directed arcs point from the statement assigning the symbol to the statements that contain the symbol in their 'math' subelement expressions. This graph must be acyclic.

SBML does not specify when or how often rules should be evaluated. Eliminating algebraic loops ensures that assignment statements can be evaluated any number of times without the result of those evaluations changing. As an example, consider the set of equations x = x + 1, y = z + 200 and z = y + 100. If this set of equations were interpreted as a set of assignment statements, it would be invalid because the rule for x refers to x (exhibiting one type of loop), and the rule for y refers to z while the rule for z refers back to y (exhibiting another type of loop). Conversely, the following set of equations would constitute a valid set of assignment statements: x = 10, y = z + 200, and z = x + 100.

A model must not be overdetermined

An SBML model must not be overdetermined; that is, a model must not define more equations than there are unknowns in a model. An SBML model that does not contain AlgebraicRule structures cannot be overdetermined.

LibSBML implements the static analysis procedure described in Appendix B of the SBML Level 3 Version 1 Core specification for assessing whether a model is overdetermined.

(In summary, assessing whether a given continuous, deterministic, mathematical model is overdetermined does not require dynamic analysis; it can be done by analyzing the system of equations created from the model. One approach is to construct a bipartite graph in which one set of vertices represents the variables and the other the set of vertices represents the equations. Place edges between vertices such that variables in the system are linked to the equations that determine them. For algebraic equations, there will be edges between the equation and each variable occurring in the equation. For ordinary differential equations (such as those defined by rate rules or implied by the reaction rate definitions), there will be a single edge between the equation and the variable determined by that differential equation. A mathematical model is overdetermined if the maximal matchings of the bipartite graph contain disconnected vertexes representing equations. If one maximal matching has this property, then all the maximal matchings will have this property; i.e., it is only necessary to find one maximal matching.)

Rule types for SBML Level 1

SBML Level 1 uses a different scheme than SBML Level 2 and Level 3 for distinguishing rules; specifically, it uses an attribute whose value is drawn from an enumeration of 3 values. LibSBML supports this using methods that work with the enumeration values listed below.

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   AlgebraicRule
__init__(SBMLNamespaces sbmlns)   AlgebraicRule

Each variant is described separately below.


Method variant with the following signature:
AlgebraicRule(SBMLNamespaces sbmlns)

Creates a new AlgebraicRule object using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
AlgebraicRule(long level, long version)

Creates a new AlgebraicRule object using the given SBML level and version values.

Parameters
levelthe SBML Level to assign to this AlgebraicRule object.
versionthe SBML Version to assign to this AlgebraicRule object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.AssignmentRule.__init__ (   self,
  args 
)

An SBML assignment rule representing x = f(Y).

The rule type AssignmentRule is derived from the parent class Rule. It is used to express equations that set the values of variables. The left-hand side (the attribute named 'variable') of an assignment rule can refer to the identifier of a Species, SpeciesReference (in SBML Level 3), Compartment, or Parameter object in the model (but not a Reaction). The entity identified must have its 'constant' attribute set to False. The effects of an assignment rule construct are in general terms the same, but differ in the precise details depending on the type of SBML component being set:

  • In the case of a species, an SBML assignment rule sets the referenced species' quantity (whether a 'concentration' or 'amount') to the value determined by the formula in the MathML subelement 'math'. The unit associated with the value produced by the 'math' formula should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in SBML releases prior to Level 2 version 4) be equal to the unit associated with the species' quantity. Restrictions: There must not be both an AssignmentRule 'variable' attribute and a SpeciesReference 'species' attribute having the same value in a model, unless the referenced Species object has its 'boundaryCondition' attribute set to True. In other words, an assignment rule cannot be defined for a species that is created or destroyed in a reaction unless that species is defined as a boundary condition in the model.

  • (For SBML Level 3 only) In the case of a species reference, an assignment rule sets the stoichiometry of the referenced reactant or product to the value determined by the formula in 'math'. The unit associated with the value produced by the 'math' formula should be consistent with the unit 'dimensionless', because reactant and product stoichiometries in reactions are dimensionless quantities.

  • In the case of a compartment, an SBML assignment rule sets the referenced compartment's size to the value determined by the formula in the 'math' subelement of the AssignmentRule object. The overall units of the formula in 'math' should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in SBML releases prior to Level 2 version 4) be the same as the units of the size of the compartment.

  • In the case of a parameter, an assignment rule sets the referenced parameter's value to that determined by the formula in the 'math' subelement of the AssignmentRule object. The overall units of the formula in the 'math' subelement should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in SBML releases prior to Level 2 version 4) be the same as the units defined for the parameter.

In the context of a simulation, assignment rules are in effect at all times, t >= 0. For purposes of evaluating expressions that involve the delay 'csymbol' (see the SBML Level 2 specification), assignment rules are considered to apply also at t <= 0. Please consult the relevant SBML specification for additional information about the semantics of assignments, rules, and entity values for simulation time t <= 0.

A model must not contain more than one AssignmentRule or RateRule object having the same value of 'variable'; in other words, in the set of all assignment rules and rate rules in an SBML model, each variable appearing in the left-hand sides can only appear once. This simply follows from the fact that an indeterminate system would result if a model contained more than one assignment rule for the same variable or both an assignment rule and a rate rule for the same variable.

Similarly, a model must also not contain both an AssignmentRule and an InitialAssignment definition for the same variable, because both kinds of constructs apply prior to and at the start of simulation time, i.e., t <= 0. If a model contained both an initial assignment and an assignment rule for the same variable, an indeterminate system would result.

The value calculated by an AssignmentRule object overrides the value assigned to the given symbol by the model component defining that symbol. For example, if a Compartment object's 'size' attribute value is set in its definition, and the model also contains an AssignmentRule object having that compartment's 'id' as its 'variable' value, then the 'size' assigned in the Compartment object definition is ignored and the value assigned based on the computation defined in the AssignmentRule. This does not mean that a definition for a given symbol can be omitted if there is an AssignmentRule object involving it. For example, there must be a Parameter object definition for a given parameter if there is an AssignmentRule definition for that parameter. It is only a question of which value definition takes precedence.

General summary of SBML rules

In SBML Level 3 as well as Level 2, rules are separated into three subclasses for the benefit of model analysis software. The three subclasses are based on the following three different possible functional forms (where x is a variable, f is some arbitrary function returning a numerical result, V is a vector of variables that does not include x, and W is a vector of variables that may include x):

Algebraic:left-hand side is zero0 = f(W)
Assignment:left-hand side is a scalar:x = f(V)
Rate:left-hand side is a rate-of-change:dx/dt = f(W)

In their general form given above, there is little to distinguish between assignment and algebraic rules. They are treated as separate cases for the following reasons:

  • Assignment rules can simply be evaluated to calculate intermediate values for use in numerical methods. They are statements of equality that hold at all times. (For assignments that are only performed once, see InitialAssignment.)
  • SBML needs to place restrictions on assignment rules, for example the restriction that assignment rules cannot contain algebraic loops.
  • Some simulators do not contain numerical solvers capable of solving unconstrained algebraic equations, and providing more direct forms such as assignment rules may enable those simulators to process models they could not process if the same assignments were put in the form of general algebraic equations;
  • Those simulators that can solve these algebraic equations make a distinction between the different categories listed above; and
  • Some specialized numerical analyses of models may only be applicable to models that do not contain algebraic rules.

The approach taken to covering these cases in SBML is to define an abstract Rule structure containing a subelement, 'math', to hold the right-hand side expression, then to derive subtypes of Rule that add attributes to distinguish the cases of algebraic, assignment and rate rules. The 'math' subelement must contain a MathML expression defining the mathematical formula of the rule. This MathML formula must return a numerical value. The formula can be an arbitrary expression referencing the variables and other entities in an SBML model.

Each of the three subclasses of Rule (AssignmentRule, AlgebraicRule, RateRule) inherit the the 'math' subelement and other fields from SBase. The AssignmentRule and RateRule classes add an additional attribute, 'variable'. See the definitions of AssignmentRule, AlgebraicRule and RateRule for details about the structure and interpretation of each one.

Additional restrictions on SBML rules

An important design goal of SBML rule semantics is to ensure that a model's simulation and analysis results will not be dependent on when or how often rules are evaluated. To achieve this, SBML needs to place two restrictions on rule use. The first concerns algebraic loops in the system of assignments in a model, and the second concerns overdetermined systems.

A model must not contain algebraic loops

The combined set of InitialAssignment, AssignmentRule and KineticLaw objects in a model constitute a set of assignment statements that should be considered as a whole. (A KineticLaw object is counted as an assignment because it assigns a value to the symbol contained in the 'id' attribute of the Reaction object in which it is defined.) This combined set of assignment statements must not contain algebraic loops—dependency chains between these statements must terminate. To put this more formally, consider a directed graph in which nodes are assignment statements and directed arcs exist for each occurrence of an SBML species, compartment or parameter symbol in an assignment statement's 'math' subelement. Let the directed arcs point from the statement assigning the symbol to the statements that contain the symbol in their 'math' subelement expressions. This graph must be acyclic.

SBML does not specify when or how often rules should be evaluated. Eliminating algebraic loops ensures that assignment statements can be evaluated any number of times without the result of those evaluations changing. As an example, consider the set of equations x = x + 1, y = z + 200 and z = y + 100. If this set of equations were interpreted as a set of assignment statements, it would be invalid because the rule for x refers to x (exhibiting one type of loop), and the rule for y refers to z while the rule for z refers back to y (exhibiting another type of loop). Conversely, the following set of equations would constitute a valid set of assignment statements: x = 10, y = z + 200, and z = x + 100.

A model must not be overdetermined

An SBML model must not be overdetermined; that is, a model must not define more equations than there are unknowns in a model. An SBML model that does not contain AlgebraicRule structures cannot be overdetermined.

LibSBML implements the static analysis procedure described in Appendix B of the SBML Level 3 Version 1 Core specification for assessing whether a model is overdetermined.

(In summary, assessing whether a given continuous, deterministic, mathematical model is overdetermined does not require dynamic analysis; it can be done by analyzing the system of equations created from the model. One approach is to construct a bipartite graph in which one set of vertices represents the variables and the other the set of vertices represents the equations. Place edges between vertices such that variables in the system are linked to the equations that determine them. For algebraic equations, there will be edges between the equation and each variable occurring in the equation. For ordinary differential equations (such as those defined by rate rules or implied by the reaction rate definitions), there will be a single edge between the equation and the variable determined by that differential equation. A mathematical model is overdetermined if the maximal matchings of the bipartite graph contain disconnected vertexes representing equations. If one maximal matching has this property, then all the maximal matchings will have this property; i.e., it is only necessary to find one maximal matching.)

Rule types for SBML Level 1

SBML Level 1 uses a different scheme than SBML Level 2 and Level 3 for distinguishing rules; specifically, it uses an attribute whose value is drawn from an enumeration of 3 values. LibSBML supports this using methods that work with the enumeration values listed below.

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   AssignmentRule
__init__(SBMLNamespaces sbmlns)   AssignmentRule

Each variant is described separately below.


Method variant with the following signature:
AssignmentRule(SBMLNamespaces sbmlns)

Creates a new AssignmentRule using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
AssignmentRule(long level, long version)

Creates a new AssignmentRule using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this AssignmentRule.
versiona long integer, the SBML Version to assign to this AssignmentRule.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.RateRule.__init__ (   self,
  args 
)

An SBML rate rule representing dx/dt = f(Y).

The rule type RateRule is derived from the parent class Rule. It is used to express equations that determine the rates of change of variables. The left-hand side (the 'variable' attribute) can refer to the identifier of a species, compartment, or parameter (but not a reaction). The entity identified must have its 'constant' attribute set to False. The effects of a RateRule are in general terms the same, but differ in the precise details depending on which variable is being set:

  • In the case of a species, a RateRule sets the rate of change of the species' quantity (concentration or amount of substance) to the value determined by the formula in the 'math' subelement of the RateRule object. The overall units of the formula in 'math' should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in SBML releases prior to Level 2 version 4) be equal to the unit of species quantity divided by the model-wide unit of time. Restrictions: There must not be both a RateRule 'variable' attribute and a SpeciesReference 'species' attribute having the same value, unless that species has its 'boundaryCondition' attribute is set to True. This means a rate rule cannot be defined for a species that is created or destroyed in a reaction, unless that species is defined as a boundary condition in the model.

  • (For SBML Level 3 only) In the case of a species reference, a RateRule sets the rate of change of the stoichiometry of the referenced reactant or product to the value determined by the formula in 'math'. The unit associated with the value produced by the 'math' formula should be consistent with the unit 'dimensionless' divided by the model-wide unit of time.

  • In the case of a compartment, a RateRule sets the rate of change of the compartment's size to the value determined by the formula in the 'math' subelement of the RateRule object. The overall units of the formula should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in SBML releases prior to Level 2 version 4) be the units of the compartment's size divided by the model-wide unit of time.

  • In the case of a parameter, a RateRule sets the rate of change of the parameter's value to that determined by the formula in the 'math' subelement of the RateRule object. The overall units of the formula should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in SBML releases prior to Level 2 version 4) be the Parameter object's 'unit' attribute value divided by the model-wide unit of time.

In the context of a simulation, rate rules are in effect for simulation time t < 0. Please consult the relevant SBML specification for additional information about the semantics of assignments, rules, and entity values for simulation time t <= 0.

As mentioned in the description of AssignmentRule, a model must not contain more than one RateRule or AssignmentRule object having the same value of 'variable'; in other words, in the set of all assignment rules and rate rules in an SBML model, each variable appearing in the left-hand sides can only appear once. This simply follows from the fact that an indeterminate system would result if a model contained more than one assignment rule for the same variable or both an assignment rule and a rate rule for the same variable.

General summary of SBML rules

In SBML Level 3 as well as Level 2, rules are separated into three subclasses for the benefit of model analysis software. The three subclasses are based on the following three different possible functional forms (where x is a variable, f is some arbitrary function returning a numerical result, V is a vector of variables that does not include x, and W is a vector of variables that may include x):

Algebraic:left-hand side is zero0 = f(W)
Assignment:left-hand side is a scalar:x = f(V)
Rate:left-hand side is a rate-of-change:dx/dt = f(W)

In their general form given above, there is little to distinguish between assignment and algebraic rules. They are treated as separate cases for the following reasons:

  • Assignment rules can simply be evaluated to calculate intermediate values for use in numerical methods. They are statements of equality that hold at all times. (For assignments that are only performed once, see InitialAssignment.)
  • SBML needs to place restrictions on assignment rules, for example the restriction that assignment rules cannot contain algebraic loops.
  • Some simulators do not contain numerical solvers capable of solving unconstrained algebraic equations, and providing more direct forms such as assignment rules may enable those simulators to process models they could not process if the same assignments were put in the form of general algebraic equations;
  • Those simulators that can solve these algebraic equations make a distinction between the different categories listed above; and
  • Some specialized numerical analyses of models may only be applicable to models that do not contain algebraic rules.

The approach taken to covering these cases in SBML is to define an abstract Rule structure containing a subelement, 'math', to hold the right-hand side expression, then to derive subtypes of Rule that add attributes to distinguish the cases of algebraic, assignment and rate rules. The 'math' subelement must contain a MathML expression defining the mathematical formula of the rule. This MathML formula must return a numerical value. The formula can be an arbitrary expression referencing the variables and other entities in an SBML model.

Each of the three subclasses of Rule (AssignmentRule, AlgebraicRule, RateRule) inherit the the 'math' subelement and other fields from SBase. The AssignmentRule and RateRule classes add an additional attribute, 'variable'. See the definitions of AssignmentRule, AlgebraicRule and RateRule for details about the structure and interpretation of each one.

Additional restrictions on SBML rules

An important design goal of SBML rule semantics is to ensure that a model's simulation and analysis results will not be dependent on when or how often rules are evaluated. To achieve this, SBML needs to place two restrictions on rule use. The first concerns algebraic loops in the system of assignments in a model, and the second concerns overdetermined systems.

A model must not contain algebraic loops

The combined set of InitialAssignment, AssignmentRule and KineticLaw objects in a model constitute a set of assignment statements that should be considered as a whole. (A KineticLaw object is counted as an assignment because it assigns a value to the symbol contained in the 'id' attribute of the Reaction object in which it is defined.) This combined set of assignment statements must not contain algebraic loops—dependency chains between these statements must terminate. To put this more formally, consider a directed graph in which nodes are assignment statements and directed arcs exist for each occurrence of an SBML species, compartment or parameter symbol in an assignment statement's 'math' subelement. Let the directed arcs point from the statement assigning the symbol to the statements that contain the symbol in their 'math' subelement expressions. This graph must be acyclic.

SBML does not specify when or how often rules should be evaluated. Eliminating algebraic loops ensures that assignment statements can be evaluated any number of times without the result of those evaluations changing. As an example, consider the set of equations x = x + 1, y = z + 200 and z = y + 100. If this set of equations were interpreted as a set of assignment statements, it would be invalid because the rule for x refers to x (exhibiting one type of loop), and the rule for y refers to z while the rule for z refers back to y (exhibiting another type of loop). Conversely, the following set of equations would constitute a valid set of assignment statements: x = 10, y = z + 200, and z = x + 100.

A model must not be overdetermined

An SBML model must not be overdetermined; that is, a model must not define more equations than there are unknowns in a model. An SBML model that does not contain AlgebraicRule structures cannot be overdetermined.

LibSBML implements the static analysis procedure described in Appendix B of the SBML Level 3 Version 1 Core specification for assessing whether a model is overdetermined.

(In summary, assessing whether a given continuous, deterministic, mathematical model is overdetermined does not require dynamic analysis; it can be done by analyzing the system of equations created from the model. One approach is to construct a bipartite graph in which one set of vertices represents the variables and the other the set of vertices represents the equations. Place edges between vertices such that variables in the system are linked to the equations that determine them. For algebraic equations, there will be edges between the equation and each variable occurring in the equation. For ordinary differential equations (such as those defined by rate rules or implied by the reaction rate definitions), there will be a single edge between the equation and the variable determined by that differential equation. A mathematical model is overdetermined if the maximal matchings of the bipartite graph contain disconnected vertexes representing equations. If one maximal matching has this property, then all the maximal matchings will have this property; i.e., it is only necessary to find one maximal matching.)

Rule types for SBML Level 1

SBML Level 1 uses a different scheme than SBML Level 2 and Level 3 for distinguishing rules; specifically, it uses an attribute whose value is drawn from an enumeration of 3 values. LibSBML supports this using methods that work with the enumeration values listed below.

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   RateRule
__init__(SBMLNamespaces sbmlns)   RateRule

Each variant is described separately below.


Method variant with the following signature:
RateRule(SBMLNamespaces sbmlns)

Creates a new RateRule using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
RateRule(long level, long version)

Creates a new RateRule using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this RateRule
versiona long integer, the SBML Version to assign to this RateRule
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.Constraint.__init__ (   self,
  args 
)

An SBML constraint, for stating validity assumptions.

The Constraint object class was introduced in SBML Level 2 Version 2 as a mechanism for stating the assumptions under which a model is designed to operate. The constraints are statements about permissible values of different quantities in a model. Constraints are not used to compute dynamical values for simulation or analysis, but rather, they serve an advisory role for simulation/analysis tools.

SBML's Constraint object class has one required attribute, 'id', to give the parameter a unique identifier by which other parts of an SBML model definition can refer to it. A Constraint object can also have an optional 'name' attribute of type string. Identifiers and names must be used according to the guidelines described in the SBML specification (e.g., Section 3.3 in the Level 2 Version 4 specification).

Constraint has one required subelement, 'math', containing a MathML formula defining the condition of the constraint. This formula must return a boolean value of True when the model is a valid state. The formula can be an arbitrary expression referencing the variables and other entities in an SBML model. The evaluation of 'math' and behavior of constraints are described in more detail below.

A Constraint structure also has an optional subelement called 'message'. This can contain a message in XHTML format that may be displayed to the user when the condition of the formula in the 'math' subelement evaluates to a value of False. Software tools are not required to display the message, but it is recommended that they do so as a matter of best practice. The XHTML content within a 'message' subelement must follow the same restrictions as for the 'notes' element on SBase described in in the SBML Level 2 specification; please consult the SBML specification document corresponding to the SBML Level and Version of your model for more information about the requirements for 'notes' content.

Constraint was introduced in SBML Level 2 Version 2. It is not available in earlier versions of Level 2 nor in any version of Level 1.

Semantics of Constraints

In the context of a simulation, a Constraint has effect at all times t >= 0. Each Constraint's 'math' subelement is first evaluated after any InitialAssignment definitions in a model at t = 0 and can conceivably trigger at that point. (In other words, a simulation could fail a constraint immediately.)

Constraint structures cannot and should not be used to compute the dynamical behavior of a model as part of, for example, simulation. Constraints may be used as input to non-dynamical analysis, for instance by expressing flux constraints for flux balance analysis.

The results of a simulation of a model containing a constraint are invalid from any simulation time at and after a point when the function given by the 'math' subelement returns a value of False. Invalid simulation results do not make a prediction of the behavior of the biochemical reaction network represented by the model. The precise behavior of simulation tools is left undefined with respect to constraints. If invalid results are detected with respect to a given constraint, the 'message' subelement may optionally be displayed to the user. The simulation tool may also halt the simulation or clearly delimit in output data the simulation time point at which the simulation results become invalid.

SBML does not impose restrictions on duplicate Constraint definitions or the order of evaluation of Constraint objects in a model. It is possible for a model to define multiple constraints all with the same mathematical expression. Since the failure of any constraint indicates that the model simulation has entered an invalid state, a system is not required to attempt to detect whether other constraints in the model have failed once any one constraint has failed.

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   Constraint
__init__(SBMLNamespaces sbmlns)   Constraint
__init__(Constraint orig)   Constraint

Each variant is described separately below.


Method variant with the following signature:
Constraint(SBMLNamespaces sbmlns)

Creates a new Constraint using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
Constraint(Constraint orig)

Copy constructor; creates a copy of this Constraint.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
Constraint(long level, long version)

Creates a new Constraint using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this Constraint
versiona long integer, the SBML Version to assign to this Constraint
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.ListOfConstraints.__init__ (   self,
  args 
)

A list of Constraint objects.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOfConstraints
__init__(SBMLNamespaces sbmlns)   ListOfConstraints

Each variant is described separately below.


Method variant with the following signature:
ListOfConstraints(SBMLNamespaces sbmlns)

Creates a new ListOfConstraints object.

The object is constructed such that it is valid for the SBML Level and Version combination determined by the SBMLNamespaces object in sbmlns.

Parameters
sbmlnsan SBMLNamespaces object that is used to determine the characteristics of the ListOfConstraints object to be created.

Method variant with the following signature:
ListOfConstraints(long level, long version)

Creates a new ListOfConstraints object.

The object is constructed such that it is valid for the given SBML Level and Version combination.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
def libsbml.Reaction.__init__ (   self,
  args 
)

An SBML reaction between species in an SBML model.

A reaction represents any transformation, transport or binding process, typically a chemical reaction, that can change the quantity of one or more species. In SBML, a reaction is defined primarily in terms of the participating reactants and products (and their corresponding stoichiometries), along with optional modifier species, an optional rate at which the reaction takes place, and optional parameters.

As with other major objects in SBML, Reaction has a mandatory attribute, 'id', used to give the compartment type an identifier. The identifier must be a text string conforming to the identifer syntax permitted in SBML. In SBML Level 2 and Level 3, the reaction 'id' identifier can be used in mathematical formulas elsewhere in an SBML model to represent the rate of that reaction; this usage is explained below. Reaction also has an optional 'name' attribute, of type string. The 'id' and 'name' must be used according to the guidelines described in the SBML specification.

The species participating as reactants, products, and/or modifiers in a reaction are declared using lists of SpeciesReference and/or ModifierSpeciesReference instances stored in subelements 'listOfReactants', 'listOfProducts' and 'listOfModifiers'. Certain restrictions are placed on the appearance of species in reaction definitions:

  • The ability of a species to appear as a reactant or product of any reaction in a model is governed by certain flags in that species' definition; see the definition of Species for more information.

  • Any species appearing in the mathematical formula of the subelement 'kineticLaw' (described below) of a Reaction must be declared in at least one of that Reaction's lists of reactants, products, and/or modifiers. Put another way, it is an error for a reaction's kinetic law formula to refer to species that have not been declared for that reaction.

  • A reaction definition can contain an empty list of reactants or an empty list of products, but it must have at least one reactant or product; in other words, a reaction without any reactant or product species is not permitted. (This restriction does not apply to modifier species, which remain optional in all cases.)

A reaction can contain up to one KineticLaw object in a subelement named 'kineticLaw'. It defines the speed at which the process defined by the reaction takes place. The description of KineticLaw provides more details about its use. Note that although the inclusion of a KineticLaw object in an instance of a Reaction component is optional, there is no useful default that can be substituted in place of a missing rate expression in a reaction. Moreover, a reaction's rate cannot be defined in any other way in SBML—InitialAssignment, AssignmentRule, RateRule, AlgebraicRule, Event, and other constructs in SBML cannot be used to set the reaction rate separately. Nevertheless, for some modeling applications, reactions without any defined rate can be perfectly acceptable.

Reaction also has a boolean attribute named 'reversible' for indicating whether the reaction is reversible. This attribute is optional in SBML Level 2, with a default of True; it is mandatory in SBML Level 3 (with no default value). To say that a reaction is reversible is to say it can proceed in either the forward or the reverse direction. Although the reversibility of a reaction can sometimes be deduced by inspecting its rate expression, this is not always the case, especially for complicated expressions. Moreover, the need in SBML to allow rate expressions (i.e., KineticLaw) to be optional leads to the need for a separate flag indicating reversibility. Note that labeling a reaction as irreversible is an assertion that the reaction always proceeds in the given forward direction. (Why else would it be flagged as irreversible?) This implies the rate expression in the KineticLaw always has a non-negative value during simulations. Software tools could provide a means of optionally testing that this condition holds. The presence of reversibility information in two places (i.e., the rate expression and the 'reversible' attribute on Reaction) leaves open the possibility that a model could contain contradictory information, but the creation of such a model would be an error on the part of the software generating it.

The Reaction object class has another boolean attribute called 'fast'. This attribute is optional in SBML Level 2, with a default of False; it is mandatory in SBML Level 3 (with no default value). It is used to indicate that a reaction occurs on a vastly faster time scale than others in a system. Readers are directed to the SBML Level 2 Version 4 specification, which provides more detail about the conditions under which a reaction can be considered to be fast in this sense. The attribute's default value is False. SBML Level 1 and Level 2 Version 1 incorrectly claimed that software tools could ignore this attribute if they did not implement support for the corresponding concept; however, further research in SBML has revealed that this is not true, and 'fast' cannot be ignored if it is set to True. SBML Level 2 Versions 2–4 therefore stipulate that if a model has any reactions with 'fast' set to True, a software tool must be able to respect the attribute or else indicate to the user that it does not have the capacity to do so. Analysis software cannot ignore the value of the 'fast' attribute because doing so may lead to different results as compared to a software system that does make use of 'fast'.

In SBML Level 3 Version 1, the Reaction object has an additional optional attribute named 'compartment', whose value must be the identifier of a compartment defined in the enclosing Model object. The 'compartment' attribute can be used to indicate the compartment in which the reaction is assumed to take place. If the attribute is present, its value must be the identifier of a Compartment object defined in the enclosing Model object. Similar to the 'reversible' attribute, the value of the 'compartment' attribute has no direct impact on the construction of mathematical equations for the SBML model. When a kinetic law is given for a reaction, the compartment location may already be implicit in the kinetic law (although this cannot always be guaranteed). Nevertheless, software tools may find the 'compartment' attribute value useful for such purposes as analyzing the structure of the model, guiding the modeler in constructing correct rate formulas, and visualization purposes.

Readers are urged to read the SBML specification for more details about the proper use of Reaction.

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   Reaction
__init__(SBMLNamespaces sbmlns)   Reaction
__init__(Reaction orig)   Reaction

Each variant is described separately below.


Method variant with the following signature:
Reaction(SBMLNamespaces sbmlns)

Creates a new Reaction using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
Reaction(Reaction orig)

Copy constructor; creates a copy of this Reaction.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
Reaction(long level, long version)

Creates a new Reaction using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this Reaction
versiona long integer, the SBML Version to assign to this Reaction
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.ListOfReactions.__init__ (   self,
  args 
)

A list of Reaction objects.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOfReactions
__init__(SBMLNamespaces sbmlns)   ListOfReactions

Each variant is described separately below.


Method variant with the following signature:
ListOfReactions(SBMLNamespaces sbmlns)

Creates a new ListOfReactions object.

The object is constructed such that it is valid for the SBML Level and Version combination determined by the SBMLNamespaces object in sbmlns.

Parameters
sbmlnsan SBMLNamespaces object that is used to determine the characteristics of the ListOfReactions object to be created.

Method variant with the following signature:
ListOfReactions(long level, long version)

Creates a new ListOfReactions object.

The object is constructed such that it is valid for the given SBML Level and Version combination.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
def libsbml.KineticLaw.__init__ (   self,
  args 
)

The rate expression for an SBML reaction.

An object of class KineticLaw is used to describe the rate at which the process defined by a given Reaction takes place. KineticLaw has subelements called 'math' (for MathML content) and 'listOfParameters' (of class ListOfParameters), in addition to the attributes and subelements it inherits from SBase.

KineticLaw's 'math' subelement for holding a MathML formula defines the rate of the reaction. The formula may refer to other entities in a model as well as local parameter definitions within the scope of the Reaction (see below). It is important to keep in mind, however, that the only Species identifiers that can be used in this formula are those declared in the lists of reactants, products and modifiers in the Reaction structure. (In other words, before a species can be referenced in the KineticLaw, it must be declared in one of those lists.)

KineticLaw provides a way to define local parameters whose identifiers can be used in the 'math' formula of that KineticLaw instance. Prior to SBML Level 3, these parameter definitions are stored inside a 'listOfParameters' subelement containing Parameter objects; in SBML Level 3, this is achieved using a specialized object class called LocalParameter and the containing subelement is called 'listOfLocalParameters'. In both cases, the parameters so defined are only visible within the KineticLaw; they cannot be accessed outside. A local parameter within one reaction is not visible from within another reaction, nor is it visible to any other construct outside of the KineticLaw in which it is defined. In addition, another important feature is that if such a Parameter (or in Level 3, LocalParameter) object has the same identifier as another object in the scope of the enclosing Model, the definition inside the KineticLaw takes precedence. In other words, within the KineticLaw's 'math' formula, references to local parameter identifiers shadow any identical global identifiers.

The values of local parameters defined within KineticLaw objects cannot change. In SBML Level 3, this quality is built into the LocalParameter construct. In Level 2, where the same kind of Parameter object class is used as for global parameters, the Parameter objects' 'constant' attribute must always have a value of True (either explicitly or left to its default value).

A warning about identifier shadowing

A common misconception is that different classes of objects (e.g., species, compartments, parameters) in SBML have different identifier scopes. They do not. The implication is that if a KineticLaw's local parameter definition uses an identifier identical to any other identifier defined in the model outside the KineticLaw, even if the other identifier does not belong to a parameter type of object, the local parameter's identifier takes precedence within that KineticLaw's 'math' formula. It is not an error in SBML for identifiers to shadow each other this way, but can lead to confusing and subtle errors.

SBML Level/Version differences

In SBML Level 2 Version 1, the SBML specification included two additional attributes on KineticLaw called 'substanceUnits' and 'timeUnits'. They were removed beginning with SBML Level 2 Version 2 because further research determined they introduced many problems. The most significant problem was that their use could easily lead to the creation of valid models whose reactions nevertheless could not be integrated into a system of equations without outside knowledge for converting the quantities used. Examination of real-life models revealed that a common reason for using 'substanceUnits' on KineticLaw was to set the units of all reactions to the same set of substance units, something that is better achieved by using UnitDefinition to redefine 'substance' for the whole Model.

As mentioned above, in SBML Level 2 Versions 2–4, local parameters are of class Parameter. In SBML Level 3, the class of object is LocalParameter.

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   KineticLaw
__init__(SBMLNamespaces sbmlns)   KineticLaw
__init__(KineticLaw orig)   KineticLaw

Each variant is described separately below.


Method variant with the following signature:
KineticLaw(KineticLaw orig)

Copy constructor; creates a copy of this KineticLaw.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
KineticLaw(SBMLNamespaces sbmlns)

Creates a new KineticLaw using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
KineticLaw(long level, long version)

Creates a new KineticLaw using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this KineticLaw
versiona long integer, the SBML Version to assign to this KineticLaw
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.SpeciesReference.__init__ (   self,
  args 
)

A reference to an SBML species in a reaction.

The Reaction structure provides a way to express which species act as reactants and which species act as products in a reaction. In a given reaction, references to those species acting as reactants and/or products are made using instances of SpeciesReference structures in a Reaction object's lists of reactants and products.

A species can occur more than once in the lists of reactants and products of a given Reaction instance. The effective stoichiometry for a species in a reaction is the sum of the stoichiometry values given on the SpeciesReference object in the list of products minus the sum of stoichiometry values given on the SpeciesReference objects in the list of reactants. A positive value indicates the species is effectively a product and a negative value indicates the species is effectively a reactant. SBML places no restrictions on the effective stoichiometry of a species in a reaction; for example, it can be zero. In the following SBML fragment, the two reactions have the same effective stoichiometry for all their species:

 <reaction id='x'>
 <listOfReactants>
     <speciesReference species='a'/>
     <speciesReference species='a'/>
     <speciesReference species='b'/>
 </listOfReactants>
 <listOfProducts>
     <speciesReference species='c'/>
     <speciesReference species='b'/>
 </listProducts>
 </reaction>
 <reaction id='y'>
 <listOfReactants>
     <speciesReference species='a' stoichiometry='2'/>
 </listOfReactants>
 <listOfProducts>
     <speciesReference species='c'/>
 </listProducts>
 </reaction>

The precise structure of SpeciesReference differs between SBML Level 2 and Level 3. We discuss the two variants in separate sections below.

SpeciesReference in SBML Level 2

The mandatory 'species' attribute of SpeciesReference must have as its value the identifier of an existing species defined in the enclosing Model. The species is thereby designated as a reactant or product in the reaction. Which one it is (i.e., reactant or product) is indicated by whether the SpeciesReference appears in the Reaction's 'reactant' or 'product' lists.

Product and reactant stoichiometries can be specified using either 'stoichiometry' or 'stoichiometryMath' in a SpeciesReference object. The 'stoichiometry' attribute is of type float and should contain values greater than zero (0). The 'stoichiometryMath' element is implemented as an element containing a MathML expression. These two are mutually exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should be defined in a given SpeciesReference instance. When neither the attribute nor the element is present, the value of 'stoichiometry' in the SpeciesReference instance defaults to 1.

For maximum interoperability, the 'stoichiometry' attribute should be used in preference to 'stoichiometryMath' when a species' stoichiometry is a simple scalar number (integer or decimal). When the stoichiometry is a rational number, or when it is a more complicated formula, 'stoichiometryMath' must be used. The MathML expression in 'stoichiometryMath' may also refer to identifiers of entities in a model (except reaction identifiers). However, the only species identifiers that can be used in 'stoichiometryMath' are those referenced in the Reaction list of reactants, products and modifiers.

The following is a simple example of a species reference for species X0, with stoichiometry 2, in a list of reactants within a reaction having the identifier J1:

 <model>
 ...
 <listOfReactions>
     <reaction id='J1'>
         <listOfReactants>
             <speciesReference species='X0' stoichiometry='2'>
         </listOfReactants>
         ...
     </reaction>
     ...
 </listOfReactions>
 ...
 </model>

The following is a more complex example of a species reference for species X0, with a stoichiometry formula consisting of the parameter x:

 <model>
 ...
 <listOfReactions>
     <reaction id='J1'>
         <listOfReactants>
             <speciesReference species='X0'>
                 <stoichiometryMath>
                     <math xmlns='http://www.w3.org/1998/Math/MathML'>
                         <ci>x</ci>
                     </math>
                 </stoichiometryMath>
             </speciesReference>
         </listOfReactants>
         ...
     </reaction>
     ...
 </listOfReactions>
 ...
 </model>

SpeciesReference in SBML Level 3

In Level 2's definition of a reaction, the stoichiometry attribute of a SpeciesReference is actually a combination of two factors, the standard biochemical stoichiometry and a conversion factor that may be needed to translate the units of the species quantity to the units of the reaction rate. Unfortunately, Level 2 offers no direct way of decoupling these two factors, or for explicitly indicating the units. The only way to do it in Level 2 is to use the StoichiometryMath object associated with SpeciesReferences, and to reference SBML Parameter objects from within the StoichiometryMath formula. This works because Parameter offers a way to attach units to a numerical value, but the solution is indirect and awkward for something that should be a simple matter. Moreover, the question of how to properly encode stoichiometries in SBML reactions has caused much confusion among implementors of SBML software.

SBML Level 3 approaches this problem differently. It (1) extends the the use of the SpeciesReference identifier to represent the value of the 'stoichiometry' attribute, (2) makes the 'stoichiometry' attribute optional, (3) removes StoichiometryMath, and (4) adds a new 'constant' boolean attribute on SpeciesReference.

As in Level 2, the 'stoichiometry' attribute is of type float and should contain values greater than zero (0). A missing 'stoichiometry' implies that the stoichiometry is either unknown, or to be obtained from an external source, or determined by an InitialAssignment object or other SBML construct elsewhere in the model.

A species reference's stoichiometry is set by its 'stoichiometry' attribute exactly once. If the SpeciesReference object's 'constant' attribute has the value True, then the stoichiometry is fixed and cannot be changed except by an InitialAssignment object. These two methods of setting the stoichiometry (i.e., using 'stoichiometry' directly, or using InitialAssignment) differ in that the 'stoichiometry' attribute can only be set to a literal floating-point number, whereas InitialAssignment allows the value to be set using an arbitrary mathematical expression. (As an example, the approach could be used to set the stoichiometry to a rational number of the form p/q, where p and q are integers, something that is occasionally useful in the context of biochemical reaction networks.) If the species reference's 'constant' attribute has the value False, the species reference's value may be overridden by an InitialAssignment or changed by AssignmentRule or AlgebraicRule, and in addition, for simulation time t > 0, it may also be changed by a RateRule or Event objects. (However, some of these constructs are mutually exclusive; see the SBML Level 3 Version 1 Core specifiation for more details.) It is not an error to define 'stoichiometry' on a species reference and also redefine the stoichiometry using an InitialAssignment, but the 'stoichiometry' attribute in that case is ignored.

The value of the 'id' attribute of a SpeciesReference can be used as the content of a <ci> element in MathML formulas elsewhere in the model. When the identifier appears in a MathML <ci> element, it represents the stoichiometry of the corresponding species in the reaction where the SpeciesReference object instance appears. More specifically, it represents the value of the 'stoichiometry' attribute on the SpeciesReference object.

In SBML Level 3, the unit of measurement associated with the value of a species' stoichiometry is always considered to be dimensionless. This has the following implications:

  • When a species reference's identifier appears in mathematical formulas elsewhere in the model, the unit associated with that value is dimensionless.

  • The units of the 'math' elements of AssignmentRule, InitialAssignment and EventAssignment objects setting the stoichiometry of the species reference should be dimensionless.

  • If a species reference's identifier is the subject of a RateRule, the unit associated with the RateRule object's value should be dimensionless/time, where time is the model-wide unit of time set on the Model object.

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   SpeciesReference
__init__(SBMLNamespaces sbmlns)   SpeciesReference
__init__(SpeciesReference orig)   SpeciesReference

Each variant is described separately below.


Method variant with the following signature:
SpeciesReference(SBMLNamespaces sbmlns)

Creates a new SpeciesReference using the given SBMLNamespaces object sbmlns.

Parameters
sbmlnsan SBMLNamespaces object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
SpeciesReference(long level, long version)

Creates a new SpeciesReference using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this SpeciesReference
versiona long integer, the SBML Version to assign to this SpeciesReference
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
SpeciesReference(SpeciesReference orig)

Copy constructor; creates a copy of this SpeciesReference.

Parameters
origthe SpeciesReference instance to copy.
Exceptions
ValueErrorThrown if the argument orig is None.
def libsbml.ListOfSpeciesReferences.__init__ (   self,
  args 
)

A list of SpeciesReference objects.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOfSpeciesReferences
__init__(SBMLNamespaces sbmlns)   ListOfSpeciesReferences

Each variant is described separately below.


Method variant with the following signature:
ListOfSpeciesReferences(SBMLNamespaces sbmlns)

Creates a new ListOfSpeciesReferences object.

The object is constructed such that it is valid for the SBML Level and Version combination determined by the SBMLNamespaces object in sbmlns.

Parameters
sbmlnsan SBMLNamespaces object that is used to determine the characteristics of the ListOfSpeciesReferences object to be created.

Method variant with the following signature:
ListOfSpeciesReferences(long level, long version)

Creates a new, empty ListOfSpeciesReferences object.

The object is constructed such that it is valid for the given SBML Level and Version combination.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
def libsbml.ModifierSpeciesReference.__init__ (   self,
  args 
)

A reference to an SBML modifier species.

Sometimes a species appears in the kinetic rate formula of a reaction but is itself neither created nor destroyed in that reaction (for example, because it acts as a catalyst or inhibitor). In SBML, all such species are simply called modifiers without regard to the detailed role of those species in the model. The Reaction structure provides a way to express which species act as modifiers in a given reaction. This is the purpose of the list of modifiers available in Reaction. The list contains instances of ModifierSpeciesReference structures.

The ModifierSpeciesReference structure inherits the mandatory attribute 'species' and optional attributes 'id' and 'name' from the parent class SimpleSpeciesReference. See the description of SimpleSpeciesReference for more information about these.

The value of the 'species' attribute must be the identifier of a species defined in the enclosing Model; this species is designated as a modifier for the current reaction. A reaction may have any number of modifiers. It is permissible for a modifier species to appear simultaneously in the list of reactants and products of the same reaction where it is designated as a modifier, as well as to appear in the list of reactants, products and modifiers of other reactions in the model.

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ModifierSpeciesReference
__init__(SBMLNamespaces sbmlns)   ModifierSpeciesReference

Each variant is described separately below.


Method variant with the following signature:
ModifierSpeciesReference(SBMLNamespaces sbmlns)

Creates a new ModifierSpeciesReference using the given SBMLNamespaces object sbmlns.

Parameters
sbmlnsan SBMLNamespaces object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
ModifierSpeciesReference(long level, long version)

Creates a new ModifierSpeciesReference using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this ModifierSpeciesReference
versiona long integer, the SBML Version to assign to this ModifierSpeciesReference
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.Event.__init__ (   self,
  args 
)

A discontinuous SBML event.

An SBML Event object defines when the event can occur, the variables that are affected by it, how the variables are affected, and the event's relationship to other events. The effect of the event can optionally be delayed after the occurrence of the condition which invokes it.

The operation of Event is divided into two phases (even when the event is not delayed): one when the event is triggered, and the other when the event is executed. Trigger objects define the conditions for triggering an event, Delay objects define when the event is actually executed, EventAssignment objects define the effects of executing the event, and (in SBML Level 3) Priority objects influence the order of EventAssignment performance in cases of simultaneous events. Please consult the descriptions of Trigger, Delay, EventAssignment and Priority for more information.

SBML Level/Version differences

SBML Level 3

SBML Level 3 introduces several changes to the structure and components of Events compared to SBML Level 2. These changes fall into two main categories: changes to what is optional or required, and additions of new attributes and elements.

  • The attribute 'useValuesFromTriggerTime' on Event is mandatory (it was optional in Level 2);
  • Event's 'listOfEventAssignments' element (of class ListOfEventAssignments) is optional (it was mandatory in Level 2);
  • Event's 'priority' element (of class Priority) is new in Level 3; and
  • The Trigger object gains new mandatory attributes (described as part of the definition of Trigger).

The changes to the attributes of Event are described below; the changes to Trigger and Priority are described in their respective sections.

SBML Level 2

In SBML Level 2 versions before Version 4, the semantics of Event time delays were defined such that the expressions in the event's assignments were always evaluated at the time the event was triggered. This definition made it difficult to define an event whose assignment formulas were meant to be evaluated at the time the event was executed (i.e., after the time period defined by the value of the Delay element). In SBML Level 2 Version 4 and in Level 3, the attribute 'useValuesFromTriggerTime' on Event allows a model to indicate the time at which the event's assignments are intended the values of the assignment formulas are computed at the moment the event is triggered, not after the delay. If 'useValuesFromTriggerTime'=False, it means that the formulas in the event's assignments are to be computed after the delay, at the time the event is executed.

The definition of Event in SBML Level 2 Versions 1 and 2 includes an additional attribute called 'timeUnits', which allowed the time units of the Delay to be set explicitly. Later Versions of SBML Level 2 as well as SBML Level 3 do not define this attribute. LibSBML supports this attribute for compatibility with previous versions of SBML Level 2; however, if a model in SBML Level 3 or Level 2 Versions 3–4 format sets the attribute, the consistency-checking method SBMLDocument.checkConsistency() will report an error.

The attribute 'useValuesFromTriggerTime' was introduced in SBML Level 2 Version 4. Models defined in prior Versions of SBML Level 2 cannot use this attribute, and SBMLDocument.checkConsistency() will report an error if they do.

Semantics of events in SBML Level 3 Version 1

The detailed semantics of events are described in the specification documents for each SBML Level/Version. Here we include the description from the SBML Level 1 Version 1. Any transition of a Trigger object's 'math' formula from the value False to True will cause the enclosing Event object to trigger. Such a transition is not possible at the very start of a simulation (i.e., at time t = 0) unless the Trigger object's 'initialValue' attribute has a value of False; this defines the value of the trigger formula to be False immediately prior to the start of simulation, thereby giving it the potential to change in value from False to True when the formula is evaluated at t = 0. If 'initialValue'=True, then the trigger expression cannot transition from False to True at t = 0 but may do so at some time t > 0.

Consider an Event object definition E with delay d in which the Trigger object's 'math' formula makes a transition in value from False to True at times t1 and t2. The EventAssignment within the Event object will have effect at t1 + d and t2 + d irrespective of the relative times of t1 and t2. For example, events can 'overlap' so that t1 < t2 < t1 + d still causes an event assignments to occur at t1 + d and t2 + d.

It is entirely possible for two events to be executed simultaneously, and it is possible for events to trigger other events (i.e., an event assignment can cause an event to trigger). This leads to several points:

  • A software package should retest all event triggers after executing an event assignment in order to account for the possibility that the assignment causes another event trigger to transition from False to True. This check should be made after each individual Event object's execution, even when several events are to be executed simultaneously.

  • Any Event object whose Trigger 'persistent' attribute has the value False must have its trigger expression reevaluated continuously between when the event is triggered and when it is executed. If its trigger expression ever evaluates to False, it must be removed from the queue of events pending execution and treated as any other event whose trigger expression evaluates to False.

  • Although the precise time at which events are executed is not resolved beyond the given execution point in simulated time, it is assumed that the order in which the events occur is resolved. This order can be significant in determining the overall outcome of a given simulation. When an event X triggers another event Y and event Y has zero delay, then event Y is added to the existing set of simultaneous events that are pending execution. Events X and Y form a cascade of events at the same point in simulation time. An event such as Y may have a special priority if it contains a Priority subobject.

  • All events in a model are open to being in a cascade. The position of an event in the event queue does not affect whether it can be in the cascade: event Y can be triggered whether it is before or after X in the queue of events pending execution. A cascade of events can be potentially infinite (never terminate); when this occurs a simulator should indicate this has occurred—it is incorrect for a simulator to break a cascade arbitrarily and continue the simulation without at least indicating that the infinite cascade occurred.

  • Simultaneous events having no defined priorities are executed in an undefined order. This does not mean that the behavior of the simulation is completely undefined; merely that the order of execution of these particular events is undefined. A given simulator may use any algorithm to choose an order as long as every event is executed exactly once.

  • Events with defined priorities are executed in the order implied by their Priority 'math' formula values, with events having higher priorities being executed ahead of events with lower priorities, and events with identical priorities being executed in a random order with respect to one another (as determined at run-time by some random algorithm equivalent to coin-flipping). Newly-triggered events that are to be executed immediately (i.e., if they define no delays) should be inserted into the queue of events pending execution according to their priorities: events with higher priority values value must be inserted ahead of events with lower priority values and after any pending events with even higher priorities, and inserted randomly among pending events with the same priority values. Events without Priority objects must be inserted into the queue in some fashion, but the algorithm used to place it in the queue is undefined. Similarly, there is no restriction on the order of a newly-inserted event with a defined Priority with respect to any other pending Event without a defined Priority.

  • A model variable that is the target of one or more event assignments can change more than once when simultaneous events are processed at some time point t. The model's behavior (output) for such a variable is the value of the variable at the end of processing all the simultaneous events at time t.

See also
Trigger
Priority
Delay
EventAssignment

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   Event
__init__(SBMLNamespaces sbmlns)   Event
__init__(Event orig)   Event

Each variant is described separately below.


Method variant with the following signature:
Event(SBMLNamespaces sbmlns)

Creates a new Event using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
Event(Event orig)

Copy constructor; creates a copy of this Event.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
Event(long level, long version)

Creates a new Event using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this Event
versiona long integer, the SBML Version to assign to this Event
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.ListOfEvents.__init__ (   self,
  args 
)

A list of Event objects.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOfEvents
__init__(SBMLNamespaces sbmlns)   ListOfEvents

Each variant is described separately below.


Method variant with the following signature:
ListOfEvents(SBMLNamespaces sbmlns)

Creates a new ListOfEvents object.

The object is constructed such that it is valid for the SBML Level and Version combination determined by the SBMLNamespaces object in sbmlns.

Parameters
sbmlnsan SBMLNamespaces object that is used to determine the characteristics of the ListOfEvents object to be created.

Method variant with the following signature:
ListOfEvents(long level, long version)

Creates a new ListOfEvents object.

The object is constructed such that it is valid for the given SBML Level and Version combination.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
def libsbml.EventAssignment.__init__ (   self,
  args 
)

An assignment to a variable by an SBML event.

Event contains an optional element called 'listOfEventAssignments', of class ListOfEventAssignments. In every instance of an event definition in a model, the object's 'listOfEventAssignments' element must have a non-empty list of one or more 'eventAssignment' elements of class EventAssignment. The object class EventAssignment has one required attribute, 'variable', and a required element, 'math'. Being derived from SBase, it also has all the usual attributes and elements of its parent class.

An Event object defines when the event can occur, the variables that are affected by the event, and how the variables are affected. The purpose of the EventAssignment object class is to define how variables are affected by an Event. In SBML Level 2, every Event object instance must have a nonempty list of event assignments; in SBML Level 3, the list of assignments is optional.

The operation of an Event is divided into two phases (regardless of whether a delay is involved): one phase when the event is triggered, and the other when the event is executed. EventAssignment objects are interpreted when an event is executed. The effects are described below.

The attribute 'variable'

The EventAssignment attribute 'variable' must be the identifier of an existing Compartment, Species, SpeciesReference, or Parameter instance defined in the model. When the event is executed, the value of the model component identified by 'variable' is changed by the EventAssignment to the value computed by the 'math' element; that is, a species' quantity, species reference's stoichiometry, compartment's size or parameter's value are reset to the value computed by 'math'.

Certain restrictions are placed on what can appear in 'variable':

  • The object identified by the value of the EventAssignment attribute 'variable' must not have its 'constant' attribute set to or default to True. (Constants cannot be affected by events.)

  • The 'variable' attribute must not contain the identifier of a reaction; only species, species references, compartment and parameter values may be set by an Event.

  • The value of every 'variable' attribute must be unique among the set of EventAssignment structures within a given Event structure. In other words, a single event cannot have multiple EventAssignment objects assigning the same variable. (All of them would be performed at the same time when that particular Event triggers, resulting in indeterminacy.) However, separate Event instances can refer to the same variable.

  • A variable cannot be assigned a value in an EventAssignment object instance and also be assigned a value by an AssignmentRule; i.e., the value of an EventAssignment's 'variable' attribute cannot be the same as the value of a AssignmentRule' 'variable' attribute. (Assignment rules hold at all times, therefore it would be inconsistent to also define an event that reassigns the value of the same variable.)

Note that the time of assignment of the object identified by the value of the 'variable' attribute is always the time at which the Event is executed, not when it is triggered. The timing is controlled by the optional Delay in an Event. The time of assignment is not affected by the 'useValuesFromTriggerTime' attribute on Event—that attribute affects the time at which the EventAssignment's 'math' expression is evaluated. In other words, SBML allows decoupling the time at which the 'variable' is assigned from the time at which its value expression is calculated.

The 'math' subelement in an EventAssignment

The MathML expression contained in an EventAssignment defines the new value of the variable being assigned by the Event.

As mentioned above, the time at which the expression in 'math' is evaluated is determined by the attribute 'useValuesFromTriggerTime' on Event. If the attribute value is True, the expression must be evaluated when the event is triggered; more precisely, the values of identifiers occurring in MathML <ci> elements in the EventAssignment's 'math' expression are the values they have at the point when the event triggered. If, instead, 'useValuesFromTriggerTime''s value is False, it means the values at execution time should be used; that is, the values of identifiers occurring in MathML <ci> elements in the EventAssignment's 'math' expression are the values they have at the point when the event executed.

SBML Level/Version differences

Between Version 4 and previous versions of SBML Level 2, the requirements regarding the matching of units between an EvengAssignment's formula and the units of the object identified by the 'variable' attribute changed. Previous versions required consistency, but in SBML Level 2 Version 4 and in SBML Level 3, unit consistency is only recommended. More precisely:

  • In the case of a species, an EventAssignment sets the referenced species' quantity (concentration or amount of substance) to the value determined by the formula in the EventAssignment's 'math' subelement. The units of the 'math' formula should (in SBML Level 2 Version 4 and in Level 3) or must (in previous Versions of Level 2) be identical to the units of the species.

  • (SBML Level 3 only.) In the case of a species reference, an EventAssignment sets the stoichiometry of the reactant or product referenced by the SpeciesReference object to the value determined by the formula in the 'math' element. The unit associated with the value produced by the 'math' formula should be dimensionless, because reactant and product stoichiometries in reactions are dimensionless quantities.

  • In the case of a compartment, an EventAssignment sets the referenced compartment's size to the size determined by the formula in the 'math' subelement of the EventAssignment. The overall units of the formula should (in SBML Level 2 Version 4 and in Level 3) or must (in previous Versions of Level 2) be identical to the units specified for the size of the compartment identified by the EventAssignment's 'variable' attribute.

  • In the case of a parameter, an EventAssignment sets the referenced parameter's value to that determined by the formula in 'math'. The overall units of the formula should (in SBML Level 2 Version 4 and Level 3) or must (in previous Versions of Level 2) be identical to the units defined for the parameter.

Note that the formula placed in the 'math' element has no assumed units. The consistency of the units of the formula, and the units of the entity which the assignment affects, must be explicitly established just as in the case of the value of the Delay subelement. An approach similar to the one discussed in the context of Delay may be used for the formula of an EventAssignment.

See also
Event

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   EventAssignment
__init__(SBMLNamespaces sbmlns)   EventAssignment
__init__(EventAssignment orig)   EventAssignment

Each variant is described separately below.


Method variant with the following signature:
EventAssignment(SBMLNamespaces sbmlns)

Creates a new EventAssignment using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
EventAssignment(EventAssignment orig)

Copy constructor; creates a copy of this EventAssignment.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
EventAssignment(long level, long version)

Creates a new EventAssignment using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this EventAssignment
versiona long integer, the SBML Version to assign to this EventAssignment
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.ListOfEventAssignments.__init__ (   self,
  args 
)

A list of EventAssignment objects.

The various ListOf___ classes in SBML are merely containers used for organizing the main components of an SBML model. In libSBML's implementation, ListOf___ classes are derived from the intermediate utility class ListOf, which is not defined by the SBML specifications but serves as a useful programmatic construct. ListOf is itself is in turn derived from SBase, which provides all of the various ListOf___ classes with common features defined by the SBML specification, such as 'metaid' attributes and annotations.

The relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):

Readers may wonder about the motivations for using the ListOf___ containers in SBML. A simpler approach in XML might be to place the components all directly at the top level of the model definition. The choice made in SBML is to group them within XML elements named after ListOfClassname, in part because it helps organize the components. More importantly, the fact that the container classes are derived from SBase means that software tools can add information about the lists themselves into each list container's 'annotation'.

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   ListOfEventAssignments
__init__(SBMLNamespaces sbmlns)   ListOfEventAssignments

Each variant is described separately below.


Method variant with the following signature:
ListOfEventAssignments(SBMLNamespaces sbmlns)

Creates a new ListOfEventAssignments object.

The object is constructed such that it is valid for the SBML Level and Version combination determined by the SBMLNamespaces object in sbmlns.

Parameters
sbmlnsan SBMLNamespaces object that is used to determine the characteristics of the ListOfEventAssignments object to be created.

Method variant with the following signature:
ListOfEventAssignments(long level, long version)

Creates a new ListOfEventAssignments object.

The object is constructed such that it is valid for the given SBML Level and Version combination.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
def libsbml.Trigger.__init__ (   self,
  args 
)

The trigger expression for an SBML event.

An Event object defines when the event can occur, the variables that are affected by the event, and how the variables are affected. The Trigger construct in SBML is used to define a mathematical expression that determines when an Event is triggered.

A Trigger object in SBML Level 2 and Level 3 contains one subelement named 'math' containing a MathML expression. The expression must evaluate to a value of type boolean. The exact moment at which the expression evaluates to True is the time point when the Event is triggered. In SBML Level 3, Trigger has additional attributes that must be assigned values; they are discussed in a separate section below.

An event only triggers when its Trigger expression makes the transition in value from False to True. The event will also trigger at any subsequent time points when the trigger makes this transition; in other words, an event can be triggered multiple times during a simulation if its trigger condition makes the transition from False to True more than once. In SBML Level 3, the behavior at the very start of simulation (i.e., at t = 0, where t stands for time) is determined in part by the boolean flag 'initialValue'. This and other additional features introduced in SBML Level 3 are discussed further below.

Version differences

SBML Level 3 Version 1 introduces two required attributes on the Trigger object: 'persistent' and 'initialValue'. The rest of this introduction describes these two attributes.

The 'persistent' attribute on Trigger

In the interval between when an Event object triggers (i.e., its Trigger object expression transitions in value from False to True) and when its assignments are to be executed, conditions in the model may change such that the trigger expression transitions back from True to False. Should the event's assignments still be made if this happens? Answering this question is the purpose of the 'persistent' attribute on Trigger.

If the boolean attribute 'persistent' has a value of True, then once the event is triggered, all of its assignments are always performed when the time of execution is reached. The name persistent is meant to evoke the idea that the trigger expression does not have to be re-checked after it triggers if 'persistent'=True. Conversely, if the attribute value is False, then the trigger expression is not assumed to persist: if the expression transitions in value back to False at any time between when the event triggered and when it is to be executed, the event is no longer considered to have triggered and its assignments are not executed. (If the trigger expression transitions once more to True after that point, then the event is triggered, but this then constitutes a whole new event trigger-and-execute sequence.)

The 'persistent' attribute can be especially useful when Event objects contain Delay objects, but it is relevant even in a model without delays if the model contains two or more events. As explained in the introduction to this section, the operation of all events in SBML (delayed or not) is conceptually divided into two phases, triggering and execution; however, unless events have priorities associated with them, SBML does not mandate a particular ordering of event execution in the case of simultaneous events. Models with multiple events can lead to situations where the execution of one event affects another event's trigger expression value. If that other event has 'persistent'=False, and its trigger expression evaluates to False before it is to be executed, the event must not be executed after all.

The 'initialValue' attribute on Trigger

As mentioned above, an event triggers when the mathematical expression in its Trigger object transitions in value from False to True. An unanswered question concerns what happens at the start of a simulation: can event triggers make this transition at t = 0, where t stands for time?

In order to determine whether an event may trigger at t = 0, it is necessary to know what value the Trigger object's 'math' expression had immediately prior to t = 0. This starting value of the trigger expression is determined by the value of the boolean attribute 'initialValue'. A value of True means the trigger expression is taken to have the value True immediately prior to t = 0. In that case, the trigger cannot transition in value from False to True at the moment simulation begins (because it has the value True both before and after t = 0), and can only make the transition from False to True sometime after t = 0. (To do that, it would also first have to transition to False before it could make the transition from False back to True.) Conversely, if 'initialValue'=False, then the trigger expression is assumed to start with the value False, and therefore may trigger at t = 0 if the expression evaluates to True at that moment.

See also
Event
Delay
EventAssignment

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   Trigger
__init__(SBMLNamespaces sbmlns)   Trigger
__init__(Trigger orig)   Trigger

Each variant is described separately below.


Method variant with the following signature:
Trigger(Trigger orig)

Copy constructor; creates a copy of this Trigger.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
Trigger(SBMLNamespaces sbmlns)

Creates a new Trigger using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.

Method variant with the following signature:
Trigger(long level, long version)

Creates a new Trigger using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this Trigger
versiona long integer, the SBML Version to assign to this Trigger
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
def libsbml.Delay.__init__ (   self,
  args 
)

A delay on the time of execution of an SBML event.

An Event object defines when the event can occur, the variables that are affected by the event, and how the variables are affected. The effect of the event can optionally be delayed after the occurrence of the condition which invokes it. An event delay is defined using an object of class Delay.

The object class Delay is derived from SBase and adds a single subelement called 'math'. This subelement is used to hold MathML content. The mathematical formula represented by 'math' must evaluate to a numerical value. It is used as the length of time between when the event is triggered and when the event's assignments are actually executed. If no delay is present on a given Event, a time delay of zero is assumed.

The expression in 'math' must be evaluated at the time the event is triggered. The expression must always evaluate to a nonnegative number (otherwise, a nonsensical situation could arise where an event is defined to execute before it is triggered!).

The units of the mathematical expression in a Delay

In SBML Level 2 versions before Version 4, the units of the numerical value computed by the Delay's 'math' expression are required to be in units of time, or the model is considered to have a unit consistency error. In Level 2 Version 4 as well as SBML Level 3 Version 1 Core, this requirement is relaxed; these specifications only stipulate that the units of the numerical value computed by a Delay instance's 'math' expression should match the model's units of time (meaning the definition of the time units in the model). LibSBML respects these requirements, and depending on whether an earlier Version of SBML Level 2 is in use, libSBML may or may not flag unit inconsistencies as errors or merely warnings.

Note that units are not predefined or assumed for the contents of 'math' in a Delay object; rather, they must be defined explicitly for each instance of a Delay object in a model. This is an important point to bear in mind when literal numbers are used in delay expressions. For example, the following Event instance would result in a warning logged by SBMLDocument.checkConsistency() about the fact that libSBML cannot verify the consistency of the units of the expression. The reason is that the formula inside the 'math' element does not have any declared units, whereas what is expected in this context is units of time:

<model>
...
<listOfEvents>
    <event useValuesFromTriggerTime='true'>
        ...
        <delay>
            <math xmlns='http://www.w3.org/1998/Math/MathML'>
                <cn> 1 </cn>
            </math>
        </delay>
        ...
    </event>
</listOfEvents>
...
</model>

The <cn> 1 </cn> within the mathematical formula of the delay above has no units declared. To make the expression have the needed units of time, literal numbers should be avoided in favor of defining Parameter objects for each quantity, and declaring units for the Parameter values. The following fragment of SBML illustrates this approach:

<model>
...
<listOfParameters>
    <parameter id='transcriptionDelay' value='10' units='second'/>
</listOfParameters>
...
<listOfEvents>
    <event useValuesFromTriggerTime='true'>
        ...
        <delay>
            <math xmlns='http://www.w3.org/1998/Math/MathML'>
                <ci> transcriptionDelay </ci>
            </math>
        </delay>
        ...
    </event>
</listOfEvents>
...
</model>

In SBML Level 3, an alternative approach is available in the form of the units attribute, which SBML Level 3 allows to appear on MathML cn elements. The value of this attribute can be used to indicate the unit of measurement to be associated with the number in the content of a cn element. The attribute is named units but, because it appears inside MathML element (which is in the XML namespace for MathML and not the namespace for SBML), it must always be prefixed with an XML namespace prefix for the SBML Level 3 Version 1 namespace. The following is an example of this approach:

<model timeUnits='second' ...>
...
<listOfEvents>
    <event useValuesFromTriggerTime='true'>
        ...
        <delay>
            <math xmlns='http://www.w3.org/1998/Math/MathML'
                  xmlns:sbml='http://www.sbml.org/sbml/level3/version1/core'>
                <cn sbml:units='second'> 10 </cn>
            </math>
        </delay>
        ...
    </event>
</listOfEvents>
...
</model>

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   Delay
__init__(SBMLNamespaces sbmlns)   Delay
__init__(Delay orig)   Delay

Each variant is described separately below.


Method variant with the following signature:
Delay(SBMLNamespaces sbmlns)

Creates a new Delay using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
Delay(Delay orig)

Copy constructor; creates a copy of this Delay.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
Delay(long level, long version)

Creates a new Delay using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this Delay
versiona long integer, the SBML Version to assign to this Delay
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.Priority.__init__ (   self,
  args 
)

The priority of execution of an SBML event.

The Priority object class (which was introduced in SBML Level 3 Version 1), like Delay, is derived from SBase and contains a MathML formula stored in the element 'math'. This formula is used to compute a dimensionless numerical value that influences the order in which a simulator is to perform the assignments of two or more events that happen to be executed simultaneously. The formula may evaluate to any float value (and thus may be a positive or negative number, or zero), with positive numbers taken to signifying a higher priority than zero or negative numbers. If no Priority object is present on a given Event object, no priority is defined for that event.

The interpretation of priorities on events in a model

For the purposes of SBML, simultaneous event execution is defined as the situation in which multiple events have identical times of execution. The time of execution is calculated as the sum of the time at which a given event's Trigger is triggered plus its Delay duration, if any. Here, identical times means mathematically equal instants in time. (In practice, simulation software adhering to this specification may have to rely on numerical equality instead of strict mathematical equality; robust models will ensure that this difference will not cause significant discrepancies from expected behavior.)

If no Priority subobjects are defined for two or more Event objects, then those events are still executed simultaneously but their order of execution is undefined by the SBML Level 3 Version 1 specification. A software implementation may choose to execute such simultaneous events in any order, as long as each event is executed only once and the requirements of checking the 'persistent' attribute (and acting accordingly) are satisfied.

If Priority subobjects are defined for two or more simultaneously-triggered events, the order in which those particular events must be executed is dictated by their Priority objects, as follows. If the values calculated using the two Priority objects' 'math' expressions differ, then the event having the higher priority value must be executed before the event with the lower value. If, instead, the two priority values are mathematically equal, then the two events must be triggered in a random order. It is important to note that a random order is not the same as an undefined order: given multiple runs of the same model with identical conditions, an undefined ordering would permit a system to execute the events in (for example) the same order every time (according to whatever scheme may have been implemented by the system), whereas the explicit requirement for random ordering means that the order of execution in different simulation runs depends on random chance. In other words, given two events A and B, a randomly-determined order must lead to an equal chance of executing A first or B first, every time those two events are executed simultaneously.

A model may contain a mixture of events, some of which have Priority subobjects and some do not. Should a combination of simultaneous events arise in which some events have priorities defined and others do not, the set of events with defined priorities must trigger in the order determined by their Priority objects, and the set of events without Priority objects must be executed in an undefined order with respect to each other and with respect to the events with Priority subobjects. (Note that undefined order does not necessarily mean random order, although a random ordering would be a valid implementation of this requirement.)

The following example may help further clarify these points. Suppose a model contains four events that should be executed simultaneously, with two of the events having Priority objects with the same value and the other two events having Priority objects with the same, but different, value. The two events with the higher priorities must be executed first, in a random order with respect to each other, and the remaining two events must be executed after them, again in a random order, for a total of four possible and equally-likely event executions: A-B-C-D, A-B-D-C, B-A-C-D, and B-A-D-C. If, instead, the model contains four events all having the same Priority values, there are 4! or 24 possible orderings, each of which must be equally likely to be chosen. Finally, if none of the four events has a Priority subobject defined, or even if exactly one of the four events has a defined Priority, there are again 24 possible orderings, but the likelihood of choosing any particular ordering is undefined; the simulator can choose between events as it wishes. (The SBML specification only defines the effects of priorities on Event objects with respect to other Event objects with priorities. Putting a priority on a single Event object in a model does not cause it to fall within that scope.)

Evaluation of Priority expressions

An event's Priority object 'math' expression must be evaluated at the time the Event is to be executed. During a simulation, all simultaneous events have their Priority values calculated, and the event with the highest priority is selected for next execution. Note that it is possible for the execution of one Event object to cause the Priority value of another simultaneously-executing Event object to change (as well as to trigger other events, as already noted). Thus, after executing one event, and checking whether any other events in the model have been triggered, all remaining simultaneous events that either (i) have Trigger objects with attributes 'persistent'=False or (ii) have Trigger expressions that did not transition from True to False, must have their Priority expression reevaluated. The highest-priority remaining event must then be selected for execution next.

Units of Priority object's mathematical expressions

The unit associated with the value of a Priority object's 'math' expression should be dimensionless. This is because the priority expression only serves to provide a relative ordering between different events, and only has meaning with respect to other Priority object expressions. The value of Priority objects is not comparable to any other kind of object in an SBML model.

Note
The Priority construct exists only in SBML Level 3; it cannot be used in SBML Level 2 or Level 1 models.
See also
Event
Delay
EventAssignment

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   Priority
__init__(SBMLNamespaces sbmlns)   Priority
__init__(Priority orig)   Priority

Each variant is described separately below.


Method variant with the following signature:
Priority(Priority orig)

Copy constructor; creates a copy of this Priority.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
Priority(SBMLNamespaces sbmlns)

Creates a new Priority object using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
The Priority construct exists only in SBML Level 3; it cannot be used in SBML Level 2 or Level 1 models.

Method variant with the following signature:
Priority(long level, long version)

Creates a new Priority object using the given SBML level and version values.

Parameters
levela long integer, the SBML Level to assign to this Priority
versiona long integer, the SBML Version to assign to this Priority
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
The Priority construct exists only in SBML Level 3; it cannot be used in SBML Level 2 or Level 1 models.
def libsbml.StoichiometryMath.__init__ (   self,
  args 
)

Stochiometry expressions in SBML Level 2 reactions.

Stoichiometries in SBML Level 2

In SBML Level 2, product and reactant stoichiometries can be specified using either the 'stoichiometry' attribute or a 'stoichiometryMath' element in a SpeciesReference object. The 'stoichiometry' attribute is of type float and should contain values greater than zero (0). The 'stoichiometryMath' element is implemented as an element containing a MathML expression. These two are mutually exclusive; only one of 'stoichiometry' or 'stoichiometryMath' should be defined in a given SpeciesReference instance. When neither the attribute nor the element is present, the value of 'stoichiometry' in the enclosing SpeciesReference instance defaults to 1.

For maximum interoperability, SpeciesReference's 'stoichiometry' attribute should be used in preference to 'stoichiometryMath' when a species' stoichiometry is a simple scalar number (integer or decimal). When the stoichiometry is a rational number, or when it is a more complicated formula, 'stoichiometryMath' must be used. The MathML expression in 'stoichiometryMath' may also refer to identifiers of entities in a model (except reaction identifiers). However, the only species identifiers that can be used in 'stoichiometryMath' are those referenced in the enclosing Reaction's list of reactants, products and modifiers.

The 'stoichiometry' attribute and the 'stoichiometryMath' element, when either is used, is each interpreted as a factor applied to the reaction rate to produce the rate of change of the species identified by the 'species' attribute in the enclosing SpeciesReference. This is the normal interpretation of a stoichiometry, but in SBML, one additional consideration has to be taken into account. The reaction rate, which is the result of the KineticLaw's 'math' element, is always in the model's substance per time units. However, the rate of change of the species will involve the species' substance units (i.e., the units identified by the Species object's 'substanceUnits' attribute), and these units may be different from the model's default substance units. If the units are different, the stoichiometry must incorporate a conversion factor for converting the model's substance units to the species' substance units. The conversion factor is assumed to be included in the scalar value of the 'stoichiometry' attribute if 'stoichiometry' is used. If instead 'stoichiometryMath' is used, then the product of the model's 'substance' units times the 'stoichiometryMath' units must match the substance units of the species. Note that in either case, if the species' units and the model's default substance units are the same, the stoichiometry ends up being a dimensionless number and equivalent to the standard chemical stoichiometry found in textbooks. Examples and more explanations of this are given in the SBML specification.

The following is a simple example of a species reference for species 'X0', with stoichiometry 2, in a list of reactants within a reaction having the identifier 'J1':

 <model>
 ...
 <listOfReactions>
     <reaction id='J1'>
         <listOfReactants>
             <speciesReference species='X0' stoichiometry='2'>
         </listOfReactants>
         ...
     </reaction>
     ...
 </listOfReactions>
 ...
 </model>

The following is a more complex example of a species reference for species 'X0', with a stoichiometry formula consisting of a rational number:

 <model>
 ...
 <listOfReactions>
     <reaction id='J1'>
         <listOfReactants>
             <speciesReference species='X0'>
                 <stoichiometryMath>
                     <math xmlns='http://www.w3.org/1998/Math/MathML'> 
                         <cn type='rational'> 3 <sep/> 2 </cn>
                     </math>
                 </stoichiometryMath>
             </speciesReference>
         </listOfReactants>
         ...
     </reaction>
     ...
 </listOfReactions>
 ...
 </model>

Additional discussions of stoichiometries and implications for species and reactions are included in the documentation of SpeciesReference class.

Stoichiometries in SBML Level 3

The StoichiometryMath construct is not defined in SBML Level 3 Version 1 Core. Instead, Level 3 defines the identifier of SpeciesReference objects as a stand-in for the stoichiometry of the reactant or product being referenced, and allows that identifier to be used elsewhere in SBML models, including (for example) InitialAssignment objects. This makes it possible to achieve the same effect as StoichiometryMath, but with other SBML objects. For instance, to produce a stoichiometry value that is a rational number, a model can use InitialAssignment to assign the identifier of a SpeciesReference object to a MathML expression evaluating to a rational number. This is analogous to the same way that, in Level 2, the model would use StoichiometryMath with a MathML expression evaluating to a rational number.

In SBML Level 2, the stoichiometry of a reactant or product is a combination of both a biochemical stoichiometry (meaning, the standard stoichiometry of a species in a reaction) and any necessary unit conversion factors. The introduction of an explicit attribute on the Species object for a conversion factor allows Level 3 to avoid having to overload the meaning of stoichiometry. In Level 3, the stoichiometry given by a SpeciesReference object in a reaction is a 'proper' biochemical stoichiometry, meaning a dimensionless number free of unit conversions.

See also
SpeciesReference
Reaction

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   StoichiometryMath
__init__(SBMLNamespaces sbmlns)   StoichiometryMath
__init__(StoichiometryMath orig)   StoichiometryMath

Each variant is described separately below.


Method variant with the following signature:
StoichiometryMath(SBMLNamespaces sbmlns)

Creates a new StoichiometryMath object using the given SBMLNamespaces object sbmlns.

The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
sbmlnsan SBMLNamespaces object.
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
The StoichiometryMath construct exists only in SBML Level 2. It is an optional construct available for defining the stoichiometries of reactants and products in Reaction objects. Note that a different mechanism is used in SBML Level 3, where StoichiometryMath is not available. Please consult the top of this libSBML StoichiometryMath documentation for more information about the differences between SBML Level 2 and 3 with respect to stoichiometries.
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

Method variant with the following signature:
StoichiometryMath(StoichiometryMath orig)

Copy constructor; creates a copy of this StoichiometryMath.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
StoichiometryMath(long level, long version)

Creates a new StoichiometryMath object using the given SBML level values.

Parameters
levela long integer, the SBML Level to assign to this StoichiometryMath
versiona long integer, the SBML Version to assign to this StoichiometryMath
Exceptions
ValueErrorThrown if the given level and version combination, or this kind of SBML object, are either invalid or mismatched with respect to the parent SBMLDocument object.
Note
The StoichiometryMath construct exists only in SBML Level 2. It is an optional construct available for defining the stoichiometries of reactants and products in Reaction objects. Note that a different mechanism is used in SBML Level 3, where StoichiometryMath is not available. Please consult the top of this libSBML StoichiometryMath documentation for more information about the differences between SBML Level 2 and 3 with respect to stoichiometries.
Attempting to add an object to an SBMLDocument having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.
def libsbml.SBMLNamespaces.__init__ (   self,
  args 
)

Set of SBML Level + Version + namespace triples.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

There are differences in the definitions of components between different SBML Levels, as well as Versions within Levels. For example, the 'sboTerm' attribute was not introduced until Level 2 Version 2, and then only on certain component classes; the SBML Level 2 Version 3 specification moved the 'sboTerm' attribute to the SBase class, thereby allowing nearly all components to have SBO annotations. As a result of differences such as those, libSBML needs to track the SBML Level and Version of every object created.

The purpose of the SBMLNamespaces object class is to make it easier to communicate SBML Level and Version data between libSBML constructors and other methods. The SBMLNamespaces object class tracks 3-tuples (triples) consisting of SBML Level, Version, and the corresponding SBML XML namespace.

The plural name (SBMLNamespaces) is not a mistake, because in SBML Level 3, objects may have extensions added by Level 3 packages used by a given model and therefore may have multiple namespaces associated with them; however, until the introduction of SBML Level 3, the SBMLNamespaces object only records one SBML Level/Version/namespace combination at a time. Most constructors for SBML objects in libSBML take a SBMLNamespaces object as an argument, thereby allowing the constructor to produce the proper combination of attributes and other internal data structures for the given SBML Level and Version.

This method has multiple variants; they differ in the arguments they accept.

__init__(long level, long version)   SBMLNamespaces
__init__(long level)   SBMLNamespaces
__init__()   SBMLNamespaces
__init__(long level, long version, string pkgName, long pkgVersion, string pkgPrefix)   SBMLNamespaces
__init__(long level, long version, string pkgName, long pkgVersion)   SBMLNamespaces
__init__(SBMLNamespaces orig)   SBMLNamespaces

Each variant is described separately below.


Method variant with the following signature:
SBMLNamespaces(long level = SBML_DEFAULT_LEVEL, long version = SBML_DEFAULT_VERSION)

Creates a new SBMLNamespaces object corresponding to the given SBML level and version.

SBMLNamespaces objects are used in libSBML to communicate SBML Level and Version data between constructors and other methods. The SBMLNamespaces object class holds triples consisting of SBML Level, Version, and the corresponding SBML XML namespace. Most constructors for SBML objects in libSBML take a SBMLNamespaces object as an argument, thereby allowing the constructor to produce the proper combination of attributes and other internal data structures for the given SBML Level and Version.

The plural name (SBMLNamespaces) is not a mistake, because in SBML Level 3, objects may have extensions added by Level 3 packages used by a given model and therefore may have multiple namespaces associated with them. In SBML Levels below Level 3, the SBMLNamespaces object only records one SBML Level/Version/namespace combination at a time. Most constructors for SBML objects in libSBML take a SBMLNamespaces object as an argument, thereby allowing the constructor to produce the proper combination of attributes and other internal data structures for the given SBML Level and Version.

Parameters
levelthe SBML level
versionthe SBML version

Method variant with the following signature:
SBMLNamespaces(long level, long version, stringpkgName, long pkgVersion, string pkgPrefix = '')

(For extensions) Creates a new SBMLNamespaces object corresponding to the combination of (1) the given SBML level and version, and (2) the given package with the package version.

SBMLNamespaces objects are used in libSBML to communicate SBML Level and Version data between constructors and other methods. The SBMLNamespaces object class holds triples consisting of SBML Level, Version, and the corresponding SBML XML namespace. Most constructors for SBML objects in libSBML take a SBMLNamespaces object as an argument, thereby allowing the constructor to produce the proper combination of attributes and other internal data structures for the given SBML Level and Version.

The plural name (SBMLNamespaces) is not a mistake, because in SBML Level 3, objects may have extensions added by Level 3 packages used by a given model and therefore may have multiple namespaces associated with them. In SBML Levels below Level 3, the SBMLNamespaces object only records one SBML Level/Version/namespace combination at a time. Most constructors for SBML objects in libSBML take a SBMLNamespaces object as an argument, thereby allowing the constructor to produce the proper combination of attributes and other internal data structures for the given SBML Level and Version.

Parameters
levelthe SBML Level
versionthe SBML Version
pkgNamethe string of package name (e.g. 'layout', 'multi')
pkgVersionthe package version
pkgPrefixthe prefix of the package namespace (e.g. 'layout', 'multi') to be added. The package's name will be used if the given string is empty (default).
Exceptions
SBMLExtensionExceptionif the extension module that supports the combination of the given SBML Level, SBML Version, package name, and package version has not been registered with libSBML.

Method variant with the following signature:
SBMLNamespaces(SBMLNamespaces orig)

Copy constructor; creates a copy of a SBMLNamespaces.

Parameters
origthe SBMLNamespaces instance to copy.
Exceptions
ValueErrorThrown if the argument orig is None.
def libsbml.ConversionOption.__init__ (   self,
  args 
)

A single configuration setting for an SBML converter.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.

LibSBML provides a number of converters that can perform transformations on SBML documents. These converters allow their behaviors to be controlled by setting property values. Converter properties are communicated using objects of class ConversionProperties, and within such objects, individual options are encapsulated using ConversionOption objects.

A ConversionOption object consists of four parts:

  • A key, acting as the name of the option.
  • A value of this option.
  • A type for the value; the type code is chosen from a set of integer constants whose names all begin with the prefix CNV_TYPE_. (See the separate subsection below for more information.)
  • A description consisting of a text string that describes the option in some way.

There are no constraints on the values of keys or descriptions; authors of SBML converters are free to choose them as they see fit.

Rule types for SBML Level 1

An option in ConversionOption must have a data type declared, to indicate whether it is a string value, an integer, and so forth. The possible types of values are taken from a set of constants whose symbol names begin with the prefix CNV_TYPE_. The following are the possible values:

Enumerator Meaning
CNV_TYPE_BOOL Indicates the value type is a Boolean.
CNV_TYPE_DOUBLE Indicates the value type is a float-sized float.
CNV_TYPE_INT Indicates the value type is an integer.
CNV_TYPE_SINGLE Indicates the value type is a float.
CNV_TYPE_STRING Indicates the value type is a string.
See also
ConversionProperties

This method has multiple variants; they differ in the arguments they accept.

__init__(string key, string value, long type=CNV_TYPE_STRING, string description)   ConversionOption
__init__(string key, string value, long type=CNV_TYPE_STRING)   ConversionOption
__init__(string key, string value)   ConversionOption
__init__(string key)   ConversionOption
__init__(string key, string value, string description)   ConversionOption
__init__(string key, string value)   ConversionOption
__init__(string key, bool value, string description)   ConversionOption
__init__(string key, bool value)   ConversionOption
__init__(string key, float value, string description)   ConversionOption
__init__(string key, float value)   ConversionOption
__init__(string key, float value, string description)   ConversionOption
__init__(string key, float value)   ConversionOption
__init__(string key, int value, string description)   ConversionOption
__init__(string key, int value)   ConversionOption
__init__(ConversionOption orig)   ConversionOption

Each variant is described separately below.


Method variant with the following signature:
ConversionOption(string key, int value, string description='')

Creates a new ConversionOption specialized for integer-type options.

Parameters
keythe key for this option
valuethe value for this option
descriptionan optional description

Method variant with the following signature:
ConversionOption(string key, string value='', long type=CNV_TYPE_STRING, string description='')

Creates a new ConversionOption.

This is the general constructor, taking arguments for all aspects of an option. Other constructors exist with different arguments.

The conversion type argument value must be one of the constants whose names begin with the characters CNV_TYPE_ in the interface class libsbml.
Parameters
keythe key for this option
valuean optional value for this option
typethe type of this option
descriptionthe description for this option

Method variant with the following signature:
ConversionOption(ConversionOption orig)

Copy constructor; creates a copy of an ConversionOption object.

Parameters
origthe ConversionOption object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
ConversionOption(string key, float value, string description='')

Creates a new ConversionOption specialized for float-type options.

Parameters
keythe key for this option
valuethe value for this option
descriptionan optional description

Method variant with the following signature:
ConversionOption(string key, float value, string description='')

Creates a new ConversionOption specialized for float-type options.

Parameters
keythe key for this option
valuethe value for this option
descriptionan optional description

Method variant with the following signature:
ConversionOption(string key, bool value, string description='')

Creates a new ConversionOption specialized for Boolean-type options.

Parameters
keythe key for this option
valuethe value for this option
descriptionan optional description

Method variant with the following signature:
ConversionOption(string key, string value, string description='')

Creates a new ConversionOption specialized for string-type options.

Parameters
keythe key for this option
valuethe value for this option
descriptionan optional description
def libsbml.ConversionProperties.__init__ (   self,
  args 
)

Set of configuration option values for a converter.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.

LibSBML provides a number of converters that can perform transformations on SBML documents. The properties of SBML converters are communicated using objects of class ConversionProperties, and within such objects, individual options are encapsulated using ConversionOption objects. The ConversionProperties class provides numerous methods for setting and getting options.

ConversionProperties objects are also used to determine the target SBML namespace when an SBML converter's behavior depends on the intended Level+Version combination of SBML. In addition, it is conceivable that conversions may be affected by SBML Level 3 packages being used by an SBML document; consequently, the packages in use are also communicated by the values of the SBML namespaces set on a ConversionProperties object.

General information about the use of SBML converters

The use of all the converters follows a similar approach. First, one creates a ConversionProperties object and calls ConversionProperties.addOption() on this object with one arguments: a text string that identifies the desired converter. (The text string is specific to each converter; consult the documentation for a given converter to find out how it should be enabled.)

Next, for some converters, the caller can optionally set some converter-specific properties using additional calls to ConversionProperties.addOption(). Many converters provide the ability to configure their behavior to some extent; this is realized through the use of properties that offer different options. The default property values for each converter can be interrogated using the method SBMLConverter.getDefaultProperties() on the converter class in question .

Finally, the caller should invoke the method SBMLDocument.convert() with the ConversionProperties object as an argument.

Example of invoking an SBML converter

The following code fragment illustrates an example using SBMLReactionConverter, which is invoked using the option string 'replaceReactions':

1 config = ConversionProperties()
2 if config != None:
3  config.addOption('replaceReactions')

In the case of SBMLReactionConverter, there are no options to affect its behavior, so the next step is simply to invoke the converter on an SBMLDocument object. Continuing the example code:

1  # Assume that the variable 'document' has been set to an SBMLDocument object.
2  status = document.convert(config)
3  if status != LIBSBML_OPERATION_SUCCESS:
4 # Handle error somehow.
5 print('Error: conversion failed due to the following:')
6 document.printErrors()

Here is an example of using a converter that offers an option. The following code invokes SBMLStripPackageConverter to remove the SBML Level 3 Layout package from a model. It sets the name of the package to be removed by adding a value for the option named 'package' defined by that converter:

1 def strip_layout_example(document):
2  config = ConversionProperties()
3  if config != None:
4 config.addOption('stripPackage')
5 config.addOption('package', 'layout')
6 status = document.convert(config)
7 if status != LIBSBML_OPERATION_SUCCESS:
8  # Handle error somehow.
9  print('Error: unable to strip the Layout package.')
10  print('LibSBML returned error: ' + OperationReturnValue_toString(status).strip())
11  else:
12 # Handle error somehow.
13 print('Error: unable to create ConversionProperties object')

Available SBML converters in libSBML

LibSBML provides a number of built-in converters; by convention, their names end in Converter. The following are the built-in converters provided by libSBML 5.11.0:

See also
ConversionOption
SBMLNamespaces

This method has multiple variants; they differ in the arguments they accept.

__init__(SBMLNamespaces targetNS=None)   ConversionProperties
__init__()   ConversionProperties
__init__(ConversionProperties orig)   ConversionProperties

Each variant is described separately below.


Method variant with the following signature:
ConversionProperties(SBMLNamespaces targetNS=None)

Constructor that initializes the conversion properties with a specific SBML target namespace.

Parameters
targetNSthe target namespace to convert to

Method variant with the following signature:
ConversionProperties(ConversionProperties orig)

Copy constructor.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.
def libsbml.SBMLConverter.__init__ (   self,
  args 
)

Base class for SBML converters.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.

The SBMLConverter class is the base class for the various SBML converters: classes of objects that transform or convert SBML documents. These transformations can involve essentially anything that can be written algorithmically; examples include converting the units of measurement in a model, or converting from one Level+Version combination of SBML to another. Applications can also create their own converters by subclassing SBMLConverter and following the examples of the existing converters.

General information about the use of SBML converters

The use of all the converters follows a similar approach. First, one creates a ConversionProperties object and calls ConversionProperties.addOption() on this object with one arguments: a text string that identifies the desired converter. (The text string is specific to each converter; consult the documentation for a given converter to find out how it should be enabled.)

Next, for some converters, the caller can optionally set some converter-specific properties using additional calls to ConversionProperties.addOption(). Many converters provide the ability to configure their behavior to some extent; this is realized through the use of properties that offer different options. The default property values for each converter can be interrogated using the method SBMLConverter.getDefaultProperties() on the converter class in question .

Finally, the caller should invoke the method SBMLDocument.convert() with the ConversionProperties object as an argument.

Example of invoking an SBML converter

The following code fragment illustrates an example using SBMLReactionConverter, which is invoked using the option string 'replaceReactions':

1 config = ConversionProperties()
2 if config != None:
3  config.addOption('replaceReactions')

In the case of SBMLReactionConverter, there are no options to affect its behavior, so the next step is simply to invoke the converter on an SBMLDocument object. Continuing the example code:

1  # Assume that the variable 'document' has been set to an SBMLDocument object.
2  status = document.convert(config)
3  if status != LIBSBML_OPERATION_SUCCESS:
4 # Handle error somehow.
5 print('Error: conversion failed due to the following:')
6 document.printErrors()

Here is an example of using a converter that offers an option. The following code invokes SBMLStripPackageConverter to remove the SBML Level 3 Layout package from a model. It sets the name of the package to be removed by adding a value for the option named 'package' defined by that converter:

1 def strip_layout_example(document):
2  config = ConversionProperties()
3  if config != None:
4 config.addOption('stripPackage')
5 config.addOption('package', 'layout')
6 status = document.convert(config)
7 if status != LIBSBML_OPERATION_SUCCESS:
8  # Handle error somehow.
9  print('Error: unable to strip the Layout package.')
10  print('LibSBML returned error: ' + OperationReturnValue_toString(status).strip())
11  else:
12 # Handle error somehow.
13 print('Error: unable to create ConversionProperties object')

Available SBML converters in libSBML

LibSBML provides a number of built-in converters; by convention, their names end in Converter. The following are the built-in converters provided by libSBML 5.11.0:

This method has multiple variants; they differ in the arguments they accept.

__init__()   SBMLConverter
__init__(string name)   SBMLConverter
__init__(SBMLConverter orig)   SBMLConverter

Each variant is described separately below.


Method variant with the following signature:
SBMLConverter(SBMLConverter orig)

Copy constructor.

This creates a copy of an SBMLConverter object.

Parameters
origthe SBMLConverter object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
SBMLConverter()

Creates a new SBMLConverter object.


Method variant with the following signature:
SBMLConverter(string name)

Creates a new SBMLConverter object with a given name.

Parameters
namethe name for the converter to create
def libsbml.SBMLFunctionDefinitionConverter.__init__ (   self,
  args 
)

Converter to expand user-defined functions in-line.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.

This converter manipulates user-defined functions in an SBML file. When invoked on a model, it performs the following operations:

  • Reads the list of user-defined functions in the model (i.e., the list of FunctionDefinition objects);
  • Looks for invocations of the function in mathematical expressions throughout the model; and
  • For each invocation found, replaces the invocation with a in-line copy of the function's body, similar to how macro expansions might be performed in scripting and programming languages.

For example, suppose the model contains a function definition representing the function f(x, y) = x * y. Further suppose this functions invoked somewhere else in the model, in a mathematical formula, as f(s, p). The outcome of running SBMLFunctionDefinitionConverter on the model will be to replace the call to f with the expression s * p.

Configuration and use of SBMLFunctionDefinitionConverter

SBMLFunctionDefinitionConverter is enabled by creating a ConversionProperties object with the option 'expandFunctionDefinitions', and passing this properties object to SBMLDocument.convert(). The converter accepts one option:

  • 'skipIds': if set, it should be a string containing a comma-separated list of identifiers (SBML 'id' values) that are to be skipped during function conversion. Functions whose identifiers are found in this list will not be converted.

General information about the use of SBML converters

The use of all the converters follows a similar approach. First, one creates a ConversionProperties object and calls ConversionProperties.addOption() on this object with one arguments: a text string that identifies the desired converter. (The text string is specific to each converter; consult the documentation for a given converter to find out how it should be enabled.)

Next, for some converters, the caller can optionally set some converter-specific properties using additional calls to ConversionProperties.addOption(). Many converters provide the ability to configure their behavior to some extent; this is realized through the use of properties that offer different options. The default property values for each converter can be interrogated using the method SBMLConverter.getDefaultProperties() on the converter class in question .

Finally, the caller should invoke the method SBMLDocument.convert() with the ConversionProperties object as an argument.

Example of invoking an SBML converter

The following code fragment illustrates an example using SBMLReactionConverter, which is invoked using the option string 'replaceReactions':

1 config = ConversionProperties()
2 if config != None:
3  config.addOption('replaceReactions')

In the case of SBMLReactionConverter, there are no options to affect its behavior, so the next step is simply to invoke the converter on an SBMLDocument object. Continuing the example code:

1  # Assume that the variable 'document' has been set to an SBMLDocument object.
2  status = document.convert(config)
3  if status != LIBSBML_OPERATION_SUCCESS:
4 # Handle error somehow.
5 print('Error: conversion failed due to the following:')
6 document.printErrors()

Here is an example of using a converter that offers an option. The following code invokes SBMLStripPackageConverter to remove the SBML Level 3 Layout package from a model. It sets the name of the package to be removed by adding a value for the option named 'package' defined by that converter:

1 def strip_layout_example(document):
2  config = ConversionProperties()
3  if config != None:
4 config.addOption('stripPackage')
5 config.addOption('package', 'layout')
6 status = document.convert(config)
7 if status != LIBSBML_OPERATION_SUCCESS:
8  # Handle error somehow.
9  print('Error: unable to strip the Layout package.')
10  print('LibSBML returned error: ' + OperationReturnValue_toString(status).strip())
11  else:
12 # Handle error somehow.
13 print('Error: unable to create ConversionProperties object')

Available SBML converters in libSBML

LibSBML provides a number of built-in converters; by convention, their names end in Converter. The following are the built-in converters provided by libSBML 5.11.0:

This method has multiple variants; they differ in the arguments they accept.

__init__()   SBMLFunctionDefinitionConverter
__init__(SBMLFunctionDefinitionConverter obj)   SBMLFunctionDefinitionConverter

Each variant is described separately below.


Method variant with the following signature:
SBMLFunctionDefinitionConverter()

Creates a new SBMLFunctionDefinitionConverter object.


Method variant with the following signature:
SBMLFunctionDefinitionConverter(SBMLFunctionDefinitionConverter obj)

Copy constructor; creates a copy of an SBMLFunctionDefinitionConverter object.

Parameters
objthe SBMLFunctionDefinitionConverter object to copy.
def libsbml.SBMLIdConverter.__init__ (   self,
  args 
)

Converter for replacing object identifiers.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.

This converter translates all instances of a given identifier (i.e., SBML object 'id' attribute value) of type 'SId' in a Model to another identifier. It does this based on a list of source identifiers, translating each one to its corresponding replacement value in a list of replacement identifiers. It also updates all references to the identifiers so replaced. (More technically, it replaces all values known as type SIdRef in the SBML Level 3 specifications.)

This converter only searches the global SId namespace for the Model child of the SBMLDocument. It does not replace any IDs or SIdRefs for LocalParameters, nor does it replace any UnitSIds or UnitSIdRefs. It likewise does not replace any IDs in a new namespace introduced by a package, such as the PortSId namespace from the Hierarchical Model Composition package, nor any Model objects that are not the direct child of the SBMLDocument, such as the ModelDefinitions from the Hierarchical Model Composition package.

If, however, a package introduces a new element with an 'id' attribute of type SId, any attribute of type SIdRef, or child of type SIdRef (such as a new Math child of a package element), those IDs will be replaced if they match a source identifier.

Configuration and use of SBMLIdConverter

SBMLIdConverter is enabled by creating a ConversionProperties object with the option 'renameSIds', and passing this properties object to SBMLDocument.convert(). The converter accepts two options, and both must be set or else no conversion is performed:

  • 'currentIds': A comma-separated list of identifiers to replace.
  • 'newIds': A comma-separated list of identifiers to use as the replacements. The values should correspond one-to-one with the identifiers in 'currentIds' that should be replaced.

General information about the use of SBML converters

The use of all the converters follows a similar approach. First, one creates a ConversionProperties object and calls ConversionProperties.addOption() on this object with one arguments: a text string that identifies the desired converter. (The text string is specific to each converter; consult the documentation for a given converter to find out how it should be enabled.)

Next, for some converters, the caller can optionally set some converter-specific properties using additional calls to ConversionProperties.addOption(). Many converters provide the ability to configure their behavior to some extent; this is realized through the use of properties that offer different options. The default property values for each converter can be interrogated using the method SBMLConverter.getDefaultProperties() on the converter class in question .

Finally, the caller should invoke the method SBMLDocument.convert() with the ConversionProperties object as an argument.

Example of invoking an SBML converter

The following code fragment illustrates an example using SBMLReactionConverter, which is invoked using the option string 'replaceReactions':

1 config = ConversionProperties()
2 if config != None:
3  config.addOption('replaceReactions')

In the case of SBMLReactionConverter, there are no options to affect its behavior, so the next step is simply to invoke the converter on an SBMLDocument object. Continuing the example code:

1  # Assume that the variable 'document' has been set to an SBMLDocument object.
2  status = document.convert(config)
3  if status != LIBSBML_OPERATION_SUCCESS:
4 # Handle error somehow.
5 print('Error: conversion failed due to the following:')
6 document.printErrors()

Here is an example of using a converter that offers an option. The following code invokes SBMLStripPackageConverter to remove the SBML Level 3 Layout package from a model. It sets the name of the package to be removed by adding a value for the option named 'package' defined by that converter:

1 def strip_layout_example(document):
2  config = ConversionProperties()
3  if config != None:
4 config.addOption('stripPackage')
5 config.addOption('package', 'layout')
6 status = document.convert(config)
7 if status != LIBSBML_OPERATION_SUCCESS:
8  # Handle error somehow.
9  print('Error: unable to strip the Layout package.')
10  print('LibSBML returned error: ' + OperationReturnValue_toString(status).strip())
11  else:
12 # Handle error somehow.
13 print('Error: unable to create ConversionProperties object')

Available SBML converters in libSBML

LibSBML provides a number of built-in converters; by convention, their names end in Converter. The following are the built-in converters provided by libSBML 5.11.0:

This method has multiple variants; they differ in the arguments they accept.

__init__()   SBMLIdConverter
__init__(SBMLIdConverter obj)   SBMLIdConverter

Each variant is described separately below.


Method variant with the following signature:
SBMLIdConverter(SBMLIdConverter obj)

Copy constructor; creates a copy of an SBMLIdConverter object.

Parameters
objthe SBMLIdConverter object to copy.

Method variant with the following signature:
SBMLIdConverter()

Creates a new SBMLIdConverter object.

def libsbml.SBMLInferUnitsConverter.__init__ (   self,
  args 
)

Converter for inferring and setting parameter units.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.

This SBML converter takes an SBML document and attempts to infer units for any Parameter objects whose units are undeclared. It then sets the 'units' attribute of those parameters to the units inferred (if necessary, creating new UnitDefinition objects on the model in the process).

Configuration and use of SBMLInferUnitsConverter

SBMLInferUnitsConverter is enabled by creating a ConversionProperties object with the option 'inferUnits', and passing this properties object to SBMLDocument.convert(). The converter offers no other options.

General information about the use of SBML converters

The use of all the converters follows a similar approach. First, one creates a ConversionProperties object and calls ConversionProperties.addOption() on this object with one arguments: a text string that identifies the desired converter. (The text string is specific to each converter; consult the documentation for a given converter to find out how it should be enabled.)

Next, for some converters, the caller can optionally set some converter-specific properties using additional calls to ConversionProperties.addOption(). Many converters provide the ability to configure their behavior to some extent; this is realized through the use of properties that offer different options. The default property values for each converter can be interrogated using the method SBMLConverter.getDefaultProperties() on the converter class in question .

Finally, the caller should invoke the method SBMLDocument.convert() with the ConversionProperties object as an argument.

Example of invoking an SBML converter

The following code fragment illustrates an example using SBMLReactionConverter, which is invoked using the option string 'replaceReactions':

1 config = ConversionProperties()
2 if config != None:
3  config.addOption('replaceReactions')

In the case of SBMLReactionConverter, there are no options to affect its behavior, so the next step is simply to invoke the converter on an SBMLDocument object. Continuing the example code:

1  # Assume that the variable 'document' has been set to an SBMLDocument object.
2  status = document.convert(config)
3  if status != LIBSBML_OPERATION_SUCCESS:
4 # Handle error somehow.
5 print('Error: conversion failed due to the following:')
6 document.printErrors()

Here is an example of using a converter that offers an option. The following code invokes SBMLStripPackageConverter to remove the SBML Level 3 Layout package from a model. It sets the name of the package to be removed by adding a value for the option named 'package' defined by that converter:

1 def strip_layout_example(document):
2  config = ConversionProperties()
3  if config != None:
4 config.addOption('stripPackage')
5 config.addOption('package', 'layout')
6 status = document.convert(config)
7 if status != LIBSBML_OPERATION_SUCCESS:
8  # Handle error somehow.
9  print('Error: unable to strip the Layout package.')
10  print('LibSBML returned error: ' + OperationReturnValue_toString(status).strip())
11  else:
12 # Handle error somehow.
13 print('Error: unable to create ConversionProperties object')

Available SBML converters in libSBML

LibSBML provides a number of built-in converters; by convention, their names end in Converter. The following are the built-in converters provided by libSBML 5.11.0:

This method has multiple variants; they differ in the arguments they accept.

__init__()   SBMLInferUnitsConverter
__init__(SBMLInferUnitsConverter obj)   SBMLInferUnitsConverter

Each variant is described separately below.


Method variant with the following signature:
SBMLInferUnitsConverter()

Creates a new SBMLInferUnitsConverter object.


Method variant with the following signature:
SBMLInferUnitsConverter(SBMLInferUnitsConverter obj)

Copy constructor; creates a copy of an SBMLInferUnitsConverter object.

Parameters
objthe SBMLInferUnitsConverter object to copy.
def libsbml.SBMLInitialAssignmentConverter.__init__ (   self,
  args 
)

Converter that removes SBML initial assignments.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.

This is an SBML converter for replacing InitialAssignment objects, when possible, by setting the initial value attributes on the model objects being assigned. In other words, for every object that is the target of an initial assignment in the model, the converter evaluates the mathematical expression of the assignment to get a numerical value, and then sets the corresponding attribute of the object to the value. The effects for different kinds of SBML components are as follows:

Component Effect
Compartment Sets the value of the size attribute.
Species Sets the value of either the initialAmount or the initialConcentration attributes, depending on the value of the Species object's hasOnlySubstanceUnits attribute.
Parameter Sets the value of the value attribute.
SpeciesReference Sets the value of the stoichiometry attribute in the Reaction object where the SpeciesReference object appears.

Configuration and use of SBMLInitialAssignmentConverter

SBMLInitialAssignmentConverter is enabled by creating a ConversionProperties object with the option 'expandInitialAssignments', and passing this properties object to SBMLDocument.convert(). The converter offers no other options.

General information about the use of SBML converters

The use of all the converters follows a similar approach. First, one creates a ConversionProperties object and calls ConversionProperties.addOption() on this object with one arguments: a text string that identifies the desired converter. (The text string is specific to each converter; consult the documentation for a given converter to find out how it should be enabled.)

Next, for some converters, the caller can optionally set some converter-specific properties using additional calls to ConversionProperties.addOption(). Many converters provide the ability to configure their behavior to some extent; this is realized through the use of properties that offer different options. The default property values for each converter can be interrogated using the method SBMLConverter.getDefaultProperties() on the converter class in question .

Finally, the caller should invoke the method SBMLDocument.convert() with the ConversionProperties object as an argument.

Example of invoking an SBML converter

The following code fragment illustrates an example using SBMLReactionConverter, which is invoked using the option string 'replaceReactions':

1 config = ConversionProperties()
2 if config != None:
3  config.addOption('replaceReactions')

In the case of SBMLReactionConverter, there are no options to affect its behavior, so the next step is simply to invoke the converter on an SBMLDocument object. Continuing the example code:

1  # Assume that the variable 'document' has been set to an SBMLDocument object.
2  status = document.convert(config)
3  if status != LIBSBML_OPERATION_SUCCESS:
4 # Handle error somehow.
5 print('Error: conversion failed due to the following:')
6 document.printErrors()

Here is an example of using a converter that offers an option. The following code invokes SBMLStripPackageConverter to remove the SBML Level 3 Layout package from a model. It sets the name of the package to be removed by adding a value for the option named 'package' defined by that converter:

1 def strip_layout_example(document):
2  config = ConversionProperties()
3  if config != None:
4 config.addOption('stripPackage')
5 config.addOption('package', 'layout')
6 status = document.convert(config)
7 if status != LIBSBML_OPERATION_SUCCESS:
8  # Handle error somehow.
9  print('Error: unable to strip the Layout package.')
10  print('LibSBML returned error: ' + OperationReturnValue_toString(status).strip())
11  else:
12 # Handle error somehow.
13 print('Error: unable to create ConversionProperties object')

Available SBML converters in libSBML

LibSBML provides a number of built-in converters; by convention, their names end in Converter. The following are the built-in converters provided by libSBML 5.11.0:

This method has multiple variants; they differ in the arguments they accept.

__init__()   SBMLInitialAssignmentConverter
__init__(SBMLInitialAssignmentConverter obj)   SBMLInitialAssignmentConverter

Each variant is described separately below.


Method variant with the following signature:
SBMLInitialAssignmentConverter()

Creates a new SBMLInitialAssignmentConverter object.


Method variant with the following signature:
SBMLInitialAssignmentConverter(SBMLInitialAssignmentConverter obj)

Copy constructor; creates a copy of an SBMLInitialAssignmentConverter object.

Parameters
objthe SBMLInitialAssignmentConverter object to copy.
def libsbml.SBMLLevelVersionConverter.__init__ (   self,
  args 
)

Whole-document SBML Level/Version converter.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.

This SBML converter takes an SBML document having one SBML Level+Version combination, and attempts to convert it to an SBML document having a different Level+Version combination.

This class is also the basis for SBMLDocument.setLevelAndVersion().

Configuration and use of SBMLLevelVersionConverter

SBMLLevelVersionConverter is enabled by creating a ConversionProperties object with the option 'setLevelAndVersion', and passing this properties object to SBMLDocument.convert(). The target SBML Level and Version combination are determined by the value of the SBML namespace set on the ConversionProperties object (using ConversionProperties.setTargetNamespaces()).

In addition, this converter offers one option:

  • 'strict': if this option has the value True, then the validity of the SBML document will be strictly preserved. This means that SBML validation will be performed, and if the original model is not valid or semantics cannot be preserved in the converted model, then conversion will not be performed. Conversely, if this option is set to False, model conversion will always be performed; if any errors are detected related to altered semantics, the errors will be logged in the usual way (i.e., the error log on the SBMLDocument object).

General information about the use of SBML converters

The use of all the converters follows a similar approach. First, one creates a ConversionProperties object and calls ConversionProperties.addOption() on this object with one arguments: a text string that identifies the desired converter. (The text string is specific to each converter; consult the documentation for a given converter to find out how it should be enabled.)

Next, for some converters, the caller can optionally set some converter-specific properties using additional calls to ConversionProperties.addOption(). Many converters provide the ability to configure their behavior to some extent; this is realized through the use of properties that offer different options. The default property values for each converter can be interrogated using the method SBMLConverter.getDefaultProperties() on the converter class in question .

Finally, the caller should invoke the method SBMLDocument.convert() with the ConversionProperties object as an argument.

Example of invoking an SBML converter

The following code fragment illustrates an example using SBMLReactionConverter, which is invoked using the option string 'replaceReactions':

1 config = ConversionProperties()
2 if config != None:
3  config.addOption('replaceReactions')

In the case of SBMLReactionConverter, there are no options to affect its behavior, so the next step is simply to invoke the converter on an SBMLDocument object. Continuing the example code:

1  # Assume that the variable 'document' has been set to an SBMLDocument object.
2  status = document.convert(config)
3  if status != LIBSBML_OPERATION_SUCCESS:
4 # Handle error somehow.
5 print('Error: conversion failed due to the following:')
6 document.printErrors()

Here is an example of using a converter that offers an option. The following code invokes SBMLStripPackageConverter to remove the SBML Level 3 Layout package from a model. It sets the name of the package to be removed by adding a value for the option named 'package' defined by that converter:

1 def strip_layout_example(document):
2  config = ConversionProperties()
3  if config != None:
4 config.addOption('stripPackage')
5 config.addOption('package', 'layout')
6 status = document.convert(config)
7 if status != LIBSBML_OPERATION_SUCCESS:
8  # Handle error somehow.
9  print('Error: unable to strip the Layout package.')
10  print('LibSBML returned error: ' + OperationReturnValue_toString(status).strip())
11  else:
12 # Handle error somehow.
13 print('Error: unable to create ConversionProperties object')

Available SBML converters in libSBML

LibSBML provides a number of built-in converters; by convention, their names end in Converter. The following are the built-in converters provided by libSBML 5.11.0:

This method has multiple variants; they differ in the arguments they accept.

__init__()   SBMLLevelVersionConverter
__init__(SBMLLevelVersionConverter obj)   SBMLLevelVersionConverter

Each variant is described separately below.


Method variant with the following signature:
SBMLLevelVersionConverter()

Creates a new SBMLLevelVersionConverter object.


Method variant with the following signature:
SBMLLevelVersionConverter(SBMLLevelVersionConverter obj)

Copy constructor; creates a copy of an SBMLLevelVersionConverter object.

Parameters
objthe SBMLLevelVersionConverter object to copy.
def libsbml.SBMLLocalParameterConverter.__init__ (   self,
  args 
)

Converter to turn local parameters into global ones.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.

This converter essentially promotes local parameters to global parameters. It works by examining every Reaction object for LocalParameter objects, then creating Parameter objects on the model for each one found, and finally removing the original LocalParameter objects. It creates new identifiers for the fresh Parameter objects by concatenating the identifier of the reaction with the identifier of the original LocalParameter object.

This converter can be useful for software applications that do not have the ability to handle local parameters on reactions. Such applications could check incoming models for local parameters and run those models through this converter before proceeding with other steps.

Configuration and use of SBMLLocalParameterConverter

SBMLLocalParameterConverter is enabled by creating a ConversionProperties object with the option 'promoteLocalParameters', and passing this properties object to SBMLDocument.convert(). The converter offers no other options.

General information about the use of SBML converters

The use of all the converters follows a similar approach. First, one creates a ConversionProperties object and calls ConversionProperties.addOption() on this object with one arguments: a text string that identifies the desired converter. (The text string is specific to each converter; consult the documentation for a given converter to find out how it should be enabled.)

Next, for some converters, the caller can optionally set some converter-specific properties using additional calls to ConversionProperties.addOption(). Many converters provide the ability to configure their behavior to some extent; this is realized through the use of properties that offer different options. The default property values for each converter can be interrogated using the method SBMLConverter.getDefaultProperties() on the converter class in question .

Finally, the caller should invoke the method SBMLDocument.convert() with the ConversionProperties object as an argument.

Example of invoking an SBML converter

The following code fragment illustrates an example using SBMLReactionConverter, which is invoked using the option string 'replaceReactions':

1 config = ConversionProperties()
2 if config != None:
3  config.addOption('replaceReactions')

In the case of SBMLReactionConverter, there are no options to affect its behavior, so the next step is simply to invoke the converter on an SBMLDocument object. Continuing the example code:

1  # Assume that the variable 'document' has been set to an SBMLDocument object.
2  status = document.convert(config)
3  if status != LIBSBML_OPERATION_SUCCESS:
4 # Handle error somehow.
5 print('Error: conversion failed due to the following:')
6 document.printErrors()

Here is an example of using a converter that offers an option. The following code invokes SBMLStripPackageConverter to remove the SBML Level 3 Layout package from a model. It sets the name of the package to be removed by adding a value for the option named 'package' defined by that converter:

1 def strip_layout_example(document):
2  config = ConversionProperties()
3  if config != None:
4 config.addOption('stripPackage')
5 config.addOption('package', 'layout')
6 status = document.convert(config)
7 if status != LIBSBML_OPERATION_SUCCESS:
8  # Handle error somehow.
9  print('Error: unable to strip the Layout package.')
10  print('LibSBML returned error: ' + OperationReturnValue_toString(status).strip())
11  else:
12 # Handle error somehow.
13 print('Error: unable to create ConversionProperties object')

Available SBML converters in libSBML

LibSBML provides a number of built-in converters; by convention, their names end in Converter. The following are the built-in converters provided by libSBML 5.11.0:

This method has multiple variants; they differ in the arguments they accept.

__init__()   SBMLLocalParameterConverter
__init__(SBMLLocalParameterConverter obj)   SBMLLocalParameterConverter

Each variant is described separately below.


Method variant with the following signature:
SBMLLocalParameterConverter(SBMLLocalParameterConverter obj)

Copy constructor; creates a copy of an SBMLLocalParameterConverter object.

Parameters
objthe SBMLLocalParameterConverter object to copy.

Method variant with the following signature:
SBMLLocalParameterConverter()

Creates a new SBMLLocalParameterConverter object.

def libsbml.SBMLReactionConverter.__init__ (   self,
  args 
)

Converter to replace reactions with SBML rate rules.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.

This converter will take an SBML model and replace the definitions of reactions in the model with definitions of SBML rate rules. Equivalent RateRule objects are only created for species mentioned in reactions that have KineticLaw subobjects, since those are the only reactions that have an effect on the rates of change of species in the model; however, the converter removes all Reaction objects in the model after it is done.

Configuration and use of SBMLReactionConverter

SBMLReactionConverter is enabled by creating a ConversionProperties object with the option 'replaceReactions', and passing this properties object to SBMLDocument.convert(). This converter does not offer any additional configuration options.

General information about the use of SBML converters

The use of all the converters follows a similar approach. First, one creates a ConversionProperties object and calls ConversionProperties.addOption() on this object with one arguments: a text string that identifies the desired converter. (The text string is specific to each converter; consult the documentation for a given converter to find out how it should be enabled.)

Next, for some converters, the caller can optionally set some converter-specific properties using additional calls to ConversionProperties.addOption(). Many converters provide the ability to configure their behavior to some extent; this is realized through the use of properties that offer different options. The default property values for each converter can be interrogated using the method SBMLConverter.getDefaultProperties() on the converter class in question .

Finally, the caller should invoke the method SBMLDocument.convert() with the ConversionProperties object as an argument.

Example of invoking an SBML converter

The following code fragment illustrates an example using SBMLReactionConverter, which is invoked using the option string 'replaceReactions':

1 config = ConversionProperties()
2 if config != None:
3  config.addOption('replaceReactions')

In the case of SBMLReactionConverter, there are no options to affect its behavior, so the next step is simply to invoke the converter on an SBMLDocument object. Continuing the example code:

1  # Assume that the variable 'document' has been set to an SBMLDocument object.
2  status = document.convert(config)
3  if status != LIBSBML_OPERATION_SUCCESS:
4 # Handle error somehow.
5 print('Error: conversion failed due to the following:')
6 document.printErrors()

Here is an example of using a converter that offers an option. The following code invokes SBMLStripPackageConverter to remove the SBML Level 3 Layout package from a model. It sets the name of the package to be removed by adding a value for the option named 'package' defined by that converter:

1 def strip_layout_example(document):
2  config = ConversionProperties()
3  if config != None:
4 config.addOption('stripPackage')
5 config.addOption('package', 'layout')
6 status = document.convert(config)
7 if status != LIBSBML_OPERATION_SUCCESS:
8  # Handle error somehow.
9  print('Error: unable to strip the Layout package.')
10  print('LibSBML returned error: ' + OperationReturnValue_toString(status).strip())
11  else:
12 # Handle error somehow.
13 print('Error: unable to create ConversionProperties object')

Available SBML converters in libSBML

LibSBML provides a number of built-in converters; by convention, their names end in Converter. The following are the built-in converters provided by libSBML 5.11.0:

This method has multiple variants; they differ in the arguments they accept.

__init__()   SBMLReactionConverter
__init__(SBMLReactionConverter obj)   SBMLReactionConverter

Each variant is described separately below.


Method variant with the following signature:
SBMLReactionConverter(SBMLReactionConverter obj)

Copy constructor; creates a copy of an SBMLReactionConverter object.

Parameters
objthe SBMLReactionConverter object to copy.

Method variant with the following signature:
SBMLReactionConverter()

Creates a new SBMLReactionConverter object.

def libsbml.SBMLRuleConverter.__init__ (   self,
  args 
)

Converter that sorts SBML rules and assignments.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.

This converter reorders assignments in a model. Specifically, it sorts the list of assignment rules (i.e., the AssignmentRule objects contained in the ListOfAssignmentRules within the Model object) and the initial assignments (i.e., the InitialAssignment objects contained in the ListOfInitialAssignments) such that, within each set, assignments that depend on prior values are placed after the values are set. For example, if there is an assignment rule stating a = b + 1, and another rule stating b = 3, the list of rules is sorted and the rules are arranged so that the rule for b = 3 appears before the rule for a = b + 1. Similarly, if dependencies of this sort exist in the list of initial assignments in the model, the initial assignments are sorted as well.

Beginning with SBML Level 2, assignment rules have no ordering required—the order in which the rules appear in an SBML file has no significance. Software tools, however, may need to reorder assignments for purposes of evaluating them. For example, for simulators that use time integration methods, it would be a good idea to reorder assignment rules such as the following,

b = a + 10 seconds
a = time

so that the evaluation of the rules is independent of integrator step sizes. (This is due to the fact that, in this case, the order in which the rules are evaluated changes the result.) SBMLRuleConverter can be used to reorder the SBML objects regardless of whether the input file contained them in the desired order.

Note that the two sets of SBML assignments (list of assignment rules on the one hand, and list of initial assignments on the other hand) are handled independently. In an SBML model, these entities are treated differently and no amount of sorting can deal with inter-dependencies between assignments of the two kinds.

Configuration and use of SBMLRuleConverter

SBMLRuleConverter is enabled by creating a ConversionProperties object with the option 'sortRules', and passing this properties object to SBMLDocument.convert(). This converter offers no other options.

General information about the use of SBML converters

The use of all the converters follows a similar approach. First, one creates a ConversionProperties object and calls ConversionProperties.addOption() on this object with one arguments: a text string that identifies the desired converter. (The text string is specific to each converter; consult the documentation for a given converter to find out how it should be enabled.)

Next, for some converters, the caller can optionally set some converter-specific properties using additional calls to ConversionProperties.addOption(). Many converters provide the ability to configure their behavior to some extent; this is realized through the use of properties that offer different options. The default property values for each converter can be interrogated using the method SBMLConverter.getDefaultProperties() on the converter class in question .

Finally, the caller should invoke the method SBMLDocument.convert() with the ConversionProperties object as an argument.

Example of invoking an SBML converter

The following code fragment illustrates an example using SBMLReactionConverter, which is invoked using the option string 'replaceReactions':

1 config = ConversionProperties()
2 if config != None:
3  config.addOption('replaceReactions')

In the case of SBMLReactionConverter, there are no options to affect its behavior, so the next step is simply to invoke the converter on an SBMLDocument object. Continuing the example code:

1  # Assume that the variable 'document' has been set to an SBMLDocument object.
2  status = document.convert(config)
3  if status != LIBSBML_OPERATION_SUCCESS:
4 # Handle error somehow.
5 print('Error: conversion failed due to the following:')
6 document.printErrors()

Here is an example of using a converter that offers an option. The following code invokes SBMLStripPackageConverter to remove the SBML Level 3 Layout package from a model. It sets the name of the package to be removed by adding a value for the option named 'package' defined by that converter:

1 def strip_layout_example(document):
2  config = ConversionProperties()
3  if config != None:
4 config.addOption('stripPackage')
5 config.addOption('package', 'layout')
6 status = document.convert(config)
7 if status != LIBSBML_OPERATION_SUCCESS:
8  # Handle error somehow.
9  print('Error: unable to strip the Layout package.')
10  print('LibSBML returned error: ' + OperationReturnValue_toString(status).strip())
11  else:
12 # Handle error somehow.
13 print('Error: unable to create ConversionProperties object')

Available SBML converters in libSBML

LibSBML provides a number of built-in converters; by convention, their names end in Converter. The following are the built-in converters provided by libSBML 5.11.0:

This method has multiple variants; they differ in the arguments they accept.

__init__()   SBMLRuleConverter
__init__(SBMLRuleConverter obj)   SBMLRuleConverter

Each variant is described separately below.


Method variant with the following signature:
SBMLRuleConverter()

Creates a new SBMLLevelVersionConverter object.


Method variant with the following signature:
SBMLRuleConverter(SBMLRuleConverter obj)

Copy constructor; creates a copy of an SBMLLevelVersionConverter object.

Parameters
objthe SBMLLevelVersionConverter object to copy.
def libsbml.SBMLStripPackageConverter.__init__ (   self,
  args 
)

Converter that removes SBML Level 3 packages.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.

This SBML converter takes an SBML document and removes (strips) an SBML Level 3 package from it. No conversion is performed; the package constructs are simply removed from the SBML document. The package to be stripped is determined by the value of the option 'package' on the conversion properties.

Configuration and use of SBMLStripPackageConverter

SBMLStripPackageConverter is enabled by creating a ConversionProperties object with the option 'stripPackage', and passing this properties object to SBMLDocument.convert(). This converter takes one required option:

  • 'package': the value of this option should be a text string, the nickname of the SBML Level 3 package to be stripped from the model.

General information about the use of SBML converters

The use of all the converters follows a similar approach. First, one creates a ConversionProperties object and calls ConversionProperties.addOption() on this object with one arguments: a text string that identifies the desired converter. (The text string is specific to each converter; consult the documentation for a given converter to find out how it should be enabled.)

Next, for some converters, the caller can optionally set some converter-specific properties using additional calls to ConversionProperties.addOption(). Many converters provide the ability to configure their behavior to some extent; this is realized through the use of properties that offer different options. The default property values for each converter can be interrogated using the method SBMLConverter.getDefaultProperties() on the converter class in question .

Finally, the caller should invoke the method SBMLDocument.convert() with the ConversionProperties object as an argument.

Example of invoking an SBML converter

The following code fragment illustrates an example using SBMLReactionConverter, which is invoked using the option string 'replaceReactions':

1 config = ConversionProperties()
2 if config != None:
3  config.addOption('replaceReactions')

In the case of SBMLReactionConverter, there are no options to affect its behavior, so the next step is simply to invoke the converter on an SBMLDocument object. Continuing the example code:

1  # Assume that the variable 'document' has been set to an SBMLDocument object.
2  status = document.convert(config)
3  if status != LIBSBML_OPERATION_SUCCESS:
4 # Handle error somehow.
5 print('Error: conversion failed due to the following:')
6 document.printErrors()

Here is an example of using a converter that offers an option. The following code invokes SBMLStripPackageConverter to remove the SBML Level 3 Layout package from a model. It sets the name of the package to be removed by adding a value for the option named 'package' defined by that converter:

1 def strip_layout_example(document):
2  config = ConversionProperties()
3  if config != None:
4 config.addOption('stripPackage')
5 config.addOption('package', 'layout')
6 status = document.convert(config)
7 if status != LIBSBML_OPERATION_SUCCESS:
8  # Handle error somehow.
9  print('Error: unable to strip the Layout package.')
10  print('LibSBML returned error: ' + OperationReturnValue_toString(status).strip())
11  else:
12 # Handle error somehow.
13 print('Error: unable to create ConversionProperties object')

Available SBML converters in libSBML

LibSBML provides a number of built-in converters; by convention, their names end in Converter. The following are the built-in converters provided by libSBML 5.11.0:

This method has multiple variants; they differ in the arguments they accept.

__init__()   SBMLStripPackageConverter
__init__(SBMLStripPackageConverter obj)   SBMLStripPackageConverter

Each variant is described separately below.


Method variant with the following signature:
SBMLStripPackageConverter()

Creates a new SBMLStripPackageConverter object.


Method variant with the following signature:
SBMLStripPackageConverter(SBMLStripPackageConverter obj)

Copy constructor; creates a copy of an SBMLStripPackageConverter object.

Parameters
objthe SBMLStripPackageConverter object to copy.
def libsbml.SBMLUnitsConverter.__init__ (   self,
  args 
)

Converts a model's existing units to SI units.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.

This SBML converter converts the units in a model to base SI units, that is, using only the units metre, kilogram, second, ampere, kelvin, mole and candela.

Unit conversion will only be performed on models that are fully unit consistent, meaning that all objects have units associated with them and there are no literal numbers with unspecified units. In the case of an SBML Level 3 model involving math expressions, this means that the timeUnits attribute on the Model object must be set, and if there are any reactions in the model, the extentUnits attribute on the Model object must also be set.

Configuration and use of SBMLUnitsConverter

SBMLUnitsConverter is enabled by creating a ConversionProperties object with the option 'units', and passing this properties object to SBMLDocument.convert(). This converter takes one optional option:

  • 'removeUnusedUnits': the value of this property should be a Boolean. If it is True, it tells the unit convert to remove any unused UnitDefinition objects after conversion is complete. ('Unused' units are units that are not referenced by any object in the model.) If the value is False, unused UnitDefinition objects are not removed from the model. The default is True.

General information about the use of SBML converters

The use of all the converters follows a similar approach. First, one creates a ConversionProperties object and calls ConversionProperties.addOption() on this object with one arguments: a text string that identifies the desired converter. (The text string is specific to each converter; consult the documentation for a given converter to find out how it should be enabled.)

Next, for some converters, the caller can optionally set some converter-specific properties using additional calls to ConversionProperties.addOption(). Many converters provide the ability to configure their behavior to some extent; this is realized through the use of properties that offer different options. The default property values for each converter can be interrogated using the method SBMLConverter.getDefaultProperties() on the converter class in question .

Finally, the caller should invoke the method SBMLDocument.convert() with the ConversionProperties object as an argument.

Example of invoking an SBML converter

The following code fragment illustrates an example using SBMLReactionConverter, which is invoked using the option string 'replaceReactions':

1 config = ConversionProperties()
2 if config != None:
3  config.addOption('replaceReactions')

In the case of SBMLReactionConverter, there are no options to affect its behavior, so the next step is simply to invoke the converter on an SBMLDocument object. Continuing the example code:

1  # Assume that the variable 'document' has been set to an SBMLDocument object.
2  status = document.convert(config)
3  if status != LIBSBML_OPERATION_SUCCESS:
4 # Handle error somehow.
5 print('Error: conversion failed due to the following:')
6 document.printErrors()

Here is an example of using a converter that offers an option. The following code invokes SBMLStripPackageConverter to remove the SBML Level 3 Layout package from a model. It sets the name of the package to be removed by adding a value for the option named 'package' defined by that converter:

1 def strip_layout_example(document):
2  config = ConversionProperties()
3  if config != None:
4 config.addOption('stripPackage')
5 config.addOption('package', 'layout')
6 status = document.convert(config)
7 if status != LIBSBML_OPERATION_SUCCESS:
8  # Handle error somehow.
9  print('Error: unable to strip the Layout package.')
10  print('LibSBML returned error: ' + OperationReturnValue_toString(status).strip())
11  else:
12 # Handle error somehow.
13 print('Error: unable to create ConversionProperties object')

Available SBML converters in libSBML

LibSBML provides a number of built-in converters; by convention, their names end in Converter. The following are the built-in converters provided by libSBML 5.11.0:

This method has multiple variants; they differ in the arguments they accept.

__init__()   SBMLUnitsConverter
__init__(SBMLUnitsConverter obj)   SBMLUnitsConverter

Each variant is described separately below.


Method variant with the following signature:
SBMLUnitsConverter(SBMLUnitsConverter obj)

Copy constructor; creates a copy of an SBMLUnitsConverter object.

Parameters
objthe SBMLUnitsConverter object to copy.

Method variant with the following signature:
SBMLUnitsConverter()

Creates a new SBMLUnitsConverter object.

def libsbml.SBMLValidator.__init__ (   self,
  args 
)

Base class for SBML validators.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

LibSBML implements facilities for verifying that a given SBML document is valid according to the SBML specifications; it also exposes the validation interface so that user programs and SBML Level 3 package authors may use the facilities to implement new validators. There are two main interfaces to libSBML's validation facilities, based on the classes Validator and SBMLValidator.

The Validator class is the basis of the system for validating an SBML document against the validation rules defined in the SBML specifications. The scheme used by Validator relies is compact and uses the visitor programming pattern, but it relies on C/C++ features and is not directly accessible from language bindings. SBMLValidator offers a framework for straightforward class-based extensibility, so that user code can subclass SBMLValidator to implement new validation systems, different validators can be introduced or turned off at run-time, and interfaces can be provided in the libSBML language bindings. SBMLValidator can call Validator functionality internally (as is the case in the current implementation of SBMLInternalValidator) or use entirely different implementation approaches, as necessary.

Users of libSBML may already be familiar with the facilities encompassed by the validation system, in the form of the consistency-checking methods defined on SBMLDocument. The methods SBMLDocument.setConsistencyChecks(), SBMLDocument.checkConsistency(), SBMLDocument.checkInternalConsistency() and other method of that sort are in fact implemented via SBMLValidator, specifically as methods on the class SBMLInternalValidator.

Authors may use SBMLValidator as the base class for their own validator extensions to libSBML. The class SBMLInternalValidator may serve as a code example for how to implement such things.

This method has multiple variants; they differ in the arguments they accept.

__init__()   SBMLValidator
__init__(SBMLValidator orig)   SBMLValidator

Each variant is described separately below.


Method variant with the following signature:
SBMLValidator(SBMLValidator orig)

Copy constructor; creates a copy of an SBMLValidator object.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
SBMLValidator()

Creates a new SBMLValidator.

def libsbml.XMLAttributes.__init__ (   self,
  args 
)

A list of attributes on an XML element.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

In libSBML's XML interface layer, attributes on an element are stored as a list of values kept in an XMLAttributes object. XMLAttributes has methods for adding and removing individual attributes as well as performing other actions on the list of attributes. Classes in libSBML that represent nodes in an XML document (i.e., XMLNode and its parent class, XMLToken) use XMLAttributes objects to manage attributes on XML elements.

Attributes on an XML element can be written in one of two forms:

  • name='value'
  • prefix:name='value'

An attribute in XML must always have a value, and the value must always be a quoted string; i.e., it is always name='value' and not name=value. An empty value is represented simply as an empty string; i.e., name=''.

In cases when a prefix is provided with an attribute name, general XML validity rules require that the prefix is an XML namespace prefix that has been declared somewhere else (possibly as an another attribute on the same element). However, the XMLAttributes class does not test for the proper existence or declaration of XML namespaces—callers must arrange to do this themselves in some other way. This class only provides facilities for tracking and manipulating attributes and their prefix/URI/name/value components.

Note
Note that although XMLAttributes provides operations that can manipulate attributes based on a numerical index, XML attributes are in fact unordered when they appear in files and data streams. The XMLAttributes class provides some list-like facilities, but it is only for the convenience of callers. (For example, it permits callers to loop across all attributes more easily.) Users should keep in mind that the order in which attributes are stored in XMLAttributes objects has no real impact on the order in which the attributes are read or written from an XML file or data stream.
See also
XMLTriple
XMLNode
XMLToken

This method has multiple variants; they differ in the arguments they accept.

__init__()   XMLAttributes
__init__(XMLAttributes orig)   XMLAttributes

Each variant is described separately below.


Method variant with the following signature:
XMLAttributes()

Creates a new, empty XMLAttributes object.


Method variant with the following signature:
XMLAttributes(XMLAttributes orig)

Copy constructor; creates a copy of this XMLAttributes object.

orig the XMLAttributes object to copy.

Exceptions
XMLConstructorExceptionThrown if the argument orig is None.
def libsbml.XMLNamespaces.__init__ (   self,
  args 
)

An XML Namespace.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

This class serves to organize functionality for tracking XML namespaces in a document or data stream. The namespace declarations are stored as a list of pairs of XML namespace URIs and prefix strings. These correspond to the parts of a namespace declaration on an XML element. For example, in the following XML fragment,

<annotation>
<mysim:nodecolors xmlns:mysim='urn:lsid:mysim.org'
     mysim:bgcolor='green' mysim:fgcolor='white'/>
</annotation>

there is one namespace declaration. Its URI is urn:lsid:mysim.org and its prefix is mysim. This pair could be stored as one item in an XMLNamespaces list.

XMLNamespaces provides various methods for manipulating the list of prefix-URI pairs. Individual namespaces stored in a given XMLNamespace object instance can be retrieved based on their index using XMLNamespaces.getPrefix(), or by their characteristics such as their URI or position in the list.

This method has multiple variants; they differ in the arguments they accept.

__init__()   XMLNamespaces
__init__(XMLNamespaces orig)   XMLNamespaces

Each variant is described separately below.


Method variant with the following signature:
XMLNamespaces(XMLNamespaces orig)

Copy constructor; creates a copy of this XMLNamespaces list.

Parameters
origthe XMLNamespaces object to copy
Exceptions
XMLConstructorExceptionThrown if the argument orig is None.

Method variant with the following signature:
XMLNamespaces()

Creates a new empty list of XML namespace declarations.

def libsbml.XMLToken.__init__ (   self,
  args 
)

A token in an XML stream.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The libSBML XML parser interface can read an XML file or data stream and convert the contents into tokens. The tokens represent items in the XML stream, either XML elements (start or end tags) or text that appears as content inside an element. The XMLToken class is libSBML's low-level representation of these entities.

Each XMLToken has the following information associated with it:

  1. Qualified name: every XML element or XML attribute has a name (e.g., for the element <mytag>, the name is 'mytag'), but this name may be qualified with a namespace (e.g., it may appear as <someNamespace:mytag> in the input). An XMLToken stores the name of a token, along with any namespace qualification present, through the use of an XMLTriple object. This object stores the bare name of the element, its XML namespace prefix (if any), and the XML namespace with which that prefix is associated.
  2. Namespaces: An XML token can have one or more XML namespaces associated with it. These namespaces may be specified explicitly on the element or inherited from parent elements. In libSBML, a list of namespaces is stored in an XMLNamespaces object. An XMLToken possesses a field for storing an XMLNamespaces object.
  3. Attributes: XML elements can have attributes associated with them, and these attributes can have values assigned to them. The set of attribute-value pairs is stored in an XMLAttributes object stored in an XMLToken object. (Note: only elements can have attributes—text blocks cannot have them in XML.)
  4. Line number: the line number in the input where the token appears.
  5. Column number: the column number in the input where the token appears.

The XMLToken class serves as base class for XMLNode. XML lends itself to a tree-structured representation, and in libSBML, the nodes in an XML document tree are XMLNode objects. Most higher-level libSBML classes and methods that offer XML-level functionality (such as the methods on SBase for interacting with annotations) work with XMLNode objects rather than XMLToken objects directly.

See also
XMLNode
XMLTriple
XMLAttributes
XMLNamespaces

This method has multiple variants; they differ in the arguments they accept.

__init__()   XMLToken
__init__(XMLTriple triple, XMLAttributes attributes, XMLNamespaces namespaces, long line=0, long column=0)   XMLToken
__init__(XMLTriple triple, XMLAttributes attributes, XMLNamespaces namespaces, long line=0)   XMLToken
__init__(XMLTriple triple, XMLAttributes attributes, XMLNamespaces namespaces)   XMLToken
__init__(XMLTriple triple, XMLAttributes attributes, long line=0, long column=0)   XMLToken
__init__(XMLTriple triple, XMLAttributes attributes, long line=0)   XMLToken
__init__(XMLTriple triple, XMLAttributes attributes)   XMLToken
__init__(XMLTriple triple, long line=0, long column=0)   XMLToken
__init__(XMLTriple triple, long line=0)   XMLToken
__init__(XMLTriple triple)   XMLToken
__init__(string chars, long line=0, long column=0)   XMLToken
__init__(string chars, long line=0)   XMLToken
__init__(string chars)   XMLToken
__init__(XMLToken orig)   XMLToken

Each variant is described separately below.


Method variant with the following signature:
XMLToken(string chars, long line = 0, long column = 0)

Creates a text object.

Parameters
charsa string, the text to be added to the XMLToken object.
linea long integer, the line number to associate with the token (default = 0).
columna long integer, the column number to associate with the token (default = 0).
Exceptions
XMLConstructorExceptionThrown if the argument chars is None.

Method variant with the following signature:
XMLToken()

Creates a new empty XMLToken object.


Method variant with the following signature:
XMLToken(XMLTriple triple, XMLAttributes attributes, XMLNamespaces namespaces, long line = 0, long column = 0)

Creates an XML start element with attributes and namespace declarations.

Parameters
triplean XMLTriple object describing the start tag.
attributesXMLAttributes, the attributes to set on the element to be created.
namespacesXMLNamespaces, the namespaces to set on the element to be created.
linea long integer, the line number to associate with the token (default = 0).
columna long integer, the column number to associate with the token (default = 0).

Method variant with the following signature:
XMLToken(XMLToken orig)

Copy constructor; creates a copy of this XMLToken object.

Parameters
origthe XMLToken object to copy.
Exceptions
XMLConstructorExceptionThrown if the argument orig is None.

Method variant with the following signature:
XMLToken(XMLTriple triple, XMLAttributes attributes, long line = 0, long column = 0)

Creates an XML start element with attributes.

Parameters
triplean XMLTriple object describing the start tag.
attributesXMLAttributes, the attributes to set on the element to be created.
linea long integer, the line number to associate with the token (default = 0).
columna long integer, the column number to associate with the token (default = 0).

The XML namespace component of this XMLToken object will be left empty. See the other variants of the XMLToken constructors for versions that take namespace arguments.


Method variant with the following signature:
XMLToken(XMLTriple triple, long line = 0, long column = 0)

Creates an XML end element.

Parameters
triplean XMLTriple object describing the end tag.
linea long integer, the line number to associate with the token (default = 0).
columna long integer, the column number to associate with the token (default = 0).
def libsbml.XMLNode.__init__ (   self,
  args 
)

A node in libSBML's XML document tree.

LibSBML implements an XML abstraction layer. This layer presents a uniform XML interface to calling programs regardless of which underlying XML parser libSBML has actually been configured to use. The basic data object in the XML abstraction is a node, represented by XMLNode.

An XMLNode can contain any number of children. Each child is another XMLNode, thereby forming a tree. The methods XMLNode.getNumChildren() and XMLNode.getChild() can be used to access the tree structure starting from a given node.

Each XMLNode is subclassed from XMLToken, and thus has the same methods available as XMLToken. These methods include XMLToken.getNamespaces(), XMLToken.getPrefix(), XMLToken.getName(), XMLToken.getURI(), and XMLToken.getAttributes().

Conversion between an XML string and an XMLNode

LibSBML provides the following utility functions for converting an XML string (e.g., <annotation>...</annotation>) to/from an XMLNode object.

The returned XMLNode object by XMLNode.convertStringToXMLNode() is a dummy root (container) XMLNode if the given XML string has two or more top-level elements (e.g., "<p>...</p><p>...</p>"). In the dummy root node, each top-level element in the given XML string is contained as a child XMLNode. XMLToken.isEOF() can be used to identify if the returned XMLNode object is a dummy node or not. Here is an example:

1 xn = XMLNode.convertStringToXMLNode('<p></p>')
2 if xn == None:
3  # Do something to handle exceptional situation.
4 
5 elif xn.isEOF():
6  # Node is a dummy node.
7 
8 else:
9  # None is not a dummy node.

This method has multiple variants; they differ in the arguments they accept.

__init__()   XMLNode
__init__(XMLToken token)   XMLNode
__init__(XMLTriple triple, XMLAttributes attributes, XMLNamespaces namespaces, long line=0, long column=0)   XMLNode
__init__(XMLTriple triple, XMLAttributes attributes, XMLNamespaces namespaces, long line=0)   XMLNode
__init__(XMLTriple triple, XMLAttributes attributes, XMLNamespaces namespaces)   XMLNode
__init__(XMLTriple triple, XMLAttributes attributes, long line=0, long column=0)   XMLNode
__init__(XMLTriple triple, XMLAttributes attributes, long line=0)   XMLNode
__init__(XMLTriple triple, XMLAttributes attributes)   XMLNode
__init__(XMLTriple triple, long line=0, long column=0)   XMLNode
__init__(XMLTriple triple, long line=0)   XMLNode
__init__(XMLTriple triple)   XMLNode
__init__(string chars, long line=0, long column=0)   XMLNode
__init__(string chars, long line=0)   XMLNode
__init__(string chars)   XMLNode
__init__(XMLInputStream stream)   XMLNode
__init__(XMLNode orig)   XMLNode

Each variant is described separately below.


Method variant with the following signature:
XMLNode(string chars, long line = 0, long column = 0)

Creates a text XMLNode.

Parameters
charsa string, the text to be added to the XMLToken
linea long integer, the line number (default = 0).
columna long integer, the column number (default = 0).

Method variant with the following signature:
XMLNode(XMLNode orig)

Copy constructor; creates a copy of this XMLNode.

Parameters
origthe XMLNode instance to copy.
Exceptions
XMLConstructorExceptionThrown if the argument orig is None.

Method variant with the following signature:
XMLNode(XMLToken token)

Creates a new XMLNode by copying an XMLToken object.

Parameters
tokenXMLToken to be copied to XMLNode

Method variant with the following signature:
XMLNode()

Creates a new empty XMLNode with no children.


Method variant with the following signature:
XMLNode(XMLTriple triple, XMLAttributes attributes, XMLNamespaces namespaces, long line = 0, long column = 0)

Creates a new start element XMLNode with the given set of attributes and namespace declarations.

Parameters
tripleXMLTriple.
attributesXMLAttributes, the attributes to set.
namespacesXMLNamespaces, the namespaces to set.
linea long integer, the line number (default = 0).
columna long integer, the column number (default = 0).

Method variant with the following signature:
XMLNode(XMLTriple triple, XMLAttributes attributes, long line = 0, long column = 0)

Creates a start element XMLNode with the given set of attributes.

Parameters
tripleXMLTriple.
attributesXMLAttributes, the attributes to set.
linea long integer, the line number (default = 0).
columna long integer, the column number (default = 0).

Method variant with the following signature:
XMLNode(XMLTriple triple, long line = 0, long column = 0)

Creates an end element XMLNode.

Parameters
tripleXMLTriple.
linea long integer, the line number (default = 0).
columna long integer, the column number (default = 0).
def libsbml.XMLTriple.__init__ (   self,
  args 
)

A qualified XML name.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

A 'triple' in the libSBML XML layer encapsulates the notion of qualified name, meaning an element name or an attribute name with an optional namespace qualifier. Triples by themselves are not entities in an XML stream—they are not, for example, elements or attributes; rather, XMLTriple is used in libSBML to construct these other kinds of objects.

An XMLTriple instance carries up to three data items:

  1. The name of the attribute or element; that is, the attribute name as it appears in an XML document or data stream;
  2. The XML namespace prefix (if any) of the attribute. For example, in the following fragment of XML, the namespace prefix is the string mysim and it appears on both the element someelement and the attribute attribA. When both the element and the attribute are stored as XMLTriple objects, their prefix is mysim.
    <mysim:someelement mysim:attribA='value' />
    
  3. The XML namespace URI with which the prefix is associated. In XML, every namespace used must be declared and mapped to a URI.

XMLTriple objects are the lowest-level data item in the XML layer of libSBML. Other objects such as XMLToken make use of XMLTriple objects.

See also
XMLToken
XMLNode
XMLAttributes
XMLNamespaces

This method has multiple variants; they differ in the arguments they accept.

__init__()   XMLTriple
__init__(string name, string uri, string prefix)   XMLTriple
__init__(string triplet, char sepchar)   XMLTriple
__init__(string triplet)   XMLTriple
__init__(XMLTriple orig)   XMLTriple

Each variant is described separately below.


Method variant with the following signature:
XMLTriple(string triplet, char sepchar = ' ')

Creates an XMLTriple object by splitting a given string at a given separator character.

The 'triplet' in this case is a string that may be in one of the following three possible formats:

  1. name
  2. URIxname
  3. URIxnamexprefix

where x represents the separator character, sepchar.

Parameters
tripleta string representing the triplet as shown above
sepchara character, the sepchar used in the triplet
Exceptions
XMLConstructorExceptionThrown if the argument triplet is None.

Method variant with the following signature:
XMLTriple()

Creates a new, empty XMLTriple object.


Method variant with the following signature:
XMLTriple(string name, string uri, string prefix)

Creates a new XMLTriple object with a given name, uri and and prefix.

Parameters
namea string, the name for the entity represented by this object.
uria string, the XML namespace URI associated with the prefix.
prefixa string, the XML namespace prefix for this triple.
Exceptions
XMLConstructorExceptionThrown if any of the arguments are None.

Method variant with the following signature:
XMLTriple(XMLTriple orig)

Copy constructor; creates a copy of this XMLTriple object.

Parameters
origthe XMLTriple object to copy.
Exceptions
XMLConstructorExceptionThrown if the argument orig is None.
def libsbml.XMLOutputStream.__init__ (   self,
  args 
)

Interface to an XML output stream.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

SBML content is serialized using XML; the resulting data can be stored and read to/from a file or data stream. Low-level XML parsers such as Xerces provide facilities to read XML data. To permit the use of different XML parsers (Xerces, Expat or libxml2), libSBML implements an abstraction layer. XMLInputStream and XMLOutputStream are two parts of that abstraction layer.

XMLOutputStream provides a wrapper above output streams to facilitate writing XML. XMLOutputStream keeps track of start and end elements, indentation, XML namespace prefixes, and more. The interface provides features for converting non-text data types into appropriate textual form; this takes the form of overloaded writeAttribute(...) methods that allow users to simply use the same method with any data type. For example, suppose an element testElement has two attributes, size and id, and the attributes are variables in your code as follows:

1 size = 3.2;
2 id = 'id';

Then, the element and the attributes can be written to the standard output stream (provided as cout in the libSBML language bindings) as follows:

1 from libsbml import *
2 
3 size = 3.2;
4 id = 'id';
5 
6 # Create an XMLOutputStream object that will write to the standard
7 # output stream, which is provide in libSBML's Python language
8 # interface as the object 'libsbml.cout'. Since we imported * from
9 # the libsbml module, we can simply refer to it as 'cout' here:
10 
11 output_stream = XMLOutputStream(cout)
12 
13 # Create the start element, write the attributes, and close the
14 # element. The output is written immediately by each method.
15 
16 output_stream.startElement('testElement')
17 output_stream.writeAttribute('size', size)
18 output_stream.writeAttribute('id', id)
19 output_stream.endElement('testElement')

Other classes in SBML take XMLOutputStream objects as arguments, and use that to write elements and attributes seamlessly to the XML output stream.

It is also worth noting that unlike XMLInputStream, XMLOutputStream is actually independent of the underlying XML parsers. It does not use the XML parser libraries at all.

Note
The convenience of the XMLInputStream and XMLOutputStream abstraction may be useful for developers interested in creating parsers for other XML formats besides SBML. It can provide developers with a layer above more basic XML parsers, as well as some useful programmatic elements such as XMLToken, XMLError, etc.
See also
XMLInputStream

Creates a new XMLOutputStream that wraps the given stream.

__init__(ostream stream, string encoding, bool writeXMLDecl=True, string programName, string programVersion)   XMLOutputStream
__init__(ostream stream, string encoding, bool writeXMLDecl=True, string programName)   XMLOutputStream
__init__(ostream stream, string encoding, bool writeXMLDecl=True)   XMLOutputStream
__init__(ostream stream, string encoding)   XMLOutputStream
__init__(ostream stream)   XMLOutputStream
Parameters
streamthe input stream to wrap.
encodingthe XML encoding to declare in the output. This value should be "UTF-8" for SBML documents. The default value is "UTF-8" if no value is supplied for this parameter.
writeXMLDeclwhether to write a standard XML declaration at the beginning of the content written on stream. The default is true.
programNamean optional program name to write as a comment in the output stream.
programVersionan optional version identification string to write as a comment in the output stream.
Documentation note:
The native C++ implementation of this method defines a default argument value. In the documentation generated for different libSBML language bindings, you may or may not see corresponding arguments in the method declarations. For example, in Java and C#, a default argument is handled by declaring two separate methods, with one of them having the argument and the other one lacking the argument. However, the libSBML documentation will be identical for both methods. Consequently, if you are reading this and do not see an argument even though one is described, please look for descriptions of other variants of this method near where this one appears in the documentation.
def libsbml.XMLInputStream.__init__ (   self,
  args 
)

An interface to an XML input stream.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

SBML content is serialized using XML; the resulting data can be stored and read to/from a file or data stream. Low-level XML parsers such as Xerces provide facilities to read XML data. To permit the use of different XML parsers (Xerces, Expat or libxml2), libSBML implements an abstraction layer. XMLInputStream and XMLOutputStream are two parts of that abstraction layer.

XMLInputStream is an interface to a file or text string containing XML. It wraps the content to be read, as well as the low-level XML parser to be used and an XMLErrorLog to record errors and other issues (if any arise). Internally, the content will be in the form of either a pointer to a file name or a character string; XMLInputStream knows the form of the content and acts appropriately. Other libSBML object classes use XMLInputStream as their interface for all read operations on the XML data. XMLInputStream provides the functionality to extract data in the form of XMLToken objects. It logs any errors encountered while reading. It also keeps track of whether a read operation has failed irrecoverably or determines whether it is safe to continue reading.

SBMLNamespaces objects can be associated with an XMLInputStream; this facilitates logging errors related to reading XML attributes and elements that may only be relevant to particular Level and Version combinations of SBML.

Note
The convenience of the XMLInputStream and XMLOutputStream abstraction may be useful for developers interested in creating parsers for other XML formats besides SBML. It can provide developers with a layer above more basic XML parsers, as well as some useful programmatic elements such as XMLToken, XMLError, etc.
See also
XMLOutputStream

Creates a new XMLInputStream.

__init__(string content, bool isFile=True, string library, XMLErrorLog errorLog=None)   XMLInputStream
__init__(string content, bool isFile=True, string library)   XMLInputStream
__init__(string content, bool isFile=True)   XMLInputStream
__init__(string content)   XMLInputStream
Parameters
contentthe source of the stream.
isFilea boolean flag to indicate whether content is a file name. If true, content is assumed to be the file from which the XML content is to be read. If false, content is taken to be a string that is the content to be read.
librarythe name of the parser library to use.
errorLogthe XMLErrorLog object to use.
Documentation note:
The native C++ implementation of this method defines a default argument value. In the documentation generated for different libSBML language bindings, you may or may not see corresponding arguments in the method declarations. For example, in Java and C#, a default argument is handled by declaring two separate methods, with one of them having the argument and the other one lacking the argument. However, the libSBML documentation will be identical for both methods. Consequently, if you are reading this and do not see an argument even though one is described, please look for descriptions of other variants of this method near where this one appears in the documentation.
def libsbml.XMLError.__init__ (   self,
  args 
)

XML-level errors, warnings and other diagnostics.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

LibSBML can be configured to use any of a number of XML parsers; at the time of this writing, libSBML supports Xerces versions 2.4 through 3.1, Expat version 1.95.x and higher, and libxml2 version 2.6.16 and higher. These parsers each report different status codes for the various exceptions that can occur during XML processing. The XMLError object class abstracts away from the particular diagnostics reported by the different parsers and presents a single uniform interface and set of status codes, along with operations for manipulating the error objects.

When the libSBML XML parser layer encounters an error in the XML content being processed, or when there is something else wrong (such as an out-of-memory condition), the problems are reported as XMLError objects. Each XMLError object instance has an identification number that identifies the nature of the problem. This error identifier is one of the constants listed in the next section below. Applications can use the error identifiers as a means of recognizing the error encountered and changing their behavior if desired.

Integer error codes are useful for software, but not so much for telling humans what happened. For this reason, XMLError also provides two text messages describing the nature of the error. These messages are accessible by means of the methods XMLError.getShortMessage() and XMLError.getMessage(). The method XMLError.getShortMessage() returns a very brief synopsis of the warning or error condition, whereas XMLError.getMessage() returns a longer explanation. These text strings are suitable for displaying to human users.

Each XMLError object also contains a category code; its value may be retrieved using the method XMLError.getCategory(). Category values are drawn from a set of constants whose names begin with the characters LIBSBML_CAT_, described below.  Categories are used by libSBML to provide more information to calling programs about the nature of a given error.

In addition to category codes, each XMLError object also has a severity code; its value may be retrieved using the method XMLError.getSeverity(). Severity code values are drawn from a set of constants whose names begin with the characters LIBSBML_SEV_, described below. Severity levels range from informational (LIBSBML_SEV_INFO) to fatal errors (LIBSBML_SEV_FATAL).

Finally, XMLError objects record the line and column near where the problem occurred in the XML content. The values can be retrieved using the methods XMLError.getLine() and XMLError.getColumn(). We say 'near where the problem occurred', because many factors affect how accurate the line/column information ultimately is. For example, sometimes, the underlying XML parsers can only report such information for the parent XML element where an error occurs, and not for the specific point where the problem occurs. In other situations, some parsers report invalid line and/or column numbers altogether. If this occurs, libSBML sets the line and/or column number in the XMLError object to either 0 or the value of the maximum unsigned long integer representable on the platform where libSBML is running. The probability that a true line or column number in an SBML model would equal this value is vanishingly small; thus, if an application encounters these values in an XMLError object, it can assume no valid line/column number could be provided by libSBML in that situation.

Possible XMLError error codes. Depending on the programming language in use, the Enumerator values will be defined either as a value from an enumeration type or as integer constants. To make this table more compact, we have shortened the identifiers for the category and severity codes to their essential parts. To get the actual names of the constants, prepend LIBSBML_CAT_ to the category names and LIBSBML_SEV_ to the severity names shown in the two right-hand columns.
Enumerator Meaning Category Severity
XMLUnknownErrorUnrecognized error encountered internallyINTERNALFATAL
XMLOutOfMemory Out of memorySYSTEMFATAL
XMLFileUnreadable File unreadableSYSTEMERROR
XMLFileUnwritable File unwritableSYSTEMERROR
XMLFileOperationErrorError encountered while attempting file operationSYSTEMERROR
XMLNetworkAccessErrorNetwork access errorSYSTEMERROR
InternalXMLParserErrorInternal XML parser state errorINTERNALFATAL
UnrecognizedXMLParserCodeXML parser returned an unrecognized error codeINTERNALFATAL
XMLTranscoderErrorCharacter transcoder errorINTERNALFATAL
MissingXMLDeclMissing XML declaration at beginning of XML inputXMLERROR
MissingXMLEncodingMissing encoding attribute in XML declarationXMLERROR
BadXMLDeclInvalid or unrecognized XML declaration or XML encodingXMLERROR
BadXMLDOCTYPEInvalid, malformed or unrecognized XML DOCTYPE declarationXMLERROR
InvalidCharInXMLInvalid character in XML contentXMLERROR
BadlyFormedXMLXML content is not well-formedXMLERROR
UnclosedXMLTokenUnclosed XML tokenXMLERROR
InvalidXMLConstructXML construct is invalid or not permittedXMLERROR
XMLTagMismatchElement tag mismatch or missing tagXMLERROR
DuplicateXMLAttributeDuplicate XML attributeXMLERROR
UndefinedXMLEntityUndefined XML entityXMLERROR
BadProcessingInstructionInvalid, malformed or unrecognized XML processing instructionXMLERROR
BadXMLPrefixInvalid or undefined XML namespace prefixXMLERROR
BadXMLPrefixValueInvalid XML namespace prefix valueXMLERROR
MissingXMLRequiredAttributeMissing a required XML attributeXMLERROR
XMLAttributeTypeMismatchData type mismatch for the value of an attributeXMLERROR
XMLBadUTF8ContentInvalid UTF8 contentXMLERROR
MissingXMLAttributeValueMissing or improperly formed attribute valueXMLERROR
BadXMLAttributeValueInvalid or unrecognizable attribute valueXMLERROR
BadXMLAttributeInvalid, unrecognized or malformed attributeXMLERROR
UnrecognizedXMLElementElement either not recognized or not permittedXMLERROR
BadXMLCommentBadly formed XML commentXMLERROR
BadXMLDeclLocationXML declaration not permitted in this locationXMLERROR
XMLUnexpectedEOFReached end of input unexpectedlyXMLERROR
BadXMLIDValueValue is invalid for XML ID, or has already been usedXMLERROR
BadXMLIDRefXML ID value was never declaredXMLERROR
UninterpretableXMLContentUnable to interpret contentXMLERROR
BadXMLDocumentStructureBad XML document structureXMLERROR
InvalidAfterXMLContentEncountered invalid content after expected contentXMLERROR
XMLExpectedQuotedStringExpected to find a quoted stringXMLERROR
XMLEmptyValueNotPermittedAn empty value is not permitted in this contextXMLERROR
XMLBadNumberInvalid or unrecognized numberXMLERROR
XMLBadColonColon characters are invalid in this contextXMLERROR
MissingXMLElementsOne or more expected elements are missingXMLERROR
XMLContentEmptyMain XML content is emptyXMLERROR
Enumerator Meaning
LIBSBML_CAT_INTERNAL A problem involving the libSBML software itself or the underlying XML parser. This almost certainly indicates a software defect (i.e., bug) in libSBML. Please report instances of this to the libSBML developers.
LIBSBML_CAT_SYSTEM A problem reported by the operating system, such as an inability to read or write a file. This indicates something that is not a program error but is outside of the control of libSBML.
LIBSBML_CAT_XML A problem in the XML content itself. This usually arises from malformed XML or the use of constructs not permitted in SBML.
Enumerator Meaning
LIBSBML_SEV_INFO The error is actually informational and not necessarily a serious problem.
LIBSBML_SEV_WARNING The error object represents a problem that is not serious enough to necessarily stop the problem, but applications should take note of the problem and evaluate what its implications may be.
LIBSBML_SEV_ERROR The error object represents a serious error. The application may continue running but it is unlikely to be able to continue processing the same XML file or data stream.
LIBSBML_SEV_FATAL A serious error occurred, such as an out-of-memory condition, and the software should terminate immediately.

This method has multiple variants; they differ in the arguments they accept.

__init__(int errorId=0, string details, long line=0, long column=0, long severity=LIBSBML_SEV_FATAL, long category=LIBSBML_CAT_INTERNAL)   XMLError
__init__(int errorId=0, string details, long line=0, long column=0, long severity=LIBSBML_SEV_FATAL)   XMLError
__init__(int errorId=0, string details, long line=0, long column=0)   XMLError
__init__(int errorId=0, string details, long line=0)   XMLError
__init__(int errorId=0, string details)   XMLError
__init__(int errorId=0)   XMLError
__init__()   XMLError
__init__(XMLError orig)   XMLError

Each variant is described separately below.


Method variant with the following signature:
XMLError(XMLError orig)

Copy constructor; creates a copy of this XMLError.

orig the XMLError object to copy.

Exceptions
XMLConstructorExceptionThrown if the argument orig is None.

Method variant with the following signature:
XMLError(int errorId = 0, string details = '', long line = 0, long column = 0, long severity = LIBSBML_SEV_FATAL, long category = LIBSBML_CAT_INTERNAL)

Creates a new XMLError to report that something occurred during XML processing.

XMLError objects have identification numbers to indicate the nature of the exception. These numbers are defined as longeger constants in the file 'libsbmlConstants.java'. See the top of this documentation for a table listing the possible values and their meanings. The argument errorId to this constructor can be (but does not have to be) a value from this set of constants. If it is one of the predefined error identifiers, the XMLError class assumes the error is a low-level system or XML layer error and prepends a built-in, predefined error message to any string passed in the argument details to this constructor. In addition, all the predefined error identifiers have associated values for the severity and category codes, and these fields are filled-in as well.

If the error identifier errorId is a number greater than 9999, this constructor assumes that the error was generated from another part of the software, and does not do additional filling in of values beyond the defaults in the constructor itself. This allows XMLError to serve as a base class for other errors (and is used in this way elsewhere in libSBML). Callers should fill in all the parameters with suitable values if generating errors with codes greater than 9999 to make maximum use of the XMLError facilities.

As mentioned above, there are additional constants defined for standard severity and standard category codes, and every predefined error in libSBML has an associated value for severity and category taken from these predefined sets. These constants have symbol names prefixed with LIBSBML_SEV_ and LIBSBML_CAT_, respectively. If the value of errorId is one of the standard error codes, callers do not need to fill in severity and category in a call to this constructor. Conversely, if errorId is not an existing XML-level error code, callers can use other values for severity and category.

Parameters
errorIda long integer, the identification number of the error.
detailsa string containing additional details about the error. If the error code in errorId is one that is recognized by XMLError, the given message is appended to a predefined message associated with the given code. If the error code is not recognized, the message is stored as-is as the text of the error.
linea long integer, the line number at which the error occured.
columna long integer, the column number at which the error occured.
severityan integer indicating severity of the error.
categoryan integer indicating the category to which the error belongs.
def libsbml.SBMLError.__init__ (   self,
  args 
)

An error, warning or other diagnostic.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

When a libSBML operation on SBML content results in an error, or when there is something wrong with the SBML content, the problems are reported as SBMLError objects. These are generally stored in an SBMLErrorLog object; this log object, in turn, is kept in the SBMLDocument object containing the SBML content. Applications can obtain the list of logged errors using SBMLDocument.getErrorLog() and then use the methods provided by SBMLErrorLog to access individual SBMLError objects. (Note that despite the word 'error' in the name, SBMLError objects are used to represent not only 'true' errors, but also warnings and some informational diagnostics. The name is a historical hold-over from early versions of libSBML, in which the object really was only used to report errors.)

Each SBMLError object instance has an identification number that identifies the nature of the problem. This 'error id' number will be up to five digits long, and it will come from one of two sets of static integer constants defined in the interface class libsbml: either the SBML error identifiers (described below) or the XML error identifiers (described in the documentation for the class XMLError). The former set of constants includes all the SBML validation rule numbers listed in the appendices of the SBML specification documents, as well as some additional libSBML-specific error codes.

Error codes are useful mainly for software. For human readers, SBMLError also includes text messages that describe the nature of a given problem. The messages can be accessed using SBMLError.getShortMessage() and SBMLError.getMessage(). The former provides a brief one-line description of the issue, while SBMLError.getMessage() provides a more detailed text, including (if appropriate) references to sections of the SBML specifications where relevant topics are discussed. These text strings are suitable for displaying to human users.

An SBMLError object also contains a category code; its value may be retrieved using the method SBMLError.getCategory(). Category values are drawn from a set of static integer constants defined in libsbml and having names beginning with the characters LIBSBML_CAT_. The list of possible codes is described in a separate section below. Categories are used to partition errors into distinct conceptual groups. This is principally used by the libSBML validation system to group classes of validation checks. For example, LIBSBML_CAT_IDENTIFIER_CONSISTENCY is the category for tests that check identifier consistency; LIBSBML_CAT_MATHML_CONSISTENCY is the category for MathML consistency checking; and so on.

In addition, SBMLError also has a severity code. Its value may be retrieved using the method SBMLError.getSeverity(). The possible severity values are the same as those reported byXMLError. Severity levels currently range from informational (LIBSBML_SEV_INFO) to fatal errors (LIBSBML_SEV_FATAL). They can be used by an application to evaluate how serious a given problem is.

SBMLError also tracks the Level 3 package extension, if any, was responsible for a given warning or error. Each diagnostic code logged by an libSBML extension for SBML Level 3 packages includes a record of the package that logged it. It can be retrieved using SBMLError.getPackage(). The information is a simple text string; the string will be the nickname of the package, such as 'comp' for the Hierarchical Model Composition package, 'fbc' for the Flux Balance Constraints package, and so on. If the value returned by SBMLError.getPackage() is an empty string or has the value 'core', then the error came from libSBML core.

Finally, SBMLError records the line and column near where the problem occurred in the SBML content. The values may be retrieved using the methods SBMLError.getLine() and SBMLError.getColumn(). We say 'near', because a lot of factors affect how accurate the line/column information ultimately is. For example, different XML parsers have different conventions for which line and column number they report for a particular problem (which makes a difference when a problem involves an opening XML tag on one line and a closing tag on another line). In some situations, some parsers report invalid line and/or column numbers altogether. If this occurs, libSBML sets the line and/or column number in the SBMLError object to the the value of the maximum unsigned long integer representable on the platform where libSBML is running. (This is equal to the constant named ULONG_MAX in C and C++.) The probability that a true line or column number in an SBML model would equal this value is vanishingly small; thus, if an application encounters these values in an XMLError object, it can assume no valid line/column number could be provided by libSBML in that situation.

Error codes associated with SBMLError objects

The error and warning codes returned by libSBML are listed in the table below. The method SBMLError.getErrorId() returns the error code of a given SBMLError object instance. In the libSBML Python language interface, these error identifiers are currently implemented as static integer constants defined in the interface class libsbml.

In this table, the right-hand columns titled 'L1V1', 'L1V2', etc. refer to Levels and Versions of the SBML specifications, and the entries in each column refer to whether the severity of the condition in that particular Level+Version of SBML. The codes stand for the following:

= Not applicable
= Warning
= Error
= Fatal

The text shown in the 'Meaning' is the text returned by the SBMLError.getShortMessage() method on a given SBMLError object. A longer and (hopefully) clearer explanation of the issue is returned by SBMLError.getMessage().

The error codes come from different lists depending on whether they're from libSBML core or from an SBML Level 3 package extension. However, in the language interfaces other than C++, all libSBML error codes are ultimately represented as integer constants rather than separate enumerations lists, and they are all stored in a single interface class. Codes from different libSBML extensions have names that begin with the package's nickname, such as Qual for the Qualitative Models package, Layout for the Layout package, and so on. If the name of a code does not begin with one of the package nicknames (Layout, Fbc, Comp, Qual, etc.), then it is a code from libSBML core.

Enumerator Meaning L1 V1 L1 V2 L2 V1 L2 V2 L2 V3 L2 V4 L3 V1
XMLUnknownError Unknown error
XMLOutOfMemory Out of memory
XMLFileUnreadable File unreadable
XMLFileUnwritable File unwritable
XMLFileOperationError File operation error
XMLNetworkAccessError Network access error
InternalXMLParserError Internal XML parser error
UnrecognizedXMLParserCode Unrecognized XML parser code
XMLTranscoderError Transcoder error
MissingXMLDecl Missing XML declaration
MissingXMLEncoding Missing XML encoding attribute
BadXMLDecl Bad XML declaration
BadXMLDOCTYPE Bad XML DOCTYPE
InvalidCharInXML Invalid character
BadlyFormedXML Badly formed XML
UnclosedXMLToken Unclosed token
InvalidXMLConstruct Invalid XML construct
XMLTagMismatch XML tag mismatch
DuplicateXMLAttribute Duplicate attribute
UndefinedXMLEntity Undefined XML entity
BadProcessingInstruction Bad XML processing instruction
BadXMLPrefix Bad XML prefix
BadXMLPrefixValue Bad XML prefix value
MissingXMLRequiredAttribute Missing required attribute
XMLAttributeTypeMismatch Attribute type mismatch
XMLBadUTF8Content Bad UTF8 content
MissingXMLAttributeValue Missing attribute value
BadXMLAttributeValue Bad attribute value
BadXMLAttribute Bad XML attribute
UnrecognizedXMLElement Unrecognized XML element
BadXMLComment Bad XML comment
BadXMLDeclLocation Bad XML declaration location
XMLUnexpectedEOF Unexpected EOF
BadXMLIDValue Bad XML ID value
BadXMLIDRef Bad XML IDREF
UninterpretableXMLContent Uninterpretable XML content
BadXMLDocumentStructure Bad XML document structure
InvalidAfterXMLContent Invalid content after XML content
XMLExpectedQuotedString Expected quoted string
XMLEmptyValueNotPermitted Empty value not permitted
XMLBadNumber Bad number
XMLBadColon Colon character not permitted
MissingXMLElements Missing XML elements
XMLContentEmpty Empty XML content
UnknownError Encountered unknown internal libSBML error
NotUTF8 File does not use UTF-8 encoding
UnrecognizedElement Encountered unrecognized element
NotSchemaConformant Document does not conform to the SBML XML schema
L3NotSchemaConformant Document is not well-formed XML
InvalidMathElement Invalid MathML
DisallowedMathMLSymbol Disallowed MathML symbol found
DisallowedMathMLEncodingUse Use of the MathML 'encoding' attribute is not allowed on this element
DisallowedDefinitionURLUse Use of the MathML 'definitionURL' attribute is not allowed on this element
BadCsymbolDefinitionURLValue Invalid <csymbol> 'definitionURL' attribute value
DisallowedMathTypeAttributeUse Use of the MathML 'type' attribute is not allowed on this element
DisallowedMathTypeAttributeValue Disallowed MathML 'type' attribute value
LambdaOnlyAllowedInFunctionDef Use of <lambda> not permitted outside of FunctionDefinition objects
BooleanOpsNeedBooleanArgs Non-Boolean argument given to Boolean operator
NumericOpsNeedNumericArgs Non-numerical argument given to numerical operator
ArgsToEqNeedSameType Arguments to <eq> and <neq> must have the same data types
PiecewiseNeedsConsistentTypes Terms in a <piecewise> expression must have consistent data types
PieceNeedsBoolean The second argument of a <piece> expression must yield a Boolean value
ApplyCiMustBeUserFunction A <ci> element in this context must refer to a function definition
ApplyCiMustBeModelComponent A <ci> element in this context must refer to a model component
KineticLawParametersAreLocalOnly Cannot use a KineticLaw local parameter outside of its local scope
MathResultMustBeNumeric A formula's result in this context must be a numerical value
OpsNeedCorrectNumberOfArgs Incorrect number of arguments given to MathML operator
InvalidNoArgsPassedToFunctionDef Incorrect number of arguments given to function invocation
DisallowedMathUnitsUse Attribute 'units' is only permitted on <cn> elements
InvalidUnitsValue Invalid value given for the 'units' attribute
DuplicateComponentId Duplicate 'id' attribute value
DuplicateUnitDefinitionId Duplicate unit definition 'id' attribute value
DuplicateLocalParameterId Duplicate local parameter 'id' attribute value
MultipleAssignmentOrRateRules Multiple rules for the same variable are not allowed
MultipleEventAssignmentsForId Multiple event assignments for the same variable are not allowed
EventAndAssignmentRuleForId An event assignment and an assignment rule must not have the same value for 'variable'
DuplicateMetaId Duplicate 'metaid' attribute value
InvalidSBOTermSyntax Invalid syntax for an 'sboTerm' attribute value
InvalidMetaidSyntax Invalid syntax for a 'metaid' attribute value
InvalidIdSyntax Invalid syntax for an 'id' attribute value
InvalidUnitIdSyntax Invalid syntax for the identifier of a unit
InvalidNameSyntax Invalid syntax for a 'name' attribute value
MissingAnnotationNamespace Missing declaration of the XML namespace for the annotation
DuplicateAnnotationNamespaces Multiple annotations using the same XML namespace
SBMLNamespaceInAnnotation The SBML XML namespace cannot be used in an Annotation object
MultipleAnnotations Only one Annotation object is permitted under a given SBML object
InconsistentArgUnits The units of the function call's arguments are not consistent with its definition
InconsistentKineticLawUnitsL3 The kinetic law's units are inconsistent with those of other kinetic laws in the model
AssignRuleCompartmentMismatch Mismatched units in assignment rule for compartment
AssignRuleSpeciesMismatch Mismatched units in assignment rule for species
AssignRuleParameterMismatch Mismatched units in assignment rule for parameter
AssignRuleStoichiometryMismatch Mismatched units in assignment rule for stoichiometry
InitAssignCompartmenMismatch Mismatched units in initial assignment to compartment
InitAssignSpeciesMismatch Mismatched units in initial assignment to species
InitAssignParameterMismatch Mismatched units in initial assignment to parameter
InitAssignStoichiometryMismatch Mismatched units in initial assignment to stoichiometry
RateRuleCompartmentMismatch Mismatched units in rate rule for compartment
RateRuleSpeciesMismatch Mismatched units in rate rule for species
RateRuleParameterMismatch Mismatched units in rate rule for parameter
RateRuleStoichiometryMismatch Mismatched units in rate rule for stoichiometry
KineticLawNotSubstancePerTime The units of the kinetic law are not 'substance'/'time'
SpeciesInvalidExtentUnits The species' units are not consistent with units of extent
DelayUnitsNotTime The units of the delay expression are not units of time
EventAssignCompartmentMismatch Mismatched units in event assignment for compartment
EventAssignSpeciesMismatch Mismatched units in event assignment for species
EventAssignParameterMismatch Mismatched units in event assignment for parameter
EventAssignStoichiometryMismatch Mismatched units in event assignment for stoichiometry
PriorityUnitsNotDimensionless The units of a priority expression must be 'dimensionless'
OverdeterminedSystem The model is overdetermined
InvalidModelSBOTerm Invalid 'sboTerm' attribute value for a Model object
InvalidFunctionDefSBOTerm Invalid 'sboTerm' attribute value for a FunctionDefinition object
InvalidParameterSBOTerm Invalid 'sboTerm' attribute value for a Parameter object
InvalidInitAssignSBOTerm Invalid 'sboTerm' attribute value for an InitialAssignment object
InvalidRuleSBOTerm Invalid 'sboTerm' attribute value for a Rule object
InvalidConstraintSBOTerm Invalid 'sboTerm' attribute value for a Constraint object
InvalidReactionSBOTerm Invalid 'sboTerm' attribute value for a Reaction object
InvalidSpeciesReferenceSBOTerm Invalid 'sboTerm' attribute value for a SpeciesReference object
InvalidKineticLawSBOTerm Invalid 'sboTerm' attribute value for a KineticLaw object
InvalidEventSBOTerm Invalid 'sboTerm' attribute value for an Event object
InvalidEventAssignmentSBOTerm Invalid 'sboTerm' attribute value for an EventAssignment object
InvalidCompartmentSBOTerm Invalid 'sboTerm' attribute value for a Compartment object
InvalidSpeciesSBOTerm Invalid 'sboTerm' attribute value for a Species object
InvalidCompartmentTypeSBOTerm Invalid 'sboTerm' attribute value for a CompartmentType object
InvalidSpeciesTypeSBOTerm Invalid 'sboTerm' attribute value for a SpeciesType object
InvalidTriggerSBOTerm Invalid 'sboTerm' attribute value for an Event Trigger object
InvalidDelaySBOTerm Invalid 'sboTerm' attribute value for an Event Delay object
NotesNotInXHTMLNamespace Notes must be placed in the XHTML XML namespace
NotesContainsXMLDecl XML declarations are not permitted in Notes objects
NotesContainsDOCTYPE XML DOCTYPE elements are not permitted in Notes objects
InvalidNotesContent Invalid notes content found
OnlyOneNotesElementAllowed Only one Notes subobject is permitted on a given SBML object
InvalidNamespaceOnSBML Invalid XML namespace for the SBML container element
MissingOrInconsistentLevel Missing or inconsistent value for the 'level' attribute
MissingOrInconsistentVersion Missing or inconsistent value for the 'version' attribute
PackageNSMustMatch Inconsistent or invalid SBML Level/Version for the package namespace declaration
LevelPositiveInteger The 'level' attribute must have a positive integer value
VersionPositiveInteger The 'version' attribute must have a positive integer value
AllowedAttributesOnSBML Invalid attribute found on the SBML container element
L3PackageOnLowerSBML An L3 package ns found on the SBML container element
MissingModel No model definition found
IncorrectOrderInModel Incorrect ordering of components within the Model object
EmptyListElement Empty ListOf___ object found
NeedCompartmentIfHaveSpecies The presence of a species requires a compartment
OneOfEachListOf Only one of each kind of ListOf___ object is allowed inside a Model object
OnlyFuncDefsInListOfFuncDefs Only FunctionDefinition, Notes and Annotation objects are allowed in ListOfFunctionDefinitions
OnlyUnitDefsInListOfUnitDefs Only UnitDefinition, Notes and Annotation objects are allowed in ListOfUnitDefinitions objects
OnlyCompartmentsInListOfCompartments Only Compartment, Notes and Annotation objects are allowed in ListOfCompartments objects
OnlySpeciesInListOfSpecies Only Species, Notes and Annotation objects are allowed in ListOfSpecies objects
OnlyParametersInListOfParameters Only Parameter, Notes and Annotation objects are allowed in ListOfParameters objects
OnlyInitAssignsInListOfInitAssigns Only InitialAssignment, Notes and Annotation objects are allowed in ListOfInitialAssignments objects
OnlyRulesInListOfRules Only Rule, Notes and Annotation objects are allowed in ListOfRules objects
OnlyConstraintsInListOfConstraints Only Constraint, Notes and Annotation objects are allowed in ListOfConstraints objects
OnlyReactionsInListOfReactions Only Reaction, Notes and Annotation objects are allowed in ListOfReactions objects
OnlyEventsInListOfEvents Only Event, Notes and Annotation objects are allowed in ListOfEvents objects
L3ConversionFactorOnModel A 'conversionFactor' attribute value must reference a Parameter object
L3TimeUnitsOnModel Invalid 'timeUnits' attribute value
L3VolumeUnitsOnModel Invalid 'volumeUnits' attribute value
L3AreaUnitsOnModel Invalid 'areaUnits' attribute value
L3LengthUnitsOnModel Invalid 'lengthUnits' attribute value
L3ExtentUnitsOnModel Invalid 'extentUnits' attribute value
AllowedAttributesOnModel Invalid attribute found on the Model object
AllowedAttributesOnListOfFuncs Invalid attribute found on the ListOfFunctionDefinitions object
AllowedAttributesOnListOfUnitDefs Invalid attribute found on the ListOfUnitDefinitions object
AllowedAttributesOnListOfComps Invalid attribute found on the ListOfCompartments object
AllowedAttributesOnListOfSpecies Invalid attribute found on the ListOfSpecies object
AllowedAttributesOnListOfParams Invalid attribute found on the ListOfParameters object
AllowedAttributesOnListOfInitAssign Invalid attribute found on the ListOfInitialAssignments object
AllowedAttributesOnListOfRules Invalid attribute found on the ListOfRules object
AllowedAttributesOnListOfConstraints Invalid attribute found on the ListOfConstraints object
AllowedAttributesOnListOfReactions Invalid attribute found on the ListOfReactions object
AllowedAttributesOnListOfEvents Invalid attribute found on the ListOfEvents object
FunctionDefMathNotLambda Invalid expression found in the function definition
InvalidApplyCiInLambda Invalid forward reference in the MathML <apply><ci>...</ci></apply> expression
RecursiveFunctionDefinition Recursive function definitions are not permitted
InvalidCiInLambda Invalid <ci> reference found inside the <lambda> mathematical formula
InvalidFunctionDefReturnType A function's return type must be either a number or a Boolean
OneMathElementPerFunc A FunctionDefinition object must contain one <math> element
AllowedAttributesOnFunc Invalid attribute found on the FunctionDefinition object
InvalidUnitDefId Invalid 'id' attribute value for a UnitDefinition object
InvalidSubstanceRedefinition Invalid redefinition of built-in type 'substance'
InvalidLengthRedefinition Invalid redefinition of built-in type 'length'
InvalidAreaRedefinition Invalid redefinition of built-in type name 'area'
InvalidTimeRedefinition Invalid redefinition of built-in type name 'time'
InvalidVolumeRedefinition Invalid redefinition of built-in type name 'volume'
VolumeLitreDefExponentNotOne Must use 'exponent'=1 when defining 'volume' in terms of litres
VolumeMetreDefExponentNot3 Must use 'exponent'=3 when defining 'volume' in terms of metres
EmptyListOfUnits An empty list of Unit objects is not permitted in a UnitDefinition object
InvalidUnitKind Invalid value for the 'kind' attribute of a UnitDefinition object
OffsetNoLongerValid Unit attribute 'offset' is not supported in this Level+Version of SBML
CelsiusNoLongerValid Unit name 'Celsius' is not defined in this Level+Version of SBML
EmptyUnitListElement A ListOfUnits object must not be empty
OneListOfUnitsPerUnitDef At most one ListOfUnits object is allowed inside a UnitDefinition object
OnlyUnitsInListOfUnits Only Unit, Notes and Annotation objects are allowed in ListOfUnits objects
AllowedAttributesOnUnitDefinition Invalid attribute found on the UnitDefinition object
AllowedAttributesOnListOfUnits Invalid attribute found on the ListOfUnits object
AllowedAttributesOnUnit Invalid attribute found on the Unit object
ZeroDimensionalCompartmentSize Invalid use of the 'size' attribute for a zero-dimensional compartment
ZeroDimensionalCompartmentUnits Invalid use of the 'units' attribute for a zero-dimensional compartment
ZeroDimensionalCompartmentConst Zero-dimensional compartments must be defined to be constant
UndefinedOutsideCompartment Invalid value for the 'outside' attribute of a Compartment object
RecursiveCompartmentContainment Recursive nesting of compartments via the 'outside' attribute is not permitted
ZeroDCompartmentContainment Invalid nesting of zero-dimensional compartments
Invalid1DCompartmentUnits Invalid value for the 'units' attribute of a one-dimensional compartment
Invalid2DCompartmentUnits Invalid value for the 'units' attribute of a two-dimensional compartment
Invalid3DCompartmentUnits Invalid value for the 'units' attribute of a three-dimensional compartment
InvalidCompartmentTypeRef Invalid value for the 'compartmentType' attribute of a compartment
OneDimensionalCompartmentUnits No units defined for 1-D compartment
TwoDimensionalCompartmentUnits No units defined for 2-D compartment
ThreeDimensionalCompartmentUnits No units defined for 3-D Compartment object
AllowedAttributesOnCompartment Invalid attribute found on Compartment object
NoUnitsOnCompartment No units defined for Compartment object
InvalidSpeciesCompartmentRef Invalid value found for Species 'compartment' attribute
HasOnlySubsNoSpatialUnits Attribute 'spatialSizeUnits' must not be set if 'hasOnlySubstanceUnits'='true'
NoSpatialUnitsInZeroD Attribute 'spatialSizeUnits' must not be set if the compartment is zero-dimensional
NoConcentrationInZeroD Attribute 'initialConcentration' must not be set if the compartment is zero-dimensional
SpatialUnitsInOneD Invalid value for 'spatialSizeUnits' attribute of a one-dimensional compartment
SpatialUnitsInTwoD Invalid value for the 'spatialSizeUnits' attribute of a two-dimensional compartment
SpatialUnitsInThreeD Invalid value for the 'spatialSizeUnits' attribute of a three-dimensional compartment
InvalidSpeciesSusbstanceUnits Invalid value for a Species 'units' attribute
BothAmountAndConcentrationSet Cannot set both 'initialConcentration' and 'initialAmount' attributes simultaneously
NonBoundarySpeciesAssignedAndUsed Cannot use a non-boundary species in both reactions and rules simultaneously
NonConstantSpeciesUsed Cannot use a constant, non-boundary species as a reactant or product
InvalidSpeciesTypeRef Invalid value for the 'speciesType' attribute of a species
MultSpeciesSameTypeInCompartment Cannot have multiple species of the same species type in the same compartment
MissingSpeciesCompartment Missing value for the 'compartment' attribute
SpatialSizeUnitsRemoved Attribute 'spatialSizeUnits' is not supported in this Level+Version of SBML
SubstanceUnitsOnSpecies No substance units defined for the species
ConversionFactorOnSpecies Invalid value for the 'conversionFactor' attribute
AllowedAttributesOnSpecies Invalid attribute found on Species object
InvalidParameterUnits Invalid value for the 'units' attribute of a Parameter object
ParameterUnits No units defined for the parameter
ConversionFactorMustConstant A conversion factor must reference a Parameter object declared to be a constant
AllowedAttributesOnParameter Invalid attribute found on Parameter object
InvalidInitAssignSymbol Invalid value for the 'symbol' attribute of an InitialAssignment object
MultipleInitAssignments Multiple initial assignments for the same 'symbol' value are not allowed
InitAssignmentAndRuleForSameId Cannot set a value using both an initial assignment and an assignment rule simultaneously
OneMathElementPerInitialAssign An InitialAssignment object must contain one <math> element
AllowedAttributesOnInitialAssign Invalid attribute found on an InitialAssignment object
InvalidAssignRuleVariable Invalid value for the 'variable' attribute of an AssignmentRule object
InvalidRateRuleVariable Invalid value for the 'variable' attribute of a RateRule object
AssignmentToConstantEntity An assignment rule cannot assign an entity declared to be constant
RateRuleForConstantEntity A rate rule cannot assign an entity declared to be constant
CircularRuleDependency Circular dependencies involving rules and reactions are not permitted
OneMathElementPerRule A rule object must contain one <math> element
AllowedAttributesOnAssignRule Invalid attribute found on an AssignmentRule object
AllowedAttributesOnRateRule Invalid attribute found on a RateRule object
AllowedAttributesOnAlgRule Invalid attribute found on an AlgebraicRule object
ConstraintMathNotBoolean A Constraint object's <math> must evaluate to a Boolean value
IncorrectOrderInConstraint Subobjects inside the Constraint object are not in the prescribed order
ConstraintNotInXHTMLNamespace A Constraint's Message subobject must be in the XHTML XML namespace
ConstraintContainsXMLDecl XML declarations are not permitted within Constraint's Message objects
ConstraintContainsDOCTYPE XML DOCTYPE elements are not permitted within Constraint's Message objects
InvalidConstraintContent Invalid content for a Constraint object's Message object
OneMathElementPerConstraint A Constraint object must contain one <math> element
OneMessageElementPerConstraint A Constraint object must contain one Message subobject
AllowedAttributesOnConstraint Invalid attribute found on Constraint object
NoReactantsOrProducts Cannot have a reaction with neither reactants nor products
IncorrectOrderInReaction Subobjects inside the Reaction object are not in the prescribed order
EmptyListInReaction Reaction components, if present, cannot be empty
InvalidReactantsProductsList Invalid object found in the list of reactants or products
InvalidModifiersList Invalid object found in the list of modifiers
OneSubElementPerReaction A Reaction object can only contain one of each allowed type of object
CompartmentOnReaction Invalid value for the Reaction 'compartment' attribute
AllowedAttributesOnReaction Invalid attribute for a Reaction object
InvalidSpeciesReference Invalid 'species' attribute value in SpeciesReference object
BothStoichiometryAndMath The 'stoichiometry' attribute and StoichiometryMath subobject are mutually exclusive
AllowedAttributesOnSpeciesReference Invalid attribute found on the SpeciesReference object
AllowedAttributesOnModifier Invalid attribute found on the ModifierSpeciesReference object
UndeclaredSpeciesRef Unknown species referenced in the kinetic law <math> formula
IncorrectOrderInKineticLaw Incorrect ordering of components in the KineticLaw object
EmptyListInKineticLaw The list of parameters, if present, cannot be empty
NonConstantLocalParameter Parameters local to a KineticLaw object must have a 'constant' attribute value of 'true'
SubsUnitsNoLongerValid Attribute 'substanceUnits' is not supported in this Level+Version of SBML
TimeUnitsNoLongerValid Attribute 'timeUnits' is not supported in this Level+Version of SBML
OneListOfPerKineticLaw Only one ListOfLocalParameters object is permitted within a KineticLaw object
OnlyLocalParamsInListOfLocalParams Only LocalParameter, Notes and Annotation objects are allowed in ListOfLocalParameter objects
AllowedAttributesOnListOfLocalParam Invalid attribute found on the ListOfLocalParameters object
OneMathPerKineticLaw Only one <math> element is allowed in a KineticLaw object
UndeclaredSpeciesInStoichMath Unknown species referenced in the StoichiometryMath object's <math> formula
AllowedAttributesOnKineticLaw Invalid attribute found on the KineticLaw object
AllowedAttributesOnListOfSpeciesRef Invalid attribute found on the ListOfSpeciesReferences object
AllowedAttributesOnListOfMods Invalid attribute found on the ListOfModifiers object
AllowedAttributesOnLocalParameter Invalid attribute found on the LocalParameter object
MissingTriggerInEvent The Event object is missing a Trigger subobject
TriggerMathNotBoolean A Trigger object's <math> expression must evaluate to a Boolean value
MissingEventAssignment The Event object is missing an EventAssignment subobject
TimeUnitsEvent Units referenced by 'timeUnits' attribute are not compatible with units of time
IncorrectOrderInEvent Incorrect ordering of components in Event object
ValuesFromTriggerTimeNeedDelay Attribute 'useValuesFromTriggerTime'='false', but the Event object does not define a delay
DelayNeedsValuesFromTriggerTime The use of a Delay object requires the Event attribute 'useValuesFromTriggerTime'
OneMathPerTrigger A Trigger object must have one <math> element
OneMathPerDelay A Delay object must have one <math> element
InvalidEventAssignmentVariable Invalid 'variable' attribute value in Event object
EventAssignmentForConstantEntity An EventAssignment object cannot assign to a component having attribute 'constant'='true'
OneMathPerEventAssignment An EventAssignment object must have one <math> element
AllowedAttributesOnEventAssignment Invalid attribute found on the EventAssignment object
OnlyOneDelayPerEvent An Event object can only have one Delay subobject
OneListOfEventAssignmentsPerEvent An Event object can only have one ListOfEventAssignments subobject
OnlyEventAssignInListOfEventAssign Only EventAssignment, Notes and Annotation objects are allowed in ListOfEventAssignments
AllowedAttributesOnListOfEventAssign Invalid attribute found on the ListOfEventAssignments object
AllowedAttributesOnEvent Invalid attribute found on the Event object
AllowedAttributesOnTrigger Invalid attribute found on the Trigger object
AllowedAttributesOnDelay Invalid attribute found on the Delay object
PersistentNotBoolean The Trigger attribute 'persistent' must evaluate to a Boolean value
InitialValueNotBoolean The Trigger attribute 'initialValue' must evaluate to a Boolean value
OnlyOnePriorityPerEvent An Event object can only have one Priority subobject
OneMathPerPriority A Priority object must have one <math> element
AllowedAttributesOnPriority Invalid attribute found on the Priority object
CompartmentShouldHaveSize It's best to define a size for every compartment in a model
SpeciesShouldHaveValue It's best to define an initial amount or initial concentration for every species in a model
ParameterShouldHaveUnits It's best to declare units for every parameter in a model
LocalParameterShadowsId Local parameters defined within a kinetic law shadow global object symbols
CannotConvertToL1V1 Cannot convert to SBML Level 1 Version 1
NoEventsInL1 SBML Level 1 does not support events
NoFunctionDefinitionsInL1 SBML Level 1 does not support function definitions
NoConstraintsInL1 SBML Level 1 does not support constraints
NoInitialAssignmentsInL1 SBML Level 1 does not support initial assignments
NoSpeciesTypesInL1 SBML Level 1 does not support species types
NoCompartmentTypeInL1 SBML Level 1 does not support compartment types
NoNon3DCompartmentsInL1 SBML Level 1 only supports three-dimensional compartments
NoFancyStoichiometryMathInL1 SBML Level 1 does not support non-integer nor non-rational stoichiometry formulas
NoNonIntegerStoichiometryInL1 SBML Level 1 does not support non-integer 'stoichiometry' attribute values
NoUnitMultipliersOrOffsetsInL1 SBML Level 1 does not support multipliers or offsets in unit definitions
SpeciesCompartmentRequiredInL1 In SBML Level 1, a value for 'compartment' is mandatory in species definitions
NoSpeciesSpatialSizeUnitsInL1 SBML Level 1 does not support species 'spatialSizeUnits' settings
NoSBOTermsInL1 SBML Level 1 does not support the 'sboTerm' attribute
StrictUnitsRequiredInL1 SBML Level 1 requires strict unit consistency
ConversionFactorNotInL1 SBML Level 1 does not support the 'conversionFactor' attribute
CompartmentNotOnL1Reaction SBML Level 1 does not support the 'compartment' attribute on Reaction objects
ExtentUnitsNotSubstance Units of extent must be compatible with units of substance
GlobalUnitsNotDeclared Global units must be refer to unit kind or unitDefinition.
HasOnlySubstanceUnitsNotinL1 The concept of hasOnlySubstanceUnits was not available in SBML Level 1.
AvogadroNotSupported Avogadro not supported in Levels 2 and 1.
NoConstraintsInL2v1 SBML Level 2 Version 1 does not support Constraint objects
NoInitialAssignmentsInL2v1 SBML Level 2 Version 1 does not support InitialAssignment objects
NoSpeciesTypeInL2v1 SBML Level 2 Version 1 does not support SpeciesType objects
NoCompartmentTypeInL2v1 SBML Level 2 Version 1 does not support CompartmentType objects
NoSBOTermsInL2v1 SBML Level 2 Version 1 does not support the 'sboTerm' attribute
NoIdOnSpeciesReferenceInL2v1 SBML Level 2 Version 1 does not support the 'id' attribute on SpeciesReference objects
NoDelayedEventAssignmentInL2v1 SBML Level 2 Version 1 does not support the 'useValuesFromTriggerTime' attribute
StrictUnitsRequiredInL2v1 SBML Level 2 Version 1 requires strict unit consistency
IntegerSpatialDimensions SBML Level 2 Version 1 requires that compartments have spatial dimensions of 0-3
StoichiometryMathNotYetSupported Conversion to StoichiometryMath objects not yet supported
PriorityLostFromL3 SBML Level 2 Version 1 does not support priorities on Event objects
NonPersistentNotSupported SBML Level 2 Version 1 does not support the 'persistent' attribute on Trigger objects
InitialValueFalseEventNotSupported SBML Level 2 Version 1 does not support the 'initialValue' attribute on Trigger objects
SBOTermNotUniversalInL2v2 The 'sboTerm' attribute is invalid for this component in SBML Level 2 Version 2
NoUnitOffsetInL2v2 This Level+Version of SBML does not support the 'offset' attribute on Unit objects
NoKineticLawTimeUnitsInL2v2 This Level+Version of SBML does not support the 'timeUnits' attribute on KineticLaw objects
NoKineticLawSubstanceUnitsInL2v2 This Level+Version of SBML does not support the 'substanceUnits' attribute on KineticLaw objects
NoDelayedEventAssignmentInL2v2 This Level+Version of SBML does not support the 'useValuesFromTriggerTime' attribute
ModelSBOBranchChangedBeyondL2v2 The allowable 'sboTerm' attribute values for Model objects differ for this SBML Level+Version
StrictUnitsRequiredInL2v2 SBML Level 2 Version 2 requires strict unit consistency
StrictSBORequiredInL2v2 SBML Level 2 Version 2 requires strict SBO term consistency
DuplicateAnnotationInvalidInL2v2 Duplicate top-level annotations are invalid in SBML Level 2 Version 2
NoUnitOffsetInL2v3 This Level+Version of SBML does not support the 'offset' attribute on Unit objects
NoKineticLawTimeUnitsInL2v3 This Level+Version of SBML does not support the 'timeUnits' attribute on KineticLaw objects
NoKineticLawSubstanceUnitsInL2v3 This Level+Version of SBML does not support the 'substanceUnits' attribute on KineticLaw objects
NoSpeciesSpatialSizeUnitsInL2v3 This Level+Version of SBML does not support the 'spatialSizeUnit' attribute on Species objects
NoEventTimeUnitsInL2v3 This Level+Version of SBML does not support the 'timeUnits' attribute on Event objects
NoDelayedEventAssignmentInL2v3 This Level+Version of SBML does not support the 'useValuesFromTriggerTime' attribute
ModelSBOBranchChangedBeyondL2v3 The allowable 'sboTerm' attribute values for Model objects differ for this SBML Level+Version
StrictUnitsRequiredInL2v3 SBML Level 2 Version 3 requires strict unit consistency
StrictSBORequiredInL2v3 SBML Level 2 Version 3 requires strict SBO term consistency
DuplicateAnnotationInvalidInL2v3 Duplicate top-level annotations are invalid in SBML Level 2 Version 3
NoUnitOffsetInL2v4 This Level+Version of SBML does not support the 'offset' attribute on Unit objects
NoKineticLawTimeUnitsInL2v4 This Level+Version of SBML does not support the 'timeUnits' attribute on KineticLaw objects
NoKineticLawSubstanceUnitsInL2v4 This Level+Version of SBML does not support the 'substanceUnits' attribute on KineticLaw objects
NoSpeciesSpatialSizeUnitsInL2v4 This Level+Version of SBML does not support the 'spatialSizeUnit' attribute on Species objects
NoEventTimeUnitsInL2v4 This Level+Version of SBML does not support the 'timeUnits' attribute on Event objects
ModelSBOBranchChangedInL2v4 The allowable 'sboTerm' attribute values for Model objects differ for this SBML Level+Version
DuplicateAnnotationInvalidInL2v4 Duplicate top-level annotations are invalid in SBML Level 2 Version 4
NoSpeciesTypeInL3v1 SBML Level 3 Version 1 does not support SpeciesType objects
NoCompartmentTypeInL3v1 SBML Level 3 Version 1 does not support CompartmentType objects
NoUnitOffsetInL3v1 This Level+Version of SBML does not support the 'offset' attribute on Unit objects
NoKineticLawTimeUnitsInL3v1 This Level+Version of SBML does not support the 'timeUnits' attribute on KineticLaw objects
NoKineticLawSubstanceUnitsInL3v1 This Level+Version of SBML does not support the 'substanceUnits' attribute on KineticLaw objects
NoSpeciesSpatialSizeUnitsInL3v1 This Level+Version of SBML does not support the 'spatialSizeUnit' attribute on Species objects
NoEventTimeUnitsInL3v1 This Level+Version of SBML does not support the 'timeUnits' attribute on Event objects
ModelSBOBranchChangedInL3v1 The allowable 'sboTerm' attribute values for Model objects differ for this SBML Level+Version
DuplicateAnnotationInvalidInL3v1 Duplicate top-level annotations are invalid in SBML Level 3 Version 1
NoCompartmentOutsideInL3v1 This Level+Version of SBML does not support the 'outside' attribute on Compartment objects
NoStoichiometryMathInL3v1 This Level+Version of SBML does not support the StoichiometryMath object
InvalidSBMLLevelVersion Unknown Level+Version combination of SBML
AnnotationNotesNotAllowedLevel1 Annotation objects on the SBML container element are not permitted in SBML Level 1
InvalidRuleOrdering Invalid ordering of rules
RequiredPackagePresent The SBML document requires an SBML Level 3 package unavailable in this software
UnrequiredPackagePresent The SBML document uses an SBML Level 3 package unavailable in this software
PackageRequiredShouldBeFalse This package expects required to be false
SubsUnitsAllowedInKL Disallowed value for attribute 'substanceUnits' on KineticLaw object
TimeUnitsAllowedInKL Disallowed value for attribute 'timeUnits' on KineticLaw object
FormulaInLevel1KL Only predefined functions are allowed in SBML Level 1 formulas
L3SubstanceUnitsOnModel Invalid 'substanceUnits' attribute value
TimeUnitsRemoved This Level+Version of SBML does not support the 'timeUnits' attribute on Event objects
BadMathML Invalid MathML expression
FailedMathMLReadOfDouble Missing or invalid floating-point number in MathML expression
FailedMathMLReadOfInteger Missing or invalid integer in MathML expression
FailedMathMLReadOfExponential Missing or invalid exponential expression in MathML
FailedMathMLReadOfRational Missing or invalid rational expression in MathML
BadMathMLNodeType Invalid MathML element
InvalidMathMLAttribute Invalid MathML attribute
NoTimeSymbolInFunctionDef Use of <csymbol> for 'time' not allowed within FunctionDefinition objects
NoBodyInFunctionDef There must be a <lambda> body within the <math> element of a FunctionDefinition object
DanglingUnitSIdRef Units must refer to valid unit or unitDefinition
RDFMissingAboutTag RDF missing the <about> tag
RDFEmptyAboutTag RDF empty <about> tag
RDFAboutTagNotMetaid RDF <about> tag is not metaid
RDFNotCompleteModelHistory RDF does not contain valid ModelHistory
RDFNotModelHistory RDF does not result in a ModelHistory
AnnotationNotElement Annotation must contain element
UndeclaredUnits Missing unit declarations on parameters or literal numbers in expression
UndeclaredTimeUnitsL3 Unable to verify consistency of units: the unit of time has not been declared
UndeclaredExtentUnitsL3 Unable to verify consistency of units: the units of reaction extent have not been declared
UndeclaredObjectUnitsL3 Unable to verify consistency of units: encountered a model entity with no declared units
UnrecognisedSBOTerm Unrecognized 'sboTerm' attribute value
ObseleteSBOTerm Obsolete 'sboTerm' attribute value
IncorrectCompartmentSpatialDimensions In SBML Level 1, only three-dimensional compartments are allowed
CompartmentTypeNotValidAttribute CompartmentType objects are not available in this Level+Version of SBML
ConstantNotValidAttribute This Level+Version of SBML does not support the 'constant' attribute on this component
MetaIdNotValidAttribute Attribute 'metaid' is not available in SBML Level 1
SBOTermNotValidAttributeBeforeL2V3 The 'sboTerm' attribute is not available on this component before SBML Level 2 Version 3
InvalidL1CompartmentUnits Invalid units for a compartment in SBML Level 1
L1V1CompartmentVolumeReqd In SBML Level 1, a compartment's volume must be specified
CompartmentTypeNotValidComponent CompartmentType objects are not available in this Level+Version of SBML
ConstraintNotValidComponent Constraint objects are not available in this Level+Version of SBML
EventNotValidComponent Event objects are not available in this Level+Version of SBML
SBOTermNotValidAttributeBeforeL2V2 The 'sboTerm' attribute is invalid for this component before Level 2 Version 2
FuncDefNotValidComponent FunctionDefinition objects are not available in this Level+Version of SBML
InitialAssignNotValidComponent InitialAssignment objects are not available in this Level+Version of SBML
VariableNotValidAttribute Attribute 'variable' is not available on this component in this Level+Version of SBML
UnitsNotValidAttribute Attribute 'units' is not available on this component in this Level+Version of SBML
ConstantSpeciesNotValidAttribute Attribute 'constant' is not available on Species objects in SBML Level 1
SpatialSizeUnitsNotValidAttribute Attribute 'spatialSizeUnits' is not available on Species objects in SBML Level 1
SpeciesTypeNotValidAttribute Attribute 'speciesType' is not available on Species objects in SBML Level 1
HasOnlySubsUnitsNotValidAttribute Attribute 'hasOnlySubstanceUnits' is not available on Species objects in SBML Level 1
IdNotValidAttribute Attribute 'id' is not available on SpeciesReference objects in SBML Level 1
NameNotValidAttribute Attribute 'name' is not available on SpeciesReference objects in SBML Level 1
SpeciesTypeNotValidComponent The SpeciesType object is not supported in SBML Level 1
StoichiometryMathNotValidComponent The StoichiometryMath object is not supported in SBML Level 1
MultiplierNotValidAttribute Attribute 'multiplier' on Unit objects is not supported in SBML Level 1
OffsetNotValidAttribute Attribute 'offset' on Unit objects is only available in SBML Level 2 Version 1
L3SpatialDimensionsUnset No value given for 'spatialDimensions' attribute; assuming a value of 3
PackageConversionNotSupported Conversion of SBML Level 3 package constructs is not yet supported
InvalidTargetLevelVersion The requested SBML Level/Version combination is not known to exist
L3NotSupported SBML Level 3 is not yet supported
CompUnknown
CompNSUndeclared The comp ns is not correctly declared
CompElementNotInNs Element not in comp namespace
CompDuplicateComponentId Duplicate 'id' attribute value
CompUniqueModelIds Model and ExternalModelDefinitions must have unique ids
CompUniquePortIds Ports must have unique ids
CompInvalidSIdSyntax Invalid SId syntax
CompInvalidSubmodelRefSyntax Invalid submodelRef syntax
CompInvalidDeletionSyntax Invalid deletion syntax
CompInvalidConversionFactorSyntax Invalid conversionFactor syntax
CompInvalidNameSyntax Invalid name syntax
CompReplacedUnitsShouldMatch Units of replaced elements should match replacement units.
CompOneListOfReplacedElements Only one <listOfReplacedElements> allowed.
CompLOReplaceElementsAllowedElements Allowed children of <listOfReplacedElements>
CompLOReplacedElementsAllowedAttribs Allowed <listOfReplacedElements> attributes
CompEmptyLOReplacedElements <listOfReplacedElements> must not be empty
CompOneReplacedByElement Only one <replacedBy> object allowed.
CompAttributeRequiredMissing Required comp:required attribute on <sbml>
CompAttributeRequiredMustBeBoolean The comp:required attribute must be Boolean
CompRequiredTrueIfElementsRemain The comp:required attribute must be 'true' if math changes
CompRequiredFalseIfAllElementsReplaced The comp:required attribute must be 'false' if math does not change
CompOneListOfModelDefinitions Only one <listOfModelDefinitions> allowed.
CompEmptyLOModelDefs <listOfModelDefinitions> and <listOfExternalModelDefinitions> must not be empty
CompLOModelDefsAllowedElements Only <modelDefinitions> in <listOfModelDefinitions>
CompLOExtModelDefsAllowedElements Only <externalModelDefinitions> in <listOfExternalModelDefinitions>
CompLOModelDefsAllowedAttributes Allowed <listOfModelDefinitions> attributes
CompLOExtModDefsAllowedAttributes Allowed <listOfExternalModelDefinitions> attributes
CompOneListOfExtModelDefinitions Only one <listOfExternalModelDefinitions> allowed.
CompAttributeRequiredMustBeTrue The comp:required attribute must be 'true'
CompExtModDefAllowedCoreAttributes Allowed <externalModelDefinitions> core attributes
CompExtModDefAllowedElements Allowed <externalModelDefinitions> elements
CompExtModDefAllowedAttributes Allowed <externalModelDefinitions> attributes
CompReferenceMustBeL3 External models must be L3
CompModReferenceMustIdOfModel 'modelRef' must be the 'id' of a model in the 'source' document
CompExtModMd5DoesNotMatch MD5 checksum does not match the 'source' document
CompInvalidSourceSyntax The 'comp:source' attribute must be of type 'anyURI'
CompInvalidModelRefSyntax The 'comp:modelRef' attribute must have the syntax of 'SId'
CompInvalidMD5Syntax The 'comp:md5' attribute must have the syntax of 'string'
CompCircularExternalModelReference Circular reference in <externalModelDefinitiongt;
CompOneListOfOnModel Only one <listOfSubmodels> and one <listOfPorts> allowed
CompNoEmptyListOfOnModel No empty listOf elements allowed
CompLOSubmodelsAllowedElements Allowed elements on <listOfSubmodels>
CompLOPortsAllowedElements Allowed elements on <listOfPorts>
CompLOSubmodelsAllowedAttributes Allowed attributes on <listOfSubmodels>
CompLOPortsAllowedAttributes Allowed attributes on <listOfPorts>
CompSubmodelAllowedCoreAttributes Allowed core attributes on <submodel>
CompSubmodelAllowedElements Allowed elements on <submodel>
CompOneListOfDeletionOnSubmodel Only one <listOfDeletions> on a <submodel> allowed
CompSubmodelNoEmptyLODeletions No empty listOfDeletions elements allowed
CompLODeletionsAllowedElements Allowed elements on <listOfDeletions>
CompLODeletionAllowedAttributes Allowed <listOfDeletions> attributes
CompSubmodelAllowedAttributes Allowed <submodel> attributes
CompModReferenceSyntax 'comp:modelRef' must conform to SId syntax
CompInvalidTimeConvFactorSyntax 'comp:timeConversionFactor' must conform to SId syntax
CompInvalidExtentConvFactorSyntax 'comp:extentConversionFactor' must conform to SId syntax
CompSubmodelMustReferenceModel The 'comp:modelRef' attribute must reference a model
CompSubmodelCannotReferenceSelf The 'comp:modelRef' attribute cannot reference own model
CompModCannotCircularlyReferenceSelf <model> may not reference <submodel> that references itself.
CompTimeConversionMustBeParameter The 'comp:timeConversionFactor' must reference a parameter
CompExtentConversionMustBeParameter The 'comp:extentConversionFactor' must reference a parameter
CompPortRefMustReferencePort The 'comp:portRef' attribute must be the 'id' of a <port>
CompIdRefMustReferenceObject The 'comp:idRef' attribute must be the 'id' of a model element
CompUnitRefMustReferenceUnitDef The 'comp:unitRef' attribute must be the 'id' of a UnitDefinition
CompMetaIdRefMustReferenceObject The 'comp:metaIdRef' attribute must be the 'metaid' of an object
CompParentOfSBRefChildMustBeSubmodel If <sBaseRef> has a child <sBaseRef> its parent must be a <submodel>
CompInvalidPortRefSyntax The 'comp:portRef' attribute must have the syntax of an SBML SId
CompInvalidIdRefSyntax The 'comp:idRef' attribute must have the syntax of an SBML SId
CompInvalidUnitRefSyntax The 'comp:unitRef' attribute must have the syntax of an SBML SId
CompInvalidMetaIdRefSyntax The 'comp:metaIdRef' attribute must have the syntax of an XML ID
CompOneSBaseRefOnly Only one <sbaseRef>
CompDeprecatedSBaseRefSpelling The spelling 'sbaseRef' is deprecated
CompSBaseRefMustReferenceObject An SBaseRef must reference an object.
CompSBaseRefMustReferenceOnlyOneObject An SBaseRef must reference only one other object.
CompNoMultipleReferences Objects may not be referenced by mutiple SBaseRef constructs.
CompPortMustReferenceObject Port must reference an object
CompPortMustReferenceOnlyOneObject Port must reference only one other object.
CompPortAllowedAttributes Allowed attributes on a Port
CompPortReferencesUnique Port definitions must be unique.
CompDeletionMustReferenceObject Deletion must reference an object
CompDeletionMustReferOnlyOneObject Deletion must reference only one other object.
CompDeletionAllowedAttributes Allowed attributes on a Deletion
CompReplacedElementMustRefObject ReplacedElement must reference an object
CompReplacedElementMustRefOnlyOne ReplacedElement must reference only one other object.
CompReplacedElementAllowedAttributes Allowed attributes on <replacedElement>
CompReplacedElementSubModelRef The 'comp:submodelRef' attribute must point to a <submodel>
CompReplacedElementDeletionRef The 'comp:deletion' attribute must point to a <deletion>
CompReplacedElementConvFactorRef The 'comp:conversionFactor attribute must point to a <parameter>
CompReplacedElementSameReference No <replacedElement> refer to same object
CompReplacedElementNoDelAndConvFact No <replacedElement> with deletion and conversionfactor
CompReplacedByMustRefObject ReplacedBy must reference an object
CompReplacedByMustRefOnlyOne ReplacedBy must reference only one other object.
CompReplacedByAllowedAttributes Allowed attributes on <replacedBy>
CompReplacedBySubModelRef The 'comp:submodelRef' attribute must point to a <submodel>
CompMustReplaceSameClass Replaced classes must match.
CompMustReplaceIDs Replaced IDs must be replaced with IDs.
CompMustReplaceMetaIDs Replaced metaids must be replaced with metaids.
CompMustReplacePackageIDs Replaced package IDs must be replaced with package IDs.
CompUnresolvedReference Unresolved reference.
CompNoModelInReference No model in referenced document.
CompExtModDefBad Referenced <externalModelDefinitiongt; unresolvable.
CompModelFlatteningFailed Model failed to flatten.
CompFlatModelNotValid Flat model not valid.
CompLineNumbersUnreliable Line numbers unreliable.
CompFlatteningNotRecognisedReqd Flattening not implemented for required package.
CompFlatteningNotRecognisedNotReqd Flattening not implemented for unrequired package.
CompFlatteningNotImplementedNotReqd Flattening not implemented for unrequired package.
CompFlatteningNotImplementedReqd Flattening not implemented for required package.
CompFlatteningWarning Flattening reference may come from package.
CompDeprecatedDeleteFunction The performDeletions functions is deprecated.
CompDeprecatedReplaceFunction The performReplacementsAndConversions fuctions is deprecated.
CompDeletedReplacement Element deleted before a subelement could be replaced.
CompIdRefMayReferenceUnknownPackage The 'comp:idRef' attribute must be the 'id' of a model element
CompMetaIdRefMayReferenceUnknownPkg The 'comp:metaIdRef' attribute must be the 'metaid' of a model element
FbcUnknown
FbcNSUndeclared The fbc ns is not correctly declared
FbcElementNotInNs Element not in fbc namespace
FbcDuplicateComponentId Duplicate 'id' attribute value
FbcSBMLSIdSyntax Invalid 'id' attribute
FbcAttributeRequiredMissing Required fbc:required attribute on <sbml>
FbcAttributeRequiredMustBeBoolean The fbc:required attribute must be Boolean
FbcRequiredFalse The fbc:required attribute must be 'false'
FbcOnlyOneEachListOf One of each list of allowed
FbcNoEmptyListOfs ListOf elements cannot be empty
FbcLOFluxBoundsAllowedElements Allowed elements on ListOfFluxBounds
FbcLOObjectivesAllowedElements Allowed elements on ListOfObjectives
FbcLOFluxBoundsAllowedAttributes Allowed attributes on ListOfFluxBounds
FbcLOObjectivesAllowedAttributes Allowed attributes on ListOfObjectives
FbcActiveObjectiveSyntax Type of activeObjective attribute
FbcActiveObjectiveRefersObjective ActiveObjective must reference Objective
FbcSpeciesAllowedL3Attributes Species allowed attributes
FbcSpeciesChargeMustBeInteger Charge must be integer
FbcSpeciesFormulaMustBeString Chemical formula must be string
FbcFluxBoundAllowedL3Attributes <fluxBound> may only have 'metaId' and 'sboTerm' from L3 namespace
FbcFluxBoundAllowedElements <fluxBound> may only have <notes> and <annotations> from L3 Core
FbcFluxBoundRequiredAttributes Invalid attribute found on <fluxBound> object
FbcFluxBoundRectionMustBeSIdRef Datatype for 'fbc:reaction' must be SIdRef
FbcFluxBoundNameMustBeString The attribute 'fbc:name' must be of the data type string
FbcFluxBoundOperationMustBeEnum The attribute 'fbc:operation' must be of data type FbcOperation
FbcFluxBoundValueMustBeDouble The attribute 'fbc:value' must be of the data type float
FbcFluxBoundReactionMustExist 'fbc:reaction' must refer to valid reaction
FbcFluxBoundsForReactionConflict Conflicting set of FluxBounds for a reaction
FbcObjectiveAllowedL3Attributes <objective> may only have 'metaId' and 'sboTerm' from L3 namespace
FbcObjectiveAllowedElements <objective> may only have <notes> and <annotations> from L3 Core
FbcObjectiveRequiredAttributes Invalid attribute found on <objective> object
FbcObjectiveNameMustBeString The attribute 'fbc:name' must be of the data type string
FbcObjectiveTypeMustBeEnum The attribute 'fbc:type' must be of data type FbcType.
FbcObjectiveOneListOfObjectives An <objective> must have one <listOfFluxObjectives>.
FbcObjectiveLOFluxObjMustNotBeEmpty <listOfFluxObjectives> subobject must not be empty
FbcObjectiveLOFluxObjOnlyFluxObj Invalid element found in <listOfFluxObjectives>
FbcObjectiveLOFluxObjAllowedAttribs <listOfFluxObjectives> may only have 'metaId' and 'sboTerm' from L3 core
FbcFluxObjectAllowedL3Attributes <fluxObjectivegt; may only have 'metaId' and 'sboTerm' from L3 namespace
FbcFluxObjectAllowedElements <fluxObjectivegt; may only have <notes> and <annotations> from L3 Core
FbcFluxObjectRequiredAttributes Invalid attribute found on <fluxObjectivegt; object
FbcFluxObjectNameMustBeString The attribute 'fbc:name' must be of the data type string
FbcFluxObjectReactionMustBeSIdRef Datatype for 'fbc:reaction' must be SIdRef
FbcFluxObjectReactionMustExist 'fbc:reaction' must refer to valid reaction
FbcFluxObjectCoefficientMustBeDouble The attribute 'fbc:coefficient' must be of the data type float
QualUnknown
QualNSUndeclared The qual ns is not correctly declared
QualElementNotInNs Element not in qual namespace
QualFunctionTermBool FunctionTerm should return boolean
QualMathCSymbolDisallowed CSymbol time or delay not allowed
QualDuplicateComponentId Duplicate 'id' attribute value
QualAttributeRequiredMissing Required qual:required attribute on <sbml>
QualAttributeRequiredMustBeBoolean The qual:required attribute must be Boolean
QualRequiredTrueIfTransitions The qual:required attribute must be 'true' if math changes
QualOneListOfTransOrQS Only one <listOfTransitions> or <listOfQualitativeSpeciesgt; allowed.
QualEmptyLONotAllowed Empty <listOfTransitions> or <listOfQualitativeSpeciesgt; not allowed.
QualLOTransitiondAllowedElements Elements allowed on <listOfTransitions>.
QualLOQualSpeciesAllowedElements Elements allowed on <listOfTransitions>.
QualLOQualSpeciesAllowedAttributes Attributes allowed on <listOfQualitativeSpeciesgt;.
QualLOTransitionsAllowedAttributes Attributes allowed on <listOfTransitions>.
QualQualSpeciesAllowedCoreAttributes Core attributes allowed on <qualitativeSpeciesgt;.
QualQualSpeciesAllowedElements Elements allowed on <qualitativeSpeciesgt;.
QualQualSpeciesAllowedAttributes Attributes allowed on <qualitativeSpeciesgt;.
QualConstantMustBeBool Attribute 'constant' on <qualitativeSpeciesgt; must be boolean.
QualNameMustBeString Attribute 'name' on <qualitativeSpeciesgt; must be string.
QualInitialLevelMustBeInt Attribute 'initialLevel' on <qualitativeSpeciesgt; must be integer.
QualMaxLevelMustBeInt Attribute 'maxLevel' on <qualitativeSpeciesgt; must be integer.
QualCompartmentMustReferExisting Attribute 'compartment' on <qualitativeSpeciesgt; must reference compartment.
QualInitialLevelCannotExceedMax Attribute 'initialLevel' on <qualitativeSpeciesgt; cannot exceed maxLevel.
QualConstantQSCannotBeOutput Constant <qualitativeSpeciesgt; cannot be an Output.
QualQSAssignedOnlyOnce A <qualitativeSpeciesgt; can only be assigned once.
QualInitalLevelNotNegative Attribute 'initialLevel' on <qualitativeSpeciesgt; cannot be negative.
QualMaxLevelNotNegative Attribute 'maxLevel' on <qualitativeSpeciesgt; cannot be negative.
QualTransitionAllowedCoreAttributes Core attributes allowed on <transition>.
QualTransitionAllowedElements Elements allowed on <transition>.
QualTransitionAllowedAttributes Attributes allowed on <transition>.
QualTransitionNameMustBeString Attribute 'name' on <transition> must be string.
QualTransitionLOElements ListOf elements on <transition>.
QualTransitionEmptyLOElements ListOf elements on <transition> not empty.
QualTransitionLOInputElements Elements on <listOfInputs>.
QualTransitionLOOutputElements Elements on <listOfOutputs>.
QualTransitionLOFuncTermElements Elements on <listOfFunctionTerms>.
QualTransitionLOInputAttributes Attributes allowed on <listOfInputs>.
QualTransitionLOOutputAttributes Attributes allowed on <listOfOutputs>.
QualTransitionLOFuncTermAttributes Attributes allowed on <listOfFunctionTerms>.
QualTransitionLOFuncTermExceedMax <listOfFunctionTerms> cannot make qualitativeSpecies exceed maxLevel.
QualTransitionLOFuncTermNegative <listOfFunctionTerms> cannot make qualitativeSpecies negative.
QualInputAllowedCoreAttributes Core attributes allowed on <input>.
QualInputAllowedElements Elements allowed on <input>.
QualInputAllowedAttributes Attributes allowed on <input>.
QualInputNameMustBeString Attribute 'name' on <input> must be string.
QualInputSignMustBeSignEnum Attribute 'sign' on <input> must be enum.
QualInputTransEffectMustBeInputEffect Attribute 'transitionEffect' on <input> must be enum.
QualInputThreshMustBeInteger Attribute 'thresholdLevel' on <input> must be non negative integer.
QualInputQSMustBeExistingQS Attribute 'qualitativeSpecies' on <input> must refer to existing
QualInputConstantCannotBeConsumed Constant <input> cannot be consumed.
QualInputThreshMustBeNonNegative Attribute 'thresholdLevel' on <input> must be non negative integer.
QualOutputAllowedCoreAttributes Core attributes allowed on <output>.
QualOutputAllowedElements Elements allowed on <output>.
QualOutputAllowedAttributes Attributes allowed on <output>.
QualOutputNameMustBeString Attribute 'name' on <output> must be string.
QualOutputTransEffectMustBeOutput Attribute 'transitionEffect' on <output> must be enum.
QualOutputLevelMustBeInteger Attribute 'outputLevel' on <output> must be non negative integer.
QualOutputQSMustBeExistingQS Attribute 'qualitativeSpecies' on <output> must refer to existing
QualOutputConstantMustBeFalse Constant 'qualitativeSpecies' cannot be <output>
QualOutputProductionMustHaveLevel <output> being produced must have level
QualOutputLevelMustBeNonNegative Attribute 'outputLevel' on <output> must be non negative integer.
QualDefaultTermAllowedCoreAttributes Core attributes allowed on <defaultTerm>.
QualDefaultTermAllowedElements Elements allowed on <defaultTerm>.
QualDefaultTermAllowedAttributes Attributes allowed on <defaultTerm>.
QualDefaultTermResultMustBeInteger Attribute 'resultLevel' on <defaultTerm> must be non negative integer.
QualDefaultTermResultMustBeNonNeg Attribute 'resultLevel' on <defaultTerm> must be non negative integer.
QualFuncTermAllowedCoreAttributes Core attributes allowed on <functionTerm>.
QualFuncTermAllowedElements Elements allowed on <functionTerm>.
QualFuncTermAllowedAttributes Attributes allowed on <functionTerm>.
QualFuncTermOnlyOneMath Only one <math> on <functionTerm>.
QualFuncTermResultMustBeInteger Attribute 'resultLevel' on <functionTerm> must be non negative integer.
QualFuncTermResultMustBeNonNeg Attribute 'resultLevel' on <functionTerm> must be non negative integer.
LayoutUnknownError
LayoutNSUndeclared The layout ns is not correctly declared
LayoutElementNotInNs Element not in layout namespace
LayoutDuplicateComponentId Duplicate 'id' attribute value
LayoutSIdSyntax 'id' attribute incorrect syntax
LayoutXsiTypeAllowedLocations 'xsi:type' allowed locations
LayoutXsiTypeSyntax 'xsi:type' attribute incorrect syntax
LayoutAttributeRequiredMissing Required layout:required attribute on <sbml>
LayoutAttributeRequiredMustBeBoolean The layout:required attribute must be Boolean
LayoutRequiredFalse The layout:required attribute must be 'false'
LayoutOnlyOneLOLayouts Only one listOfLayouts on <model>
LayoutLOLayoutsNotEmpty ListOf elements cannot be empty
LayoutLOLayoutsAllowedElements Allowed elements on ListOfLayouts
LayoutLOLayoutsAllowedAttributes Allowed attributes on ListOfLayouts
LayoutLayoutAllowedElements Allowed elements on Layout
LayoutLayoutAllowedCoreAttributes Allowed core attributes on Layout
LayoutOnlyOneEachListOf Only one each listOf on <layout>
LayoutNoEmptyListOfs ListOf elements cannot be empty
LayoutLayoutAllowedAttributes <layout> must have 'id' and may have 'name'
LayoutLayoutNameMustBeString 'name' must be string
LayoutLOCompGlyphAllowedAttributes Attributes allowed on <listOfCompartmentGlyphs>.
LayoutLOCompGlyphAllowedElements Elements allowed on <listOfCompartmentGlyphs>.
LayoutLOSpeciesGlyphAllowedAttributes Attributes allowed on <listOfSpeciesGlyphs>.
LayoutLOSpeciesGlyphAllowedElements Elements allowed on <listOfSpeciesGlyphs>.
LayoutLORnGlyphAllowedAttributes Attributes allowed on <listOfReactionGlyphs>.
LayoutLORnGlyphAllowedElements Elements allowed on <listOfReactionGlyphs>.
LayoutLOAddGOAllowedAttribut Attributes allowed on <listOfAdditionalGraphicalObjectGlyphs>.
LayoutLOAddGOAllowedElements Elements allowed on <listOfAdditionalGraphicalObjectGlyphs>.
LayoutLayoutMustHaveDimensions Layout must have <dimensions>.
LayoutLOTextGlyphAllowedAttributes Attributes allowed on <listOfTextGlyphs>.
LayoutLOTextGlyphAllowedElements Elements allowed on <listOfTextGlyphs>.
LayoutGOAllowedCoreElements Core elements allowed on <graphicalObject>.
LayoutGOAllowedCoreAttributes Core attributes allowed on <graphicalObject>.
LayoutGOAllowedElements Layout elements allowed on <graphicalObject>.
LayoutGOAllowedAttributes Layout attributes allowed on <graphicalObject>.
LayoutGOMetaIdRefMustBeIDREF Layout 'metIdRef' must be IDREF.
LayoutGOMetaIdRefMustReferenceObject Layout 'metIdRef' must reference existing object.
LayoutGOMustContainBoundingBox A <graphicalObject> must contain a <boundingBox>.
LayoutCGAllowedCoreElements Core elements allowed on <compartmentGlyph>.
LayoutCGAllowedCoreAttributes Core attributes allowed on <compartmentGlyph>.
LayoutCGAllowedElements Layout elements allowed on <compartmentGlyph>.
LayoutCGAllowedAttributes Layout attributes allowed on <compartmentGlyph>.
LayoutCGMetaIdRefMustBeIDREF Layout 'metIdRef' must be IDREF.
LayoutCGMetaIdRefMustReferenceObject Layout 'metIdRef' must reference existing object.
LayoutCGCompartmentSyntax CompartmentGlyph 'compartment' must have SIdRef syntax.
LayoutCGCompartmentMustRefComp CompartmentGlyph compartment must reference existing compartment.
LayoutCGNoDuplicateReferences CompartmentGlyph cannot reference two objects.
LayoutCGOrderMustBeDouble CompartmentGlyph order must be float.
LayoutSGAllowedCoreElements Core elements allowed on <speciesGlyph>.
LayoutSGAllowedCoreAttributes Core attributes allowed on <speciesGlyph>.
LayoutSGAllowedElements Layout elements allowed on <speciesGlyph>.
LayoutSGAllowedAttributes Layout attributes allowed on <speciesGlyph>.
LayoutSGMetaIdRefMustBeIDREF Layout 'metIdRef' must be IDREF.
LayoutSGMetaIdRefMustReferenceObject Layout 'metIdRef' must reference existing object.
LayoutSGSpeciesSyntax SpeciesGlyph 'species' must have SIdRef syntax.
LayoutSGSpeciesMustRefSpecies SpeciesGlyph species must reference existing species.
LayoutSGNoDuplicateReferences SpeciesGlyph cannot reference two objects.
LayoutRGAllowedCoreElements Core elements allowed on <reactionGlyph>.
LayoutRGAllowedCoreAttributes Core attributes allowed on <reactionGlyph>.
LayoutRGAllowedElements Layout elements allowed on <reactionGlyph>.
LayoutRGAllowedAttributes Layout attributes allowed on <reactionGlyph>.
LayoutRGMetaIdRefMustBeIDREF Layout 'metIdRef' must be IDREF.
LayoutRGMetaIdRefMustReferenceObject Layout 'metIdRef' must reference existing object.
LayoutRGReactionSyntax ReactionGlyph 'reaction' must have SIdRef syntax.
LayoutRGReactionMustRefReaction ReactionGlyph reaction must reference existing reaction.
LayoutRGNoDuplicateReferences ReactionGlyph cannot reference two objects.
LayoutLOSpeciesRefGlyphAllowedElements Allowed elements on ListOfSpeciesReferenceGlyphs
LayoutLOSpeciesRefGlyphAllowedAttribs Allowed attributes on ListOfSpeciesReferenceGlyphs
LayoutLOSpeciesRefGlyphNotEmpty ListOfSpeciesReferenceGlyphs not empty
LayoutGGAllowedCoreElements Core elements allowed on <generalGlyph>.
LayoutGGAllowedCoreAttributes Core attributes allowed on <generalGlyph>.
LayoutGGAllowedElements Layout elements allowed on <generalGlyph>.
LayoutGGAllowedAttributes Layout attributes allowed on <generalGlyph>.
LayoutGGMetaIdRefMustBeIDREF Layout 'metIdRef' must be IDREF.
LayoutGGMetaIdRefMustReferenceObject Layout 'metIdRef' must reference existing object.
LayoutGGReferenceSyntax GeneralGlyph 'reference' must have SIdRef syntax.
LayoutGGReferenceMustRefObject GeneralGlyph 'reference' must reference existing element.
LayoutGGNoDuplicateReferences GeneralGlyph cannot reference two objects.
LayoutLOReferenceGlyphAllowedElements Allowed elements on ListOfReferenceGlyphs
LayoutLOReferenceGlyphAllowedAttribs Allowed attributes on ListOfReferenceGlyphs
LayoutLOSubGlyphAllowedElements
LayoutLOSubGlyphAllowedAttribs Allowed attributes on ListOfSubGlyphs
LayoutTGAllowedCoreElements Core elements allowed on <textGlyph>.
LayoutTGAllowedCoreAttributes Core attributes allowed on <textGlyph>.
LayoutTGAllowedElements Layout elements allowed on <textGlyph>.
LayoutTGAllowedAttributes Layout attributes allowed on <textGlyph>.
LayoutTGMetaIdRefMustBeIDREF Layout 'metIdRef' must be IDREF.
LayoutTGMetaIdRefMustReferenceObject Layout 'metIdRef' must reference existing object.
LayoutTGOriginOfTextSyntax TextGlyph 'originOfText' must have SIdRef syntax.
LayoutTGOriginOfTextMustRefObject TextGlyph 'originOfText' must reference existing element.
LayoutTGNoDuplicateReferences TextGlyph cannot reference two objects.
LayoutTGGraphicalObjectSyntax TextGlyph 'graphicalObject' must have SIdRef syntax.
LayoutTGGraphicalObjectMustRefObject TextGlyph 'graphicalObject' must reference existing element.
LayoutTGTextMustBeString TextGlyph 'text' must be string.
LayoutSRGAllowedCoreElements Core elements allowed on <speciesReferenceGlyphgt;.
LayoutSRGAllowedCoreAttributes Core attributes allowed on <speciesReferenceGlyphgt;.
LayoutSRGAllowedElements Layout elements allowed on <speciesReferenceGlyphgt;.
LayoutSRGAllowedAttributes Layout attributes allowed on <speciesReferenceGlyphgt;.
LayoutSRGMetaIdRefMustBeIDREF Layout 'metIdRef' must be IDREF.
LayoutSRGMetaIdRefMustReferenceObject Layout 'metIdRef' must reference existing object.
LayoutSRGSpeciesReferenceSyntax SpeciesReferenceGlyph 'speciesReference' must have SIdRef syntax.
LayoutSRGSpeciesRefMustRefObject SpeciesReferenceGlyph 'speciesReference' must reference existing element.
LayoutSRGNoDuplicateReferences SpeciesReferenceGlyph cannot reference two objects.
LayoutSRGSpeciesGlyphSyntax SpeciesReferenceGlyph 'speciesGlyph' must have SIdRef syntax.
LayoutSRGSpeciesGlyphMustRefObject SpeciesReferenceGlyph 'speciesGlyph' must reference existing element.
LayoutSRGRoleSyntax SpeciesReferenceGlyph 'role' must be string from enumeration.
LayoutREFGAllowedCoreElements Core elements allowed on <referenceGlyph>.
LayoutREFGAllowedCoreAttributes Core attributes allowed on <referenceGlyph>.
LayoutREFGAllowedElements Layout elements allowed on <referenceGlyph>.
LayoutREFGAllowedAttributes Layout attributes allowed on <referenceGlyph>.
LayoutREFGMetaIdRefMustBeIDREF Layout 'metIdRef' must be IDREF.
LayoutREFGMetaIdRefMustReferenceObject Layout 'metIdRef' must reference existing object.
LayoutREFGReferenceSyntax ReferenceGlyph 'reference' must have SIdRef syntax.
LayoutREFGReferenceMustRefObject ReferenceGlyph 'reference' must reference existing element.
LayoutREFGNoDuplicateReferences ReferenceGlyph cannot reference two objects.
LayoutREFGGlyphSyntax ReferenceGlyph 'glyph' must have SIdRef syntax.
LayoutREFGGlyphMustRefObject ReferenceGlyph 'glyph' must reference existing element.
LayoutREFGRoleSyntax ReferenceGlyph 'role' must be string.
LayoutPointAllowedCoreElements Core elements allowed on <point>.
LayoutPointAllowedCoreAttributes Core attributes allowed on <point>.
LayoutPointAllowedAttributes Layout attributes allowed on <point>.
LayoutPointAttributesMustBeDouble Layout 'x', 'y' and 'z' must be float.
LayoutBBoxAllowedCoreElements Core elements allowed on <boundingBox>.
LayoutBBoxAllowedCoreAttributes Core attributes allowed on <boundingBox>.
LayoutBBoxAllowedElements Layout elements allowed on <boundingBox>.
LayoutBBoxAllowedAttributes Layout attributes allowed on <boundingBox>.
LayoutBBoxConsistent3DDefinition Layout consistent dimensions on a <boundingBox>
LayoutCurveAllowedCoreElements Core elements allowed on <curve>.
LayoutCurveAllowedCoreAttributes Core attributes allowed on <curve>.
LayoutCurveAllowedElements Layout elements allowed on <curve>.
LayoutCurveAllowedAttributes Layout attributes allowed on <curve>.
LayoutLOCurveSegsAllowedAttributes Allowed attributes on ListOfCurveSegments
LayoutLOCurveSegsAllowedElements Allowed elements on ListOfCurveSegments
LayoutLOCurveSegsNotEmpty No empty ListOfCurveSegments
LayoutLSegAllowedCoreElements Core elements allowed on <lineSegment>.
LayoutLSegAllowedCoreAttributes Core attributes allowed on <lineSegment>.
LayoutLSegAllowedElements Layout elements allowed on <lineSegment>.
LayoutLSegAllowedAttributes Layout attributes allowed on <lineSegment>.
LayoutCBezAllowedCoreElements Core elements allowed on <cubicBezier>.
LayoutCBezAllowedCoreAttributes Core attributes allowed on <cubicBezier>.
LayoutCBezAllowedElements Layout elements allowed on <cubicBezier>.
LayoutCBezAllowedAttributes Layout attributes allowed on <cubicBezier>.
LayoutDimsAllowedCoreElements Core elements allowed on <dimensions>.
LayoutDimsAllowedCoreAttributes Core attributes allowed on <dimensions>.
LayoutDimsAllowedAttributes Layout attributes allowed on <dimensions>.
LayoutDimsAttributesMustBeDouble Layout 'width', 'height' and 'depth' must be float.

Category codes associated with SBMLError objects

As discussed above, each SBMLError object contains a value for a category identifier, describing the type of issue that the SBMLError object represents. The category can be retrieved from an SBMLError object using the method SBMLError.getCategory(). The following table lists each possible value and a brief description of its meaning.

As is the case with the error codes, in the libSBML Python language interface, the category identifiers are currently implemented as static integer constants defined in the interface class libsbml.

The following table lists each possible value and a brief description of its meaning.

Enumerator Meaning
LIBSBML_CAT_SBMLGeneral error not falling into another category below.
LIBSBML_CAT_SBML_L1_COMPATCategory of errors that can only occur during attempted translation from one Level/Version of SBML to another. This particular category applies to errors encountered while trying to convert a model from SBML Level 2 to SBML Level 1.
LIBSBML_CAT_SBML_L2V1_COMPATCategory of errors that can only occur during attempted translation from one Level/Version of SBML to another. This particular category applies to errors encountered while trying to convert a model to SBML Level 2 Version 1.
LIBSBML_CAT_SBML_L2V2_COMPATCategory of errors that can only occur during attempted translation from one Level/Version of SBML to another. This particular category applies to errors encountered while trying to convert a model to SBML Level 2 Version 2.
LIBSBML_CAT_GENERAL_CONSISTENCYCategory of errors that can occur while validating general SBML constructs. With respect to the SBML specification, these concern failures in applying the validation rules numbered 2xxxx in the Level 2 Versions 2–4 and Level 3 Version 1 specifications.
LIBSBML_CAT_IDENTIFIER_CONSISTENCYCategory of errors that can occur while validating symbol identifiers in a model. With respect to the SBML specification, these concern failures in applying the validation rules numbered 103xx in the Level 2 Versions 2–4 and Level 3 Version 1 specifications.
LIBSBML_CAT_UNITS_CONSISTENCYCategory of errors that can occur while validating the units of measurement on quantities in a model. With respect to the SBML specification, these concern failures in applying the validation rules numbered 105xx in the Level 2 Versions 2–4 and Level 3 Version 1 specifications.
LIBSBML_CAT_MATHML_CONSISTENCYCategory of errors that can occur while validating MathML formulas in a model. With respect to the SBML specification, these concern failures in applying the validation rules numbered 102xx in the Level 2 Versions 2–4 and Level 3 Version 1 specifications.
LIBSBML_CAT_SBO_CONSISTENCYCategory of errors that can occur while validating SBO identifiers in a model. With respect to the SBML specification, these concern failures in applying the validation rules numbered 107xx in the Level 2 Versions 2–4 and Level 3 Version 1 specifications.
LIBSBML_CAT_OVERDETERMINED_MODELError in the system of equations in the model: the system is overdetermined, therefore violating a tenet of proper SBML. With respect to the SBML specification, this is validation rule #10601 in the SBML Level 2 Versions 2–4 and Level 3 Version 1 specifications.
LIBSBML_CAT_SBML_L2V3_COMPATCategory of errors that can only occur during attempted translation from one Level/Version of SBML to another. This particular category applies to errors encountered while trying to convert a model to SBML Level 2 Version 3.
LIBSBML_CAT_MODELING_PRACTICECategory of warnings about recommended good practices involving SBML and computational modeling. (These are tests performed by libSBML and do not have equivalent SBML validation rules.)
LIBSBML_CAT_INTERNAL_CONSISTENCYCategory of errors that can occur while validating libSBML's internal representation of SBML constructs. (These are tests performed by libSBML and do not have equivalent SBML validation rules.)
LIBSBML_CAT_SBML_L2V4_COMPATCategory of errors that can only occur during attempted translation from one Level/Version of SBML to another. This particular category applies to errors encountered while trying to convert a model to SBML Level 2 Version 4.
LIBSBML_CAT_SBML_L3V1_COMPAT

Category of errors that can only occur during attempted translation from one Level/Version of SBML to another. This particular category applies to errors encountered while trying to convert a model to SBML Level 3 Version 1.

Severity codes associated with SBMLError objects

In libSBML version 5.11.0 there are no additional severity codes beyond those defined by XMLError. They are implemented as static integer constants defined in the interface class libsbml, and have names beginning with LIBSBML_SEV_.

This method has multiple variants; they differ in the arguments they accept.

__init__(long errorId=0, long level, long version, string details, long line=0, long column=0, long severity=LIBSBML_SEV_ERROR, long category=LIBSBML_CAT_SBML, string package, long pkgVersion=1)   SBMLError
__init__(long errorId=0, long level, long version, string details, long line=0, long column=0, long severity=LIBSBML_SEV_ERROR, long category=LIBSBML_CAT_SBML, string package)   SBMLError
__init__(long errorId=0, long level, long version, string details, long line=0, long column=0, long severity=LIBSBML_SEV_ERROR, long category=LIBSBML_CAT_SBML)   SBMLError
__init__(long errorId=0, long level, long version, string details, long line=0, long column=0, long severity=LIBSBML_SEV_ERROR)   SBMLError
__init__(long errorId=0, long level, long version, string details, long line=0, long column=0)   SBMLError
__init__(long errorId=0, long level, long version, string details, long line=0)   SBMLError
__init__(long errorId=0, long level, long version, string details)   SBMLError
__init__(long errorId=0, long level, long version)   SBMLError
__init__(long errorId=0, long level)   SBMLError
__init__(long errorId=0)   SBMLError
__init__()   SBMLError
__init__(SBMLError orig)   SBMLError

Each variant is described separately below.


Method variant with the following signature:
SBMLError(SBMLError orig)

Copy constructor; creates a copy of this SBMLError.


Method variant with the following signature:
SBMLError(long errorId = 0, long level = SBML_DEFAULT_LEVEL, long version = SBML_DEFAULT_VERSION, string details = '', long line = 0, long column = 0, long severity = LIBSBML_SEV_ERROR, long category = LIBSBML_CAT_SBML, string package = 'core', long pkgVersion = 1)

Creates a new SBMLError to report that something occurred during SBML processing.

When a libSBML operation on SBML content results in a warning, error or other diagnostic, the issue is reported as an SBMLError object. SBMLError objects have identification numbers to indicate the nature of the exception.These numbers are defined as longeger constants in the interface class libsbml. See the top of this documentation page for a table listing the possible values and their meanings. The argument errorId to this constructor can be (but does not have to be) a value from this set of constants. If it is one of the predefined error identifiers, the SBMLError class assumes the error is a low-level system or SBML layer error and prepends a built-in, predefined error message to any string passed in the argument details to this constructor. In addition, all the predefined error identifiers have associated values for the severity and category codes, and these fields are filled-in using the libSBML defaults for each different error identifier.

If the error identifier errorId is a number greater than 99999, the SBMLError class assumes the error was generated from another part of the software and does not do additional filling in of values beyond the default in the constructor itself. This allows SBMLError to serve as a base class for other errors, such as for user-defined validation rules (see Validator). Callers should fill in all the parameters with suitable values if generating errors with codes greater than 99999 to make maximum use of the SBMLError facilities.

As mentioned above, there are additional constants defined for standard severity and standard category codes, and every predefined error in libSBML has an associated value for severity and category taken from these predefined sets. These constants have symbol names prefixed with LIBSBML_SEV_ and LIBSBML_CAT_, respectively. If the value of errorId is one of the standard error codes, callers do not need to fill in severity and category in a call to this constructor. Conversely, if errorId is not an existing SBML-level error code, callers can use other values for severity and category.

Please see the top of the documentation for SBMLError for a longer discussion of the possible error codes, their meanings, and their applicability to different combinations of Level+Version of SBML.

Parameters
errorIda long integer, the identification number of the error.
levelthe SBML Level of the SBML model
versionthe SBML Version within the Level of the SBML model
detailsa string containing additional details about the error. If the error code in errorId is one that is recognized by SBMLError, the given message is appended to a predefined message associated with the given code. If the error code is not recognized, the message is stored as-is as the text of the error.
linea long integer, the line number at which the error occured.
columna long integer, the column number at which the error occured.
severityan integer indicating severity of the error.
categoryan integer indicating the category to which the error belongs.
packagethe SBML Level package involved.
pkgVersionthe version of the package.
def libsbml.CVTerm.__init__ (   self,
  args 
)

A MIRIAM-compliant controlled vocabulary term.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The SBML Level 2 and Level 3 specifications define a simple format for annotating models when (a) referring to controlled vocabulary terms and database identifiers that define and describe biological and biochemical entities, and (b) describing the creator of a model and the model's modification history. This SBML format is a concrete syntax that conforms to the guidelines of MIRIAM ('Minimum Information Requested in the Annotation of biochemical Models', Nature Biotechnology, vol. 23, no. 12, Dec. 2005). The format uses a subset of W3C RDF (Resource Description Format). In order to help application developers work with annotations in this format, libSBML provides several helper classes that provide higher-level interfaces to the data elements; these classes include CVTerm, ModelCreator, ModelHistory, RDFAnnotationParser, and Date.

Components of an SBML annotation

The SBML annotation format consists of RDF-based content placed inside an <annotation> element attached to an SBML component such as Species, Compartment, etc. A small change was introduced in SBML Level 2 Version 5 and SBML Level 3 Version 2 to permit nested annotations: lower Versions of the SBML specifications did not explicitly allow this. We first describe the different parts of SBML annotations in XML form for SBML Level 2 below Version 5 and SBML Level 3 below Version 2:

 <SBML_ELEMENT +++ metaid="meta id" +++>
   +++
   <annotation>
 +++
 <rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'
          xmlns:dcterm='http://purl.org/dc/terms/'
          xmlns:vcard='http://www.w3.org/2001/vcard-rdf/3.0#'
          xmlns:bqbiol='http://biomodels.net/biology-qualifiers/'
          xmlns:bqmodel='http://biomodels.net/model-qualifiers/' >
   <rdf:Description rdf:about="#meta id">
     HISTORY
     <RELATION_ELEMENT>
       <rdf:Bag>
         <rdf:li rdf:resource="URI" />
         ...
       </rdf:Bag>
     </RELATION_ELEMENT>
     ...
   </rdf:Description>
   +++
 </rdf:RDF>
 +++
   </annotation>
   +++
 </SBML_ELEMENT>
 

In the template above, the placeholder SBML_ELEMENT stands for the XML tag name of an SBML model component (e.g., model, reaction, etc.) and the placeholder meta id stands for the element's meta identifier, which is a field available on all SBML components derived from the SBase base object class. The dotted portions are optional, the symbol +++ is a placeholder for either no content or valid XML content that is not defined by this annotation scheme, and the ellipses ... are placeholders for zero or more elements of the same form as the immediately preceding element. The optional content HISTORY is a creation and modification history; in libSBML, this is stored using ModelHistory objects.

The placeholder RELATION_ELEMENT refers to a BioModels.net qualifier element name. This is an element in either the XML namespace 'http://biomodels.net/model-qualifiers' (for model qualifiers) or 'http://biomodels.net/biology-qualifiers' (for biological qualifier). Note that these namespace URIs are only labels, and not actual Web locations, which means you cannot visit an address such as 'http://biomodels.net/model-qualifiers' in your browser or try to have your application access it.

The URI is a required data value that uniquely identifies a resource and data within that resource to which the annotation refers. Again, being URIs, these do not refer to physical Web locations; nevertheless, applications will often want a means of finding the resource to which a given URI refers. Providing the facilities for this task is the purpose of MIRIAM Resources, described in detail online at http://biomodels.net/miriam) and also in the paper 'MIRIAM Resources: tools to generate and resolve robust cross-references in Systems Biology', BMC Systems Biology, 58(1), 2007.

Finally, the following is the same template as above, but this time showing the nested content permitted by the most recent SBML specifications (SBML Level 2 Version 5 and Level 3 Version 2):

 <SBML_ELEMENT +++ metaid="meta id" +++>
   +++
   <annotation>
 +++
 <rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'
          xmlns:dcterm='http://purl.org/dc/terms/'
          xmlns:vcard='http://www.w3.org/2001/vcard-rdf/3.0#'
          xmlns:bqbiol='http://biomodels.net/biology-qualifiers/'
          xmlns:bqmodel='http://biomodels.net/model-qualifiers/' >
   <rdf:Description rdf:about="#meta id">
     HISTORY
     <RELATION_ELEMENT>
       <rdf:Bag>
         <rdf:li rdf:resource="URI" />
         NESTED_CONTENT
         ...
       </rdf:Bag>
     </RELATION_ELEMENT>
     ...
   </rdf:Description>
   +++
 </rdf:RDF>
 +++
   </annotation>
   +++
 </SBML_ELEMENT>
 

The placeholder NESTED_CONTENT refers to other optional RDF elements such as 'bqbiol:isDescribedBy' that describe a clarification or another annotation about the RELATION_ELEMENT in which it appears. Nested content allows one to, for example, describe protein modifications on species, or to add evidence codes for an annotation. Nested content relates to its containing RELATION_ELEMENT, not the other way around. It qualifies it, but does not change its meaning. As such, ignoring a NESTED_CONTENT does not affect the information provided by the containing RELATION_ELEMENT.

For more information about SBML annotations in general, please refer to Section 6 in the SBML Level 2 (Versions 2–4) or Level 3 specification documents.

The parts of a CVTerm

Annotations that refer to controlled vocabularies are managed in libSBML using CVTerm objects. The relation-resource pairs discussed in the previous section are the 'controlled vocabulary' terms that CVTerm is designed to store and manipulate. A set of RDF-based annotations attached to a given SBML <annotation> element are read by RDFAnnotationParser and converted into a list of these CVTerm objects. Each CVTerm object instance stores the following components of an annotation:

  • The qualifier, which can be a BioModels.net 'biological qualifier', a BioModels.net 'model qualifier', or an unknown qualifier (as far as the CVTerm class is concerned). Qualifiers are used in MIRIAM to indicate the nature of the relationship between the object being annotated and the resource. In CVTerm, the qualifiers can be manipulated using the methods CVTerm.getQualifierType(), CVTerm.setQualifierType(), and related methods.

  • The resource, represented by a URI (which, we must remind developers, is not the same as a URL). In the CVTerm class, the resource component can be manipulated using the methods CVTerm.addResource() and CVTerm.removeResource().

Note that a CVTerm contains a single qualifier, but possibly more than one resource. This corresponds to the possibility of an annotation that points to multiple resources, all of which are qualified by the same BioModels.net qualifier. The CVTerm object class supports this by supporting a list of resources.

Detailed explanations of the qualifiers defined by BioModels.net can be found at http://co.mbine.org/standards/qualifiers.

This method has multiple variants; they differ in the arguments they accept.

__init__(long type=UNKNOWN_QUALIFIER)   CVTerm
__init__()   CVTerm
__init__(XMLNode node)   CVTerm
__init__(CVTerm orig)   CVTerm

Each variant is described separately below.


Method variant with the following signature:
CVTerm(XMLNode node)

Creates a new CVTerm from the given XMLNode.

The SBML Level 2 and Level 3 specifications define a simple format for annotating models when (a) referring to controlled vocabulary terms and database identifiers that define and describe biological and other entities, and (b) describing the creator of a model and the model's modification history. The annotation content is stored in <annotation> elements attached to individual SBML elements. The format for storing the content inside SBML <annotation> elements is a subset of W3C RDF (Resource Description Format) expressed in XML. The CVTerm class provides a programming interface for working directly with controlled vocabulary term ('CV term') objects without having to deal directly with the XML form. When libSBML reads in an SBML model containing RDF annotations, it parses those annotations into a list of CVTerm objects, and when writing a model, it parses the CVTerm objects back into the appropriate SBML <annotation> structure.

This method creates a CVTerm object from the given XMLNode object node. XMLNode is libSBML's representation of a node in an XML tree of elements, and each such element can be placed in a namespace. This constructor looks for the element to be in the XML namespaces 'http://biomodels.net/model-qualifiers' (for model qualifiers) and 'http://biomodels.net/biology-qualifiers' (for biological qualifier), and if they are, creates CVTerm objects for the result.

Parameters
nodean XMLNode representing a CVTerm.
Note
This method assumes that the given XMLNode object node is of the correct structural form.

Method variant with the following signature:
CVTerm(CVTerm orig)

Copy constructor; creates a copy of a CVTerm object.

Parameters
origthe CVTerm instance to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
CVTerm(long type = UNKNOWN_QUALIFIER)

Creates an empty CVTerm, optionally with the given qualifier type.

The SBML Level 2 and Level 3 specifications define a simple format for annotating models when (a) referring to controlled vocabulary terms and database identifiers that define and describe biological and other entities, and (b) describing the creator of a model and the model's modification history. The annotation content is stored in <annotation> elements attached to individual SBML elements. The format for storing the content inside SBML <annotation> elements is a subset of W3C RDF (Resource Description Format) expressed in XML. The CVTerm class provides a programming interface for working directly with controlled vocabulary term ('CV term') objects without having to deal directly with the XML form. When libSBML reads in an SBML model containing RDF annotations, it parses those annotations into a list of CVTerm objects, and when writing a model, it parses the CVTerm objects back into the appropriate SBML <annotation> structure.

This method creates an empty CVTerm object. The possible qualifier types usable as values of type are MODEL_QUALIFIER and BIOLOGICAL_QUALIFIER. If an explicit value for type is not given, this method defaults to using UNKNOWN_QUALIFIER. The qualifier type can be set later using the CVTerm.setQualifierType() method.

Different BioModels.net qualifier elements encode different types of relationships. Please refer to the SBML specification or the BioModels.net qualifiers web page for an explanation of the meaning of these different qualifiers.

Parameters
typea qualifier type
def libsbml.Date.__init__ (   self,
  args 
)

A MIRIAM-compliant date representation.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

A Date object stores a reasonably complete representation of date and time. Its purpose is to serve as a way to store dates to be read and written in the W3C date format used in RDF Dublin Core annotations within SBML. The W3C date format is a restricted form of ISO 8601, the international standard for the representation of dates and times. A time and date value in this W3C format takes the form YYYY-MM-DDThh:mm:ssXHH:ZZ (e.g., 1997-07-16T19:20:30+01:00) where XHH:ZZ is the time zone offset. The libSBML Date object contains the following fields to represent these values:

  • year: a long integer representing the year. This should be a four-digit number such as 2011.
  • month: a long integer representing the month, with a range of values of 1–12. The value 1 represents January, and so on.
  • day: a long integer representing the day of the month, with a range of values of 1–31.
  • hour: a long integer representing the hour on a 24-hour clock, with a range of values of 0–23.
  • minute: a long integer representing the minute, with a range of 0–59.
  • second: a long integer representing the second, with a range of 0–59.
  • sign: a long integer representing the sign of the offset (0 signifying + and 1 signifying -). See the paragraph below for further explanations.
  • hours offset: a long integer representing the time zone's hour offset from GMT.
  • minute offset: a long integer representing the time zone's minute offset from GMT.

To illustrate the time zone offset, a value of -05:00 would correspond to USA Eastern Standard Time. In the Date object, this would require a value of 1 for the sign field, 5 for the hour offset and 0 for the minutes offset.

In the restricted RDF annotations used in SBML, described in Section 6 of the SBML Level 2 and Level 3 specification documents, date/time stamps can be used to indicate the time of creation and modification of a model. The following SBML model fragment illustrates this:

<model metaid='_180340' id='GMO' name='Goldbeter1991_MinMitOscil'>
<annotation>
    <rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'
             xmlns:dc='http://purl.org/dc/elements/1.1/'
             xmlns:dcterms='http://purl.org/dc/terms/'
             xmlns:vCard='http://www.w3.org/2001/vcard-rdf/3.0#' >
        <rdf:Description rdf:about='#_180340'>
            <dc:creator>
                <rdf:Bag>
                    <rdf:li rdf:parseType='Resource'>
                        <vCard:N rdf:parseType='Resource'>
                            <vCard:Family>Shapiro</vCard:Family>
                            <vCard:Given>Bruce</vCard:Given>
                        </vCard:N>
                        <vCard:EMAIL>bshapiro@jpl.nasa.gov</vCard:EMAIL>
                        <vCard:ORG rdf:parseType='Resource'>
                            <vCard:Orgname>NASA Jet Propulsion Laboratory</vCard:Orgname>
                        </vCard:ORG>
                    </rdf:li>
                </rdf:Bag>
            </dc:creator>
            <dcterms:created rdf:parseType='Resource'>
                <dcterms:W3CDTF>2005-02-06T23:39:40+00:00</dcterms:W3CDTF>
            </dcterms:created>
            <dcterms:modified rdf:parseType='Resource'>
                <dcterms:W3CDTF>2005-09-13T13:24:56+00:00</dcterms:W3CDTF>
            </dcterms:modified>
        </rdf:Description>
    </rdf:RDF>
</annotation>
</model>

This method has multiple variants; they differ in the arguments they accept.

__init__(long year=2000, long month=1, long day=1, long hour=0, long minute=0, long second=0, long sign=0, long hoursOffset=0, long minutesOffset=0)   Date
__init__(long year=2000, long month=1, long day=1, long hour=0, long minute=0, long second=0, long sign=0, long hoursOffset=0)   Date
__init__(long year=2000, long month=1, long day=1, long hour=0, long minute=0, long second=0, long sign=0)   Date
__init__(long year=2000, long month=1, long day=1, long hour=0, long minute=0, long second=0)   Date
__init__(long year=2000, long month=1, long day=1, long hour=0, long minute=0)   Date
__init__(long year=2000, long month=1, long day=1, long hour=0)   Date
__init__(long year=2000, long month=1, long day=1)   Date
__init__(long year=2000, long month=1)   Date
__init__(long year=2000)   Date
__init__()   Date
__init__(string date)   Date
__init__(Date orig)   Date

Each variant is described separately below.


Method variant with the following signature:
Date(string date)

Creates a Date object from a string expressing a date and time value.

This constructor expects its argument to be in the W3C date format with time zone offset, used in RDF Dublin Core annotations within SBML.

The date format expresses a date and time value as a string of the form YYYY-MM-DDThh:mm:ssXHH:ZZ, where
  • YYYY is a four-digit integer representing the year. This should be a four-digit number such as 2011.
  • MM is a two-digit integer representing the month, with a range of values of 01–12. The value 1 represents January, and so on.
  • DD is a two-digit integer representing the day of the month, with a range of values of 01–31.
  • hh is a two-digit integer representing the hour on a 24-hour clock, with a range of values of 00–23.
  • mm is a two-digit integer representing the minute, with a range of 00–59.
  • ss is a two-digit integer representing the second, with a range of 0–59.
  • X is the the sign of the time zone offset, either + or -.
  • HH is a two-digit integer representing the hour of the time zone offset, with a range of 00–23.
  • ZZ is a two-digit integer representing the minutes of the time zone offset, with a range of 00–59.

In the string format above, it is important not to forget the literal character T in the string. Here is an example date/time string: 1997-07-16T19:20:30+01:00, which would represent July 16, 1997, at 19:20:30 in Central European Time (which is UTC +1:00).

If this constructor is given a None argument or a string of length zero, it constructs a Date object with the value of January 1, 2000, at time 00:00 UTC. Otherwise, the argument must be in the complete format described above, or unpredictable results will happen.

Parameters
datea string representing the date.

Method variant with the following signature:
Date(Date orig)

Copy constructor; creates a copy of this Date.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
Date(long year = 2000, long month = 1, long day = 1, long hour = 0, long minute = 0, long second = 0, long sign = 0, long hoursOffset = 0, long minutesOffset = 0)

Creates a time and date representation for use in model annotations and elsewhere.

The following is the complete set of possible arguments to this constructor, with default values as indicated:

Parameters
yeara long integereger representing the year. This should be a four-digit number such as 2011. (Default value used if this argument is not given: 2000.)
montha long integereger representing the month, with a range of values of 1–12. The value 1 represents January, and so on. (Default value used if this argument is not given: 1.)
daya long integereger representing the day of the month, with a range of values of 1–31. (Default value used if this argument is not given: 1.)
houra long integereger representing the hour on a 24-hour clock, with a range of values of 0–23. (Default value used if this argument is not given: 0.)
minutea long integereger representing the minute, with a range of 0–59. (Default value used if this argument is not given: 0.)
seconda long integereger representing the second, with a range of 0–59. (Default value used if this argument is not given: 0.)
signa long integereger representing the sign of the offset (0 signifying + and 1 signifying -). See the paragraph below for further explanations. (Default value used if this argument is not given: 0.)
hoursOffseta long integereger representing the time zone's hour offset from GMT. (Default value used if this argument is not given: 0.)
minutesOffseta long integereger representing the time zone's minute offset from GMT. (Default value used if this argument is not given: 0.)

To illustrate the time zone offset, a value of -05:00 would correspond to USA Eastern Standard Time. In the Date object, this would require a value of 1 for the sign field, 5 for the hour offset and 0 for the minutes offset.

def libsbml.ModelCreator.__init__ (   self,
  args 
)

MIRIAM-compliant data about a model's creator.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The SBML specification beginning with Level 2 Version 2 defines a standard approach to recording model history and model creator information in a form that complies with MIRIAM ('Minimum Information Requested in the Annotation of biochemical Models', Nature Biotechnology, vol. 23, no. 12, Dec. 2005). For the model creator, this form involves the use of parts of the vCard representation. LibSBML provides the ModelCreator class as a convenience high-level interface for working with model creator data. Objects of class ModelCreator can be used to store and carry around creator data within a program, and the various methods in this object class let callers manipulate the different parts of the model creator representation.

The different parts of a model creator definition

The ModelCreator class mirrors the structure of the MIRIAM model creator annotations in SBML. The following template illustrates these different fields when they are written in XML form:

 <vCard:N rdf:parseType='Resource'>
   <vCard:Family>family name</vCard:Family>
   <vCard:Given>given name</vCard:Given>
 </vCard:N>
 ...
 <vCard:EMAIL>email address</vCard:EMAIL>
 ...
 <vCard:ORG rdf:parseType='Resource'>
   <vCard:Orgname>organization</vCard:Orgname>
 </vCard:ORG>
 

Each of the separate data values family name, given name, email address, and organization can be set and retrieved via corresponding methods in the ModelCreator class. These methods are documented in more detail below.

This method has multiple variants; they differ in the arguments they accept.

__init__()   ModelCreator
__init__(XMLNode creator)   ModelCreator
__init__(ModelCreator orig)   ModelCreator

Each variant is described separately below.


Method variant with the following signature:
ModelCreator(ModelCreator orig)

Copy constructor; creates a copy of the ModelCreator.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
ModelCreator()

Creates a new ModelCreator object.


Method variant with the following signature:
ModelCreator(XMLNode creator)

Creates a new ModelCreator from an XMLNode.

Parameters
creatorthe XMLNode from which to create the ModelCreator.
def libsbml.ModelHistory.__init__ (   self,
  args 
)

MIRIAM-compliant data about a model's history.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The SBML specification beginning with Level 2 Version 2 defines a standard approach to recording optional model history and model creator information in a form that complies with MIRIAM ('Minimum Information Requested in the Annotation of biochemical Models', Nature Biotechnology, vol. 23, no. 12, Dec. 2005). LibSBML provides the ModelHistory class as a convenient high-level interface for working with model history data.

Model histories in SBML consist of one or more model creators, a single date of creation, and one or more modification dates. The overall XML form of this data takes the following form:

 <dc:creator>
   <rdf:Bag>
 <rdf:li rdf:parseType='Resource'>
   +++
   <vCard:N rdf:parseType='Resource'>
     <vCard:Family>family name</vCard:Family>
     <vCard:Given>given name</vCard:Given>
   </vCard:N>
   +++
   <vCard:EMAIL>email address</vCard:EMAIL>
   +++
   <vCard:ORG rdf:parseType='Resource'>
    <vCard:Orgname>organization name</vCard:Orgname>
   </vCard:ORG>
   +++
 </rdf:li>
 ...
   </rdf:Bag>
 </dc:creator>
 <dcterms:created rdf:parseType='Resource'>
   <dcterms:W3CDTF>creation date</dcterms:W3CDTF>
 </dcterms:created>
 <dcterms:modified rdf:parseType='Resource'>
   <dcterms:W3CDTF>modification date</dcterms:W3CDTF>
 </dcterms:modified>
 ...
 

In the template above, the underlined portions are optional, the symbol +++ is a placeholder for either no content or valid XML content that is not defined by the annotation scheme, and the ellipses ... are placeholders for zero or more elements of the same form as the immediately preceding element. The various placeholders for content, namely family name, given name, email address, organization, creation date, and modification date are data that can be filled in using the various methods on the ModelHistory class described below.

See also
ModelCreator
Date

This method has multiple variants; they differ in the arguments they accept.

__init__()   ModelHistory
__init__(ModelHistory orig)   ModelHistory

Each variant is described separately below.


Method variant with the following signature:
ModelHistory(ModelHistory orig)

Copy constructor; creates a copy of this ModelHistory object.

Parameters
origthe object to copy.
Exceptions
ValueErrorThrown if the argument orig is None.

Method variant with the following signature:
ModelHistory()

Creates a new ModelHistory object.

def libsbml.SBMLDocumentPlugin.__init__ (   self,
  args 
)

Base class for extending SBMLDocument in packages.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The SBMLDocumentPlugin class is a specialization of SBasePlugin designed specifically for extending SBMLDocument. All package extensions must extend SBMLDocument to implement support for SBML Level 3 packages; these extensions can be subclasses of this class or from a derived class of this class.

How to extend SBMLDocumentPlugin for a package implementation

The following subsections detail the basic steps necessary to use SBMLDocumentPlugin to extend SBMLDocument for a given package extension.

1. Identify the changes necessary to SBMLDocument

The specification for a SBML Level 3 package will define the changes to the SBML <sbml> element. Packages typically do not make any changes beyond adding an attribute named 'required' (discussed below), so in most cases, the extension of SBMLDocument is very simple. However, some packages do more. For instance, the Hierarchical Model Composition package adds subobjects for lists of model definitions. SBMLDocumentPlugin supports all these cases.

2. Create the SBMLDocumentPlugin subclass

A package extension will only define one subclass of SBMLDocumentPlugin. Below, we describe in detail the different parts of a subclass definition.

2.1 Override SBasePlugin class-related methods

The derived class must override the constructor, copy constructor, assignment operator (operator=) and clone() methods from SBasePlugin.

2.2 Determine the necessary value of the 'required' attribute

At minimum, it is necessary for a package implementation to add the 'required' attribute to the SBML <sbml> element mandated by SBML for all Level 3 packages, and this is done using this class as a base. If the 'required' attribute is the only addition necessary for a particular SBML Level 3 package, then the subclass of SBMLDocumentPlugin for the package can have a very simple implementation. Some Level 3 packages add additional attributes or elements to <sbml>, and their implementations would go into the subclassed SBMLDocumentPlugin.

SBMLDocumentPlugin provides methods with default implementations that support managing the 'required' attribute, so package extension code does not need to provide implementations—they only need to set the correct value for the SBML Level 3 package based on its specification. The following are the virtual methods for working with the 'required' attribute. Package extensions would only need to override them in special circumstances:

  • setRequired(bool value): This method sets the value of the flag.
  • getRequired(): This method gets the value of the 'required' flag.

2.3 Define protected data members

An extended SBMLDocument object may need more than just the 'required' attribute, depending on what is defined in the specification for the package being implemented. Data attributes on the extended <sbml> object in an SBML package will have one of the data types string, double, int, or bool. Subelements/subobjects will normally be derived from the ListOf class or from SBase.

The additional data members must be properly initialized in the class constructor, and must be properly copied in the copy constructor and assignment operator.

2.4 Override virtual methods for attributes

If the extended component is defined by the SBML Level 3 package to have attributes, then the extended SBMLDocumentPlugin class definition needs to override the following internal methods that come from SBasePlugin (the base class of SBMLDocumentPlugin) and provide appropriate implementations:

  • addExpectedAttributes(ExpectedAttributes& attributes): This method should add the attributes that are expected to be found on this kind of extended component in an SBML file or data stream.
  • readAttributes(XMLAttributes attributes, ExpectedAttributes& expectedAttributes): This method should read the attributes expected to be found on this kind of extended component in an SBML file or data stream.
  • hasRequiredAttributes(): This method should return True if all of the required attribute for this extended component are present on instance of the object.
  • writeAttributes(XMLOutputStream stream): This method should write out the attributes of an extended component. The implementation should use the different kinds of writeAttribute methods defined by XMLOutputStream to achieve this.

2.5 Override virtual methods for subcomponents

If the extended component is defined by the Level 3 package to have subcomponents (i.e., full XML elements rather than mere attributes), then the extended class definition needs to override the following internal methods on SBasePlugin (the base class of SBMLDocumentPlugin) and provide appropriate implementations:

  • createObject(XMLInputStream stream): Subclasses must override this method to create, store, and then return an SBML object corresponding to the next XMLToken in the XMLInputStream. To do this, implementations can use methods like peek() on XMLInputStream to test if the next object in the stream is something expected for the package. For example, LayoutModelPlugin uses peek() to examine the next element in the input stream, then tests that element against the Layout namespace and the element name 'listOfLayouts' to see if it's the single subcomponent (ListOfLayouts) permitted on a Model object using the Layout package. If it is, it returns the appropriate object.
  • connectToParent(SBase sbase): This creates a parent-child relationship between a given extended component and its subcomponent(s).
  • setSBMLDocument(SBMLDocument d): This method should set the parent SBMLDocument object on the subcomponent object instances, so that the subcomponent instances know which SBMLDocument contains them.
  • enablePackageInternal(string& pkgURI, string& pkgPrefix, bool flag): This method should enable or disable the subcomponent based on whether a given XML namespace is active.
  • writeElements(XMLOutputStream stream): This method must be overridden to provide an implementation that will write out the expected subcomponents/subelements to the XML output stream.
  • readOtherXML(SBase parentObject, XMLInputStream stream): This function should be overridden if elements of annotation, notes, MathML content, etc., need to be directly parsed from the given XMLInputStream object.
  • hasRequiredElements(): This method should return True if a given object contains all the required subcomponents defined by the specification for that SBML Level 3 package.

2.6 Override virtual methods for XML namespaces

If the package needs to add additional xmlns attributes to declare additional XML namespace URIs, the extended class should override the following method coming from SBasePlugin (the parent class of SBMLDocumentPlugin):

  • writeXMLNS(XMLOutputStream stream): This method should write out any additional XML namespaces that might be needed by a package implementation.

2.7 Implement additional methods as needed

Extended SBMLDocumentPlugin implementations can add whatever additional utility methods are useful for their implementation.

This method has multiple variants; they differ in the arguments they accept.

__init__(string uri, string prefix, SBMLNamespaces sbmlns)   SBMLDocumentPlugin
__init__(SBMLDocumentPlugin orig)   SBMLDocumentPlugin

Each variant is described separately below.


Method variant with the following signature:
SBMLDocumentPlugin(stringuri, stringprefix, SBMLNamespaces sbmlns)

Creates a new SBMLDocumentPlugin object using the given parameters.

In the XML representation of an SBML document, XML namespaces are used to identify the origin of each XML construct used. XML namespaces are identified by their unique resource identifiers (URIs). The core SBML specifications stipulate the namespaces that must be used for core SBML constructs; for example, all XML elements that belong to SBML Level 3 Version 1 Core must be placed in the XML namespace identified by the URI 'http://www.sbml.org/sbml/level3/version1/core'. Individual SBML Level 3 packages define their own XML namespaces; for example, all elements belonging to the SBML Level 3 Layout Version 1 package must be placed in the XML namespace 'http://www.sbml.org/sbml/level3/version1/layout/version1/'.
The SBMLNamespaces object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces facilities is to create an SBMLNamespaces object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces as arguments.
Parameters
urithe URI of the SBML Level 3 package implemented by this libSBML package extension.
prefixthe XML namespace prefix being used for the package.
sbmlnsthe SBMLNamespaces object for the package.

Method variant with the following signature:
SBMLDocumentPlugin(SBMLDocumentPlugin orig)

Copy constructor.

This creates a copy of this object.

Parameters
origthe SBMLDocumentPlugin instance to copy.
def libsbml.SBMLExtensionException.__init__ (   self,
  errmsg 
)

Exception used by package extensions

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

Certain situations can result in an exception being thrown by libSBML package extensions. A prominent example involves the constructor for SBMLNamespaces (and its subclasses), which will throw SBMLExtensionException if the arguments it is given refer to an unknown SBML Level 3 package. The situation can arise for legitimate SBML files if the necessary package extension has not been registered with a given copy of libSBML.
See also
SBMLNamespaces

Creates a new SBMLExtensionException object with a given message.

__init__(string errmsg)   SBMLExtensionException
Parameters
errmsga string, the text of the error message to store with this exception
def libsbml.ASTNode.__init__ (   self,
  args 
)

Abstract Syntax Trees for mathematical expressions.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

Abstract Syntax Trees (ASTs) are a simple kind of data structure used in libSBML for storing mathematical expressions. LibSBML ASTs provide a canonical, in-memory representation for all mathematical formulas regardless of their original format (which might be MathML or might be text strings).

An AST node in libSBML is a recursive tree structure; each node has a type, a pointer to a value, and a list of children nodes. Each ASTNode node may have none, one, two, or more children depending on its type. There are node types to represent numbers (with subtypes to distinguish integer, real, and rational numbers), names (e.g., constants or variables), simple mathematical operators, logical or relational operators and functions. The following diagram illustrates an example of how the mathematical expression '1 + 2' is represented as an AST with one plus node having two integer children nodes for the numbers 1 and 2. The figure also shows the corresponding MathML representation:
Example AST representation of a mathematical expression.
Infix AST MathML
1 + 2 <math xmlns="http://www.w3.org/1998/Math/MathML">
  <apply>
    <plus/>
    <cn type="integer"> 1 </cn>
    <cn type="integer"> 2 </cn>
  </apply>
</math>

The following are other noteworthy points about the AST representation in libSBML:

  • A numerical value represented in MathML as a real number with an exponent is preserved as such in the AST node representation, even if the number could be stored in a float data type. This is done so that when an SBML model is read in and then written out again, the amount of change introduced by libSBML to the SBML during the round-trip activity is minimized.
  • The children of an ASTNode are other ASTNode objects. The list of children is empty for nodes that are leaf elements, such as numbers. For nodes that are actually roots of expression subtrees, the list of children points to the parsed objects that make up the rest of the expression.

For many applications, the details of ASTs are irrelevant because libSBML provides text-string based translation functions such as formulaToL3String() and parseL3Formula(). If you find the complexity of using the AST representation of expressions too high for your purposes, perhaps the string-based functions will be more suitable.

The set of possible ASTNode types

Every ASTNode has an associated type code to indicate whether, for example, it holds a number or stands for an arithmetic operator.

The type is recorded as a value drawn from a set of static integer constants defined in the class libsbml. Their names begin with the characters AST_.The list of possible types is quite long, because it covers all the mathematical functions that are permitted in SBML. The values are shown in the following table:

AST_CONSTANT_E AST_FUNCTION_COT AST_LOGICAL_NOT
AST_CONSTANT_FALSE AST_FUNCTION_COTH AST_LOGICAL_OR
AST_CONSTANT_PI AST_FUNCTION_CSC AST_LOGICAL_XOR
AST_CONSTANT_TRUE AST_FUNCTION_CSCH AST_MINUS
AST_DIVIDE AST_FUNCTION_DELAY AST_NAME
AST_FUNCTION AST_FUNCTION_EXP AST_NAME_AVOGADRO (Level 3 only)
AST_FUNCTION_ABS AST_FUNCTION_FACTORIAL AST_NAME_TIME
AST_FUNCTION_ARCCOS AST_FUNCTION_FLOOR AST_PLUS
AST_FUNCTION_ARCCOSH AST_FUNCTION_LN AST_POWER
AST_FUNCTION_ARCCOT AST_FUNCTION_LOG AST_RATIONAL
AST_FUNCTION_ARCCOTH AST_FUNCTION_PIECEWISE AST_REAL
AST_FUNCTION_ARCCSC AST_FUNCTION_POWER AST_REAL_E
AST_FUNCTION_ARCCSCH AST_FUNCTION_ROOT AST_RELATIONAL_EQ
AST_FUNCTION_ARCSEC AST_FUNCTION_SEC AST_RELATIONAL_GEQ
AST_FUNCTION_ARCSECH AST_FUNCTION_SECH AST_RELATIONAL_GT
AST_FUNCTION_ARCSIN AST_FUNCTION_SIN AST_RELATIONAL_LEQ
AST_FUNCTION_ARCSINH AST_FUNCTION_SINH AST_RELATIONAL_LT
AST_FUNCTION_ARCTAN AST_FUNCTION_TAN AST_RELATIONAL_NEQ
AST_FUNCTION_ARCTANH AST_FUNCTION_TANH AST_TIMES
AST_FUNCTION_CEILING AST_INTEGER AST_UNKNOWN
AST_FUNCTION_COS AST_LAMBDA
AST_FUNCTION_COSH AST_LOGICAL_AND

The types have the following meanings:

  • If the node is a predefined function or operator from SBML Level 1 (in the string-based formula syntax used in Level 1) or SBML Level 2 and 3 (in the subset of MathML used in SBML Levels 2 and 3), then the node's type will be either AST_FUNCTION_X, AST_LOGICAL_X, or AST_RELATIONAL_X, as appropriate. (Examples: AST_FUNCTION_LOG, AST_RELATIONAL_LEQ.)
  • If the node refers to a user-defined function, the node's type will be AST_FUNCTION (because it holds the name of the function).
  • If the node is a lambda expression, its type will be AST_LAMBDA.
  • (Levels 2 and 3 only) If the node is the special MathML csymbol time, the value of the node will be AST_NAME_TIME. (Note, however, that the MathML csymbol delay is translated into a node of type AST_FUNCTION_DELAY. The difference is due to the fact that time is a single variable, whereas delay is actually a function taking arguments.)
  • (Level 3 only) If the node is the special MathML csymbol avogadro, the value of the node will be AST_NAME_AVOGADRO.

Converting between ASTs and text strings

The text-string form of mathematical formulas produced by formulaToString() and formulaToL3String(), and read by parseFormula() and parseL3Formula(), are in a simple C-inspired infix notation. A formula in one of these two text-string formats can be handed to a program that understands SBML mathematical expressions, or used as part of a translation system. The libSBML distribution comes with example programs in the 'examples' subdirectory that demonstrate such things as translating infix formulas into MathML and vice-versa.

Please see the documentation for the functions parseFormula() and parseL3Formula() for detailed explanations of the infix syntax they accept.

Historical notes

Readers may wonder why this part of libSBML uses a seemingly less object-oriented design than other parts. Originally, much of libSBML was written in C. All subsequent development was done in C++, but the complexity of some of the functionality for converting between infix, AST and MathML, coupled with the desire to maintain stability and backward compatibility, means that some of the underlying code is still written in C. This has lead to the exposed API being more C-like.

See also
parseL3Formula()
parseL3FormulaWithSettings()
parseL3FormulaWithModel()
parseFormula()
formulaToL3StringWithSettings()
formulaToL3String()
formulaToString()
getDefaultL3ParserSettings()

This method has multiple variants; they differ in the arguments they accept.

__init__(int type=AST_UNKNOWN)   ASTNode
__init__()   ASTNode
__init__(SBMLNamespaces sbmlns, int type=AST_UNKNOWN)   ASTNode
__init__(SBMLNamespaces sbmlns)   ASTNode
__init__(ASTNode orig)   ASTNode

Each variant is described separately below.


Method variant with the following signature:
ASTNode(Token_t *token)

Creates a new ASTNode from the given Token.

The resulting ASTNode will contain the same data as the given token.

Parameters
tokenthe token to use as a starting point for creating the ASTNode object.

Method variant with the following signature:
ASTNode(long type)

Creates a new ASTNode.

Unless the argument type is given, the returned node will by default have a type of AST_UNKNOWN. If the type isn't supplied when caling this constructor, the caller should set the node type to something else as soon as possible using ASTNode.setType().

Parameters
typean optional integer type code indicating the type of node to create.

Method variant with the following signature:
ASTNode(ASTNode orig)

Copy constructor; creates a deep copy of the given ASTNode.

Parameters
origthe ASTNode to be copied.
def libsbml.L3ParserSettings.__init__ (   self,
  args 
)

Controls the behavior of the Level 3 formula parser.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The function parseL3FormulaWithSettings(), along with its variants parseL3Formula() and parseL3FormulaWithModel(), are the interfaces to a parser for mathematical formulas written as text strings. The inverse function is formulaToL3String() and its variants such as formulaToL3StringWithSettings(). The parsers and the formula writers convert between a text-string representation of mathematical formulas and Abstract Syntax Trees (ASTs), represented in libSBML using ASTNode objects. Compared to the parser and writer implemented by the functions parseFormula() and formulaToString(), which were designed primarily for converting the mathematical formula strings in SBML Level 1, the SBML Level 3 or 'L3' variants of the parser and writer use an extended formula syntax. They also have a number of configurable behaviors. This class (L3ParserSettings) is an object used to communicate the configuration settings with callers.

The following aspects of the parser are configurable using L3ParserSettings objects. (For the formula writer, only a subset of these settings is relevant; please see the documentation for formulaToL3StringWithSettings() for more information about which ones).

  • A Model object may optionally be provided to use identifiers (values of type SId) from the model in preference to pre-defined MathML symbols More precisely, the Model entities whose identifiers will shadow identical symbols in the mathematical formula are: Species, Compartment, Parameter, Reaction, and SpeciesReference. For instance, if the parser is given a Model containing a Species with the identifier "pi", and the formula to be parsed is "3*pi", the MathML produced by the parser will contain the construct <ci> pi </ci> instead of the construct <pi/>. Another example, if the passed-in Model contains a FunctionDefinition with the identifier "sin", that function will be used instead of the predefined MathML function <sin/>.
  • The function log with a single argument ("log(x)") can be parsed as log10(x), ln(x), or treated as an error, as desired.
  • Unary minus signs can be either collapsed or preserved; that is, the parser can either (1) remove sequential pairs of unary minuses (e.g., "- -3") from the input and incorporate single unary minuses into the number node, or (2) preserve all minuses in the AST node structure, turning them into ASTNode objects of type AST_MINUS.
  • The character sequence "number id" can be interpreted as a numerical value number followed by units of measurement indicated by id, or it can be treated as a syntax error. (In Level 3, MathML <cn> elements can have an attribute named units placed in the SBML namespace, which can be used to indicate the units to be associated with the number. The text-string infix formula parser allows units to be placed after raw numbers; they are interpreted as unit identifiers for units defined by the SBML specification or in the containing Model object.)
  • The symbol avogadro can be parsed either as a MathML csymbol or as a identifier. More specifically, "avogadro" can be treated as an ASTNode of type AST_NAME_AVOGADRO or of type AST_NAME.
  • Strings that match built-in functions and constants can either be parsed as a match regardless of capitalization, or may be required to be all-lower-case to be considered a match.
  • LibSBML plug-ins implementing support for SBML Level 3 packages may introduce extensions to the syntax understood by the parser. The precise nature of the extensions will be documented by the individual package plug-ins. An example of a possible extension is a notation for vectors and arrays, introduced by the SBML Level 3 Arrays package.

To obtain the default configuration values, callers can use the function getDefaultL3ParserSettings(). To change the configuration, callers can create an L3ParserSettings object, set the desired characteristics using the methods provided, and pass that object to parseL3FormulaWithSettings().

See also
parseL3Formula()
parseL3FormulaWithSettings()
parseL3FormulaWithModel()
parseFormula()
formulaToL3StringWithSettings()
formulaToL3String()
formulaToString()
getDefaultL3ParserSettings()

This method has multiple variants; they differ in the arguments they accept.

__init__()   L3ParserSettings
__init__(Model model, long parselog, bool collapseminus, bool parseunits, bool avocsymbol, bool caseSensitive=False, SBMLNamespaces sbmlns=None)   L3ParserSettings
__init__(Model model, long parselog, bool collapseminus, bool parseunits, bool avocsymbol, bool caseSensitive=False)   L3ParserSettings
__init__(Model model, long parselog, bool collapseminus, bool parseunits, bool avocsymbol)   L3ParserSettings
__init__(L3ParserSettings source)   L3ParserSettings

Each variant is described separately below.


Method variant with the following signature:
L3ParserSettings()

Creates a new L3ParserSettings object with default values.

This is the default constructor for the L3ParserSettings object. It sets the stored Model object to None and sets the following field values in the L3ParserSettings object:

  • sbmlns ('SBML namespaces') is set to None (which indicates that no syntax extensions due to SBML Level 3 packages will be assumed—the formula parser will only understand the core syntax described in the documentation for parseL3Formula()).

Method variant with the following signature:
L3ParserSettings(L3ParserSettings source)

Copy constructor.


Method variant with the following signature:
L3ParserSettings(Model model, long parselog, bool collapseminus, bool parseunits, bool avocsymbol, bool caseSensitive = false, SBMLNamespaces sbmlns = None)

Creates a new L3ParserSettings object with specific values for all possible settings.

Parameters
modela Model object to be used for disambiguating identifiers encountered by parseL3FormulaWithSettings() in mathematical formulas.
parselog('parse log') a flag that controls how the parser will handle the symbol log in mathematical formulas. The function log with a single argument ("log(x)") can be parsed as log10(x), ln(x), or treated as an error, as desired, by using the parameter values L3P_PARSE_LOG_AS_LOG10, L3P_PARSE_LOG_AS_LN, or L3P_PARSE_LOG_AS_ERROR, respectively.
collapseminus('collapse minus') a flag that controls how the parser will handle minus signs in formulas. Unary minus signs can be collapsed or preserved; that is, sequential pairs of unary minuses (e.g., "- -3") can be removed from the input entirely and single unary minuses can be incorporated into the number node, or all minuses can be preserved in the AST node structure. The possible values of this field are L3P_COLLAPSE_UNARY_MINUS (to collapse unary minuses) and L3P_EXPAND_UNARY_MINUS (to expand unary minuses).
parseunits('parse units') a flag that controls how the parser will handle apparent references to units of measurement associated with raw numbers in a formula. If set to the value L3P_PARSE_UNITS, units are parsed; if set to the value L3P_NO_UNITS, units are not parsed.
avocsymbol('Avogadro csymbol') a flag that controls how the parser will handle the appearance of the symbol avogadro in a formula. If set to the value L3P_AVOGADRO_IS_CSYMBOL, the symbol is interpreted as the SBML/MathML csymbol avogadro; if set to the value L3P_AVOGADRO_IS_NAME, the symbol is interpreted as a plain symbol name.
caseSensitive('case sensitive') a flag that controls how the cases of alphabetical characters are treated when symbols are compared. If the flag is set to the value L3P_COMPARE_BUILTINS_CASE_INSENSITIVE, symbols are compared in a case-insensitive manner, which means that mathematical functions such as 'sin' will be matched no matter what their case is: 'Sin', 'SIN', etc. If the flag is set to the value L3P_COMPARE_BUILTINS_CASE_SENSITIVE, symbols are interpreted in a case-sensitive manner.
sbmlns('SBML namespaces') an SBML namespaces object. The namespaces identify the SBML Level 3 packages that can extend the syntax understood by the formula parser. When non-None, the parser will interpret additional syntax defined by the packages; for example, it may understand vector/array extensions introduced by the SBML Level 3 Arrays package.
See also
getModel()
setModel()
unsetModel()
getParseLog()
setParseLog()
getParseUnits()
setParseUnits()
getParseCollapseMinus()
setParseCollapseMinus()
getParseAvogadroCsymbol()
setParseAvogadroCsymbol()
def libsbml.RenderPkgNamespaces.__init__ (   self,
  args 
)

Set of SBML Level + Version + namespace triples.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

SBMLExtensionNamespaces is a template class. It is extended from SBMLNamespaces and is meant to be used by package extensions to store the SBML Level, Version within a Level, and package version of the SBML Level 3 package implemented by a libSBML package extension.

How to use SBMLExtensionNamespaces for a package implementation

Each package extension in libSBML needs to extend and instantiate the template class SBMLExtensionNamespaces, as well as declare a specific typedef. The following sections explain these steps in detail.

1. Define the typedef

Each package needs to declare a package-specific version of the SBMLExtensionNamespaces class using a typedef. The following example code demonstrates how this is done in the case of the Layout package:

typedef SBMLExtensionNamespaces<LayoutExtension> LayoutPkgNamespaces;

This creates a new type called LayoutPkgNamespaces. The code above is usually placed in the same file that contains the SBMLExtension-derived definition of the package extension base class. In the case of the Layout package, this is in the file src/packages/layout/extension/LayoutExtension.h in the libSBML source distribution.

2. Instantiate a template instance

Each package needs to instantiate a template instance of the SBMLExtensionNamespaces class. The following example code demonstrates how this is done in the case of the Layout package:

template class LIBSBML_EXTERN SBMLExtensionNamespaces<LayoutExtension>;

In the case of the Layout package, the code above is located in the file src/packages/layout/extension/LayoutExtension.cpp in the libSBML source distribution.

3. Create constructors that accept the class

Each SBase-derived class in the package extension should implement a constructor that accepts the SBMLExtensionNamespaces-derived class as an argument. For example, in the Layout package, the class BoundBox has a constructor declared as follows

BoundingBox(LayoutPkgNamespaces layoutns);

The implementation of this constructor must, among other things, take the argument namespace object and use it to set the XML namespace URI for the object. Again, for the BoundingBox example:

BoundingBox.BoundingBox()
: SBase(layoutns)
,mPosition(layoutns)
,mDimensions(layoutns)
,mPositionExplicitlySet (false)
,mDimensionsExplicitlySet (false)
{
// Standard extension actions.
setElementNamespace(layoutns->getURI());
connectToChild();
// Package-specific actions.
mPosition.setElementName('position');
// Load package extensions bound with this object (if any).
loadPlugins(layoutns);
}
__init__(SBMLExtensionNamespaces<(RenderExtension)> self, long level, long version, long pkgVersion, string prefix)   RenderPkgNamespaces
__init__(SBMLExtensionNamespaces<(RenderExtension)> self, long level, long version, long pkgVersion)   RenderPkgNamespaces
__init__(SBMLExtensionNamespaces<(RenderExtension)> self, long level, long version)   RenderPkgNamespaces
__init__(SBMLExtensionNamespaces<(RenderExtension)> self, long level)   RenderPkgNamespaces
__init__(SBMLExtensionNamespaces<(RenderExtension)> self)   RenderPkgNamespaces
__init__(SBMLExtensionNamespaces<(RenderExtension)> self, RenderPkgNamespaces orig)   RenderPkgNamespaces
Set of SBML Level + Version + namespace triples.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

SBMLExtensionNamespaces is a template class. It is extended from SBMLNamespaces and is meant to be used by package extensions to store the SBML Level, Version within a Level, and package version of the SBML Level 3 package implemented by a libSBML package extension.

How to use SBMLExtensionNamespaces for a package implementation

Each package extension in libSBML needs to extend and instantiate the template class SBMLExtensionNamespaces, as well as declare a specific typedef. The following sections explain these steps in detail.

1. Define the typedef

Each package needs to declare a package-specific version of the SBMLExtensionNamespaces class using a typedef. The following example code demonstrates how this is done in the case of the Layout package:

typedef SBMLExtensionNamespaces<LayoutExtension> LayoutPkgNamespaces;

This creates a new type called LayoutPkgNamespaces. The code above is usually placed in the same file that contains the SBMLExtension-derived definition of the package extension base class. In the case of the Layout package, this is in the file src/packages/layout/extension/LayoutExtension.h in the libSBML source distribution.

2. Instantiate a template instance

Each package needs to instantiate a template instance of the SBMLExtensionNamespaces class. The following example code demonstrates how this is done in the case of the Layout package:

template class LIBSBML_EXTERN SBMLExtensionNamespaces<LayoutExtension>;

In the case of the Layout package, the code above is located in the file src/packages/layout/extension/LayoutExtension.cpp in the libSBML source distribution.

3. Create constructors that accept the class

Each SBase-derived class in the package extension should implement a constructor that accepts the SBMLExtensionNamespaces-derived class as an argument. For example, in the Layout package, the class BoundBox has a constructor declared as follows

BoundingBox(LayoutPkgNamespaces layoutns);

The implementation of this constructor must, among other things, take the argument namespace object and use it to set the XML namespace URI for the object. Again, for the BoundingBox example:

BoundingBox.BoundingBox()
: SBase(layoutns)
,mPosition(layoutns)
,mDimensions(layoutns)
,mPositionExplicitlySet (false)
,mDimensionsExplicitlySet (false)
{
// Standard extension actions.
setElementNamespace(layoutns->getURI());
connectToChild();
// Package-specific actions.
mPosition.setElementName('position');
// Load package extensions bound with this object (if any).
loadPlugins(layoutns);
}
def libsbml.SBase.clone (   self)

SBML's SBase class, base class of most SBML objects.

Most components in SBML are derived from a single abstract base type, SBase. In addition to serving as the parent class for most other classes of objects in SBML, this base type is designed to allow a modeler or a software package to attach arbitrary information to each major element or list in an SBML model.

SBase has an optional subelement called 'notes'. It is intended to serve as a place for storing optional information intended to be seen by humans. An example use of the 'notes' element would be to contain formatted user comments about the model element in which the 'notes' element is enclosed. There are certain conditions on the XHTML content permitted inside the 'notes' element; please consult the SBML specification document corresponding to the SBML Level and Version of your model for more information about the requirements for 'notes' content.

SBase has another optional subelement called 'annotation'. Whereas the 'notes' element described above is a container for content to be shown directly to humans, the 'annotation' element is a container for optional software-generated content not meant to be shown to humans. The element's content type is XML type 'any', allowing essentially arbitrary data content. SBML places only a few restrictions on the organization of the content; these are intended to help software tools read and write the data as well as help reduce conflicts between annotations added by different tools. As is the case with 'notes', it is important to refer to the SBML specification document corresponding to the SBML Level and Version of your model for more information about the requirements for 'annotation' content.

It is worth pointing out that the 'annotation' element in the definition of SBase exists in order that software developers may attach optional application-specific data to the elements in an SBML model. However, it is important that this facility not be misused. In particular, it is critical that data essential to a model definition or that can be encoded in existing SBML elements is not stored in 'annotation'. Parameter values, functional dependencies between model elements, etc., should not be recorded as annotations. It is crucial to keep in mind the fact that data placed in annotations can be freely ignored by software applications. If such data affects the interpretation of a model, then software interoperability is greatly impeded.

SBML Level 2 introduced an optional SBase attribute named 'metaid' for supporting metadata annotations using RDF (Resource Description Format). The attribute value has the data type XML ID, the XML identifier type, which means each 'metaid' value must be globally unique within an SBML file. (Importantly, this uniqueness criterion applies across any attribute with type XML ID, not just the 'metaid' attribute used by SBML—something to be aware of if your application-specific XML content inside the 'annotation' subelement happens to use XML ID.) The 'metaid' value serves to identify a model component for purposes such as referencing that component from metadata placed within 'annotation' subelements.

Beginning with SBML Level 2 Version 3, SBase also has an optional attribute named 'sboTerm' for supporting the use of the Systems Biology Ontology. In SBML proper, the data type of the attribute is a string of the form 'SBO:NNNNNNN', where 'NNNNNNN' is a seven digit integer number; libSBML simplifies the representation by only storing the 'NNNNNNN' integer portion. Thus, in libSBML, the 'sboTerm' attribute on SBase has data type int, and SBO identifiers are stored simply as integers. (For convenience, SBase offers methods for returning both the integer form and a text-string form of the SBO identifier.) SBO terms are a type of optional annotation, and each different class of SBML object derived from SBase imposes its own requirements about the values permitted for 'sboTerm'. Please consult the SBML Level 2 Version 4 specification for more information about the use of SBO and the 'sboTerm' attribute.

Finally, note that, in the list of methods on SBase, there is no public constructor because SBase is an abstract class. The constructors reside in the subclasses derived from SBase.

Standard format for annotations linking data resources

SBML Level 2 Versions 2, 3 and 4, and Level 3, define a proposed regular format for encoding two particular categories of annotations: (a) references to controlled vocabulary terms and database identifiers which define and describe biological and biochemical entities in a model; and (b) descriptions of the provenance of a model, including its author(s) and modification history.

Creates and returns a deep copy of this SBase object.

clone()   SBase
Returns
the (deep) copy of this SBase object.
def libsbml.Rule.clone (   self)

Parent class for SBML rules in libSBML.

In SBML, rules provide additional ways to define the values of variables in a model, their relationships, and the dynamical behaviors of those variables. They enable encoding relationships that cannot be expressed using Reaction nor InitialAssignment objects alone.

The libSBML implementation of rules mirrors the SBML Level 3 Version 1 Core definition (which is in turn is very similar to the Level 2 Version 4 definition), with Rule being the parent class of three subclasses as explained below. The Rule class itself cannot be instantiated by user programs and has no constructor; only the subclasses AssignmentRule, AlgebraicRule and RateRule can be instantiated directly.

General summary of SBML rules

In SBML Level 3 as well as Level 2, rules are separated into three subclasses for the benefit of model analysis software. The three subclasses are based on the following three different possible functional forms (where x is a variable, f is some arbitrary function returning a numerical result, V is a vector of variables that does not include x, and W is a vector of variables that may include x):

Algebraic:left-hand side is zero0 = f(W)
Assignment:left-hand side is a scalar:x = f(V)
Rate:left-hand side is a rate-of-change:dx/dt = f(W)

In their general form given above, there is little to distinguish between assignment and algebraic rules. They are treated as separate cases for the following reasons:

  • Assignment rules can simply be evaluated to calculate intermediate values for use in numerical methods. They are statements of equality that hold at all times. (For assignments that are only performed once, see InitialAssignment.)
  • SBML needs to place restrictions on assignment rules, for example the restriction that assignment rules cannot contain algebraic loops.
  • Some simulators do not contain numerical solvers capable of solving unconstrained algebraic equations, and providing more direct forms such as assignment rules may enable those simulators to process models they could not process if the same assignments were put in the form of general algebraic equations;
  • Those simulators that can solve these algebraic equations make a distinction between the different categories listed above; and
  • Some specialized numerical analyses of models may only be applicable to models that do not contain algebraic rules.

The approach taken to covering these cases in SBML is to define an abstract Rule structure containing a subelement, 'math', to hold the right-hand side expression, then to derive subtypes of Rule that add attributes to distinguish the cases of algebraic, assignment and rate rules. The 'math' subelement must contain a MathML expression defining the mathematical formula of the rule. This MathML formula must return a numerical value. The formula can be an arbitrary expression referencing the variables and other entities in an SBML model.

Each of the three subclasses of Rule (AssignmentRule, AlgebraicRule, RateRule) inherit the the 'math' subelement and other fields from SBase. The AssignmentRule and RateRule classes add an additional attribute, 'variable'. See the definitions of AssignmentRule, AlgebraicRule and RateRule for details about the structure and interpretation of each one.

Additional restrictions on SBML rules

An important design goal of SBML rule semantics is to ensure that a model's simulation and analysis results will not be dependent on when or how often rules are evaluated. To achieve this, SBML needs to place two restrictions on rule use. The first concerns algebraic loops in the system of assignments in a model, and the second concerns overdetermined systems.

A model must not contain algebraic loops

The combined set of InitialAssignment, AssignmentRule and KineticLaw objects in a model constitute a set of assignment statements that should be considered as a whole. (A KineticLaw object is counted as an assignment because it assigns a value to the symbol contained in the 'id' attribute of the Reaction object in which it is defined.) This combined set of assignment statements must not contain algebraic loops—dependency chains between these statements must terminate. To put this more formally, consider a directed graph in which nodes are assignment statements and directed arcs exist for each occurrence of an SBML species, compartment or parameter symbol in an assignment statement's 'math' subelement. Let the directed arcs point from the statement assigning the symbol to the statements that contain the symbol in their 'math' subelement expressions. This graph must be acyclic.

SBML does not specify when or how often rules should be evaluated. Eliminating algebraic loops ensures that assignment statements can be evaluated any number of times without the result of those evaluations changing. As an example, consider the set of equations x = x + 1, y = z + 200 and z = y + 100. If this set of equations were interpreted as a set of assignment statements, it would be invalid because the rule for x refers to x (exhibiting one type of loop), and the rule for y refers to z while the rule for z refers back to y (exhibiting another type of loop). Conversely, the following set of equations would constitute a valid set of assignment statements: x = 10, y = z + 200, and z = x + 100.

A model must not be overdetermined

An SBML model must not be overdetermined; that is, a model must not define more equations than there are unknowns in a model. An SBML model that does not contain AlgebraicRule structures cannot be overdetermined.

LibSBML implements the static analysis procedure described in Appendix B of the SBML Level 3 Version 1 Core specification for assessing whether a model is overdetermined.

(In summary, assessing whether a given continuous, deterministic, mathematical model is overdetermined does not require dynamic analysis; it can be done by analyzing the system of equations created from the model. One approach is to construct a bipartite graph in which one set of vertices represents the variables and the other the set of vertices represents the equations. Place edges between vertices such that variables in the system are linked to the equations that determine them. For algebraic equations, there will be edges between the equation and each variable occurring in the equation. For ordinary differential equations (such as those defined by rate rules or implied by the reaction rate definitions), there will be a single edge between the equation and the variable determined by that differential equation. A mathematical model is overdetermined if the maximal matchings of the bipartite graph contain disconnected vertexes representing equations. If one maximal matching has this property, then all the maximal matchings will have this property; i.e., it is only necessary to find one maximal matching.)

Rule types for SBML Level 1

SBML Level 1 uses a different scheme than SBML Level 2 and Level 3 for distinguishing rules; specifically, it uses an attribute whose value is drawn from an enumeration of 3 values. LibSBML supports this using methods that work with the enumeration values listed below.

Creates and returns a deep copy of this Rule object.

clone()   Rule
Returns
the (deep) copy of this Rule object.
def libsbml.RDFAnnotationParser.createAnnotation ( )

MIRIAM-compliant RDF annotation reader/writer.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

RDFAnnotationParser is a libSBML construct used as part of the libSBML support for annotations conforming to the guidelines specified by MIRIAM ('Minimum Information Requested in the Annotation of biochemical Models', Nature Biotechnology, vol. 23, no. 12, Dec. 2005). Section 6 of the SBML Level 2 and Level 3 specification documents defines a recommended way of encoding MIRIAM information using a subset of RDF (Resource Description Format). The general scheme is as follows. A set of RDF-based annotations attached to a given SBML <annotation> element are read by RDFAnnotationParser and converted into a list of CVTerm objects. There are different versions of the main method, and RDFAnnotationParser.parseRDFAnnotation(), used depending on whether the annotation in question concerns the MIRIAM model history or other MIRIAM resource annotations. A special object class, ModelHistory, is used to make it easier to manipulate model history annotations.

All of the methods on RDFAnnotationParser are static; the class exists only to encapsulate the annotation and CVTerm parsing and manipulation functionality.

Creates a blank annotation and returns its root XMLNode object.

createAnnotation()   XMLNode

This creates a completely empty SBML <annotation> element. It is not attached to any SBML element. An example of how this might be used is illustrated in the following code fragment. In this example, suppose that content is an XMLNode object previously created, containing MIRIAM-style annotations, and that sbmlObject is an SBML object derived from SBase (e.g., a Model, or a Species, or a Compartment, etc.). Then:

1 RDF = RDFAnnotationParser.createRDFAnnotation() # Create XML structure.
2 success = RDF.addChild(...content...) # Put some content into it.
3 ... # Check return code value.
4 
5 annot = RDFAnnotationParser.createAnnotation() # Create <annotation>.
6 success = annot.addChild(RDF) # Put the annotation into it.
7 ... # Check return code value.
8 
9 success = sbmlObject.setAnnotation(annot) # Set object's annotation.
10 ... # Check return code value.

The SBML specification contains more information about the format of annotations. We urge readers to consult Section 6 of the SBML Level 2 (Versions 2–4) and SBML Level 3 specification documents.

Returns
a pointer to an XMLNode for the annotation
Note
Because this is a static method on a class, the Python language interface for libSBML will contain two variants. One will be the expected, normal static method on the class (i.e., a regular methodName), and the other will be a standalone top-level function with the name ClassName_methodName(). This is merely an artifact of how the language interfaces are created in libSBML. The methods are functionally identical.
See also
RDFAnnotationParser.createRDFAnnotation()
def libsbml.SBMLDocument.getDefaultLevel ( )

Overall SBML container object.

LibSBML uses the class SBMLDocument as a top-level container for storing SBML content and data associated with it (such as warnings and error messages). The two primary means of reading an SBML model, SBMLReader.readSBML() and SBMLReader.readSBMLFromString(), both return a pointer to an SBMLDocument object. From there, callers can inquire about any errors encountered (e.g., using SBMLDocument.getNumErrors()), access the Model object, and perform other actions such as consistency-checking and model translation.

When creating fresh models programmatically, the starting point is typically the creation of an SBMLDocument object instance. The SBMLDocument constructor accepts arguments for the SBML Level and Version of the model to be created. After creating the SBMLDocument object, calling programs then typically call SBMLDocument.createModel() almost immediately, and then proceed to call the methods on the Model object to fill out the model's contents.

SBMLDocument corresponds roughly to the class Sbml defined in the SBML Level 2 specification and SBML in the Level 3 specification. It does not have a direct correspondence in SBML Level 1. (However, to make matters simpler for applications, libSBML creates an SBMLDocument no matter whether the model is Level 1, Level 2 or Level 3.) In its barest form, when written out in XML format for (e.g.) SBML Level 2 Version 4, the corresponding structure is the following:

<sbml xmlns='http://www.sbml.org/sbml/level2/version4' level='2' version='4'>
  ...
</sbml>

SBMLDocument is derived from SBase, and therefore contains the usual SBase attributes (in SBML Level 2 and Level 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 data structure. These can be accessed using the methods defined by the SBase class for that purpose.

Checking consistency and adherence to SBML specifications

One of the most important features of libSBML is its ability to perform SBML validation to ensure that a model adheres to the SBML specification for whatever Level+Version combination the model uses. SBMLDocument provides the methods for running consistency-checking and validation rules on the SBML content.

First, a brief explanation of the rationale is in order. In libSBML versions up to and including the version 3.3.x series, the individual methods for creating and setting attributes and other components were quite lenient, and allowed a caller to compose SBML entities that might not, in the end, represent valid SBML. This allowed applications the freedom to do things such as save incomplete models (which is useful when models are being developed over long periods of time). In the version 4.x series, libSBML is somewhat stricter, but still permits structures to be created independently and the results to be combined in a separate step. In all these cases, it means that a separate validation step is necessary when a calling program finally wants to finish a complete SBML document.

The primary interface to this validation facility is SBMLDocument's SBMLDocument.checkInternalConsistency() and SBMLDocument.checkConsistency(). The former verifies the basic internal consistency and syntax of an SBML document, and the latter implements more elaborate validation rules (both those defined by the SBML specifications, as well as additional rules offered by libSBML).

The checks performed by SBMLDocument.checkInternalConsistency() are hardwired and cannot be changed by calling programs, but the validation performed by SBMLDocument.checkConsistency() is under program control using the method SBMLDocument.setConsistencyChecks(). Applications can selectively disable specific kinds of checks that they may not be interested in, by calling SBMLDocument.setConsistencyChecks() with appropriate parameters.

These methods have slightly different relevance depending on whether a model is created programmaticaly from scratch, or whether it is read in from a file or data stream. The following list summarizes the possible scenarios.

Scenario 1: Creating a model from scratch. Before writing out the model,

Scenario 2: Reading a model from a file or data stream. After reading the model,

  • Basic consistency checks will have been performed automatically by libSBML upon reading the content, so you only need to inquire about the results by using SBMLDocument.getNumErrors()

Converting documents between Levels and Versions of SBML

LibSBML provides facilities for limited translation of SBML between Levels and Versions of the SBML specifications. The method for doing is is setLevelAndVersion() . In general, models can be converted upward without difficulty (e.g., from SBML Level 1 to Level 2, or from an earlier Version of Level 2 to the latest Version of Level 2). Sometimes models can be translated downward as well, if they do not use constructs specific to more advanced Levels of SBML.

Calling SBMLDocument.setLevelAndVersion() will not necessarily lead to a successful conversion. The method will return a boolean value to indicate success or failure. Callers must check the error log (see next section) attached to the SBMLDocument object after calling SBMLDocument.setLevelAndVersion() in order to assess whether any problems arose.

If an application is interested in translating to a lower Level and/or Version of SBML within a Level, the following methods allow for prior assessment of whether there is sufficient compatibility to make a translation possible:

Some changes between Versions of SBML Level 2 may lead to unexpected behaviors when attempting conversions in either direction. For example, SBML Level 2 Version 4 relaxed the requirement for consistency in units of measurement between expressions annd quantities in a model. As a result, a model written in Version 4, if converted to Version 3 with no other changes, may fail validation as a Version 3 model because Version 3 imposed stricter requirements on unit consistency.

Other changes between SBML Level 2 and Level 3 make downward conversions challenging. In some cases, it means that a model converted to Level 2 from Level 3 will contain attributes that were not explicitly given in the Level 3 model, because in Level 2 these attributes may have been optional or have default values.

Error handling

Upon reading a model, SBMLDocument logs any problems encountered while reading the model from the file or data stream. The log contains objects that record diagnostic information about any notable issues that arose. Whether the problems are warnings or errors, they are both reported through a single common interface involving the object class SBMLError.

The methods SBMLDocument.getNumErrors(), SBMLDocument.getError() and SBMLDocument.printErrors() allow callers to interact with the warnings or errors logged. Alternatively, callers may retrieve the entire log as an SBMLErrorLog object using the method SBMLDocument.getErrorLog(). The SBMLErrorLog object provides some alternative methods for interacting with the set of errors and warnings. In either case, applications typically should first call SBMLDocument.getNumErrors() to find out if any issues have been logged after specific libSBML operations such as the ones discussed in the sections above. If they have, then an application will should proceed to inspect the individual reports using either the direct interfaces on SBMLDocument or using the methods on the SBMLErrorLog object.

The default SBML Level of new SBMLDocument objects.

getDefaultLevel()   long
This 'default Level' corresponds to the most recent SBML specification Level available at the time libSBML version 5.11.0 was released. The default Level is used by SBMLDocument if no Level is explicitly specified at the time of the construction of an SBMLDocument instance.
Returns
an integer indicating the most recent SBML specification Level
Note
Because this is a static method on a class, the Python language interface for libSBML will contain two variants. One will be the expected, normal static method on the class (i.e., a regular methodName), and the other will be a standalone top-level function with the name ClassName_methodName(). This is merely an artifact of how the language interfaces are created in libSBML. The methods are functionally identical.
See also
SBMLDocument.getDefaultVersion()
def libsbml.SBasePlugin.getElementNamespace (   self)

Base class for extending SBML objects in packages.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The SBasePlugin class is libSBML's base class for extensions of core SBML component objects. SBasePlugin defines basic virtual methods for reading/writing/checking additional attributes and/or subobjects; these methods should be overridden by subclasses to implement the necessary features of an extended SBML object.

Perhaps the easiest way to explain and motivate the role of SBasePlugin is through an example. The SBML Layout package specifies the existence of an element, <listOfLayouts>, contained inside an SBML <model> element. In terms of libSBML components, this means a new ListOfLayouts class of objects must be defined, and this object placed in an extended class of Model (because Model in plain/core SBML does not allow the inclusion of a ListOfLayouts subobject). This extended class of Model is LayoutModelPlugin, and it is derived from SBasePlugin.

How to extend SBasePlugin for a package implementation

LibSBML package extensions can extend existing libSBML objects such as Model using SBasePlugin as a base class, to hold attributes and/or subcomponents necessary for the SBML package being implemented. Package developers must implement an SBasePlugin extended class for each element to be extended (e.g., Model, Reaction, and others) where additional attributes and/or top-level objects of the package extension are directly contained. The following subsections detail the basic steps necessary to use SBasePlugin for the implementation of a class extension.

1. Identify the SBML components that need to be extended

The specification for a SBML Level 3 package will define the attributes and subojects that make up the package constructs. Those constructs that modify existing SBML components such as Model, Reaction, etc., will be the ones that need to be extended using SBasePlugin.

For example, the Layout package makes additions to Model, SpeciesReference, and the <sbml> element (which is represented in libSBML by SBMLDocument). This means that the Layout package extension in libSBML needs to define extended versions of Model, SpeciesReference and SBMLDocument. Elements other than the SBML document need to be implemented using SBasePlugin; the document component must be implemented using SBMLDocumentPlugin instead.

2. Create a SBasePlugin subclass for each extended SBML component

A new class definition that subclasses SBasePlugin needs to be created for each SBML component to be extended by the package. For instance, the Layout package needs LayoutModelPlugin and LayoutSpeciesReferencePlugin. (As mentioned above, the Layout class also needs LayoutSBMLDocumentPlugin, but this one is implemented using SBMLDocumentPlugin instead of SBasePlugin.) Below, we describe in detail the different parts of an SBasePlugin subclass definition.

2.1 Define protected data members

Data attributes on each extended class in an SBML package will have one of the data types string, double, int, or bool. Subelements/subobjects will normally be derived from the ListOf class or from SBase.

The additional data members must be properly initialized in the class constructor, and must be properly copied in the copy constructor and assignment operator. For example, the following data member is defined in the GroupsModelPlugin class (in the file GroupsModelPlugin.h):

ListOfGroups mGroups;

2.2 Override SBasePlugin class-related methods

The derived class must override the constructor, copy constructor, assignment operator (operator=) and clone() methods from SBasePlugin.

2.3 Override SBasePlugin virtual methods for attributes

If the extended component is defined by the SBML Level 3 package to have attributes, then the extended class definition needs to override the following internal methods on SBasePlugin and provide appropriate implementations:

  • addExpectedAttributes(ExpectedAttributes& attributes): This method should add the attributes that are expected to be found on this kind of extended component in an SBML file or data stream.
  • readAttributes(XMLAttributes attributes, ExpectedAttributes& expectedAttributes): This method should read the attributes expected to be found on this kind of extended component in an SBML file or data stream.
  • hasRequiredAttributes(): This method should return True if all of the required attribute for this extended component are present on instance of the object.
  • writeAttributes(XMLOutputStream stream): This method should write out the attributes of an extended component. The implementation should use the different kinds of writeAttribute methods defined by XMLOutputStream to achieve this.

2.4 Override SBasePlugin virtual methods for subcomponents

If the extended component is defined by the Level 3 package to have subcomponents (i.e., full XML elements rather than mere attributes), then the extended class definition needs to override the following internal SBasePlugin methods and provide appropriate implementations:

  • createObject(XMLInputStream stream): Subclasses must override this method to create, store, and then return an SBML object corresponding to the next XMLToken in the XMLInputStream. To do this, implementations can use methods like peek() on XMLInputStream to test if the next object in the stream is something expected for the package. For example, LayoutModelPlugin uses peek() to examine the next element in the input stream, then tests that element against the Layout namespace and the element name 'listOfLayouts' to see if it's the single subcomponent (ListOfLayouts) permitted on a Model object using the Layout package. If it is, it returns the appropriate object.
  • connectToParent(SBase sbase): This creates a parent-child relationship between a given extended component and its subcomponent(s).
  • setSBMLDocument(SBMLDocument d): This method should set the parent SBMLDocument object on the subcomponent object instances, so that the subcomponent instances know which SBMLDocument contains them.
  • enablePackageInternal(string& pkgURI, string& pkgPrefix, bool flag): This method should enable or disable the subcomponent based on whether a given XML namespace is active.
  • writeElements(XMLOutputStream stream): This method must be overridden to provide an implementation that will write out the expected subcomponents/subelements to the XML output stream.
  • readOtherXML(SBase parentObject, XMLInputStream stream): This function should be overridden if elements of annotation, notes, MathML content, etc., need to be directly parsed from the given XMLInputStream object.
  • hasRequiredElements(): This method should return True if a given object contains all the required subcomponents defined by the specification for that SBML Level 3 package.

2.5 Override SBasePlugin virtual methods for XML namespaces

If the package needs to add additional xmlns attributes to declare additional XML namespace URIs, the extended class should override the following method:

  • writeXMLNS(XMLOutputStream stream): This method should write out any additional XML namespaces that might be needed by a package implementation.

2.6 Implement additional methods as needed

Extended component implementations can add whatever additional utility methods are useful for their implementation.

Returns the namespace URI of the package to which this plugin object belongs.

getElementNamespace()   string
Returns
the XML namespace URI of the SBML Level 3 package implemented by this libSBML package extension.
def libsbml.SBMLErrorLog.getError (   self,
  n 
)

Log of diagnostics reported during processing.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The error log is a list. Each SBMLDocument maintains its own SBMLErrorLog. When a libSBML operation on SBML content results in an error, or when there is something worth noting about the SBML content, the issue is reported as an SBMLError object stored in the SBMLErrorLog list.

SBMLErrorLog is derived from XMLErrorLog, an object class that serves exactly the same purpose but for the XML parsing layer. XMLErrorLog provides crucial methods such as getNumErrors() for determining how many SBMLError or XMLError objects are in the log. SBMLErrorLog inherits these methods.

The general approach to working with SBMLErrorLog in user programs involves first obtaining a pointer to a log from a libSBML object such as SBMLDocument. Callers should then use getNumErrors() to inquire how many objects there are in the list. (The answer may be 0.) If there is at least one SBMLError object in the SBMLErrorLog instance, callers can then iterate over the list using SBMLErrorLog.getError(), using methods provided by the SBMLError class to find out the error code and associated information such as the error severity, the message, and the line number in the input.

If you wish to simply print the error strings for a human to read, an easier and more direct way might be to use SBMLDocument.printErrors().

See also
SBMLError
XMLErrorLog
XMLError

Returns the nth SBMLError object in this log.

getError(long n)   SBMLError

Index n is counted from 0. Callers should first inquire about the number of items in the log by using the getNumErrors() method. Attempts to use an error index number that exceeds the actual number of errors in the log will result in a None being returned.

Parameters
nthe index number of the error to retrieve (with 0 being the first error).
Returns
the nth SBMLError in this log, or None if n is greater than or equal to getNumErrors().
See also
getNumErrors()
def libsbml.SimpleSpeciesReference.getId (   self)

Abstract class for references to species in reactions.

As mentioned in the description of Reaction, every species that enters into a given reaction must appear in that reaction's lists of reactants, products and/or modifiers. In an SBML model, all species that may participate in any reaction are listed in the 'listOfSpecies' element of the top-level Model object. Lists of products, reactants and modifiers in Reaction objects do not introduce new species, but rather, they refer back to those listed in the model's top-level 'listOfSpecies'. For reactants and products, the connection is made using SpeciesReference objects; for modifiers, it is made using ModifierSpeciesReference objects. SimpleSpeciesReference is an abstract type that serves as the parent class of both SpeciesReference and ModifierSpeciesReference. It is used simply to hold the attributes and elements that are common to the latter two structures.

The SimpleSpeciesReference structure has a mandatory attribute, 'species', which must be a text string conforming to the identifer syntax permitted in SBML. This attribute is inherited by the SpeciesReference and ModifierSpeciesReference subclasses derived from SimpleSpeciesReference. The value of the 'species' attribute must be the identifier of a species defined in the enclosing Model. The species is thereby declared as participating in the reaction being defined. The precise role of that species as a reactant, product, or modifier in the reaction is determined by the subclass of SimpleSpeciesReference (i.e., either SpeciesReference or ModifierSpeciesReference) in which the identifier appears.

SimpleSpeciesReference also contains an optional attribute, 'id', allowing instances to be referenced from other structures. No SBML structures currently do this; however, such structures are anticipated in future SBML Levels.

Returns the value of the 'id' attribute of this SimpleSpeciesReference.

getId()   string
Returns
the id of this SimpleSpeciesReference.
def libsbml.SBMLConverterRegistry.getInstance ( )

Registry of all libSBML SBML converters.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. It is a class used in the implementation of extra functionality provided by libSBML.

LibSBML provides facilities for transforming and converting SBML documents in various ways. These transformations can involve essentially anything that can be written algorithmically; examples include converting the units of measurement in a model, or converting from one Level+Version combination of SBML to another. Converters are implemented as objects derived from the class SBMLConverter.

The converter registry, implemented as a singleton object of class SBMLConverterRegistry, maintains a list of known converters and provides methods for discovering them. Callers can use the method SBMLConverterRegistry.getNumConverters() to find out how many converters are registered, then use SBMLConverterRegistry.getConverterByIndex() to iterate over each one; alternatively, callers can use SBMLConverterRegistry.getConverterFor() to search for a converter having specific properties.

Returns the singleton instance for the converter registry.

getInstance()   SBMLConverterRegistry

Prior to using the registry, callers have to obtain a copy of the registry. This static method provides the means for doing that.

Returns
the singleton for the converter registry.
def libsbml.SBMLExtensionRegistry.getInstance ( )

Registry where package extensions are registered.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

This class provides a central registry of all extensions known to libSBML. Each package extension must be registered with the registry. The registry class is accessed by various classes to retrieve information about known package extensions and to create additional attributes and/or elements by factory objects of the package extensions.

The package extension registry is implemented as a singleton instance of SBMLExtensionRegistry. The class provides only utility functionality; implementations of SBML packages do not need to implement any subclasses or methods of this class. SBMLExtensionRegistry is useful for its facilities to query the known packages, and to enable or disable packages selectively.

Returns a singleton instance of the registry.

getInstance()   SBMLExtensionRegistry

Callers need to obtain a copy of the package extension registry before they can invoke its methods. The registry is implemented as a singleton, and this is the method callers can use to get a copy of it.

Returns
the instance of the SBMLExtensionRegistry object.
def libsbml.XMLErrorLog.getNumErrors (   self)

Log of diagnostics reported during XML processing.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The error log is a list. The XML layer of libSBML maintains an error log associated with a given XML document or data stream. When an operation results in an error, or when there is something wrong with the XML content, the problem is reported as an XMLError object stored in the XMLErrorLog list. Potential problems range from low-level issues (such as the inability to open a file) to XML syntax errors (such as mismatched tags or other problems).

A typical approach for using this error log is to first use getNumErrors() to inquire how many XMLError object instances it contains, and then to iterate over the list of objects one at a time using getError(long n) . Indexing in the list begins at 0.

In normal circumstances, programs using libSBML will actually obtain an SBMLErrorLog rather than an XMLErrorLog. The former is subclassed from XMLErrorLog and simply wraps commands for working with SBMLError objects rather than the low-level XMLError objects. Classes such as SBMLDocument use the higher-level SBMLErrorLog.

Returns the number of errors that have been logged.

getNumErrors()   long

To retrieve individual errors from the log, callers may use XMLErrorLog.getError() .

Returns
the number of errors that have been logged.
def libsbml.SBO.isQuantitativeParameter (   term)

Facilities for using the Systems Biology Ontology.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The values of 'id' attributes on SBML components allow the components to be cross-referenced within a model. The values of 'name' attributes on SBML components provide the opportunity to assign them meaningful labels suitable for display to humans. The specific identifiers and labels used in a model necessarily must be unrestricted by SBML, so that software and users are free to pick whatever they need. However, this freedom makes it more difficult for software tools to determine, without additional human intervention, the semantics of models more precisely than the semantics provided by the SBML object classes defined in other sections of this document. For example, there is nothing inherent in a parameter with identifier k that would indicate to a software tool it is a first-order rate constant (if that's what k happened to be in some given model). However, one may need to convert a model between different representations (e.g., Henri-Michaelis-Menten versus elementary steps), or to use it with different modeling approaches (discrete or continuous). One may also need to relate the model components with other description formats such as SBGN (http://www.sbgn.org/) using deeper semantics. Although an advanced software tool might be able to deduce the semantics of some model components through detailed analysis of the kinetic rate expressions and other parts of the model, this quickly becomes infeasible for any but the simplest of models.

An approach to solving this problem is to associate model components with terms from carefully curated controlled vocabularies (CVs). This is the purpose of the optional 'sboTerm' attribute provided on the SBML class SBase. The 'sboTerm' attribute always refers to terms belonging to the Systems Biology Ontology (SBO).

Use of SBO

Labeling model components with terms from shared controlled vocabularies allows a software tool to identify each component using identifiers that are not tool-specific. An example of where this is useful is the desire by many software developers to provide users with meaningful names for reaction rate equations. Software tools with editing interfaces frequently provide these names in menus or lists of choices for users. However, without a standardized set of names or identifiers shared between developers, a given software package cannot reliably interpret the names or identifiers of reactions used in models written by other tools.

The first solution that might come to mind is to stipulate that certain common reactions always have the same name (e.g., 'Michaelis-Menten'), but this is simply impossible to do: not only do humans often disagree on the names themselves, but it would not allow for correction of errors or updates to the list of predefined names except by issuing new releases of the SBML specification—to say nothing of many other limitations with this approach. Moreover, the parameters and variables that appear in rate expressions also need to be identified in a way that software tools can interpret mechanically, implying that the names of these entities would also need to be regulated.

The Systems Biology Ontology (SBO) provides terms for identifying most elements of SBML. The relationship implied by an 'sboTerm' on an SBML model component is is-a between the characteristic of the component meant to be described by SBO on this element and the SBO term identified by the value of the 'sboTerm'. By adding SBO term references on the components of a model, a software tool can provide additional details using independent, shared vocabularies that can enable other software tools to recognize precisely what the component is meant to be. Those tools can then act on that information. For example, if the SBO identifier 'SBO:0000049' is assigned to the concept of 'first-order irreversible mass-action kinetics, continuous framework', and a given KineticLaw object in a model has an 'sboTerm' attribute with this value, then regardless of the identifier and name given to the reaction itself, a software tool could use this to inform users that the reaction is a first-order irreversible mass-action reaction. This kind of reverse engineering of the meaning of reactions in a model would be difficult to do otherwise, especially for more complex reaction types.

The presence of SBO labels on Compartment, Species, and Reaction objects in SBML can help map those entities to equivalent concepts in other standards, such as (but not limited to) BioPAX (http://www.biopax.org/), PSI-MI (http://www.psidev.info), or the Systems Biology Graphical Notation (SBGN, http://www.sbgn.org/). Such mappings can be used in conversion procedures, or to build interfaces, with SBO becoming a kind of 'glue' between standards of representation.

The presence of the label on a kinetic expression can also allow software tools to make more intelligent decisions about reaction rate expressions. For example, an application could recognize certain types of reaction formulas as being ones it knows how to solve with optimized procedures. The application could then use internal, optimized code implementing the rate formula indexed by identifiers such as 'SBO:0000049' appearing in SBML models.

Finally, SBO labels may be very valuable when it comes to model integration, by helping identify interfaces, convert mathematical expressions and parameters etc.

Although the use of SBO can be beneficial, it is critical to keep in mind that the presence of an 'sboTerm' value on an object must not change the fundamental mathematical meaning of the model. An SBML model must be defined such that it stands on its own and does not depend on additional information added by SBO terms for a correct mathematical interpretation. SBO term definitions will not imply any alternative mathematical semantics for any SBML object labeled with that term. Two important reasons motivate this principle. First, it would be too limiting to require all software tools to be able to understand the SBO vocabularies in addition to understanding SBML. Supporting SBO is not only additional work for the software developer; for some kinds of applications, it may not make sense. If SBO terms on a model are optional, it follows that the SBML model must remain unambiguous and fully interpretable without them, because an application reading the model may ignore the terms. Second, we believe allowing the use of 'sboTerm' to alter the mathematical meaning of a model would allow too much leeway to shoehorn inconsistent concepts into SBML objects, ultimately reducing the interoperability of the models.

Relationships between SBO and SBML

The goal of SBO labeling for SBML is to clarify to the fullest extent possible the nature of each element in a model. The approach taken in SBO begins with a hierarchically-structured set of controlled vocabularies with six main divisions: (1) entity, (2) participant role, (3) quantitative parameter, (4) modeling framework, (5) mathematical expression, and (6) interaction. The web site for SBO (http://biomodels.net) should be consulted for the current version of the ontology.

The Systems Biology Ontology (SBO) is not part of SBML; it is being developed separately, to allow the modeling community to evolve the ontology independently of SBML. However, the terms in the ontology are being designed keeping SBML components in mind, and are classified into subsets that can be directly related with SBML components such as reaction rate expressions, parameters, and others. The use of 'sboTerm' attributes is optional, and the presence of 'sboTerm' on an element does not change the way the model is interpreted. Annotating SBML elements with SBO terms adds additional semantic information that may be used to convert the model into another model, or another format. Although SBO support provides an important source of information to understand the meaning of a model, software does not need to support 'sboTerm' to be considered SBML-compliant.

Returns True if the given term identifier comes from the stated branch of SBO.

isQuantitativeParameter(long term)   bool
Returns
True if term is-a SBO 'quantiative parameter', False otherwise.
Note
Because this is a static method on a class, the Python language interface for libSBML will contain two variants. One will be the expected, normal static method on the class (i.e., a regular methodName), and the other will be a standalone top-level function with the name ClassName_methodName(). This is merely an artifact of how the language interfaces are created in libSBML. The methods are functionally identical.
def libsbml.SyntaxChecker.isValidSBMLSId (   sid)

Methods for checking the validity of SBML identifiers.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

This utility class provides static methods for checking the syntax of identifiers and other text used in an SBML model. The methods allow callers to verify that strings such as SBML identifiers and XHTML notes text conform to the SBML specifications.

Returns true True or False depending on whether the argument string conforms to the syntax of SBML identifiers.

isValidSBMLSId(string sid)   bool
In SBML, identifiers that are the values of 'id' attributes on objects must conform to a data type called SId in the SBML specifications. LibSBML does not provide an explicit SId data type; it uses ordinary character strings, which is easier for applications to support. (LibSBML does, however, test for identifier validity at various times, such as when reading in models from files and data streams.)

This method provides programs with the ability to test explicitly that the identifier strings they create conform to the SBML identifier syntax.

Parameters
sidstring to be checked for conformance to SBML identifier syntax.
Returns
True if the string conforms to type SBML data type SId, False otherwise.
SBML has strict requirements for the syntax of identifiers, that is, the values of the 'id' attribute present on most types of SBML objects. The following is a summary of the definition of the SBML identifier type SId, which defines the permitted syntax of identifiers. We express the syntax using an extended form of BNF notation:
letter ::= 'a'..'z','A'..'Z'
digit  ::= '0'..'9'
idChar ::= letter | digit | '_'
SId    ::= ( letter | '_' ) idChar*
The characters ( and ) are used for grouping, the character * 'zero or more times', and the character | indicates logical 'or'. The equality of SBML identifiers is determined by an exact character sequence match; i.e., comparisons must be performed in a case-sensitive manner. In addition, there are a few conditions for the uniqueness of identifiers in an SBML model. Please consult the SBML specifications for the exact details of the uniqueness requirements.
Note
Because this is a static method on a class, the Python language interface for libSBML will contain two variants. One will be the expected, normal static method on the class (i.e., a regular methodName), and the other will be a standalone top-level function with the name ClassName_methodName(). This is merely an artifact of how the language interfaces are created in libSBML. The methods are functionally identical.
See also
SyntaxChecker.isValidUnitSId()
SyntaxChecker.isValidXMLID()