public class Trigger extends SBase
An Event
object defines when the event can occur, the variables that are
affected by the event, and how the variables are affected. The Trigger
construct in SBML is used to define a mathematical expression that
determines when an Event
is triggered.
A Trigger
object in SBML Level 2 and Level 3 contains one
subelement named 'math' containing a MathML expression. The expression
is evaluated as a value of type boolean.
The exact moment at which
the expression evaluates to true
is the time point when the Event
is
triggered. In SBML Level 3, Trigger
has additional attributes
that must be assigned values they are discussed in a separate section
below.
In SBML Level 2 and SBML Level 3 Version 1, the 'math'
subelement is required, and it must evaluate to a boolean
expression.
In SBML Level 3 Version 2, those restrictions are relaxed:
the 'math' element is optional, and numeric values are allowed in
Boolean contexts (a '0' is interpreted as false
, and all other
values are interpreted as true
). If a Trigger
with no 'math'
is present in an Event
, that Event
will never trigger, unless that
missing information is included in an SBML Level 3 package.
An event only triggers when its Trigger
expression makes the
transition in value from false
to true.
The event will also
trigger at any subsequent time points when the trigger makes this
transition in other words, an event can be triggered multiple times
during a simulation if its trigger condition makes the transition from
false
to true
more than once. In SBML Level 3, the behavior
at the very start of simulation (i.e., at t = 0, where
t stands for time) is determined in part by the boolean flag
'initialValue'. This and other additional features introduced in SBML
Level 3 are discussed further below.
SBML Level 3 Version 1 introduces two required attributes
on the Trigger
object: 'persistent' and 'initialValue'. The rest of
this introduction describes these two attributes.
Trigger
In the interval between when an Event
object triggers (i.e.,
its Trigger
object expression transitions in value from false
to
true
) and when its assignments are to be executed, conditions
in the model may change such that the trigger expression transitions
back from true
to false.
Should the event's assignments still be
made if this happens? Answering this question is the purpose of the
'persistent' attribute on Trigger
.
If the boolean attribute 'persistent' has a value of true
, then once
the event is triggered, all of its assignments are always performed when
the time of execution is reached. The name persistent is meant to
evoke the idea that the trigger expression does not have to be
re-checked after it triggers if 'persistent'=true.
Conversely, if
the attribute value is false
, then the trigger expression is not
assumed to persist: if the expression transitions in value back to
false
at any time between when the event triggered and when it is to be
executed, the event is no longer considered to have triggered and its
assignments are not executed. (If the trigger expression transitions
once more to true
after that point, then the event is triggered, but
this then constitutes a whole new event trigger-and-execute sequence.)
The 'persistent' attribute can be especially useful when Event
objects
contain Delay
objects, but it is relevant even in a model without delays
if the model contains two or more events. As explained in the
introduction to this section, the operation of all events in SBML
(delayed or not) is conceptually divided into two phases,
triggering and execution however, unless events have
priorities associated with them, SBML does not mandate a particular
ordering of event execution in the case of simultaneous events. Models
with multiple events can lead to situations where the execution of one
event affects another event's trigger expression value. If that other
event has 'persistent'=false
, and its trigger expression evaluates to
false
before it is to be executed, the event must not be executed
after all.
Trigger
As mentioned above, an event triggers when the mathematical
expression in its Trigger
object transitions in value from false
to
true.
An unanswered question concerns what happens at the start of a
simulation: can event triggers make this transition at t = 0,
where t stands for time?
In order to determine whether an event may trigger at t = 0, it
is necessary to know what value the Trigger
object's 'math' expression
had immediately prior to t = 0. This starting value of the
trigger expression is determined by the value of the boolean attribute
'initialValue'. A value of true
means the trigger expression is
taken to have the value true
immediately prior to t = 0. In
that case, the trigger cannot transition in value from false
to
true
at the moment simulation begins (because it has the value true
both before and after t = 0), and can only make the transition
from false
to true
sometime after t = 0. (To do
that, it would also first have to transition to false
before it could
make the transition from false
back to true.
) Conversely, if
'initialValue'=false
, then the trigger expression is assumed to start
with the value false
, and therefore may trigger at t = 0 if
the expression evaluates to true
at that moment.
Event
,
Delay
,
EventAssignment
Constructor and Description |
---|
Trigger(long level,
long version)
|
Trigger(SBMLNamespaces sbmlns)
|
Trigger(Trigger orig)
Copy constructor creates a copy of this
Trigger . |
Modifier and Type | Method and Description |
---|---|
Trigger |
cloneObject()
Creates and returns a deep copy of this
Trigger object. |
void |
delete()
Explicitly deletes the underlying native object.
|
java.lang.String |
getElementName()
Returns the XML element name of this object, which for
Trigger , is
always 'trigger'. |
boolean |
getInitialValue()
(SBML Level 3 only) Get the value of the 'initialValue' attribute
of this
Trigger . |
ASTNode |
getMath()
Get the mathematical formula for the trigger and return it
as an AST.
|
boolean |
getPersistent()
(SBML Level 3 only) Get the value of the 'persistent' attribute
of this
Trigger . |
int |
getTypeCode()
Returns the libSBML type code of this object instance.
|
boolean |
hasRequiredAttributes()
Predicate returning
true if
all the required attributes for this Trigger object
have been set. |
boolean |
hasRequiredElements()
Predicate returning
true if
all the required elements for this Trigger object
have been set. |
boolean |
isSetInitialValue()
(SBML Level 3 only) Predicate to test whether the 'initialValue'
attribute for this trigger is set.
|
boolean |
isSetMath()
Predicate to test whether the math for this trigger is set.
|
boolean |
isSetPersistent()
(SBML Level 3 only) Predicate to test whether the 'persistent'
attribute for this trigger is set.
|
int |
removeFromParentAndDelete()
|
void |
renameSIdRefs(java.lang.String oldid,
java.lang.String newid)
Replaces all uses of a given
SIdRef type attribute value with another
value. |
void |
renameUnitSIdRefs(java.lang.String oldid,
java.lang.String newid)
Replaces all uses of a given
UnitSIdRef type attribute value with
another value. |
int |
setInitialValue(boolean initialValue)
(SBML Level 3 only) Sets the 'initialValue' attribute of this
Trigger instance. |
int |
setMath(ASTNode math)
|
int |
setPersistent(boolean persistent)
(SBML Level 3 only) Sets the 'persistent' attribute of this
Trigger instance. |
int |
unsetInitialValue()
(SBML Level 3 only) Unsets the 'initialValue' attribute of this
Trigger instance. |
int |
unsetPersistent()
(SBML Level 3 only) Unsets the 'persistent' attribute of this
Trigger instance. |
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, connectToChild, deleteDisabledPlugins, deleteDisabledPlugins, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getDisabledPlugin, getElementByMetaId, getElementBySId, getId, getIdAttribute, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getName, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumDisabledPlugins, getNumPlugins, getPackageCoreVersion, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isPkgEnabled, isPkgURIEnabled, isSetAnnotation, isSetId, isSetIdAttribute, isSetMetaId, isSetModelHistory, isSetName, isSetNotes, isSetSBOTerm, isSetUserData, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setId, setIdAttribute, setMetaId, setModelHistory, setName, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetId, unsetIdAttribute, unsetMetaId, unsetModelHistory, unsetName, unsetNotes, unsetSBOTerm, unsetUserData
public Trigger(long level, long version) throws SBMLConstructorException
level
- a long integer, the SBML Level to assign to this Trigger
.
version
- a long integer, the SBML Version to assign to this
Trigger
.
SBMLConstructorException
- Thrown if the given level
and version
combination are invalid
or if this object is incompatible with the given level and version.
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.public Trigger(SBMLNamespaces sbmlns) throws SBMLConstructorException
Trigger
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 sbmlns
is inconsistent or incompatible
with this object.
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.public Trigger(Trigger orig) throws SBMLConstructorException
Trigger
.
orig
- the object 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 Trigger.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 Trigger.delete()
themselves.
public Trigger cloneObject()
Trigger
object.
cloneObject
 in class SBase
Trigger
object.public ASTNode getMath()
Trigger
, or null
if the math is not set.public boolean getInitialValue()
Trigger
.
Trigger
.
public boolean getPersistent()
Trigger
.
Trigger
.
public boolean isSetMath()
true
if the formula (meaning the 'math' subelement) of
this Trigger
is set, false
otherwise.public boolean isSetInitialValue()
true
if the initialValue attribute of
this Trigger
is set, false
otherwise.
public boolean isSetPersistent()
true
if the persistent attribute of
this Trigger
is set, false
otherwise.
public int setMath(ASTNode math)
math
- an ASTNode
representing a formula tree.
public int setInitialValue(boolean initialValue)
Trigger
instance.
initialValue
- a boolean representing the initialValue to be set.
public int setPersistent(boolean persistent)
Trigger
instance.
persistent
- a boolean representing the persistent value to be set.
public int unsetInitialValue()
Trigger
instance.
public int unsetPersistent()
Trigger
instance.
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
method on the object.
SBase.getPackageName()
getTypeCode
 in class SBase
SBML_TRIGGER
(default).
Trigger.getElementName()
,
SBase.getPackageName()
public java.lang.String getElementName()
Trigger
, is
always 'trigger'.
getElementName
 in class SBase
'trigger'.
public void renameSIdRefs(java.lang.String oldid, java.lang.String newid)
Replaces all uses of a given SIdRef
type attribute value with another
value.
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 in MathML content, comparing the referenced
identifiers to the value of oldid
. If any matches are found, the
matching values are replaced with newid
. The method does not
descend into child elements.
renameSIdRefs
 in class SBase
oldid
- the old identifier.newid
- the new identifier.public void renameUnitSIdRefs(java.lang.String oldid, java.lang.String newid)
Replaces all uses of a given UnitSIdRef
type attribute value with
another value.
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
referenced unit identifiers to the value of oldid
. If any matches
are found, the matching values are replaced with newid
. The method
does not descend into child elements.
renameUnitSIdRefs
 in class SBase
oldid
- the old identifier.newid
- the new identifier.public boolean hasRequiredElements()
true
if
all the required elements for this Trigger
object
have been set.
hasRequiredElements
 in class SBase
Trigger
object are:
public boolean hasRequiredAttributes()
true
if
all the required attributes for this Trigger
object
have been set.
The required attributes for a Trigger
object are:
hasRequiredAttributes
 in class SBase
public int removeFromParentAndDelete()
Trigger
's Event
parent and calls unsetTrigger() on it, indirectly deleting itself. Overridden from the SBase
function since the parent is not a ListOf
.
removeFromParentAndDelete
 in class SBase