Apache
/
commons-math
mirror of https://github.com/apache/commons-math.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improved javadoc for ContinuousOutputModel and StepInterpolator. 

The fact the arrays are reused is stated more clearly, as weel as the
fact changing the time changes the array content.

Yes, it is a bad design, we should change it in the next major version
to allocate fresh new arrays :-(
This commit is contained in:
Luc Maisonobe 2014-10-22 21:36:40 +02:00
parent 25aa4bd366
commit f8e6bc8ec7
2 changed files with 49 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
src/main/java/org/apache/commons/math3/ode/ContinuousOutputModel.java
View File

@ -233,12 +233,19 @@ public class ContinuousOutputModel
* integration is over because some internal variables are set only
* once the last step has been handled.</p>
* <p>Setting the time outside of the integration interval is now
* allowed (it was not allowed up to version 5.9 of Mantissa), but
* should be used with care since the accuracy of the interpolator
* will probably be very poor far from this interval. This allowance
* has been added to simplify implementation of search algorithms
* near the interval endpoints.</p>
* allowed, but should be used with care since the accuracy of the
* interpolator will probably be very poor far from this interval.
* This allowance has been added to simplify implementation of search
* algorithms near the interval endpoints.</p>
* <p>Note that each time this method is called, the internal arrays
* returned in {@link #getInterpolatedState()}, {@link
* #getInterpolatedDerivatives()} and {@link #getInterpolatedSecondaryState(int)}
* <em>will</em> be overwritten. So if their content must be preserved
* across several calls, user must copy them.</p>
* @param time time of the interpolated point
* @see #getInterpolatedState()
* @see #getInterpolatedDerivatives()
* @see #getInterpolatedSecondaryState(int)
*/
public void setInterpolatedTime(final double time) {
@ -330,8 +337,13 @@ public class ContinuousOutputModel
/**
* Get the state vector of the interpolated point.
* <p>The returned vector is a reference to a reused array, so
* it should not be modified and it should be copied if it needs
* to be preserved across several calls to the associated
* {@link #setInterpolatedTime(double)} method.</p>
* @return state vector at time {@link #getInterpolatedTime}
* @exception MaxCountExceededException if the number of functions evaluations is exceeded
* @see #setInterpolatedTime(double)
* @see #getInterpolatedDerivatives()
* @see #getInterpolatedSecondaryState(int)
*/
@ -341,8 +353,13 @@ public class ContinuousOutputModel
/**
* Get the derivatives of the state vector of the interpolated point.
* <p>The returned vector is a reference to a reused array, so
* it should not be modified and it should be copied if it needs
* to be preserved across several calls to the associated
* {@link #setInterpolatedTime(double)} method.</p>
* @return derivatives of the state vector at time {@link #getInterpolatedTime}
* @exception MaxCountExceededException if the number of functions evaluations is exceeded
* @see #setInterpolatedTime(double)
* @see #getInterpolatedState()
* @see #getInterpolatedSecondaryState(int)
* @since 3.4
@ -352,11 +369,16 @@ public class ContinuousOutputModel
}
/** Get the interpolated secondary state corresponding to the secondary equations.
* <p>The returned vector is a reference to a reused array, so
* it should not be modified and it should be copied if it needs
* to be preserved across several calls to the associated
* {@link #setInterpolatedTime(double)} method.</p>
* @param secondaryStateIndex index of the secondary set, as returned by {@link
* org.apache.commons.math3.ode.ExpandableStatefulODE#addSecondaryEquations(
* org.apache.commons.math3.ode.SecondaryEquations)
* ExpandableStatefulODE.addSecondaryEquations(SecondaryEquations)}
* @return interpolated secondary state at the current interpolation date
* @see #setInterpolatedTime(double)
* @see #getInterpolatedState()
* @see #getInterpolatedDerivatives()
* @since 3.2

28
src/main/java/org/apache/commons/math3/ode/sampling/StepInterpolator.java
View File

@ -74,10 +74,17 @@ public interface StepInterpolator extends Externalizable {
* probably be very poor far from this step. This allowance has been
* added to simplify implementation of search algorithms near the
* step endpoints.</p>
* <p>Setting the time changes the instance internal state. If a
* specific state must be preserved, a copy of the instance must be
* created using {@link #copy()}.</p>
* <p>Setting the time changes the instance internal state. This includes
* the internal arrays returned in {@link #getInterpolatedState()},
* {@link #getInterpolatedDerivatives()}, {@link
* #getInterpolatedSecondaryState(int)} and {@link
* #getInterpolatedSecondaryDerivatives(int)}. So if their content must be preserved
* across several calls, user must copy them.</p>
* @param time time of the interpolated point
* @see #getInterpolatedState()
* @see #getInterpolatedDerivatives()
* @see #getInterpolatedSecondaryState(int)
* @see #getInterpolatedSecondaryDerivatives(int)
*/
void setInterpolatedTime(double time);
@ -85,9 +92,13 @@ public interface StepInterpolator extends Externalizable {
* Get the state vector of the interpolated point.
* <p>The returned vector is a reference to a reused array, so
* it should not be modified and it should be copied if it needs
* to be preserved across several calls.</p>
* to be preserved across several calls to the associated
* {@link #setInterpolatedTime(double)} method.</p>
* @return state vector at time {@link #getInterpolatedTime}
* @see #getInterpolatedDerivatives()
* @see #getInterpolatedSecondaryState(int)
* @see #getInterpolatedSecondaryDerivatives(int)
* @see #setInterpolatedTime(double)
* @exception MaxCountExceededException if the number of functions evaluations is exceeded
*/
double[] getInterpolatedState() throws MaxCountExceededException;
@ -96,9 +107,13 @@ public interface StepInterpolator extends Externalizable {
* Get the derivatives of the state vector of the interpolated point.
* <p>The returned vector is a reference to a reused array, so
* it should not be modified and it should be copied if it needs
* to be preserved across several calls.</p>
* to be preserved across several calls to the associated
* {@link #setInterpolatedTime(double)} method.</p>
* @return derivatives of the state vector at time {@link #getInterpolatedTime}
* @see #getInterpolatedState()
* @see #getInterpolatedSecondaryState(int)
* @see #getInterpolatedSecondaryDerivatives(int)
* @see #setInterpolatedTime(double)
* @since 2.0
* @exception MaxCountExceededException if the number of functions evaluations is exceeded
*/
@ -107,7 +122,8 @@ public interface StepInterpolator extends Externalizable {
/** Get the interpolated secondary state corresponding to the secondary equations.
* <p>The returned vector is a reference to a reused array, so
* it should not be modified and it should be copied if it needs
* to be preserved across several calls.</p>
* to be preserved across several calls to the associated
* {@link #setInterpolatedTime(double)} method.</p>
* @param index index of the secondary set, as returned by {@link
* org.apache.commons.math3.ode.ExpandableStatefulODE#addSecondaryEquations(
* org.apache.commons.math3.ode.SecondaryEquations)