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