public class InitialAssignment extends SBase
SBML Level 2 Versions 2&ndash4 and SBML Level 3 provide two ways of assigning initial
values to entities in a model. The simplest and most basic is to set
the values of the appropriate attributes in the relevant components for
example, the initial value of a model parameter (whether it is a
constant or a variable) can be assigned by setting its 'value' attribute
directly in the model definition. However, this approach is not
suitable when the value must be calculated, because the initial value
attributes on different components such as species, compartments, and
parameters are single values and not mathematical expressions. In those
situations, the InitialAssignment
construct can be used it permits the
calculation of the value of a constant or the initial value of a
variable from the values of other quantities in a model.
As explained below, the provision of InitialAssignment
does not mean
that models necessarily must use this construct when defining initial
values of quantities in a model. If a value can be set directly using
the relevant attribute of a component in a model, then that
approach may be more efficient and more portable to other software
tools. InitialAssignment
should be used when the other mechanism is
insufficient for the needs of a particular model.
The InitialAssignment
construct has some similarities to AssignmentRule
.
The main differences are: (a) an InitialAssignment
can set the value of
a constant whereas an AssignmentRule
cannot, and (b) unlike
AssignmentRule
, an InitialAssignment
definition only applies up to and
including the beginning of simulation time, i.e., t ≤ 0,
while an AssignmentRule
applies at all times.
InitialAssignment
has a required attribute, 'symbol', whose value must
follow the guidelines for identifiers described in the SBML
specification (e.g., Section 3.3 in the Level 2 Version 4
specification). The value of this attribute in an InitialAssignment
object can be the identifier of a Compartment
, Species
or global
Parameter
elsewhere in the model. The InitialAssignment
defines the
initial value of the constant or variable referred to by the 'symbol'
attribute. (The attribute's name is 'symbol' rather than 'variable'
because it may assign values to constants as well as variables in a
model.) Note that an initial assignment cannot be made to reaction
identifiers, that is, the 'symbol' attribute value of an
InitialAssignment
cannot be an identifier that is the 'id' attribute
value of a Reaction
object in the model. This is identical to a
restriction placed on rules.
InitialAssignment
also has a required 'math' subelement that contains a
MathML expression used to calculate the value of the constant or the
initial value of the variable. The units of the value computed by the
formula in the 'math' subelement should (in SBML Level 2
Version 4 and in SBML Level 3) or must (in previous Versions) be identical to be the
units associated with the identifier given in the 'symbol' attribute.
(That is, the units are the units of the species, compartment, or
parameter, as appropriate for the kind of object identified by the value
of 'symbol'.)
InitialAssignment
was introduced in SBML Level 2 Version 2. It is not
available in SBML Level 2 Version 1 nor in any version of Level 1.
The value calculated by an InitialAssignment
object overrides the value
assigned to the given symbol by the object defining that symbol. For
example, if a compartment's 'size' attribute is set in its definition,
and the model also contains an InitialAssignment
having that
compartment's identifier as its 'symbol' attribute value, then the
interpretation is that the 'size' assigned in the Compartment
object
should be ignored and the value assigned based on the computation
defined in the InitialAssignment
. Initial assignments can take place
for Compartment
, Species
and global Parameter
objects regardless of the
value of their 'constant' attribute.
The actions of all InitialAssignment
objects are in general terms
the same, but differ in the precise details depending on the type
of variable being set:
InitialAssignment
sets the
referenced species' initial quantity (concentration or amount of
substance) to the value determined by the formula in the 'math'
subelement. The overall units of the formula should (in SBML
Level 2 Version 4 and in SBML Level 3) or must (in previous Versions) be the same
as the units specified for the species.
InitialAssignment
sets
the referenced compartment's initial size to the size determined by the
formula in 'math'. The overall units of the formula should (in SBML
Level 2 Version 4 and in SBML Level 3) or must (in previous Versions) be the same
as the units specified for the size of the compartment.
InitialAssignment
sets the
referenced parameter's initial value to that determined by the formula
in 'math'. The overall units of the formula should (in SBML
Level 2 Version 4 and SBML Level 3) or must (in previous Versions) be the same
as the units defined for the parameter. In the context of a simulation, initial assignments establish values that are in effect prior to and including the start of simulation time, i.e., t ≤ 0. Section 3.4.8 in the SBML Level 2 Version 4 and SBML Level 3 Version 1 Core specifications provides information about the interpretation of assignments, rules, and entity values for simulation time up to and including the start time t = 0 this is important for establishing the initial conditions of a simulation if the model involves expressions containing the delay 'csymbol'.
There cannot be two initial assignments for the same symbol in a model
that is, a model must not contain two or more InitialAssignment
objects
that both have the same identifier as their 'symbol' attribute value. A
model must also not define initial assignments and assignment
rules for the same entity. That is, there cannot be both an
InitialAssignment
and an AssignmentRule
for the same symbol in a model,
because both kinds of constructs apply prior to and at the start of
simulated time&mdashallowing both to exist for a given symbol would
result in indeterminism).
The ordering of InitialAssignment
objects is not significant. The
combined set of InitialAssignment
, AssignmentRule
and KineticLaw
objects form a set of assignment statements that must be considered as a
whole. The combined set of assignment statements should not contain
algebraic loops: a chain of dependency between these statements should
terminate. (More formally, consider the directed graph of assignment
statements where nodes are a model's assignment statements and directed
arcs exist for each occurrence of a symbol in an assignment statement
'math' attribute. The directed arcs in this graph start from the
statement assigning the symbol and end at the statement that contains
the symbol in their math elements. Such a graph must be acyclic.)
Finally, it is worth being explicit about the expected behavior in the
following situation. Suppose (1) a given symbol has a value x
assigned to it in its definition, and (2) there is an initial assignment
having the identifier as its 'symbol' value and reassigning the value to
y, and (3) the identifier is also used in the
mathematical formula of a second initial assignment. What value should
the second initial assignment use? It is y, the value assigned
to the symbol by the first initial assignment, not whatever value was
given in the symbol's definition. This follows directly from the
behavior described above: if an InitialAssignment
object exists for a
given symbol, then the symbol's value is overridden by that initial
assignment.
Constructor and Description |
---|
InitialAssignment(InitialAssignment orig)
Copy constructor creates a copy of this
InitialAssignment . |
InitialAssignment(long level,
long version)
|
InitialAssignment(SBMLNamespaces sbmlns)
|
Modifier and Type | Method and Description |
---|---|
InitialAssignment |
cloneObject()
Creates and returns a deep copy of this
InitialAssignment . |
boolean |
containsUndeclaredUnits()
Predicate returning
true if the math expression of this
InitialAssignment contains parameters/numbers with undeclared units. |
void |
delete()
Explicitly deletes the underlying native object.
|
UnitDefinition |
getDerivedUnitDefinition()
Calculates and returns a
UnitDefinition that expresses the units
of measurement assumed for the 'math' expression of this
InitialAssignment . |
java.lang.String |
getElementName()
Returns the XML element name of this object, which for
InitialAssignment , is always 'initialAssignment'. |
ASTNode |
getMath()
Get the mathematical formula of this
InitialAssignment . |
java.lang.String |
getSymbol()
Get the value of the 'symbol' attribute of this
InitialAssignment . |
int |
getTypeCode()
Returns the libSBML type code for this SBML object.
|
boolean |
hasRequiredAttributes()
Predicate returning
true if all the required attributes for this
InitialAssignment object have been set. |
boolean |
hasRequiredElements()
Predicate returning
true if all the required elements for this
InitialAssignment object have been set. |
boolean |
isSetMath()
Predicate returning
true if this
InitialAssignment 's 'math' subelement contains a value. |
boolean |
isSetSymbol()
Predicate returning
true if this
InitialAssignment 's 'symbol' attribute is set. |
void |
renameSIdRefs(java.lang.String oldid,
java.lang.String newid)
Renames all the
SIdRef attributes on this element, including any
found in MathML. |
void |
renameUnitSIdRefs(java.lang.String oldid,
java.lang.String newid)
Renames all the
UnitSIdRef attributes on this element. |
int |
setMath(ASTNode math)
Sets the 'math' subelement of this
InitialAssignment . |
int |
setSymbol(java.lang.String sid)
Sets the 'symbol' attribute value of this
InitialAssignment . |
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getElementByMetaId, getElementBySId, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumPlugins, getPackageName, getPackageVersion, 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, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetId, unsetMetaId, unsetModelHistory, unsetName, unsetNotes, unsetSBOTerm
public InitialAssignment(InitialAssignment orig) throws SBMLConstructorException
InitialAssignment
.
orig
- the object to copy.
SBMLConstructorException
- Thrown if the argument orig
is null.
public InitialAssignment(long level, long version) throws SBMLConstructorException
level
- a long integer, the SBML Level to assign to this InitialAssignment
version
- a long integer, the SBML Version to assign to this
InitialAssignment
SBMLConstructorException
- Thrown if the given level
and version
combination, or this kind
of SBML object, are either invalid or mismatched with respect to the
parent SBMLDocument
object.
InitialAssignment
object to an SBMLDocument
(e.g., using Model.addInitialAssignment(InitialAssignment
ia)
), the SBML Level, SBML Version and XML namespace of the document
override the values used when creating the InitialAssignment
object
via this constructor. This is necessary to ensure that an SBML document
is a consistent structure. Nevertheless, the ability to supply the values
at the time of creation of a InitialAssignment
is an important aid to
producing valid SBML. Knowledge of the intented SBML Level and Version
determine whether it is valid to assign a particular value to an
attribute, or whether it is valid to add an object to an existing
SBMLDocument
.public InitialAssignment(SBMLNamespaces sbmlns) throws SBMLConstructorException
InitialAssignment
using the given SBMLNamespaces
object
sbmlns
.
The SBMLNamespaces
object encapsulates SBML Level/Version/namespaces
information. It is used to communicate the SBML Level, Version, and (in
Level 3) packages used in addition to SBML Level 3 Core. A
common approach to using libSBML's SBMLNamespaces
facilities is to create an
SBMLNamespaces
object somewhere in a program once, then hand that object
as needed to object constructors that accept SBMLNamespaces
as arguments.
sbmlns
- an SBMLNamespaces
object.
SBMLConstructorException
- Thrown if the given level
and version
combination, or this kind
of SBML object, are either invalid or mismatched with respect to the
parent SBMLDocument
object.
InitialAssignment
object to an SBMLDocument
(e.g., using Model.addInitialAssignment(InitialAssignment
ia)
), the SBML Level, SBML Version and XML namespace of the document
override the values used when creating the InitialAssignment
object
via this constructor. This is necessary to ensure that an SBML document
is a consistent structure. Nevertheless, the ability to supply the values
at the time of creation of a InitialAssignment
is an important aid to
producing valid SBML. Knowledge of the intented SBML Level and Version
determine whether it is valid to assign a particular value to an
attribute, or whether it is valid to add an object to an existing
SBMLDocument
.public InitialAssignment cloneObject()
InitialAssignment
.
cloneObject
 in class SBase
InitialAssignment
.public boolean containsUndeclaredUnits()
true
if the math expression of this
InitialAssignment
contains parameters/numbers with undeclared units.
containsUndeclaredUnits
 in class SBase
true
if the math expression of this InitialAssignment
includes parameters/numbers
with undeclared units, false
otherwise.
InitialAssignment.getDerivedUnitDefinition()
true
indicates that the UnitDefinition
returned by InitialAssignment.getDerivedUnitDefinition may not
accurately represent the units of the expression.
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 InitialAssignment.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 InitialAssignment.delete()
themselves.
public UnitDefinition getDerivedUnitDefinition()
UnitDefinition
that expresses the units
of measurement assumed for the 'math' expression of this
InitialAssignment
.
The units are calculated based on the mathematical expression in the
InitialAssignment
and the model quantities referenced by
<ci>
elements used within that expression. The method
InitialAssignment.getDerivedUnitDefinition()
returns the calculated
units, to the extent that libSBML can compute them.
getDerivedUnitDefinition
 in class SBase
UnitDefinition
that expresses the units of the math
expression of this InitialAssignment
, or null
if one cannot be constructed.
InitialAssignment.containsUndeclaredUnits()
null.
InitialAssignment
contains literal numbers or parameters
with undeclared units. In those cases, it is not possible to calculate
the units of the overall expression without making assumptions. LibSBML
does not make assumptions about the units, and
InitialAssignment.getDerivedUnitDefinition()
only returns the units as
far as it is able to determine them. For example, in an expression X
+ Y, if X has unambiguously-defined units and Y
does not, it will return the units of X. When using this method,
it is critical that callers also invoke the method
InitialAssignment.containsUndeclaredUnits()
to determine whether
this situation holds. Callers should take suitable action in
those situations.
public java.lang.String getElementName()
InitialAssignment
, is always 'initialAssignment'.
getElementName
 in class SBase
'initialAssignment'.
public ASTNode getMath()
InitialAssignment
.
ASTNode
, the value of the 'math' subelement of this
InitialAssignment
public java.lang.String getSymbol()
InitialAssignment
.
InitialAssignment
.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_INITIAL_ASSIGNMENT
(default).
InitialAssignment.getElementName()
,
SBase.getPackageName()
public boolean hasRequiredAttributes()
true
if all the required attributes for this
InitialAssignment
object have been set.
hasRequiredAttributes
 in class SBase
InitialAssignment
object are:
public boolean hasRequiredElements()
true
if all the required elements for this
InitialAssignment
object have been set.
hasRequiredElements
 in class SBase
InitialAssignment
object are:
public boolean isSetMath()
true
if this
InitialAssignment
's 'math' subelement contains a value.
true
if the 'math' for this InitialAssignment
is set,
false
otherwise.public boolean isSetSymbol()
true
if this
InitialAssignment
's 'symbol' attribute is set.
true
if the 'symbol' attribute of this InitialAssignment
is set, false
otherwise.public void renameSIdRefs(java.lang.String oldid, java.lang.String newid)
SIdRef
attributes on this element, including any
found in MathML.
In SBML, object identifiers are of a data type called SId
.
In SBML Level 3, an explicit data type called SIdRef
was
introduced for attribute values that refer to SId
values in
previous Levels of SBML, this data type did not exist and attributes were
simply described to as 'referring to an identifier', but the effective
data type was the same as SIdRef
in Level 3. These and
other methods of libSBML refer to the type SIdRef
for all
Levels of SBML, even if the corresponding SBML specification did not
explicitly name the data type.
This method works by looking at all attributes and (if appropriate)
mathematical formulas, comparing the identifiers to the value of
oldid
. If any matches are found, the matching identifiers are replaced
with newid
. The method does not descend into child elements.
renameSIdRefs
 in class SBase
oldid
- the old identifiernewid
- the new identifierpublic void renameUnitSIdRefs(java.lang.String oldid, java.lang.String newid)
UnitSIdRef
attributes on this element.
In SBML, unit definitions have identifiers of type UnitSId
. In
SBML Level 3, an explicit data type called UnitSIdRef
was
introduced for attribute values that refer to UnitSId
values in
previous Levels of SBML, this data type did not exist and attributes were
simply described to as 'referring to a unit identifier', but the effective
data type was the same as UnitSIdRef
in Level 3. These and
other methods of libSBML refer to the type UnitSIdRef
for all
Levels of SBML, even if the corresponding SBML specification did not
explicitly name the data type.
This method works by looking at all unit identifier attribute values
(including, if appropriate, inside mathematical formulas), comparing the
unit identifiers to the value of oldid
. If any matches are found,
the matching identifiers are replaced with newid
. The method does
not descend into child elements.
renameUnitSIdRefs
 in class SBase
oldid
- the old identifiernewid
- the new identifierpublic int setMath(ASTNode math)
InitialAssignment
.
The AST passed in math
is copied.
math
- an AST containing the mathematical expression to
be used as the formula for this InitialAssignment
.
public int setSymbol(java.lang.String sid)
InitialAssignment
.
sid
- the identifier of a Species
, Compartment
or Parameter
object defined elsewhere in this Model
.