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