View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.math3.ode.sampling;
19  
20  import java.io.Externalizable;
21  
22  import org.apache.commons.math3.exception.MaxCountExceededException;
23  
24  /** This interface represents an interpolator over the last step
25   * during an ODE integration.
26   *
27   * <p>The various ODE integrators provide objects implementing this
28   * interface to the step handlers. These objects are often custom
29   * objects tightly bound to the integrator internal algorithms. The
30   * handlers can use these objects to retrieve the state vector at
31   * intermediate times between the previous and the current grid points
32   * (this feature is often called dense output).</p>
33   * <p>One important thing to note is that the step handlers may be so
34   * tightly bound to the integrators that they often share some internal
35   * state arrays. This imply that one should <em>never</em> use a direct
36   * reference to a step interpolator outside of the step handler, either
37   * for future use or for use in another thread. If such a need arise, the
38   * step interpolator <em>must</em> be copied using the dedicated
39   * {@link #copy()} method.
40   * </p>
41   *
42   * @see org.apache.commons.math3.ode.FirstOrderIntegrator
43   * @see org.apache.commons.math3.ode.SecondOrderIntegrator
44   * @see StepHandler
45   * @since 1.2
46   */
47  
48  public interface StepInterpolator extends Externalizable {
49  
50    /**
51     * Get the previous grid point time.
52     * @return previous grid point time
53     */
54    double getPreviousTime();
55  
56    /**
57     * Get the current grid point time.
58     * @return current grid point time
59     */
60    double getCurrentTime();
61  
62    /**
63     * Get the time of the interpolated point.
64     * If {@link #setInterpolatedTime} has not been called, it returns
65     * the current grid point time.
66     * @return interpolation point time
67     */
68    double getInterpolatedTime();
69  
70    /**
71     * Set the time of the interpolated point.
72     * <p>Setting the time outside of the current step is now allowed, but
73     * should be used with care since the accuracy of the interpolator will
74     * probably be very poor far from this step. This allowance has been
75     * added to simplify implementation of search algorithms near the
76     * step endpoints.</p>
77     * <p>Setting the time changes the instance internal state. This includes
78     * the internal arrays returned in {@link #getInterpolatedState()},
79     * {@link #getInterpolatedDerivatives()}, {@link
80     * #getInterpolatedSecondaryState(int)} and {@link
81     * #getInterpolatedSecondaryDerivatives(int)}. So if their content must be preserved
82     * across several calls, user must copy them.</p>
83     * @param time time of the interpolated point
84     * @see #getInterpolatedState()
85     * @see #getInterpolatedDerivatives()
86     * @see #getInterpolatedSecondaryState(int)
87     * @see #getInterpolatedSecondaryDerivatives(int)
88     */
89    void setInterpolatedTime(double time);
90  
91    /**
92     * Get the state vector of the interpolated point.
93     * <p>The returned vector is a reference to a reused array, so
94     * it should not be modified and it should be copied if it needs
95     * to be preserved across several calls to the associated
96     * {@link #setInterpolatedTime(double)} method.</p>
97     * @return state vector at time {@link #getInterpolatedTime}
98     * @see #getInterpolatedDerivatives()
99     * @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 }