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 018package org.apache.commons.math3.ode.sampling; 019 020import java.io.Externalizable; 021 022import org.apache.commons.math3.exception.MaxCountExceededException; 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 org.apache.commons.math3.ode.FirstOrderIntegrator 043 * @see org.apache.commons.math3.ode.SecondOrderIntegrator 044 * @see StepHandler 045 * @since 1.2 046 */ 047 048public interface StepInterpolator 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. This includes 078 * the internal arrays returned in {@link #getInterpolatedState()}, 079 * {@link #getInterpolatedDerivatives()}, {@link 080 * #getInterpolatedSecondaryState(int)} and {@link 081 * #getInterpolatedSecondaryDerivatives(int)}. So if their content must be preserved 082 * across several calls, user must copy them.</p> 083 * @param time time of the interpolated point 084 * @see #getInterpolatedState() 085 * @see #getInterpolatedDerivatives() 086 * @see #getInterpolatedSecondaryState(int) 087 * @see #getInterpolatedSecondaryDerivatives(int) 088 */ 089 void setInterpolatedTime(double time); 090 091 /** 092 * Get the state vector of the interpolated point. 093 * <p>The returned vector is a reference to a reused array, so 094 * it should not be modified and it should be copied if it needs 095 * to be preserved across several calls to the associated 096 * {@link #setInterpolatedTime(double)} method.</p> 097 * @return state vector at time {@link #getInterpolatedTime} 098 * @see #getInterpolatedDerivatives() 099 * @see #getInterpolatedSecondaryState(int) 100 * @see #getInterpolatedSecondaryDerivatives(int) 101 * @see #setInterpolatedTime(double) 102 * @exception MaxCountExceededException if the number of functions evaluations is exceeded 103 */ 104 double[] getInterpolatedState() throws MaxCountExceededException; 105 106 /** 107 * Get the derivatives of the state vector of the interpolated point. 108 * <p>The returned vector is a reference to a reused array, so 109 * it should not be modified and it should be copied if it needs 110 * to be preserved across several calls to the associated 111 * {@link #setInterpolatedTime(double)} method.</p> 112 * @return derivatives of the state vector at time {@link #getInterpolatedTime} 113 * @see #getInterpolatedState() 114 * @see #getInterpolatedSecondaryState(int) 115 * @see #getInterpolatedSecondaryDerivatives(int) 116 * @see #setInterpolatedTime(double) 117 * @since 2.0 118 * @exception MaxCountExceededException if the number of functions evaluations is exceeded 119 */ 120 double[] getInterpolatedDerivatives() throws MaxCountExceededException; 121 122 /** Get the interpolated secondary state corresponding to the secondary equations. 123 * <p>The returned vector is a reference to a reused array, so 124 * it should not be modified and it should be copied if it needs 125 * to be preserved across several calls to the associated 126 * {@link #setInterpolatedTime(double)} method.</p> 127 * @param index index of the secondary set, as returned by {@link 128 * org.apache.commons.math3.ode.ExpandableStatefulODE#addSecondaryEquations( 129 * org.apache.commons.math3.ode.SecondaryEquations) 130 * ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)} 131 * @return interpolated secondary state at the current interpolation date 132 * @see #getInterpolatedState() 133 * @see #getInterpolatedDerivatives() 134 * @see #getInterpolatedSecondaryDerivatives(int) 135 * @see #setInterpolatedTime(double) 136 * @since 3.0 137 * @exception MaxCountExceededException if the number of functions evaluations is exceeded 138 */ 139 double[] getInterpolatedSecondaryState(int index) throws MaxCountExceededException; 140 141 /** Get the interpolated secondary derivatives corresponding to the secondary equations. 142 * <p>The returned vector is a reference to a reused array, so 143 * it should not be modified and it should be copied if it needs 144 * to be preserved across several calls.</p> 145 * @param index index of the secondary set, as returned by {@link 146 * org.apache.commons.math3.ode.ExpandableStatefulODE#addSecondaryEquations( 147 * org.apache.commons.math3.ode.SecondaryEquations) 148 * ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)} 149 * @return interpolated secondary derivatives at the current interpolation date 150 * @see #getInterpolatedState() 151 * @see #getInterpolatedDerivatives() 152 * @see #getInterpolatedSecondaryState(int) 153 * @see #setInterpolatedTime(double) 154 * @since 3.0 155 * @exception MaxCountExceededException if the number of functions evaluations is exceeded 156 */ 157 double[] getInterpolatedSecondaryDerivatives(int index) throws MaxCountExceededException; 158 159 /** Check if the natural integration direction is forward. 160 * <p>This method provides the integration direction as specified by 161 * the integrator itself, it avoid some nasty problems in 162 * degenerated cases like null steps due to cancellation at step 163 * initialization, step control or discrete events 164 * triggering.</p> 165 * @return true if the integration variable (time) increases during 166 * integration 167 */ 168 boolean isForward(); 169 170 /** Copy the instance. 171 * <p>The copied instance is guaranteed to be independent from the 172 * original one. Both can be used with different settings for 173 * interpolated time without any side effect.</p> 174 * @return a deep copy of the instance, which can be used independently. 175 * @see #setInterpolatedTime(double) 176 * @exception MaxCountExceededException if the number of functions evaluations is exceeded 177 * during step finalization 178 */ 179 StepInterpolator copy() throws MaxCountExceededException; 180 181}