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 }