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 java.io.Externalizable;
021    
022    import org.apache.commons.math3.exception.MaxCountExceededException;
023    
024    /** This interface represents an interpolator over the last step
025     * during an ODE integration.
026     *
027     * <p>The various ODE integrators provide objects implementing this
028     * interface to the step handlers. These objects are often custom
029     * objects tightly bound to the integrator internal algorithms. The
030     * handlers can use these objects to retrieve the state vector at
031     * intermediate times between the previous and the current grid points
032     * (this feature is often called dense output).</p>
033     * <p>One important thing to note is that the step handlers may be so
034     * tightly bound to the integrators that they often share some internal
035     * state arrays. This imply that one should <em>never</em> use a direct
036     * reference to a step interpolator outside of the step handler, either
037     * for future use or for use in another thread. If such a need arise, the
038     * step interpolator <em>must</em> be copied using the dedicated
039     * {@link #copy()} method.
040     * </p>
041     *
042     * @see org.apache.commons.math3.ode.FirstOrderIntegrator
043     * @see org.apache.commons.math3.ode.SecondOrderIntegrator
044     * @see StepHandler
045     * @version $Id: StepInterpolator.java 1416643 2012-12-03 19:37:14Z tn $
046     * @since 1.2
047     */
048    
049    public interface StepInterpolator extends Externalizable {
050    
051      /**
052       * Get the previous grid point time.
053       * @return previous grid point time
054       */
055      double getPreviousTime();
056    
057      /**
058       * Get the current grid point time.
059       * @return current grid point time
060       */
061      double getCurrentTime();
062    
063      /**
064       * Get the time of the interpolated point.
065       * If {@link #setInterpolatedTime} has not been called, it returns
066       * the current grid point time.
067       * @return interpolation point time
068       */
069      double getInterpolatedTime();
070    
071      /**
072       * Set the time of the interpolated point.
073       * <p>Setting the time outside of the current step is now allowed, but
074       * should be used with care since the accuracy of the interpolator will
075       * probably be very poor far from this step. This allowance has been
076       * added to simplify implementation of search algorithms near the
077       * step endpoints.</p>
078       * <p>Setting the time changes the instance internal state. If a
079       * specific state must be preserved, a copy of the instance must be
080       * created using {@link #copy()}.</p>
081       * @param time time of the interpolated point
082       */
083      void setInterpolatedTime(double time);
084    
085      /**
086       * Get the state vector of the interpolated point.
087       * <p>The returned vector is a reference to a reused array, so
088       * it should not be modified and it should be copied if it needs
089       * to be preserved across several calls.</p>
090       * @return state vector at time {@link #getInterpolatedTime}
091       * @see #getInterpolatedDerivatives()
092       * @exception MaxCountExceededException if the number of functions evaluations is exceeded
093       */
094      double[] getInterpolatedState() throws MaxCountExceededException;
095    
096      /**
097       * Get the derivatives of the state vector of the interpolated point.
098       * <p>The returned vector is a reference to a reused array, so
099       * it should not be modified and it should be copied if it needs
100       * to be preserved across several calls.</p>
101       * @return derivatives of the state vector at time {@link #getInterpolatedTime}
102       * @see #getInterpolatedState()
103       * @since 2.0
104       * @exception MaxCountExceededException if the number of functions evaluations is exceeded
105       */
106      double[] getInterpolatedDerivatives() throws MaxCountExceededException;
107    
108      /** Get the interpolated secondary state corresponding to the secondary equations.
109       * <p>The returned vector is a reference to a reused array, so
110       * it should not be modified and it should be copied if it needs
111       * to be preserved across several calls.</p>
112       * @param index index of the secondary set, as returned by {@link
113       * org.apache.commons.math3.ode.ExpandableStatefulODE#addSecondaryEquations(
114       * org.apache.commons.math3.ode.SecondaryEquations)
115       * ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)}
116       * @return interpolated secondary state at the current interpolation date
117       * @see #getInterpolatedState()
118       * @see #getInterpolatedDerivatives()
119       * @see #getInterpolatedSecondaryDerivatives(int)
120       * @see #setInterpolatedTime(double)
121       * @since 3.0
122       * @exception MaxCountExceededException if the number of functions evaluations is exceeded
123       */
124      double[] getInterpolatedSecondaryState(int index) throws MaxCountExceededException;
125    
126      /** Get the interpolated secondary derivatives corresponding to the secondary equations.
127       * <p>The returned vector is a reference to a reused array, so
128       * it should not be modified and it should be copied if it needs
129       * to be preserved across several calls.</p>
130       * @param index index of the secondary set, as returned by {@link
131       * org.apache.commons.math3.ode.ExpandableStatefulODE#addSecondaryEquations(
132       * org.apache.commons.math3.ode.SecondaryEquations)
133       * ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)}
134       * @return interpolated secondary derivatives at the current interpolation date
135       * @see #getInterpolatedState()
136       * @see #getInterpolatedDerivatives()
137       * @see #getInterpolatedSecondaryState(int)
138       * @see #setInterpolatedTime(double)
139       * @since 3.0
140       * @exception MaxCountExceededException if the number of functions evaluations is exceeded
141       */
142      double[] getInterpolatedSecondaryDerivatives(int index) throws MaxCountExceededException;
143    
144      /** Check if the natural integration direction is forward.
145       * <p>This method provides the integration direction as specified by
146       * the integrator itself, it avoid some nasty problems in
147       * degenerated cases like null steps due to cancellation at step
148       * initialization, step control or discrete events
149       * triggering.</p>
150       * @return true if the integration variable (time) increases during
151       * integration
152       */
153      boolean isForward();
154    
155      /** Copy the instance.
156       * <p>The copied instance is guaranteed to be independent from the
157       * original one. Both can be used with different settings for
158       * interpolated time without any side effect.</p>
159       * @return a deep copy of the instance, which can be used independently.
160       * @see #setInterpolatedTime(double)
161       * @exception MaxCountExceededException if the number of functions evaluations is exceeded
162       * during step finalization
163       */
164       StepInterpolator copy() throws MaxCountExceededException;
165    
166    }