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: 785473 $ $Date: 2009-06-17 00:02:35 -0400 (Wed, 17 Jun 2009) $
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,
077 double maxCheckInterval,
078 double convergence,
079 int maxIterationCount);
080
081 /** Get all the event handlers that have been added to the integrator.
082 * @return an unmodifiable collection of the added events handlers
083 * @see #addEventHandler(EventHandler, double, double, int)
084 * @see #clearEventHandlers()
085 */
086 Collection<EventHandler> getEventHandlers();
087
088 /** Remove all the event handlers that have been added to the integrator.
089 * @see #addEventHandler(EventHandler, double, double, int)
090 * @see #getEventHandlers()
091 */
092 void clearEventHandlers();
093
094 /** Get the current value of the step start time t<sub>i</sub>.
095 * <p>This method can be called during integration (typically by
096 * the object implementing the {@link FirstOrderDifferentialEquations
097 * differential equations} problem) if the value of the current step that
098 * is attempted is needed.</p>
099 * <p>The result is undefined if the method is called outside of
100 * calls to <code>integrate</code>.</p>
101 * @return current value of the step start time t<sub>i</sub>
102 */
103 double getCurrentStepStart();
104
105 /** Get the current signed value of the integration stepsize.
106 * <p>This method can be called during integration (typically by
107 * the object implementing the {@link FirstOrderDifferentialEquations
108 * differential equations} problem) if the signed value of the current stepsize
109 * that is tried is needed.</p>
110 * <p>The result is undefined if the method is called outside of
111 * calls to <code>integrate</code>.</p>
112 * @return current signed value of the stepsize
113 */
114 double getCurrentSignedStepsize();
115
116 /** Set the maximal number of differential equations function evaluations.
117 * <p>The purpose of this method is to avoid infinite loops which can occur
118 * for example when stringent error constraints are set or when lots of
119 * discrete events are triggered, thus leading to many rejected steps.</p>
120 * @param maxEvaluations maximal number of function evaluations (negative
121 * values are silently converted to maximal integer value, thus representing
122 * almost unlimited evaluations)
123 */
124 void setMaxEvaluations(int maxEvaluations);
125
126 /** Get the maximal number of functions evaluations.
127 * @return maximal number of functions evaluations
128 */
129 int getMaxEvaluations();
130
131 /** Get the number of evaluations of the differential equations function.
132 * <p>
133 * The number of evaluations corresponds to the last call to the
134 * <code>integrate</code> method. It is 0 if the method has not been called yet.
135 * </p>
136 * @return number of evaluations of the differential equations function
137 */
138 int getEvaluations();
139
140 }