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 }