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   * @version $Id: StepInterpolator.java 1416643 2012-12-03 19:37:14Z tn $
46   * @since 1.2
47   */
48  
49  public interface StepInterpolator extends Externalizable {
50  
51    /**
52     * Get the previous grid point time.
53     * @return previous grid point time
54     */
55    double getPreviousTime();
56  
57    /**
58     * Get the current grid point time.
59     * @return current grid point time
60     */
61    double getCurrentTime();
62  
63    /**
64     * Get the time of the interpolated point.
65     * If {@link #setInterpolatedTime} has not been called, it returns
66     * the current grid point time.
67     * @return interpolation point time
68     */
69    double getInterpolatedTime();
70  
71    /**
72     * Set the time of the interpolated point.
73     * <p>Setting the time outside of the current step is now allowed, but
74     * should be used with care since the accuracy of the interpolator will
75     * probably be very poor far from this step. This allowance has been
76     * added to simplify implementation of search algorithms near the
77     * step endpoints.</p>
78     * <p>Setting the time changes the instance internal state. If a
79     * specific state must be preserved, a copy of the instance must be
80     * created using {@link #copy()}.</p>
81     * @param time time of the interpolated point
82     */
83    void setInterpolatedTime(double time);
84  
85    /**
86     * Get the state vector of the interpolated point.
87     * <p>The returned vector is a reference to a reused array, so
88     * it should not be modified and it should be copied if it needs
89     * to be preserved across several calls.</p>
90     * @return state vector at time {@link #getInterpolatedTime}
91     * @see #getInterpolatedDerivatives()
92     * @exception MaxCountExceededException if the number of functions evaluations is exceeded
93     */
94    double[] getInterpolatedState() throws MaxCountExceededException;
95  
96    /**
97     * Get the derivatives of the state vector of the interpolated point.
98     * <p>The returned vector is a reference to a reused array, so
99     * it should not be modified and it should be copied if it needs
100    * to be preserved across several calls.</p>
101    * @return derivatives of the state vector at time {@link #getInterpolatedTime}
102    * @see #getInterpolatedState()
103    * @since 2.0
104    * @exception MaxCountExceededException if the number of functions evaluations is exceeded
105    */
106   double[] getInterpolatedDerivatives() throws MaxCountExceededException;
107 
108   /** Get the interpolated secondary state corresponding to the secondary equations.
109    * <p>The returned vector is a reference to a reused array, so
110    * it should not be modified and it should be copied if it needs
111    * to be preserved across several calls.</p>
112    * @param index index of the secondary set, as returned by {@link
113    * org.apache.commons.math3.ode.ExpandableStatefulODE#addSecondaryEquations(
114    * org.apache.commons.math3.ode.SecondaryEquations)
115    * ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)}
116    * @return interpolated secondary state at the current interpolation date
117    * @see #getInterpolatedState()
118    * @see #getInterpolatedDerivatives()
119    * @see #getInterpolatedSecondaryDerivatives(int)
120    * @see #setInterpolatedTime(double)
121    * @since 3.0
122    * @exception MaxCountExceededException if the number of functions evaluations is exceeded
123    */
124   double[] getInterpolatedSecondaryState(int index) throws MaxCountExceededException;
125 
126   /** Get the interpolated secondary derivatives corresponding to the secondary equations.
127    * <p>The returned vector is a reference to a reused array, so
128    * it should not be modified and it should be copied if it needs
129    * to be preserved across several calls.</p>
130    * @param index index of the secondary set, as returned by {@link
131    * org.apache.commons.math3.ode.ExpandableStatefulODE#addSecondaryEquations(
132    * org.apache.commons.math3.ode.SecondaryEquations)
133    * ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)}
134    * @return interpolated secondary derivatives at the current interpolation date
135    * @see #getInterpolatedState()
136    * @see #getInterpolatedDerivatives()
137    * @see #getInterpolatedSecondaryState(int)
138    * @see #setInterpolatedTime(double)
139    * @since 3.0
140    * @exception MaxCountExceededException if the number of functions evaluations is exceeded
141    */
142   double[] getInterpolatedSecondaryDerivatives(int index) throws MaxCountExceededException;
143 
144   /** Check if the natural integration direction is forward.
145    * <p>This method provides the integration direction as specified by
146    * the integrator itself, it avoid some nasty problems in
147    * degenerated cases like null steps due to cancellation at step
148    * initialization, step control or discrete events
149    * triggering.</p>
150    * @return true if the integration variable (time) increases during
151    * integration
152    */
153   boolean isForward();
154 
155   /** Copy the instance.
156    * <p>The copied instance is guaranteed to be independent from the
157    * original one. Both can be used with different settings for
158    * interpolated time without any side effect.</p>
159    * @return a deep copy of the instance, which can be used independently.
160    * @see #setInterpolatedTime(double)
161    * @exception MaxCountExceededException if the number of functions evaluations is exceeded
162    * during step finalization
163    */
164    StepInterpolator copy() throws MaxCountExceededException;
165 
166 }