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    }