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
18package org.apache.commons.math.ode;
19
20import java.util.Collection;
21
22import org.apache.commons.math.ode.events.EventHandler;
23import org.apache.commons.math.ode.sampling.StepHandler;
24
25/**
26 * This interface defines the common parts shared by integrators
27 * for first and second order differential equations.
28 * @see FirstOrderIntegrator
29 * @see SecondOrderIntegrator
30 * @version $Revision: 1061507 $ $Date: 2011-01-20 21:55:00 +0100 (jeu. 20 janv. 2011) $
31 * @since 2.0
32 */
33public 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     * @param handler event handler
67     * @param maxCheckInterval maximal time interval between switching
68     * function checks (this interval prevents missing sign changes in
69     * case the integration steps becomes very large)
70     * @param convergence convergence threshold in the event time search
71     * @param maxIterationCount upper limit of the iteration count in
72     * the event time search
73     * @see #getEventHandlers()
74     * @see #clearEventHandlers()
75     */
76    void addEventHandler(EventHandler handler, double maxCheckInterval,
77                         double convergence, int maxIterationCount);
78
79    /** Get all the event handlers that have been added to the integrator.
80     * @return an unmodifiable collection of the added events handlers
81     * @see #addEventHandler(EventHandler, double, double, int)
82     * @see #clearEventHandlers()
83     */
84    Collection<EventHandler> getEventHandlers();
85
86    /** Remove all the event handlers that have been added to the integrator.
87     * @see #addEventHandler(EventHandler, double, double, int)
88     * @see #getEventHandlers()
89     */
90    void clearEventHandlers();
91
92    /** Get the current value of the step start time t<sub>i</sub>.
93     * <p>This method can be called during integration (typically by
94     * the object implementing the {@link FirstOrderDifferentialEquations
95     * differential equations} problem) if the value of the current step that
96     * is attempted is needed.</p>
97     * <p>The result is undefined if the method is called outside of
98     * calls to <code>integrate</code>.</p>
99     * @return current value of the step start time t<sub>i</sub>
100     */
101    double getCurrentStepStart();
102
103    /** Get the current signed value of the integration stepsize.
104     * <p>This method can be called during integration (typically by
105     * the object implementing the {@link FirstOrderDifferentialEquations
106     * differential equations} problem) if the signed value of the current stepsize
107     * that is tried is needed.</p>
108     * <p>The result is undefined if the method is called outside of
109     * calls to <code>integrate</code>.</p>
110     * @return current signed value of the stepsize
111     */
112    double getCurrentSignedStepsize();
113
114    /** Set the maximal number of differential equations function evaluations.
115     * <p>The purpose of this method is to avoid infinite loops which can occur
116     * for example when stringent error constraints are set or when lots of
117     * discrete events are triggered, thus leading to many rejected steps.</p>
118     * @param maxEvaluations maximal number of function evaluations (negative
119     * values are silently converted to maximal integer value, thus representing
120     * almost unlimited evaluations)
121     */
122    void setMaxEvaluations(int maxEvaluations);
123
124    /** Get the maximal number of functions evaluations.
125     * @return maximal number of functions evaluations
126     */
127    int getMaxEvaluations();
128
129    /** Get the number of evaluations of the differential equations function.
130     * <p>
131     * The number of evaluations corresponds to the last call to the
132     * <code>integrate</code> method. It is 0 if the method has not been called yet.
133     * </p>
134     * @return number of evaluations of the differential equations function
135     */
136    int getEvaluations();
137
138}
139