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.jacobians; 19 20 import java.io.Externalizable; 21 22 import org.apache.commons.math.ode.DerivativeException; 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 FirstOrderIntegratorWithJacobians 43 * @see StepHandlerWithJacobians 44 * @version $Revision: 1073158 $ $Date: 2011-02-21 22:46:52 +0100 (lun. 21 févr. 2011) $ 45 * @since 2.1 46 * @deprecated as of 2.2 the complete package is deprecated, it will be replaced 47 * in 3.0 by a completely rewritten implementation 48 */ 49 @Deprecated 50 public interface StepInterpolatorWithJacobians extends Externalizable { 51 52 /** 53 * Get the previous grid point time. 54 * @return previous grid point time 55 */ getPreviousTime()56 double getPreviousTime(); 57 58 /** 59 * Get the current grid point time. 60 * @return current grid point time 61 */ getCurrentTime()62 double getCurrentTime(); 63 64 /** 65 * Get the time of the interpolated point. 66 * If {@link #setInterpolatedTime} has not been called, it returns 67 * the current grid point time. 68 * @return interpolation point time 69 */ getInterpolatedTime()70 double getInterpolatedTime(); 71 72 /** 73 * Set the time of the interpolated point. 74 * <p>Setting the time outside of the current step is now allowed, but 75 * should be used with care since the accuracy of the interpolator will 76 * probably be very poor far from this step. This allowance has been 77 * added to simplify implementation of search algorithms near the 78 * step endpoints.</p> 79 * <p>Setting the time changes the instance internal state. If a 80 * specific state must be preserved, a copy of the instance must be 81 * created using {@link #copy()}.</p> 82 * @param time time of the interpolated point 83 */ setInterpolatedTime(double time)84 void setInterpolatedTime(double time); 85 86 /** 87 * Get the state vector of the interpolated point. 88 * <p>The returned vector is a reference to a reused array, so 89 * it should not be modified and it should be copied if it needs 90 * to be preserved across several calls.</p> 91 * @return state vector at time {@link #getInterpolatedTime} 92 * @see #getInterpolatedYDot() 93 * @throws DerivativeException if this call induces an automatic 94 * step finalization that throws one 95 */ getInterpolatedY()96 double[] getInterpolatedY() throws DerivativeException; 97 98 /** 99 * Get the partial derivatives of the state vector with respect to 100 * the initial state of the interpolated point. 101 * <p>The returned vector is a reference to a reused array, so 102 * it should not be modified and it should be copied if it needs 103 * to be preserved across several calls.</p> 104 * @return partial derivatives of the state vector with respect to 105 * the initial state at time {@link #getInterpolatedTime} 106 * @see #getInterpolatedY() 107 * @throws DerivativeException if this call induces an automatic 108 * step finalization that throws one 109 */ getInterpolatedDyDy0()110 double[][] getInterpolatedDyDy0() throws DerivativeException; 111 112 /** 113 * Get the partial derivatives of the state vector with respect to 114 * the ODE parameters of the interpolated point. 115 * <p>The returned vector is a reference to a reused array, so 116 * it should not be modified and it should be copied if it needs 117 * to be preserved across several calls.</p> 118 * @return partial derivatives of the state vector with respect to 119 * the ODE parameters at time {@link #getInterpolatedTime} 120 * @see #getInterpolatedY() 121 * @throws DerivativeException if this call induces an automatic 122 * step finalization that throws one 123 */ getInterpolatedDyDp()124 double[][] getInterpolatedDyDp() throws DerivativeException; 125 126 /** 127 * Get the time derivatives of the state vector of the interpolated point. 128 * <p>The returned vector is a reference to a reused array, so 129 * it should not be modified and it should be copied if it needs 130 * to be preserved across several calls.</p> 131 * @return derivatives of the state vector at time {@link #getInterpolatedTime} 132 * @see #getInterpolatedY() 133 * @throws DerivativeException if this call induces an automatic 134 * step finalization that throws one 135 */ getInterpolatedYDot()136 double[] getInterpolatedYDot() throws DerivativeException; 137 138 /** 139 * Get the time derivatives of the jacobian of the state vector 140 * with respect to the initial state of the interpolated point. 141 * <p>The returned vector is a reference to a reused array, so 142 * it should not be modified and it should be copied if it needs 143 * to be preserved across several calls.</p> 144 * @return time derivatives of the jacobian of the state vector 145 * with respect to the initial state at time {@link #getInterpolatedTime} 146 * @see #getInterpolatedY() 147 * @throws DerivativeException if this call induces an automatic 148 * step finalization that throws one 149 */ getInterpolatedDyDy0Dot()150 double[][] getInterpolatedDyDy0Dot() throws DerivativeException; 151 152 /** 153 * Get the time derivatives of the jacobian of the state vector 154 * with respect to the ODE parameters of the interpolated point. 155 * <p>The returned vector is a reference to a reused array, so 156 * it should not be modified and it should be copied if it needs 157 * to be preserved across several calls.</p> 158 * @return time derivatives of the jacobian of the state vector 159 * with respect to the ODE parameters at time {@link #getInterpolatedTime} 160 * @see #getInterpolatedY() 161 * @throws DerivativeException if this call induces an automatic 162 * step finalization that throws one 163 */ getInterpolatedDyDpDot()164 double[][] getInterpolatedDyDpDot() throws DerivativeException; 165 166 /** Check if the natural integration direction is forward. 167 * <p>This method provides the integration direction as specified by 168 * the integrator itself, it avoid some nasty problems in 169 * degenerated cases like null steps due to cancellation at step 170 * initialization, step control or discrete events 171 * triggering.</p> 172 * @return true if the integration variable (time) increases during 173 * integration 174 */ isForward()175 boolean isForward(); 176 177 /** Copy the instance. 178 * <p>The copied instance is guaranteed to be independent from the 179 * original one. Both can be used with different settings for 180 * interpolated time without any side effect.</p> 181 * @return a deep copy of the instance, which can be used independently. 182 * @throws DerivativeException if this call induces an automatic 183 * step finalization that throws one 184 * @see #setInterpolatedTime(double) 185 */ copy()186 StepInterpolatorWithJacobians copy() throws DerivativeException; 187 188 } 189