|
libSBML C++ API
5.18.0
|
|
libSBML C++ API
5.18.0
|
SBML Comp C structure declarations. More...
Macros | |
| #define | CLASS_OR_STRUCT class |
| Forward declaration of all opaque C types. More... | |
Typedefs | |
| typedef class CompSBasePlugin | CompSBasePlugin_t |
| comp
Extension of SBase. More... | |
| typedef class CompSBMLDocumentPlugin | CompSBMLDocumentPlugin_t |
| typedef class Deletion | Deletion_t |
| comp
Deletion of an object from a submodel. More... | |
| typedef class ExternalModelDefinition | ExternalModelDefinition_t |
| comp
A reference to an externally-defined model. More... | |
| typedef class ListOfExternalModelDefinitions | ListOfExternalModelDefinitions_t |
| comp
A list of ExternalModelDefinition objects. More... | |
| typedef class ListOfModelDefinitions | ListOfModelDefinitions_t |
| comp
A list of ModelDefinition objects. More... | |
| typedef class ModelDefinition | ModelDefinition_t |
| comp
A model used in model composition. More... | |
| typedef class Port | Port_t |
| comp
An interface to be used in composition. More... | |
| typedef class ReplacedBy | ReplacedBy_t |
| comp
Indicates an object replaced by another. More... | |
| typedef class ReplacedElement | ReplacedElement_t |
| comp
Indicates an object replaces another. More... | |
| typedef class SBaseRef | SBaseRef_t |
| comp
Base class for references to objects. More... | |
| typedef class Submodel | Submodel_t |
| comp
A model instance inside another model. More... | |
SBML Comp C structure declarations.
| #define CLASS_OR_STRUCT class |
Forward declaration of all opaque C types.
Declaring all types up-front avoids "redefinition of type 'Foo'" compile errors and allows our combined C/C++ headers to depend minimally upon each other. Put another way, the type definitions below serve the same purpose as "class Foo;" forward declarations in C++ code.
| typedef class CompSBasePlugin CompSBasePlugin_t |
The CompSBasePlugin class inherits from the SBasePlugin class, and codifies the extensions to the SBase class defined in the Hierarchical Model Composition (“comp”) package. This extension allows the modeler to define one or more submodel elements which the parent SBase object replaces, and/or a single submodel element which replaces the parent SBase object.
This is accomplished through the addition of an optional ListOfReplacedElements child, which may contain one or more ReplacedElement objects, each of which references a submodel object to be replaced by the containing SBase object, and through the addition of a single optional ReplacedBy child, which references a submodel object which is to replace the containing SBase object.
If a single SBase element both contains a ListOfReplacedElements and has a ReplacedBy child, it and all the referenced ReplacedElement objects are to be replaced by the object referenced by the ReplacedBy element.
| typedef class CompSBMLDocumentPlugin CompSBMLDocumentPlugin_t |
| typedef class Deletion Deletion_t |
comp Deletion of an object from a submodel.
The Deletion class was introduced by the SBML Level 3 Hierarchical Model Composition (“comp”) package to allow elements of submodels to be removed before instantiation.
The Deletion object class is used to define a deletion operation to be applied when a submodel instantiates a model definition. Deletions may be useful in hierarchical model composition scenarios for various reasons. For example, some components in a submodel may be redundant in the composed model, perhaps because the same features are implemented in a different way in the new model.
Deletions function as follows. When the Model to which the Submodel object refers (via the "modelRef" attribute) is read and processed for inclusion into the composed model, each Deletion object identifies an object to remove from that Model instance. The resulting submodel instance consists of everything in the Model object instance minus the entities referenced by the list of Deletion objects.
As might be expected, deletions can have wide-ranging implications, especially when the object deleted has substantial substructure, as in the case of reactions. The following are rules regarding deletions and their effects.
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.
| typedef class ExternalModelDefinition ExternalModelDefinition_t |
comp A reference to an externally-defined model.
The ExternalModelDefinition class was introduced by the SBML Level 3 Hierarchical Model Composition (“comp”) package to define references to Model objects defined in other files.
ExternalModelDefinition objects are model definitions—in and of themselves, they are definitions of models but not uses of those models. The class provides a way to declare and identify them so that Model objects in the present SBML document can use them in Submodel objects.
ExternalModelDefinition contains two required attributes ("source" and "id") and three optional attributes ("modelRef", "md5" and "name").
The "id" attribute serves to provide a handle for the external model reference so that Submodel objects can refer to it. Crucially, it is not the identifier of the model being referenced; rather, it is an identifier for this ExternalModelDefinition object within the current SBML document. The "id" attribute takes a required value of type SId, and must be unique across all Model and ExternalModelDefinition objects present in the document.
ExternalModelDefinition also has an optional "name" attribute, of type 'string'. The "name" attribute may be used to provide a human-readable description of the ExternalModelDefintion object.
The required attribute "source" is used to locate the SBML document containing an external model definition. The value of this attribute must be of type anyURI. Since URIs may be either URLs, URNs, or relative or absolute file locations, this offers flexibility in referencing SBML documents. In all cases, the "source" attribute value must refer specifically to an SBML Level 3 document; prior Levels/Versions of SBML are not supported by this package. The entire file at the given location is referenced. The "source" attribute must have a value for every ExternalModelDefinition instance.
It should be noted that even though there is currently only a Hierarchical Model Composition package for SBML Level 3 Version 1, it may be used in SBML Level 3 Version 2, as long as nothing new from that package is used. This allows the ExternalModelDefinition to reference any SBML Level 3 document, so long as only constructs from Version 1 are used.
ExternalModelDefinition's optional attribute "modelRef", of type SIdRef, is used to identify a Model or ExternalModelDefinition object within the SBML document located at "source". The object referenced may be the main model in the document, or it may be a model definition contained in the SBML document's ListOfModelDefinitions or ListOfExternalModelDefinitions lists. Loops are not allowed: it must be possible to follow a chain of ExternalModelDefinition objects to its end in a Model object.
In core SBML, the "id" on Model is an optional attribute, and therefore, it is possible that the Model object in a given SBML document does not have an identifier. In that case, there is no value to give to the "modelRef" attribute in ExternalModelDefinition. If "modelRef" does not have a value, then the main model (i.e., the <model> element within the <sbml> element) in the referenced file is interpreted as being the model referenced by this ExternalModelDefinition instance.
Finally, the optional "md5" attribute takes a string value. If set, it must be an MD5 checksum value computed over the document referenced by "source". This checksum can serve as a data integrity check over the contents of the "source". Applications may use this to verify that the contents have not changed since the time that the ExternalModelDefinition reference was constructed.
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 relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):
SBML Level 3 Version 1 has essentially the same structure as Level 2 Version 4, depicted above, but SBML Level 3 Version 2 allows containers to contain zero or more of the relevant object, instead of requiring at least one. As such, libsbml will write out an otherwise-empty ListOf___ element that has any optional attribute set (such as 'id' or 'metaid'), that has an optional child (such as a 'notes' or 'annotation'), or that has attributes or children set from any SBML Level 3 package, whether or not the ListOf___ has any other children.
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".
| typedef class ListOfModelDefinitions ListOfModelDefinitions_t |
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 relationship between the lists and the rest of an SBML model is illustrated by the following (for SBML Level 2 Version 4):
SBML Level 3 Version 1 has essentially the same structure as Level 2 Version 4, depicted above, but SBML Level 3 Version 2 allows containers to contain zero or more of the relevant object, instead of requiring at least one. As such, libsbml will write out an otherwise-empty ListOf___ element that has any optional attribute set (such as 'id' or 'metaid'), that has an optional child (such as a 'notes' or 'annotation'), or that has attributes or children set from any SBML Level 3 package, whether or not the ListOf___ has any other children.
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".
| typedef class ModelDefinition ModelDefinition_t |
comp A model used in model composition.
The Hierarchical Model Composition (“comp”) package allows multiple Model objects to be defined in a single SBMLDocument. While these new Model objects are not new SBML classes, they are given a new name, <modelDefinition>, and reside in ListOfModelDefinition objects. In libSBML, this class inherits from the Model class, changing only the expected parent of the object, and the XML name.
An additional restriction is placed on the "id" attribute of ModelDefinition objects: not only must it be unique across all such attributes of type SId within the ModelDefintion, it must also be unique across all Model, ModelDefinition, and ExternalModelDefinition objects in the same SBMLDocument.
comp An interface to be used in composition.
The Port class was introduced by the SBML Level 3 Hierarchical Model Composition (“comp”) package to allow a Model to define a standard interface between it and other models that might use it as a submodel. It derives from the SBaseRef class, and the elements defined there refer to elements in the same parent Model as the Port object. A Port object instance therefore uses those attributes to define a port for a component in a model. When other SBaseRef or SBaseRef-derived classes refer to a Port object using a "portRef" attribute, the element being referenced is the element the Port object itself points to.
In the present formulation of the Hierarchical Model Composition package, the use of ports is not enforced, nor is there any mechanism to restrict which ports may be used in what ways—they are only an advisory construct. Future versions of this SBML package may provide additional functionality to support explicit restrictions on port use. For the present definition of Hierarchical Model Composition, users of models containing ports are encouraged to respect the modeler's intention in defining ports, and use the port definitions to interact with components through their ports (when they have ports defined) rather than interact directly with the components.
The required attribute "id" is used to give an identifier to a Port object so that other objects can refer to it. The attribute has type PortSId and is essentially identical to the SBML primitive type SId, except that its namespace is limited to the identifiers of Port objects defined within a Model object. In parallel, the PortSId type has a companion type, PortSIdRef, that corresponds to the SBML primitive type SIdRef; the value space of PortSIdRef is limited to PortSId values.
| typedef class ReplacedBy ReplacedBy_t |
comp Indicates an object replaced by another.
The ReplacedBy class was introduced by the SBML Level 3 Hierarchical Model Composition (“comp”) package to allow submodel elements to be 'canonical' versions of the element while still allowing the parent model to reference those elements. Whereas a ReplacedElement object indicates that the containing object replaces another, a ReplacedBy object indicates the converse: the parent object is to be replaced by another object.
As is the case with ReplacedElement, the ReplacedBy class inherits from SBaseRef. It additionally defines one required attribute ("submodelRef"), defined in libSBML in the Replacing class.
| typedef class ReplacedElement ReplacedElement_t |
comp Indicates an object replaces another.
The ReplacedElement class was introduced by the SBML Level 3 Hierarchical Model Composition (“comp”) package to allow submodel elements to be replaced, but still allow references to those elements to be valid. A ReplacedElement object is essentially a pointer to a submodel object that should be considered 'replaced'. The object holding the ReplacedElement instance is the one doing the replacing; the object pointed to by the ReplacedElement object is the object being replaced.
A replacement implies that dependencies involving the replaced object must be updated: all references to the replaced object elsewhere in the model are taken to refer to the replacement object instead. For example, if one species replaces another, then any reference to the original species in mathematical formulas, or lists of reactants or products or modifiers in reactions, or initial assignments, or any other SBML construct, are taken to refer to the replacement species, with its value possibly modified by either this object's "conversionFactor" attribute or the relevant submodel's conversion factors. Moreover, any annotations that refer to the replaced species' "metaid" value must be made to refer to the replacement species' "metaid" value instead; and anything else that referred either to an object identifier (i.e., attributes such as the "id" attribute whose types inherit from the SId primitive data type) or the meta identifier (i.e., the "metaid" attribute or any other attribute that inherits from the ID primitive data type) must be made to refer to the replacement species object instead.
It is worth noting that local parameters (inside Reaction objects) pose an interesting edge case for these rules. In order to determine which element is pointed to by a <cn> element within the <math> element of a KineticLaw object, it is necessary to examine the local parameters of that kinetic law's parent Reaction object. Whether the <cn> element is considered to point to something new, then, depends on whether it pointed to the local parameter and whether that local parameter was replaced, even if the text of the element matched the SId value of another element in the model. Note that local parameters may only effectively be replaced by global parameters, since references to its SId are only valid from within the Reaction element to which it belongs.
When referencing an element within the Submodel pointed to by the "submodelRef" attribute (defined in libSBML in the Replacing class), any of the four attributes inherited from SBaseRef for the purpose may be used (portRef, idRef, unitRef, or metaIdRef), or a new optional attribute "deletion" may be used. This attribute must be the identifier of a Deletion object in the parent Model of the ReplacedElement (i.e., the value of some Deletion object's "id" attribute). When "deletion" is set, it means the ReplacedElement object is actually an annotation to indicate that the replacement object replaces something deleted from a submodel. The use of the "deletion" attribute overrides the use of the attributes inherited from SBaseRef: instead of using, e.g., "portRef" or "idRef", the ReplacedElement instance sets "deletion" to the identifier of the Deletion object. In addition, the referenced Deletion must be a child of the Submodel referenced by the "submodelRef" attribute.
The use of ReplacedElement objects to refer to deletions has no effect on the composition of models or the mathematical properties of the result. It serves instead to help record the decision-making process that lead to a given model. It can be particularly useful for visualization purposes, as well as to serve as scaffolding where other types of annotations can be added using the normal Annotation subcomponents available on all SBase objects in SBML.
As with the Submodel class, it may be that the units of the replaced element may not match the units of the replacement element. In this case, the optional "conversionFactor" attribute may be used. This attribute, if present, defines how to transform or rescale the replaced object's value so that it is appropriate for the new contexts in which the object appears. This attribute takes a value of type SIdRef, and the value must refer to a Parameter object instance defined in the model. This parameter then acts as a conversion factor.
The value of the conversion factor should be defined such that a single unit of the replaced element multiplied by the conversion factor should equal a single unit of the replacement element, and the units of the conversion factor should be commensurate with that transformation. The referenced Parameter may be non-constant, particularly if a Species is replaced by a Species with a different "hasOnlySubstanceUnits" attribute value, thus changing amount to concentration, or visa versa.
| typedef class SBaseRef SBaseRef_t |
comp Base class for references to objects.
The SBaseRef class was introduced by the SBML Level 3 Hierarchical Model Composition (“comp”) package as the principle way by which submodel elements may be referenced. The SBaseRef class is usually found as the base class of a Port, Deletion, ReplacedElement, or ReplacedBy class, but may appear as an child of one of the above classes if the parent object references a Submodel.
An SBaseRef object must reference an element using exactly one of the optional attributes of the class. Subclasses of SBaseRef may define additional optional attributes that are legal ways to reference an element.
SBaseRef objects may reference elements that do not live in the Model parent of the SBaseRef object. However, the SBaseRef class itself does not provide a method of determining which Model or Submodel is being referenced. The subclasses of SBaseRef provide methods for this instead.
Once the Model to which the SBaseRef object is referencing has been established, there are four optional attributes defined in the SBaseRef class that are each methods of referencing an element:
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. 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. 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.) 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.
| typedef class Submodel Submodel_t |
comp A model instance inside another model.
The Submodel class was introduced by the SBML Level 3 Hierarchical Model Composition (“comp”) package as the principle way by which models are structured hierarchically. Submodels are instantiations of models contained within other models. They reference another Model that is to be instantiated within its parent Model, and additionally define how that Model is to be modified before instantiation.
The Submodel object class has a required attribute "modelRef", which must reference another Model or ExternalModelDefinition object present in the SBML Document. This referenced Model is the model to be instantiated.
It also has a required attribute, "id", to give the submodel a unique identifier by which other parts of an SBML model definition can refer to it, and an optional "name" attribute of type string. Identifiers and names must be used according to the guidelines described in the SBML specification.
The Submodel class also 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.