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;
19  
20  import java.io.Externalizable;
21  
22  /** This interface represents an interpolator over the last step
23   * during an ODE integration.
24   *
25   * <p>The various ODE integrators provide objects implementing this
26   * interface to the step handlers. These objects are often custom
27   * objects tightly bound to the integrator internal algorithms. The
28   * handlers can use these objects to retrieve the state vector at
29   * intermediate times between the previous and the current grid points
30   * (this feature is often called dense output).</p>
31   *
32   * @see FirstOrderIntegrator
33   * @see SecondOrderIntegrator
34   * @see StepHandler
35   * @version $Revision: 620312 $ $Date: 2008-02-10 12:28:59 -0700 (Sun, 10 Feb 2008) $
36   * @since 1.2
37   */
38  
39  public interface StepInterpolator
40    extends Externalizable {
41  
42    /**
43     * Get the previous grid point time.
44     * @return previous grid point time
45     */
46    public double getPreviousTime();
47      
48    /**
49     * Get the current grid point time.
50     * @return current grid point time
51     */
52    public double getCurrentTime();
53      
54    /**
55     * Get the time of the interpolated point.
56     * If {@link #setInterpolatedTime} has not been called, it returns
57     * the current grid point time.
58     * @return interpolation point time
59     */
60    public double getInterpolatedTime();
61      
62    /**
63     * Set the time of the interpolated point.
64     * <p>Setting the time outside of the current step is now allowed, but
65     * should be used with care since the accuracy of the interpolator will
66     * probably be very poor far from this step. This allowance has been
67     * added to simplify implementation of search algorithms near the
68     * step endpoints.</p>
69     * <p>Setting the time changes the instance internal state. If a
70     * specific state must be preserved, a copy of the instance must be
71     * created using {@link #copy()}.</p>
72     * @param time time of the interpolated point
73     * @throws DerivativeException if this call induces an automatic
74     * step finalization that throws one
75     */
76    public void setInterpolatedTime(double time)
77      throws DerivativeException;
78  
79    /**
80     * Get the state vector of the interpolated point.
81     * @return state vector at time {@link #getInterpolatedTime}
82     */
83    public double[] getInterpolatedState();
84  
85    /** Check if the natural integration direction is forward.
86     * <p>This method provides the integration direction as specified by
87     * the integrator itself, it avoid some nasty problems in
88     * degenerated cases like null steps due to cancellation at step
89     * initialization, step control or switching function
90     * triggering.</p>
91     * @return true if the integration variable (time) increases during
92     * integration
93     */
94    public boolean isForward();
95  
96    /** Copy the instance.
97     * <p>The copied instance is guaranteed to be independent from the
98     * original one. Both can be used with different settings for
99     * interpolated time without any side effect.</p>
100    * @return a deep copy of the instance, which can be used independently.
101    * @throws DerivativeException if this call induces an automatic
102    * step finalization that throws one
103    * @see #setInterpolatedTime(double)
104    */
105    public StepInterpolator copy() throws DerivativeException;
106 
107 }