Repository: commons-math Updated Branches: refs/heads/master 25aa4bd36 -> f8e6bc8ec
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 :-( Project: http://git-wip-us.apache.org/repos/asf/commons-math/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-math/commit/f8e6bc8e Tree: http://git-wip-us.apache.org/repos/asf/commons-math/tree/f8e6bc8e Diff: http://git-wip-us.apache.org/repos/asf/commons-math/diff/f8e6bc8e Branch: refs/heads/master Commit: f8e6bc8ec72fd02cde8c705ca17609c76a07d3b8 Parents: 25aa4bd Author: Luc Maisonobe <l...@apache.org> Authored: Wed Oct 22 21:36:40 2014 +0200 Committer: Luc Maisonobe <l...@apache.org> Committed: Wed Oct 22 21:36:40 2014 +0200 ---------------------------------------------------------------------- .../math3/ode/ContinuousOutputModel.java | 32 +++++++++++++++++--- .../math3/ode/sampling/StepInterpolator.java | 28 +++++++++++++---- 2 files changed, 49 insertions(+), 11 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-math/blob/f8e6bc8e/src/main/java/org/apache/commons/math3/ode/ContinuousOutputModel.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/math3/ode/ContinuousOutputModel.java b/src/main/java/org/apache/commons/math3/ode/ContinuousOutputModel.java index d9f6192..6d324d1 100644 --- a/src/main/java/org/apache/commons/math3/ode/ContinuousOutputModel.java +++ b/src/main/java/org/apache/commons/math3/ode/ContinuousOutputModel.java @@ -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 http://git-wip-us.apache.org/repos/asf/commons-math/blob/f8e6bc8e/src/main/java/org/apache/commons/math3/ode/sampling/StepInterpolator.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/math3/ode/sampling/StepInterpolator.java b/src/main/java/org/apache/commons/math3/ode/sampling/StepInterpolator.java index 44e77eb..5d27bf2 100644 --- a/src/main/java/org/apache/commons/math3/ode/sampling/StepInterpolator.java +++ b/src/main/java/org/apache/commons/math3/ode/sampling/StepInterpolator.java @@ -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)
