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
must evaluate to 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.
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 . |
void |
delete()
Explicitly deletes the underlying native object.
|
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(String oldid,
String newid)
Renames all the SIdRef attributes on this element, including any found in MathML
|
void |
renameUnitSIdRefs(String oldid,
String newid)
Renames all the UnitSIdRef attributes on this element
|
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. |
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getElementByMetaId, getElementBySId, getLevel, getLine, getListOfAllElements, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumPlugins, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isSetAnnotation, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, unsetAnnotation, unsetCVTerms, unsetId, unsetMetaId, unsetModelHistory, unsetName, unsetNotes, unsetSBOTerm
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, or this kind
of SBML object, are either invalid or mismatched with respect to the
parent SBMLDocument
object.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 this class constructor is to create an
SBMLNamespaces
object somewhere in a program, once, then pass it to
object constructors such as this one when needed.
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.public Trigger(Trigger orig) throws SBMLConstructorException
Trigger
.
orig
- the object to copy.
SBMLConstructorException
- Thrown if the argument orig
is null.
public Trigger cloneObject()
Trigger
.
cloneObject
 in class SBase
Trigger
.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 String getElementName()
Trigger
, is
always 'trigger'.
getElementName
 in class SBase
'trigger'.
public boolean getInitialValue()
Trigger
.
Trigger
.
public ASTNode getMath()
Trigger
.public boolean getPersistent()
Trigger
.
Trigger
.
public int getTypeCode()
LibSBML attaches an identifying code to every
kind of SBML object. These are known as SBML type codes. In
other languages, the set of type codes is stored in an enumeration in
the Java language interface for libSBML, the type codes are defined as
static integer constants in the interface class libsbmlConstants
. The names of the type codes all begin with the
characters SBML_.
getTypeCode
 in class SBase
SBML_UNKNOWN
(default).
Trigger.getElementName()
public boolean hasRequiredAttributes()
true
if
all the required attributes for this Trigger
object
have been set.
hasRequiredAttributes
 in class SBase
Trigger
object are:
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 isSetInitialValue()
true
if the initialValue attribute of
this Trigger
is set, false
otherwise.
public boolean isSetMath()
true
if the formula (meaning the 'math' subelement) of
this Trigger
is set, false
otherwise.public boolean isSetPersistent()
true
if the persistent attribute of
this Trigger
is set, false
otherwise.
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
public void renameSIdRefs(String oldid, String newid)
renameSIdRefs
 in class SBase
oldid
- the old identifiernewid
- the new identifierpublic void renameUnitSIdRefs(String oldid, String newid)
renameUnitSIdRefs
 in class SBase
oldid
- the old identifiernewid
- the new identifierpublic int setInitialValue(boolean initialValue)
Trigger
instance.
initialValue
- a boolean representing the initialValue to be set.
public int setMath(ASTNode math)
math
- an ASTNode
representing a formula tree.
public int setPersistent(boolean persistent)
Trigger
instance.
persistent
- a boolean representing the persistent value to be set.