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.sampling;
019    
020    import org.apache.commons.math3.exception.MaxCountExceededException;
021    
022    
023    /**
024     * This interface represents a handler that should be called after
025     * each successful step.
026     *
027     * <p>The ODE integrators compute the evolution of the state vector at
028     * some grid points that depend on their own internal algorithm. Once
029     * they have found a new grid point (possibly after having computed
030     * several evaluation of the derivative at intermediate points), they
031     * provide it to objects implementing this interface. These objects
032     * typically either ignore the intermediate steps and wait for the
033     * last one, store the points in an ephemeris, or forward them to
034     * specialized processing or output methods.</p>
035     *
036     * @see org.apache.commons.math3.ode.FirstOrderIntegrator
037     * @see org.apache.commons.math3.ode.SecondOrderIntegrator
038     * @see StepInterpolator
039     * @version $Id: StepHandler.java 1416643 2012-12-03 19:37:14Z tn $
040     * @since 1.2
041     */
042    
043    public interface StepHandler {
044    
045        /** Initialize step handler at the start of an ODE integration.
046         * <p>
047         * This method is called once at the start of the integration. It
048         * may be used by the step handler to initialize some internal data
049         * if needed.
050         * </p>
051         * @param t0 start value of the independent <i>time</i> variable
052         * @param y0 array containing the start value of the state vector
053         * @param t target time for the integration
054         */
055        void init(double t0, double[] y0, double t);
056    
057        /**
058         * Handle the last accepted step
059         * @param interpolator interpolator for the last accepted step. For
060         * efficiency purposes, the various integrators reuse the same
061         * object on each call, so if the instance wants to keep it across
062         * all calls (for example to provide at the end of the integration a
063         * continuous model valid throughout the integration range, as the
064         * {@link org.apache.commons.math3.ode.ContinuousOutputModel
065         * ContinuousOutputModel} class does), it should build a local copy
066         * using the clone method of the interpolator and store this copy.
067         * Keeping only a reference to the interpolator and reusing it will
068         * result in unpredictable behavior (potentially crashing the application).
069         * @param isLast true if the step is the last one
070         * @exception MaxCountExceededException if the interpolator throws one because
071         * the number of functions evaluations is exceeded
072         */
073        void handleStep(StepInterpolator interpolator, boolean isLast)
074            throws MaxCountExceededException;
075    
076    }