org.sbml.libsbml

Class Priority

java.lang.Object

org.sbml.libsbml.SBase

org.sbml.libsbml.Priority

public class Priority
extends SBase

The priority of execution of an SBML 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.

The interpretation of priorities on events in a model

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.)

Evaluation of 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.

Units of 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.

See Also:

Event, Delay, EventAssignment

Note:

The Priority construct exists only in SBML Level 3; it cannot be used in SBML Level 2 or Level 1 models.

Restrictions relaxed in SBML Level 3 Version 2

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 Summary

Constructors

Constructor and Description
Priority(long level, long version) Creates a new Priority object using the given SBML level and version values.
Priority(Priority orig) Copy constructor; creates a copy of this Priority.
Priority(SBMLNamespaces sbmlns) Creates a new Priority object using the given SBMLNamespaces object sbmlns.

Method Summary

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() Finds this Priority's Event parent and calls unsetPriority() on it, indirectly deleting itself.
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) Sets the math expression of this Priority instance to a copy of the given ASTNode.

Methods inherited from class org.sbml.libsbml.SBase

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

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Priority

public Priority(long level,
                long version)
         throws SBMLConstructorException

Creates a new Priority object using the given SBML level and version values.

Parameters:

level - a long integer, the SBML Level to assign to this Priority.

version - a long integer, the SBML Version to assign to this Priority.

Throws:

SBMLConstructorException - Thrown if the given level and version combination are invalid or if this object is incompatible with the given level and version.

Note:

Attempting to add an object to an 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.

Priority

public Priority(SBMLNamespaces sbmlns)
         throws SBMLConstructorException

Creates a new 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.

Parameters:

sbmlns - an SBMLNamespaces object.

Throws:

SBMLConstructorException - Thrown if the given sbmlns is inconsistent or incompatible with this object.

Note:

Attempting to add an object to an 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.

Priority

public Priority(Priority orig)
         throws SBMLConstructorException

Copy constructor; creates a copy of this Priority.

Parameters:

orig - the object to copy.

Throws:

SBMLConstructorException

Method Detail

delete

public void delete()

Explicitly deletes the underlying native object.

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.

Overrides:

delete in class SBase

cloneObject

public Priority cloneObject()

Creates and returns a deep copy of this Priority object.

Overrides:

cloneObject in class SBase

Returns:

the (deep) copy of this Priority object.

getMath

public ASTNode getMath()

Get the mathematical formula for the priority and return it as an AST.

Returns:

the math of this Priority, or null if the math is not set.

isSetMath

public boolean isSetMath()

Predicate to test whether the formula for this delay is set.

Returns:

true if the formula (meaning the math subelement) of this Priority is set, false otherwise.

setMath

public int setMath(ASTNode math)

Sets the math expression of this Priority instance to a copy of the given ASTNode.

Parameters:

math - an ASTNode representing a formula tree.

Returns:

integer value indicating success/failure of the function. The possible values returned by this function are:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_INVALID_OBJECT

getTypeCode

public int getTypeCode()

Returns the libSBML type code of this object instance.

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 SBase.getPackageName() method on the object.

The exception to this is lists: all SBML-style list elements have the type SBML_LIST_OF, regardless of what package they are from.

Overrides:

getTypeCode in class SBase

Returns:

the SBML type code for this object: SBML_PRIORITY (default).

See Also:

Priority.getElementName(), SBase.getPackageName()

Warning:

The specific integer values of the possible type codes may be reused by different libSBML plug-ins for SBML Level 3. packages, To fully identify the correct code, it is necessary to invoke both getPackageName() and getTypeCode() (or ListOf.getItemTypeCode()).

getElementName

public java.lang.String getElementName()

Returns the XML element name of this object, which for Priority, is always 'priority'.

Overrides:

getElementName in class SBase

Returns:

the name of this element, i.e., 'priority'.

See Also:

Priority.getTypeCode()

hasRequiredElements

public boolean hasRequiredElements()

Predicate returning true if all the required elements for this Priority object have been set.

Overrides:

hasRequiredElements in class SBase

Returns:

a boolean value indicating whether all the required elements for this object have been defined.

Note:

The required elements for a Priority object are:

• 'math' inSBML Level 2 and Level 3 Version 1. (In SBML Level 3 Version 2+, it is no longer required.)

removeFromParentAndDelete

public int removeFromParentAndDelete()

Finds this Priority's Event parent and calls unsetPriority() on it, indirectly deleting itself.

Overridden from the SBase function since the parent is not a ListOf.

Overrides:

removeFromParentAndDelete in class SBase

Returns:

integer value indicating success/failure of the function. The possible values returned by this function are:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_OPERATION_FAILED

renameSIdRefs

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.

Overrides:

renameSIdRefs in class SBase

Parameters:

oldid - the old identifier.

newid - the new identifier.

renameUnitSIdRefs

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.

Overrides:

renameUnitSIdRefs in class SBase

Parameters:

oldid - the old identifier.

newid - the new identifier.