public class Priority extends SBase
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
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.
In SBML Level 3 Version 2, the requirement that a Priority
have a 'math' subelement was relaxed, making it optional. In
this case, the Priority
remains undefined, and unless that information
is provided in some other form (such as with an SBML Level 3
package), the Event
behaves as if it had no Priority
.
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 object. |
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)
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 |
setMath(ASTNode math)
|
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, getObjectVersion, 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 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 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.
, The Priority
construct exists only in SBML Level 3 it
cannot be used in SBML Level 2 or Level 1 models.
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 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.
, 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
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 Priority cloneObject()
Priority
object.
cloneObject
 in class SBase
Priority
object.public ASTNode getMath()
Priority
, or null
if the math is not set.public boolean isSetMath()
true
if the formula (meaning the math
subelement) of
this Priority
is set, false
otherwise.public int setMath(ASTNode math)
math
- an ASTNode
representing a formula tree.
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_PRIORITY
(default).
Priority.getElementName()
,
SBase.getPackageName()
public java.lang.String getElementName()
Priority
, is
always 'priority'.
getElementName
 in class SBase
'priority'.
Priority.getTypeCode()
public boolean hasRequiredElements()
true
if all the required elements for this
Priority
object have been set.
hasRequiredElements
 in class SBase
Priority
object are:
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)
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.