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
018package org.apache.commons.math3.ode.sampling;
019
020import java.io.Externalizable;
021
022import 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 * @since 1.2
046 */
047
048public interface StepInterpolator extends Externalizable {
049
050  /**
051   * Get the previous grid point time.
052   * @return previous grid point time
053   */
054  double getPreviousTime();
055
056  /**
057   * Get the current grid point time.
058   * @return current grid point time
059   */
060  double getCurrentTime();
061
062  /**
063   * Get the time of the interpolated point.
064   * If {@link #setInterpolatedTime} has not been called, it returns
065   * the current grid point time.
066   * @return interpolation point time
067   */
068  double getInterpolatedTime();
069
070  /**
071   * Set the time of the interpolated point.
072   * <p>Setting the time outside of the current step is now allowed, but
073   * should be used with care since the accuracy of the interpolator will
074   * probably be very poor far from this step. This allowance has been
075   * added to simplify implementation of search algorithms near the
076   * step endpoints.</p>
077   * <p>Setting the time changes the instance internal state. This includes
078   * the internal arrays returned in {@link #getInterpolatedState()},
079   * {@link #getInterpolatedDerivatives()}, {@link
080   * #getInterpolatedSecondaryState(int)} and {@link
081   * #getInterpolatedSecondaryDerivatives(int)}. So if their content must be preserved
082   * across several calls, user must copy them.</p>
083   * @param time time of the interpolated point
084   * @see #getInterpolatedState()
085   * @see #getInterpolatedDerivatives()
086   * @see #getInterpolatedSecondaryState(int)
087   * @see #getInterpolatedSecondaryDerivatives(int)
088   */
089  void setInterpolatedTime(double time);
090
091  /**
092   * Get the state vector of the interpolated point.
093   * <p>The returned vector is a reference to a reused array, so
094   * it should not be modified and it should be copied if it needs
095   * to be preserved across several calls to the associated
096   * {@link #setInterpolatedTime(double)} method.</p>
097   * @return state vector at time {@link #getInterpolatedTime}
098   * @see #getInterpolatedDerivatives()
099   * @see #getInterpolatedSecondaryState(int)
100   * @see #getInterpolatedSecondaryDerivatives(int)
101   * @see #setInterpolatedTime(double)
102   * @exception MaxCountExceededException if the number of functions evaluations is exceeded
103   */
104  double[] getInterpolatedState() throws MaxCountExceededException;
105
106  /**
107   * Get the derivatives of the state vector of the interpolated point.
108   * <p>The returned vector is a reference to a reused array, so
109   * it should not be modified and it should be copied if it needs
110   * to be preserved across several calls to the associated
111   * {@link #setInterpolatedTime(double)} method.</p>
112   * @return derivatives of the state vector at time {@link #getInterpolatedTime}
113   * @see #getInterpolatedState()
114   * @see #getInterpolatedSecondaryState(int)
115   * @see #getInterpolatedSecondaryDerivatives(int)
116   * @see #setInterpolatedTime(double)
117   * @since 2.0
118   * @exception MaxCountExceededException if the number of functions evaluations is exceeded
119   */
120  double[] getInterpolatedDerivatives() throws MaxCountExceededException;
121
122  /** Get the interpolated secondary state corresponding to the secondary equations.
123   * <p>The returned vector is a reference to a reused array, so
124   * it should not be modified and it should be copied if it needs
125   * to be preserved across several calls to the associated
126   * {@link #setInterpolatedTime(double)} method.</p>
127   * @param index index of the secondary set, as returned by {@link
128   * org.apache.commons.math3.ode.ExpandableStatefulODE#addSecondaryEquations(
129   * org.apache.commons.math3.ode.SecondaryEquations)
130   * ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)}
131   * @return interpolated secondary state at the current interpolation date
132   * @see #getInterpolatedState()
133   * @see #getInterpolatedDerivatives()
134   * @see #getInterpolatedSecondaryDerivatives(int)
135   * @see #setInterpolatedTime(double)
136   * @since 3.0
137   * @exception MaxCountExceededException if the number of functions evaluations is exceeded
138   */
139  double[] getInterpolatedSecondaryState(int index) throws MaxCountExceededException;
140
141  /** Get the interpolated secondary derivatives corresponding to the secondary equations.
142   * <p>The returned vector is a reference to a reused array, so
143   * it should not be modified and it should be copied if it needs
144   * to be preserved across several calls.</p>
145   * @param index index of the secondary set, as returned by {@link
146   * org.apache.commons.math3.ode.ExpandableStatefulODE#addSecondaryEquations(
147   * org.apache.commons.math3.ode.SecondaryEquations)
148   * ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)}
149   * @return interpolated secondary derivatives at the current interpolation date
150   * @see #getInterpolatedState()
151   * @see #getInterpolatedDerivatives()
152   * @see #getInterpolatedSecondaryState(int)
153   * @see #setInterpolatedTime(double)
154   * @since 3.0
155   * @exception MaxCountExceededException if the number of functions evaluations is exceeded
156   */
157  double[] getInterpolatedSecondaryDerivatives(int index) throws MaxCountExceededException;
158
159  /** Check if the natural integration direction is forward.
160   * <p>This method provides the integration direction as specified by
161   * the integrator itself, it avoid some nasty problems in
162   * degenerated cases like null steps due to cancellation at step
163   * initialization, step control or discrete events
164   * triggering.</p>
165   * @return true if the integration variable (time) increases during
166   * integration
167   */
168  boolean isForward();
169
170  /** Copy the instance.
171   * <p>The copied instance is guaranteed to be independent from the
172   * original one. Both can be used with different settings for
173   * interpolated time without any side effect.</p>
174   * @return a deep copy of the instance, which can be used independently.
175   * @see #setInterpolatedTime(double)
176   * @exception MaxCountExceededException if the number of functions evaluations is exceeded
177   * during step finalization
178   */
179   StepInterpolator copy() throws MaxCountExceededException;
180
181}