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