libsbmljs experimental

5.18.1
Need help reading this?

libsbml

libsbmljs

A WebAssembly / JavaScript wrapper for the libSBML C++ library.

Async Loading

Unlike most JavaScript modules, this module and associated WebAssembly file are loaded asynchronously by the browser, so you can not begin using it immediately after importing it. Instead, the module returns a promise-like object with a then() method, which is invoked with the module itself when it is fully loaded. This is a standard convention for all Emscripten modules.

import libsbml from 'libsbml_stable'
// the module isn't usable yet - wait for it to load
libsbml().then((libsbml) => {
  // now it is safe to use the module
  const doc = new libsbml.SBMLDocument(3,2)
})

Despite this suggestive naming scheme, the libsbml().then() method does not return an authentic JavaScript Promise. For instance, the expected catch() method is missing. Instead, it is recommended that users use normal try/catch blocks to handle errors within the callback.

Static Methods

The mechanism for calling static methods is somewhat unconventional. Static methods should be called via an class's prototype. For example, to get the namespace for the SBML comp extension, one would normally call the getXmlnsL3V1V1 static method of the C++ CompExtension class. In libsbmljs, this method should be called on the class's prototype instead.

import libsbml from 'libsbml_stable'
libsbml().then((libsbml) => {
  const doc = new libsbml.SBMLDocument(3,2)
  // call the getXmlnsL3V1V1 static method on the prototype, not the type itself
  doc.enablePackage(libsbml.CompExtension.prototype.getXmlnsL3V1V1(), 'comp', true)
})

addX Methods vs. createX Methods

Objects in libSBML typically provide two types of methods for adding a subobject. Methods that start with add take a pre-existing subobject and add it to the parent, whereas methods that start with create return a new subobject. You should generally use the create methods. While add methods technically work in this wrapper, they have very confusing ownership semantics and using them will most likely result in bugs which are difficult to track down. This advice also applies to C++, but debugging can be harder in a JavaScript environment.

import libsbml from 'libsbml_stable'
libsbml().then((libsbml) => {
  ...
  const model = ...
  // prefer this way of creating species
  const spec = model.createSpecies()
  // this way is more awkward
  const spec = new libsbml.Species(...)
  model.addSpecies(spec)
})

Module

libsbml

SBMLReader

Text-string SBML reader.

The SBMLReader class provides the main interface for reading SBML content from 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.

Support for reading compressed files

The libsbml.js wrapper does not include library-level compression support. Users who wish to utilize compressed models on the web should consider HTTP compression.

new SBMLReader()
Instance Members
▸ SBMLReader()
▸ readSBMLFromString(xml)

SBMLWriter

Text-string SBML writer.

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

The libsbml.js wrapper does not include library-level compression support. Users who wish to utilize compressed models on the web should consider HTTP compression.

new SBMLWriter()
Instance Members
▸ SBMLWriter()
▸ writeSBMLToString(d)
▸ setProgramVersion(version)
▸ setProgramName(name)

SBMLDocument

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 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 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,

  • Call SBMLDocument::checkInternalConsistency(), then inquire about the results by calling SBMLDocument::getNumErrors()

  • Call SBMLDocument#setConsistencyChecks to configure which checks will be performed by SBMLDocument::checkConsistency()

  • Call SBMLDocument::checkConsistency(), then inquire about the results by calling SBMLDocument::getNumErrors()

Scenario 2: Reading a model from a file or data stream. After reading the model,

It should be noted that as of SBML Level 3 Version 2, the Model became an optional child of SBMLDocument, instead of being required. This means that one can no longer use SBMLDocument#getModel as a cheap method of checking if an SBML document was read in properly: the more robust getError methods detailed above must be used instead.

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 SBMLDocument#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 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 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 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.

new SBMLDocument()
Instance Members
▸ setLevelAndVersion(level, version, strict, ignorePackages)

SBMLDocumentPlugin

Base class for extending SBMLDocument in packages.

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.

All packages must additionally define a required flag named required, which indicates whether that package's constructs can be used to change the core mathematics of the <model> child of the <sbml> element. If they can, this attribute must be set true, and if they cannot, this attribute must be set false.

new SBMLDocumentPlugin()
Instance Members
▸ setRequired(value)
▸ getRequired()
▸ isSetRequired()
▸ unsetRequired()
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

Model

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 SBML Level 1, the components are: UnitDefinition, Compartment, Species, Parameter, Rule, and Reaction. Instances of the classes are placed inside instances of classes ListOfUnitDefinitions, ListOfCompartments, ListOfSpecies, ListOfParameters, ListOfRules, and ListOfReactions.

  • In SBML Level 2 Version 1, the components are: FunctionDefinition, UnitDefinition, Compartment, Species, Parameter, Rule, Reaction and Event. Instances of the classes are placed inside instances of classes ListOfFunctionDefinitions, ListOfUnitDefinitions, ListOfCompartments, ListOfSpecies, ListOfParameters, ListOfRules, ListOfReactions, and ListOfEvents.

  • In SBML Level 2 Versions 2, 3 and 4, the components are: FunctionDefinition, UnitDefinition, CompartmentType, SpeciesType, Compartment, Species, Parameter, InitialAssignment, Rule, Constraint, Reaction and Event. Instances of the classes are placed inside instances of classes ListOfFunctionDefinitions, ListOfUnitDefinitions, ListOfCompartmentTypes, ListOfSpeciesTypes, ListOfCompartments, ListOfSpecies, ListOfParameters, ListOfInitialAssignments, ListOfRules, ListOfConstraints, ListOfReactions, and ListOfEvents.

  • In SBML Level 3 Version 1, the components are: FunctionDefinition, UnitDefinition, Compartment, Species, Parameter, InitialAssignment, Rule, Constraint, Reaction and Event. Instances of the classes are placed inside instances of classes ListOfFunctionDefinitions, ListOfUnitDefinitions, ListOfCompartments, ListOfSpecies, ListOfParameters, ListOfInitialAssignments, ListOfRules, ListOfConstraints, ListOfReactions, and ListOfEvents.

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, 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., libsbml.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:

import libsbml from 'libsbml_experimental'

libsbml.then((libsbml) => {
  // Create an SBMLDocument object in Level 3 Version 1 format:

  const SBMLDocument sbmlDoc = new libsbml.SBMLDocument(3, 1)

  // Create a Model object inside the SBMLDocument object and set
  // its identifier.  The call returns a pointer to the Model object
  // created, and methods called on that object affect the attributes
  // of the object attached to the model (as expected).

  const Model model = sbmlDoc.createModel()
  model.setId("BestModelEver")

  // Create a Species object inside the Model and set its identifier.
  // Similar to the lines above, this call returns a pointer to the Species
  // object created, and methods called on that object affect the attributes
  // of the object attached to the model (as expected).

  const Species sp = model->createSpecies()
  sp.setId("MySpecies")
})

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 <listOfSpecies> 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 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. 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 specifications provide 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 specifications.

new Model()
Instance Members
▸ getNumReactions()
▸ getReaction(sid)
▸ createReaction()
▸ addReaction(r)
▸ removeReaction(n)
▸ getNumSpecies()
▸ createSpecies()
▸ addSpecies(s)
▸ getSpecies(n)
▸ removeSpecies(n)
▸ getNumUnitDefinitions()
▸ getUnitDefinition(n)
▸ getNumCompartments()
▸ getCompartment(n)
▸ createCompartment()
▸ removeCompartment(n)
▸ getNumParameters()
▸ createParameter()
▸ getParameter(n)
▸ getNumEvents()
▸ getEvent(sid)
▸ getFunctionDefinition(n)
▸ getNumInitialAssignments()
▸ getConstraint(n)
▸ getNumConstraints()
▸ getNumSpeciesWithBoundaryCondition()
▸ getSpeciesReference(sid)
▸ getModifierSpeciesReference(sid)
▸ getNumRules()
▸ getRule(n)
▸ getRateRuleByVariable(variable)
▸ getAssignmentRuleByVariable(variable)
▸ getInitialAssignment(n)
▸ getInitialAssignmentBySymbol(symbol)
▸ createInitialAssignment()
▸ createAlgebraicRule()
▸ createAssignmentRule()
▸ createRateRule()
▸ createConstraint()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

StoichiometryMath

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 double 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. 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.

new StoichiometryMath()

SpeciesReference

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 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.

See the libSBML C++ docs for this class

new SpeciesReference()
Instance Members
▸ getSpecies()
▸ setSpecies()
▸ isSetSpecies()
▸ getConstant()
▸ setConstant(flag)
▸ isSetConstant()
▸ getStoichiometry()
▸ getStoichiometryMath()
▸ getDenominator()
▸ isSetStoichiometryMath()
▸ isSetStoichiometry()
▸ setStoichiometry(value)
▸ setStoichiometryMath(math)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

ModifierSpeciesReference

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.

new ModifierSpeciesReference()
Instance Members
▸ getSpecies()
▸ setSpecies()
▸ isSetSpecies()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Species

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 majorructs 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 double, 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 SBMLruct 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 ructs 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.

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, orructs 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 ructs 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.

Finally, it is worth clarifying that while theant and boundaryCondition attributes restrict whether and how the species amount changes, the same is not true of a species' concentration. In SBML, the concentration of a species is a quantity that depends on the size of the compartment in which it is located. A compartment's size may change, and therefore, so can the concentration of a species even if the amount of the species remains unchanged. A species' concentration may therefore vary even if the Species object'sant attribute is set to true in a 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 ant, 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 SBMLructs 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 ructs; 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 heldant, 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 SBMLruct). 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 SBMLruct. 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 heldant if the compartment size changes? No; it is still the amount that is kept ant across a compartment size change. The fact that the species was initialized using a concentration value is irrelevant.

new Species()
Instance Members
▸ getInitialAmount()
▸ setInitialAmount(value)
▸ isSetInitialAmount()
▸ getInitialConcentration()
▸ setInitialConcentration(value)
▸ isSetInitialConcentration()
▸ getHasOnlySubstanceUnits()
▸ setHasOnlySubstanceUnits(value)
▸ isSetHasOnlySubstanceUnits()
▸ getCompartment()
▸ setCompartment(sid)
▸ isSetCompartment()
▸ getUnits()
▸ setUnits(sname)
▸ isSetUnits()
▸ getBoundaryCondition()
▸ isSetBoundaryCondition()
▸ getConstant()
▸ setConstant(value)
▸ isSetConstant()
▸ getSubstanceUnits()
▸ setSubstanceUnits(sid)
▸ isSetSubstanceUnits()
▸ getConversionFactor()
▸ setConversionFactor(sid)
▸ isSetConversionFactor()
▸ unsetConstant()
▸ unsetInitialAmount()
▸ unsetInitialConcentration()
▸ unsetSubstanceUnits()
▸ unsetUnits()
▸ unsetConversionFactor()
▸ unsetCompartment()
▸ unsetBoundaryCondition()
▸ unsetHasOnlySubstanceUnits()
▸ initDefaults()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

KineticLaw

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 (required through SBML Level 3 Version 1, but optional as of SBML Level 3 Version 2) 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 (or, as of SBML Level 3 Version 2, only visible within the parent Reaction); 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.

In SBML Level 3 Version 2, the scope of the LocalParameter was expanded to the entire Reaction, instead of just the KineticLaw. This introduced a single new restriction: an L3v2 LocalParameter may not now shadow the id of any Species referenced by a SpeciesReference in the same Reaction. Other than that, there is no difference in any core construct. However, packages may take advantage of this new scope by adding elements to the Reaction that may now reference a LocalParameter defined in the same Reaction.

new KineticLaw()
Instance Members
▸ getMath()
▸ setMath(math)
▸ isSetMath()
▸ getNumLocalParameters()
▸ createLocalParameter()
▸ getLocalParameter(n)
▸ removeLocalParameter(n)
▸ getNumParameters()
▸ createParameter()
▸ getParameter(n)
▸ removeParameter(n)
▸ getFormula()
▸ setFormula(formula)
▸ getDerivedUnitDefinition()
▸ containsUndeclaredUnits()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Reaction

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 reaction 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.

  • For SBML Levels 1, 2, and SBML Level 3 Version 1, 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.) In SBML Level 3 Version 2, this requirement was dropped, allowing the creation of reactions with neither reactants nor products.

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 @em 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). In SBML Level 3 Version 2, a value of true for the "fast" attribute is deprecated in favor of all reactions having a "fast" value of false. 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. 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, 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.

See the libSBML C++ docs for this class

new Reaction()
Instance Members
▸ getNumReactants()
▸ getNumProducts()
▸ getNumModifiers()
▸ getReactant(n)
▸ getProduct(n)
▸ getModifier(n)
▸ addReactant(sr)
▸ addProduct(sr)
▸ addModifier(msr)
▸ createReactant()
▸ createProduct()
▸ createModifier()
▸ removeReactant(n)
▸ removeProduct(n)
▸ removeModifier(n)
▸ createKineticLaw()
▸ getKineticLaw()
▸ setKineticLaw(kl)
▸ isSetKineticLaw()
▸ unsetKineticLaw()
▸ getReversible()
▸ setReversible(value)
▸ isSetReversible()
▸ unsetReversible()
▸ getCompartment()
▸ setCompartment(sid)
▸ isSetCompartment()
▸ unsetCompartment()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Compartment

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 double, 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 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" is optional, and has a default value of true. In SBML Level 3, there is no default value for the "constant" attribute, and it is required.

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 objectin 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 (in Level 2 Versions 1-3) or should (in Level 2 Version 4) 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 (in Level 2 Versions 1–3) or should (in Level 2 Version 4) be identical to the compartment's units (whether defined by the "units" attribute or by taking the default value from the Model) 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 objectif 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 object 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 objectinstance. 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 objectdoes 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 a given Compartment's "units" are left unset and the "spatialDimensions" either has a value other than 1, 2, or 3 or is left unset itself (as it has no default value), 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. 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 objectthat 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 objectdefined 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.

new Compartment()
Instance Members
▸ getConstant()
▸ setConstant(value)
▸ isSetConstant()
▸ getSize()
▸ setSize(value)
▸ isSetSize()
▸ getVolume()
▸ setVolume(value)
▸ isSetVolume()
▸ getUnits()
▸ setUnits(sid)
▸ isSetUnits()
▸ getSpatialDimensions()
▸ setSpatialDimensions(value)
▸ isSetSpatialDimensions()
▸ initDefaults()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Parameter

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 double) 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.

In SBML Level 3 Version 2, many restrictions were lifted requiring only Boolean values in Boolean contexts, and numeric values in numeric contexts. This means that a Parameter may now be used as a Boolean, despite canonically having a numeric value. To be consistent, one should always assign it a value of true or false, and use it in Boolean contexts exclusively. It would be appropriate to give it an SBO value of 602 ('Logical parameter') if one chooses to do this.

new Parameter()
Instance Members
▸ getValue()
▸ setValue(value)
▸ isSetValue()
▸ isSetUnits()
▸ getUnits()
▸ setUnits(units)
▸ getConstant()
▸ setConstant(flag)
▸ isSetConstant()
▸ initDefaults()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

LocalParameter

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 double) 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.

In SBML Level 3 Version 2, the scope of the LocalParameter was expanded slightly to officially encompass the entire Reaction instead of just the KineticLaw in which it appears. This has no effect on models using only SBML Level 3 Core constructs, but has the potential to allow SBML Level 3 Packages to include elements in a Reaction that could reference a LocalParameter from that Reaction's KineticLaw. It also means that no LocalParameter may have the same "id" as a referenced Species in any SimpleSpeciesReference in that Reaction.

Note: libsbml.js does not contain implementations of isSetConstant(), setConstant(), and getConstant()) for LocalParameter objects because these methods are only relevant to the parent class Parameter.

new LocalParameter()
Instance Members
▸ getValue()
▸ setValue(value)
▸ isSetValue()
▸ isSetUnits()
▸ getUnits()
▸ setUnits(units)
▸ getDerivedUnitDefinition()
▸ initDefaults()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Unit

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 Level3:

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

The attribute named "exponent" on Unit represents an exponent on the unit. In SBML Level2, the attribute is optional and has a default value of 1 (one); in SBML Level3, 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 Level2, the attribute is optional and has a default value of 0 (zero), because 10 0 = 1; in SBML Level3, 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 Level2, where it has a default value of 1 (one); in SBML Level3, the attribute is mandatory and has no 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.

Until SBML Level2 Version3, there existed a data type in the SBML specifications called UnitKind, enumerating the possible SBML base units. Although SBML Level2 Version3 removed this type from the language specification, libSBML maintains the corresponding enumeration type UnitKind_t as a convenience and as a way to provide backward compatibility to previous SBML Level/Version specifications. (The removal in SBML Level2 Version3 of the enumeration UnitKind was also accompanied by the redefinition of the data type UnitSId to include the previous UnitKind values as reserved symbols in the UnitSId space. 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.)

As a consequence of the fact that libSBML supports models in all Levels and Versions of SBML, libSBML's set of UNITKIND 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 Level1 models.

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

  • The unit "Celsius" is included because of its presence in specifications of SBML prior to SBML Level2 Version2.

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

new Unit()
Static Members
▸ isBuiltIn(name, level)
▸ areIdentical(unit1, unit2)
▸ areEquivalent(unit1, unit2)
▸ removeScale(unit)
▸ merge(unit1, unit2)
Instance Members
▸ getKind()
▸ setKind(kind)
▸ isSetKind()
▸ unsetKind()
▸ getScale()
▸ setScale(value)
▸ isSetScale()
▸ setMultiplier(value)
▸ isSetMultiplier()
▸ unsetMultiplier()
▸ initDefaults()
▸ getExponent()
▸ getExponentAsDouble()
▸ setExponent(value)
▸ isSetExponent()
▸ unsetExponent()
▸ getOffset()
▸ setOffset(value)
▸ unsetOffset()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

UnitDefinition

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 may contain exactly one ListOfUnits, and this list may contain one or more Unit definitions; see the definitions of these other object classes for more information about them. In SBML Level 2 and SBML Level 3 Version 1, if the ListOfUnits was present, it must have one or more Unit definitions. In SBML Level 3 Version 2, this restriction was relaxed, and a ListOfUnits was allowed to be empty. In either case, if a UnitDefinition had no child Unit elements, the unit was considered to be undefined.

The following example illustrates a complete unit definition (when written in XML) when 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.).

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.

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.

new UnitDefinition()
Instance Members
▸ getNumUnits()
▸ createUnit()
▸ getUnit(n)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

UnitKindConstructor

A helper class for getting UnitKind_t values

Normally one would call the libSBML global function UnitKind_forName to get the UnitKind_t value for a string, but global functions are not available in this wrapper. Instead this helper class can be used.

See the libSBML C++ docs for UnitKind_forName.

new UnitKindConstructor()
Example
new libsbml.UnitKindConstructor().fromName('mole') // returns libsbml.UNIT_KIND_MOLE
Instance Members
▸ fromName(name)

ASTBasePlugin

Base class for extensions that plug into AST classes.

new ASTBasePlugin()
Instance Members
▸ getPackageName()

ASTNode

Abstract Syntax Tree (AST) representation of amathematical expression.

Abstract Syntax Trees (ASTs) are a simple kind of data structure used in libSBML for storing mathematical expressions. The ASTNode is the cornerstone of libSBML's AST representation. An AST "node" represents the most basic, indivisible part of a mathematical formula and come in many types. For instance, 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. 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).

The ASTNodeType_t type contains all permitted AST nodes.

Converting between ASTs and text strings

The text-string form of mathematical formulas handled by SBMLFormulaParser#parseL3Formula are in a simple C-inspired infix notation. A formula in this text-string form can be handed to a program that understands SBML mathematical expressions, or used as part of a translation system.

The formula strings may contain operators, function calls, symbols, and white space characters. The allowable white space characters are tab and space. The following are illustrative examples of formulas expressed in the syntax:

0.10 * k4^2
(vm * s1)/(km + s1)

The libSBML documentation shows the precedence rules in this syntax.

A program parsing a formula in an SBML model should assume that names appearing in the formula are the identifiers of Species, Parameter, Compartment, FunctionDefinition, Reaction (in SBML Levels 2 and 3), or SpeciesReference (in SBML Level 3 only) objects defined in a model. When a function call is involved, the syntax consists of a function identifier, followed by optional white space, followed by an opening parenthesis, followed by a sequence of zero or more arguments separated by commas (with each comma optionally preceded and/or followed by zero or more white space characters), followed by a closing parenthesis. There is an almost one-to-one mapping between the list of predefined functions available, and those defined in MathML. All of the MathML functions are recognized; this set is larger than the functions defined in SBML Level 1. In the subset of functions that overlap between MathML and SBML Level 1, there exist a few differences.

For constructing ASTs use SBMLFormulaParser.parseL3Formula.

new ASTNode()
Instance Members
▸ ASTNode(type)
▸ getNumChildren()
▸ getChild(n)
▸ getLeftChild()
▸ getRightChild()
▸ getType()
▸ getInteger()
▸ getReal()
▸ getMantissa()
▸ getExponent()
▸ getValue()
▸ getPrecedence()
▸ isAvogadro()
▸ isBoolean()
▸ returnsBoolean()
▸ isConstant()
▸ isCiNumber()
▸ isConstantNumber()
▸ isCSymbolFunction()
▸ isFunction()
▸ isInfinity()
▸ isInteger()
▸ isLambda()
▸ isLog10()
▸ isLogical()
▸ isName()
▸ isNaN()
▸ isNegInfinity()
▸ isNumber()
▸ isOperator()
▸ isPiecewise()
▸ isRational()
▸ isReal()
▸ isRelational()
▸ isSqrt()
▸ isUMinus()
▸ isUPlus()
▸ setValue(value)
▸ isUserFunction()
▸ isSetUnits()
▸ getUnits()
▸ setUnits(units)
▸ getName()
▸ setName(name)
▸ getNumPlugins()
▸ getPlugin(n)
▸ addChild(disownedChild)
▸ isSetClass()
▸ setClass(className)
▸ getClass()
▸ isWellFormedASTNode()

FunctionDefinition

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 "math" subelement containing a MathML expression defining the function body. In SBML Level 2 and SBML Level 3 Version 1, that "math" subelement is required; in SBML Level 3 Version 2, this restriction was relaxed, making the "math" subelement optional. 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.

In SBML Level 3 Version 2, if no math element is present in the FunctionDefinition, the function has no mathematical meaning defined in SBML Level 3 Core. This situation may arise when models are incomplete, or when additional meanings are provided by an SBML Level 3 package.

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.)

new FunctionDefinition()
Instance Members
▸ getNumArguments()
▸ getArgument(n)
▸ getBody()
▸ isSetBody()
▸ getMath()
▸ setMath(math)
▸ isSetMath()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Delay

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, 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 an SBML Level 3 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>

Restrictions relaxed in SBML Level 3 Version 2

In SBML Level 3 Version 2, the requirement that a Delay have a "math" subelement was relaxed, making it optional. In this case, the Delay remains undefined, and unless that information is provided in some other form (such as with an SBML Level 3 package), the Event behaves as if it had no Delay.

new Delay()
Instance Members
▸ getMath()
▸ setMath(math)
▸ isSetMath()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Priority

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 double 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 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.

Restrictions relaxed in SBML Level 3 Version 2

In SBML Level 3 Version 2, the requirement that a Priority have a "math" subelement was relaxed, making it optional. In this case, the Priority remains undefined, and unless that information is provided in some other form (such as with an SBML Level 3 package), the Event behaves as if it had no Priority.

new Priority()
Instance Members
▸ getMath()
▸ setMath(math)
▸ isSetMath()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

EventAssignment

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. In SBML Level 3 Version 2, this list was expanded to include identifiers of SBML Level 3 package variables that have both mathematical meaning and the ability to be assigned. 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. In SBML Level 2 and SBML Level 3 Version 1, only species, species references, compartment and parameter values may be set by an Event. In SBML Level 3 Version 2, the "variable" attribute may also be the identifier of an SBML Level 3 package element with mathematical meaning and the ability to be assigned a value. This situation may only arise if the SBML package is present in the SBML document with a package:required attribute of true

  • 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.)

If the variable attribute of an EventAssignment object references an object in an SBML namespace that is not understood by the interpreter reading a given SBML document (that is, if the object is defined by an SBML Level 3 package that the software does not support), the event assignment must be ignored--the object's value will not need to be set, as the interpreter could not understand that package. If an interpreter cannot establish whether a referenced object is missing from the model or instead is defined in an SBML namespace not understood by the interpreter, it may produce a warning to the user. (The latter situation may only arise if an SBML package is present in the SBML document with a package:required attribute of "true".)

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.

  • (For SBML Level 3 Version 2 only) In the case of an object from an SBML Level 3 package, an EventAssignment sets the referenced object's value (as defined by that package) to the value of the formula in "math". The unit of measurement associated with the value produced by the formula should be the same as that object's units attribute value (if it has such an attribute), or be equal to the units of model components of that type (if objects of that class are defined by the package as having the same units).

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.

Restrictions relaxed in SBML Level 3 Version 2

In SBML Level 3 Version 2, the requirement that an EventAssignment have a "math" subelement was relaxed, making it optional. In this case, the EventAssignment remains undefined, and unless that information is provided in some other form (such as with an SBML Level 3 package), the Event behaves as if it had no EventAssignment.

new EventAssignment()
Instance Members
▸ getVariable()
▸ setVariable(sid)
▸ isSetVariable()
▸ unsetVariable()
▸ getMath()
▸ setMath(math)
▸ isSetMath()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Trigger

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 is evaluated as 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.

In SBML Level 2 and SBML Level 3 Version 1, the "math" subelement is required, and it must evaluate to a boolean expression. In SBML Level 3 Version 2, those restrictions are relaxed: the "math" element is optional, and numeric values are allowed in Boolean contexts (a '0' is interpreted as false, and all other values are interpreted as true). If a Trigger with no "math" is present in an Event, that Event will never trigger, unless that missing information is included in an SBML Level 3 package.

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 Event, Delay, EventAssignment

new Trigger()
Instance Members
▸ getMath()
▸ setMath(math)
▸ isSetMath()
▸ getPersistent()
▸ setPersistent(persistent)
▸ isSetPersistent()
▸ getInitialValue()
▸ isSetInitialValue()
▸ setInitialValue(initialValue)
▸ unsetInitialValue()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Event

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 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, or after any other simultaneous event may have been executed and changed the model state). In SBML Level 2 Version 4 and in Level 3, the attribute "useValuesFromTriggerTime" on Event was added to allow a model to indicate the time at which the event's assignments are to be calculated, whether at the moment the event is triggered (if the value of the attribute is true), or at the moment of execution (if "useValuesFromTriggerTime"=false). If the event has a delay, the "useValuesFromTriggerTime" is likely to make a significant difference in the values used in the assignment, but the possibility of simultaneous events mean that even zero-delay events can have different results depending on the value of this attribute.

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.

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 and had a default value of true);
  • 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).
  • In SBML Level 3 Version 2, the Trigger object became optional. An Event with no Trigger will simply not fire.

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

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.

Restrictions relaxed in SBML Level 3 Version 2

In SBML Level 3 Version 2, several restrictions were lifted that have the potential to affect the semantics of an Event:

  • The Trigger subobject of an Event is optional. If missing, an Event is never triggered, unless an alternate triggering scheme is introduced by an SBML Level 3 package.

  • The "math" subelements of an Event Trigger, Delay, Priority, and EventAssignment are all optional. If any of these elements lack a "math" subelement, and that information is not supplied in an SBML Level 3 package, it is mathematically equivalent to the Trigger, Delay, Priority, or EventAssignment not being present at all.

  • The ListOfEventAssignments may be empty, which is mathematically equivalent to the Event not having a ListOfEventAssignments at all.

  • Any "math" subelement may return a Boolean or a numeric value in any context. If a numeric value is used in a Boolean context, a "0" is interpreted as false, and all other values are interpreted as true. If a Boolean value is used in a numeric context, a true is interpreted as a 1, and a false is interpreted as a 0. This means (for example) that a Trigger value that changes from 0.0 to anything else is equivalent to changing from false to true.

See Trigger, Priority, Delay, EventAssignment

new Event()
Instance Members
▸ createDelay()
▸ getDelay()
▸ setDelay(delay)
▸ isSetDelay()
▸ unsetDelay()
▸ createPriority()
▸ getPriority()
▸ setPriority(priority)
▸ isSetPriority()
▸ unsetPriority()
▸ createTrigger()
▸ getTrigger()
▸ setTrigger(trigger)
▸ isSetTrigger()
▸ unsetTrigger()
▸ createEventAssignment()
▸ getEventAssignment(n)
▸ getNumEventAssignments()
▸ getTimeUnits()
▸ setTimeUnits(sid)
▸ isSetTimeUnits()
▸ unsetTimeUnits()
▸ getUseValuesFromTriggerTime()
▸ setUseValuesFromTriggerTime(value)
▸ isSetUseValuesFromTriggerTime()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Rule

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 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.

new Rule()
Instance Members
▸ isRate()
▸ isAssignment()
▸ isAlgebraic()
▸ isScalar()
▸ isSpeciesConcentration()
▸ getMath()
▸ isSetMath()
▸ setMath(math)
▸ getFormula()
▸ setFormula(formula)
▸ isSetFormula()
▸ getVariable()
▸ setVariable(sid)
▸ isSetVariable()
▸ unsetVariable()
▸ getDerivedUnitDefinition()
▸ containsUndeclaredUnits()
▸ isParameter()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

AssignmentRule

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 must refer to the identifier of a Species, SpeciesReference (in SBML Level3), Compartment, or global Parameter object in the model (but not a Reaction). In SBML Level3 Version2, it may also refer to the SId of an element defined in an SBML Level3 package with mathematical meaning and the ability to be assigned. 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 Level2 Version4 and in SBML Level3) or must (in SBML releases prior to Level2 version4) 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 Level3 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 Level2 Version4 and in SBML Level3) or must (in SBML releases prior to Level2 version4) 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 Level2 Version4 and in SBML Level3) or must (in SBML releases prior to Level2 version4) be the same as the units defined for the parameter.

  • (For SBML Level3 Version2 only) In the case of an object from an SBML Level3 package, an AssignmentRule sets the referenced object's value (as defined by that package) to the value of the formula in math. The unit of measurement associated with the value produced by the formula should be the same as that object's units attribute value (if it has such an attribute), or be equal to the units of model components of that type (if objects of that class are defined by the package as having the same units).

In SBML Level2 and Level3 Version1, the "math" subelement of the AssignmentRule is required. In SBML Level3 Version2, this rule is relaxed, and the subelement is optional. If an AssignmentRule with no "math" child is present in the model, the value of its referenced "variable" is undefined. This may represent a situation where the model itself is unfinished, or the missing information may be provided by an SBML Level3 package.

If the variable attribute of an AssignmentRule object references an object in an SBML namespace not understood by the interpreter reading a given SBML document (that is, if the object is defined by an SBML Level3 package that the software does not support), the assignment rule must be ignored--the object's value will not need to be set, as the interpreter could not understand that package. If an interpreter cannot establish whether a referenced object is missing from the model or instead is defined in an SBML namespace not understood by the interpreter, it may produce a warning to the user. (The latter situation may only arise if an SBML package is present in the SBML document with a package:required attribute of "true".)

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 Level2 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.

new AssignmentRule()
Instance Members
▸ isRate()
▸ isAssignment()
▸ isAlgebraic()
▸ isScalar()
▸ isSpeciesConcentration()
▸ getMath()
▸ isSetMath()
▸ setMath(math)
▸ getFormula()
▸ setFormula(formula)
▸ isSetFormula()
▸ getVariable()
▸ setVariable(sid)
▸ isSetVariable()
▸ unsetVariable()
▸ getDerivedUnitDefinition()
▸ containsUndeclaredUnits()
▸ isParameter()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

RateRule

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 Level2 Version4 and in SBML Level3) or must (in SBML releases prior to Level2 version4) 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 Level3 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 Level2 Version4 and in SBML Level3) or must (in SBML releases prior to Level2 version4) 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 Level2 Version4 and in SBML Level3) or must (in SBML releases prior to Level2 version4) be the Parameter object's "unit" attribute value divided by the model-wide unit of time.

  • (For SBML Level3 Version2 only) In the case of an object from an SBML Level3 package, a RateRule sets the rate of change of the referenced object's value (as defined by that package) to the value of the formula in "math". The unit of measurement associated with the value produced by the formula should be the same as that object's units attribute value (if it has such an attribute) divided by the model-wide unit of time, or be equal to the units of model components of that type (if objects of that class are defined by the package as having the same units) divided by the model-wide unit of time.

In SBML Level2 and Level3 Version1, the "math" subelement of the RateRule is required. In SBML Level3 Version2, this rule is relaxed, and the subelement is optional. If a RateRule with no "math" child is present in the model, the rate at which its referenced "variable" changes over time is undefined. This may represent a situation where the model itself is unfinished, or the missing information may be provided by an SBML Level3 package.

If the variable attribute of a RateRule object references an object in an SBML namespace that is not understood by the interpreter reading a given SBML document (that is, if the object is defined by an SBML Level3 package that the software does not support), the rate rule must be ignored--the object's value will not need to be set, as the interpreter could not understand that package. If an interpreter cannot establish whether a referenced object is missing from the model or instead is defined in an SBML namespace not understood by the interpreter, it may produce a warning to the user. (The latter situation may only arise if an SBML package is present in the SBML document with a package:required attribute of "true".)

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.

new RateRule()
Instance Members
▸ isRate()
▸ isAssignment()
▸ isAlgebraic()
▸ isScalar()
▸ isSpeciesConcentration()
▸ getMath()
▸ isSetMath()
▸ setMath(math)
▸ getFormula()
▸ setFormula(formula)
▸ isSetFormula()
▸ getVariable()
▸ setVariable(sid)
▸ isSetVariable()
▸ unsetVariable()
▸ getDerivedUnitDefinition()
▸ containsUndeclaredUnits()
▸ isParameter()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

AlgebraicRule

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.)

In SBML Level2 and Level3 Version1, the "math" subelement of the AlgebraicRule is required. In SBML Level3 Version2, this rule is relaxed, and the subelement is optional. If an AlgebraicRule with no "math" child is present in the model, no additional mathematical constraints on the model are added by the rule. This may represent a situation where the model itself is unfinished, or the missing information may be provided by an SBML Level3 package.

Finally, any symbol that appears as the target of a rateOf csymbol (AST_FUNCTION_RATE_OF, introduced in SBML Level3 Version2) may not be determined by an AlgebraicRule. This is because the rateOf csymbol is defined as applying only to symbols whose rates of change are easily determinable.

Users should note that these rules about what symbols may not be determined by an AlgebraicRule may be used to discover what symbol is being determined by an AlgebraicRule. If three symbols appear in the math element of an AlgebraicRule, the first of which is flagged constant=true, and the second of which appears as the target of a rateOf csymbol, one may conclude that the AlgebraicRule must be used to determine the value of the third symbol. This is, in fact, a principle use (outside of validation) of the constant attribute: its use in allowing software to properly identify the dependent variable in an AlgebraicRule.

new AlgebraicRule()
Instance Members
▸ isRate()
▸ isAssignment()
▸ isAlgebraic()
▸ isScalar()
▸ isSpeciesConcentration()
▸ getMath()
▸ isSetMath()
▸ setMath(math)
▸ getFormula()
▸ setFormula(formula)
▸ isSetFormula()
▸ getVariable()
▸ setVariable(sid)
▸ isSetVariable()
▸ unsetVariable()
▸ getDerivedUnitDefinition()
▸ containsUndeclaredUnits()
▸ isParameter()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

InitialAssignment

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, SpeciesReference (in SBML Level 3), global Parameter, or (as of SBML Level 3 Version 2) the identifier of a SBML Level 3 package element with mathematical meaning. 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 "math" subelement that contains a MathML expression used to calculate the value of the constant or the initial value of the variable. This subelement is required in SBML Level 2 and SBML Level 3 Version 1, but the requirement was relaxed in SBML Level 3 Version 2, making it optional. 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, global Parameter, SpeciesReference (in Level 3), and SBML Level 3 package elements (in Level 3 Version 2), 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.

  • (For SBML Level 3 only) In the case of a species reference, an initial assignment sets the initial value 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", because reactant and product stoichiometries in reactions are dimensionless quantities.

  • (For SBML Level 3 Version 2 only) In the case of an object from an SBML Level 3 package, an InitialAssignment sets the referenced object's initial value (however such values are defined by the package) to the value of the formula in math. The unit of measurement associated with the value produced by the formula should be the same as that object's units attribute value (if it has such an attribute), or be equal to the units of model components of that type (if objects of that class are defined by the package as having the same units).

If the symbol attribute of an InitialAssignment object references an object in an SBML namespace that is not understood by the interpreter reading a given SBML document (that is, if the object is defined by an SBML Level 3 package that the software does not support), the assignment must be ignored--the object's initial value will not need to be set, as the interpreter could not understand that package. If an interpreter cannot establish whether a referenced object is missing from the model or instead is defined in an SBML namespace not understood by the interpreter, it may produce a warning to the user. (The latter situation may only arise if an SBML package is present in the SBML document with a package:required attribute of "true".)

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 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.

new InitialAssignment()
Instance Members
▸ getSymbol()
▸ getMath()
▸ isSetSymbol()
▸ isSetMath()
▸ setSymbol(sid)
▸ unsetSymbol()
▸ setMath(math)
▸ getDerivedUnitDefinition()
▸ containsUndeclaredUnits()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

CVTerm

A MIRIAM-compliant controlled vocabulary term.

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.

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.

See the libSBML C++ docs for this class.

new CVTerm()
Instance Members
▸ addResource(resource)
▸ getNumResources()
▸ getResourceURI(n)
▸ removeResource(resource)
▸ getQualifierType()
▸ setQualifierType(type)
▸ getBiologicalQualifierType()
▸ setBiologicalQualifierType(type)
▸ getModelQualifierType()
▸ setModelQualifierType(type)

SBase

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 2, SBase 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 long, 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". More details can be found in SBML specifications for Level 2 Version 2 and above.

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.

See the libSBML C++ docs for this class.

new SBase()
Instance Members
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

SBasePlugin

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.

new SBasePlugin()
Instance Members
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

SBMLFormulaParser

A helper class for parsing Level 3 formulae

libSBML uses the global function SBML_parseL3Formula for parsing formulae, but libsbml.js only exposes C++ types, not functions. This helper class can be used in lieu of SBML_parseL3Formula.

See the libSBML C++ docs for SBML_parseL3Formula.

new SBMLFormulaParser()
Example
new libsbml.SBMLFormulaParser().parseL3Formula('S1*S2') // returns the expected AST with a product node and two leaf nodes
Instance Members
▸ parseL3Formula(formula)
▸ parseFormula(formula)
▸ fromMathML(mathml)
▸ formulaToL3String(tree)
▸ formulaToString(tree)

LineSegment

Representation of a line.

The LineSegment class consists of the mandatory attribute xsi:type and two child elements of type Point. One is called 'start' and represents the starting point of the line, the other is called 'end' and represents the endpoint of the line. The LineSegment class is also the base class for CubicBezier, which represent curved lines instead of straight ones.

new LineSegment()
Instance Members
▸ getStart()
▸ setStart(Point)
▸ getEnd()
▸ setEnd(Point)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

CubicBezier

A Cubic Bézier smooth curve.

In order to be able to represent smooth curves the “layout” package defines the class CubicBezier. It represents a Bezier curve, and is readily available in most graphics APIs. The class CubicBezier is derived from LineSegment. It consists of four elements: the two inherited elements 'start' and 'end', which specify the starting point and the endpoint of the cubic bezier curve, and two elements 'basePoint1' and 'basePoint2', which specify the two additional base points that are needed to describe a cubic bezier curve.

new CubicBezier()
Instance Members
▸ getBasePoint1()
▸ setBasePoint1(p)
▸ getBasePoint2()
▸ setBasePoint2(p)
▸ getStart()
▸ setStart(Point)
▸ getEnd()
▸ setEnd(Point)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Curve

A curve connecting elements in a diagram.

The Curve class describes how to connect elements in a diagram defined with the use of the “layout” package. A curve is fully specified by a mandatory listOfCurveSegments element and is used in four places in the “layout” package:

  • SpeciesReferenceGlyph: Here it describes a curve from/to the center piece of the parent ReactionGlyph to/from the SpeciesGlyph it represents.

  • ReactionGlyph: Here it describes a curve for the center piece of a reaction.

  • ReferenceGlyph: Here it describes a curve from/to the center piece of the parent GeneralGlyph to/from the glyph it represents.

  • GeneralGlyph: Here it describes a curve for the center piece of an additional relationship.

In the text above, the term 'center piece' refers to either the Curve element of a ReactionGlyph, or its BoundingBox.

new Curve()
Instance Members
▸ createCubicBezier()
▸ createLineSegment()
▸ getNumCurveSegments()
▸ getCurveSegment(index)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ getPlugin(n)
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Layout

The layout of a diagram of an SBML model.

The Layout class stores layout information for some or all elements of the SBML model as well as additional objects that need not be connected to the model. The Layout has two attributes: id and name. Additionally, a Dimensions element specifies the size of the layout. The actual layout elements are contained in several lists, namely: a ListOfCompartmentGlyphs, a ListOfSpeciesGlyphs, a ListOfReactionGlyphs, a ListOfTextGlyphs, and a ListOfAdditionalGraphicalObjects. Each of these lists can only occur once, and, if present, are not allowed to be empty.

new Layout()
Instance Members
▸ getDimensions()
▸ setDimensions()
▸ createAdditionalGraphicalObject()
▸ createCompartmentGlyph()
▸ createCubicBezier()
▸ createGeneralGlyph()
▸ createLineSegment()
▸ createReactionGlyph()
▸ createSpeciesGlyph()
▸ createSpeciesReferenceGlyph()
▸ createTextGlyph()
▸ getNumAdditionalGraphicalObjects()
▸ getNumCompartmentGlyphs()
▸ getNumGeneralGlyphs()
▸ getNumReactionGlyphs()
▸ getNumSpeciesGlyphs()
▸ getNumTextGlyphs()
▸ getAdditionalGraphicalObject(n)
▸ getCompartmentGlyph(n)
▸ getGeneralGlyph(n)
▸ getReactionGlyph(n)
▸ getSpeciesGlyph()
▸ getTextGlyph(n)
▸ removeAdditionalGraphicalObject(n)
▸ removeCompartmentGlyph(n)
▸ removeReactionGlyph(n)
▸ removeSpeciesGlyph()
▸ removeSpeciesReferenceGlyph(id)
▸ removeTextGlyph(n)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Dimensions

Spatial dimensions of a 2D or 3D shape.

A dimension is specified via the required attributes width, height, and an optional attribute depth, all of which are of type double. If the attribute depth is not specified, the object is a two dimensional object. The width attribute of Dimensions specifies the size of the object in the direction of the positive x axis, the height attribute specifies the size of the object along the positive y axis and the depth attribute specifies the size of the object along the positive z axis. All sizes for Dimensions objects are positive values, and so the attributes are not allowed to take negative values. The Dimensions class also has an optional attribute id of type SId. While not used in the “layout” package, it can be used by programs to refer to the elements.

new Dimensions()
Instance Members
▸ Dimensions(the, w, h, d)
▸ setWidth(w)
▸ setHeight(h)
▸ setDepth(d)
▸ getWidth()
▸ getHeight()
▸ getDepth()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Point

Representation of a point.

A point is specified via the required attributes 'x', 'y' and an optional attribute 'z', all of which are of type double. If the attribute z is not specified, the object is a two dimensional object. The Point class also has an optional attribute id of type SId. While not used in the "layout" package, it can be used by programs to refer to the elements.

new Point()
Instance Members
▸ Point(layoutns, x, y)
▸ setX(x)
▸ setY(y)
▸ setZ(z)
▸ setXOffset(x)
▸ setYOffset(y)
▸ setZOffset(y)
▸ x()
▸ y()
▸ z()
▸ getXOffset()
▸ getYOffset()
▸ getZOffset()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

BoundingBox

A bounding box for an item in a diagram.

new BoundingBox()
Instance Members
▸ BoundingBox()
▸ getDimensions()
▸ setDimensions(d)
▸ getPosition()
▸ setPosition(p)
▸ setX(x)
▸ setY(y)
▸ setZ(z)
▸ x()
▸ y()
▸ z()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

GraphicalObject

Base class of objects that store layouts.

All the more specific layout elements (CompartmentGlyph, GeneralGlyph, SpeciesGlyph, ReactionGlyph, ReferenceGlyph, TextGlyph, and SpeciesReferenceGlyph) are derived from the class GraphicalObject. Each object of class GraphicalObject has a mandatory BoundingBox, which specifies the position and the size of the object. While GraphicalObject is the base class for most elements in the “layout” package, it is not an abstract class. It can be instantiated when used in the listOfAdditionalGraphicalObjects to describe additional elements and relationships. Since it only describes a BoundingBox, programs are encouraged to add Annotation objects that describe program-specific graphical information.

new GraphicalObject()
Instance Members
▸ getBoundingBox()
▸ setBoundingBox(bb)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

CompartmentGlyph

A glyph for an SBML compartment.

new CompartmentGlyph()
Instance Members
▸ getCompartmentId()
▸ setCompartmentId(id)
▸ isSetCompartmentId()
▸ getOrder()
▸ setOrder(order)
▸ unsetOrder()
▸ isSetOrder()
▸ getBoundingBox()
▸ setBoundingBox(bb)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

GeneralGlyph

A glyph for miscellaneous items.

The GeneralGlyph is used to facilitate the representation of elements other than Compartment, Species and Reaction and thus can be used for the display of relationships of Rule or elements defined by other SBML packages. It closely follows the structure of the ReactionGlyph. GeneralGlyph is defined to have an optional attribute reference as well as the elements curve, listOfReferenceGlyphs and listOfSubGlyphs.

new GeneralGlyph()
Instance Members
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

ReactionGlyph

A glyph for an SBML reaction.

Analogous to how a Reaction object has to at least have one reactant or product, the ReactionGlyph has to at least have one SpeciesReferenceGlyph stored in the ListOfSpeciesReferenceGlyphs. Figure 12 on the following page provides the UML diagram for the class definition. The ReactionGlyph inherits from GraphicalObject. In addition to the attributes inherited from GraphicalObject, the ReactionGlyph is described by an attribute reaction, a Curve element and a listOfSpeciesReferenceGlyphs element. The Curve describes the center section of a ReactionGlyph. The center section is frequently used by tools to separate the point where substrates arcs come together, from the point where product arcs split off. The Curve is optional, and when not present the dimensions of the inherited BoundingBox describes the center section, by storing its position and dimension.

new ReactionGlyph()
Instance Members
▸ getReactionId()
▸ setReactionId(id)
▸ isSetReactionId()
▸ getNumSpeciesReferenceGlyphs()
▸ getSpeciesReferenceGlyph()
▸ createSpeciesReferenceGlyph()
▸ createLineSegment()
▸ createCubicBezier()
▸ getCurve()
▸ setCurve()
▸ isSetCurve()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

SpeciesGlyph

A glyph for an SBML species.

In addition to the attributes it inherits from GraphicalObject, the SpeciesGlyph object has an optional 'species' attribute.

new SpeciesGlyph()
Instance Members
▸ getSpeciesId()
▸ setSpeciesId(id)
▸ isSetSpeciesId()
▸ getBoundingBox()
▸ setBoundingBox(bb)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

SpeciesReferenceGlyph

A glyph for an SBML species reference.

The SpeciesReferenceGlyph element describes the graphical connection between a SpeciesGlyph and a ReactionGlyph (which would be an arrow or some curve in most cases). A SpeciesReferenceGlyph inherits from GraphicalObject, and adds a mandatory attribute 'speciesGlyph' and two optional attributes 'speciesReference' and 'role'. Optionally, the SpeciesReferenceGlyph also has a child element 'curve'.

If the curve is specified, it overrides the inherited bounding box.

new SpeciesReferenceGlyph()
Instance Members
▸ createCubicBezier()
▸ createLineSegment()
▸ getCurve()
▸ isSetCurve()
▸ getSpeciesGlyphId()
▸ setSpeciesGlyphId()
▸ getSpeciesReferenceId()
▸ setSpeciesReferenceId()
▸ getRole()
▸ getRoleString()
▸ setRole()
▸ isSetSpeciesGlyphId()
▸ isSetSpeciesReferenceId()
▸ isSetRole()
▸ getBoundingBox()
▸ setBoundingBox(bb)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

TextGlyph

A glyph for a text label.

The TextGlyph class describes the position and dimension of text labels in the “layout” package. It inherits from GraphicalObject and adds the attributes graphicalObject, text and originOfText.

new TextGlyph()
Instance Members
▸ getText()
▸ setText(t)
▸ isSetText()
▸ getGraphicalObjectId()
▸ setGraphicalObjectId()
▸ getOriginOfTextId()
▸ setOriginOfTextId()
▸ isSetOriginOfTextId()
▸ isSetGraphicalObjectId()
▸ getBoundingBox()
▸ setBoundingBox(bb)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

LayoutModelPlugin

Plugin subclass for the layout extension.

new LayoutModelPlugin()
Instance Members
▸ createLayout()
▸ getNumLayouts()
▸ getLayout(index)
▸ getListOfLayouts()

LayoutExtension

The layout extension.

new LayoutExtension()
Static Members
▸ getXmlnsL2()
▸ getXmlnsL3V1V1()

getXmlnsL3V1V1

Returns URI of supported versions of this package.

getXmlnsL3V1V1()

FluxBound

Max or min value for a reaction flux.

The FluxBound class of objects is used in Version 1 of the SBML Level 3 fbc ("fbc") package to express a single (in)equality that provides the maximum or minimum value that a reaction flux can obtain at steady state. (This same information is encoded differently in Version 2 of "fbc"; see the "upperFluxBound" and "lowerFluxBound" attributes on FbcReactionPlugin.)

Attributes on FluxBound

In addition to the common optional attributes "id" and "name", FluxBound takes three required attributes: "reaction", "operation" and "value". These three attributes define the meaning of the FluxBound, and are interpreted using the following expression:

reaction operator value

The "reaction" attribute takes a value of SIdRef. The value must be the identifier of a Reaction object defined within the enclosing model.

The "operation" attribute takes a value from FluxBoundOperation_t representing different mathematical inequalities. Possible values for "operation" include greaterEqual, equal, and others.

The "value" attribute takes a numerical value of type double, and represents the value of the flux bound. The permitted values include positive infinity (INF) and negative infinity (-INF).

The following is an example of a set of flux bounds encoded in this form; it also demonstrates the use of ListOfFluxBounds.

<fbc:listOfFluxBounds>
    <fbc:fluxBound fbc:id="R1b" fbc:reaction="R1" fbc:operation="greaterEqual" fbc:value="1.2"/>
    <fbc:fluxBound fbc:id="R2b" fbc:reaction="R2" fbc:operation="lessEqual" fbc:value="-1.2"/>
    <fbc:fluxBound fbc:id="R3b" fbc:reaction="R3" fbc:operation="greaterEqual" fbc:value="-INF"/>
    <fbc:fluxBound fbc:id="R4b" fbc:reaction="R4" fbc:operation="lessEqual" fbc:value="INF"/>
    <fbc:fluxBound fbc:id="R5b" fbc:reaction="R5" fbc:operation="equal" fbc:value="1"/>
</fbc:listOfFluxBounds>

Note: This class is only defined for Version 1 of the "fbc" package specification. It was replaced in Version 2 by a Parameter referenced by the "upperFluxBound" or "lowerFluxBound" attributes on an FbcReactionPlugin. FluxBound is therefore not used for Version 2 "fbc" models.

new FluxBound()
Instance Members
▸ getReaction()
▸ isSetReaction()
▸ setReaction()
▸ unsetReaction()
▸ getOperation()
▸ getFluxBoundOperation()
▸ isSetOperation()
▸ setOperation(operation)
▸ unsetOperation()
▸ getValue()
▸ isSetValue()
▸ setValue(value)
▸ unsetValue()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Objective

An objective function.

An integral component in a complete description of a steady-state model is the so-called objective function, which generally consists of a linear combination of model variables (fluxes) and a sense (direction). In the SBML Level 3 fbc ("fbc") package, this concept is succinctly captured in the Objective class.

The Objective class is derived from the normal SBML SBase class and inherits the "metaid" and "sboTerm" attributes, as well as the subcomponents for Annotation and Notes. To these, the Objective class adds an optional attribute named "type". The type attribute can take one of two literal values: "maximize" or "minimize". The values represent the sense of the optimality constraint for the FBC model.

The "fbc" package allows for the definition of multiple model objectives, with one being designated as active. The active objective is indicated using the attribute "activeObjective" on the ListOfObjectives object. Here is an example of the XML encoding of a model with a list of objective functions:

<fbc:listOfObjectives fbc:activeObjective="obj1"> <fbc:objective fbc:id="obj1" fbc:type="maximize"> <fbc:listOfFluxObjectives> <fbc:fluxObjective fbc:reaction="R101" fbc:coefficient="1"/> </fbc:listOfFluxObjectives> </fbc:objective> <fbc:objective fbc:id="obj2" fbc:type="minimize"> <fbc:listOfFluxObjectives> <fbc:fluxObjective fbc:reaction="R102" fbc:coefficient="-2.5"/> <fbc:fluxObjective fbc:reaction="R103" fbc:coefficient="1"/> </fbc:listOfFluxObjectives> </fbc:objective> </fbc:listOfObjectives>

new Objective()
Instance Members
▸ getFluxObjective(n)
▸ addFluxObjective(fo)
▸ getNumFluxObjectives()
▸ createFluxObjective()
▸ removeFluxObjective(n)
▸ getType()
▸ isSetType()
▸ setType(type)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

FluxObjective

An objective function for a flux.

An integral component in a complete description of a steady-state model is the so-called objective function, which generally consists of a linear combination of model variables (fluxes) and a sense (direction). In the SBML Level 3 fbc ("fbc") package, this concept is succinctly captured in the Objective class. An Objective object includes a list of flux objectives, each in the form of a FluxObjective object.

The FluxObjective class is a relatively simple container for a model variable weighted by a signed linear coefficient. In addition to the common SBML object attributes of "id" and "name" (both of which are optional), it adds two required attributes: "reaction" and "coefficient".

The "reaction" attribute must have a value of type SIdRef, and its value is restricted to the identifier of a Reaction object in the model. The "reaction" attribute identifiers the reaction to which the FluxObjective applies. The "coefficient" attribute must have a value of type double, and refers to the coefficient that this FluxObjective takes in the enclosing Objective. Its unit of measurement is dimensionless. The meaning of these two attributes together is given by the formula coefficient times; reaction-flux. Since reactions in SBML Level 3 are in units of extent, the units of a flux objective are thus extent per time.

The following example illustrates the use of these attributes:

<fbc:listOfObjectives fbc:activeObjective="obj1">
 <fbc:objective fbc:id="obj1" fbc:type="maximize">
  <fbc:listOfFluxObjectives>
   <fbc:fluxObjective fbc:reaction="R1" fbc:coefficient="1"/>
   <fbc:fluxObjective fbc:reaction="R2" fbc:coefficient="2"/>
  </fbc:listOfFluxObjectives>
 </fbc:objective>
</fbc:listOfObjectives>
new FluxObjective()
Instance Members
▸ getReaction()
▸ getCoefficient()
▸ isSetReaction()
▸ isSetCoefficient()
▸ setReaction(reaction)
▸ setCoefficient(coefficient)
▸ unsetReaction()
▸ unsetCoefficient()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

FbcAnd

An "and" relationship for gene products

FbcAnd class is used in Version 2 of the SBML Level 3 fbc ("fbc") package to represent an "and" relationship between two or more child FbcAssociation objects. In other words, it indicates that all of the child objects are included. Note that since the FbcAssociation class is the parent class of GeneProductRef, FbcAnd and FbcOr, a given FbcAnd can potentially include nested "and"/"or" combinations of gene products.

new FbcAnd()
Instance Members
▸ getAssociation(n)
▸ addAssociation(fa)
▸ getNumAssociations()
▸ toInfix()
▸ createAnd()
▸ createOr()
▸ createGeneProductRef()
▸ removeAssociation(n)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

FbcOr

new FbcOr()
Instance Members
▸ getAssociation(n)
▸ addAssociation(fa)
▸ getNumAssociations()
▸ toInfix(usingId)
▸ createAnd()
▸ createOr()
▸ createGeneProductRef()
▸ removeAssociation(n)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

FbcAssociation

Base class for FbcAnd, FbcOr, and GeneProductRef

The FbcAssociation class is the abstract base class for the classes that can be used as children of the GeneProductAssociation child of a Reaction. The FbcAnd class is used when all of its children are definitely associated with the Reaction; the FbcOr class is used when at least one of its children are associated with the Reaction; and the GeneProductRef class is used to denote a particular GeneProduct.

new FbcAssociation()
Static Members
▸ parseFbcInfixAssociation(association, plugin, usingId, addMissingGP)
Instance Members
▸ isFbcAnd()
▸ isFbcOr()
▸ isGeneProductRef()
▸ toInfix()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

GeneProduct

Association of a gene product with a Reaction

In the SBML Level 3 @ref fbc (“fbc”) package representation format, a GeneProduct object represents a single gene or implied gene product. The gene or gene product is identified using the required attribute "label", which is a text string. (This attribute is separate from the usual SBML "id" attribute, which is used to cross-reference entities within an SBML model.) A GeneProduct object can also possess an optional "associatedSpecies" attribute; if this a attribute is defined, it should have a value of type SIdRef and be the identifier of a Species object defined in the enclosing Model. An "associatedSpecies", if it exists, is interpreted to be a species associated with the gene or gene product that is represented by the GeneProduct object.

new GeneProduct()
Instance Members
▸ getLabel()
▸ getAssociatedSpecies()
▸ isSetLabel()
▸ isSetAssociatedSpecies()
▸ setLabel(label)
▸ setAssociatedSpecies(associatedSpecies)
▸ unsetLabel()
▸ unsetAssociatedSpecies()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

GeneProductAssociation

Association between gene products and reactions

In Version 2 of the SBML Level 3 fbc ("fbc") package specification, GeneProductAssociation is a class derived from SBase used to associate one more genes or gene products with reactions. GeneProductAssociation objects are essentially containers, with one such container optionally attached as a subelement to a Reaction object in a model. The container can contain one of three kinds of objects, all of which are subclasses of the libSBML parent class FbcAssociation. (Note that this class is named Association in the "fbc" Version 2 specification, but in libSBML is named FbcAssociation to avoid a name conflict with an existing class.)

One of the kinds of FbcAssociation subclasses that can appear in a GeneProductAssociation is GeneProductRef. This class of objects references a GeneProduct declared in a ListOfGeneProducts attached to the enclosing Model object. In the "fbc" approach, when more than one gene (or gene product) is present in an association, they are written as logical expressions using Boolean logical operators and and or through the classes (in libSBML) FbcAnd and FbcOr. (In the "fbc" Version 2 specification, these are simply named And and Or, respectively.) The FbcAnd and FbcOr objects in turn can contain either GeneProductRef objects or other FbcAnd and/or FbcOr objects.

Here is a concrete example of what the XML representation of a simple or relationship might look like: <reaction id = "R_ABTA" ... rest of Reaction declaration elided for this example ...> <fbc:geneProductAssociation fbc:id="ga_16"> <fbc:or> <fbc:geneProductRef fbc:geneProduct="g_b2662"/> <fbc:geneProductRef fbc:geneProduct="g_b1302"/> </fbc:or> </fbc:geneProductAssociation>

new GeneProductAssociation()
Instance Members
▸ getAssociation()
▸ createAnd()
▸ createOr()
▸ createGeneProductRef()
▸ isSetAssociation()
▸ setAssociation(association)
▸ unsetName()
▸ unsetAssociation()

GeneProductRef

Reference to a gene product of a reaction

GeneProductRef encodes a references to a GeneProduct object declared in a ListOfGeneProducts attached to the enclosing Model object. GeneProductRef is derived from the FbcAssociation class.

GeneProductRef objects are used to construct the content of GeneProductAssociation objects. As described more fully in the documentation of the latter, a GeneProductAssociation is a container that may contain either (i) a single GeneProductRef or (ii) a logical expression built up with FbcAnd and FbcOr and ultimately containing two or more GeneProductRef objects.

new GeneProductRef()
Instance Members
▸ getGeneProduct()
▸ toInfix()
▸ isSetGeneProduct()
▸ setGeneProduct(geneProduct)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

FbcSpeciesPlugin

new FbcSpeciesPlugin()
Instance Members
▸ getCharge()
▸ getChemicalFormula()
▸ isSetCharge()
▸ isSetChemicalFormula()
▸ setCharge(charge)
▸ setChemicalFormula(chemicalFormula)
▸ unsetCharge()
▸ unsetChemicalFormula()
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

FbcReactionPlugin

Extension of Reaction by the "fbc" package.

The FbcReactionPlugin class inherits from the SBasePlugin class, and codifies the extentions to the Reaction class defined in the @ref fbc package ("fbc"). This extention allows the modeler to define (in Version 2 of the "fbc" package) an upper and lower flux bound, with the 'upperFluxBound' and 'lowerFluxBound' attributes, as well as a way to reference any GeneProduct associated with this Reaction, through the GeneProductAssociation child.

new FbcReactionPlugin()
Instance Members
▸ getGeneProductAssociation()
▸ isSetGeneProductAssociation()
▸ setGeneProductAssociation(geneProductAssociation)
▸ createGeneProductAssociation()
▸ getLowerFluxBound()
▸ getUpperFluxBound()
▸ isSetLowerFluxBound()
▸ isSetUpperFluxBound()
▸ setLowerFluxBound(lowerFluxBound)
▸ setUpperFluxBound(upperFluxBound)
▸ unsetLowerFluxBound()
▸ unsetUpperFluxBound()
▸ unsetGeneProductAssociation()
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

FbcModelPlugin

Extension of Model.

The FbcModelPlugin object is used to extend the standard SBML Model object with features used in the SBML Level 3 fbc ("fbc") package. In Version 1 of the "fbc" specification, the extended Model class has two optional subobjects: ListOfObjectives and ListOfFluxBounds. In Version 2 of the specification, the extended Model object is defined differently: it is extended with a new required attribute named "strict", and the two optional subobjects ListOfObjectives and ListOfGeneProducts. (ListOfFluxBounds is not used in Version 2.)

The "strict" attribute on the (extended) Model class

The mandatory attribute "strict", of type boolean, in Version 2 of this package, is used to apply an additional set of restrictions to the model. The "strict" attribute helps ensure that the Flux Balance Constraints package can be used to encode legacy flux-balance analysis models expressible as Linear Programs (LP's) for software that is unable to analyze arbitrary mathematical expressions that may appear in an SBML model. In addition, a "strict" model is fully described and mathematically consistent, for example, by ensuring that all fluxes have a valid upper or lower bound.

The following restrictions are in effect if an "fbc" model object has a value of true for the attribute "strict" on Model:

  • Each Reaction in a Model must define values for the attributes "lowerFluxBound" and "upperFluxBound", with each attribute pointing to a valid Parameter object defined in the current Model.

  • Each Parameter object referred to by the Reaction attributes "lowerFluxBound" and "upperFluxBound" must have its "constant" attribute set to the value true and its "value" attribute set to a value of type double. This value may not be NaN.

  • SpeciesReference objects in Reaction objects must have their "stoichiometry" attribute set to a double value that is not NaN, nor -INF, nor INF. In addition, the value of their "constant" attribute must be set to true.

  • InitialAssignment objects may not target the Parameter objects referenced by the Reaction attributes "lowerFluxBound" and "upperFluxBound", nor any SpeciesReference objects.

  • All defined FluxObjective objects must have their coefficient attribute set to a double value that is not NaN, nor -INF, nor INF.

  • A Reaction "lowerFluxBound" attribute may not point to a Parameter object that has a value of INF.

  • A Reaction "upperFluxBound" attribute may not point to a Parameter object that has a value of -INF.

  • For all Reaction objects, the value of a "lowerFluxBound" attribute must be less than or equal to the value of the "upperFluxBound" attribute.

While it is not compulsory for a "strict" Flux Balance Constraints model to define an Objective, doing so does does allow the model to be formulated as a Linear Program and optimized. However, this decision is left to the modeler. Note that all other properties of the objects referred to in the list above are to be set as specified in the relevant SBML Level 3 Version 1 Core and fbc ("fbc") specifications.

Alternatively, if the value of the strict attribute is false, then none of these restrictions apply and the model creator can choose to define "fbc" models that are not necessarily encodable as an LP. For example, if strict is false, the InitialAssignment construct may be used to set any valid numerical entity, including Parameter values and stoichiometric coefficients, with any value of type double. In addition, Parameter elements are no longer required to be flagged as constant, thus allowing for a Flux Balance Constraints model's use in alternative, hybrid modeling strategies.

Lists of subobjects on the (extended) Model class

The ListOfObjectives is used to define the objectives of a given "fbc" model. Objectives generally consist of linear combinations of model variables (fluxes) and a direction for the optimality constraint (either maximization or minimization). Each Objective has a ListOfFluxObjectives subobjects.

In Version 2 of "fbc", the ListOfGeneProducts is used to define the gene products represented by the "fbc" model.

In Version 1 of "fbc", there is no ListOfGeneProducts, and instead, Model can have an optional ListOfFluxBounds.

See Objective, FluxObjective, FluxBound

new FbcModelPlugin()
Instance Members
▸ getStrict()
▸ setStrict(strict)
▸ isSetStrict()
▸ unsetStrict()
▸ getFluxBound(n)
▸ addFluxBound(bound)
▸ createFluxBound()
▸ removeFluxBound(n)
▸ getNumFluxBounds()
▸ getObjective(n)
▸ addObjective(o)
▸ getNumObjectives()
▸ createObjective()
▸ removeObjective(n)
▸ getActiveObjective()
▸ setActiveObjectiveId()
▸ getActiveObjectiveId()
▸ unsetActiveObjectiveId()
▸ getGeneProduct(n)
▸ getGeneProductByLabel(label)
▸ addGeneProduct(gp)
▸ getNumGeneProducts()
▸ createGeneProduct()
▸ removeGeneProduct(n)
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

FbcExtension

Base extension class for the "fbc" package.

There are currently two possible namespaces defined for the Flux Balance Constraints package: "http://www.sbml.org/sbml/level3/version1/fbc/version1" and "http://www.sbml.org/sbml/level3/version1/fbc/version2". Despite both referencing SBML Level 3 Version 1 explicitly, both versions of this package (and all such packages) can be used without change in SBML Level 3 Version 2 documents. The only caveat is that features of the SBML Level 3 Version 2 specification that were not present in Level 1 may not be used by constructs from the Flux Balance Constraints package.

new FbcExtension()
Static Members
▸ getXmlnsL3V1V1()
▸ getXmlnsL3V1V2()

Group

Representation of a group of SBML components.

The Group class is the first and most central class in the SBML Level 3 Groups package. This class represents a group of entities: a simple mechanism for indicating that particular components of an SBML model are related in some way. The nature of the relationship is left up to the modeler, and can be clarified by means of annotations on model components. Groups may contain either the same or different types of SBML objects, and groups may be nested if desired. There are no predefined modeling or mathematical semantics associated with groups.

The Groups class has one required attribute, "kind"; two optional attributes, "id" and "name"; and a single child element, ListOfMembers. The membership of a group is determined by the contents of the list of members stored in Member objects within the ListOfMembers child of a Group object. Since the Group class of objects is derived from SBase, and SBase provides the ability to attach SBO terms as well as MIRIAM annotations, the semantics of a given group in a model can be made more precise using references to external controlled vocabularies and ontologies.

Group kinds

The attribute "kind" on Group is used to indicate the nature of the group defined by a Group instance. The "kind" attribute must always have one of the following three possible values:

  • "classification": The group represents a class, and its members have an is-a relationship to the group. For example, the group could represent a type of molecule such as ATP, and the members could be species located in different compartments, thereby establishing that the species are pools of the same molecule in different locations.

  • "partonomy": The group represents a collection of parts, and its members have a part-of relationship to the group. For example, the group could represent a cellular structure, and individual compartments could be made members of the group to indicate they represent subparts of that cellular structure.

  • "collection": The grouping is merely a collection for convenience, without an implied relationship between the members. For example, the group could be used to collect together multiple disparate components of a model—species, reactions, events—involved in a particular phenotype, and apply a common annotation rather than having to copy the same annotation to each component individually.

In the libSBML API for Groups, these possible values for the "kind" attribute are programmatically represented as constants so that callers will not normally need to deal with text string values. The following are the constants defined for the three values of "kind" (plus an additional constant to represent unrecognized values):

  • libsbml.GROUP_KIND_CLASSIFICATION

  • libsbml.GROUP_KIND_PARTONOMY

  • libsbml.GROUP_KIND_COLLECTION

  • libsbml.GROUP_KIND_UNKNOWN

    Groups and their members

If an SBML element is referenced by a Group's child Member (directly or indirectly), it is considered to be a member of that Group. If the same element is referenced by multiple Member objects, this is equivalent to including it just once. (It is considered best practice to avoid this, but does not make for an invalid SBML document.)

Children of referenced elements are not considered to be members of the Group: a KineticLaw of a referenced Reaction is not itself a Group member. Even the membership of so-called SBML container classes (e.g., ListOfSpecies, ListOfCompartments, etc.) does not imply inclusion of children as members of the Group. The sole exception to this rule is the handling of ListOfMembers class. See the libSBML C++ documentation for more info.

new Group()
Instance Members
▸ getKind()
▸ getKindAsString()
▸ isSetKind()
▸ setKind(value)
▸ getMember(n)
▸ getMemberByIdRef(sid)
▸ addMember(m)
▸ createMember()
▸ removeMember(n)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Member

The Member class defines what objects are parts of a Group.

The Member class has four optional attributes: id and name, which identify the element, and idRef and metaIdRef which reference the identifiers of other elements. There must be exactly one (and only one) method used to reference another element: either idRef or metaIdRef may be defined, but not both. (Multiple attributes are needed to account for the different types of identifiers that a given object may have.) The referenced object (including, potentially, another Group object) is thus made a member of the group in which the Member object is contained.

Since Member is derived from SBase and, as mentioned above, SBase provides both the ability to attach SBO terms as well as MIRIAM annotations, the semantics of a given member in a model can be made more precise by reference to external controlled vocabularies and ontologies.

new Member()
Instance Members
▸ getIdRef()
▸ getMetaIdRef()
▸ isSetIdRef()
▸ isSetMetaIdRef()
▸ setIdRef(idRef)
▸ setMetaIdRef(metaIdRef)
▸ unsetIdRef()
▸ unsetMetaIdRef()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

GroupsModelPlugin

Extension of Model.

new GroupsModelPlugin()
Instance Members
▸ getGroup(n)
▸ addGroup(g)
▸ getNumGroups()
▸ createGroup()
▸ removeGroup(n)
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

GroupsSBMLDocumentPlugin

Extension of SBMLDocument.

This class extends SBMLDocumentPlugin, a class that is used by libSBML plugins as part of their implementation of SBML Level 3 packages.

new GroupsSBMLDocumentPlugin()
Instance Members
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

GroupsExtension

Base extension class for the package.

This is the Groups package extension of the SBMLExtension class that is used to facilitate libSBML plug-ins in the implementation of an SBMLLevel 3 package.

new GroupsExtension()
Static Members
▸ getXmlnsL3V1V1()

MultiASTPlugin

Extension of ASTBasePlugin.

The MultiASTPlugin object is used to extend the standard SBML AST (abstract syntax tree) base object (ASTBase) to allow a "ci" element (libsbml.AST_NAME) to have an optional "speciesReference" attribute. This attribute is used to distinguish which version of a Species should be used in the mathematics. If a "template" type Species appears as both a reactant and a product in the same Reaction, for example, it may have one amount as a reactant and a different amount as a product, since the same template is being used to match slightly different pools of elements in each case. By defining the "speciesReference" attribute on an libsbml.AST_NAME that references that Species, the modeler may determine which amount is being referenced. Similarly, an libsbml.AST_NAME node may reference a SpeciesFeature that appears in multiple Species in the Reaction, and this attribute can be used to specify which one should be used.

new MultiASTPlugin()
Instance Members
▸ getSpeciesReference()
▸ isSetSpeciesReference()
▸ setSpeciesReference()
▸ unsetSpeciesReference()
▸ getRepresentationType()
▸ isSetRepresentationType()
▸ setRepresentationType(representationType)
▸ unsetRepresentationType()
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

MultiCompartmentPlugin

Extension of Compartment for the "multi" package.

The MultiCompartmentPlugin object is used to extend the standard SBML Compartment base object with an optional "compartmentType" attribute, a required "isType" Boolean attribute, and a child ListOfCompartmentReferences. The "isType" attribute flags whether this Compartment should be treated as a standard SBML Compartment (if false), or as a more generic rule-based "type" of Compartment (if true). A compartment "type" is a template (in the sense of prototype) for all Compartment objects referencing it (via "compartmentType" attributes). A Species object directly referencing a compartment type is not a "fully defined" species, but rather a "template" species. If the value of the "isType" attribute is false, the Compartment object is a "not-a-type" compartment, and it is similar to a SBML core Compartment except it can reference a compartment type and can have a ListOfCompartmentReferences child. Each child CompartmentReference in the ListOfCompartmentReferences defines a subcompartment of the parent Compartment. The "compartmentType" attribute identifies this Compartment as the CompartmentType defined elsewhere in the Model. If the "compartmentType" attribute is set, the "isType" attribute must be true.

new MultiCompartmentPlugin()
Instance Members
▸ getCompartmentType()
▸ isSetCompartmentType()
▸ setCompartmentType(compartmentType)
▸ unsetCompartmentType()
▸ getIsType()
▸ isSetIsType()
▸ setIsType(isType)
▸ unsetIsType()
▸ getCompartmentReference(n)
▸ addCompartmentReference(compartmentReference)
▸ createCompartmentReference()
▸ removeCompartmentReference(n)
▸ getNumCompartmentReferences()
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

MultiSBMLDocumentPlugin

Extension of SBMLDocument for the "multi" package.

The MultiSBMLDocumentPlugin class inherits from the SBMLDocumentPlugin class, and codifies the extensions to the SBMLDocument class defined in the SBML Level 3 @ref multi ("multi") package. This extension defines a required flag named "required", which indicates whether "multi" constructs can be used to change the core mathematical interpretation of the Model defined in the SBML input. Since "multi" constructs can, this attribute must be set to the value "true".

new MultiSBMLDocumentPlugin()
Instance Members
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

MultiExtension

Base extension class for the package.

This is the Multistate, Multicomponent and Multicompartment Species package extension of the SBMLExtension class. This is a class that every libSBML plug-in must implement in order to implement an SBML Level 3 package.

There is currently exactly one namespace defined for the Multistate, Multicomponent and Multicompartment Species package: "http://www.sbml.org/sbml/level3/version1/multi/version1". Despite referencing SBML Level 3 Version 1 explicitly, this package (and all such packages) can be used without change in SBML Level 3 Version 2 documents. The only caveat is that features of the SBML Level 3 Version 2 specification that were not present in Level 1 may not be used by constructs from Level 1 packages. However, this restriction should not affect the 'multi' package.

new MultiExtension()
Static Members
▸ getXmlnsL3V1V1()

MultiListOfReactionsPlugin

Extension of ListOfReactions for the "multi" package.

The MultiListOfReactionsPlugin class extends the ListOfReactions class to allow a ListOfReactions to contain IntraSpeciesReaction objects as well as Reaction objects.

new MultiListOfReactionsPlugin()
Instance Members
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

MultiModelPlugin

Extension of Model.

The MultiModelPlugin object is used to extend the standard SBML Model object to allow a ListOfSpeciesTypes child.

new MultiModelPlugin()
Instance Members
▸ getMultiSpeciesType(n)
▸ addMultiSpeciesType(multiSpeciesType)
▸ createMultiSpeciesType()
▸ createBindingSiteSpeciesType()
▸ removeMultiSpeciesType(n)
▸ getNumMultiSpeciesTypes()
▸ createIntraSpeciesReaction()
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

MultiSimpleSpeciesReferencePlugin

Extension of SimpleSpeciesReference for the "multi" package.

The MultiSpeciesPlugin class extends the SimpleSpeciesReference class with a new optional attribute "compartmentReference", of type SIdRef, that points to a CompartmentReference. The compartmentReference attribute can serve to indicate in which subcompartment the SpeciesReference or ModifierSpeciesReference (which inherit from SimpleSpeciesReference) is located.

new MultiSimpleSpeciesReferencePlugin()
Instance Members
▸ getCompartmentReference()
▸ isSetCompartmentReference()
▸ setCompartmentReference(compartmentReference)
▸ unsetCompartmentReference()
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

MultiSpeciesPlugin

Extension of Species for the "multi" package.

The MultiSpeciesPlugin class extends the Species class to have a new attribute "speciesType", and two extra optional ListOfOutwardBindingSites and ListOfSpeciesFeatures children. A species may have a ListOfOutwardBindingSites child and/or a ListOfSpeciesFeatures child only when its speciesType attribute has been defined. The relationship among the elements of a ListOfOutwardBindingSites or a ListOfSpeciesFeatures is "and".

new MultiSpeciesPlugin()
Instance Members
▸ getSpeciesType()
▸ isSetSpeciesType()
▸ setSpeciesType(speciesType)
▸ unsetSpeciesType()
▸ getOutwardBindingSite(n)
▸ addOutwardBindingSite(outwardBindingSite)
▸ createOutwardBindingSite()
▸ removeOutwardBindingSite(n)
▸ getNumOutwardBindingSites()
▸ getSpeciesFeature(n)
▸ addSpeciesFeature(speciesFeature)
▸ createSpeciesFeature()
▸ removeSpeciesFeature(n)
▸ getSubListOfSpeciesFeatures(n)
▸ addSubListOfSpeciesFeatures(subListOfSpeciesFeatures)
▸ createSubListOfSpeciesFeatures()
▸ getNumSpeciesFeatures()
▸ getNumSubListOfSpeciesFeatures()
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

MultiSpeciesReferencePlugin

Extension of SpeciesReference for the "multi" package.

The MultiSpeciesReferencePlugin class inherits from the MultiSimpleSpeciesReferencePlugin class, and extends the SpeciesReference class to establish component mappings between the reactant species and the product species when the mappings cannot be inferred from the ids of the SpeciesTypeInstance objects. A MultiSpeciesReferencePlugin object defines an optional ListOfSpeciesTypeComponentMapInProducts child. Only a reaction product can contain the ListOfSpeciesTypeComponentMapInProducts child and it is not necessary to store the mappings again in the reactants.

new MultiSpeciesReferencePlugin()
Instance Members
▸ getSpeciesTypeComponentMapInProduct(n)
▸ addSpeciesTypeComponentMapInProduct(speciesTypeComponentMapInProduct)
▸ createSpeciesTypeComponentMapInProduct()
▸ removeSpeciesTypeComponentMapInProduct(n)
▸ getNumSpeciesTypeComponentMapInProducts()
▸ getCompartmentReference()
▸ isSetCompartmentReference()
▸ setCompartmentReference(compartmentReference)
▸ unsetCompartmentReference()
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

BindingSiteSpeciesType

Extension of MultiSpeciesType to define a binding site.

A BindingSiteSpeciesType inherits from MultiSpeciesType, and also is a child of the extended Model (via the MultiModelPlugin). A BindingSiteSpeciesType object defines a binding site, and therefore its instance can further define the bindingStatus attribute and can participate a binding internally and explicitly in an InSpeciesTypeBond object, or externally and implicitly defined by an OutwardBindingSite object. A binding site must be an atomic component which means that a BindingSiteSpeciesType object cannot contain a ListOfSpeciesTypeInstances subobject. Note: In the Multi package, a binding site can only participate in one binding at a time. That means a binding site cannot bind two partners at the same time. The binding relationship is one-to-one.

new BindingSiteSpeciesType()
Instance Members
▸ getCompartment()
▸ isSetCompartment()
▸ setCompartment(compartment)
▸ unsetCompartment()
▸ getSpeciesFeatureType(n)
▸ addSpeciesFeatureType(sft)
▸ getNumSpeciesFeatureTypes()
▸ createSpeciesFeatureType()
▸ removeSpeciesFeatureType(n)
▸ getSpeciesTypeInstance(n)
▸ addSpeciesTypeInstance(sti)
▸ getNumSpeciesTypeInstances()
▸ createSpeciesTypeInstance()
▸ removeSpeciesTypeInstance(n)
▸ getSpeciesTypeComponentIndex(n)
▸ addSpeciesTypeComponentIndex(stci)
▸ getNumSpeciesTypeComponentIndexes()
▸ createSpeciesTypeComponentIndex()
▸ removeSpeciesTypeComponentIndex(n)
▸ getInSpeciesTypeBond(n)
▸ addInSpeciesTypeBond(istb)
▸ getNumInSpeciesTypeBonds()
▸ createInSpeciesTypeBond()
▸ removeInSpeciesTypeBond(n)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

CompartmentReference

Child of a Compartment that references a different Compartment.

A CompartmentReference object is a child of an extended Compartment (via the MultiCompartmentPlugin), and provides a way for that Compartment to reference another Compartment, and indicates that the referenced Compartment is a sub-compartment in a composite parent compartment. Compartments may be arbitrarily nested in this way, but this nesting cannot be circular.

The ListOfCompartmentReferences is a container for CompartmentReference objects.

new CompartmentReference()
Instance Members
▸ getCompartment()
▸ isSetCompartment()
▸ setCompartment(compartment)
▸ unsetCompartment()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

InSpeciesTypeBond

Defines a bond within a MultiSpeciesType.

The InSpeciesTypeBond object is a child of MultiSpeciesType, and defines a bond existing within that MultiSpeciesType. The bond therefore exists in every species that references the MultiSpeciesType. The binding relationship in an InSpeciesTypeBond is one-to-one. The uniqueness of an InSpeciesTypeBond is ensured by the pair of referenced attributes "bindingSite1" and "bindingSite2", both of type SBaseRef. The referenced identifiers of the binding sites can be the ids of SpeciesTypeInstance objects (binding sites), or the ids of the SpeciesTypeComponentIndex objects indexing the binding sites and the ultimately referenced components must be the BindingSiteSpeciesType objects. Obviously, attributes "bindingSite1" and "bindingSite2" must not reference the same BindingSiteSpeciesType object.

new InSpeciesTypeBond()
Instance Members
▸ getBindingSite1()
▸ isSetBindingSite1()
▸ setBindingSite1(bindingSite1)
▸ unsetBindingSite1()
▸ getBindingSite2()
▸ isSetBindingSite2()
▸ setBindingSite2(bindingSite2)
▸ unsetBindingSite2()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

IntraSpeciesReaction

A subclass of Reaction for changes of an internal species bond.

An IntraSpeciesReaction is derived from Reaction for the reactions happening within a Species. A particular Reaction may happen within a Species as an IntraSpeciesReaction if the following conditions are fulfilled:

  • The Reaction is either an association reaction or a dissociation reaction.

  • If it is an association reaction, each of the two reactant Species has at least one OutwardBindingSite free ("unbound").

  • If it is a dissociation reaction, each of the two product Species has at least one OutwardBindingSite free ("unbound").

Note: Technically, transformations are also reactions happening with one Species, but they do not have the ambiguity of association and dissociation reactions. Therefore, a transformation reaction does not have to be defined as an IntraSpeciesReaction.

new IntraSpeciesReaction()
Instance Members
▸ getNumReactants()
▸ getNumProducts()
▸ getNumModifiers()
▸ getReactant(n)
▸ getProduct(n)
▸ getModifier(n)
▸ addReactant(sr)
▸ addProduct(sr)
▸ addModifier(msr)
▸ createReactant()
▸ createProduct()
▸ createModifier()
▸ removeReactant(n)
▸ removeProduct(n)
▸ removeModifier(n)
▸ createKineticLaw()
▸ getKineticLaw()
▸ setKineticLaw(kl)
▸ isSetKineticLaw()
▸ unsetKineticLaw()
▸ getReversible()
▸ setReversible(value)
▸ isSetReversible()
▸ unsetReversible()
▸ getCompartment()
▸ setCompartment(sid)
▸ isSetCompartment()
▸ unsetCompartment()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

OutwardBindingSite

Defines a outward-facing binding site for a MultiSpeciesType.

The OutwardBindingSite object is a child of a Species (via the MultiSpeciesPlugin). It has two optional attributes, "id" and "name", and two required attributes, "bindingStatus" and "component". A binding site not involved in any InSpeciesTypeBond object in the MultiSpeciesType referenced by a Species is an OutwardBindingSite. The bindingStatus attribute is of type {*nk BindingStatus_t}. The component attribute, of type SIdRef, references a component which ultimately references a BindingSiteSpeciesType object. The attribute value must be the identifier of a SpeciesTypeInstance, SpeciesTypeComponentIndex or MultiSpeciesType object. An OutwardBindingSite cannot be a binding site referenced by any InSpeciesTypeBond in the species. There are three scenarios for the component attribute to have the value of an identifier of MultiSpeciesType, SpeciesTypeInstance, or SpeciesTypeComponentIndex respectively:

  • When a Species references a simple BindingSiteSpeciesType, the value of the component attribute of the OutwardBindingSite of the Species can only be the id of the referenced MultiSpeciesType.
  • When a Species references a MultiSpeciesType with a SpeciesTypeInstance being a binding site (have an id of BindingSiteSpeciesType as its "speciesType" attribute) and the id of the SpeciesTypeInstance can identify the binding site within the MultiSpeciesType (referenced by the Species) unambiguously, and therefore, the value of the component attribute of an OutwardBindingSite of the species can be the id of the SpeciesTypeInstance.
  • When a Species references a MultiSpeciesType with a SpeciesTypeInstance being a binding site (directly or indirectly) and id of the SpeciesTypeInstance can NOT identify the binding site without ambiguity, an id of SpeciesTypeComponentIndex can be used as the value of the component attribute of an OutwardBindingSite of the Species.
new OutwardBindingSite()
Instance Members
▸ getBindingStatus()
▸ isSetBindingStatus()
▸ setBindingStatus(bindingStatus)
▸ unsetBindingStatus()
▸ getComponent()
▸ isSetComponent()
▸ setComponent(component)
▸ unsetComponent()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

PossibleSpeciesFeatureValue

Defines one value of a SpeciesFeature.

The PossibleSpeciesFeatureValue object is a child of a SpeciesFeatureType, and defines one value (though its optional "numericValue" attribute) which the parent SpeciesFeatureType can hold.

new PossibleSpeciesFeatureValue()
Instance Members
▸ getNumericValue()
▸ isSetNumericValue()
▸ setNumericValue(numericValue)
▸ unsetNumericValue()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

SpeciesFeature

Defines a feature of a multi Species.

Each SpeciesFeature object is a child of the MultiSpeciesPlugin, which extends the Species. Each defines one feature of the parent Species. It has three optional attributes, "id", "name" and "component", and two required attributes, "speciesFeatureType" and "occur", and a required child ListOfSpeciesFeatureValues. SpeciesFeature serves to define the state of a component in a species by selecting values from the ListOfPossibleSpeciesFeatureValues of the referenced SpeciesFeatureType. Its "speciesFeatureType" attribue references the particular SpeciesFeatureType of which this Species is an example. The "occur" attribute defines the number of instances of the referenced SpeciesFeatureType. The optional "component" attribute, of type SIdRef, can be used to indicate which component of a Species the SpeciesFeature belongs to, and is required when the component cannot be identified only based on the speciesFeatureType attribute. The ListOfSpeciesFeatureValues contain one or more SpeciesFeatureValue objects—if more than one, the relationship between them is "or", defining a list of mutually exclusive possibilities. Each SpeciesFeatureValue serves to specify a value for a SpeciesFeature to select from the ListOfPossibleSpeciesFeatureValues defined in the referenced SpeciesFeatureType.

new SpeciesFeature()
Instance Members
▸ SpeciesFeature(level, version, pkgVersion)
▸ getSpeciesFeatureType()
▸ isSetSpeciesFeatureType()
▸ setSpeciesFeatureType(speciesFeatureType)
▸ unsetSpeciesFeatureType()
▸ getOccur()
▸ isSetOccur()
▸ setOccur(occur)
▸ unsetOccur()
▸ getComponent()
▸ isSetComponent()
▸ setComponent(component)
▸ unsetComponent()
▸ getSpeciesFeatureValue(n)
▸ addSpeciesFeatureValue(sfv)
▸ getNumSpeciesFeatureValues()
▸ createSpeciesFeatureValue()
▸ removeSpeciesFeatureValue(n)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

SpeciesFeatureType

Defines a template for referencing SpeciesFeature objects.

The SpeciesFeatureType object is a child of a MultiSpeciesType, and serves to provide frameworks or templates to define the referencing SpeciesFeature objects. SpeciesFeatureType has two required attributes "id" and "occur", an optional attribute "name", and a required child ListOfPossibleSpeciesFeatureValues. The multiple PossibleSpeciesFeatureValue children of the ListOfPossibleSpeciesFeatureValues object permit constructing multistate species via its SpeciesFeature children of the ListOfSpeciesFeatures or SubListOfSpeciesFeatures object. The "occur" attribute is used to indicate the number of instances of the SpeciesFeatureType. This attribute can be used to infer the number of the instances in the "don"t care" state in a referencing SpeciesFeature.

new SpeciesFeatureType()
Instance Members
▸ getOccur()
▸ isSetOccur()
▸ setOccur(occur)
▸ unsetOccur()
▸ getPossibleSpeciesFeatureValue(n)
▸ addPossibleSpeciesFeatureValue(psfv)
▸ getNumPossibleSpeciesFeatureValues()
▸ createPossibleSpeciesFeatureValue()
▸ removePossibleSpeciesFeatureValue(n)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

SpeciesFeatureValue

Defines a particular value for a SpeciesFeature.

The SpeciesFeatureValue object is a child of a SpeciesFeature, and serves to specify a value for a SpeciesFeature to select from the ListOfPossibleSpeciesFeatureValues defined in the SpeciesFeatureType referenced by the parent SpeciesFeature.

new SpeciesFeatureValue()
Instance Members
▸ getValue()
▸ isSetValue()
▸ setValue(value)
▸ unsetValue()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

MultiSpeciesType

A type of Species in SBML Level 3 "multi"

The MultiSpeciesType class (defined simply as SpeciesType in the SBML Level 3 "multi" specification, but called MultiSpeciesType here to distinguish it from the SpeciesType class defined in SBML Level 2), is a child of the extended Model object (via the MultiModelPlugin class). It defines "id" and "name" attributes, an optional "compartment" attribute for indicating which Compartment the referencing Species is in, and four optional lists for child SpeciesFeatureType, SpeciesTypeInstance, SpeciesTypeComponentIndex, and InSpeciesTypeBond objects. Together those children define the species type. The ListOfSpeciesTypeInstances subobject provides a way to define multicomponents which are instances of other MultiSpeciesType objects. The ListOfSpeciesFeatureTypes subobject and its SpeciesFeatureType children set up a framework for the referencing species or the instances of MultiSpeciesType objects to be able to have multistates. The ListOfSpeciesTypeComponentIndexes subobject provides a flexible way to reference any component in a MultiSpeciesType. The ListOfInSpeciesTypeBonds subobject and its InSpeciesTypeBond children provides a way to define bonds within a MultiSpeciesType.

new MultiSpeciesType()
Instance Members
▸ getCompartment()
▸ isSetCompartment()
▸ setCompartment(compartment)
▸ unsetCompartment()
▸ getSpeciesFeatureType(n)
▸ addSpeciesFeatureType(sft)
▸ getNumSpeciesFeatureTypes()
▸ createSpeciesFeatureType()
▸ removeSpeciesFeatureType(n)
▸ getSpeciesTypeInstance(n)
▸ addSpeciesTypeInstance(sti)
▸ getNumSpeciesTypeInstances()
▸ createSpeciesTypeInstance()
▸ removeSpeciesTypeInstance(n)
▸ getSpeciesTypeComponentIndex(n)
▸ addSpeciesTypeComponentIndex(stci)
▸ getNumSpeciesTypeComponentIndexes()
▸ createSpeciesTypeComponentIndex()
▸ removeSpeciesTypeComponentIndex(n)
▸ getInSpeciesTypeBond(n)
▸ addInSpeciesTypeBond(istb)
▸ getNumInSpeciesTypeBonds()
▸ createInSpeciesTypeBond()
▸ removeInSpeciesTypeBond(n)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

SpeciesTypeComponentIndex

Identifies a component within a MultiSpeciesType.

The SpeciesTypeComponentIndex object is a child of MultiSpeciesType, and provides a way to identify or index a component within that MultiSpeciesType. A SpeciesTypeComponentIndex object can be referenced by other class objects, such as InSpeciesTypeBond, OutwardBindingSite, SpeciesFeature or SpeciesTypeComponentMapInProduct objects, which need to identify a component in a particular MultiSpeciesType. A SpeciesTypeComponentIndex should be unambiguous. For example, a SpeciesTypeComponentIndex should not reference a MultiSpeciesType which is referenced by two SpeciesTypeInstance objects contained in the same MultiSpeciesType object.

new SpeciesTypeComponentIndex()
Instance Members
▸ getComponent()
▸ isSetComponent()
▸ setComponent(component)
▸ unsetComponent()
▸ getIdentifyingParent()
▸ isSetIdentifyingParent()
▸ setIdentifyingParent(identifyingParent)
▸ unsetIdentifyingParent()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

SpeciesTypeComponentMapInProduct

Distinguishes between components in reactants versus products.

The SpeciesTypeComponentMapInProduct object is a child of a SpeciesReference (via the MultiSpeciesReferencePlugin) in a Reaction, and defines the mapping between a component in a reactant and a component in a product. The identifications of a component and the SpeciesReference should be sufficient to identify the component in the context of a reaction. The attributes "reactant" and "reactantComponent" can identify the component in a reactant, and the "productComponent" attribute and the product storing the mapping information can identify the component in a product.

new SpeciesTypeComponentMapInProduct()
Instance Members
▸ getReactant()
▸ isSetReactant()
▸ setReactant(reactant)
▸ unsetReactant()
▸ getReactantComponent()
▸ isSetReactantComponent()
▸ setReactantComponent(reactantComponent)
▸ unsetReactantComponent()
▸ getProductComponent()
▸ isSetProductComponent()
▸ setProductComponent(productComponent)
▸ unsetProductComponent()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

SpeciesTypeInstance

Allows construction of structured MultiSpeciesType objects.

The SpeciesTypeInstance object is a child of MultiSpeciesType, and provides a way to construct MultiSpeciesType objects and Species with multiple components. A MultiSpeciesType can contain a list of instances of other MultiSpeciesType objects which can also have their own SpeciesTypeInstance objects, so the complete construct of a MultiSpeciesType has a tree structure. A MultiSpeciesType cannot contain an instance of any other MultiSpeciesType that already contains the instance of it. In other words, circular references are not allowed when constructing MultiSpeciesType objects. For example, if a MultiSpeciesType "A" contains the instance of another MultiSpeciesType "B", "B" must not contain the instance of "A" anywhere in the complete structure of "B". The optional attribute compartmentReference, of type SIdRef, can be used to indicate which sub-compartment in a composite compartment the SpeciesTypeInstance is located in.

new SpeciesTypeInstance()
Instance Members
▸ getSpeciesType()
▸ isSetSpeciesType()
▸ setSpeciesType(speciesType)
▸ unsetSpeciesType()
▸ getCompartmentReference()
▸ isSetCompartmentReference()
▸ setCompartmentReference(compartmentReference)
▸ unsetCompartmentReference()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

SubListOfSpeciesFeatures

Defines a set of SpeciesFeature objects.

The SubListOfSpeciesFeatures object is an optional child of the ListOfSpeciesFeatures list child of the extended Species (via the MultiSpeciesPlugin object). Listed alongside its sibling SpeciesFeature objects, it allows the user to define a set of two or more SpeciesFeature elements that have a logical relationship with each other. This relationship is defined by the "relation" attribute, which is an enumeration of values representing "and", "or", "not". (An "unknown" option is provided here for incomplete models, but cannot be used in a valid SBML document.) The following constants represent the values: libsbml.MULTI_RELATION_AND, libsbml.MULTI_RELATION_OR, libsbml.MULTI_RELATION_NOT, and libsbml.MULTI_RELATION_UNKNOWN. If any SpeciesFeature involved in a SubListOfSpeciesFeatures references a SpeciesFeatureType with an "occur" attribute greater than 1, the SubListOfSpeciesFeatures can only have the value "and" for its relation attribute.

new SubListOfSpeciesFeatures()
Instance Members
▸ getComponent()
▸ isSetComponent()
▸ setComponent(component)
▸ unsetComponent()
▸ createSpeciesFeature()
▸ get(n)
▸ remove(n)
▸ getRelation()
▸ isSetRelation()
▸ setRelation(relation)
▸ unsetRelation()
▸ appendAndOwn(disownedItem)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

DefaultTerm

The default result of a Transition.

The DefaultTerm defines the default result of a Transition, held in the (required) "resultLevel" attribute. This term is used when there are no other FunctionTerm elements or when none of the Math elements of the FunctionTerm elements evaluate to @c true.

new DefaultTerm()
Instance Members
▸ getResultLevel()
▸ isSetResultLevel()
▸ setResultLevel(resultLevel)
▸ unsetResultLevel()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

FunctionTerm

A function term.

Each FunctionTerm is associated with a result and with a Boolean function inside a Math element that can be used to set the conditions under which this term is selected.

new FunctionTerm()
Instance Members
▸ getResultLevel()
▸ isSetResultLevel()
▸ setResultLevel(resultLevel)
▸ unsetResultLevel()
▸ getMath()
▸ isSetMath()
▸ setMath(math)
▸ unsetMath()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ getName()
▸ setName(name)
▸ isSetName()
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Input

The input to a QualitativeSpecies.

Each Input refers to a QualitativeSpecies that participates in the corresponding Transition. In Petri nets, these are the input places of the transition. In logical models, they are the regulators of the species whose behaviour is defined by the transition.

new Input()
Instance Members
▸ getQualitativeSpecies()
▸ getTransitionEffect()
▸ getName()
▸ getSign()
▸ getThresholdLevel()
▸ isSetQualitativeSpecies()
▸ isSetTransitionEffect()
▸ isSetName()
▸ isSetSign()
▸ isSetThresholdLevel()
▸ setQualitativeSpecies(qualitativeSpecies)
▸ setTransitionEffect(transitionEffect)
▸ setSign(sign)
▸ setThresholdLevel(thresholdLevel)
▸ unsetQualitativeSpecies()
▸ unsetTransitionEffect()
▸ unsetSign()
▸ unsetThresholdLevel()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Output

The output from a QualitativeSpecies.

Each Output refers to a QualitativeSpecies that participates in (is affected by) the corresponding Transition. In Petri net models these are the output places of the transition.

In a logical model, a QualitativeSpecies should be referenced in at most one ListOfOutputs, (that of the Transition defining the evolution of this species). When a Transition has several outputs, it is because the referenced species share the same regulators and the same logical rules.

new Output()
Instance Members
▸ getQualitativeSpecies()
▸ getTransitionEffect()
▸ getOutputLevel()
▸ isSetQualitativeSpecies()
▸ isSetTransitionEffect()
▸ isSetOutputLevel()
▸ setQualitativeSpecies(qualitativeSpecies)
▸ setTransitionEffect(transitionEffect)
▸ setOutputLevel(outputLevel)
▸ unsetQualitativeSpecies()
▸ unsetTransitionEffect()
▸ unsetName()
▸ unsetOutputLevel()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

QualitativeSpecies

Extension of Species.

Similarly to the Species in SBML, the components of qualitative models refer to pools of entities that are considered indistinguishable and are each located in a specific Compartment. However, here components are characterised by their qualitative influences rather than by taking part in reactions. Therefore, we define the QualitativeSpecies element to represent such pools of entities.

In a Petri net, qualitative species refer to the places of the model, while in a logical model, they refer to the variables of this model (i.e. nodes of the influence graph).

A QualitativeSpecies describes a pool of indistinguishable entities in a Compartment. It is associated with a level (an integer representing e.g. an activity state, or a functional level of concentration, etc.)

new QualitativeSpecies()
Instance Members
▸ getCompartment()
▸ getConstant()
▸ getInitialLevel()
▸ getMaxLevel()
▸ isSetCompartment()
▸ isSetConstant()
▸ isSetInitialLevel()
▸ isSetMaxLevel()
▸ setCompartment(compartment)
▸ setConstant(constant)
▸ setInitialLevel(initialLevel)
▸ setMaxLevel(maxLevel)
▸ unsetCompartment()
▸ unsetConstant()
▸ unsetInitialLevel()
▸ unsetMaxLevel()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Transition

A transition of a QualitativeSpecies.

A Transition element contains at most one ListOfInputs and one ListOfOutputs and exactly one ListOfFunctionTerms.

A Transition defines the changes in level associated with the QualitativeSpecies that occur when a Transition is enabled.

In logical models, a Transition is used to specify the logical rule associated with a QualitativeSpecies (that appears as an Output of this Transition). For example, the rule "if A > 1 : B = 2" would be encapsulated as a Transition with QualitativeSpecies "A" as an Input and "B" as an Output; the "if A > 1" rule being encode by the math element of a FunctionTerm with the resultLevel attribute having a value "2".

In Petri net models, a Transition is interpreted, using the common Petri net semantics, as events that might occur within the system causing tokens to be moved.

new Transition()
Instance Members
▸ getInput(n)
▸ getInputBySpecies(sid)
▸ addInput(i)
▸ getNumInputs()
▸ createInput()
▸ removeInput(n)
▸ getOutput(n)
▸ getOutputBySpecies(sid)
▸ addOutput(o)
▸ getNumOutputs()
▸ createOutput()
▸ removeOutput(n)
▸ getFunctionTerm(n)
▸ addFunctionTerm(ft)
▸ getNumFunctionTerms()
▸ createFunctionTerm()
▸ removeFunctionTerm(n)
▸ createDefaultTerm()
▸ setDefaultTerm(dt)
▸ isSetDefaultTerm()
▸ getDefaultTerm()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

QualModelPlugin

Extension of Model.

The extension of SBML Level 3 Core's Model class is relatively straightforward: the Qualitative Models Package adds two lists, one for holding qualitativeSpecies (ListOfQualitativeSpecies), and the other for holding transitions (ListOfTransitions). The Model element may contain at most one ListOfQualitativeSpecies, which must contain at least one QualitativeSpecies. It may also contain at most one ListOfTransitions which must contain at least one Transition.

new QualModelPlugin()
Instance Members
▸ getQualitativeSpecies(n)
▸ addQualitativeSpecies(qualitativeSpecies)
▸ createQualitativeSpecies()
▸ removeQualitativeSpecies(n)
▸ getTransition(n)
▸ addTransition(transition)
▸ createTransition()
▸ removeTransition(n)
▸ getNumTransitions()
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

QualSBMLDocumentPlugin

Extension of SBMLDocument.

The QualSBMLDocumentPlugin class inherits from the SBMLDocumentPlugin class, and codifies the extensions to the SBMLDocument class defined in the SBML Level 3 qual ("qual") package.

The QualSBMLDocumentPlugin defines a required flag named required, which indicates whether the 'qual' constructs can be used to change the core mathematics of the model child of the sbml element. Because they can not, this attribute must be set false.

new QualSBMLDocumentPlugin()
Instance Members
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

QualExtension

Base extension class for the package.

There is currently one possible namespace defined for the Qualitative Modeling package: "http://www.sbml.org/sbml/level3/version1/qual/version1". Despite referencing SBML Level 3 Version 1 explicitly, this package (and all such packages) can be used without change in SBML Level 3 Version 2 documents. The only caveat is that features of the SBML Level 3 Version 2 specification that were not present in Level 1 may not be used by constructs from the Qualitative Modeling package.

new QualExtension()
Static Members
▸ getXmlnsL3V1V1()

CompBase

Convenience class for SBase-derived classes.

The CompBase class derives from SBase, and defines a few functions and features common to all SBase-derived classes in the SBML Level 3 comp ("comp") package.

new CompBase()
Instance Members
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

SBaseRef

Base class for references to objects.

The SBaseRef class was introduced by the SBML Level 3 comp ("comp") package as the principle way by which submodel elements may be referenced. The SBaseRef class is usually found as the base class of a Port, Deletion, ReplacedElement, or ReplacedBy class, but may appear as an child of one of the above classes if the parent object references a Submodel.

An SBaseRef object must reference an element using exactly one of the optional attributes of the class. Subclasses of SBaseRef may define additional optional attributes that are legal ways to reference an element.

SBaseRef objects may reference elements that do not live in the Model parent of the SBaseRef object. However, the SBaseRef class itself does not provide a method of determining which Model or Submodel is being referenced. The subclasses of SBaseRef provide methods for this instead.

Once the Model to which the SBaseRef object is referencing has been established, there are four optional attributes defined in the SBaseRef class that are each methods of referencing an element:

  • "portRef" (type PortSIdRef): As its name implies, this attribute is used to refer to a port identifier, in the case when the reference being ructed with the SBaseRef is intended to refer to a port on a submodel. The namespace of the PortSIdRef value is the set of identifiers of type PortSId defined in the submodel, not the parent model.
  • "idRef" (type SIdRef): As its name implies, this attribute is used to refer to a regular identifier (i.e., the value of an "id" attribute on some other object), in the case when the reference being ructed with the SBaseRef is intended to refer to an object that does not have a port identifier. The namespace of the SIdRef value is the set of identifiers of type SId defined in the submodel, not the parent model.
  • "unitRef" (type UnitSIdRef): This attribute is used to refer to the identifier of a UnitDefinition object. The namespace of the UnitSIdRef value is the set of unit identifiers defined in the submodel, not the parent model. (Note that even though this attribute is of type UnitSIdRef, the reserved unit identifiers that are defined by SBML Level 3 (see Section 3.1.10 of the core specification) are not permitted as values of "unitRef". Reserved unit identifiers may not be replaced or deleted.)
  • "metaIdRef" (type IDREF): This attribute is used to refer to a "metaid" attribute value on some other object, in the case when the reference beingructed with the SBaseRef is intended to refer to an object that does not have a port identifier. The namespace of the "metaIdRef" value is the entire document in which the referenced model resides, but must refer to a subelement of the referenced model. Since meta identifiers are optional attributes of SBase, all SBML objects have the potential to have a meta identifier value.

An SBaseRef object may have up to one subcomponent named "SBaseRef", of type SBaseRef. This permits recursive structures to beructed so that objects inside submodels can be referenced.

The form of such recursive references must be as follows. The highest-level SBaseRef object of such a chain (which will necessarily be an object of class Port, Deletion, ReplacedElement or ReplacedBy, because they are the only classes derived from the class SBaseRef) must refer to a Submodel object in the containing model. All child SBaseRef objects in the chain must refer to components inside the Model instance to which the Submodel refers.

new SBaseRef()
Instance Members
▸ getMetaIdRef()
▸ isSetMetaIdRef()
▸ setMetaIdRef()
▸ unsetMetaIdRef()
▸ getPortRef()
▸ isSetPortRef()
▸ setPortRef()
▸ unsetPortRef()
▸ getIdRef()
▸ isSetIdRef()
▸ setIdRef()
▸ unsetIdRef()
▸ getUnitRef()
▸ isSetUnitRef()
▸ setUnitRef()
▸ unsetUnitRef()
▸ getSBaseRef()
▸ isSetSBaseRef()
▸ setSBaseRef(the)
▸ createSBaseRef()
▸ unsetSBaseRef()
▸ getNumReferents()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Port

An interface to be used in composition.

The Port class was introduced by the SBML Level 3 comp ("comp") package to allow a Model to define a standard interface between it and other models that might use it as a submodel. It derives from the SBaseRef class, and the elements defined there refer to elements in the same parent Model as the Port object. A Port object instance therefore uses those attributes to define a port for a component in a model. When other SBaseRef or SBaseRef-derived classes refer to a Port object using a "portRef" attribute, the element being referenced is the element the Port object itself points to.

In the present formulation of the Hierarchical Model Composition package, the use of ports is not enforced, nor is there any mechanism to restrict which ports may be used in what ways---they are only an advisory construct. Future versions of this SBML package may provide additional functionality to support explicit restrictions on port use. For the present definition of Hierarchical Model Composition, users of models containing ports are encouraged to respect the modeler's intention in defining ports, and use the port definitions to interact with components through their ports (when they have ports defined) rather than interact directly with the components.

The required attribute "id" is used to give an identifier to a Port object so that other objects can refer to it. The attribute has type PortSId and is essentially identical to the SBML primitive type SId, except that its namespace is limited to the identifiers of Port objects defined within a Model object. In parallel, the PortSId type has a companion type, PortSIdRef, that corresponds to the SBML primitive type SIdRef; the value space of PortSIdRef is limited to PortSId values.

new Port()
Instance Members
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)
▸ getMetaIdRef()
▸ isSetMetaIdRef()
▸ setMetaIdRef()
▸ unsetMetaIdRef()
▸ getPortRef()
▸ isSetPortRef()
▸ setPortRef()
▸ unsetPortRef()
▸ getIdRef()
▸ isSetIdRef()
▸ setIdRef()
▸ unsetIdRef()
▸ getUnitRef()
▸ isSetUnitRef()
▸ setUnitRef()
▸ unsetUnitRef()
▸ getSBaseRef()
▸ isSetSBaseRef()
▸ setSBaseRef(the)
▸ createSBaseRef()
▸ unsetSBaseRef()
▸ getNumReferents()

ModelDefinition

A model used in model composition.

The comp ("comp") package allows multiple Model objects to be defined in a single SBMLDocument. While these new Model objects are not new SBML classes, they are given a new name, <modelDefinition>, and reside in ListOfModelDefinition objects. In libSBML, this class inherits from the Model class, changing only the expected parent of the object, and the XML name.

An additional restriction is placed on the "id" attribute of ModelDefinition objects: not only must it be unique across all such attributes of type SId within the ModelDefinition, it must also be unique across all Model, ModelDefinition, and ExternalModelDefinition objects in the same SBMLDocument.

new ModelDefinition()
Instance Members
▸ getNumReactions()
▸ getReaction(sid)
▸ createReaction()
▸ addReaction(r)
▸ removeReaction(n)
▸ getNumSpecies()
▸ createSpecies()
▸ addSpecies(s)
▸ getSpecies(n)
▸ removeSpecies(n)
▸ getNumUnitDefinitions()
▸ getUnitDefinition(n)
▸ getNumCompartments()
▸ getCompartment(n)
▸ createCompartment()
▸ removeCompartment(n)
▸ getNumParameters()
▸ createParameter()
▸ getParameter(n)
▸ getNumEvents()
▸ getEvent(sid)
▸ getFunctionDefinition(n)
▸ getNumInitialAssignments()
▸ getConstraint(n)
▸ getNumConstraints()
▸ getNumSpeciesWithBoundaryCondition()
▸ getSpeciesReference(sid)
▸ getModifierSpeciesReference(sid)
▸ getNumRules()
▸ getRule(n)
▸ getRateRuleByVariable(variable)
▸ getAssignmentRuleByVariable(variable)
▸ getInitialAssignment(n)
▸ getInitialAssignmentBySymbol(symbol)
▸ createInitialAssignment()
▸ createAlgebraicRule()
▸ createAssignmentRule()
▸ createRateRule()
▸ createConstraint()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

ExternalModelDefinition

A reference to an externally-defined model.

The ExternalModelDefinition class was introduced by the SBML Level 3 comp ("comp") package to define references to Model objects defined in other files.

ExternalModelDefinition objects are model definitions---in and of themselves, they are definitions of models but not uses of those models. The class provides a way to declare and identify them so that Model objects in the present SBML document can use them in Submodel objects.

ExternalModelDefinition contains two required attributes ("source" and "id") and three optional attributes ("modelRef", "md5" and "name").

The "id" attribute serves to provide a handle for the external model reference so that Submodel objects can refer to it. Crucially, it is not the identifier of the model being referenced; rather, it is an identifier for this ExternalModelDefinition object within the current SBML document. The "id" attribute takes a required value of type SId, and must be unique across all Model and ExternalModelDefinition objects present in the document.

ExternalModelDefinition also has an optional "name" attribute, of type 'string'. The "name" attribute may be used to provide a human-readable description of the ExternalModelDefintion object.

The required attribute "source" is used to locate the SBML document containing an external model definition. The value of this attribute must be of type anyURI. Since URIs may be either URLs, URNs, or relative or absolute file locations, this offers flexibility in referencing SBML documents. In all cases, the "source" attribute value must refer specifically to an SBML Level 3 document; prior Levels/Versions of SBML are not supported by this package. The entire file at the given location is referenced. The "source" attribute must have a value for every ExternalModelDefinition instance.

It should be noted that even though there is currently only a Hierarchical Model Composition package for SBML Level 3 Version 1, it may be used in SBML Level 3 Version 2, as long as nothing new from that package is used. This allows the ExternalModelDefinition to reference any SBML Level 3 document, so long as only constructs from Version 1 are used.

ExternalModelDefinition's optional attribute "modelRef", of type SIdRef, is used to identify a Model or ExternalModelDefinition object within the SBML document located at "source". The object referenced may be the main model in the document, or it may be a model definition contained in the SBML document's ListOfModelDefinitions or ListOfExternalModelDefinitions lists. Loops are not allowed: it must be possible to follow a chain of ExternalModelDefinition objects to its end in a Model object.

In core SBML, the "id" on Model is an optional attribute, and therefore, it is possible that the Model object in a given SBML document does not have an identifier. In that case, there is no value to give to the "modelRef" attribute in ExternalModelDefinition. If "modelRef" does not have a value, then the main model (i.e., the <model> element within the <sbml> element) in the referenced file is interpreted as being the model referenced by this ExternalModelDefinition instance.

Finally, the optional "md5" attribute takes a string value. If set, it must be an MD5 checksum value computed over the document referenced by "source". This checksum can serve as a data integrity check over the contents of the "source". Applications may use this to verify that the contents have not changed since the time that the ExternalModelDefinition reference was constructed.

new ExternalModelDefinition()
Instance Members
▸ getModelRef()
▸ isSetModelRef()
▸ setModelRef(id)
▸ unsetModelRef()
▸ getMd5()
▸ isSetMd5()
▸ setMd5(md5)
▸ unsetMd5()
▸ getSource()
▸ isSetSource()
▸ setSource(source)
▸ unsetSource()
▸ getReferencedModel()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Submodel

A model instance inside another model.

The Submodel class was introduced by the SBML Level 3 comp ("comp") package as the principle way by which models are structured hierarchically. Submodels are instantiations of models contained within other models. They reference another Model that is to be instantiated within its parent Model, and additionally define how that Model is to be modified before instantiation.

The Submodel object class has a required attribute "modelRef", which must reference another Model or ExternalModelDefinition object present in the SBML Document. This referenced Model is the model to be instantiated.

It also has a required attribute, "id", to give the submodel a unique identifier by which other parts of an SBML model definition can refer to it, and an optional "name" attribute of type string. Identifiers and names must be used according to the guidelines described in the SBML specification.

The Submodel class also providesructs that define how the referenced Model object is to be modified before it is instantiated in the enclosing model. If numerical values in the referenced model must be changed in order to fit them into their new context as part of the submodel, the changes can be handled through conversion factors. If one or more structural features in the referenced model are undesirable and should be removed, the changes can be handled through deletions. (For example, an initial assignment or reaction may not be relevant in its new context and should be removed.)

In some cases, the referenced Model may have been written with different units than the containing model. For most model elements, this is not a problem: it is already possible to have Species and Parameter objects with different units in a single model, for example, so in this case the resulting hierarchical model would be treated in exactly the same way as any other model with Species and Parameters with different units.

However, two units in SBML models are fixed and must not vary between SBML elements: time and extent. The units of time are set once per model, and affect the core elements of RateRule, KineticLaw, Delay, and the csymbols 'time' and 'delay'. Even if the model does not explicitly state what the units of time actually are, they are defined to be consistent across the model, and therefore might differ from the units of time across a parent model. To correct this imbalance, the optional attribute "timeConversionFactor" may be used, which, if defined, must reference a ant parameter in the parent model. The value of the time conversion factor should be defined such that a single unit of time in the Submodel multiplied by the time conversion factor should equal a single unit of time in the parent model.

Extent is the unit in SBML that defines how the KineticLaw of a Reaction affects species quantities: kinetic laws are defined to be in units of extent/time. No other SBML coreruct is defined in terms of extent. If the effective units of extent in a submodel differ from the effective units of extent in the parent model (regardless of whether either defined what those units actually are), the optional attribute "extentConversionFactor" may be used, which, if defined, must reference a ant parameter in the parent model. The value of the extent conversion factor should be defined such that a single unit of extent in the Submodel multiplied by the extent conversion factor should equal a single unit of extent in the parent model.

If features of the referenced model must be removed, a Deletion should be added to the Submodel object. A Submodel may contain a child ListOfDeletions, which in turn may contain one or more Deletion items. Each Deletion references a single element of the referenced Model that must be removed before instantiating that Model as a submodel of the parent Model.

new Submodel()
Instance Members
▸ getModelRef()
▸ isSetModelRef()
▸ setModelRef(modelRef)
▸ unsetModelRef()
▸ getSubstanceConversionFactor()
▸ isSetSubstanceConversionFactor()
▸ setSubstanceConversionFactor()
▸ unsetSubstanceConversionFactor()
▸ getTimeConversionFactor()
▸ isSetTimeConversionFactor()
▸ setTimeConversionFactor()
▸ unsetTimeConversionFactor()
▸ getExtentConversionFactor()
▸ isSetExtentConversionFactor()
▸ setExtentConversionFactor()
▸ unsetExtentConversionFactor()
▸ getDeletion(n)
▸ addDeletion(deletion, deletion)
▸ getNumDeletions()
▸ createDeletion()
▸ removeDeletion(index)
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Deletion

Deletion of an object from a submodel.

The Deletion class was introduced by the SBML Level 3 comp ("comp") package to allow elements of submodels to be removed before instantiation.

The Deletion object class is used to define a deletion operation to be applied when a submodel instantiates a model definition. Deletions may be useful in hierarchical model composition scenarios for various reasons. For example, some components in a submodel may be redundant in the composed model, perhaps because the same features are implemented in a different way in the new model.

Deletions function as follows. When the Model to which the Submodel object refers (via the "modelRef" attribute) is read and processed for inclusion into the composed model, each Deletion object identifies an object to remove from that Model instance. The resulting submodel instance consists of everything in the Model object instance minus the entities referenced by the list of Deletion objects.

As might be expected, deletions can have wide-ranging implications, especially when the object deleted has substantial substructure, as in the case of reactions. The following are rules regarding deletions and their effects.

  • An object that has been deleted is considered inaccessible. Any element that has been deleted (or replaced) may not be referenced by an SBaseRef object.
  • If the deleted object has child objects and other structures, the child objects and substructure are also considered to be deleted.
  • It is not an error to delete explicitly an object that is already deleted by implication (for example as a result of the second point above). The resulting model is the same.
  • If the deleted object is from an SBML namespace that is not understood by the interpreter, the deletion must be ignored---the object will not need to be deleted, as the interpreter could not understand the package. If an interpreter cannot tell whether a referenced object does not exist or if exists in an unparsed namespace it may produce a warning.

The Deletion object class is subclassed from SBaseRef, and reuses all the machinery provided by SBaseRef. In addition, it defines two optional attributes, "id" and "name". The "id" attribute can be used to give an identifier to a given deletion operation. The identifier has no mathematical meaning, but it may be useful for creating submodels that can be manipulated more directly by other submodels. (Indeed, it is legitimate for an enclosing model definition to delete a deletion!)

The optional "name" attribute is provided on Deletion for the same reason it is provided on other elements that have identifiers; viz., to provide for the possibility of giving a human-readable name to the object. The name may be useful in situations when deletions are displayed to modelers.

new Deletion()
Instance Members
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)
▸ getMetaIdRef()
▸ isSetMetaIdRef()
▸ setMetaIdRef()
▸ unsetMetaIdRef()
▸ getPortRef()
▸ isSetPortRef()
▸ setPortRef()
▸ unsetPortRef()
▸ getIdRef()
▸ isSetIdRef()
▸ setIdRef()
▸ unsetIdRef()
▸ getUnitRef()
▸ isSetUnitRef()
▸ setUnitRef()
▸ unsetUnitRef()
▸ getSBaseRef()
▸ isSetSBaseRef()
▸ setSBaseRef(the)
▸ createSBaseRef()
▸ unsetSBaseRef()
▸ getNumReferents()

ReplacedElement

Indicates an object replaces another.

The ReplacedElement class was introduced by the SBML Level 3 comp ("comp") package to allow submodel elements to be replaced, but still allow references to those elements to be valid. A ReplacedElement object is essentially a pointer to a submodel object that should be considered 'replaced'. The object holding the ReplacedElement instance is the one doing the replacing; the object pointed to by the ReplacedElement object is the object being replaced.

A replacement implies that dependencies involving the replaced object must be updated: all references to the replaced object elsewhere in the model are taken to refer to the replacement object instead. For example, if one species replaces another, then any reference to the original species in mathematical formulas, or lists of reactants or products or modifiers in reactions, or initial assignments, or any other SBML construct, are taken to refer to the replacement species, with its value possibly modified by either this object's "conversionFactor" attribute or the relevant submodel's conversion factors. Moreover, any annotations that refer to the replaced species' "metaid" value must be made to refer to the replacement species' "metaid" value instead; and anything else that referred either to an object identifier (i.e., attributes such as the "id" attribute whose types inherit from the SId primitive data type) or the meta identifier (i.e., the "metaid" attribute or any other attribute that inherits from the ID primitive data type) must be made to refer to the replacement species object instead.

It is worth noting that local parameters (inside Reaction objects) pose an interesting edge case for these rules. In order to determine which element is pointed to by a cn element within the math element of a KineticLaw object, it is necessary to examine the local parameters of that kinetic law's parent Reaction object. Whether the cn element is considered to point to something new, then, depends on whether it pointed to the local parameter and whether that local parameter was replaced, even if the text of the element matched the SId value of another element in the model. Note that local parameters may only effectively be replaced by global parameters, since references to its SId are only valid from within the Reaction element to which it belongs.

When referencing an element within the Submodel pointed to by the "submodelRef" attribute (defined in libSBML in the Replacing class), any of the four attributes inherited from SBaseRef for the purpose may be used (portRef, idRef, unitRef, or metaIdRef), or a new optional attribute "deletion" may be used. This attribute must be the identifier of a Deletion object in the parent Model of the ReplacedElement (i.e., the value of some Deletion object's "id" attribute). When "deletion" is set, it means the ReplacedElement object is actually an annotation to indicate that the replacement object replaces something deleted from a submodel. The use of the "deletion" attribute overrides the use of the attributes inherited from SBaseRef: instead of using, e.g., "portRef" or "idRef", the ReplacedElement instance sets "deletion" to the identifier of the Deletion object. In addition, the referenced Deletion must be a child of the Submodel referenced by the "submodelRef" attribute.

The use of ReplacedElement objects to refer to deletions has no effect on the composition of models or the mathematical properties of the result. It serves instead to help record the decision-making process that lead to a given model. It can be particularly useful for visualization purposes, as well as to serve as scaffolding where other types of annotations can be added using the normal Annotation subcomponents available on all SBase objects in SBML.

As with the Submodel class, it may be that the units of the replaced element may not match the units of the replacement element. In this case, the optional "conversionFactor" attribute may be used. This attribute, if present, defines how to transform or rescale the replaced object's value so that it is appropriate for the new contexts in which the object appears. This attribute takes a value of type SIdRef, and the value must refer to a Parameter object instance defined in the model. This parameter then acts as a conversion factor.

The value of the conversion factor should be defined such that a single unit of the replaced element multiplied by the conversion factor should equal a single unit of the replacement element, and the units of the conversion factor should be commensurate with that transformation. The referenced Parameter may be non-constant, particularly if a Species is replaced by a Species with a different "hasOnlySubstanceUnits" attribute value, thus changing amount to concentration, or visa versa.

new ReplacedElement()
Instance Members
▸ getConversionFactor()
▸ isSetConversionFactor()
▸ setConversionFactor(id)
▸ unsetConversionFactor()
▸ getDeletion()
▸ isSetDeletion()
▸ setDeletion(id)
▸ unsetDeletion()
▸ getElementName()
▸ getNumReferents()
▸ getSubmodelRef()
▸ isSetSubmodelRef()
▸ setSubmodelRef(id)
▸ unsetSubmodelRef()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)
▸ getMetaIdRef()
▸ isSetMetaIdRef()
▸ setMetaIdRef()
▸ unsetMetaIdRef()
▸ getPortRef()
▸ isSetPortRef()
▸ setPortRef()
▸ unsetPortRef()
▸ getIdRef()
▸ isSetIdRef()
▸ setIdRef()
▸ unsetIdRef()
▸ getUnitRef()
▸ isSetUnitRef()
▸ setUnitRef()
▸ unsetUnitRef()
▸ getSBaseRef()
▸ isSetSBaseRef()
▸ setSBaseRef(the)
▸ createSBaseRef()
▸ unsetSBaseRef()

ReplacedBy

Indicates an object replaced by another.

The ReplacedBy class was introduced by the SBML Level 3 @ref comp ("comp") package to allow submodel elements to be 'canonical' versions of the element while still allowing the parent model to reference those elements. Whereas a ReplacedElement object indicates that the containing object replaces another, a ReplacedBy object indicates the converse: the parent object is to be replaced by another object.

As is the case with ReplacedElement, the ReplacedBy class inherits from SBaseRef. It additionally defines one required attribute ("submodelRef"), defined in libSBML in the Replacing class.

new ReplacedBy()
Instance Members
▸ getSubmodelRef()
▸ isSetSubmodelRef()
▸ setSubmodelRef(id)
▸ unsetSubmodelRef()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)
▸ getMetaIdRef()
▸ isSetMetaIdRef()
▸ setMetaIdRef()
▸ unsetMetaIdRef()
▸ getPortRef()
▸ isSetPortRef()
▸ setPortRef()
▸ unsetPortRef()
▸ getIdRef()
▸ isSetIdRef()
▸ setIdRef()
▸ unsetIdRef()
▸ getUnitRef()
▸ isSetUnitRef()
▸ setUnitRef()
▸ unsetUnitRef()
▸ getSBaseRef()
▸ isSetSBaseRef()
▸ setSBaseRef(the)
▸ createSBaseRef()
▸ unsetSBaseRef()

Replacing

Convenience class.

The Replacing class does not exist officialy in the the @ref comp ("comp") package, but is implemented here as a convenience subclass of the ReplacedElement and ReplacedBy classes, since both of those classes define a 'submodelRef' attribute.

The required attribute "submodelRef" takes a value of type SIdRef, which must be the identifier of a Submodel object in the containing model. The model referenced by the Submodel object establishes the object namespaces for the "portRef", "idRef", "unitRef" and "metaIdRef" attributes: only objects within the Model object may be referenced by those attributes.

new Replacing()
Instance Members
▸ getSubmodelRef()
▸ isSetSubmodelRef()
▸ setSubmodelRef(id)
▸ unsetSubmodelRef()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)
▸ getMetaIdRef()
▸ isSetMetaIdRef()
▸ setMetaIdRef()
▸ unsetMetaIdRef()
▸ getPortRef()
▸ isSetPortRef()
▸ setPortRef()
▸ unsetPortRef()
▸ getIdRef()
▸ isSetIdRef()
▸ setIdRef()
▸ unsetIdRef()
▸ getUnitRef()
▸ isSetUnitRef()
▸ setUnitRef()
▸ unsetUnitRef()
▸ getSBaseRef()
▸ isSetSBaseRef()
▸ setSBaseRef(the)
▸ createSBaseRef()
▸ unsetSBaseRef()
▸ getNumReferents()

CompModelPlugin

Extension of Model.

The CompModelPlugin class inherits from the SBMLSBasePlugin class, and codifies the extensions to the Model class defined in the SBML Level"3 @ref comp ("comp") package. This extension allows a Model to define Submodels (other Models that are instantiated as new parts of the parent Model), and Ports, a defined interface for including the given Model as a Submodel of a different Model.

Submodels are stored in an optional child ListOfSubmodels object, which, if present, must contain one or more Submodel objects. All of the Submodels present in the ListOfSubmodels are defined to be instantiated in the 'complete' Model.

Ports are stored in an optional child ListOfPorts object, which, if present, must contain one or more Port objects. All of the Ports present in the ListOfPorts collectively define the 'port interface' of the Model.

new CompModelPlugin()
Instance Members
▸ getSubmodel()
▸ addSubmodel(submodel)
▸ getNumSubmodels()
▸ createSubmodel()
▸ removeSubmodel(index)
▸ getPort(id)
▸ addPort(port)
▸ getNumPorts()
▸ createPort()
▸ removePort(index)
▸ setDivider(divider)
▸ getDivider()
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

CompSBasePlugin

Extension of SBase.

The CompSBasePlugin class inherits from the SBasePlugin class, and codifies the extensions to the SBase class defined in the comp ("comp") package. This extension allows the modeler to define one or more submodel elements which the parent SBase object replaces, and/or a single submodel element which replaces the parent SBase object.

This is accomplished through the addition of an optional ListOfReplacedElements child, which may contain one or more ReplacedElement objects, each of which references a submodel object to be replaced by the containing SBase object, and through the addition of a single optional ReplacedBy child, which references a submodel object which is to replace the containing SBase object.

If a single SBase element both contains a ListOfReplacedElements and has a ReplacedBy child, it and all the referenced ReplacedElement objects are to be replaced by the object referenced by the ReplacedBy element.

new CompSBasePlugin()
Instance Members
▸ getReplacedElement(n)
▸ addReplacedElement(replacedElement)
▸ getNumReplacedElements()
▸ clearReplacedElements()
▸ createReplacedElement()
▸ removeReplacedElement(index)
▸ getReplacedBy()
▸ isSetReplacedBy()
▸ setReplacedBy(replacedBy)
▸ createReplacedBy()
▸ unsetReplacedBy()
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

CompSBMLDocumentPlugin

Extension of SBMLDocument.

The CompSBMLDocumentPlugin class inherits from the SBMLDocumentPlugin class, and codifies the extensions to the SBMLDocument class defined in the SBML Level 3 comp ("comp") package. This extension allows multiple Model objects to be defined in a single SBMLDocument, stored in an optional child ListOfModelDefinitions object, as well as define references to Model objects in other files, stored in the optional child ListOfExternalModelDefinitions object. These model definitions, if present, allow Submodel objects to reference other Models to instantiate.

The presence of any ModelDefinition or ExternalModelDefinition in an SBMLDocument does not change the default Model in the file. If a SBMLDocument is submitted somewhere to be simulated, it is still the "model" child of the "sbml" element that should be simulated.

In addition, as all packages do, the CompSBMLDocumentPlugin defines a required flag named "required", which indicates whether "comp" constructs can be used to change the core mathematics of the "model" child of the "sbml" element. Because they can, this attribute must be set true.

new CompSBMLDocumentPlugin()
Instance Members
▸ getModelDefinition(n)
▸ addModelDefinition(modelDefinition)
▸ getNumModelDefinitions()
▸ createModelDefinition()
▸ removeModelDefinition(index)
▸ getExternalModelDefinition(n)
▸ addExternalModelDefinition(externalModelDefinition)
▸ getNumExternalModelDefinitions()
▸ createExternalModelDefinition()
▸ removeExternalModelDefinition(index)
▸ setRequired(value)
▸ getRequired()
▸ isSetRequired()
▸ unsetRequired()
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

CompExtension

Base extension class for the package.

There is currently exactly one namespace defined for the Hierarchical Model Composition package: "http://www.sbml.org/sbml/level3/version1/comp/version1". Despite referencing SBML Level 3 Version 1 explicitly, this package (and all such packages) can be used without change in SBML Level 3 Version 2 documents. The only caveat is that features of the SBML Level 3 Version 2 specification that were not present in Level 1 may not be used by constructs from the Hierarchical Model Composition package. The most relevant restriction this implies is that if a Level 2 SBML element has an "id" attribute that was newly added in Level 2 (when "id" was added to SBase itself), an SBaseRef "idRef" attribute may not reference it, and it must continue to use the "metaIdRef" attribute instead.

new CompExtension()
Static Members
▸ getXmlnsL3V1V1()

ArraysASTPlugin

Extension of AST.

new ArraysASTPlugin()
Instance Members
▸ getPackageName()

ArraysSBMLDocumentPlugin

Extension of SBMLDocument.

new ArraysSBMLDocumentPlugin()
Instance Members
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

ArraysExtension

Base extension class.

new ArraysExtension()
Static Members
▸ getXmlnsL3V1V1()

ArraysSBasePlugin

Extension of SBase.

new ArraysSBasePlugin()
Instance Members
▸ getIndex(n)
▸ getIndexByArrayDimension(arrayDimension)
▸ addIndex(i)
▸ getNumIndices()
▸ createIndex()
▸ removeIndex(n)
▸ getDimension(n)
▸ getDimensionBySize(sid)
▸ getDimensionByArrayDimension(arrayDimension)
▸ addDimension(d)
▸ getNumDimensions()
▸ createDimension()
▸ removeDimension(n)
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

Dimension

The SBML Arrays Dimension class.

new Dimension()
Instance Members
▸ getSize()
▸ getArrayDimension()
▸ isSetSize()
▸ isSetArrayDimension()
▸ setSize(size)
▸ setArrayDimension()
▸ unsetSize()
▸ unsetArrayDimension()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

Index

The SBML Arrays Index class.

new Index()

Type: String

Instance Members
▸ getReferencedAttribute()
▸ getArrayDimension()
▸ isSetReferencedAttribute()
▸ isSetArrayDimension()
▸ setReferencedAttribute(referencedAttribute)
▸ setArrayDimension(arrayDimension)
▸ unsetReferencedAttribute()
▸ unsetArrayDimension()
▸ getMath()
▸ isSetMath()
▸ setMath(math)
▸ unsetMath()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

DynCompartmentPlugin

Implementation of the DynCompartmentPlugin class

new DynCompartmentPlugin()
Instance Members
▸ getCboTerm()
▸ isSetCboTerm()
▸ setCboTerm(cboTerm)
▸ unsetCboTerm()
▸ getSpatialComponent(n)
▸ addSpatialComponent(sc)
▸ getNumSpatialComponents()
▸ createSpatialComponent()
▸ removeSpatialComponent(n)
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

DynSBMLDocumentPlugin

Implementation of the DynSBMLDocumentPlugin class

new DynSBMLDocumentPlugin()
Instance Members
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

DynEventPlugin

Implementation of the DynEventPlugin class

new DynEventPlugin()
Instance Members
▸ getCboTerm()
▸ getApplyToAll()
▸ isSetCboTerm()
▸ isSetApplyToAll()
▸ setCboTerm(cboTerm)
▸ setApplyToAll(applyToAll)
▸ unsetCboTerm()
▸ unsetApplyToAll()
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

DynExtension

Implementation of the DynExtension class

new DynExtension()
Static Members
▸ getXmlnsL3V1V1()

DynSBasePlugin

Implementation of the DynSBasePlugin class

new DynSBasePlugin()
Instance Members
▸ getCboTerm()
▸ isSetCboTerm()
▸ setCboTerm(cboTerm)
▸ unsetCboTerm()
▸ getPackageName()
▸ getPrefix()
▸ getURI()
▸ getVersion()
▸ getLevel()

DynElement

Implementation of the DynElement class

new DynElement()
Instance Members
▸ getIdRef()
▸ getMetaIdRef()
▸ isSetIdRef()
▸ isSetMetaIdRef()
▸ setIdRef(idRef)
▸ setMetaIdRef(metaIdRef)
▸ unsetIdRef()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

SpatialComponent

Implementation of the SpatialComponent class

new SpatialComponent()
Instance Members
▸ getSpatialIndex()
▸ getVariable()
▸ isSetSpatialIndex()
▸ isSetVariable()
▸ isSetId()
▸ isSetName()
▸ setSpatialIndex(spatialIndex)
▸ setVariable(variable)
▸ unsetSpatialIndex()
▸ unsetVariable()
▸ getId()
▸ setId(id)
▸ isSetIdAttribute()
▸ setName(name)
▸ setMetaId(metaid)
▸ isSetMetaId()
▸ getSBOTerm()
▸ setSBOTerm(value)
▸ isSetSBOTerm()
▸ unsetSBOTerm()
▸ setAnnotation(annotation)
▸ unsetAnnotation()
▸ getAnnotationString()
▸ getLevel()
▸ getVersion()
▸ getNotesString()
▸ isSetNotes()
▸ unsetNotes()
▸ getNumCVTerms()
▸ getCVTerm(n)
▸ getNumPlugins()
▸ enablePackage(pkgURI, pkgPrefix, flag)
▸ disablePackage(pkgURI, pkgPrefix)

ASTNodeType_t

Abstract Syntax Tree (AST) representation of amathematical expression.

Abstract Syntax Trees (ASTs) are a simple kind of data structure used in libSBML for storing mathematical expressions. The ASTNode is the cornerstone of libSBML's AST representation. An AST "node" represents the most basic, indivisible part of a mathematical formula and come in many types. For instance, 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. 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).

The ASTNodeType_t type contains all permitted AST nodes.

Converting between ASTs and text strings

The text-string form of mathematical formulas handled by SBMLFormulaParser#parseL3Formula are in a simple C-inspired infix notation. A formula in this text-string form can be handed to a program that understands SBML mathematical expressions, or used as part of a translation system.

The formula strings may contain operators, function calls, symbols, and white space characters. The allowable white space characters are tab and space. The following are illustrative examples of formulas expressed in the syntax:

0.10 * k4^2
(vm * s1)/(km + s1)

The libSBML documentation shows the precedence rules in this syntax.

A program parsing a formula in an SBML model should assume that names appearing in the formula are the identifiers of Species, Parameter, Compartment, FunctionDefinition, Reaction (in SBML Levels 2 and 3), or SpeciesReference (in SBML Level 3 only) objects defined in a model. When a function call is involved, the syntax consists of a function identifier, followed by optional white space, followed by an opening parenthesis, followed by a sequence of zero or more arguments separated by commas (with each comma optionally preceded and/or followed by zero or more white space characters), followed by a closing parenthesis. There is an almost one-to-one mapping between the list of predefined functions available, and those defined in MathML. All of the MathML functions are recognized; this set is larger than the functions defined in SBML Level 1. In the subset of functions that overlap between MathML and SBML Level 1, there exist a few differences.

For constructing ASTs use SBMLFormulaParser#parseL3Formula.

AST_PLUS
AST_MINUS
AST_TIMES
AST_DIVIDE
AST_POWER
AST_INTEGER
AST_REAL
AST_REAL_E
AST_RATIONAL
AST_NAME
AST_NAME_AVOGADRO
AST_NAME_TIME
AST_CONSTANT_E
AST_CONSTANT_FALSE
AST_CONSTANT_PI
AST_CONSTANT_TRUE
AST_LAMBDA
AST_FUNCTION
AST_FUNCTION_ABS
AST_FUNCTION_ARCCOS
AST_FUNCTION_ARCCOSH
AST_FUNCTION_ARCCOT
AST_FUNCTION_ARCCOTH
AST_FUNCTION_ARCCSC
AST_FUNCTION_ARCCSCH
AST_FUNCTION_ARCSEC
AST_FUNCTION_ARCSECH
AST_FUNCTION_ARCSIN
AST_FUNCTION_ARCSINH
AST_FUNCTION_ARCTAN
AST_FUNCTION_ARCTANH
AST_FUNCTION_CEILING
AST_FUNCTION_COS
AST_FUNCTION_COSH
AST_FUNCTION_COT
AST_FUNCTION_COTH
AST_FUNCTION_CSC
AST_FUNCTION_CSCH
AST_FUNCTION_DELAY
AST_FUNCTION_EXP
AST_FUNCTION_FACTORIAL
AST_FUNCTION_FLOOR
AST_FUNCTION_LN
AST_FUNCTION_LOG
AST_FUNCTION_PIECEWISE
AST_FUNCTION_POWER
AST_FUNCTION_ROOT
AST_FUNCTION_SEC
AST_FUNCTION_SECH
AST_FUNCTION_SIN
AST_FUNCTION_SINH
AST_FUNCTION_TAN
AST_FUNCTION_TANH
AST_LOGICAL_AND
AST_LOGICAL_NOT
AST_LOGICAL_OR
AST_LOGICAL_XOR
AST_RELATIONAL_EQ
AST_RELATIONAL_GEQ
AST_RELATIONAL_GT
AST_RELATIONAL_LEQ
AST_RELATIONAL_LT
AST_RELATIONAL_NEQ
AST_END_OF_CORE
AST_FUNCTION_MAX
AST_FUNCTION_MIN
AST_FUNCTION_QUOTIENT
AST_FUNCTION_RATE_OF
AST_FUNCTION_REM
AST_LOGICAL_IMPLIES
AST_CSYMBOL_FUNCTION
AST_DISTRIB_FUNCTION_NORMAL
AST_DISTRIB_FUNCTION_UNIFORM
AST_DISTRIB_FUNCTION_BERNOULLI
AST_DISTRIB_FUNCTION_BINOMIAL
AST_DISTRIB_FUNCTION_CAUCHY
AST_DISTRIB_FUNCTION_CHISQUARE
AST_DISTRIB_FUNCTION_EXPONENTIAL
AST_DISTRIB_FUNCTION_GAMMA
AST_DISTRIB_FUNCTION_LAPLACE
AST_DISTRIB_FUNCTION_LOGNORMAL
AST_DISTRIB_FUNCTION_POISSON
AST_DISTRIB_FUNCTION_RAYLEIGH
AST_LINEAR_ALGEBRA_VECTOR
AST_LINEAR_ALGEBRA_SELECTOR
AST_LINEAR_ALGEBRA_MATRIX
AST_LINEAR_ALGEBRA_MATRIXROW
AST_LINEAR_ALGEBRA_DETERMINANT
AST_LINEAR_ALGEBRA_TRANSPOSE
AST_LINEAR_ALGEBRA_VECTOR_PRODUCT
AST_LINEAR_ALGEBRA_SCALAR_PRODUCT
AST_LINEAR_ALGEBRA_OUTER_PRODUCT
AST_LOGICAL_EXISTS
AST_LOGICAL_FORALL
AST_STATISTICS_MEAN
AST_STATISTICS_MEDIAN
AST_STATISTICS_MODE
AST_STATISTICS_MOMENT
AST_SERIES_PRODUCT
AST_STATISTICS_SDEV
AST_SERIES_SUM
AST_STATISTICS_VARIANCE
AST_UNKNOWN
ASTNodeType_t

UnitKind_t

UnitKind_t

Enumeration of predefined SBML base units.

See the libSBML C++ docs for UnitKind_t.

UNIT_KIND_AMPERE
UNIT_KIND_AVOGADRO
UNIT_KIND_BECQUEREL
UNIT_KIND_CANDELA
UNIT_KIND_CELSIUS
UNIT_KIND_COULOMB
UNIT_KIND_DIMENSIONLESS
UNIT_KIND_FARAD
UNIT_KIND_GRAM
UNIT_KIND_GRAY
UNIT_KIND_HENRY
UNIT_KIND_HERTZ
UNIT_KIND_ITEM
UNIT_KIND_JOULE
UNIT_KIND_KATAL
UNIT_KIND_KELVIN
UNIT_KIND_KILOGRAM
UNIT_KIND_LITER
UNIT_KIND_LITRE
UNIT_KIND_LUMEN
UNIT_KIND_LUX
UNIT_KIND_METER
UNIT_KIND_METRE
UNIT_KIND_MOLE
UNIT_KIND_NEWTON
UNIT_KIND_OHM
UNIT_KIND_PASCAL
UNIT_KIND_RADIAN
UNIT_KIND_SECOND
UNIT_KIND_SIEMENS
UNIT_KIND_SIEVERT
UNIT_KIND_STERADIAN
UNIT_KIND_TESLA
UNIT_KIND_VOLT
UNIT_KIND_WATT
UNIT_KIND_WEBER
UNIT_KIND_INVALID
UnitKind_t

OperationReturnValues_t

LibSBML diagnostic return codes.

Many methods in libSBML return a status code to indicate whether the operation requested by the caller succeeded or failed. This enumeration lists all the possible return codes from any libSBML methods.

LIBSBML_OPERATION_SUCCESS
LIBSBML_INDEX_EXCEEDS_SIZE
LIBSBML_UNEXPECTED_ATTRIBUTE
LIBSBML_OPERATION_FAILED
LIBSBML_INVALID_ATTRIBUTE_VALUE
LIBSBML_INVALID_OBJECT
LIBSBML_DUPLICATE_OBJECT_ID
LIBSBML_LEVEL_MISMATCH
LIBSBML_VERSION_MISMATCH
LIBSBML_INVALID_XML_OPERATION
LIBSBML_NAMESPACES_MISMATCH
LIBSBML_DUPLICATE_ANNOTATION_NS
LIBSBML_ANNOTATION_NAME_NOT_FOUND
LIBSBML_ANNOTATION_NS_NOT_FOUND
LIBSBML_MISSING_METAID
LIBSBML_PKG_VERSION_MISMATCH
LIBSBML_PKG_UNKNOWN
LIBSBML_PKG_UNKNOWN_VERSION
LIBSBML_PKG_DISABLED
LIBSBML_PKG_CONFLICTED_VERSION
LIBSBML_PKG_CONFLICT
LIBSBML_CONV_INVALID_TARGET_NAMESPACE
LIBSBML_CONV_PKG_CONVERSION_NOT_AVAILABLE
LIBSBML_CONV_INVALID_SRC_DOCUMENT
LIBSBML_CONV_CONVERSION_NOT_AVAILABLE
LIBSBML_CONV_PKG_CONSIDERED_UNKNOWN
OperationReturnValues_t

SpeciesReferenceRole_t

SpeciesReferenceRole_t is the enumeration of possible values for the 'role' attribute of a SpeciesReferenceGlyph.

The role attribute is of type SpeciesReferenceRole and is used to specify how the species reference should be displayed. Allowed values are 'substrate', 'product', 'sidesubstrate', 'sideproduct', 'modifier', 'activator', 'inhibitor' and 'undefined'.

This attribute is optional and should only be necessary if the optional speciesReference attribute is not given or if the respective information from the model needs to be overridden.

SPECIES_ROLE_UNDEFINED
SPECIES_ROLE_SUBSTRATE
SPECIES_ROLE_PRODUCT
SPECIES_ROLE_SIDESUBSTRATE
SPECIES_ROLE_SIDEPRODUCT
SPECIES_ROLE_MODIFIER
SPECIES_ROLE_ACTIVATOR
SPECIES_ROLE_INHIBITOR
SPECIES_ROLE_INVALID
SpeciesReferenceRole_t

FluxBoundOperation_t

Possible values for the FluxBound 'operation' attribute.

The possible legal values are less than or equal to, greater than or equal to, or equal to. The two options "FLUXBOUND_OPERATION_LESS" and " FLUXBOUND_OPERATION_GREATER" are not legal values for the FluxBound 'operation' attribute, but are provided to allow backwards compatibility with an earlier version of the draft specification.

FLUXBOUND_OPERATION_LESS_EQUAL
FLUXBOUND_OPERATION_GREATER_EQUAL
FLUXBOUND_OPERATION_LESS
FLUXBOUND_OPERATION_GREATER
FLUXBOUND_OPERATION_EQUAL
FLUXBOUND_OPERATION_UNKNOWN
FluxBoundOperation_t

ObjectiveType_t

Enumeration of possible values for the 'type' attribute of an Objective object.

OBJECTIVE_TYPE_MAXIMIZE
OBJECTIVE_TYPE_MINIMIZE
OBJECTIVE_TYPE_UNKNOWN
ObjectiveType_t

GroupKind_t

Enumeration of values permitted as the value of the "kind" attribute on Group objects.

GROUP_KIND_CLASSIFICATION
GROUP_KIND_PARTONOMY
GROUP_KIND_COLLECTION
GROUP_KIND_UNKNOWN
GroupKind_t

BindingStatus_t

Enumeration of possible binding status of a OutwardBindingSite in the libSBML "multi" package implementation.

MULTI_BINDING_STATUS_BOUND
MULTI_BINDING_STATUS_UNBOUND
MULTI_BINDING_STATUS_EITHER
MULTI_BINDING_STATUS_UNKNOWN
BindingStatus_t

Relation_t

Enumeration of possible relations between the children of a SubListOfSpeciesFeatures in the libSBML "multi" package implementation.

MULTI_RELATION_AND
MULTI_RELATION_OR
MULTI_RELATION_NOT
MULTI_RELATION_UNKNOWN
Relation_t

InputTransitionEffect_t

Enumeration of possible values for the 'transitionEffect' attribute of an Input. Must be 'none' or 'consumption'.

INPUT_TRANSITION_EFFECT_NONE
INPUT_TRANSITION_EFFECT_CONSUMPTION
INPUT_TRANSITION_EFFECT_UNKNOWN
InputTransitionEffect_t

InputSign_t

Enumeration of possible values for the 'transitionEffect' attribute of an Input. Must be 'positive', 'negative', 'dual', or 'unknown'.

INPUT_SIGN_POSITIVE
INPUT_SIGN_NEGATIVE
INPUT_SIGN_DUAL
INPUT_SIGN_UNKNOWN
INPUT_SIGN_VALUE_NOTSET
InputSign_t

OutputTransitionEffect_t

Enumeration of possible values for the 'transitionEffect' attribute of an Output.

OUTPUT_TRANSITION_EFFECT_PRODUCTION
OUTPUT_TRANSITION_EFFECT_ASSIGNMENT_LEVEL
OUTPUT_TRANSITION_EFFECT_UNKNOWN
OutputTransitionEffect_t

SpatialKind_t

SpatialKind_t

SPATIALKIND_UNKNOWN
DYN_SPATIALKIND_CARTESIANX
DYN_SPATIALKIND_CARTESIANY
DYN_SPATIALKIND_CARTESIANZ
DYN_SPATIALKIND_ALPHA
DYN_SPATIALKIND_BETA
DYN_SPATIALKIND_GAMMA
DYN_SPATIALKIND_FX
DYN_SPATIALKIND_FY
DYN_SPATIALKIND_FZ
SpatialKind_t

castObject

Cast an object to the given derived type. This method is a built-in feature of Emscripten No type checking is performed. In libsbml.js this method is primarily used to cast SBasePlugin to a derived type such as FbcModelPlugin or CompSBasePlugin.

castObject(object: Object, Class: Type): any
Parameters
object (Object) The object instance
Class (Type) The target type to cast to
Returns
any: The instance cast to the derived type