public class Submodel extends CompBase
The Submodel
class was introduced by the SBML Level 3 Hierarchical Model Composition
(&ldquocomp&rdquo) 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
.
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. |
void |
connectToChild()   |
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 object. |
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 sid)
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, deleteDisabledPlugins, deleteDisabledPlugins, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getDisabledPlugin, getIdAttribute, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumDisabledPlugins, getNumPlugins, getObjectVersion, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isPkgEnabled, isPkgURIEnabled, isSetAnnotation, isSetIdAttribute, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, isSetUserData, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeFromParentAndDelete, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, renameUnitSIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setIdAttribute, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetIdAttribute, unsetMetaId, unsetModelHistory, unsetNotes, unsetSBOTerm, unsetUserData
public Submodel(long level, long version, long pkgVersion) throws SBMLConstructorException
Submodel
with the given level, version, and package
version.
level
- the SBML Level.version
- the Version within the SBML Level.pkgVersion
- the version of the package.
SBMLConstructorException
SBMLDocument
having a different
combination of SBML Level, Version and XML namespaces than the object
itself will result in an error at the time a caller attempts to make the
addition. A parent object must have compatible Level, Version and XML
namespaces. (Strictly speaking, a parent may also have more XML
namespaces than a child, but the reverse is not permitted.) The
restriction is necessary to ensure that an SBML model has a consistent
overall structure. This requires callers to manage their objects
carefully, but the benefit is increased flexibility in how models can be
created by permitting callers to create objects bottom-up if desired. In
situations where objects are not yet attached to parents (e.g.,
SBMLDocument
), knowledge of the intented SBML Level and Version help
libSBML determine such things as whether it is valid to assign a
particular value to an attribute. For packages, this means that the
parent object to which this package element is being added must have
been created with the package namespace, or that the package namespace
was added to it, even if that parent is not a package object itself.public Submodel(long level, long version) throws SBMLConstructorException
Submodel
with the given level, version, and package
version.
level
- the SBML Level.version
- the Version within the SBML Level.pkgVersion
- the version of the package.
SBMLConstructorException
SBMLDocument
having a different
combination of SBML Level, Version and XML namespaces than the object
itself will result in an error at the time a caller attempts to make the
addition. A parent object must have compatible Level, Version and XML
namespaces. (Strictly speaking, a parent may also have more XML
namespaces than a child, but the reverse is not permitted.) The
restriction is necessary to ensure that an SBML model has a consistent
overall structure. This requires callers to manage their objects
carefully, but the benefit is increased flexibility in how models can be
created by permitting callers to create objects bottom-up if desired. In
situations where objects are not yet attached to parents (e.g.,
SBMLDocument
), knowledge of the intented SBML Level and Version help
libSBML determine such things as whether it is valid to assign a
particular value to an attribute. For packages, this means that the
parent object to which this package element is being added must have
been created with the package namespace, or that the package namespace
was added to it, even if that parent is not a package object itself.public Submodel(long level) throws SBMLConstructorException
Submodel
with the given level, version, and package
version.
level
- the SBML Level.version
- the Version within the SBML Level.pkgVersion
- the version of the package.
SBMLConstructorException
SBMLDocument
having a different
combination of SBML Level, Version and XML namespaces than the object
itself will result in an error at the time a caller attempts to make the
addition. A parent object must have compatible Level, Version and XML
namespaces. (Strictly speaking, a parent may also have more XML
namespaces than a child, but the reverse is not permitted.) The
restriction is necessary to ensure that an SBML model has a consistent
overall structure. This requires callers to manage their objects
carefully, but the benefit is increased flexibility in how models can be
created by permitting callers to create objects bottom-up if desired. In
situations where objects are not yet attached to parents (e.g.,
SBMLDocument
), knowledge of the intented SBML Level and Version help
libSBML determine such things as whether it is valid to assign a
particular value to an attribute. For packages, this means that the
parent object to which this package element is being added must have
been created with the package namespace, or that the package namespace
was added to it, even if that parent is not a package object itself.public Submodel() throws SBMLConstructorException
Submodel
with the given level, version, and package
version.
level
- the SBML Level.version
- the Version within the SBML Level.pkgVersion
- the version of the package.
SBMLConstructorException
SBMLDocument
having a different
combination of SBML Level, Version and XML namespaces than the object
itself will result in an error at the time a caller attempts to make the
addition. A parent object must have compatible Level, Version and XML
namespaces. (Strictly speaking, a parent may also have more XML
namespaces than a child, but the reverse is not permitted.) The
restriction is necessary to ensure that an SBML model has a consistent
overall structure. This requires callers to manage their objects
carefully, but the benefit is increased flexibility in how models can be
created by permitting callers to create objects bottom-up if desired. In
situations where objects are not yet attached to parents (e.g.,
SBMLDocument
), knowledge of the intented SBML Level and Version help
libSBML determine such things as whether it is valid to assign a
particular value to an attribute. For packages, this means that the
parent object to which this package element is being added must have
been created with the package namespace, or that the package namespace
was added to it, even if that parent is not a package object itself.public Submodel(CompPkgNamespaces compns) throws SBMLConstructorException
Submodel
with the given CompPkgNamespaces
object.
The package namespaces object used in this constructor is derived from a
SBMLNamespaces
object, which encapsulates SBML Level/Version/namespaces
information. It is used to communicate the SBML Level, Version, and
package version and name information used in addition to SBML Level 3 Core. A
common approach to using libSBML's SBMLNamespaces
facilities is to create an
package namespace object somewhere in a program once, then hand that object
as needed to object constructors of that package that accept it as and
argument, such as this one.
compns
- the CompPkgNamespaces
object.
SBMLConstructorException
SBMLDocument
having a different
combination of SBML Level, Version and XML namespaces than the object
itself will result in an error at the time a caller attempts to make the
addition. A parent object must have compatible Level, Version and XML
namespaces. (Strictly speaking, a parent may also have more XML
namespaces than a child, but the reverse is not permitted.) The
restriction is necessary to ensure that an SBML model has a consistent
overall structure. This requires callers to manage their objects
carefully, but the benefit is increased flexibility in how models can be
created by permitting callers to create objects bottom-up if desired. In
situations where objects are not yet attached to parents (e.g.,
SBMLDocument
), knowledge of the intented SBML Level and Version help
libSBML determine such things as whether it is valid to assign a
particular value to an attribute. For packages, this means that the
parent object to which this package element is being added must have
been created with the package namespace, or that the package namespace
was added to it, even if that parent is not a package object itself.public Submodel(Submodel source) throws SBMLConstructorException
source
- the instance to copy.SBMLConstructorException
public 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 SBase cloneObject()
Submodel
object.
cloneObject
 in class SBase
Submodel
object.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 the object to find.
SBase
element 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 the object to find.
SBase
element with the given metaid
.public java.lang.String getId()
Submodel
.
getId
 in class SBase
Submodel
.
SBase.getIdAttribute()
,
SBase.setIdAttribute(String sid)
,
SBase.isSetIdAttribute()
,
SBase.unsetIdAttribute()
The identifier given by an object's 'id' attribute value
is used to identify the object within the SBML model definition.
Other objects can refer to the component using this identifier. The
data type of 'id' is always SId
or a type derived
from that, such as UnitSId
, depending on the object in
question. All data types are defined as follows:
letter .= 'a'..'z','A'..'Z' digit .= '0'..'9' idChar .= letter | digit | '_' SId .= ( letter | '_' ) idChar*
The characters (
and )
are used for grouping, the
character *
'zero or more times', and the character
|
indicates logical 'or'. The equality of SBML identifiers is
determined by an exact character sequence match i.e., comparisons must be
performed in a case-sensitive manner. This applies to all uses of SId
,
SIdRef
, and derived types.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, check, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The exception to this rule is that for InitialAssignment
, EventAssignment
,
AssignmentRule
, and RateRule
objects, the getId() function and the isSetId()
functions (though not the setId() or unsetId() functions) would instead
reference the value of the 'variable' attribute (for the rules and event
assignments) or the 'symbol' attribute (for initial assignments).
The AlgebraicRule
fell into this category as well, though because it
contained neither a 'variable' nor a 'symbol' attribute, getId() would
always return an empty string, and isSetId() would always return false.
For this reason, four new functions are now provided
(getIdAttribute(), setIdAttribute(String),
isSetIdAttribute(), and unsetIdAttribute()) that will always
act on the actual 'id' attribute, regardless of the object's type. The
new functions should be used instead of the old ones unless the old behavior
is somehow necessary.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an 'id' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write 'id' attributes for those objects.
public boolean isSetId()
isSetId
 in class SBase
true
if the 'id' attribute of this SBML object is
set, false
otherwise.
SBase.getIdAttribute()
,
SBase.setIdAttribute(String sid)
,
SBase.unsetIdAttribute()
,
SBase.isSetIdAttribute()
The identifier given by an object's 'id' attribute value
is used to identify the object within the SBML model definition.
Other objects can refer to the component using this identifier. The
data type of 'id' is always SId
or a type derived
from that, such as UnitSId
, depending on the object in
question. All data types are defined as follows:
letter .= 'a'..'z','A'..'Z' digit .= '0'..'9' idChar .= letter | digit | '_' SId .= ( letter | '_' ) idChar*
The characters (
and )
are used for grouping, the
character *
'zero or more times', and the character
|
indicates logical 'or'. The equality of SBML identifiers is
determined by an exact character sequence match i.e., comparisons must be
performed in a case-sensitive manner. This applies to all uses of SId
,
SIdRef
, and derived types.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, check, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The exception to this rule is that for InitialAssignment
, EventAssignment
,
AssignmentRule
, and RateRule
objects, the getId() function and the isSetId()
functions (though not the setId() or unsetId() functions) would instead
reference the value of the 'variable' attribute (for the rules and event
assignments) or the 'symbol' attribute (for initial assignments).
The AlgebraicRule
fell into this category as well, though because it
contained neither a 'variable' nor a 'symbol' attribute, getId() would
always return an empty string, and isSetId() would always return false.
For this reason, four new functions are now provided
(getIdAttribute(), setIdAttribute(String),
isSetIdAttribute(), and unsetIdAttribute()) that will always
act on the actual 'id' attribute, regardless of the object's type. The
new functions should be used instead of the old ones unless the old behavior
is somehow necessary.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an 'id' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write 'id' attributes for those objects.
public int setId(java.lang.String sid)
Submodel
.
The string sid
is copied.
The identifier given by an object's 'id' attribute value
is used to identify the object within the SBML model definition.
Other objects can refer to the component using this identifier. The
data type of 'id' is always SId
or a type derived
from that, such as UnitSId
, depending on the object in
question. All data types are defined as follows:
letter .= 'a'..'z','A'..'Z' digit .= '0'..'9' idChar .= letter | digit | '_' SId .= ( letter | '_' ) idChar*
The characters (
and )
are used for grouping, the
character *
'zero or more times', and the character
|
indicates logical 'or'. The equality of SBML identifiers is
determined by an exact character sequence match i.e., comparisons must be
performed in a case-sensitive manner. This applies to all uses of SId
,
SIdRef
, and derived types.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, check, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The exception to this rule is that for InitialAssignment
, EventAssignment
,
AssignmentRule
, and RateRule
objects, the getId() function and the isSetId()
functions (though not the setId() or unsetId() functions) would instead
reference the value of the 'variable' attribute (for the rules and event
assignments) or the 'symbol' attribute (for initial assignments).
The AlgebraicRule
fell into this category as well, though because it
contained neither a 'variable' nor a 'symbol' attribute, getId() would
always return an empty string, and isSetId() would always return false.
For this reason, four new functions are now provided
(getIdAttribute(), setIdAttribute(String),
isSetIdAttribute(), and unsetIdAttribute()) that will always
act on the actual 'id' attribute, regardless of the object's type. The
new functions should be used instead of the old ones unless the old behavior
is somehow necessary.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an 'id' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write 'id' attributes for those objects.
setId
 in class SBase
sid
- the string to use as the identifier of this object.
SBase.getIdAttribute()
,
SBase.setIdAttribute(String sid)
,
SBase.isSetIdAttribute()
,
SBase.unsetIdAttribute()
public int unsetId()
Submodel
.
The identifier given by an object's 'id' attribute value
is used to identify the object within the SBML model definition.
Other objects can refer to the component using this identifier. The
data type of 'id' is always SId
or a type derived
from that, such as UnitSId
, depending on the object in
question. All data types are defined as follows:
letter .= 'a'..'z','A'..'Z' digit .= '0'..'9' idChar .= letter | digit | '_' SId .= ( letter | '_' ) idChar*
The characters (
and )
are used for grouping, the
character *
'zero or more times', and the character
|
indicates logical 'or'. The equality of SBML identifiers is
determined by an exact character sequence match i.e., comparisons must be
performed in a case-sensitive manner. This applies to all uses of SId
,
SIdRef
, and derived types.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, check, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The exception to this rule is that for InitialAssignment
, EventAssignment
,
AssignmentRule
, and RateRule
objects, the getId() function and the isSetId()
functions (though not the setId() or unsetId() functions) would instead
reference the value of the 'variable' attribute (for the rules and event
assignments) or the 'symbol' attribute (for initial assignments).
The AlgebraicRule
fell into this category as well, though because it
contained neither a 'variable' nor a 'symbol' attribute, getId() would
always return an empty string, and isSetId() would always return false.
For this reason, four new functions are now provided
(getIdAttribute(), setIdAttribute(String),
isSetIdAttribute(), and unsetIdAttribute()) that will always
act on the actual 'id' attribute, regardless of the object's type. The
new functions should be used instead of the old ones unless the old behavior
is somehow necessary.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an 'id' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write 'id' attributes for those objects.
unsetId
 in class SBase
SBase.getIdAttribute()
,
SBase.setIdAttribute(String sid)
,
SBase.isSetIdAttribute()
,
SBase.unsetIdAttribute()
public java.lang.String getName()
Submodel
object.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The 'name' attribute is
optional and is not intended to be used for cross-referencing purposes
within a model. Its purpose instead is to provide a human-readable
label for the component. The data type of 'name' is the type
string
defined in XML Schema. SBML imposes no
restrictions as to the content of 'name' attributes beyond those
restrictions defined by the string
type in XML Schema.
The recommended practice for handling 'name' is as follows. If a software tool has the capability for displaying the content of 'name' attributes, it should display this content to the user as a component's label instead of the component's 'id'. If the user interface does not have this capability (e.g., because it cannot display or use special characters in symbol names), or if the 'name' attribute is missing on a given component, then the user interface should display the value of the 'id' attribute instead. (Script language interpreters are especially likely to display 'id' instead of 'name'.)
As a consequence of the above, authors of systems that automatically generate the values of 'id' attributes should be aware some systems may display the 'id''s to the user. Authors therefore may wish to take some care to have their software create 'id' values that are: (a) reasonably easy for humans to type and read and (b) likely to be meaningful, for example by making the 'id' attribute be an abbreviated form of the name attribute value.
An additional point worth mentioning is although there are restrictions on the uniqueness of 'id' values, there are no restrictions on the uniqueness of 'name' values in a model. This allows software applications leeway in assigning component identifiers.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have names). If the object in question does not posess a 'name' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the name to be set, nor will it read or write 'name' attributes for those objects.
getName
 in class SBase
SBase.getIdAttribute()
,
Submodel.isSetName()
,
Submodel.setName(String sid)
,
Submodel.unsetName()
public boolean isSetName()
true
or false
depending on whether this
Submodel
's 'name' attribute has been set.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The 'name' attribute is
optional and is not intended to be used for cross-referencing purposes
within a model. Its purpose instead is to provide a human-readable
label for the component. The data type of 'name' is the type
string
defined in XML Schema. SBML imposes no
restrictions as to the content of 'name' attributes beyond those
restrictions defined by the string
type in XML Schema.
The recommended practice for handling 'name' is as follows. If a software tool has the capability for displaying the content of 'name' attributes, it should display this content to the user as a component's label instead of the component's 'id'. If the user interface does not have this capability (e.g., because it cannot display or use special characters in symbol names), or if the 'name' attribute is missing on a given component, then the user interface should display the value of the 'id' attribute instead. (Script language interpreters are especially likely to display 'id' instead of 'name'.)
As a consequence of the above, authors of systems that automatically generate the values of 'id' attributes should be aware some systems may display the 'id''s to the user. Authors therefore may wish to take some care to have their software create 'id' values that are: (a) reasonably easy for humans to type and read and (b) likely to be meaningful, for example by making the 'id' attribute be an abbreviated form of the name attribute value.
An additional point worth mentioning is although there are restrictions on the uniqueness of 'id' values, there are no restrictions on the uniqueness of 'name' values in a model. This allows software applications leeway in assigning component identifiers.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have names). If the object in question does not posess a 'name' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the name to be set, nor will it read or write 'name' attributes for those objects.
isSetName
 in class SBase
true
if the 'name' attribute of this SBML object is
set, false
otherwise.
Submodel.getName()
,
Submodel.setName(String sid)
,
Submodel.unsetName()
public int setName(java.lang.String name)
public int unsetName()
Submodel
.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The 'name' attribute is
optional and is not intended to be used for cross-referencing purposes
within a model. Its purpose instead is to provide a human-readable
label for the component. The data type of 'name' is the type
string
defined in XML Schema. SBML imposes no
restrictions as to the content of 'name' attributes beyond those
restrictions defined by the string
type in XML Schema.
The recommended practice for handling 'name' is as follows. If a software tool has the capability for displaying the content of 'name' attributes, it should display this content to the user as a component's label instead of the component's 'id'. If the user interface does not have this capability (e.g., because it cannot display or use special characters in symbol names), or if the 'name' attribute is missing on a given component, then the user interface should display the value of the 'id' attribute instead. (Script language interpreters are especially likely to display 'id' instead of 'name'.)
As a consequence of the above, authors of systems that automatically generate the values of 'id' attributes should be aware some systems may display the 'id''s to the user. Authors therefore may wish to take some care to have their software create 'id' values that are: (a) reasonably easy for humans to type and read and (b) likely to be meaningful, for example by making the 'id' attribute be an abbreviated form of the name attribute value.
An additional point worth mentioning is although there are restrictions on the uniqueness of 'id' values, there are no restrictions on the uniqueness of 'name' values in a model. This allows software applications leeway in assigning component identifiers.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have names). If the object in question does not posess a 'name' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the name to be set, nor will it read or write 'name' attributes for those objects.
unsetName
 in class SBase
Submodel.getName()
,
Submodel.setName(String sid)
,
Submodel.isSetName()
public java.lang.String getModelRef()
Submodel
.
Submodel
.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 int setModelRef(java.lang.String modelRef)
Submodel
. Fails if
the modelRef is not a valid syntax for an SIdRef.
public int unsetModelRef()
Submodel
.
public java.lang.String getSubstanceConversionFactor()
public boolean isSetSubstanceConversionFactor()
false
, since 'substanceConversionFactor' is not a part of the comp spec.
false.
public int setSubstanceConversionFactor(java.lang.String id)
public int unsetSubstanceConversionFactor()
public java.lang.String getTimeConversionFactor()
Submodel
.
Submodel
.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 setTimeConversionFactor(java.lang.String id)
Submodel
.
Fails if the id is not a valid syntax for an SIdRef.
public int unsetTimeConversionFactor()
Submodel
.
public java.lang.String getExtentConversionFactor()
Submodel
.
Submodel
.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 int setExtentConversionFactor(java.lang.String id)
Submodel
. Fails if the id is not a valid syntax for an SIdRef.
public int unsetExtentConversionFactor()
Submodel
.
public ListOfDeletions getListOfDeletions()
ListOf
object that holds all deletions.
ListOf
object that holds all deletions.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 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 long getNumDeletions()
Submodel
.
Submodel
.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
object.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 boolean hasRequiredAttributes()
true
if the 'submodel' attribute is set, and if getNumReferents() is exactly 1.
hasRequiredAttributes
 in class SBase
public java.lang.String getElementName()
getElementName
 in class SBase
public void renameSIdRefs(java.lang.String oldid, java.lang.String newid)
oldid
matches.renameSIdRefs
 in class SBase
oldid
- the old identifier.newid
- the new identifier.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 SBML_
.
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 void connectToChild()
connectToChild
 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
(which
indicates this Submodel
itself is invalid, and no Model
can be instantiated
from it)
LIBSBML_OPERATION_FAILED
public int performDeletions()
Submodel
's listOfDeletions.
LIBSBML_OPERATION_SUCCESS
LIBSBML_INVALID_OBJECT
(which
indicates this Submodel
itself is invalid, and no Model
can be instantiated
from it)
LIBSBML_OPERATION_FAILED
public 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 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 void clearInstantiation()
Model
, if it exists.public int convertTimeAndExtent()
Model
, according to the
timeConversionFactor and extentConversionFactor attributes.public SBaseList getListOfAllInstantiatedElements()