specifies an action that occurs when the event triggers it for equations in NDSolve and related functions.

Details and Options

  • In NDSolve[eqns,] the WhenEvent expressions are included in eqns and can be considered a part of the specification for the solution, especially for piecewise or hybrid systems.
  • WhenEvent expressions can be used in NDSolve, NDSolveValue, ParametricNDSolve, ParametricNDSolveValue, DSolve, and DSolveValue.
  • At a time when the event becomes True, the action is evaluated with the numerical solution values at . Examples of events and how is determined include:
  • predthe predicate pred becomes True
    f0the function f of the solution variables crosses zero
    f>0f crosses zero from below
    f<0f crosses zero from above
    f0&&predf crosses zero and pred is True
    Mod[t,Deltat]0sample at regular intervals in the time variable
  • WhenEvent typically finds a function f of the solution variables such that the roots of f occur where the event becomes True, and a bracketing interval within the accuracy and precision tolerances of the numerical computation is found using a numerical root-finding procedure.
  • In the case that a root function cannot be determined, the bracketing interval is found using bisection.
  • WhenEvent[{event1,},action] is treated as {WhenEvent[event1,action],}.
  • With WhenEvent[event,{action1,action2,}], the actions are evaluated sequentially.
  • The value from the evaluation of action is ignored by WhenEvent unless it has a special value that is used to affect NDSolve. The following special values are recognized:
  • "StopIntegration"stop integrating at , return the solution
    "RestartIntegration"restart the integration at
    "CrossDiscontinuity"integrate to , extrapolate, and restart at
    "CrossSlidingDiscontinuity"integrate to , extrapolate and check sliding mode conditions, and restart at
    "RemoveEvent"remove the event
    y[t]->valchange the state variable y to val
    d[t]->"DiscontinuitySignature"change the discontinuity signature variable d
  • With WhenEvent[f==0,d->"DiscontinuitySignature"], the discontinuity is the surface f==0, and d must be a discrete variable that takes on values {-1, 0, 1} or {-1, 1} and is effectively set to Sign[f] for subsequent to the event.
  • WhenEvent has attribute HoldAll, so by default the event and action are only evaluated with variables assigned approximated values.
  • WhenEvent can take the following options:
  • "DetectionMethod"Automaticthe method to use for detecting an event
    "LocationMethod"Automaticthe method to use for locating an event within a time step
    "IntegrateEvent"Automaticwhether to integrate the event function
    "Priority"Automaticpriority for actions of simultaneous events
  • Possible settings for "DetectionMethod" are:
  • Automaticautomatically determine detection method
    "Sign"use a sign change
    "DerivativeSign"use sign change and time derivative
    "Interpolation"use interpolation of dense solution output
  • The "Sign" detection method has the least overhead, but may miss events in rapidly varying functions. The "Interpolation" detection method is more robust and may detect multiple events per step.
  • Possible settings for "LocationMethod" are:
  • Automaticautomatically determine location method
    "StepBegin"locate the event at the beginning of a step
    "StepEnd"locate the event at the end of a step
    "LinearInterpolation"linearly interpolate within a step
    "Brent"use Brent's root location within a step
  • Possible settings for "IntegrateEvent" are:
  • Automaticautomatically determined
    Falsedo not integrate the event function
    Trueintegrate the event function
  • The settings for "Priority" can be any integer or Infinity. In the case of simultaneous events, the actions will be evaluated in sorted priority order.


open all close all

Basic Examples  (1)

Simulate a bouncing ball that retains 95% of its velocity in each bounce:

Click for copyable input
Click for copyable input

Scope  (16)

Generalizations & Extensions  (2)

Options  (11)

Applications  (20)

Properties & Relations  (2)

Possible Issues  (5)

Interactive Examples  (2)

Introduced in 2012
Updated in 2014