View Javadoc
1   /*
2    * Licensed to the Hipparchus project under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The Hipparchus project licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      https://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.hipparchus.ode.events;
19  
20  import org.hipparchus.exception.MathIllegalArgumentException;
21  import org.hipparchus.exception.MathIllegalStateException;
22  import org.hipparchus.ode.ODEStateAndDerivative;
23  import org.hipparchus.ode.sampling.ODEStateInterpolator;
24  
25  /** This interface handles the state for either one {@link ODEEventHandler
26   * event handler} or one {@link ODEStepEndHandler step end handler}
27   * during integration steps.
28   * @since 3.0
29   */
30  public interface EventState {
31  
32      /** Initialize handler at the start of an integration.
33       * <p>
34       * This method is called once at the start of the integration. It
35       * may be used by the handler to initialize some internal data
36       * if needed.
37       * </p>
38       * @param s0 initial state
39       * @param t target time for the integration
40       *
41       */
42      void init(ODEStateAndDerivative s0, double t);
43  
44      /**
45       * Get the occurrence time of the event triggered in the current step.
46       *
47       * @return occurrence time of the event triggered in the current step or infinity if
48       * no events are triggered
49       */
50      double getEventTime();
51  
52      /**
53       * Evaluate the impact of the proposed step on the handler.
54       *
55       * @param interpolator step interpolator for the proposed step
56       * @return true if the event handler triggers an event before the end of the proposed
57       * step
58       * @throws MathIllegalStateException    if the interpolator throws one because the
59       *                                      number of functions evaluations is exceeded
60       * @throws MathIllegalArgumentException if the event cannot be bracketed
61       */
62      boolean evaluateStep(ODEStateInterpolator interpolator)
63              throws MathIllegalArgumentException, MathIllegalStateException;
64  
65      /**
66       * Notify the user's listener of the event. The event occurs wholly within this method
67       * call including a call to {@link ODEEventHandler#resetState(ODEEventDetector,
68       * ODEStateAndDerivative)} if necessary.
69       *
70       * @param state the state at the time of the event. This must be at the same time as
71       *              the current value of {@link #getEventTime()}.
72       * @return the user's requested action and the new state if the action is {@link
73       * Action#RESET_STATE}. Otherwise the new state is {@code state}. The stop time
74       * indicates what time propagation should stop if the action is {@link Action#STOP}.
75       * This guarantees the integration will stop on or after the root, so that integration
76       * may be restarted safely.
77       */
78      EventOccurrence doEvent(ODEStateAndDerivative state);
79  
80  }