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

Details and OptionsDetails 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.
Introduced in 2012
| Updated in 2014