Skip to main content
`Ctrl`+`K`

# 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[], PetscCtx ctx), PetscErrorCode (*postevent)(TS ts, PetscInt nevents_zero, PetscInt events_zero[], PetscReal t, Vec U, PetscBool forwardsolve, PetscCtx ctx), PetscCtx 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 tol - tolerance for zero crossing check of indicator functions

- -ts_event_monitor - print choices made by event handler

- -ts_event_recorder_initial_size recsize - initial size of event recorder

- -ts_event_post_event_step dt1 - first time step after event

- -ts_event_post_event_second_step dt2 - second time step after event

- -ts_event_dt_min dt - 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.

## See Also

TS: Scalable ODE and DAE Solvers, Handling of discontinuities, `TSEvent`, `TSCreate()`, `TSSetTimeStep()`, `TSSetConvergedReason()`

## Level

intermediate

## Location

src/ts/event/tsevent.c

## Examples

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

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