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.math.ode.sampling;
19  
20  import java.io.Externalizable;
21  
22  import org.apache.commons.math.ode.DerivativeException;
23  import org.apache.commons.math.ode.FirstOrderIntegrator;
24  import org.apache.commons.math.ode.SecondOrderIntegrator;
25  
26  /** This interface represents an interpolator over the last step
27   * during an ODE integration.
28   *
29   * <p>The various ODE integrators provide objects implementing this
30   * interface to the step handlers. These objects are often custom
31   * objects tightly bound to the integrator internal algorithms. The
32   * handlers can use these objects to retrieve the state vector at
33   * intermediate times between the previous and the current grid points
34   * (this feature is often called dense output).</p>
35   * <p>One important thing to note is that the step handlers may be so
36   * tightly bound to the integrators that they often share some internal
37   * state arrays. This imply that one should <em>never</em> use a direct
38   * reference to a step interpolator outside of the step handler, either
39   * for future use or for use in another thread. If such a need arise, the
40   * step interpolator <em>must</em> be copied using the dedicated
41   * {@link #copy()} method.
42   * </p>
43   *
44   * @see FirstOrderIntegrator
45   * @see SecondOrderIntegrator
46   * @see StepHandler
47   * @version $Revision: 782431 $ $Date: 2009-06-07 15:04:37 -0400 (Sun, 07 Jun 2009) $
48   * @since 1.2
49   */
50  
51  public interface StepInterpolator
52    extends Externalizable {
53  
54    /**
55     * Get the previous grid point time.
56     * @return previous grid point time
57     */
58    public double getPreviousTime();
59      
60    /**
61     * Get the current grid point time.
62     * @return current grid point time
63     */
64    public double getCurrentTime();
65      
66    /**
67     * Get the time of the interpolated point.
68     * If {@link #setInterpolatedTime} has not been called, it returns
69     * the current grid point time.
70     * @return interpolation point time
71     */
72    public double getInterpolatedTime();
73      
74    /**
75     * Set the time of the interpolated point.
76     * <p>Setting the time outside of the current step is now allowed, but
77     * should be used with care since the accuracy of the interpolator will
78     * probably be very poor far from this step. This allowance has been
79     * added to simplify implementation of search algorithms near the
80     * step endpoints.</p>
81     * <p>Setting the time changes the instance internal state. If a
82     * specific state must be preserved, a copy of the instance must be
83     * created using {@link #copy()}.</p>
84     * @param time time of the interpolated point
85     */
86    public void setInterpolatedTime(double time);
87  
88    /**
89     * Get the state vector of the interpolated point.
90     * <p>The returned vector is a reference to a reused array, so
91     * it should not be modified and it should be copied if it needs
92     * to be preserved across several calls.</p>
93     * @return state vector at time {@link #getInterpolatedTime}
94     * @see #getInterpolatedDerivatives()
95     * @throws DerivativeException if this call induces an automatic
96     * step finalization that throws one
97     */
98    public double[] getInterpolatedState()
99        throws DerivativeException;
100 
101   /**
102    * Get the derivatives of the state vector of the interpolated point.
103    * <p>The returned vector is a reference to a reused array, so
104    * it should not be modified and it should be copied if it needs
105    * to be preserved across several calls.</p>
106    * @return derivatives of the state vector at time {@link #getInterpolatedTime}
107    * @see #getInterpolatedState()
108    * @throws DerivativeException if this call induces an automatic
109    * step finalization that throws one
110    * @since 2.0
111    */
112   public double[] getInterpolatedDerivatives()
113       throws DerivativeException;
114 
115   /** Check if the natural integration direction is forward.
116    * <p>This method provides the integration direction as specified by
117    * the integrator itself, it avoid some nasty problems in
118    * degenerated cases like null steps due to cancellation at step
119    * initialization, step control or discrete events
120    * triggering.</p>
121    * @return true if the integration variable (time) increases during
122    * integration
123    */
124   public boolean isForward();
125 
126   /** Copy the instance.
127    * <p>The copied instance is guaranteed to be independent from the
128    * original one. Both can be used with different settings for
129    * interpolated time without any side effect.</p>
130    * @return a deep copy of the instance, which can be used independently.
131    * @throws DerivativeException if this call induces an automatic
132    * step finalization that throws one
133    * @see #setInterpolatedTime(double)
134    */
135    public StepInterpolator copy() throws DerivativeException;
136 
137 }