TSSetEventHandler#

Sets functions and parameters used for indicating events and handling them

Synopsis#

#include "petscts.h" 
PetscErrorCode TSSetEventHandler(TS ts, PetscInt nevents, PetscInt direction[], PetscBool terminate[], PetscErrorCode (*indicator)(TS ts, PetscReal t, Vec U, PetscReal fvalue[], void *ctx), PetscErrorCode (*postevent)(TS ts, PetscInt nevents_zero, PetscInt events_zero[], PetscReal t, Vec U, PetscBool forwardsolve, void *ctx), void *ctx)

Logically Collective

Input Parameters#

ts - the TS context obtained from TSCreate()
nevents - number of local events (i.e. managed by the given MPI process)
direction - direction of zero crossing to be detected (one for each local event). -1 => zero crossing in negative direction, +1 => zero crossing in positive direction, 0 => both ways
terminate - flag to indicate whether time stepping should be terminated after an event is detected (one for each local event)
indicator - callback defininig the user indicator functions whose sign changes (see direction) mark presence of the events
postevent - [optional] user post-event callback; it can change the solution, ODE etc at the time of the event
ctx - [optional] user-defined context for private data for the indicator() and postevent() routines (use NULL if no context is desired)

Calling sequence of `indicator`#

ts - the TS context
t - current time
U - current solution
fvalue - output array with values of local indicator functions (length == nevents) for time t and state-vector U
ctx - the context passed as the final argument to TSSetEventHandler()

Calling sequence of `postevent`#

ts - the TS context
nevents_zero - number of triggered local events (whose indicator function is marked as crossing zero, and direction is appropriate)
events_zero - indices of the triggered local events
t - current time
U - current solution
forwardsolve - flag to indicate whether TS is doing a forward solve (PETSC_TRUE) or adjoint solve (PETSC_FALSE)
ctx - the context passed as the final argument to TSSetEventHandler()

Options Database Keys#

-ts_event_tol - tolerance for zero crossing check of indicator functions
-ts_event_monitor - print choices made by event handler
-ts_event_recorder_initial_size - initial size of event recorder
-ts_event_post_event_step - first time step after event
-ts_event_post_event_second_step - second time step after event
-ts_event_dt_min
- minimum time step considered for TSEvent

Notes#

The indicator functions should be defined in the indicator callback using the components of solution U and/or time t. Note that U is PetscScalar-valued, and the indicator functions are PetscReal-valued. It is the user’s responsibility to properly handle this difference, e.g. by applying PetscRealPart() or other appropriate conversion means.

The full set of events is distributed (by the user design) across MPI processes, with each process defining its own local sub-set of events. However, the postevent() callback invocation is performed synchronously on all processes, including those processes which have not currently triggered any events.

Level#

intermediate

Location#

src/ts/event/tsevent.c

Examples#

src/ts/tutorials/ex40.c
src/ts/tutorials/ex41.c
src/ts/tutorials/ex44.c
src/ts/tutorials/ex32.c

Index of all TS routines
Table of Contents for all manual pages
Index of all manual pages