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