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:

dt1 = PETSC_DECIDE, dt2 = PETSC_DECIDE. Then, after te TS goes to t3, and then to t4. This is the all-default behaviour.
dt1 = PETSC_DECIDE, dt2 = x2 (numerical). Then, after te TS goes to t3, and then to t3+x2.
dt1 = x1 (numerical), dt2 = x2 (numerical). Then, after te TS goes to te+x1, and then to te+x1+x2.
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.

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