    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    }