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.jacobians; 019 020 import java.io.Externalizable; 021 022 import org.apache.commons.math.ode.DerivativeException; 023 024 /** This interface represents an interpolator over the last step 025 * during an ODE integration. 026 * 027 * <p>The various ODE integrators provide objects implementing this 028 * interface to the step handlers. These objects are often custom 029 * objects tightly bound to the integrator internal algorithms. The 030 * handlers can use these objects to retrieve the state vector at 031 * intermediate times between the previous and the current grid points 032 * (this feature is often called dense output).</p> 033 * <p>One important thing to note is that the step handlers may be so 034 * tightly bound to the integrators that they often share some internal 035 * state arrays. This imply that one should <em>never</em> use a direct 036 * reference to a step interpolator outside of the step handler, either 037 * for future use or for use in another thread. If such a need arise, the 038 * step interpolator <em>must</em> be copied using the dedicated 039 * {@link #copy()} method. 040 * </p> 041 * 042 * @see FirstOrderIntegratorWithJacobians 043 * @see StepHandlerWithJacobians 044 * @version $Revision: 918702 $ $Date: 2010-03-03 16:28:16 -0500 (Wed, 03 Mar 2010) $ 045 * @since 2.1 046 */ 047 048 public interface StepInterpolatorWithJacobians extends Externalizable { 049 050 /** 051 * Get the previous grid point time. 052 * @return previous grid point time 053 */ 054 double getPreviousTime(); 055 056 /** 057 * Get the current grid point time. 058 * @return current grid point time 059 */ 060 double getCurrentTime(); 061 062 /** 063 * Get the time of the interpolated point. 064 * If {@link #setInterpolatedTime} has not been called, it returns 065 * the current grid point time. 066 * @return interpolation point time 067 */ 068 double getInterpolatedTime(); 069 070 /** 071 * Set the time of the interpolated point. 072 * <p>Setting the time outside of the current step is now allowed, but 073 * should be used with care since the accuracy of the interpolator will 074 * probably be very poor far from this step. This allowance has been 075 * added to simplify implementation of search algorithms near the 076 * step endpoints.</p> 077 * <p>Setting the time changes the instance internal state. If a 078 * specific state must be preserved, a copy of the instance must be 079 * created using {@link #copy()}.</p> 080 * @param time time of the interpolated point 081 */ 082 void setInterpolatedTime(double time); 083 084 /** 085 * Get the state vector of the interpolated point. 086 * <p>The returned vector is a reference to a reused array, so 087 * it should not be modified and it should be copied if it needs 088 * to be preserved across several calls.</p> 089 * @return state vector at time {@link #getInterpolatedTime} 090 * @see #getInterpolatedYDot() 091 * @throws DerivativeException if this call induces an automatic 092 * step finalization that throws one 093 */ 094 double[] getInterpolatedY() throws DerivativeException; 095 096 /** 097 * Get the partial derivatives of the state vector with respect to 098 * the initial state of the interpolated point. 099 * <p>The returned vector is a reference to a reused array, so 100 * it should not be modified and it should be copied if it needs 101 * to be preserved across several calls.</p> 102 * @return partial derivatives of the state vector with respect to 103 * the initial state at time {@link #getInterpolatedTime} 104 * @see #getInterpolatedY() 105 * @throws DerivativeException if this call induces an automatic 106 * step finalization that throws one 107 */ 108 double[][] getInterpolatedDyDy0() throws DerivativeException; 109 110 /** 111 * Get the partial derivatives of the state vector with respect to 112 * the ODE parameters of the interpolated point. 113 * <p>The returned vector is a reference to a reused array, so 114 * it should not be modified and it should be copied if it needs 115 * to be preserved across several calls.</p> 116 * @return partial derivatives of the state vector with respect to 117 * the ODE parameters at time {@link #getInterpolatedTime} 118 * @see #getInterpolatedY() 119 * @throws DerivativeException if this call induces an automatic 120 * step finalization that throws one 121 */ 122 double[][] getInterpolatedDyDp() throws DerivativeException; 123 124 /** 125 * Get the time derivatives of the state vector of the interpolated point. 126 * <p>The returned vector is a reference to a reused array, so 127 * it should not be modified and it should be copied if it needs 128 * to be preserved across several calls.</p> 129 * @return derivatives of the state vector at time {@link #getInterpolatedTime} 130 * @see #getInterpolatedY() 131 * @throws DerivativeException if this call induces an automatic 132 * step finalization that throws one 133 */ 134 double[] getInterpolatedYDot() throws DerivativeException; 135 136 /** 137 * Get the time derivatives of the jacobian of the state vector 138 * with respect to the initial state of the interpolated point. 139 * <p>The returned vector is a reference to a reused array, so 140 * it should not be modified and it should be copied if it needs 141 * to be preserved across several calls.</p> 142 * @return time derivatives of the jacobian of the state vector 143 * with respect to the initial state at time {@link #getInterpolatedTime} 144 * @see #getInterpolatedY() 145 * @throws DerivativeException if this call induces an automatic 146 * step finalization that throws one 147 */ 148 double[][] getInterpolatedDyDy0Dot() throws DerivativeException; 149 150 /** 151 * Get the time derivatives of the jacobian of the state vector 152 * with respect to the ODE parameters of the interpolated point. 153 * <p>The returned vector is a reference to a reused array, so 154 * it should not be modified and it should be copied if it needs 155 * to be preserved across several calls.</p> 156 * @return time derivatives of the jacobian of the state vector 157 * with respect to the ODE parameters at time {@link #getInterpolatedTime} 158 * @see #getInterpolatedY() 159 * @throws DerivativeException if this call induces an automatic 160 * step finalization that throws one 161 */ 162 double[][] getInterpolatedDyDpDot() throws DerivativeException; 163 164 /** Check if the natural integration direction is forward. 165 * <p>This method provides the integration direction as specified by 166 * the integrator itself, it avoid some nasty problems in 167 * degenerated cases like null steps due to cancellation at step 168 * initialization, step control or discrete events 169 * triggering.</p> 170 * @return true if the integration variable (time) increases during 171 * integration 172 */ 173 boolean isForward(); 174 175 /** Copy the instance. 176 * <p>The copied instance is guaranteed to be independent from the 177 * original one. Both can be used with different settings for 178 * interpolated time without any side effect.</p> 179 * @return a deep copy of the instance, which can be used independently. 180 * @throws DerivativeException if this call induces an automatic 181 * step finalization that throws one 182 * @see #setInterpolatedTime(double) 183 */ 184 StepInterpolatorWithJacobians copy() throws DerivativeException; 185 186 }