Detailed Description

A discontinuous SBML event.

An SBML Event_t object defines when the event can occur, the variables that are affected by it, how the variables are affected, and the event's relationship to other events. The effect of the event can optionally be delayed after the occurrence of the condition which invokes it.

The operation of Event_t is divided into two phases (even when the event is not delayed): one when the event is triggered, and the other when the event is executed. Trigger_t objects define the conditions for triggering an event, Delay_t objects define when the event is actually executed, EventAssignment_t objects define the effects of executing the event, and (in SBML Level 3) Priority_t objects influence the order of EventAssignment_t performance in cases of simultaneous events. Please consult the descriptions of Trigger_t, Delay_t, EventAssignment_t and Priority_t for more information.

SBML Level/Version differences

SBML Level 2

In SBML Level 2 versions before Version 4, the semantics of Event_t time delays were defined such that the expressions in the event's assignments were always evaluated at the time the event was triggered. This definition made it difficult to define an event whose assignment formulas were meant to be evaluated at the time the event was executed (i.e., after the time period defined by the value of the Delay_t element, or after any other simultaneous event may have been executed and changed the model state). In SBML Level 2 Version 4 and in Level 3, the attribute "useValuesFromTriggerTime" on Event_t was added to allow a model to indicate the time at which the event's assignments are to be calculated, whether at the moment the event is triggered (if the value of the attribute is true), or at the moment of execution (if "useValuesFromTriggerTime"=false). If the event has a delay, the "useValuesFromTriggerTime" is likely to make a significant difference in the values used in the assignment, but the possibility of simultaneous events mean that even zero-delay events can have different results depending on the value of this attribute.

The definition of Event_t in SBML Level 2 Versions 1 and 2 includes an additional attribute called "timeUnits", which allowed the time units of the Delay_t to be set explicitly. Later Versions of SBML Level 2 as well as SBML Level 3 do not define this attribute. LibSBML supports this attribute for compatibility with previous versions of SBML Level 2; however, if a model in SBML Level 3 or Level 2 Versions 3–4 format sets the attribute, the consistency-checking method SBMLDocument_t::checkConsistency() will report an error.

The attribute "useValuesFromTriggerTime" was introduced in SBML Level 2 Version 4. Models defined in prior Versions of SBML Level 2 cannot use this attribute, and SBMLDocument_t::checkConsistency() will report an error if they do.

SBML Level 3

SBML Level 3 introduces several changes to the structure and components of Events compared to SBML Level 2. These changes fall into two main categories: changes to what is optional or required, and additions of new attributes and elements.

The attribute "useValuesFromTriggerTime" on Event_t is mandatory (it was optional in Level 2 and had a default value of true);
Event_t's "listOfEventAssignments" element (of class ListOfEventAssignments_t) is optional (it was mandatory in Level 2);
Event_t's "priority" element (of class Priority_t) is new in Level 3; and
The Trigger_t object gains new mandatory attributes (described as part of the definition of Trigger_t).
In SBML Level 3 Version 2, the Trigger_t object became optional. An Event_t with no Trigger_t will simply not fire.

The changes to the attributes of Event_t are described below; the changes to Trigger_t and Priority_t are described in their respective sections.

Semantics of events in SBML Level 3 Version 1

The detailed semantics of events are described in the specification documents for each SBML Level/Version. Here we include the description from the SBML Level 1 Version 1. Any transition of a Trigger_t object's "math" formula from the value false to true will cause the enclosing Event_t object to trigger. Such a transition is not possible at the very start of a simulation (i.e., at time t = 0) unless the Trigger_t object's "initialValue" attribute has a value of false; this defines the value of the trigger formula to be false immediately prior to the start of simulation, thereby giving it the potential to change in value from false to true when the formula is evaluated at t = 0. If "initialValue"=true, then the trigger expression cannot transition from false to true at t = 0 but may do so at some time t > 0.

Consider an Event_t object definition E with delay d in which the Trigger_t object's "math" formula makes a transition in value from false to true at times t₁ and t₂. The EventAssignment_t within the Event_t object will have effect at t₁ + d and t₂ + d irrespective of the relative times of t₁ and t₂. For example, events can "overlap" so that t₁ < t₂ < t₁ + d still causes an event assignments to occur at t₁ + d and t₂ + d.

It is entirely possible for two events to be executed simultaneously, and it is possible for events to trigger other events (i.e., an event assignment can cause an event to trigger). This leads to several points:

A software package should retest all event triggers after executing an event assignment in order to account for the possibility that the assignment causes another event trigger to transition from false to true. This check should be made after each individual Event_t object's execution, even when several events are to be executed simultaneously.
Any Event_t object whose Trigger_t "persistent" attribute has the value false must have its trigger expression reevaluated continuously between when the event is triggered and when it is executed. If its trigger expression ever evaluates to false, it must be removed from the queue of events pending execution and treated as any other event whose trigger expression evaluates to false.
Although the precise time at which events are executed is not resolved beyond the given execution point in simulated time, it is assumed that the order in which the events occur is resolved. This order can be significant in determining the overall outcome of a given simulation. When an event X triggers another event Y and event Y has zero delay, then event Y is added to the existing set of simultaneous events that are pending execution. Events X and Y form a cascade of events at the same point in simulation time. An event such as Y may have a special priority if it contains a Priority_t subobject.
All events in a model are open to being in a cascade. The position of an event in the event queue does not affect whether it can be in the cascade: event Y can be triggered whether it is before or after X in the queue of events pending execution. A cascade of events can be potentially infinite (never terminate); when this occurs a simulator should indicate this has occurred—it is incorrect for a simulator to break a cascade arbitrarily and continue the simulation without at least indicating that the infinite cascade occurred.
Simultaneous events having no defined priorities are executed in an undefined order. This does not mean that the behavior of the simulation is completely undefined; merely that the order of execution of these particular events is undefined. A given simulator may use any algorithm to choose an order as long as every event is executed exactly once.
Events with defined priorities are executed in the order implied by their Priority_t "math" formula values, with events having higher priorities being executed ahead of events with lower priorities, and events with identical priorities being executed in a random order with respect to one another (as determined at run-time by some random algorithm equivalent to coin-flipping). Newly-triggered events that are to be executed immediately (i.e., if they define no delays) should be inserted into the queue of events pending execution according to their priorities: events with higher priority values value must be inserted ahead of events with lower priority values and after any pending events with even higher priorities, and inserted randomly among pending events with the same priority values. Events without Priority_t objects must be inserted into the queue in some fashion, but the algorithm used to place it in the queue is undefined. Similarly, there is no restriction on the order of a newly-inserted event with a defined Priority_t with respect to any other pending Event_t without a defined Priority_t.
A model variable that is the target of one or more event assignments can change more than once when simultaneous events are processed at some time point t. The model's behavior (output) for such a variable is the value of the variable at the end of processing all the simultaneous events at time t.

Restrictions relaxed in SBML Level 3 Version 2

In SBML Level 3 Version 2, several restrictions were lifted that have the potential to affect the semantics of an Event_t:

The Trigger_t subobject of an Event_t is optional. If missing, an Event_t is never triggered, unless an alternate triggering scheme is introduced by an SBML Level 3 package.
The "math" subelements of an Event_t Trigger_t, Delay_t, Priority_t, and EventAssignment_t are all optional. If any of these elements lack a "math" subelement, and that information is not supplied in an SBML Level 3 package, it is mathematically equivalent to the Trigger_t, Delay_t, Priority_t, or EventAssignment_t not being present at all.
The ListOfEventAssignments_t may be empty, which is mathematically equivalent to the Event_t not having a ListOfEventAssignments_t at all.
Any "math" subelement may return a Boolean or a numeric value in any context. If a numeric value is used in a Boolean context, a "0" is interpreted as false, and all other values are interpreted as true. If a Boolean value is used in a numeric context, a true is interpreted as a 1, and a false is interpreted as a 0. This means (for example) that a Trigger_t value that changes from 0.0 to anything else is equivalent to changing from false to true.

See also: Trigger_t; Priority_t; Delay_t; EventAssignment_t

Examples:: printAnnotation.c, printMath.c, printNotes.c, printUnits.c, unsetAnnotation.c, and unsetNotes.c.

Public Member Functions
int	Event_addEventAssignment (Event_t e, const EventAssignment_t ea)
	Appends a copy of the given EventAssignment_t structure to the given Event_t structure. More...

Event_t *	Event_clone (const Event_t *e)
	Returns a copy of the given Event_t structure. More...

Event_t *	Event_create (unsigned int level, unsigned int version)
	Creates a new Event_t structure using the given SBML `level` and `version` values. More...

Delay_t *	Event_createDelay (Event_t *e)
	Creates a new, empty Delay_t structure, adds it to this Event_t, and returns the Delay_t. More...

EventAssignment_t *	Event_createEventAssignment (Event_t *e)
	Creates a new, empty EventAssignment_t structure, adds it to this Event_t's list of event assignments, and returns the EventAssignment_t. More...

Priority_t *	Event_createPriority (Event_t *e)
	Creates a new, empty Priority_t structure, adds it to this Event_t, and returns the Priority_t. More...

Trigger_t *	Event_createTrigger (Event_t *e)
	Creates a new, empty Trigger_t structure, adds it to this Event_t, and returns the Trigger_t. More...

Event_t *	Event_createWithNS (SBMLNamespaces_t *sbmlns)
	Creates a new Event_t structure using the given SBMLNamespaces_t structure. More...

void	Event_free (Event_t *e)
	Frees the given Event_t structure. More...

Delay_t *	Event_getDelay (Event_t *e)
	Takes an Event_t structure and returns its Delay_t structure. More...

EventAssignment_t *	Event_getEventAssignment (Event_t *e, unsigned int n)
	Return a specific EventAssignment_t structure of the given Event_t. More...

EventAssignment_t *	Event_getEventAssignmentByVar (Event_t e, const char variable)
	Return the event assignment indicated by the given `variable`. More...

const char *	Event_getId (const Event_t *e)
	Takes an Event_t structure and returns its identifier. More...

ListOf_t *	Event_getListOfEventAssignments (Event_t *e)
	Get the list of EventAssignment_t structures from the given Event_t structure. More...

const char *	Event_getName (const Event_t *e)
	Takes an Event_t structure and returns its name. More...

const XMLNamespaces_t *	Event_getNamespaces (Event_t *e)
	Returns a list of XMLNamespaces_t associated with the given Event_t structure. More...

unsigned int	Event_getNumEventAssignments (const Event_t *e)
	Returns the number of EventAssignment_t structures attached to the given Event_t. More...

Priority_t *	Event_getPriority (Event_t *e)
	Takes an Event_t structure and returns its Priority_t structure. More...

const char *	Event_getTimeUnits (const Event_t *e)
	Takes an Event_t structure and returns the value of its "timeUnits" attribute. More...

Trigger_t *	Event_getTrigger (Event_t *e)
	Takes an Event_t structure and returns its Trigger_t structure. More...

int	Event_getUseValuesFromTriggerTime (const Event_t *e)
	Takes an Event_t structure and returns the value of its "useValuesFromTriggerTime" attribute. More...

int	Event_hasRequiredAttributes (Event_t *e)
	Predicate returning `1` (true) or `0` (false) depending on whether all the required attributes for the given Event_t structure have been set. More...

int	Event_hasRequiredElements (Event_t *e)
	Predicate returning `1` (true) or `0` (false) depending on whether all the required elements for the given Event_t structure have been set. More...

int	Event_isSetDelay (const Event_t *e)
	Predicate returning `1` (true) or `0` (false) depending on whether the given Event_t structure's delay is set. More...

int	Event_isSetId (const Event_t *e)
	Predicate returning `1` (true) or `0` (false) depending on whether the given Event_t structure's identifier is set. More...

int	Event_isSetName (const Event_t *e)
	Predicate returning `1` (true) or `0` (false) depending on whether the given Event_t structure's name is set. More...

int	Event_isSetPriority (const Event_t *e)
	Predicate returning `1` (true) or `0` (false) depending on whether the given Event_t structure's priority is set. More...

int	Event_isSetTimeUnits (const Event_t *e)
	Predicate returning `1` (true) or `0` (false) depending on whether the given Event_t structure's "timeUnits" attribute is set. More...

int	Event_isSetTrigger (const Event_t *e)
	Predicate returning `1` (true) or `0` (false) depending on whether the given Event_t structure's trigger is set. More...

int	Event_isSetUseValuesFromTriggerTime (const Event_t *e)
	Predicate returning `1` (true) or `0` (false) depending on whether the given Event_t structure's useValuesFromTriggerTime attribute is set. More...

EventAssignment_t *	Event_removeEventAssignment (Event_t *e, unsigned int n)
	Removes the nth EventAssignment_t structure from the given Event_t structure and returns a pointer to it. More...

EventAssignment_t *	Event_removeEventAssignmentByVar (Event_t e, const char variable)
	Removes the EventAssignment_t structure with the given "variable" attribute from the given Event_t structure and returns a pointer to it. More...

int	Event_setDelay (Event_t e, const Delay_t delay)
	Sets the delay of the given Event_t to a copy of the given Delay_t. More...

int	Event_setId (Event_t e, const char sid)
	Assigns the identifier of an Event_t structure. More...

int	Event_setName (Event_t e, const char name)
	Sets the name of the given Event_t to a copy of `name`. More...

int	Event_setPriority (Event_t e, const Priority_t priority)
	Sets the priority of the given Event_t to a copy of the given Priority_t. More...

int	Event_setTimeUnits (Event_t e, const char sid)
	Sets the "timeUnits" attribute of the given Event_t to a copy of `sid`. More...

int	Event_setTrigger (Event_t e, const Trigger_t trigger)
	Sets the trigger of the given Event_t to a copy of the given Trigger_t. More...

int	Event_setUseValuesFromTriggerTime (Event_t *e, int value)
	Sets the "useValuesFromTriggerTime" attribute of the given Event_t to a `value`. More...

int	Event_unsetDelay (Event_t *e)
	Unsets the delay of the given Event_t. More...

int	Event_unsetId (Event_t *e)
	Unsets the "id" attribute of the given Event_t structure. More...

int	Event_unsetName (Event_t *e)
	Unsets the "name" attribute of the given Event_t structure. More...

int	Event_unsetPriority (Event_t *e)
	Unsets the priority of the given Event_t. More...

int	Event_unsetTimeUnits (Event_t *e)
	Unsets the "timeUnits" attribute of the given Event_t. More...

int	Event_unsetUseValuesFromTriggerTime (Event_t *e)
	Unsets the "useValuesFromTriggerTime" attribute of the given Event_t structure. More...

Member Function Documentation

int Event_addEventAssignment	(	Event_t *	e,
		const EventAssignment_t *	ea
	)

Appends a copy of the given EventAssignment_t structure to the given Event_t structure.

Parameters

e	the Event_t structure to which the EventAssignment_t should be added.
ea	an EventAssignment_t structure to add.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Event_t * Event_clone ( const Event_t * e )

Returns a copy of the given Event_t structure.

Parameters

e	the Event_t structure to copy.

Returns: a (deep) copy of the Event_t.

Event_t * Event_create	(	unsigned int	level,
		unsigned int	version
	)

Creates a new Event_t structure using the given SBML level and version values.

Parameters

level	an unsigned int, the SBML Level to assign to this Event_t.
version	an unsigned int, the SBML Version to assign to this Event_t.

Returns: a pointer to the newly created Event_t structure.

Note: Attempting to add an object to an SBMLDocument_t 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_t), 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.

Delay_t * Event_createDelay ( Event_t * e )

Creates a new, empty Delay_t structure, adds it to this Event_t, and returns the Delay_t.

Parameters

e	the Event_t structure to which the delay should be added.

EventAssignment_t * Event_createEventAssignment ( Event_t * e )

Creates a new, empty EventAssignment_t structure, adds it to this Event_t's list of event assignments, and returns the EventAssignment_t.

Parameters

e	the Event_t structure to which the event assignment should be added.

Priority_t * Event_createPriority ( Event_t * e )

Creates a new, empty Priority_t structure, adds it to this Event_t, and returns the Priority_t.

Parameters

e	the Event_t structure to which the priority should be added.

Trigger_t * Event_createTrigger ( Event_t * e )

Creates a new, empty Trigger_t structure, adds it to this Event_t, and returns the Trigger_t.

Parameters

e	the Event_t structure to which the trigger should be added.

Event_t * Event_createWithNS ( SBMLNamespaces_t * sbmlns )

Creates a new Event_t structure using the given SBMLNamespaces_t structure.

Parameters

sbmlns SBMLNamespaces_t, a pointer to an SBMLNamespaces_t structure to assign to the given Event_t.

Returns: a pointer to the newly created Event_t structure.

Note: Attempting to add an object to an SBMLDocument_t 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_t), 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.

void Event_free ( Event_t * e )

Frees the given Event_t structure.

Parameters

e	the Event_t structure to free.

Delay_t * Event_getDelay ( Event_t * e )

Takes an Event_t structure and returns its Delay_t structure.

Parameters

e	the Event_t structure whose delay definition is sought.

Returns: the Delay_t of the given Event_t.

Examples:: printAnnotation.c, printMath.c, printNotes.c, and printUnits.c.

EventAssignment_t * Event_getEventAssignment	(	Event_t *	e,
		unsigned int	n
	)

Return a specific EventAssignment_t structure of the given Event_t.

Parameters

e	the Event_t structure to use.
n	an integer, the index of the EventAssignment_t structure to return.

Returns: the nth EventAssignment_t of the given Event_t, or NULL if no such EventAssignment_t exists.

Examples:: printAnnotation.c, printMath.c, printNotes.c, printUnits.c, unsetAnnotation.c, and unsetNotes.c.

EventAssignment_t * Event_getEventAssignmentByVar	(	Event_t *	e,
		const char *	variable
	)

Return the event assignment indicated by the given variable.

Parameters

e	the Event_t structure to use.
variable	a string, the identifier of the variable whose EventAssignment_t is being sought.

Returns: the EventAssignment_t for the given variable, or NULL if no such EventAssignment_t exists.

const char * Event_getId ( const Event_t * e )

Takes an Event_t structure and returns its identifier.

Parameters

e	the Event_t structure whose identifier is sought.

Returns: the identifier of the given Event_t, as a pointer to a string.

Examples:: printAnnotation.c, and printNotes.c.

ListOf_t * Event_getListOfEventAssignments ( Event_t * e )

Get the list of EventAssignment_t structures from the given Event_t structure.

Parameters

e	the Event_t structure to use.

Returns: the list of EventAssignments for the given Event_t.

const char * Event_getName ( const Event_t * e )

Takes an Event_t structure and returns its name.

Parameters

e	the Event_t whose name is sought.

Returns: the name of the given Event_t, as a pointer to a string.

const XMLNamespaces_t * Event_getNamespaces ( Event_t * e )

Returns a list of XMLNamespaces_t associated with the given Event_t structure.

Parameters

e	the Event_t structure.

Returns: pointer to the XMLNamespaces_t structure associated with this structure

unsigned int Event_getNumEventAssignments ( const Event_t * e )

Returns the number of EventAssignment_t structures attached to the given Event_t.

Parameters

e	the Event_t structure to use.

Returns: the number of EventAssignment_t structures in the given Event_t.

Examples:: printAnnotation.c, printMath.c, printNotes.c, printUnits.c, unsetAnnotation.c, and unsetNotes.c.

Priority_t * Event_getPriority ( Event_t * e )

Takes an Event_t structure and returns its Priority_t structure.

Parameters

e	the Event_t structure whose delay definition is sought.

Returns: the Priority_t of the given Event_t.

const char * Event_getTimeUnits ( const Event_t * e )

Takes an Event_t structure and returns the value of its "timeUnits" attribute.

Parameters

e	the Event_t structure whose "timeUnits" value is sought.

Returns: the timeUnits of the given Event_t

Warning: Definitions of Event_t in SBML Level 2 Versions 1 and 2 included the additional attribute called "timeUnits", but it was removed in SBML Level 2 Version 3. LibSBML supports this attribute for compatibility with previous versions of SBML Level 2, but its use is discouraged since models in Level 2 Versions 3 and 4 cannot contain it.

Trigger_t * Event_getTrigger ( Event_t * e )

Takes an Event_t structure and returns its Trigger_t structure.

Parameters

e	the Event_t structure whose trigger definition is sought.

Returns: the Trigger_t of the given Event_t.

Examples:: printAnnotation.c, printMath.c, and printNotes.c.

int Event_getUseValuesFromTriggerTime ( const Event_t * e )

Takes an Event_t structure and returns the value of its "useValuesFromTriggerTime" attribute.

Parameters

e	the Event_t structure whose "useValuesFromTriggerTime" value is sought.

Returns: the useValuesFromTriggerTime of the given Event_t

int Event_hasRequiredAttributes ( Event_t * e )

Predicate returning 1 (true) or 0 (false) depending on whether all the required attributes for the given Event_t structure have been set.

The required attributes for an Event_t structure are:

useValuesfromTriggerTime ( L3 onwards )

Returns: 1 (true) if the required attributes have been set, 0 (false) otherwise.

int Event_hasRequiredElements ( Event_t * e )

Predicate returning 1 (true) or 0 (false) depending on whether all the required elements for the given Event_t structure have been set.

Note

The required elements for an Event_t structure are:

"trigger" (required in SBML Level 2 and Level 3 Version 1; optional in SBML Level 3 Version 2+
"listOfEventAssignments" (required in SBML Level 2; optional in Level 3)

int Event_isSetDelay ( const Event_t * e )

Predicate returning 1 (true) or 0 (false) depending on whether the given Event_t structure's delay is set.

Parameters

e	the Event_t structure to query.

Returns: 1 (true) if a Delay_t structure is assigned to the given Event_t structure, 0 (false) otherwise.

Examples:: printAnnotation.c, printMath.c, printNotes.c, and printUnits.c.

int Event_isSetId ( const Event_t * e )

Predicate returning 1 (true) or 0 (false) depending on whether the given Event_t structure's identifier is set.

Parameters

e	the Event_t structure to query.

Returns: 1 (true) if the "id" attribute of the given Event_t structure is set, 0 (false) otherwise.

int Event_isSetName ( const Event_t * e )

Predicate returning 1 (true) or 0 (false) depending on whether the given Event_t structure's name is set.

Parameters

e	the Event_t structure to query.

Returns: 1 (true) if the "name" attribute of the given Event_t structure is set, 0 (false) otherwise.

int Event_isSetPriority ( const Event_t * e )

Predicate returning 1 (true) or 0 (false) depending on whether the given Event_t structure's priority is set.

Parameters

e	the Event_t structure to query.

Returns: 1 (true) if a Priority_t structure is assigned to the given Event_t structure, 0 (false) otherwise.

int Event_isSetTimeUnits ( const Event_t * e )

Predicate returning 1 (true) or 0 (false) depending on whether the given Event_t structure's "timeUnits" attribute is set.

Parameters

e	the Event_t structure to query.

Returns: 1 (true) if a value for the "timeUnits" attribute is assigned in the given Event_t structure, 0 (false) otherwise.

Warning: Definitions of Event_t in SBML Level 2 Versions 1 and 2 included the additional attribute called "timeUnits", but it was removed in SBML Level 2 Version 3. LibSBML supports this attribute for compatibility with previous versions of SBML Level 2, but its use is discouraged since models in Level 2 Versions 3 and 4 cannot contain it.

int Event_isSetTrigger ( const Event_t * e )

Predicate returning 1 (true) or 0 (false) depending on whether the given Event_t structure's trigger is set.

Parameters

e	the Event_t structure to query.

Returns: 1 (true) if a Trigger_t structure is assigned to the given Event_t structure, 0 (false) otherwise.

Examples:: printAnnotation.c, printMath.c, and printNotes.c.

int Event_isSetUseValuesFromTriggerTime ( const Event_t * e )

Predicate returning 1 (true) or 0 (false) depending on whether the given Event_t structure's useValuesFromTriggerTime attribute is set.

Parameters

e	the Event_t structure to query.

Returns: 1 (true) if the "useValuesFromTriggerTime" attribute of the given Event_t structure is set, 0 (false) otherwise.

EventAssignment_t * Event_removeEventAssignment	(	Event_t *	e,
		unsigned int	n
	)

Removes the nth EventAssignment_t structure from the given Event_t structure and returns a pointer to it.

The caller owns the returned structure and is responsible for deleting it.

Parameters

e	the Event_t structure.
n	the integer index of the EventAssignment_t sought.

Returns: the EventAssignment_t structure removed. As mentioned above, the caller owns the returned item. NULL is returned if the given index is out of range.

EventAssignment_t * Event_removeEventAssignmentByVar	(	Event_t *	e,
		const char *	variable
	)

Removes the EventAssignment_t structure with the given "variable" attribute from the given Event_t structure and returns a pointer to it.

The caller owns the returned structure and is responsible for deleting it.

Parameters

e	the Event_t structure.
variable	the string of the "variable" attribute of the EventAssignment_t sought.

Returns: the EventAssignment_t structure removed. As mentioned above, the caller owns the returned structure. NULL is returned if no EventAssignment_t structure with the "variable" attribute exists in the given Event_t structure.

int Event_setDelay	(	Event_t *	e,
		const Delay_t *	delay
	)

Sets the delay of the given Event_t to a copy of the given Delay_t.

Parameters

e	the Event_t structure to set.
delay	the Delay_t structure to use.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Event_setId	(	Event_t *	e,
		const char *	sid
	)

Assigns the identifier of an Event_t structure.

This makes a copy of the string passed in the parameter sid.

Parameters

e	the Event_t structure to set.
sid	the string to use as the identifier.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Using this function with an sid of NULL is equivalent to unsetting the "id" attribute.

int Event_setName	(	Event_t *	e,
		const char *	name
	)

Sets the name of the given Event_t to a copy of name.

Parameters

e	the Event_t structure to set.
name	the name to assign to the given Event_t's "name" attribute.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Using this function with the name set to NULL is equivalent to unsetting the "name" attribute.

int Event_setPriority	(	Event_t *	e,
		const Priority_t *	priority
	)

Sets the priority of the given Event_t to a copy of the given Priority_t.

Parameters

e	the Event_t structure to set.
priority	the Priority_t structure to use.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Event_setTimeUnits	(	Event_t *	e,
		const char *	sid
	)

Sets the "timeUnits" attribute of the given Event_t to a copy of sid.

Parameters

e	the Event_t structure to set.
sid	the identifier of the units to use as the value of the "timeUnits" attribute.

Warning: Definitions of Event_t in SBML Level 2 Versions 1 and 2 included the additional attribute called "timeUnits", but it was removed in SBML Level 2 Version 3. LibSBML supports this attribute for compatibility with previous versions of SBML Level 2, but its use is discouraged since models in Level 2 Versions 3 and 4 cannot contain it.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Using this function with an sid of NULL is equivalent to unsetting the "timeUnits" attribute.

int Event_setTrigger	(	Event_t *	e,
		const Trigger_t *	trigger
	)

Sets the trigger of the given Event_t to a copy of the given Trigger_t.

Parameters

e	the Event_t structure to set.
trigger	the Trigger_t structure to use.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Event_setUseValuesFromTriggerTime	(	Event_t *	e,
		int	value
	)

Sets the "useValuesFromTriggerTime" attribute of the given Event_t to a value.

Parameters

e	the Event_t structure to set.
value	the value of the "useValuesFromTriggerTime" attribute.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Event_unsetDelay ( Event_t * e )

Unsets the delay of the given Event_t.

Parameters

e	the Event_t structure to unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Event_unsetId ( Event_t * e )

Unsets the "id" attribute of the given Event_t structure.

Parameters

e	the Event_t structure to unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Event_unsetName ( Event_t * e )

Unsets the "name" attribute of the given Event_t structure.

Parameters

e	the Event_t structure to unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Event_unsetPriority ( Event_t * e )

Unsets the priority of the given Event_t.

Parameters

e	the Event_t structure to unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int Event_unsetTimeUnits ( Event_t * e )

Unsets the "timeUnits" attribute of the given Event_t.

Parameters

e	the Event_t structure to unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Warning: Definitions of Event_t in SBML Level 2 Versions 1 and 2 included the additional attribute called "timeUnits", but it was removed in SBML Level 2 Version 3. LibSBML supports this attribute for compatibility with previous versions of SBML Level 2, but its use is discouraged since models in Level 2 Versions 3 and 4 cannot contain it.

int Event_unsetUseValuesFromTriggerTime ( Event_t * e )

Unsets the "useValuesFromTriggerTime" attribute of the given Event_t structure.

Parameters

e	the Event_t structure to unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Detailed Description

SBML Level/Version differences

SBML Level 2

SBML Level 3

Semantics of events in SBML Level 3 Version 1

Restrictions relaxed in SBML Level 3 Version 2

Public Member Functions

Member Function Documentation