libSBML C++ API  libSBML 5.12.0 C++ API
Submodel Class Reference
Inheritance diagram for Submodel:
[legend]

Detailed Description

{comp}

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.

Examples:
spec_example1.cpp, spec_example2.cpp, spec_example3.cpp, and spec_example4.cpp.

Public Member Functions

int addDeletion (const Deletion *deletion)
 Adds a copy of the given Deletion object to the list of deletions. More...
 
virtual void clearInstantiation ()
 Delete the instantiated Model, if it exists. More...
 
virtual Submodelclone () const
 Creates and returns a deep copy of this Submodel object. More...
 
virtual int convertTimeAndExtent ()
 Convert all references to time and extent in the instantiated Model, according to the timeConversionFactor and extentConversionFactor attributes. More...
 
DeletioncreateDeletion ()
 Creates a Deletion object, adds it to the end of the deletion objects list and returns a pointer to the newly created object. More...
 
virtual ListgetAllElements (ElementFilter *filter=NULL)
 Returns a List of all child SBase objects, including those nested to an arbitrary depth. More...
 
virtual ListgetAllInstantiatedElements ()
 Get all instantiated sub-elements, including any elements from instantiated submodels, etc. More...
 
DeletiongetDeletion (unsigned int n)
 Returns the deletion with the given index. More...
 
const DeletiongetDeletion (unsigned int n) const
 Returns the deletion with the given index. More...
 
DeletiongetDeletion (std::string id)
 Returns the deletion with the given id. More...
 
const DeletiongetDeletion (std::string id) const
 Returns the deletion with the given id. More...
 
virtual SBasegetElementByMetaId (const std::string &metaid)
 Returns the first child element it can find with the given metaid, or itself if it has the given metaid, or NULL if no such object is found. More...
 
virtual SBasegetElementBySId (const std::string &id)
 Returns the first child element found that has the given id in the model-wide SId namespace, or NULL if no such object is found. More...
 
virtual const std::string & getElementName () const
 Returns the XML element name of this SBML object. More...
 
virtual const std::string & getExtentConversionFactor () const
 Returns the value of the "extentConversionFactor" attribute of this Submodel. More...
 
virtual const std::string & getId () const
 Returns the value of the "id" attribute of this Submodel. More...
 
virtual ModelgetInstantiation ()
 Get the instantiated Model this Submodel contains rules to create. More...
 
virtual const ModelgetInstantiation () const
 Get the instantiated Model this Submodel contains rules to create. More...
 
const ListOfDeletionsgetListOfDeletions () const
 Returns the ListOf object that holds all deletions. More...
 
ListOfDeletionsgetListOfDeletions ()
 Returns the ListOf object that holds all deletions. More...
 
virtual const std::string & getModelRef () const
 Returns the value of the "modelRef" attribute of this Submodel. More...
 
virtual const std::string & getName () const
 Returns the value of the "name" attribute of this Submodel. More...
 
unsigned int getNumDeletions () const
 Returns the number of deletions for this Submodel. More...
 
virtual const std::string & getSubstanceConversionFactor () const
 Returns an empty string, since "substanceConversionFactor" is not a part of the comp spec. More...
 
virtual const std::string & getTimeConversionFactor () const
 Returns the value of the "timeConversionFactor" attribute of this Submodel. More...
 
virtual int getTypeCode () const
 Returns the libSBML type code of this object instance. More...
 
virtual bool hasRequiredAttributes () const
 Returns true if the 'submodel' attribute is set, and if getNumReferents() is exactly 1. More...
 
virtual int instantiate ()
 Find and create a local copy of the Model object referenced by this Submodel. More...
 
virtual bool isSetExtentConversionFactor () const
 Predicate returning true or false depending on whether this Submodel's "extentConversionFactor" attribute has been set. More...
 
virtual bool isSetId () const
 Predicate returning true or false depending on whether this Submodel's "id" attribute has been set. More...
 
virtual bool isSetModelRef () const
 Predicate returning true or false depending on whether this Submodel's "modelRef" attribute has been set. More...
 
virtual bool isSetName () const
 Predicate returning true or false depending on whether this Submodel's "name" attribute has been set. More...
 
virtual bool isSetSubstanceConversionFactor () const
 Returns false, since "substanceConversionFactor" is not a part of the comp spec. More...
 
virtual bool isSetTimeConversionFactor () const
 Predicate returning true or false depending on whether this Submodel's "timeConversionFactor" attribute has been set. More...
 
Submodeloperator= (const Submodel &source)
 Assignment operator. More...
 
virtual int performDeletions ()
 Delete elements in the instantiated submodel, based on any Deletions from this Submodel's listOfDeletions. More...
 
DeletionremoveDeletion (unsigned int index)
 Removes the deletion with the given index from the Submodel. More...
 
DeletionremoveDeletion (const std::string &sid)
 Removes the deletion with the given identifier from the Submodel. More...
 
virtual void renameSIdRefs (const std::string &oldid, const std::string &newid)
 Renames the conversion factor attributes on this element if oldid matches. More...
 
virtual int replaceElement (SBase *toReplace, SBase *replacement)
 Delete the element in question from the stored instantiated Model, and replace all references to it with references to the replacement object. More...
 
virtual int setExtentConversionFactor (const std::string &id)
 Sets the value of the "extentConversionFactor" attribute of this Submodel. More...
 
virtual int setId (const std::string &id)
 Sets the value of the "id" attribute of this Submodel. More...
 
virtual int setModelRef (const std::string &modelRef)
 Sets the value of the "modelRef" attribute of this Submodel. More...
 
virtual int setName (const std::string &name)
 Sets the value of the "name" attribute of this Submodel. More...
 
virtual int setSubstanceConversionFactor (const std::string &id)
 Automatically fails, since "substanceConversionFactor" is not a part of the comp spec. More...
 
virtual int setTimeConversionFactor (const std::string &id)
 Sets the value of the "timeConversionFactor" attribute of this Submodel. More...
 
 Submodel (unsigned int level=CompExtension::getDefaultLevel(), unsigned int version=CompExtension::getDefaultVersion(), unsigned int pkgVersion=CompExtension::getDefaultPackageVersion())
 Creates a new Submodel with the given level, version, and package version. More...
 
 Submodel (CompPkgNamespaces *compns)
 Creates a new Submodel with the given CompPkgNamespaces object. More...
 
 Submodel (const Submodel &source)
 Copy constructor. More...
 
virtual int unsetExtentConversionFactor ()
 Unsets the value of the "extentConversionFactor" attribute of this Submodel. More...
 
virtual int unsetId ()
 Unsets the value of the "id" attribute of this Submodel. More...
 
virtual int unsetModelRef ()
 Unsets the value of the "modelRef" attribute of this Submodel. More...
 
virtual int unsetName ()
 Unsets the value of the "name" attribute of this Submodel. More...
 
virtual int unsetSubstanceConversionFactor ()
 Automatically fails, since "substanceConversionFactor" is not a part of the comp spec. More...
 
virtual int unsetTimeConversionFactor ()
 Unsets the value of the "timeConversionFactor" attribute of this Submodel. More...
 
virtual ~Submodel ()
 Destructor. More...
 

Constructor & Destructor Documentation

Submodel::Submodel ( unsigned int  level = CompExtension::getDefaultLevel(),
unsigned int  version = CompExtension::getDefaultVersion(),
unsigned int  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
Submodel::Submodel ( CompPkgNamespaces compns)

Creates a new Submodel with the given CompPkgNamespaces object.

Parameters
compnsthe namespace to use
Submodel::Submodel ( const Submodel source)

Copy constructor.

Submodel::~Submodel ( )
virtual

Destructor.

Member Function Documentation

int Submodel::addDeletion ( const Deletion deletion)

Adds a copy of the given Deletion object to the list of deletions.

Parameters
deletionthe Deletion object to be added to the list of deletions. Fails if the added deletion is NULL, does not match the level/version/package of the parent object, or cannot be added to the list of deletions.
void Submodel::clearInstantiation ( )
virtual

Delete the instantiated Model, if it exists.

Submodel * Submodel::clone ( ) const
virtual

Creates and returns a deep copy of this Submodel object.

Returns
a (deep) copy of this Submodel object
int Submodel::convertTimeAndExtent ( )
virtual

Convert all references to time and extent in the instantiated Model, according to the timeConversionFactor and extentConversionFactor attributes.

Deletion * Submodel::createDeletion ( )

Creates a Deletion object, adds it to the end of the deletion objects list and returns a pointer to the newly created object.

Returns
a newly created Deletion object
Examples:
spec_example3.cpp, and spec_example4.cpp.
List * Submodel::getAllElements ( ElementFilter filter = NULL)
virtual

Returns a List of all child SBase objects, including those nested to an arbitrary depth.

Returns
a List of pointers to all children objects.
List * Submodel::getAllInstantiatedElements ( )
virtual

Get all instantiated sub-elements, including any elements from instantiated submodels, etc.

Deletion * Submodel::getDeletion ( unsigned int  n)

Returns the deletion with the given index.

If the index is invalid, NULL is returned.

Parameters
nthe index number of the Deletion to get.
Returns
the nth Deletion in the ListOfDeletions.
const Deletion * Submodel::getDeletion ( unsigned int  n) const

Returns the deletion with the given index.

If the index is invalid, NULL is returned.

Parameters
nthe index number of the Deletion to get.
Returns
the nth Deletion in the ListOfDeletions.
Deletion * Submodel::getDeletion ( std::string  id)

Returns the deletion with the given id.

If the id is invalid, NULL is returned.

Parameters
idthe id of the Deletion to get.
Returns
the Deletion in the ListOfDeletions with the given id.
const Deletion * Submodel::getDeletion ( std::string  id) const

Returns the deletion with the given id.

If the id is invalid, NULL is returned.

Parameters
idthe id of the Deletion to get.
Returns
the Deletion in the ListOfDeletions with the given id.
SBase * Submodel::getElementByMetaId ( const std::string &  metaid)
virtual

Returns the first child element it can find with the given metaid, or itself if it has the given metaid, or NULL if no such object is found.

Parameters
metaidstring representing the metaid of objects to find
Returns
a pointer to the SBase element with the given metaid.
SBase * Submodel::getElementBySId ( const std::string &  id)
virtual

Returns the first child element found that has the given id in the model-wide SId namespace, or NULL if no such object is found.

Parameters
idstring representing the id of objects to find
Returns
a pointer to the SBase element with the given id.
const std::string & Submodel::getElementName ( ) const
virtual

Returns the XML element name of this SBML object.

Returns
the name of this element, as a text string.
const string & Submodel::getExtentConversionFactor ( ) const
virtual

Returns the value of the "extentConversionFactor" attribute of this Submodel.

Returns
the value of the "extentConversionFactor" attribute of this Submodel.
const string & Submodel::getId ( ) const
virtual

Returns the value of the "id" attribute of this Submodel.

Returns
the value of the "id" attribute of this Submodel.
Model * Submodel::getInstantiation ( )
virtual

Get the instantiated Model this Submodel contains rules to create.

Calls instantiate() automatically if this operation has not yet been performed, and/or if the operation failed the last time it was called. Any modifictions that have been performed with performDeletions(), replaceElement(), or convertTimeAndExtent() function calls will be included.

Returns
the instantiated Model object: a clone of the original, modified according to the performDeletions() and replaceElement() functions that have been called. Returns NULL if any error is encountered.
const Model * Submodel::getInstantiation ( ) const
virtual

Get the instantiated Model this Submodel contains rules to create.

Calls instantiate() automatically if this operation has not yet been performed, and/or if the operation failed the last time it was called. Any modifictions that have been performed with performDeletions(), replaceElement(), or convertTimeAndExtent() function calls will be included.

Returns
the instantiated Model object: a clone of the original, modified according to the performDeletions() and replaceElement() functions that have been called. Returns NULL if any error is encountered.
const ListOfDeletions * Submodel::getListOfDeletions ( ) const

Returns the ListOf object that holds all deletions.

Returns
the ListOf object that holds all deletions.
ListOfDeletions * Submodel::getListOfDeletions ( )

Returns the ListOf object that holds all deletions.

Returns
the ListOf object that holds all deletions.
const string & Submodel::getModelRef ( ) const
virtual

Returns the value of the "modelRef" attribute of this Submodel.

Returns
the value of the "modelRef" attribute of this Submodel.
const string & Submodel::getName ( ) const
virtual

Returns the value of the "name" attribute of this Submodel.

Returns
the value of the "name" attribute of this Submodel.
unsigned int Submodel::getNumDeletions ( ) const

Returns the number of deletions for this Submodel.

Returns
the number of deletions for this Submodel.
const string & Submodel::getSubstanceConversionFactor ( ) const
virtual

Returns an empty string, since "substanceConversionFactor" is not a part of the comp spec.

Returns
an empty string
const string & Submodel::getTimeConversionFactor ( ) const
virtual

Returns the value of the "timeConversionFactor" attribute of this Submodel.

Returns
the value of the "timeConversionFactor" attribute of this Submodel.
int Submodel::getTypeCode ( ) const
virtual

Returns the libSBML type code of this object instance.

LibSBML attaches an identifying code to every kind of SBML object. These are integer constants known as SBML type codes. The names of all the codes begin with the characters SBML_. The set of possible type codes for core elements is defined in the enumeration SBMLTypeCode_t, and in addition, libSBML plug-ins for SBML Level 3 packages define their own extra enumerations of type codes (e.g., SBMLLayoutTypeCode_t for the Level 3 Layout package). Note that different Level 3 package plug-ins may use overlapping type codes; to identify the package to which a given object belongs, call the getPackageName() method on the object.
Returns
the SBML type code for this object: SBML_COMP_SUBMODELendif
bool Submodel::hasRequiredAttributes ( ) const
virtual

Returns true if the 'submodel' attribute is set, and if getNumReferents() is exactly 1.

Returns
boolean: 'true' if the attributes are correctly set; 'false' if not.
int Submodel::instantiate ( )
virtual

Find and create a local copy of the Model object referenced by this Submodel.

Is recursive, in that if the instantiated Model contains any Submodel objects, those Submodels will themselves be instantiated. If an instantiated model previously existed, it is deleted and a new one is created. For this reason, call this function only once, or call Submodel::getInstantiation().

bool Submodel::isSetExtentConversionFactor ( ) const
virtual

Predicate returning true or false depending on whether this Submodel's "extentConversionFactor" attribute has been set.

Returns
true if this Submodel's "extentConversionFactor" attribute has been set, otherwise false is returned.
bool Submodel::isSetId ( ) const
virtual

Predicate returning true or false depending on whether this Submodel's "id" attribute has been set.

Returns
true if this Submodel's "id" attribute has been set, otherwise false is returned.
bool Submodel::isSetModelRef ( ) const
virtual

Predicate returning true or false depending on whether this Submodel's "modelRef" attribute has been set.

Returns
true if this Submodel's "modelRef" attribute has been set, otherwise false is returned.
bool Submodel::isSetName ( ) const
virtual

Predicate returning true or false depending on whether this Submodel's "name" attribute has been set.

Returns
true if this Submodel's "name" attribute has been set, otherwise false is returned.
bool Submodel::isSetSubstanceConversionFactor ( ) const
virtual

Returns false, since "substanceConversionFactor" is not a part of the comp spec.

Returns
false.
bool Submodel::isSetTimeConversionFactor ( ) const
virtual

Predicate returning true or false depending on whether this Submodel's "timeConversionFactor" attribute has been set.

Returns
true if this Submodel's "timeConversionFactor" attribute has been set, otherwise false is returned.
Submodel & Submodel::operator= ( const Submodel source)

Assignment operator.

int Submodel::performDeletions ( )
virtual

Delete elements in the instantiated submodel, based on any Deletions from this Submodel's listOfDeletions.

Deletion * Submodel::removeDeletion ( unsigned int  index)

Removes the deletion with the given index from the Submodel.

A pointer to the deletion that was removed is returned. If no deletion has been removed, NULL is returned.

Parameters
indexthe index of the Deletion object to remove
Returns
the Deletion object removed. As mentioned above, the caller owns the returned object. NULL is returned if the given index is out of range.
Deletion * Submodel::removeDeletion ( const std::string &  sid)

Removes the deletion with the given identifier from the Submodel.

A pointer to the deletion that was removed is returned. If no deletion has been removed, NULL is returned.

Parameters
sidstring representing the identifier of the Deletion object to remove
Returns
the Deletion object removed. As mentioned above, the caller owns the returned object. NULL is returned if the given sid is not found.
void Submodel::renameSIdRefs ( const std::string &  oldid,
const std::string &  newid 
)
virtual

Renames the conversion factor attributes on this element if oldid matches.

int Submodel::replaceElement ( SBase toReplace,
SBase replacement 
)
virtual

Delete the element in question from the stored instantiated Model, and replace all references to it with references to the replacement object.

LIBSBML_INVALID_OBJECTendif

int Submodel::setExtentConversionFactor ( const std::string &  id)
virtual

Sets the value of the "extentConversionFactor" attribute of this Submodel.

Fails if the id is not a valid syntax for an SIdRef.

int Submodel::setId ( const std::string &  id)
virtual

Sets the value of the "id" attribute of this Submodel.

Fails if the id is not a valid syntax for an SId.

Examples:
spec_example1.cpp, spec_example2.cpp, spec_example3.cpp, and spec_example4.cpp.
int Submodel::setModelRef ( const std::string &  modelRef)
virtual

Sets the value of the "modelRef" attribute of this Submodel.

Fails if the modelRef is not a valid syntax for an SIdRef.

Examples:
spec_example1.cpp, spec_example2.cpp, spec_example3.cpp, and spec_example4.cpp.
int Submodel::setName ( const std::string &  name)
virtual

Sets the value of the "name" attribute of this Submodel.

Fails if the name is empty.

int Submodel::setSubstanceConversionFactor ( const std::string &  id)
virtual

Automatically fails, since "substanceConversionFactor" is not a part of the comp spec.

Returns
integer value indicating success/failure of the operation. The possible return value is:
int Submodel::setTimeConversionFactor ( const std::string &  id)
virtual

Sets the value of the "timeConversionFactor" attribute of this Submodel.

Fails if the id is not a valid syntax for an SIdRef.

int Submodel::unsetExtentConversionFactor ( )
virtual

Unsets the value of the "extentConversionFactor" attribute of this Submodel.

int Submodel::unsetId ( )
virtual

Unsets the value of the "id" attribute of this Submodel.

int Submodel::unsetModelRef ( )
virtual

Unsets the value of the "modelRef" attribute of this Submodel.

int Submodel::unsetName ( )
virtual

Unsets the value of the "name" attribute of this Submodel.

int Submodel::unsetSubstanceConversionFactor ( )
virtual

Automatically fails, since "substanceConversionFactor" is not a part of the comp spec.

Returns
integer value indicating success/failure of the operation. The possible return value is:
int Submodel::unsetTimeConversionFactor ( )
virtual

Unsets the value of the "timeConversionFactor" attribute of this Submodel.