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.sampling;
019    
020    import org.apache.commons.math.ode.ContinuousOutputModel;
021    import org.apache.commons.math.ode.DerivativeException;
022    import org.apache.commons.math.ode.FirstOrderIntegrator;
023    import org.apache.commons.math.ode.SecondOrderIntegrator;
024    
025    /**
026     * This interface represents a handler that should be called after
027     * each successful step.
028     *
029     * <p>The ODE integrators compute the evolution of the state vector at
030     * some grid points that depend on their own internal algorithm. Once
031     * they have found a new grid point (possibly after having computed
032     * several evaluation of the derivative at intermediate points), they
033     * provide it to objects implementing this interface. These objects
034     * typically either ignore the intermediate steps and wait for the
035     * last one, store the points in an ephemeris, or forward them to
036     * specialized processing or output methods.</p>
037     *
038     * @see FirstOrderIntegrator
039     * @see SecondOrderIntegrator
040     * @see StepInterpolator
041     * @version $Revision: 786881 $ $Date: 2009-06-20 14:53:08 -0400 (Sat, 20 Jun 2009) $
042     * @since 1.2
043     */
044    
045    public interface StepHandler {
046    
047      /** Determines whether this handler needs dense output.
048       * <p>This method allows the integrator to avoid performing extra
049       * computation if the handler does not need dense output. If this
050       * method returns false, the integrator will call the {@link
051       * #handleStep} method with a {@link DummyStepInterpolator} rather
052       * than a custom interpolator.</p>
053       * @return true if the handler needs dense output
054       */
055      public boolean requiresDenseOutput();
056    
057      /** Reset the step handler.
058       * Initialize the internal data as required before the first step is
059       * handled.
060       */
061      public void reset();
062    
063      /**
064       * Handle the last accepted step
065       * @param interpolator interpolator for the last accepted step. For
066       * efficiency purposes, the various integrators reuse the same
067       * object on each call, so if the instance wants to keep it across
068       * all calls (for example to provide at the end of the integration a
069       * continuous model valid throughout the integration range, as the
070       * {@link ContinuousOutputModel ContinuousOutputModel} class does),
071       * it should build a local copy using the clone method of the
072       * interpolator and store this copy. Keeping only a reference to the
073       * interpolator and reusing it will result in unpredictable
074       * behaviour (potentially crashing the application).
075       * @param isLast true if the step is the last one
076       * @throws DerivativeException this exception is propagated to the
077       * caller if the underlying user function triggers one
078       */
079      public void handleStep(StepInterpolator interpolator, boolean isLast)
080        throws DerivativeException;
081        
082    }