Package org.hipparchus.ode.events
Events
This package provides classes to handle discrete events occurring during Ordinary Differential Equations integration.
Discrete events detection is based on switching functions. The user provides
a simple g(state)
function depending on the current time and state in a detector object and a
handler function
in a handler object. The integrator will monitor
the value of the function throughout integration range and will trigger the
event when its sign changes. The magnitude of the value is almost irrelevant,
it should however be continuous (but not necessarily smooth) for the sake of
root finding.
Events detection is based on two embedded search algorithms. A top level loop, driven by the maxCheck interval, samples the g function during integration steps to identify sign changes and therefore bracket roots. When a sign change has been detected between two successive samples, then a lower level root finding algorithm is triggered to precisely locate the root, using the provided threshold as a convergence criterion. The maxCheck interval should be large enough to avoid sampling too finely the integration step and evaluating the g function too often, but it should be small enough to still separate successive roots, otherwise some events may be missed. See below for a formal definition of the maxCheck behavior. The threshold on the other hand should generally be very small, it really corresponds to the accuracy at which events must be located.
When an event is triggered, several different options are available:
 integration can be stopped (this is called a Gstop facility),
 the state vector or the derivatives can be changed,
 or integration can simply go on.
The first case, Gstop, is the most common one. A typical use case is when an ODE must be solved up to some target state is reached, with a known value of the state but an unknown occurrence time. As an example, if we want to monitor a chemical reaction up to some predefined concentration for the first substance, we can use the following switching function setting in the detector:
public double g(final ODEStateAndDerivative state) { return state.getState()[0]  targetConcentration; }
and the following setting in the event handler:
public Action eventOccurred(final ODEStateAndDerivative state, final ODEEventDetector detector, final boolean increasing) { return STOP; }
The second case, change state vector or derivatives is encountered when dealing with discontinuous dynamical models. A typical case would be the motion of a spacecraft when thrusters are fired for orbital maneuvers. The acceleration is smooth as long as no maneuver are performed, depending only on gravity, drag, third body attraction, radiation pressure. Firing a thruster introduces a discontinuity that must be handled appropriately by the integrator. In such a case, we would use a switching function setting similar to this:
public double g(final ODEStateAndDerivative state) { return (state.getTime()  tManeuverStart) ∗ (state.getTime()  tManeuverStop); }
and the following setting in the event handler:
public Action eventOccurred(final ODEStateAndDerivative state, final ODEEventDetector detector, final boolean increasing) { return RESET_DERIVATIVES; }
The third case is useful mainly for monitoring purposes, a simple example is:
public double g(final ODEStateAndDerivative state) { final double[] y = state.getState(); return y[0]  y[1]; }
and the following setting in the event handler:
public Action eventOccurred(final ODEStateAndDerivative state, final ODEEventDetector detector, final boolean increasing) { logger.log("y0(t) and y1(t) curves cross at t = " + t); return CONTINUE; }
Rules of Event Handling
These rules formalize the concept of event detection and are used to determine when
an event must be reported to the user and the order in which events must occur. These
rules assume the event handler and g function conform to the documentation on
ODEEventHandler
and
ODEIntegrator
.
 An event must be detected if the g function has changed signs for longer than maxCheck(t, y(t)). Formally, given times t, t_e1, t_e2 such that t < t_e1 < t_e2, g(t_e1) = 0, g(t_e2) = 0, and g(t_i) != 0 on the intervals {[t, t_e1>, <t_e1, t_e2>} (i.e. t_e1, t_e2 are the next two event times after t) then t_e1 will be detected if maxCheck(t, y(t)) < t_e2. (I.e. the max check interval must be less than the time until the second event.)
 MaxCheck(t, y(t)) is evaluated at step start and called again at the end of the previous maxCheck; this implies that if maxCheck depends a lot on state, care must be taken to return conservative values, i.e. it is better to return small maxCheck and hence perform a lot of checks than missing an event because maxCheck was too large.
 MaxCheck should always return positive values, even if integration is backward
 For a given tolerance, h, and root, r, the event may occur at any point on the
interval [rh, r+h]. The tolerance is the larger of the
convergence
parameter and the convergence settings of the root finder specified whenadding
the event detector.  At most one event is triggered per root.
 Events from the same event detector must alternate between increasing and decreasing events. That is, for every pair of increasing events there must exist an intervening decreasing event and viceversa.
 An event starts occurring when the
eventOccured()
method is called. An event stops occurring when eventOccurred() returns or when the handler'sresetState()
method returns if eventOccured() returnedRESET_STATE
.  If event A happens before event B then the effects of A occurring are visible to B. (Including resetting the state or derivatives, or stopping)
 Events occur in chronological order. If integration is forward and event A happens before event B then the time of event B is greater than or equal to the time of event A.
 There is a total order on events. That is for two events A and B either A happens before B or B happens before A.

ClassDescriptionBase class for #@link
FieldODEEventDetector
.AbstractODEDetector<T extends AbstractODEDetector<T>>Base class for #@linkODEEventDetector
.Enumerate for actions to be performed when an event occurs during ODE integration.This interface represents an event checking interval that depends on state.This class handles the state for oneevent handler
during integration steps.Class to hold the data related to an event occurrence that is needed to decide how to modify integration.EventSlopeFilter<T extends ODEEventDetector>Wrapper used to detect only increasing or decreasing events.This interface handles the state for either oneevent handler
or onestep end handler
during integration steps.FieldAdaptableInterval<T extends CalculusFieldElement<T>>This interface represents an event checking interval that depends on state.FieldDetectorBasedEventState<T extends CalculusFieldElement<T>>This class handles the state for oneevent handler
during integration steps.FieldEventOccurrence<T extends CalculusFieldElement<T>>Class to hold the data related to an event occurrence that is needed to decide how to modify integration.Wrapper used to detect only increasing or decreasing events.FieldEventState<T extends CalculusFieldElement<T>>This interface handles the state for either oneevent handler
or onestep end handler
during integration steps.FieldODEEventDetector<T extends CalculusFieldElement<T>>This interface represents a handler for discrete events triggered during ODE integration.FieldODEEventHandler<T extends CalculusFieldElement<T>>This interface represents a handler for discrete events triggered during ODE integration.FieldODEStepEndHandler<T extends CalculusFieldElement<T>>This interface represents a handler for discrete events triggered during ODE integration at each step end.FieldStepEndEventState<T extends CalculusFieldElement<T>>This class handles the state for oneevent handler
that triggers at step end.Enumerate forfiltering events
.This interface represents a detector for discrete events triggered during ODE integration.This interface represents a handler for discrete events triggered during ODE integration.This interface represents a handler for discrete events triggered during ODE integration at each step end.This class handles the state for oneevent handler
that triggers at step end.