TSSetPostEventStep — PETSc 3.22.5 documentation

Skip to main content
`Ctrl`+`K`

# TSSetPostEventStep

Set the first time step to use after the event

## Synopsis

    #include "petscts.h"
    PetscErrorCode TSSetPostEventStep(TS ts, PetscReal dt1)

Logically Collective

## Input Parameters

- ts - time integration context

- dt1 - first post event step

## Options Database Key

- -ts_event_post_event_step - first time step after the event

## Notes

`TSSetPostEventStep()` allows one to set a time step to use immediately following an event. Note, if `TSAdapt` is allowed to interfere and reject steps, a large ‘dt1’ set by `TSSetPostEventStep()` may get truncated, resulting in a smaller actual post-event step. See also the warning below regarding the `TSAdapt`.

The post-event time steps should be selected based on the post-event dynamics. If the dynamics are stiff, or a significant jump in the equations or the state vector has taken place at the event, conservative (small) steps should be employed. If not, then larger time steps may be appropriate.

This function accepts either a numerical value for `dt1`, or `PETSC_DECIDE`. The special value `PETSC_DECIDE` signals the event handler to follow the originally planned trajectory, and is assumed by default.

To describe the way `PETSC_DECIDE` affects the post-event steps, consider a trajectory of time points t1 -> t2 -> t3 -> t4. Suppose the TS has reached and calculated the solution at point t3, and has planned the next move: t3 -> t4. At this moment, an event between t2 and t3 is detected, and after a few iterations it is resolved at point `te`, t2 < te < t3. After event `te`, two post-event steps can be specified: the first one dt1 (`TSSetPostEventStep()`), and the second one dt2 (`TSSetPostEventSecondStep()`). Both post-event steps can be either `PETSC_DECIDE`, or a number. Four different combinations are possible:

1. dt1 = `PETSC_DECIDE`, dt2 = `PETSC_DECIDE`. Then, after `te` TS goes to t3, and then to t4. This is the all-default behaviour.

2. dt1 = `PETSC_DECIDE`, dt2 = x2 (numerical). Then, after `te` TS goes to t3, and then to t3+x2.

3. dt1 = x1 (numerical), dt2 = x2 (numerical). Then, after `te` TS goes to te+x1, and then to te+x1+x2.

4. dt1 = x1 (numerical), dt2 = `PETSC_DECIDE`. Then, after `te` TS goes to te+x1, and event handler does not interfere to the subsequent steps.

In the special case when `te` == t3 with a good precision, the post-event step te -> t3 is not performed, so behaviour of (1) and (2) becomes:

1a. After `te` TS goes to t4, and event handler does not interfere to the subsequent steps.

2a. After `te` TS goes to t4, and then to t4+x2.

Warning! When the second post-event step (either PETSC_DECIDE or a numerical value) is managed by the event handler, i.e. in cases 1, 2, 3 and 2a, `TSAdapt` will never analyse (and never do a reasonable rejection of) the first post-event step. The first post-event step will always be accepted. In this situation, it is the user’s responsibility to make sure the step size is appropriate! In cases 4 and 1a, however, `TSAdapt` will analyse the first post-event step, and is allowed to reject it.

This function can be called not only in the initial setup, but also inside the `postevent()` callback set with `TSSetEventHandler()`, affecting the post-event steps for the current event, and the subsequent ones. Thus, the strategy of the post-event time step definition can be adjusted on the fly. In case several events are triggered in the given time point, only a single postevent handler is invoked, and the user is to determine what post-event time step is more appropriate in this situation.

The default value is `PETSC_DECIDE`.

## Developer Notes

Event processing starts after visiting point t3, which means ts->adapt->dt_span_cached has been set to whatever value is required when planning the step t3 -> t4.

## See Also

TS: Scalable ODE and DAE Solvers, `TS`, `TSEvent`, `TSSetEventHandler()`, `TSSetPostEventSecondStep()`

## Level

advanced

## Location

src/ts/event/tsevent.c

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