001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.math3.ode;
019
020 import java.util.Collection;
021
022 import org.apache.commons.math3.analysis.solvers.UnivariateSolver;
023 import org.apache.commons.math3.ode.events.EventHandler;
024 import org.apache.commons.math3.ode.sampling.StepHandler;
025
026 /**
027 * This interface defines the common parts shared by integrators
028 * for first and second order differential equations.
029 * @see FirstOrderIntegrator
030 * @see SecondOrderIntegrator
031 * @version $Id: ODEIntegrator.java 1416643 2012-12-03 19:37:14Z tn $
032 * @since 2.0
033 */
034 public interface ODEIntegrator {
035
036 /** Get the name of the method.
037 * @return name of the method
038 */
039 String getName();
040
041 /** Add a step handler to this integrator.
042 * <p>The handler will be called by the integrator for each accepted
043 * step.</p>
044 * @param handler handler for the accepted steps
045 * @see #getStepHandlers()
046 * @see #clearStepHandlers()
047 * @since 2.0
048 */
049 void addStepHandler(StepHandler handler);
050
051 /** Get all the step handlers that have been added to the integrator.
052 * @return an unmodifiable collection of the added events handlers
053 * @see #addStepHandler(StepHandler)
054 * @see #clearStepHandlers()
055 * @since 2.0
056 */
057 Collection<StepHandler> getStepHandlers();
058
059 /** Remove all the step handlers that have been added to the integrator.
060 * @see #addStepHandler(StepHandler)
061 * @see #getStepHandlers()
062 * @since 2.0
063 */
064 void clearStepHandlers();
065
066 /** Add an event handler to the integrator.
067 * Uses a default {@link UnivariateSolver}
068 * with an absolute accuracy equal to the given convergence threshold,
069 * as root-finding algorithm to detect the state events.
070 * @param handler event handler
071 * @param maxCheckInterval maximal time interval between switching
072 * function checks (this interval prevents missing sign changes in
073 * case the integration steps becomes very large)
074 * @param convergence convergence threshold in the event time search
075 * @param maxIterationCount upper limit of the iteration count in
076 * the event time search
077 * @see #getEventHandlers()
078 * @see #clearEventHandlers()
079 */
080 void addEventHandler(EventHandler handler, double maxCheckInterval,
081 double convergence, int maxIterationCount);
082
083 /** Add an event handler to the integrator.
084 * @param handler event handler
085 * @param maxCheckInterval maximal time interval between switching
086 * function checks (this interval prevents missing sign changes in
087 * case the integration steps becomes very large)
088 * @param convergence convergence threshold in the event time search
089 * @param maxIterationCount upper limit of the iteration count in
090 * the event time search
091 * @param solver The root-finding algorithm to use to detect the state
092 * events.
093 * @see #getEventHandlers()
094 * @see #clearEventHandlers()
095 */
096 void addEventHandler(EventHandler handler, double maxCheckInterval,
097 double convergence, int maxIterationCount,
098 UnivariateSolver solver);
099
100 /** Get all the event handlers that have been added to the integrator.
101 * @return an unmodifiable collection of the added events handlers
102 * @see #addEventHandler(EventHandler, double, double, int)
103 * @see #clearEventHandlers()
104 */
105 Collection<EventHandler> getEventHandlers();
106
107 /** Remove all the event handlers that have been added to the integrator.
108 * @see #addEventHandler(EventHandler, double, double, int)
109 * @see #getEventHandlers()
110 */
111 void clearEventHandlers();
112
113 /** Get the current value of the step start time t<sub>i</sub>.
114 * <p>This method can be called during integration (typically by
115 * the object implementing the {@link FirstOrderDifferentialEquations
116 * differential equations} problem) if the value of the current step that
117 * is attempted is needed.</p>
118 * <p>The result is undefined if the method is called outside of
119 * calls to <code>integrate</code>.</p>
120 * @return current value of the step start time t<sub>i</sub>
121 */
122 double getCurrentStepStart();
123
124 /** Get the current signed value of the integration stepsize.
125 * <p>This method can be called during integration (typically by
126 * the object implementing the {@link FirstOrderDifferentialEquations
127 * differential equations} problem) if the signed value of the current stepsize
128 * that is tried is needed.</p>
129 * <p>The result is undefined if the method is called outside of
130 * calls to <code>integrate</code>.</p>
131 * @return current signed value of the stepsize
132 */
133 double getCurrentSignedStepsize();
134
135 /** Set the maximal number of differential equations function evaluations.
136 * <p>The purpose of this method is to avoid infinite loops which can occur
137 * for example when stringent error constraints are set or when lots of
138 * discrete events are triggered, thus leading to many rejected steps.</p>
139 * @param maxEvaluations maximal number of function evaluations (negative
140 * values are silently converted to maximal integer value, thus representing
141 * almost unlimited evaluations)
142 */
143 void setMaxEvaluations(int maxEvaluations);
144
145 /** Get the maximal number of functions evaluations.
146 * @return maximal number of functions evaluations
147 */
148 int getMaxEvaluations();
149
150 /** Get the number of evaluations of the differential equations function.
151 * <p>
152 * The number of evaluations corresponds to the last call to the
153 * <code>integrate</code> method. It is 0 if the method has not been called yet.
154 * </p>
155 * @return number of evaluations of the differential equations function
156 */
157 int getEvaluations();
158
159 }