001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 018 package org.apache.commons.math.ode.sampling; 019 020 import java.io.Externalizable; 021 022 import org.apache.commons.math.ode.DerivativeException; 023 import org.apache.commons.math.ode.FirstOrderIntegrator; 024 import org.apache.commons.math.ode.SecondOrderIntegrator; 025 026 /** This interface represents an interpolator over the last step 027 * during an ODE integration. 028 * 029 * <p>The various ODE integrators provide objects implementing this 030 * interface to the step handlers. These objects are often custom 031 * objects tightly bound to the integrator internal algorithms. The 032 * handlers can use these objects to retrieve the state vector at 033 * intermediate times between the previous and the current grid points 034 * (this feature is often called dense output).</p> 035 * <p>One important thing to note is that the step handlers may be so 036 * tightly bound to the integrators that they often share some internal 037 * state arrays. This imply that one should <em>never</em> use a direct 038 * reference to a step interpolator outside of the step handler, either 039 * for future use or for use in another thread. If such a need arise, the 040 * step interpolator <em>must</em> be copied using the dedicated 041 * {@link #copy()} method. 042 * </p> 043 * 044 * @see FirstOrderIntegrator 045 * @see SecondOrderIntegrator 046 * @see StepHandler 047 * @version $Revision: 782431 $ $Date: 2009-06-07 15:04:37 -0400 (Sun, 07 Jun 2009) $ 048 * @since 1.2 049 */ 050 051 public interface StepInterpolator 052 extends Externalizable { 053 054 /** 055 * Get the previous grid point time. 056 * @return previous grid point time 057 */ 058 public double getPreviousTime(); 059 060 /** 061 * Get the current grid point time. 062 * @return current grid point time 063 */ 064 public double getCurrentTime(); 065 066 /** 067 * Get the time of the interpolated point. 068 * If {@link #setInterpolatedTime} has not been called, it returns 069 * the current grid point time. 070 * @return interpolation point time 071 */ 072 public double getInterpolatedTime(); 073 074 /** 075 * Set the time of the interpolated point. 076 * <p>Setting the time outside of the current step is now allowed, but 077 * should be used with care since the accuracy of the interpolator will 078 * probably be very poor far from this step. This allowance has been 079 * added to simplify implementation of search algorithms near the 080 * step endpoints.</p> 081 * <p>Setting the time changes the instance internal state. If a 082 * specific state must be preserved, a copy of the instance must be 083 * created using {@link #copy()}.</p> 084 * @param time time of the interpolated point 085 */ 086 public void setInterpolatedTime(double time); 087 088 /** 089 * Get the state vector of the interpolated point. 090 * <p>The returned vector is a reference to a reused array, so 091 * it should not be modified and it should be copied if it needs 092 * to be preserved across several calls.</p> 093 * @return state vector at time {@link #getInterpolatedTime} 094 * @see #getInterpolatedDerivatives() 095 * @throws DerivativeException if this call induces an automatic 096 * step finalization that throws one 097 */ 098 public double[] getInterpolatedState() 099 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 }