libSBML Python API  5.11.0
Hierarchical Model Composition

The libSBML “comp” extension implements support for the SBML Level 3 Hierarchical Model Composition package.

Introduction

In the context of SBML, hierarchical model composition refers to the ability to include models as submodels inside another model. The goal is to support the ability of modelers and software tools to do such things as (1) decompose larger models into smaller ones, as a way to manage complexity; (2) incorporate multiple instances of a given model within one or more enclosing models, to avoid literal duplication of repeated elements; and (3) create libraries of reusable, tested models, much as is done in software development and other engineering fields. SBML Level 3 Version 1 Core, by itself, has no direct support for allowing a model to include other models as submodels. The Level 3 Hierarchical Model Composition package adds the missing capabilities. The figure below illustrates some of the scenarios targeted by this package.

Two examples of model configuration supported by the “comp” package: (left) a model composed of a submodel that is itself composed of submodels; (right) a model composed of submodels, one of which is defined in an external file.

The specification for this SBML package

This API documentation for libSBML does not provide a complete explanation of the SBML Level 3 Hierarchical Model Composition (“comp”) package. If you are developing software that uses “comp”, you are strongly urged to read the actual specification for the package. A link to the specification document current is provided below, along with a link to the page of known issues (if any).

Specification for SBML Level 3 Hierarchical Model Composition, current at the time of this libSBML release (5.11.0). Note: an Internet connection is required to access these documents.
Specification (in PDF format) Known issues
Hierarchical Model Composition package, Version 1 Release 3 Errata page
More...

Classes

class  libsbml.CompExtension
 comp Base extension class for the package. More...
 
class  libsbml.CompFlatteningConverter
 comp 'Flattens' a model, removing composition. More...
 
class  libsbml.CompModelPlugin
 comp Extension of Model. More...
 
class  libsbml.CompPkgNamespaces
 comp SBMLNamespaces extension for the package. More...
 
class  libsbml.CompSBasePlugin
 comp Extension of SBase. More...
 
class  libsbml.CompSBMLDocumentPlugin
 comp Extension of SBMLDocument. More...
 
class  libsbml.Deletion
 comp Deletion of an object from a submodel. More...
 
class  libsbml.ExternalModelDefinition
 comp A reference to an externally-defined model. More...
 
class  libsbml.ListOfDeletions
 comp A list of Deletion objects. More...
 
class  libsbml.ListOfExternalModelDefinitions
 comp A list of ExternalModelDefinition objects. More...
 
class  libsbml.ListOfModelDefinitions
 comp A list of ModelDefinition objects. More...
 
class  libsbml.ListOfPorts
 comp A list of Port objects. More...
 
class  libsbml.ListOfReplacedElements
 comp A list of ReplacedElement objects. More...
 
class  libsbml.ListOfSubmodels
 comp A list of Submodel objects. More...
 
class  libsbml.ModelDefinition
 comp A model used in model composition. More...
 
class  libsbml.Port
 comp An interface to be used in composition. More...
 
class  libsbml.ReplacedBy
 comp Indicates an object replaced by another. More...
 
class  libsbml.ReplacedElement
 comp Indicates an object replaces another. More...
 
class  libsbml.Replacing
 comp Convenience class. More...
 
class  libsbml.SBaseRef
 comp Base class for references to objects. More...
 
class  libsbml.SBMLFileResolver
 comp Resolves documents stored on a file system. More...
 
class  libsbml.SBMLResolver
 comp Base class for SBML resolvers. More...
 
class  libsbml.SBMLResolverRegistry
 comp Registry of all SBML resolvers. More...
 
class  libsbml.SBMLUri
 comp Utility class for handling URIs. More...
 
class  libsbml.Submodel
 comp A model instance inside another model. More...
 

Functions

def libsbml.CompSBasePlugin.__init__ (self, args)
 comp Extension of SBase. More...
 
def libsbml.CompModelPlugin.__init__ (self, args)
 comp Extension of Model. More...
 
def libsbml.CompSBMLDocumentPlugin.__init__ (self, args)
 comp Extension of SBMLDocument. More...
 
def libsbml.SBMLUri.__init__ (self, args)
 comp Utility class for handling URIs. More...
 
def libsbml.SBMLResolver.__init__ (self, args)
 comp Base class for SBML resolvers. More...
 
def libsbml.SBMLFileResolver.__init__ (self, args)
 comp Resolves documents stored on a file system. More...
 
def libsbml.CompFlatteningConverter.__init__ (self, args)
 comp 'Flattens' a model, removing composition. More...
 
def libsbml.SBaseRef.__init__ (self, args)
 comp Base class for references to objects. More...
 
def libsbml.Deletion.__init__ (self, args)
 comp Deletion of an object from a submodel. More...
 
def libsbml.ExternalModelDefinition.__init__ (self, args)
 comp A reference to an externally-defined model. More...
 
def libsbml.ModelDefinition.__init__ (self, args)
 comp A model used in model composition. More...
 
def libsbml.Port.__init__ (self, args)
 comp An interface to be used in composition. More...
 
def libsbml.ReplacedBy.__init__ (self, args)
 comp Indicates an object replaced by another. More...
 
def libsbml.ReplacedElement.__init__ (self, args)
 comp Indicates an object replaces another. More...
 
def libsbml.Submodel.__init__ (self, args)
 comp A model instance inside another model. More...
 
def libsbml.ListOfDeletions.clone (self)
 comp A list of Deletion objects. More...
 
def libsbml.ListOfExternalModelDefinitions.clone (self)
 comp A list of ExternalModelDefinition objects. More...
 
def libsbml.ListOfModelDefinitions.clone (self)
 comp A list of ModelDefinition objects. More...
 
def libsbml.ListOfPorts.clone (self)
 comp A list of Port objects. More...
 
def libsbml.ListOfReplacedElements.clone (self)
 comp A list of ReplacedElement objects. More...
 
def libsbml.ListOfSubmodels.clone (self)
 comp A list of Submodel objects. More...
 
def libsbml.SBMLResolverRegistry.getInstance ()
 comp Registry of all SBML resolvers. More...
 
def libsbml.CompExtension.getPackageName ()
 comp Base extension class for the package. More...
 
def libsbml.Replacing.getSubmodelRef (self)
 comp Convenience class. More...
 

Detailed Description

The libSBML “comp” extension implements support for the SBML Level 3 Hierarchical Model Composition package.

Introduction

In the context of SBML, hierarchical model composition refers to the ability to include models as submodels inside another model. The goal is to support the ability of modelers and software tools to do such things as (1) decompose larger models into smaller ones, as a way to manage complexity; (2) incorporate multiple instances of a given model within one or more enclosing models, to avoid literal duplication of repeated elements; and (3) create libraries of reusable, tested models, much as is done in software development and other engineering fields. SBML Level 3 Version 1 Core, by itself, has no direct support for allowing a model to include other models as submodels. The Level 3 Hierarchical Model Composition package adds the missing capabilities. The figure below illustrates some of the scenarios targeted by this package.

Two examples of model configuration supported by the “comp” package: (left) a model composed of a submodel that is itself composed of submodels; (right) a model composed of submodels, one of which is defined in an external file.

The specification for this SBML package

This API documentation for libSBML does not provide a complete explanation of the SBML Level 3 Hierarchical Model Composition (“comp”) package. If you are developing software that uses “comp”, you are strongly urged to read the actual specification for the package. A link to the specification document current is provided below, along with a link to the page of known issues (if any).

Specification for SBML Level 3 Hierarchical Model Composition, current at the time of this libSBML release (5.11.0). Note: an Internet connection is required to access these documents.
Specification (in PDF format) Known issues
Hierarchical Model Composition package, Version 1 Release 3 Errata page

Function Documentation

def libsbml.CompSBasePlugin.__init__ (   self,
  args 
)

comp Extension of SBase.

The CompSBasePlugin class inherits from the SBasePlugin class, and codifies the extentions to the SBase class defined in the Hierarchical Model Composition package (“comp”). This extention 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.

See also
ReplacedElement
ReplacedBy

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

__init__(string uri, string prefix, CompPkgNamespaces compns)   CompSBasePlugin
__init__(CompSBasePlugin orig)   CompSBasePlugin

Each variant is described separately below.


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

Copy constructor. Creates a copy of this CompSBasePlugin object.


Method variant with the following signature:
CompSBasePlugin(stringuri, stringprefix, CompPkgNamespaces compns)

Constructor.

def libsbml.CompModelPlugin.__init__ (   self,
  args 
)

comp Extension of Model.

The CompModelPlugin class inherits from the SBMLSBasePlugin class, and codifies the extentions to the Model class defined in the SBML Level 3 Hierarchical Model Composition package (“comp”). This extention 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.

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

__init__(string uri, string prefix, CompPkgNamespaces compns)   CompModelPlugin
__init__(CompModelPlugin orig)   CompModelPlugin

Each variant is described separately below.


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

Copy constructor. Creates a copy of this CompModelPlugin object.


Method variant with the following signature:
CompModelPlugin(stringuri, stringprefix, CompPkgNamespaces compns)

Constructor.

def libsbml.CompSBMLDocumentPlugin.__init__ (   self,
  args 
)

comp Extension of SBMLDocument.

The CompSBMLDocumentPlugin class inherits from the SBMLDocumentPlugin class, and codifies the extentions to the SBMLDocument class defined in the SBML Level 3 Hierarchical Model Composition

package (“comp”). This extention 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 ModelDefinitions and ExternalModelDefinitions 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.

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

__init__(string uri, string prefix, CompPkgNamespaces compns)   CompSBMLDocumentPlugin
__init__(CompSBMLDocumentPlugin orig)   CompSBMLDocumentPlugin

Each variant is described separately below.


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

Copy constructor. Creates a copy of this CompSBMLDocumentPlugin object.


Method variant with the following signature:
CompSBMLDocumentPlugin(stringuri, stringprefix, CompPkgNamespaces compns)

Constructor.

def libsbml.SBMLUri.__init__ (   self,
  args 
)

comp Utility class for handling URIs.

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

This class implements functionality for parsing URIs and extracting information about them.

See also
SBMLResolver
SBMLFileResolver

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

__init__(string uri)   SBMLUri
__init__(SBMLUri orig)   SBMLUri

Each variant is described separately below.


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

Copy constructor. Creates a copy of an SBMLUri object.

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

Method variant with the following signature:
SBMLUri(string uri)

Creates a new SBMLUri from the given string URI.

def libsbml.SBMLResolver.__init__ (   self,
  args 
)

comp Base class for SBML resolvers.

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

The SBMLResolver class is the base class for the various SBML resolvers: facilities that take a unique identifier as input and return the document associated with that identifier. In SBML, resolvers come into play with the SBML Level 3 Hierarchical Model Composition package; this package includes features that allow a model to be composed from pieces that are external to a given SBML document, which implies the need to be able to identify and locate those external pieces. The SBMLResolver class and its subclasses provide facilities for software applications to be able to do these tasks.

LibSBML provides a number of built-in resolvers, and applications can create their own by subclassing SBMLResolver and following the examples of the existing resolvers. The following are the built-in resolvers in libSBML 5.11.0:

More resolvers may be provided by libSBML in the future. Application authors may also write their own.

See also
SBMLUri

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

__init__()   SBMLResolver
__init__(SBMLResolver c)   SBMLResolver

Each variant is described separately below.


Method variant with the following signature:
SBMLResolver()

Creates a new SBMLResolver object.


Method variant with the following signature:
SBMLResolver(SBMLResolver c)

Copy constructor. Creates a copy of an SBMLResolver object.

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

comp Resolves documents stored on a file system.

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

In SBML, resolvers come into play with the SBML Level 3 Hierarchical Model Composition package (“comp”); this package includes features that allow a model to be composed from pieces that are external to a given SBML document, which implies the need to be able to identify and locate those external pieces. The identifiers used in “comp” are URIs (Uniform Resource Identifiers).

SBMLFileResolver is a class implementing the ability to resolve URIs to files. It works on the local file system only. It can resolve relative and absolute paths, and directories to be searched can be specified using the methodsSBMLFileResolver.addAdditionalDir() and SBMLFileResolver.clearAdditionalDirs().

See also
SBMLResolver
SBMLUri

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

__init__()   SBMLFileResolver
__init__(SBMLFileResolver c)   SBMLFileResolver

Each variant is described separately below.


Method variant with the following signature:
SBMLFileResolver(SBMLFileResolver c)

Copy constructor. Creates a copy of an SBMLFileResolver object.

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

Method variant with the following signature:
SBMLFileResolver()

Creates a new SBMLFileResolver object.

def libsbml.CompFlatteningConverter.__init__ (   self,
  args 
)

comp 'Flattens' a model, removing composition.

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

This converter translates a hierarchical model defined with the SBML Level 3 Hierarchical Model Composition package to a so-called 'flattened' version of the same model. A 'flattened' model is one that results from interpreting the hierarchical structure and creating an equivalent model that does not use any Hierarchical Model Composition package constructs; all of the mathematics of the model remain as intended, but the hierarchical structure is removed. CompFlatteningConverter achieves this by performing the following actions on a model:

  1. Each submodel is instantiated; that is, a copy of every Model object referenced by every Submodel object is created. This is a recursive process: if the instantiated Model itself has Submodel children, they are also instantiated.

  2. The identifier of every component object in every Model that is instantiated is modified by prepending a prefix to it, to make the identifier unique in the overall flattened SBML model. The prefix consists of the Submodel object identifier, plus a small integer if necessary to ensure uniqueness, plus two underscore characters ('__'). Typically, this results in a final identifier of the form SubmodelIdentifier__ObjectIdentifier, where ObjectIdentifier is the object's original identifier and SubmodelIdentifier__ is the prefix. The same process is applied to metaid (meta-identifier) values of every component object as well.

  3. All deleted elements are removed from the model and all instantiated submodels.

  4. All replaced elements are removed from the model and all instantiated submodels.

  5. All references to replaced elements are changed to point to the replacement element instead.

  6. All remaining elements are placed in a single Model object; this Model object is made the new child of the SBMLDocument container. The original Model, ModelDefinition, and ExternalModelDefinition objects are all deleted.

Note an implication of this process is that if conversion is successful, all old pointers to the SBMLDocument object's Model object as well as all of its children, will be rendered obsolete, and will no longer work.

Summary of options for CompFlatteningConverter

CompFlatteningConverter is enabled by creating a ConversionProperties object with the option 'flatten comp', and passing this ConversionProperties object to SBMLDocument.convert(). The CompFlatteningConverter converter accepts numerous options influencing its behavior. The following list briefly summarizes the options:
  • 'flatten comp': Possible values are 'True' or 'False'. Setting the option to True (the default) means enable the flattening converter.

  • 'abortIfUnflattenable': Possible values are 'all', 'requiredOnly' (the default), or 'none'. Controls what happens upon encountering an SBML Level 3 package with no flattener implementation.

  • 'stripUnflattenablePackages': Possible values are 'True' or 'False' (the default). Controls whether the constructs of Level 3 packages with no flattener implementation are stripped from the output.

  • 'basePath': The value must be a string representing the path where the converter should search for any ExternalModelDefinition objects. (Default value: '.', meaning, the current directory.)

  • 'leavePorts': Possible values are 'True' or 'False' (the default). Controls what happens to Port constructs in the output.

  • 'listModelDefinitions': Possible values are 'True' or 'False' (the default). Controls what happens to ModelDefinition and ExternalModelDefinition objects in the final output.

  • 'performValidation': Possible values are 'True' (the default) or 'False'. Controls whether whether libSBML validates the model before attempting to flatten it.

Detailed explanation of available options

The following sections examine in detail the options understood by CompFlatteningConverter and their effects on the flattening process.

Options for handling Level 3 packages that lack flattening algorithms

If other SBML Level 3 packages are used in the SBMLDocument, the same rules apply to each package's constructs if an implementation of the flattener exists for that Level 3 package. If no implementation exists, the behavior of this CompFlatteningConverter depends on the values of the options 'abortIfUnflattenable' and 'stripUnflattenablePackages'. Specifically:

  • The option 'abortIfUnflattenable' controls whether the flattening process is abandoned. The following are the possible values for this option and their meanings:

    • If the 'abortIfUnflattenable' option is set to 'all', then if any construct is found for a package that has no flattening algorithm available, the converter will abort, return failure, and avoid changing the original SBMLDocument object.

    • If 'abortIfUnflattenable' is set to 'requiredOnly' (the default), then if any SBML Level 3 package construct is found for a package that is labeled 'required=true' and for which no flattening algorithm is available, the converter will abort, return failure, and avoid changing the original SBMLDocument object. SBML Level 3 package constructs from packages set 'required=false' for which no flattening algorithm is implemented will be ignored and the constructs will be kept or removed depending on the value of the 'stripUnflattenablePackages' option described below.

    • If 'abortIfUnflattenable' is set to 'none', constructs from all unflattenable SBML Level 3 packages will be ignored, and their constructs will be kept or removed depending on the value of the 'stripUnflattenablePackages' option.

  • The option 'stripUnflattenablePackages' controls whether SBML Level 3 package constructs are removed from the final flattened model. The following are the possible values for this option and their meanings:

    • If the option 'stripUnflattenablePackages' is set to 'True', and the option 'abortIfUnflattenable' has the value 'requireOnly' or 'none', then CompFlatteningConverter will remove all constructs belonging to packages that lack a flattening converter. The XML namespace declaration for unflattenable SBML Level 3 packages will also be removed.

    • If the option 'stripUnflattenablePackages' is set to 'False' (the default), CompFlatteningConverter will leave any package constructs that cannot be flattened due to the lack of a flattening implementation. These Level 3 package constructs will remain in the final model. Note that any package constructs from an instantiated Submodel object that was not a child of a retained component will be lost (because the SBML component where it was located was removed from the final, flattened model).

Additional general conversion options for CompFlatteningConverter

The following are other, general options offered by CompFlatteningConverter:

  • 'basePath': if there are ExternalModelDefinition objects that are to be instantiated in a flattened Submodel, the 'basePath' option may be set to a location where those external models may be found. The default is the working directory ('.').
  • 'leavePorts': if this option is set to 'False' (the default), the flattened model will have no Port objects in it. Conversely, if 'leavePorts' is set to 'True', any Port objects not referenced by any Replacement or Deletion will be left in the resulting flattened Model.
  • 'performValidation': if this option is set to 'True' (the default), the SBMLDocument will first be validated before flattening is attempted. If there are any validation errors, those errors will be logged with the SBMLDocument, which will remain otherwise unchanged, and the conversion process will return a failure code. Similarly, if the flattened Model is not valid, those validation errors will be added to the SBMLDocument, which will remain otherwise unchanged, and the conversion attempt will return failure. Conversely, if the option 'performValidation' is set to 'False', the SBMLDocument will be flattened regardless of any validation errors. The conversion may yet fail if insurmountable errors are encountered in the course of trying to flatten the model (for instance, if an element is replaced by something that does not exist), but no separate validation steps are performed.

Note that if both the option 'leavePorts' and 'listModelDefinitions' are set to 'False' (which they are by default), the Hierarchical Model Composition namespace will be removed from the resulting SBMLDocument.

Complete example of invoking CompFlatteningConverter

In this section, we present a complete example of a program that can take an SBML model containing Level 3 Hierarchical Model Composition constructs and flatten it to a plain SBML Level 3 model. A version of this program is available in the libSBML distribution's examples/python/comp directory as the program named flattenModel.py 'flattenModel.py'. The example XML models shown below are the same models as given in sections 4.1–4.2 in the specification document for SBML Level 3 Hierarchical Model Composition.

Example program

For brevity, we do not give the general scaffolding that a real program would have (such as inclusion of header files, command-line argument checks, additional error checks throughout the code, and so on), and focus instead on the parts relevant to an application using the libSBML 'comp' extension.

First, our program checks that this copy of libSBML has the 'comp' extension available. The process for doing that simply involves a call to the extension registry in libSBML:

1 if not SBMLExtensionRegistry.isPackageEnabled('comp'):
2 err_msg = 'This copy of libSBML does not contain the 'comp' extension.'
3 raise SystemExit(err_msg)

Next, we read the SBML input file. For this example, we simply assume that the path to the file is given as the first argument to the program; a real program would perform more sophisticated command-line argument processing and error checking.

1 reader = SBMLReader()
2 sbmldoc = reader.readSBML(args[1])
3 if sbmldoc.getNumErrors() > 0:
4 sbmldoc.printErrors()
5 raise SystemExit(2)

Continuing, we set up options for the call to the converter. The use of ConversionProperties and the general scheme behind conversion options is explained further below; for the purposes of this example, it is enough to know that the following are the basic lines of code needed to obtain a copy of a libSBML converter object that will invoke CompFlatteningConverter:

1 props = ConversionProperties()
2 props.addOption('flatten comp', True) # Invokes CompFlatteningConverter

Now comes the actual invocation of CompFlatteningConverter. As always, it is critical to check for possible errors by checking the status code returned by the call; we do this in the code below too.

1 result = sbmldoc.convert(props)
2 if (result != LIBSBML_OPERATION_SUCCESS):
3 sbmldoc.printErrors()
4 raise SystemExit('Conversion failed... ('+ str(result) + ')')

If successful, we simply write out the resulting flattened model to an output file which, for the purposes of this simple example, we assume is indicated by the second argument handed to the program on the command line by the user.

1 writer = SBMLWriter()
2 check(writer, 'create an SBMLWriter object.')
3 writer.writeSBML(sbmldoc, output_file)
4 print('Flattened model written to %s' % (output_file))

Example use of the program

What is the result of the above on an actual model? Suppose we have the following SBML Level 3 model stored in a file named 'enzyme_model.xml':

<?xml version="1.0" encoding="UTF-8"?>
<sbml xmlns="http://www.sbml.org/sbml/level3/version1/core" level="3" version="1"
      xmlns:comp="http://www.sbml.org/sbml/level3/version1/comp/version1" comp:required="true">

  <model id="aggregate">
    <comp:listOfSubmodels>
      <comp:submodel comp:id="submod1" comp:modelRef="enzyme"/>
      <comp:submodel comp:id="submod2" comp:modelRef="enzyme"/>
    </comp:listOfSubmodels>
  </model>
  <comp:listOfModelDefinitions>
    <comp:modelDefinition id="enzyme" name="enzyme">
      <listOfCompartments>
        <compartment id="compartment" spatialDimensions="3" size="1" constant="true"/>
      </listOfCompartments>
      <listOfSpecies>
        <species id="S"  compartment="compartment" hasOnlySubstanceUnits="false"
                         boundaryCondition="false" constant="false"/>
        <species id="E"  compartment="compartment" hasOnlySubstanceUnits="false" 
                         boundaryCondition="false" constant="false"/>
        <species id="D"  compartment="compartment" hasOnlySubstanceUnits="false" 
                         boundaryCondition="false" constant="false"/>
        <species id="ES" compartment="compartment" hasOnlySubstanceUnits="false"
                         boundaryCondition="false" constant="false"/>
      </listOfSpecies>
      <listOfReactions>
        <reaction id="J0" reversible="true" fast="false">
          <listOfReactants>
            <speciesReference species="S" stoichiometry="1" constant="true"/>
            <speciesReference species="E" stoichiometry="1" constant="true"/>
          </listOfReactants>
          <listOfProducts>
            <speciesReference species="ES" stoichiometry="1" constant="true"/>
          </listOfProducts>
        </reaction>
        <reaction id="J1" reversible="true" fast="false">
          <listOfReactants>
            <speciesReference species="ES" stoichiometry="1" constant="true"/>
          </listOfReactants>
          <listOfProducts>
            <speciesReference species="E" stoichiometry="1" constant="true"/>
            <speciesReference species="D" stoichiometry="1" constant="true"/>
          </listOfProducts>
        </reaction>
      </listOfReactions>
    </comp:modelDefinition>
  </comp:listOfModelDefinitions>
</sbml>

Also suppose we have the following SBML Level 3 model stored in a file called 'main.xml' in the same directory as the file above. The model below imports the model 'enzyme' from the model file above twice; this is used to create two submodels whose identifiers are 'A' and 'B'.

<?xml version="1.0" encoding="UTF-8"?>
<sbml xmlns="http://www.sbml.org/sbml/level3/version1/core" level="3" version="1"
      xmlns:comp="http://www.sbml.org/sbml/level3/version1/comp/version1" comp:required="true">
  <model>
    <listOfCompartments>
      <compartment id="compartment" spatialDimensions="3" size="1" constant="true">
        <comp:listOfReplacedElements>
          <comp:replacedElement comp:idRef="compartment" comp:submodelRef="A"/>
          <comp:replacedElement comp:idRef="compartment" comp:submodelRef="B"/>
        </comp:listOfReplacedElements>
      </compartment>
    </listOfCompartments>
    <listOfSpecies>
      <species id="S" compartment="compartment" hasOnlySubstanceUnits="false"
                      boundaryCondition="false" constant="false">
        <comp:listOfReplacedElements>
          <comp:replacedElement comp:idRef="S" comp:submodelRef="A"/>
          <comp:replacedElement comp:idRef="S" comp:submodelRef="B"/>
        </comp:listOfReplacedElements>
      </species>
    </listOfSpecies>
    <comp:listOfSubmodels>
      <comp:submodel comp:id="A" comp:modelRef="ExtMod1"/>
      <comp:submodel comp:id="B" comp:modelRef="ExtMod1"/>
    </comp:listOfSubmodels>
  </model>
  <comp:listOfExternalModelDefinitions>
    <comp:externalModelDefinition comp:id="ExtMod1" comp:source="enzyme_model.xml"
                                  comp:modelRef="enzyme"/>
  </comp:listOfExternalModelDefinitions>
</sbml>

Finally, invoking the example program developed the previous section on the file 'main.xml', we would obtain the following XML output as result a result

<?xml version="1.0" encoding="UTF-8"?>
<sbml xmlns="http://www.sbml.org/sbml/level3/version1/core" level="3" version="1">
  <model>
    <listOfCompartments>
      <compartment id="compartment" spatialDimensions="3" size="1" constant="true"/>
    </listOfCompartments>
    <listOfSpecies>
      <species id="S"     compartment="compartment" hasOnlySubstanceUnits="false"
                          boundaryCondition="false" constant="false"/>
      <species id="A__E"  compartment="compartment" hasOnlySubstanceUnits="false"
                          boundaryCondition="false" constant="false"/>
      <species id="A__D"  compartment="compartment" hasOnlySubstanceUnits="false"
                          boundaryCondition="false" constant="false"/>
      <species id="A__ES" compartment="compartment" hasOnlySubstanceUnits="false"
                          boundaryCondition="false" constant="false"/>
      <species id="B__E"  compartment="compartment" hasOnlySubstanceUnits="false"
                          boundaryCondition="false" constant="false"/>
      <species id="B__D"  compartment="compartment" hasOnlySubstanceUnits="false"
                          boundaryCondition="false" constant="false"/>
      <species id="B__ES" compartment="compartment" hasOnlySubstanceUnits="false"
                          boundaryCondition="false" constant="false"/>
    </listOfSpecies>
    <listOfReactions>
      <reaction id="A__J0" reversible="true" fast="false">
        <listOfReactants>
          <speciesReference species="S" stoichiometry="1" constant="true"/>
          <speciesReference species="A__E" stoichiometry="1" constant="true"/>
        </listOfReactants>
        <listOfProducts>
          <speciesReference species="A__ES" stoichiometry="1" constant="true"/>
        </listOfProducts>
      </reaction>
      <reaction id="A__J1" reversible="true" fast="false">
        <listOfReactants>
          <speciesReference species="A__ES" stoichiometry="1" constant="true"/>
        </listOfReactants>
        <listOfProducts>
          <speciesReference species="A__E" stoichiometry="1" constant="true"/>
          <speciesReference species="A__D" stoichiometry="1" constant="true"/>
        </listOfProducts>
      </reaction>
      <reaction id="B__J0" reversible="true" fast="false">
        <listOfReactants>
          <speciesReference species="S" stoichiometry="1" constant="true"/>
          <speciesReference species="B__E" stoichiometry="1" constant="true"/>
        </listOfReactants>
        <listOfProducts>
          <speciesReference species="B__ES" stoichiometry="1" constant="true"/>
        </listOfProducts>
      </reaction>
      <reaction id="B__J1" reversible="true" fast="false">
        <listOfReactants>
          <speciesReference species="B__ES" stoichiometry="1" constant="true"/>
        </listOfReactants>
        <listOfProducts>
          <speciesReference species="B__E" stoichiometry="1" constant="true"/>
          <speciesReference species="B__D" stoichiometry="1" constant="true"/>
        </listOfProducts>
      </reaction>
    </listOfReactions>
  </model>
</sbml>

The final model is a concrete realization of the effective model defined by 'main.xml', with a single compartment and two reactions; the species 'S' can either bind with enzyme 'E' (from submodel 'A') to form 'D' (from submodel 'A'), or with enzyme 'E' (from submodel 'B') to form 'D' (from submodel 'B'). In the flattened model above, note how the identifiers of components inside the ModelDefinition objects 'A' and 'B' of our file 'enzyme_model.xml' have been rewritten as (for example) 'A__E' 'B__E', etc.

General information about the use of SBML converters

The use of all the converters follows a similar approach. First, one creates a ConversionProperties object and calls ConversionProperties.addOption() on this object with one arguments: a text string that identifies the desired converter. (The text string is specific to each converter; consult the documentation for a given converter to find out how it should be enabled.)

Next, for some converters, the caller can optionally set some converter-specific properties using additional calls to ConversionProperties.addOption(). Many converters provide the ability to configure their behavior to some extent; this is realized through the use of properties that offer different options. The default property values for each converter can be interrogated using the method SBMLConverter.getDefaultProperties() on the converter class in question .

Finally, the caller should invoke the method SBMLDocument.convert() with the ConversionProperties object as an argument.

Example of invoking an SBML converter

The following code fragment illustrates an example using SBMLReactionConverter, which is invoked using the option string 'replaceReactions':

1 config = ConversionProperties()
2 if config != None:
3  config.addOption('replaceReactions')

In the case of SBMLReactionConverter, there are no options to affect its behavior, so the next step is simply to invoke the converter on an SBMLDocument object. Continuing the example code:

1  # Assume that the variable 'document' has been set to an SBMLDocument object.
2  status = document.convert(config)
3  if status != LIBSBML_OPERATION_SUCCESS:
4 # Handle error somehow.
5 print('Error: conversion failed due to the following:')
6 document.printErrors()

Here is an example of using a converter that offers an option. The following code invokes SBMLStripPackageConverter to remove the SBML Level 3 Layout package from a model. It sets the name of the package to be removed by adding a value for the option named 'package' defined by that converter:

1 def strip_layout_example(document):
2  config = ConversionProperties()
3  if config != None:
4 config.addOption('stripPackage')
5 config.addOption('package', 'layout')
6 status = document.convert(config)
7 if status != LIBSBML_OPERATION_SUCCESS:
8  # Handle error somehow.
9  print('Error: unable to strip the Layout package.')
10  print('LibSBML returned error: ' + OperationReturnValue_toString(status).strip())
11  else:
12 # Handle error somehow.
13 print('Error: unable to create ConversionProperties object')

Available SBML converters in libSBML

LibSBML provides a number of built-in converters; by convention, their names end in Converter. The following are the built-in converters provided by libSBML 5.11.0:

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

__init__()   CompFlatteningConverter
__init__(CompFlatteningConverter orig)   CompFlatteningConverter

Each variant is described separately below.


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

Copy constructor.

This creates a copy of a CompFlatteningConverter object.

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

Method variant with the following signature:
CompFlatteningConverter()

Creates a new CompFlatteningConverter object.

def libsbml.SBaseRef.__init__ (   self,
  args 
)

comp Base class for references to objects.

The SBaseRef class was introduced by the SBML Level 3 Hierarchical Model Composition package (“comp”) 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 constructed 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 constructed 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 being constructed 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 be constructed 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.

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

__init__(long level, long version, long pkgVersion)   SBaseRef
__init__(long level, long version)   SBaseRef
__init__(long level)   SBaseRef
__init__()   SBaseRef
__init__(CompPkgNamespaces compns)   SBaseRef
__init__(SBaseRef source)   SBaseRef

Each variant is described separately below.


Method variant with the following signature:
SBaseRef(SBaseRef source)

Copy constructor.


Method variant with the following signature:
SBaseRef(CompPkgNamespaces compns)

Creates a new SBaseRef with the given CompPkgNamespaces object.

Parameters
compnsthe namespace to use

Method variant with the following signature:
SBaseRef(long level = CompExtension.getDefaultLevel(), long version = CompExtension.getDefaultVersion(), long pkgVersion = CompExtension.getDefaultPackageVersion())

Creates a new SBaseRef with the given level, version, and package version.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
pkgVersionthe version of the package
def libsbml.Deletion.__init__ (   self,
  args 
)

comp Deletion of an object from a submodel.

The Deletion class was introduced by the SBML Level 3 Hierarchical Model Composition package (“comp”) 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.

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

__init__(long level, long version, long pkgVersion)   Deletion
__init__(long level, long version)   Deletion
__init__(long level)   Deletion
__init__()   Deletion
__init__(CompPkgNamespaces compns)   Deletion
__init__(Deletion source)   Deletion

Each variant is described separately below.


Method variant with the following signature:
Deletion(Deletion source)

Copy constructor.


Method variant with the following signature:
Deletion(CompPkgNamespaces compns)

Creates a new Deletion with the given CompPkgNamespaces object.


Method variant with the following signature:
Deletion(long level = CompExtension.getDefaultLevel(), long version = CompExtension.getDefaultVersion(), long pkgVersion = CompExtension.getDefaultPackageVersion())

Creates a new Deletion with the given level, version, and package version.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
pkgVersionthe version of the package
def libsbml.ExternalModelDefinition.__init__ (   self,
  args 
)

comp A reference to an externally-defined model.

The ExternalModelDefinition class was introduced by the SBML Level 3 Hierarchical Model Composition package (“comp”) 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 Version 1 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.

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.

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

__init__(long level, long version, long pkgVersion)   ExternalModelDefinition
__init__(long level, long version)   ExternalModelDefinition
__init__(long level)   ExternalModelDefinition
__init__()   ExternalModelDefinition
__init__(CompPkgNamespaces compns)   ExternalModelDefinition
__init__(ExternalModelDefinition source)   ExternalModelDefinition

Each variant is described separately below.


Method variant with the following signature:
ExternalModelDefinition(ExternalModelDefinition source)

Copy constructor.

Parameters
sourcethe object to copy.

Method variant with the following signature:
ExternalModelDefinition(CompPkgNamespaces compns)

Creates a new ExternalModelDefinition with the given CompPkgNamespaces object.

Parameters
compnsthe namespace to use.

Method variant with the following signature:
ExternalModelDefinition(long level = CompExtension.getDefaultLevel(), long version = CompExtension.getDefaultVersion(), long pkgVersion = CompExtension.getDefaultPackageVersion())

Creates a new ExternalModelDefinition with the given level, version, and package version.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
pkgVersionthe version of the package
def libsbml.ModelDefinition.__init__ (   self,
  args 
)

comp A model used in model composition.

The Hierarchical Model Composition package (“comp”) 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 ModelDefintion, it must also be unique across all Model, ModelDefinition, and ExternalModelDefinition objects in the same SBMLDocument.

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

__init__(long level, long version, long pkgVersion)   ModelDefinition
__init__(long level, long version)   ModelDefinition
__init__(long level)   ModelDefinition
__init__()   ModelDefinition
__init__(CompPkgNamespaces compns)   ModelDefinition
__init__(Model source)   ModelDefinition

Each variant is described separately below.


Method variant with the following signature:
ModelDefinition(Model source)

Copy constructor from base Model object.


Method variant with the following signature:
ModelDefinition(CompPkgNamespaces compns)

Creates a new ModelDefinition with the given CompPkgNamespaces object.

Parameters
compnsthe namespace to use

Method variant with the following signature:
ModelDefinition(long level = CompExtension.getDefaultLevel(), long version = CompExtension.getDefaultVersion(), long pkgVersion = CompExtension.getDefaultPackageVersion())

Creates a new ModelDefinition with the given level, version, and package version.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
pkgVersionthe version of the package
def libsbml.Port.__init__ (   self,
  args 
)

comp An interface to be used in composition.

The Port class was introduced by the SBML Level 3 Hierarchical Model Composition package (“comp”) 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.

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

__init__(long level, long version, long pkgVersion)   Port
__init__(long level, long version)   Port
__init__(long level)   Port
__init__()   Port
__init__(CompPkgNamespaces compns)   Port
__init__(Port source)   Port

Each variant is described separately below.


Method variant with the following signature:
Port(Port source)

Copy constructor.


Method variant with the following signature:
Port(CompPkgNamespaces compns)

Creates a new Port with the given CompPkgNamespaces object.

Parameters
compnsthe namespace to use

Method variant with the following signature:
Port(long level = CompExtension.getDefaultLevel(), long version = CompExtension.getDefaultVersion(), long pkgVersion = CompExtension.getDefaultPackageVersion())

Creates a new Port with the given level, version, and package version.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
pkgVersionthe version of the package
def libsbml.ReplacedBy.__init__ (   self,
  args 
)

comp Indicates an object replaced by another.

The ReplacedBy class was introduced by the SBML Level 3 Hierarchical Model Composition

package (“comp”) 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.

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

__init__(long level, long version, long pkgVersion)   ReplacedBy
__init__(long level, long version)   ReplacedBy
__init__(long level)   ReplacedBy
__init__()   ReplacedBy
__init__(CompPkgNamespaces compns)   ReplacedBy
__init__(ReplacedBy source)   ReplacedBy

Each variant is described separately below.


Method variant with the following signature:
ReplacedBy(CompPkgNamespaces compns)

Creates a new ReplacedBy with the given CompPkgNamespaces object.

Parameters
compnsthe namespace to use

Method variant with the following signature:
ReplacedBy(ReplacedBy source)

Copy constructor.


Method variant with the following signature:
ReplacedBy(long level = CompExtension.getDefaultLevel(), long version = CompExtension.getDefaultVersion(), long pkgVersion = CompExtension.getDefaultPackageVersion())

Creates a new ReplacedBy with the given level, version, and package version.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
pkgVersionthe version of the package
def libsbml.ReplacedElement.__init__ (   self,
  args 
)

comp Indicates an object replaces another.

The ReplacedElement class was introduced by the SBML Level 3 Hierarchical Model Composition package (“comp”) 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.

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

__init__(long level, long version, long pkgVersion)   ReplacedElement
__init__(long level, long version)   ReplacedElement
__init__(long level)   ReplacedElement
__init__()   ReplacedElement
__init__(CompPkgNamespaces compns)   ReplacedElement
__init__(ReplacedElement source)   ReplacedElement

Each variant is described separately below.


Method variant with the following signature:
ReplacedElement(ReplacedElement source)

Copy constructor.


Method variant with the following signature:
ReplacedElement(CompPkgNamespaces compns)

Creates a new ReplacedElement with the given CompPkgNamespaces object.

Parameters
compnsthe namespace to use

Method variant with the following signature:
ReplacedElement(long level = CompExtension.getDefaultLevel(), long version = CompExtension.getDefaultVersion(), long pkgVersion = CompExtension.getDefaultPackageVersion())

Creates a new ReplacedElement with the given level, version, and package version.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
pkgVersionthe version of the package
def libsbml.Submodel.__init__ (   self,
  args 
)

comp A model instance inside another model.

The Submodel class was introduced by the SBML Level 3 Hierarchical Model Composition package (“comp”) 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 provides constructs 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 constant 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 core construct 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 constant 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.

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

__init__(long level, long version, long pkgVersion)   Submodel
__init__(long level, long version)   Submodel
__init__(long level)   Submodel
__init__()   Submodel
__init__(CompPkgNamespaces compns)   Submodel
__init__(Submodel source)   Submodel

Each variant is described separately below.


Method variant with the following signature:
Submodel(CompPkgNamespaces compns)

Creates a new Submodel with the given CompPkgNamespaces object.

Parameters
compnsthe namespace to use

Method variant with the following signature:
Submodel(long level = CompExtension.getDefaultLevel(), long version = CompExtension.getDefaultVersion(), long pkgVersion = CompExtension.getDefaultPackageVersion())

Creates a new Submodel with the given level, version, and package version.

Parameters
levelthe SBML Level
versionthe Version within the SBML Level
pkgVersionthe version of the package

Method variant with the following signature:
Submodel(Submodel source)

Copy constructor.

def libsbml.ListOfDeletions.clone (   self)

comp A list of Deletion objects.

The ListOfDeletions is a container for the “comp” Submodel that defines elements to be removed before instantiation.

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

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

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

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents
Deletion
ListOfExternalModelDefinitions
ListOfModelDefinitions
ListOfPorts
ListOfReplacedElements
ListOfSubmodels

Creates and returns a deep copy of this ListOfDeletions object.

clone()   ListOfDeletions
Returns
a (deep) copy of this ListOfDeletions.
def libsbml.ListOfExternalModelDefinitions.clone (   self)

comp A list of ExternalModelDefinition objects.

The ListOfExternalModelDefinitions is a container for the extended SBMLDocument that defines references to Models defined in external files.

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

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

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

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents
ExternalModelDefinition
ListOfDeletions
ListOfModelDefinitions
ListOfPorts
ListOfReplacedElements
ListOfSubmodels

Creates and returns a deep copy of this ListOfExternalModelDefinitions object.

clone()   ListOfExternalModelDefinitions
Returns
a (deep) copy of this ListOfExternalModelDefinitions.
def libsbml.ListOfModelDefinitions.clone (   self)

comp A list of ModelDefinition objects.

The ListOfModelDefinitions is a container for the extended SBMLDocument that allows one to define multiple Models in a single file for use in Submodel objects.

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

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

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

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents
ModelDefinition
ListOfDeletions
ListOfExternalModelDefinitions
ListOfPorts
ListOfReplacedElements
ListOfSubmodels

Creates and returns a deep copy of this ListOfModelDefinitions object.

clone()   ListOfModelDefinitions
Returns
a (deep) copy of this ListOfModelDefinitions.
def libsbml.ListOfPorts.clone (   self)

comp A list of Port objects.

The ListOfPorts is a container for the extended Model for Port objects for that Model.

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

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

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

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents
Port
ListOfDeletions
ListOfExternalModelDefinitions
ListOfModelDefinitions
ListOfReplacedElements
ListOfSubmodels

Creates and returns a deep copy of this ListOfPorts object.

clone()   ListOfPorts
Returns
a (deep) copy of this ListOfPorts.
def libsbml.ListOfReplacedElements.clone (   self)

comp A list of ReplacedElement objects.

The ListOfReplacedElements is a container for any SBase object. It contains ReplacedElement objects, which point to elements the parent SBase object is to replace.

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

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

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

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents
ReplacedElement
ListOfDeletions
ListOfExternalModelDefinitions
ListOfModelDefinitions
ListOfPorts
ListOfSubmodels

Creates and returns a deep copy of this ListOfReplacedElements object.

clone()   ListOfReplacedElements
Returns
a (deep) copy of this ListOfReplacedElements.
def libsbml.ListOfSubmodels.clone (   self)

comp A list of Submodel objects.

The ListOfSubmodels is a container for the extended Model that contains Submodel objects to be instantiated in that Model.

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

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

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

See also
ListOfFunctionDefinitions
ListOfUnitDefinitions
ListOfCompartmentTypes
ListOfSpeciesTypes
ListOfCompartments
ListOfSpecies
ListOfParameters
ListOfInitialAssignments
ListOfRules
ListOfConstraints
ListOfReactions
ListOfEvents
Submodel
ListOfDeletions
ListOfExternalModelDefinitions
ListOfModelDefinitions
ListOfPorts
ListOfReplacedElements

Creates and returns a deep copy of this ListOfSubmodels object.

clone()   ListOfSubmodels
Returns
a (deep) copy of this ListOfSubmodels.
def libsbml.SBMLResolverRegistry.getInstance ( )

comp Registry of all SBML resolvers.

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

LibSBML provides facilities for resolving SBML documents in various ways from a given URI. Resolvers are implemented as objects derived from the class SBMLResolver.

The resolver registry maintains a list of known resolvers and provides methods for discovering them. It is implemented as a singleton object of class SBMLResolverRegistry. Callers can use the method SBMLResolverRegistry.getNumResolvers() to find out how many resolvers are registered, then use SBMLResolverRegistry.getResolverByIndex() to iterate over each one;

See also
SBMLFileResolver

Returns the singleton instance for the resolver registry.

getInstance()   SBMLResolverRegistry

Prior to using the registry, callers have to obtain a copy of the registry. This static method provides the means for doing that.

Returns
the singleton for the resolver registry.
def libsbml.CompExtension.getPackageName ( )

comp Base extension class for the package.

Returns the nickname of the SBML Level 3 package implemented by this libSBML extension.

getPackageName()   string
Returns
the package nickname, as a string.
Note
Because this is a static method on a class, the Python language interface for libSBML will contain two variants. One will be the expected, normal static method on the class (i.e., a regular methodName), and the other will be a standalone top-level function with the name ClassName_methodName(). This is merely an artifact of how the language interfaces are created in libSBML. The methods are functionally identical.
def libsbml.Replacing.getSubmodelRef (   self)

comp Convenience class.

The Replacing class does not exist officialy in the the Hierarchical Model Composition package (“comp”), 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.

Returns the value of the 'submodelRef' attribute of this SBaseRef.

getSubmodelRef()   string
Returns
the value of the 'submodelRef' attribute of this SBaseRef.