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    }