public class Submodel extends CompBase
The Submodel
class was introduced by the SBML Level 3
'Hierarchical Model Composition' package
(&ldquocomp&rdquo) 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
.
Constructor and Description |
---|
Submodel()
Creates a new
Submodel with the given level, version, and package
version. |
Submodel(CompPkgNamespaces compns)
Creates a new
Submodel with the given CompPkgNamespaces object. |
Submodel(long level)
Creates a new
Submodel with the given level, version, and package
version. |
Submodel(long level,
long version)
Creates a new
Submodel with the given level, version, and package
version. |
Submodel(long level,
long version,
long pkgVersion)
Creates a new
Submodel with the given level, version, and package
version. |
Submodel(Submodel source)
Copy constructor.
|
Modifier and Type | Method and Description |
---|---|
int |
addDeletion(Deletion deletion)
Adds a copy of the given
Deletion object to the list of deletions. |
void |
clearInstantiation()
Delete the instantiated
Model , if it exists. |
SBase |
cloneObject()
Creates and returns a deep copy of this
Submodel object. |
int |
convertTimeAndExtent()
Convert all references to time and extent in the instantiated
Model , according to the
timeConversionFactor and extentConversionFactor attributes. |
Deletion |
createDeletion()
Creates a
Deletion object, adds it to the end of the
deletion objects list and returns a pointer to the newly
created object. |
void |
delete()
Explicitly deletes the underlying native object.
|
Deletion |
getDeletion(long n)
Returns the deletion with the given index.
|
Deletion |
getDeletion(java.lang.String id)
Returns the deletion with the given
id . |
SBase |
getElementByMetaId(java.lang.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. |
SBase |
getElementBySId(java.lang.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. |
java.lang.String |
getElementName()
Returns the XML element name of
this SBML object.
|
java.lang.String |
getExtentConversionFactor()
Returns the value of the 'extentConversionFactor' attribute of this
Submodel . |
java.lang.String |
getId()
Returns the value of the 'id' attribute of this
Submodel . |
Model |
getInstantiation()
|
SBaseList |
getListOfAllInstantiatedElements()   |
ListOfDeletions |
getListOfDeletions()
Returns the
ListOf object that holds all deletions. |
java.lang.String |
getModelRef()
Returns the value of the 'modelRef' attribute of this
Submodel . |
java.lang.String |
getName()
Returns the value of the 'name' attribute of this
Submodel . |
long |
getNumDeletions()
Returns the number of deletions for this
Submodel . |
java.lang.String |
getSubstanceConversionFactor()
Returns an empty string, since 'substanceConversionFactor' is not a part of the comp spec.
|
java.lang.String |
getTimeConversionFactor()
Returns the value of the 'timeConversionFactor' attribute of this
Submodel . |
int |
getTypeCode()
Returns the libSBML type code of this object instance.
|
boolean |
hasRequiredAttributes()
Returns true if the 'submodel' attribute is set, and if getNumReferents() is exactly 1.
|
int |
instantiate()
|
boolean |
isSetExtentConversionFactor()
Predicate returning
true or false depending on whether this
Submodel 's 'extentConversionFactor' attribute has been set. |
boolean |
isSetId()
|
boolean |
isSetModelRef()
Predicate returning
true or false depending on whether this
Submodel 's 'modelRef' attribute has been set. |
boolean |
isSetName()
Predicate returning
true or false depending on whether this
Submodel 's 'name' attribute has been set. |
boolean |
isSetSubstanceConversionFactor()
Returns
false , since 'substanceConversionFactor' is not a part of the comp spec. |
boolean |
isSetTimeConversionFactor()
Predicate returning
true or false depending on whether this
Submodel 's 'timeConversionFactor' attribute has been set. |
int |
performDeletions()
Delete elements in the instantiated submodel, based on any Deletions
from this
Submodel 's listOfDeletions. |
Deletion |
removeDeletion(long index)
Removes the deletion with the given index from the
Submodel . |
Deletion |
removeDeletion(java.lang.String sid)
Removes the deletion with the given identifier from the
Submodel . |
void |
renameSIdRefs(java.lang.String oldid,
java.lang.String newid)
Renames the conversion factor attributes on this element if
oldid matches. |
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. |
int |
setExtentConversionFactor(java.lang.String id)
Sets the value of the 'extentConversionFactor' attribute of this
Submodel . |
int |
setId(java.lang.String id)
Sets the value of the 'id' attribute of this
Submodel . |
int |
setModelRef(java.lang.String modelRef)
Sets the value of the 'modelRef' attribute of this
Submodel . |
int |
setName(java.lang.String name)
Sets the value of the 'name' attribute of this
Submodel . |
int |
setSubstanceConversionFactor(java.lang.String id)
Automatically fails, since 'substanceConversionFactor' is not a part of the comp spec.
|
int |
setTimeConversionFactor(java.lang.String id)
Sets the value of the 'timeConversionFactor' attribute of this
Submodel . |
int |
unsetExtentConversionFactor()
Unsets the value of the 'extentConversionFactor' attribute of this
Submodel . |
int |
unsetId()
Unsets the value of the 'id' attribute of this
Submodel . |
int |
unsetModelRef()
Unsets the value of the 'modelRef' attribute of this
Submodel . |
int |
unsetName()
Unsets the value of the 'name' attribute of this
Submodel . |
int |
unsetSubstanceConversionFactor()
Automatically fails, since 'substanceConversionFactor' is not a part of the comp spec.
|
int |
unsetTimeConversionFactor()
Unsets the value of the 'timeConversionFactor' attribute of this
Submodel . |
getPackageName, getPackageURI, getPackageVersion, getParentModel
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumPlugins, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isSetAnnotation, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeFromParentAndDelete, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, renameUnitSIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetMetaId, unsetModelHistory, unsetNotes, unsetSBOTerm
public Submodel() throws SBMLConstructorException
Submodel
with the given level, version, and package
version.
level
- the SBML Levelversion
- the Version within the SBML LevelpkgVersion
- the version of the packageSBMLConstructorException
public Submodel(CompPkgNamespaces compns) throws SBMLConstructorException
Submodel
with the given CompPkgNamespaces
object.
compns
- the namespace to useSBMLConstructorException
public Submodel(long level) throws SBMLConstructorException
Submodel
with the given level, version, and package
version.
level
- the SBML Levelversion
- the Version within the SBML LevelpkgVersion
- the version of the packageSBMLConstructorException
public Submodel(long level, long version) throws SBMLConstructorException
Submodel
with the given level, version, and package
version.
level
- the SBML Levelversion
- the Version within the SBML LevelpkgVersion
- the version of the packageSBMLConstructorException
public Submodel(long level, long version, long pkgVersion) throws SBMLConstructorException
Submodel
with the given level, version, and package
version.
level
- the SBML Levelversion
- the Version within the SBML LevelpkgVersion
- the version of the packageSBMLConstructorException
public Submodel(Submodel source) throws SBMLConstructorException
SBMLConstructorException
public int addDeletion(Deletion deletion)
Deletion
object to the list of deletions.
deletion
- the 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.
public void clearInstantiation()
Model
, if it exists.public SBase cloneObject()
Submodel
object.
cloneObject
 in class SBase
Submodel
objectpublic int convertTimeAndExtent()
Model
, according to the
timeConversionFactor and extentConversionFactor attributes.public Deletion createDeletion()
Deletion
object, adds it to the end of the
deletion objects list and returns a pointer to the newly
created object.
Deletion
objectpublic void delete()
In general, application software will not need to call this method directly. The Java language binding for libSBML is implemented as a language wrapper that provides a Java interface to libSBML's underlying C++/C code. Some of the Java methods return objects that are linked to objects created not by Java code, but by C++ code. The Java objects wrapped around them will be deleted when the garbage collector invokes the corresponding C++ finalize()
methods for the objects. The finalize()
methods in turn call the Submodel.delete()
method on the libSBML object.
This method is exposed in case calling programs want to ensure that the underlying object is freed immediately, and not at some arbitrary time determined by the Java garbage collector. In normal usage, callers do not need to invoke Submodel.delete()
themselves.
public Deletion getDeletion(long n)
null
is returned.
n
- the index number of the Deletion
to get.
Deletion
in the ListOfDeletions
.public Deletion getDeletion(java.lang.String id)
id
.
If the id is invalid, null
is returned.
id
- the id of the Deletion
to get.
Deletion
in the ListOfDeletions
with the given id
.public SBase getElementByMetaId(java.lang.String metaid)
metaid
, or
itself if it has the given metaid
, or null
if no such object is found.
getElementByMetaId
 in class SBase
metaid
- string representing the metaid of objects to find
SBase
element with the given metaid
.public SBase getElementBySId(java.lang.String id)
id
in the
model-wide SId namespace, or null
if no such object is found.
getElementBySId
 in class SBase
id
- string representing the id of objects to find
SBase
element with the given id
.public java.lang.String getElementName()
getElementName
 in class SBase
public java.lang.String getExtentConversionFactor()
Submodel
.
Submodel
.public java.lang.String getId()
Submodel
.
public Model getInstantiation()
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.
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.public SBaseList getListOfAllInstantiatedElements()
public ListOfDeletions getListOfDeletions()
ListOf
object that holds all deletions.
ListOf
object that holds all deletions.public java.lang.String getModelRef()
Submodel
.
Submodel
.public java.lang.String getName()
Submodel
.
public long getNumDeletions()
Submodel
.
Submodel
.public java.lang.String getSubstanceConversionFactor()
public java.lang.String getTimeConversionFactor()
Submodel
.
Submodel
.public int getTypeCode()
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 &ldquoSBML_
&rdquo.
In the Java language interface for libSBML, the
type codes are defined as static integer constants in the interface class
libsbmlConstants
. 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.
getTypeCode
 in class SBase
SBML_COMP_SUBMODEL
Submodel.getElementName()
,
CompBase.getPackageName()
public boolean hasRequiredAttributes()
hasRequiredAttributes
 in class SBase
public int instantiate()
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()
.
LIBSBML_OPERATION_SUCCESS
LIBSBML_INVALID_OBJECT
LIBSBML_OPERATION_FAILED
In this case, 'invalid object' means that this Submodel
itself is invalid, and no Model
can be instantiated from it.
public boolean isSetExtentConversionFactor()
true
or false
depending on whether this
Submodel
's 'extentConversionFactor' attribute has been set.
true
if this Submodel
's 'extentConversionFactor' attribute has been set,
otherwise false
is returned.public boolean isSetId()
public boolean isSetModelRef()
true
or false
depending on whether this
Submodel
's 'modelRef' attribute has been set.
true
if this Submodel
's 'modelRef' attribute has been set,
otherwise false
is returned.public boolean isSetName()
true
or false
depending on whether this
Submodel
's 'name' attribute has been set.
public boolean isSetSubstanceConversionFactor()
false
, since 'substanceConversionFactor' is not a part of the comp spec.
false.
public boolean isSetTimeConversionFactor()
true
or false
depending on whether this
Submodel
's 'timeConversionFactor' attribute has been set.
true
if this Submodel
's 'timeConversionFactor' attribute has been set,
otherwise false
is returned.public int performDeletions()
Submodel
's listOfDeletions.
LIBSBML_OPERATION_SUCCESS
LIBSBML_INVALID_OBJECT
LIBSBML_OPERATION_FAILED
In this case, 'invalid object' means that this Submodel
itself is invalid, and no Model
can be instantiated from it.
public Deletion removeDeletion(long index)
Submodel
.
A pointer to the deletion that was removed is returned.
If no deletion has been removed, null
is returned.
public Deletion removeDeletion(java.lang.String sid)
Submodel
.
A pointer to the deletion that was removed is returned.
If no deletion has been removed, null
is returned.
public void renameSIdRefs(java.lang.String oldid, java.lang.String newid)
oldid
matches.renameSIdRefs
 in class SBase
oldid
- the old identifiernewid
- the new identifierpublic int replaceElement(SBase toReplace, SBase replacement)
Model
, and
replace all references to it with references to the replacement object.
LIBSBML_INVALID_OBJECT
means that this Submodel
itself or one of the passed-in objects are invalid.
LIBSBML_OPERATION_FAILED
means that the routine failed for some othe reason.
public int setExtentConversionFactor(java.lang.String id)
Submodel
. Fails if the id is not a valid syntax for an SIdRef.
public int setId(java.lang.String id)
Submodel
. Fails if the id
is not a valid syntax for an SId.
public int setModelRef(java.lang.String modelRef)
Submodel
. Fails if
the modelRef is not a valid syntax for an SIdRef.
public int setName(java.lang.String name)
Submodel
. Fails if the
name is empty.
public int setSubstanceConversionFactor(java.lang.String id)
public int setTimeConversionFactor(java.lang.String id)
Submodel
.
Fails if the id is not a valid syntax for an SIdRef.
public int unsetExtentConversionFactor()
Submodel
.
public int unsetId()
Submodel
.
public int unsetModelRef()
Submodel
.
public int unsetName()
Submodel
.
public int unsetSubstanceConversionFactor()
public int unsetTimeConversionFactor()
Submodel
.