1 /*
2 * Licensed to the Apache Software Foundation (ASF) 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 ASF 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 * http://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.apache.commons.math4.legacy.ode;
19
20 import java.util.Collection;
21
22 import org.apache.commons.math4.legacy.analysis.solvers.UnivariateSolver;
23 import org.apache.commons.math4.legacy.ode.events.EventHandler;
24 import org.apache.commons.math4.legacy.ode.sampling.StepHandler;
25
26 /**
27 * This interface defines the common parts shared by integrators
28 * for first and second order differential equations.
29 * @see FirstOrderIntegrator
30 * @see SecondOrderIntegrator
31 * @since 2.0
32 */
33 public interface ODEIntegrator {
34
35 /** Get the name of the method.
36 * @return name of the method
37 */
38 String getName();
39
40 /** Add a step handler to this integrator.
41 * <p>The handler will be called by the integrator for each accepted
42 * step.</p>
43 * @param handler handler for the accepted steps
44 * @see #getStepHandlers()
45 * @see #clearStepHandlers()
46 * @since 2.0
47 */
48 void addStepHandler(StepHandler handler);
49
50 /** Get all the step handlers that have been added to the integrator.
51 * @return an unmodifiable collection of the added events handlers
52 * @see #addStepHandler(StepHandler)
53 * @see #clearStepHandlers()
54 * @since 2.0
55 */
56 Collection<StepHandler> getStepHandlers();
57
58 /** Remove all the step handlers that have been added to the integrator.
59 * @see #addStepHandler(StepHandler)
60 * @see #getStepHandlers()
61 * @since 2.0
62 */
63 void clearStepHandlers();
64
65 /** Add an event handler to the integrator.
66 * Uses a default {@link UnivariateSolver}
67 * with an absolute accuracy equal to the given convergence threshold,
68 * as root-finding algorithm to detect the state events.
69 * @param handler event handler
70 * @param maxCheckInterval maximal time interval between switching
71 * function checks (this interval prevents missing sign changes in
72 * case the integration steps becomes very large)
73 * @param convergence convergence threshold in the event time search
74 * @param maxIterationCount upper limit of the iteration count in
75 * the event time search
76 * @see #getEventHandlers()
77 * @see #clearEventHandlers()
78 */
79 void addEventHandler(EventHandler handler, double maxCheckInterval,
80 double convergence, int maxIterationCount);
81
82 /** Add an event handler to the integrator.
83 * @param handler event handler
84 * @param maxCheckInterval maximal time interval between switching
85 * function checks (this interval prevents missing sign changes in
86 * case the integration steps becomes very large)
87 * @param convergence convergence threshold in the event time search
88 * @param maxIterationCount upper limit of the iteration count in
89 * the event time search
90 * @param solver The root-finding algorithm to use to detect the state
91 * events.
92 * @see #getEventHandlers()
93 * @see #clearEventHandlers()
94 */
95 void addEventHandler(EventHandler handler, double maxCheckInterval,
96 double convergence, int maxIterationCount,
97 UnivariateSolver solver);
98
99 /** Get all the event handlers that have been added to the integrator.
100 * @return an unmodifiable collection of the added events handlers
101 * @see #addEventHandler(EventHandler, double, double, int)
102 * @see #clearEventHandlers()
103 */
104 Collection<EventHandler> getEventHandlers();
105
106 /** Remove all the event handlers that have been added to the integrator.
107 * @see #addEventHandler(EventHandler, double, double, int)
108 * @see #getEventHandlers()
109 */
110 void clearEventHandlers();
111
112 /** Get the current value of the step start time t<sub>i</sub>.
113 * <p>This method can be called during integration (typically by
114 * the object implementing the {@link FirstOrderDifferentialEquations
115 * differential equations} problem) if the value of the current step that
116 * is attempted is needed.</p>
117 * <p>The result is undefined if the method is called outside of
118 * calls to <code>integrate</code>.</p>
119 * @return current value of the step start time t<sub>i</sub>
120 */
121 double getCurrentStepStart();
122
123 /** Get the current signed value of the integration stepsize.
124 * <p>This method can be called during integration (typically by
125 * the object implementing the {@link FirstOrderDifferentialEquations
126 * differential equations} problem) if the signed value of the current stepsize
127 * that is tried is needed.</p>
128 * <p>The result is undefined if the method is called outside of
129 * calls to <code>integrate</code>.</p>
130 * @return current signed value of the stepsize
131 */
132 double getCurrentSignedStepsize();
133
134 /** Set the maximal number of differential equations function evaluations.
135 * <p>The purpose of this method is to avoid infinite loops which can occur
136 * for example when stringent error constraints are set or when lots of
137 * discrete events are triggered, thus leading to many rejected steps.</p>
138 * @param maxEvaluations maximal number of function evaluations (negative
139 * values are silently converted to maximal integer value, thus representing
140 * almost unlimited evaluations)
141 */
142 void setMaxEvaluations(int maxEvaluations);
143
144 /** Get the maximal number of functions evaluations.
145 * @return maximal number of functions evaluations
146 */
147 int getMaxEvaluations();
148
149 /** Get the number of evaluations of the differential equations function.
150 * <p>
151 * The number of evaluations corresponds to the last call to the
152 * <code>integrate</code> method. It is 0 if the method has not been called yet.
153 * </p>
154 * @return number of evaluations of the differential equations function
155 */
156 int getEvaluations();
157 }