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;
19  
20  import java.util.List;
21  
22  import org.hipparchus.exception.MathIllegalArgumentException;
23  import org.hipparchus.exception.MathIllegalStateException;
24  import org.hipparchus.ode.events.ODEEventDetector;
25  import org.hipparchus.ode.events.ODEStepEndHandler;
26  import org.hipparchus.ode.sampling.ODEStepHandler;
27  
28  /** This interface represents a first order integrator for
29   * differential equations.
30  
31   * <p>The classes which are devoted to solve first order differential
32   * equations should implement this interface. The problems which can
33   * be handled should implement the {@link
34   * OrdinaryDifferentialEquation} interface.</p>
35   *
36   * @see OrdinaryDifferentialEquation
37   * @see org.hipparchus.ode.sampling.ODEStepHandler
38   * @see org.hipparchus.ode.events.ODEEventHandler
39   */
40  public interface ODEIntegrator  {
41  
42      /** Get the name of the method.
43       * @return name of the method
44       */
45      String getName();
46  
47      /** Add a step handler to this integrator.
48       * <p>The handler will be called by the integrator for each accepted
49       * step.</p>
50       * @param handler handler for the accepted steps
51       * @see #getStepHandlers()
52       * @see #clearStepHandlers()
53       */
54      void addStepHandler(ODEStepHandler handler);
55  
56      /** Get all the step handlers that have been added to the integrator.
57       * @return an unmodifiable collection of the added events handlers
58       * @see #addStepHandler(ODEStepHandler)
59       * @see #clearStepHandlers()
60       */
61      List<ODEStepHandler> getStepHandlers();
62  
63      /** Remove all the step handlers that have been added to the integrator.
64       * @see #addStepHandler(ODEStepHandler)
65       * @see #getStepHandlers()
66       */
67      void clearStepHandlers();
68  
69      /** Add an event detector to the integrator.
70       * @param detector event detector
71       * @see #getEventDetectors()
72       * @see #clearEventDetectors()
73       * @since 3.0
74       */
75      void addEventDetector(ODEEventDetector detector);
76  
77      /** Get all the event detectors that have been added to the integrator.
78       * @return an unmodifiable list of the added events detectors
79       * @see #addEventDetector(ODEEventDetector)
80       * @see #clearEventDetectors()
81       * @since 3.0
82       */
83      List<ODEEventDetector> getEventDetectors();
84  
85      /** Remove all the event handlers that have been added to the integrator.
86       * @see #addEventDetector(ODEEventDetector)
87       * @see #getEventDetectors()
88       * @since 3.0
89       */
90      void clearEventDetectors();
91  
92      /** Add a handler for step ends to the integrator.
93       * <p>
94       * The {@link ODEStepEndHandler#stepEndOccurred(ODEStateAndDerivative, boolean)
95       * stepEndOccurred(state, forward)} method of the {@code handler} will be called
96       * at each step end.
97       * </p>
98       * @param handler handler for step ends
99       * @see #getStepEndHandlers()
100      * @see #clearStepEndHandlers()
101      * @since 3.0
102      */
103     void addStepEndHandler(ODEStepEndHandler handler);
104 
105     /** Get all the handlers for step ends that have been added to the integrator.
106      * @return an unmodifiable list of the added step end handlers
107      * @see #addStepEndHandler(ODEStepEndHandler)
108      * @see #clearStepEndHandlers()
109      * @since 3.0
110      */
111     List<ODEStepEndHandler> getStepEndHandlers();
112 
113     /** Remove all the handlers for step ends that have been added to the integrator.
114      * @see #addStepEndHandler(ODEStepEndHandler)
115      * @see #getStepEndHandlers()
116      * @since 3.0
117      */
118     void clearStepEndHandlers();
119 
120     /** Get the state at step start time t<sub>i</sub>.
121      * <p>This method can be called during integration (typically by
122      * the object implementing the {@link OrdinaryDifferentialEquation
123      * differential equations} problem) if the value of the current step that
124      * is attempted is needed.</p>
125      * <p>The result is undefined if the method is called outside of
126      * calls to <code>integrate</code>.</p>
127      * @return state at step start time t<sub>i</sub>
128      */
129     ODEStateAndDerivative getStepStart();
130 
131     /** Get the current signed value of the integration stepsize.
132      * <p>This method can be called during integration (typically by
133      * the object implementing the {@link OrdinaryDifferentialEquation
134      * differential equations} problem) if the signed value of the current stepsize
135      * that is tried is needed.</p>
136      * <p>The result is undefined if the method is called outside of
137      * calls to <code>integrate</code>.</p>
138      * @return current signed value of the stepsize
139      */
140     double getCurrentSignedStepsize();
141 
142     /** Set the maximal number of differential equations function evaluations.
143      * <p>The purpose of this method is to avoid infinite loops which can occur
144      * for example when stringent error constraints are set or when lots of
145      * discrete events are triggered, thus leading to many rejected steps.</p>
146      * @param maxEvaluations maximal number of function evaluations (negative
147      * values are silently converted to maximal integer value, thus representing
148      * almost unlimited evaluations)
149      */
150     void setMaxEvaluations(int maxEvaluations);
151 
152     /** Get the maximal number of functions evaluations.
153      * @return maximal number of functions evaluations
154      */
155     int getMaxEvaluations();
156 
157     /** Get the number of evaluations of the differential equations function.
158      * <p>
159      * The number of evaluations corresponds to the last call to the
160      * <code>integrate</code> method. It is 0 if the method has not been called yet.
161      * </p>
162      * @return number of evaluations of the differential equations function
163      */
164     int getEvaluations();
165 
166     /** Integrate the differential equations up to the given time.
167      * <p>This method solves an Initial Value Problem (IVP).</p>
168      * <p>Since this method stores some internal state variables made
169      * available in its public interface during integration ({@link
170      * #getCurrentSignedStepsize()}), it is <em>not</em> thread-safe.</p>
171      * @param equations differential equations to integrate
172      * @param initialState initial state (time, primary and secondary state vectors)
173      * @param finalTime target time for the integration
174      * (can be set to a value smaller than {@code t0} for backward integration)
175      * @return final state, its time will be the same as {@code finalTime} if
176      * integration reached its target, but may be different if some {@link
177      * org.hipparchus.ode.events.ODEEventHandler} stops it at some point.
178      * @exception MathIllegalArgumentException if integration step is too small
179      * @exception MathIllegalStateException if the number of functions evaluations is exceeded
180      * @exception MathIllegalArgumentException if the location of an event cannot be bracketed
181      */
182     ODEStateAndDerivative integrate(ExpandableODE equations,
183                                     ODEState initialState, double finalTime)
184         throws MathIllegalArgumentException, MathIllegalStateException;
185 
186     /** Integrate the differential equations up to the given time.
187      * <p>This method solves an Initial Value Problem (IVP).</p>
188      * <p>Since this method stores some internal state variables made
189      * available in its public interface during integration ({@link
190      * #getCurrentSignedStepsize()}), it is <em>not</em> thread-safe.</p>
191      * @param equations differential equations to integrate
192      * @param initialState initial state (time, primary and secondary state vectors)
193      * @param finalTime target time for the integration
194      * (can be set to a value smaller than {@code t0} for backward integration)
195      * @return final state, its time will be the same as {@code finalTime} if
196      * integration reached its target, but may be different if some {@link
197      * org.hipparchus.ode.events.ODEEventHandler} stops it at some point.
198      * @exception MathIllegalArgumentException if integration step is too small
199      * @exception MathIllegalStateException if the number of functions evaluations is exceeded
200      * @exception MathIllegalArgumentException if the location of an event cannot be bracketed
201      */
202     default ODEStateAndDerivative integrate(OrdinaryDifferentialEquation equations,
203                                             ODEState initialState, double finalTime)
204         throws MathIllegalArgumentException, MathIllegalStateException {
205         return integrate(new ExpandableODE(equations), initialState, finalTime);
206     }
207 
208 }