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. If a
78     * specific state must be preserved, a copy of the instance must be
79     * created using {@link #copy()}.</p>
80     * @param time time of the interpolated point
81     */
82    void setInterpolatedTime(double time);
83  
84    /**
85     * Get the state vector of the interpolated point.
86     * <p>The returned vector is a reference to a reused array, so
87     * it should not be modified and it should be copied if it needs
88     * to be preserved across several calls.</p>
89     * @return state vector at time {@link #getInterpolatedTime}
90     * @see #getInterpolatedDerivatives()
91     * @exception MaxCountExceededException if the number of functions evaluations is exceeded
92     */
93    double[] getInterpolatedState() throws MaxCountExceededException;
94  
95    /**
96     * Get the derivatives of the state vector of the interpolated point.
97     * <p>The returned vector is a reference to a reused array, so
98     * it should not be modified and it should be copied if it needs
99     * to be preserved across several calls.</p>
100    * @return derivatives of the state vector at time {@link #getInterpolatedTime}
101    * @see #getInterpolatedState()
102    * @since 2.0
103    * @exception MaxCountExceededException if the number of functions evaluations is exceeded
104    */
105   double[] getInterpolatedDerivatives() throws MaxCountExceededException;
106 
107   /** Get the interpolated secondary state corresponding to the secondary equations.
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.</p>
111    * @param index index of the secondary set, as returned by {@link
112    * org.apache.commons.math3.ode.ExpandableStatefulODE#addSecondaryEquations(
113    * org.apache.commons.math3.ode.SecondaryEquations)
114    * ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)}
115    * @return interpolated secondary state at the current interpolation date
116    * @see #getInterpolatedState()
117    * @see #getInterpolatedDerivatives()
118    * @see #getInterpolatedSecondaryDerivatives(int)
119    * @see #setInterpolatedTime(double)
120    * @since 3.0
121    * @exception MaxCountExceededException if the number of functions evaluations is exceeded
122    */
123   double[] getInterpolatedSecondaryState(int index) throws MaxCountExceededException;
124 
125   /** Get the interpolated secondary derivatives corresponding to the secondary equations.
126    * <p>The returned vector is a reference to a reused array, so
127    * it should not be modified and it should be copied if it needs
128    * to be preserved across several calls.</p>
129    * @param index index of the secondary set, as returned by {@link
130    * org.apache.commons.math3.ode.ExpandableStatefulODE#addSecondaryEquations(
131    * org.apache.commons.math3.ode.SecondaryEquations)
132    * ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)}
133    * @return interpolated secondary derivatives at the current interpolation date
134    * @see #getInterpolatedState()
135    * @see #getInterpolatedDerivatives()
136    * @see #getInterpolatedSecondaryState(int)
137    * @see #setInterpolatedTime(double)
138    * @since 3.0
139    * @exception MaxCountExceededException if the number of functions evaluations is exceeded
140    */
141   double[] getInterpolatedSecondaryDerivatives(int index) throws MaxCountExceededException;
142 
143   /** Check if the natural integration direction is forward.
144    * <p>This method provides the integration direction as specified by
145    * the integrator itself, it avoid some nasty problems in
146    * degenerated cases like null steps due to cancellation at step
147    * initialization, step control or discrete events
148    * triggering.</p>
149    * @return true if the integration variable (time) increases during
150    * integration
151    */
152   boolean isForward();
153 
154   /** Copy the instance.
155    * <p>The copied instance is guaranteed to be independent from the
156    * original one. Both can be used with different settings for
157    * interpolated time without any side effect.</p>
158    * @return a deep copy of the instance, which can be used independently.
159    * @see #setInterpolatedTime(double)
160    * @exception MaxCountExceededException if the number of functions evaluations is exceeded
161    * during step finalization
162    */
163    StepInterpolator copy() throws MaxCountExceededException;
164 
165 }