    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.jacobians;
    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     * <p>Note that is is possible to register a {@link
    036     * org.apache.commons.math.ode.sampling.StepHandler classical step handler}
    037     * in the low level integrator used to build a {@link FirstOrderIntegratorWithJacobians}
    038     * rather than implementing this class. The step handlers registered at low level
    039     * will see the big compound state whether the step handlers defined by this interface
    040     * see the original state, and its jacobians in separate arrays.</p>
    041     *
    042     * <p>The compound state is guaranteed to contain the original state in the first
    043     * elements, followed by the jacobian with respect to initial state (in row order),
    044     * followed by the jacobian with respect to parameters (in row order). If for example
    045     * the original state dimension is 6 and there are 3 parameters, the compound state will
    046     * be a 60 elements array. The first 6 elements will be the original state, the next 36
    047     * elements will be the jacobian with respect to initial state, and the remaining 18 elements
    048     * will be the jacobian with respect to parameters.</p>
    049     *
    050     * <p>Dealing with low level step handlers is cumbersome if one really needs the jacobians
    051     * in these methods, but it also prevents many data being copied back and forth between
    052     * state and jacobians on one side and compound state on the other side. So for performance
    053     * reasons, it is recommended to use this interface <em>only</em> if jacobians are really
    054     * needed and to use lower level handlers if only state is needed.</p>
    055     *
    056     * @see FirstOrderIntegratorWithJacobians
    057     * @see StepInterpolatorWithJacobians
    058     * @version $Revision: 1073158 $ $Date: 2011-02-21 22:46:52 +0100 (lun. 21 f??vr. 2011) $
    059     * @since 2.1
    060     * @deprecated as of 2.2 the complete package is deprecated, it will be replaced
    061     * in 3.0 by a completely rewritten implementation
    062     */
    063    @Deprecated
    064    public interface StepHandlerWithJacobians {
    065
    066      /** Determines whether this handler needs dense output.
    067       * <p>This method allows the integrator to avoid performing extra
    068       * computation if the handler does not need dense output.</p>
    069       * @return true if the handler needs dense output
    070       */
    071      boolean requiresDenseOutput();
    072
    073      /** Reset the step handler.
    074       * Initialize the internal data as required before the first step is
    075       * handled.
    076       */
    077      void reset();
    078
    079      /**
    080       * Handle the last accepted step
    081       * @param interpolator interpolator for the last accepted step. For
    082       * efficiency purposes, the various integrators reuse the same
    083       * object on each call, so if the instance wants to keep it across
    084       * all calls (for example to provide at the end of the integration a
    085       * continuous model valid throughout the integration range, as the
    086       * {@link org.apache.commons.math.ode.ContinuousOutputModel
    087       * ContinuousOutputModel} class does), it should build a local copy
    088       * using the clone method of the interpolator and store this copy.
    089       * Keeping only a reference to the interpolator and reusing it will
    090       * result in unpredictable behavior (potentially crashing the application).
    091       * @param isLast true if the step is the last one
    092       * @throws DerivativeException this exception is propagated to the
    093       * caller if the underlying user function triggers one
    094       */
    095      void handleStep(StepInterpolatorWithJacobians interpolator, boolean isLast) throws DerivativeException;
    096
    097    }