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.math.ode;
019
020 import java.util.Collection;
021
022 import org.apache.commons.math.ode.events.EventHandler;
023 import org.apache.commons.math.ode.sampling.StepHandler;
024
025 /**
026 * This interface defines the common parts shared by integrators
027 * for first and second order differential equations.
028 * @see FirstOrderIntegrator
029 * @see SecondOrderIntegrator
030 * @version $Revision: 1061507 $ $Date: 2011-01-20 21:55:00 +0100 (jeu. 20 janv. 2011) $
031 * @since 2.0
032 */
033 public interface ODEIntegrator {
034
035 /** Get the name of the method.
036 * @return name of the method
037 */
038 String getName();
039
040 /** Add a step handler to this integrator.
041 * <p>The handler will be called by the integrator for each accepted
042 * step.</p>
043 * @param handler handler for the accepted steps
044 * @see #getStepHandlers()
045 * @see #clearStepHandlers()
046 * @since 2.0
047 */
048 void addStepHandler(StepHandler handler);
049
050 /** Get all the step handlers that have been added to the integrator.
051 * @return an unmodifiable collection of the added events handlers
052 * @see #addStepHandler(StepHandler)
053 * @see #clearStepHandlers()
054 * @since 2.0
055 */
056 Collection<StepHandler> getStepHandlers();
057
058 /** Remove all the step handlers that have been added to the integrator.
059 * @see #addStepHandler(StepHandler)
060 * @see #getStepHandlers()
061 * @since 2.0
062 */
063 void clearStepHandlers();
064
065 /** Add an event handler to the integrator.
066 * @param handler event handler
067 * @param maxCheckInterval maximal time interval between switching
068 * function checks (this interval prevents missing sign changes in
069 * case the integration steps becomes very large)
070 * @param convergence convergence threshold in the event time search
071 * @param maxIterationCount upper limit of the iteration count in
072 * the event time search
073 * @see #getEventHandlers()
074 * @see #clearEventHandlers()
075 */
076 void addEventHandler(EventHandler handler, double maxCheckInterval,
077 double convergence, int maxIterationCount);
078
079 /** Get all the event handlers that have been added to the integrator.
080 * @return an unmodifiable collection of the added events handlers
081 * @see #addEventHandler(EventHandler, double, double, int)
082 * @see #clearEventHandlers()
083 */
084 Collection<EventHandler> getEventHandlers();
085
086 /** Remove all the event handlers that have been added to the integrator.
087 * @see #addEventHandler(EventHandler, double, double, int)
088 * @see #getEventHandlers()
089 */
090 void clearEventHandlers();
091
092 /** Get the current value of the step start time t<sub>i</sub>.
093 * <p>This method can be called during integration (typically by
094 * the object implementing the {@link FirstOrderDifferentialEquations
095 * differential equations} problem) if the value of the current step that
096 * is attempted is needed.</p>
097 * <p>The result is undefined if the method is called outside of
098 * calls to <code>integrate</code>.</p>
099 * @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 }