public class Priority extends SBase
Event
.
The Priority
object class (which was introduced in SBML Level 3
Version 1), like Delay
, is derived from SBase
and contains a MathML
formula stored in the element 'math'. This formula is used to compute a
dimensionless numerical value that influences the order in which a
simulator is to perform the assignments of two or more events that
happen to be executed simultaneously. The formula may evaluate to any
double
value (and thus may be a positive or negative number, or
zero), with positive numbers taken to signifying a higher priority than
zero or negative numbers. If no Priority
object is present on a given
Event
object, no priority is defined for that event.
For the purposes of SBML, simultaneous event execution is
defined as the situation in which multiple events have identical
times of execution. The time of execution is calculated as the
sum of the time at which a given event's Trigger
is triggered
plus its Delay
duration, if any. Here, identical times means
mathematically equal instants in time. (In practice,
simulation software adhering to this specification may have to
rely on numerical equality instead of strict mathematical
equality robust models will ensure that this difference will not
cause significant discrepancies from expected behavior.)
If no Priority
subobjects are defined for two or more Event
objects,
then those events are still executed simultaneously but their order of
execution is undefined by the SBML Level 3 Version 1
specification. A software implementation may choose to execute
such simultaneous events in any order, as long as each event is executed
only once and the requirements of checking the 'persistent' attribute
(and acting accordingly) are satisfied.
If Priority
subobjects are defined for two or more
simultaneously-triggered events, the order in which those particular
events must be executed is dictated by their Priority
objects,
as follows. If the values calculated using the two Priority
objects' 'math' expressions differ, then the event having
the higher priority value must be executed before the event with
the lower value. If, instead, the two priority values are
mathematically equal, then the two events must be triggered in a
random order. It is important to note that a random
order is not the same as an undefined order: given multiple
runs of the same model with identical conditions, an undefined
ordering would permit a system to execute the events in (for
example) the same order every time (according to whatever scheme
may have been implemented by the system), whereas the explicit
requirement for random ordering means that the order of execution
in different simulation runs depends on random chance. In other
words, given two events A and B, a randomly-determined
order must lead to an equal chance of executing A first or
B first, every time those two events are executed
simultaneously.
A model may contain a mixture of events, some of which have
Priority
subobjects and some do not. Should a combination of
simultaneous events arise in which some events have priorities
defined and others do not, the set of events with defined
priorities must trigger in the order determined by their Priority
objects, and the set of events without Priority
objects must be
executed in an undefined order with respect to each other
and with respect to the events with Priority
subobjects. (Note
that undefined order does not necessarily mean random
order, although a random ordering would be a valid implementation
of this requirement.)
The following example may help further clarify these points.
Suppose a model contains four events that should be executed
simultaneously, with two of the events having Priority
objects
with the same value and the other two events having Priority
objects with the same, but different, value. The two events with
the higher priorities must be executed first, in a random order
with respect to each other, and the remaining two events must be
executed after them, again in a random order, for a total of four
possible and equally-likely event executions: A-B-C-D, A-B-D-C,
B-A-C-D, and B-A-D-C. If, instead, the model contains four events
all having the same Priority
values, there are 4! or 24
possible orderings, each of which must be equally likely to be
chosen. Finally, if none of the four events has a Priority
subobject defined, or even if exactly one of the four events has a
defined Priority
, there are again 24 possible orderings, but the
likelihood of choosing any particular ordering is undefined the
simulator can choose between events as it wishes. (The SBML
specification only defines the effects of priorities on Event
objects with respect to other Event
objects with
priorities. Putting a priority on a single Event
object
in a model does not cause it to fall within that scope.)
Priority
expressions
An event's Priority
object 'math' expression must be
evaluated at the time the Event
is to be executed. During
a simulation, all simultaneous events have their Priority
values
calculated, and the event with the highest priority is selected for
next execution. Note that it is possible for the execution of one
Event
object to cause the Priority
value of another
simultaneously-executing Event
object to change (as well as to
trigger other events, as already noted). Thus, after executing
one event, and checking whether any other events in the model have
been triggered, all remaining simultaneous events that
either (i) have Trigger
objects with attributes
'persistent'=false
or (ii) have Trigger
expressions that did not transition from true
to
false
, must have their Priority
expression reevaluated.
The highest-priority remaining event must then be selected for
execution next.
Priority
object's mathematical expressions
The unit associated with the value of a Priority
object's
'math' expression should be dimensionless.
This is
because the priority expression only serves to provide a relative
ordering between different events, and only has meaning with
respect to other Priority
object expressions. The value of
Priority
objects is not comparable to any other kind of object in
an SBML model.
Event
,
Delay
,
EventAssignment
Priority
construct exists only in SBML Level 3 it cannot
be used in SBML Level 2 or Level 1 models.
Constructor and Description |
---|
Priority(long level,
long version)
|
Priority(Priority orig)
Copy constructor creates a copy of this
Priority . |
Priority(SBMLNamespaces sbmlns)
|
Modifier and Type | Method and Description |
---|---|
Priority |
cloneObject()
Creates and returns a deep copy of this
Priority . |
void |
delete()
Explicitly deletes the underlying native object.
|
java.lang.String |
getElementName()
Returns the XML element name of this object, which for
Priority , is
always 'priority'. |
ASTNode |
getMath()
Get the mathematical formula for the priority and return it
as an AST.
|
int |
getTypeCode()
Returns the libSBML type code of this object instance.
|
boolean |
hasRequiredElements()
Predicate returning
true if all the required elements for this
Priority object have been set. |
boolean |
isSetMath()
Predicate to test whether the formula for this delay is set.
|
int |
removeFromParentAndDelete()
|
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)
|
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, 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 Priority(long level, long version) throws SBMLConstructorException
level
- a long integer, the SBML Level to assign to this Priority
version
- a long integer, the SBML Version to assign to this
Priority
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.
Priority
object to an Event
(e.g., using
Event.setPriority(Priority d)
), the SBML Level, SBML Version
and XML namespace of the document override the values used when
creating the Priority
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 Priority
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 a
particular Priority
object to an existing Event
.
, The Priority
construct exists only in SBML Level 3 it
cannot be used in SBML Level 2 or Level 1 models.
public Priority(Priority orig) throws SBMLConstructorException
Priority
.
orig
- the object to copy.
SBMLConstructorException
- Thrown if the argument orig
is null.
public Priority(SBMLNamespaces sbmlns) throws SBMLConstructorException
Priority
object 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.
Priority
object to an Event
(e.g., using
Event.setPriority(Priority d)
), the SBML Level, SBML Version
and XML namespace of the document override the values used when
creating the Priority
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 Priority
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 a
particular Priority
object to an existing Event
.
, The Priority
construct exists only in SBML Level 3 it
cannot be used in SBML Level 2 or Level 1 models.
public Priority cloneObject()
Priority
.
cloneObject
 in class SBase
Priority
.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 Priority.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 Priority.delete()
themselves.
public java.lang.String getElementName()
Priority
, is
always 'priority'.
getElementName
 in class SBase
'priority'.
Priority.getTypeCode()
public ASTNode getMath()
Priority
.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_PRIORITY
(default).
Priority.getElementName()
,
SBase.getPackageName()
public boolean hasRequiredElements()
true
if all the required elements for this
Priority
object have been set.
hasRequiredElements
 in class SBase
Priority
object are:
public boolean isSetMath()
true
if the formula (meaning the math
subelement) of
this Priority
is set, false
otherwise.public int removeFromParentAndDelete()
Priority
's Event
parent and calls unsetPriority() on it,
indirectly deleting itself.
Overridden from the SBase
function since the parent is not a ListOf
.
removeFromParentAndDelete
 in class SBase
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 identifier