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    }