1. Terminal and non-terminal events
2. Arbitrary precision
3. Activation of events
4. High- and low-level events
5. Directional detection
6. Simultaneous events
7. Defining events
   1. Event parameters
8. Events and generators
9. Further information

---

1. Terminal and non-terminal events

Discrete events provide the basis for stopping integration of an ODE or the computation of a difference equation, or for simply marking times at which a defined zero-crossing condition is met (without stopping generation of the trajectory). The first kind of events are known as terminal, the latter are known as non-terminal.

Terminal events form the basis of transitions in hybrid dynamical systems (see HybridSystems).

2. Arbitrary precision

For continuous dynamical systems, events can be resolved to arbitrary precision (precise events) or only to the precision of the trajectory generator's current step-size (non-precise events). For discrete DSs the step-size inherently corresponds to the maximal event precision.

The VODE integrator uses refined integration steps to find an event precisely, whereas Dopri and Radau use interpolation to the same order as the integration method itself.

Note that the precision of event detection can only be provided in terms of a tolerance for the independent variable associated with the event (e.g., time). Event precision cannot be specified in terms of a tolerance on the magnitude of the value of the zero-crossing function associated with the event.

3. Activation of events

Events that have been defined for a dynamical system can be made active or inactive, which controls whether or not those events are detected during generation of a trajectory.

4. High- and low-level events

The Event class defined in Events.py is split into two sub-classes: high level events HighLevelEvent (specified only using Python code), and low level events LowLevelEvent (specified using non-Python code, for either C or Matlab language targets).

5. Directional detection

Events can be defined to trigger only when the event boundary is crossed in one direction or another, or in both directions. This is specified by an integer, taking values -1 (decreasing), 0 (either), and 1 (increasing).

6. Simultaneous events

For continuously-defined dynamical systems it is not generic for multiple simultaneous events to occur. PyDSTool will resolve the correct order of multiple events that are flagged over a single time step, and depending on the generator will either flag an error if two events perfectly coincide or will choose an arbitrary order for them at consecutive time steps.

7. Defining events

The recommended manner to create events for all compatible generators is the function makeZeroCrossEvent, exported from Events.py. This function takes as arguments a general string expression, a direction, a dictionary of algorithmic arguments, followed by 'declarations' of any names used in the string expression, including variables, parameters, and inputs. Auxiliary functions can be called in the string definition, but auxiliary variables may not be accessed. For instance,

ev_args_nonterm = {'name': 'monitor',
           'eventtol': 1e-4,
           'eventdelay': 1e-5,
           'starttime': 0,
           'active': True,
           'term': False,
           'precise': True}

thresh_ev_nonterm = Events.makeZeroCrossEvent('in', 0,
                        ev_args_nonterm, inputnames=['in'])

defines a non-terminal python event (default target language is Python) that monitors an external input signal in for zero crossings in either direction.

An older alternative, for Python-based generators, is makePythonStateZeroCrossEvent, which is also only able to make events for state variable threshold crossings. The sole advantage of this function is its simpler syntax, but we may phase this function out in future releases.

7.1. Event parameters

Parameters not already described:

• eventtol: tolerance for event locater (in state variable)

• starttime: effective time zero for searches (used internally with eventdelay -- usually keep at zero)

• eventdelay: time interval before event detection begins on each run

• eventinterval: time interval between event detections restart

• bisectlimit: number of bisection steps to take when finding events

8. Events and generators

Once defined, events are passed to the initialization call to a generator in order to be incorporated into the generator. Events are contained in the eventstruct attribute of a generator. This attribute is an instance of the EventStruct class. This structure is used to maintain and query the events associated with the generator. With it, events can be added to or deleted from the structure. However, once a generator is created, only one that uses python as its target language will reflect such changes in its behaviour. C-based generators have their events committed at compile-time.

9. Further information

Further information is currently available only by inspecting the documented code in Events.py, and by running that module as a script to see the implementation of basic examples.