org.apache.commons.math3.ode.events

## Class EventState

- java.lang.Object
- - org.apache.commons.math3.ode.events.EventState

-     public class EventState
      extends java.lang.Object

  This class handles the state for one `event handler` during integration steps.

  Each time the integrator proposes a step, the event handler switching function should be checked. This class handles the state of one handler during one integration step, with references to the state at the end of the preceding step. This information is used to decide if the handler should trigger an event or not during the proposed step.

  Since:
    1.2
  Version:
    $Id: EventState.java 1416643 2012-12-03 19:37:14Z tn $

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `private static class` | `EventState.LocalMaxCountExceededException` Local wrapper to propagate exceptions.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private double` | `convergence` Convergence threshold for event localization.
    `private boolean` | `forward` Integration direction.
    `private double` | `g0` Value of the events handler at the beginning of the step.
    `private boolean` | `g0Positive` Simulated sign of g0 (we cheat when crossing events).
    `private EventHandler` | `handler` Event handler.
    `private boolean` | `increasing` Variation direction around pending event.
    `private double` | `maxCheckInterval` Maximal time interval between events handler checks.
    `private int` | `maxIterationCount` Upper limit in the iteration count for event localization.
    `private EventHandler.Action` | `nextAction` Next action indicator.
    `private boolean` | `pendingEvent` Indicator of event expected during the step.
    `private double` | `pendingEventTime` Occurrence time of the pending event.
    `private double` | `previousEventTime` Occurrence time of the previous event.
    `private UnivariateSolver` | `solver` Root-finding algorithm to use to detect state events.
    `private double` | `t0` Time at the beginning of the step.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `EventState(EventHandler handler, double maxCheckInterval, double convergence, int maxIterationCount, UnivariateSolver solver)` Simple constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `evaluateStep(StepInterpolator interpolator)` Evaluate the impact of the proposed step on the event handler.
    `double` | `getConvergence()` Get the convergence threshold for event localization.
    `EventHandler` | `getEventHandler()` Get the underlying event handler.
    `double` | `getEventTime()` Get the occurrence time of the event triggered in the current step.
    `double` | `getMaxCheckInterval()` Get the maximal time interval between events handler checks.
    `int` | `getMaxIterationCount()` Get the upper limit in the iteration count for event localization.
    `void` | `reinitializeBegin(StepInterpolator interpolator)` Reinitialize the beginning of the step.
    `boolean` | `reset(double t, double[] y)` Let the event handler reset the state if it wants.
    `void` | `stepAccepted(double t, double[] y)` Acknowledge the fact the step has been accepted by the integrator.
    `boolean` | `stop()` Check if the integration should be stopped at the end of the current step.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### handler

          private final EventHandler handler

      Event handler.

    - #### maxCheckInterval

          private final double maxCheckInterval

      Maximal time interval between events handler checks.

    - #### convergence

          private final double convergence

      Convergence threshold for event localization.

    - #### maxIterationCount

          private final int maxIterationCount

      Upper limit in the iteration count for event localization.

    - #### t0

          private double t0

      Time at the beginning of the step.

    - #### g0

          private double g0

      Value of the events handler at the beginning of the step.

    - #### g0Positive

          private boolean g0Positive

      Simulated sign of g0 (we cheat when crossing events).

    - #### pendingEvent

          private boolean pendingEvent

      Indicator of event expected during the step.

    - #### pendingEventTime

          private double pendingEventTime

      Occurrence time of the pending event.

    - #### previousEventTime

          private double previousEventTime

      Occurrence time of the previous event.

    - #### forward

          private boolean forward

      Integration direction.

    - #### increasing

          private boolean increasing

      Variation direction around pending event. (this is considered with respect to the integration direction)

    - #### nextAction

          private EventHandler.Action nextAction

      Next action indicator.

    - #### solver

          private final UnivariateSolver solver

      Root-finding algorithm to use to detect state events.

  - ### Constructor Detail

    - #### EventState

          public EventState(EventHandler handler,
                    double maxCheckInterval,
                    double convergence,
                    int maxIterationCount,
                    UnivariateSolver solver)

      Simple constructor.
      Parameters:
        `handler` - event handler
        `maxCheckInterval` - maximal time interval between switching function checks (this interval prevents missing sign changes in case the integration steps becomes very large)
        `convergence` - convergence threshold in the event time search
        `maxIterationCount` - upper limit of the iteration count in the event time search
        `solver` - Root-finding algorithm to use to detect state events

  - ### Method Detail

    - #### getEventHandler

          public EventHandler getEventHandler()

      Get the underlying event handler.
      Returns:
        underlying event handler

    - #### getMaxCheckInterval

          public double getMaxCheckInterval()

      Get the maximal time interval between events handler checks.
      Returns:
        maximal time interval between events handler checks

    - #### getConvergence

          public double getConvergence()

      Get the convergence threshold for event localization.
      Returns:
        convergence threshold for event localization

    - #### getMaxIterationCount

          public int getMaxIterationCount()

      Get the upper limit in the iteration count for event localization.
      Returns:
        upper limit in the iteration count for event localization

    - #### reinitializeBegin

          public void reinitializeBegin(StepInterpolator interpolator)
                                 throws MaxCountExceededException

      Reinitialize the beginning of the step.
      Parameters:
        `interpolator` - valid for the current step
      Throws:
        `EventState.LocalMaxCountExceededException` - if the interpolator throws one because the number of functions evaluations is exceeded
        `MaxCountExceededException`

    - #### evaluateStep

          public boolean evaluateStep(StepInterpolator interpolator)
                               throws MaxCountExceededException,
                                      NoBracketingException

      Evaluate the impact of the proposed step on the event handler.
      Parameters:
        `interpolator` - step interpolator for the proposed step
      Returns:
        true if the event handler triggers an event before the end of the proposed step
      Throws:
        `EventState.LocalMaxCountExceededException` - if the interpolator throws one because the number of functions evaluations is exceeded
        `NoBracketingException` - if the event cannot be bracketed
        `MaxCountExceededException`

    - #### getEventTime

          public double getEventTime()

      Get the occurrence time of the event triggered in the current step.
      Returns:
        occurrence time of the event triggered in the current step or infinity if no events are triggered

    - #### stepAccepted

          public void stepAccepted(double t,
                          double[] y)

      Acknowledge the fact the step has been accepted by the integrator.
      Parameters:
        `t` - value of the independent time variable at the end of the step
        `y` - array containing the current value of the state vector at the end of the step

    - #### stop

          public boolean stop()

      Check if the integration should be stopped at the end of the current step.
      Returns:
        true if the integration should be stopped

    - #### reset

          public boolean reset(double t,
                      double[] y)

      Let the event handler reset the state if it wants.
      Parameters:
        `t` - value of the independent time variable at the beginning of the next step
        `y` - array were to put the desired state vector at the beginning of the next step
      Returns:
        true if the integrator should reset the derivatives too

Copyright (c) 2003-2013 Apache Software Foundation