|
libSBML C API
5.18.0
|
|
libSBML C API
5.18.0
|
The Priority_t object class (which was introduced in SBML Level 3 Version 1), like Delay_t, is derived from SBase_t 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_t object is present on a given Event_t 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_t is triggered plus its Delay_t 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_t subobjects are defined for two or more Event_t 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_t 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_t objects, as follows. If the values calculated using the two Priority_t 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_t 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_t objects, and the set of events without Priority_t objects must be executed in an undefined order with respect to each other and with respect to the events with Priority_t 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_t objects with the same value and the other two events having Priority_t 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_t 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_t subobject defined, or even if exactly one of the four events has a defined Priority_t, 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_t objects with respect to other Event_t objects with priorities. Putting a priority on a single Event_t object in a model does not cause it to fall within that scope.)
An event's Priority_t object "math" expression must be evaluated at the time the Event_t is to be executed. During a simulation, all simultaneous events have their Priority_t 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_t object to cause the Priority_t value of another simultaneously-executing Event_t 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_t objects with attributes "persistent"=false or (ii) have Trigger_t expressions that did not transition from true to false, must have their Priority_t expression reevaluated. The highest-priority remaining event must then be selected for execution next.
The unit associated with the value of a Priority_t 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_t object expressions. The value of Priority_t objects is not comparable to any other kind of object in an SBML model.
In SBML Level 3 Version 2, the requirement that a Priority_t have a "math" subelement was relaxed, making it optional. In this case, the Priority_t remains undefined, and unless that information is provided in some other form (such as with an SBML Level 3 package), the Event_t behaves as if it had no Priority_t.
Public Member Functions | |
| Priority_t * | Priority_clone (const Priority_t *p) |
| Creates and returns a deep copy of the given Priority_t structure. More... | |
| Priority_t * | Priority_create (unsigned int level, unsigned int version) |
Creates a new Priority_t structure using the given SBML level and version values. More... | |
| Priority_t * | Priority_createWithNS (SBMLNamespaces_t *sbmlns) |
| Creates a new Priority_t structure using the given SBMLNamespaces_t structure. More... | |
| void | Priority_free (Priority_t *p) |
| Frees the given Priority_t structure. More... | |
| const ASTNode_t * | Priority_getMath (const Priority_t *p) |
| Get the mathematical formula for a Priority_t structure and return it as as an ASTNode_t structure. More... | |
| const XMLNamespaces_t * | Priority_getNamespaces (Priority_t *p) |
| Returns a list of XMLNamespaces_t associated with this Priority_t structure. More... | |
| int | Priority_isSetMath (const Priority_t *p) |
| Predicate to test whether the formula for the given Priority_t structure is set. More... | |
| int | Priority_setMath (Priority_t *p, const ASTNode_t *math) |
| Sets the math expression of the given Priority_t instance to a copy of the given ASTNode_t structure. More... | |
| Priority_t * Priority_clone | ( | const Priority_t * | p | ) |
Creates and returns a deep copy of the given Priority_t structure.
| p | the Priority_t structure to copy. |
t. | Priority_t * Priority_create | ( | unsigned int | level, |
| unsigned int | version | ||
| ) |
Creates a new Priority_t structure using the given SBML level and version values.
| level | an unsigned int, the SBML Level to assign to this Priority_t. |
| version | an unsigned int, the SBML Version to assign to this Priority_t. |
| Priority_t * Priority_createWithNS | ( | SBMLNamespaces_t * | sbmlns | ) |
Creates a new Priority_t structure using the given SBMLNamespaces_t structure.
| sbmlns | SBMLNamespaces_t, a pointer to an SBMLNamespaces_t structure to assign to this Priority_t. |
| void Priority_free | ( | Priority_t * | p | ) |
Frees the given Priority_t structure.
| p | the Priority_t structure to free. |
| const ASTNode_t * Priority_getMath | ( | const Priority_t * | p | ) |
Get the mathematical formula for a Priority_t structure and return it as as an ASTNode_t structure.
| p | the Priority_t structure to query. |
| const XMLNamespaces_t * Priority_getNamespaces | ( | Priority_t * | p | ) |
Returns a list of XMLNamespaces_t associated with this Priority_t structure.
| p | the Priority_t structure. |
| int Priority_isSetMath | ( | const Priority_t * | p | ) |
Predicate to test whether the formula for the given Priority_t structure is set.
| p | the Priority_t structure to query. |
1 (true) if the formula (meaning the math subelement) of this Priority_t is set, 0 (false) otherwise. | int Priority_setMath | ( | Priority_t * | p, |
| const ASTNode_t * | math | ||
| ) |
Sets the math expression of the given Priority_t instance to a copy of the given ASTNode_t structure.
| p | the Priority_t structure to set. |
| math | an ASTNode_t representing a formula tree. |