Repository: commons-math Updated Branches: refs/heads/MATH_3_X 67181947f -> 523774aa8
Javadoc fixes. Project: http://git-wip-us.apache.org/repos/asf/commons-math/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-math/commit/523774aa Tree: http://git-wip-us.apache.org/repos/asf/commons-math/tree/523774aa Diff: http://git-wip-us.apache.org/repos/asf/commons-math/diff/523774aa Branch: refs/heads/MATH_3_X Commit: 523774aa8b6e722340ee610a9c8ab32ba9170f50 Parents: 6718194 Author: Phil Steitz <phil.ste...@gmail.com> Authored: Fri Dec 25 14:03:57 2015 -0700 Committer: Phil Steitz <phil.ste...@gmail.com> Committed: Fri Dec 25 14:03:57 2015 -0700 ---------------------------------------------------------------------- .../org/apache/commons/math3/FieldElement.java | 2 +- .../apache/commons/math3/RealFieldElement.java | 6 +-- .../commons/math3/analysis/FunctionUtils.java | 47 ++++++++++++-------- .../analysis/RealFieldUnivariateFunction.java | 8 ++-- .../math3/analysis/UnivariateFunction.java | 8 ++-- .../analysis/differentiation/DSCompiler.java | 14 +++--- .../differentiation/DerivativeStructure.java | 6 +-- .../FiniteDifferencesDifferentiator.java | 7 +-- .../differentiation/SparseGradient.java | 2 +- .../math3/analysis/function/StepFunction.java | 9 ++-- 10 files changed, 59 insertions(+), 50 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-math/blob/523774aa/src/main/java/org/apache/commons/math3/FieldElement.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/math3/FieldElement.java b/src/main/java/org/apache/commons/math3/FieldElement.java index 58af0db..bd286ef 100644 --- a/src/main/java/org/apache/commons/math3/FieldElement.java +++ b/src/main/java/org/apache/commons/math3/FieldElement.java @@ -66,7 +66,7 @@ public interface FieldElement<T> { T multiply(T a) throws NullArgumentException; /** Compute this ÷ a. - * @param a element to add + * @param a element to divide by * @return a new element representing this ÷ a * @throws NullArgumentException if {@code a} is {@code null}. * @throws MathArithmeticException if {@code a} is zero http://git-wip-us.apache.org/repos/asf/commons-math/blob/523774aa/src/main/java/org/apache/commons/math3/RealFieldElement.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/math3/RealFieldElement.java b/src/main/java/org/apache/commons/math3/RealFieldElement.java index 0e54ba1..e3656d4 100644 --- a/src/main/java/org/apache/commons/math3/RealFieldElement.java +++ b/src/main/java/org/apache/commons/math3/RealFieldElement.java @@ -52,7 +52,7 @@ public interface RealFieldElement<T> extends FieldElement<T> { /** '÷' operator. * @param a right hand side parameter of the operator - * @return this÷s;a + * @return this÷a */ T divide(double a); @@ -88,7 +88,7 @@ public interface RealFieldElement<T> extends FieldElement<T> { T floor(); /** Get the whole number that is the nearest to the instance, or the even one if x is exactly half way between two integers. - * @return a double number r such that r is an integer r - 0.5 <= this <= r + 0.5 + * @return a double number r such that r is an integer r - 0.5 ≤ this ≤ r + 0.5 */ T rint(); @@ -130,7 +130,7 @@ public interface RealFieldElement<T> extends FieldElement<T> { /** * Returns the hypotenuse of a triangle with sides {@code this} and {@code y} - * - sqrt(<i>this</i><sup>2</sup> +<i>y</i><sup>2</sup>)<br/> + * - sqrt(<i>this</i><sup>2</sup> +<i>y</i><sup>2</sup>) * avoiding intermediate overflow or underflow. * * <ul> http://git-wip-us.apache.org/repos/asf/commons-math/blob/523774aa/src/main/java/org/apache/commons/math3/analysis/FunctionUtils.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/math3/analysis/FunctionUtils.java b/src/main/java/org/apache/commons/math3/analysis/FunctionUtils.java index d7f9d70..ae68ba1 100644 --- a/src/main/java/org/apache/commons/math3/analysis/FunctionUtils.java +++ b/src/main/java/org/apache/commons/math3/analysis/FunctionUtils.java @@ -40,9 +40,9 @@ public class FunctionUtils { /** * Composes functions. - * <br/> + * <p> * The functions in the argument list are composed sequentially, in the - * given order. For example, compose(f1,f2,f3) acts like f1(f2(f3(x))). + * given order. For example, compose(f1,f2,f3) acts like f1(f2(f3(x))).</p> * * @param f List of functions. * @return the composite function. @@ -62,9 +62,9 @@ public class FunctionUtils { /** * Composes functions. - * <br/> + * <p> * The functions in the argument list are composed sequentially, in the - * given order. For example, compose(f1,f2,f3) acts like f1(f2(f3(x))). + * given order. For example, compose(f1,f2,f3) acts like f1(f2(f3(x))).</p> * * @param f List of functions. * @return the composite function. @@ -96,9 +96,9 @@ public class FunctionUtils { /** * Composes functions. - * <br/> + * <p> * The functions in the argument list are composed sequentially, in the - * given order. For example, compose(f1,f2,f3) acts like f1(f2(f3(x))). + * given order. For example, compose(f1,f2,f3) acts like f1(f2(f3(x))).</p> * * @param f List of functions. * @return the composite function. @@ -314,8 +314,8 @@ public class FunctionUtils { } /** - * Returns the univariate function <br/> - * {@code h(x) = combiner(f(x), g(x))}. + * Returns the univariate function + * {@code h(x) = combiner(f(x), g(x)).} * * @param combiner Combiner function. * @param f Function. @@ -376,7 +376,7 @@ public class FunctionUtils { * Creates a unary function by fixing the first argument of a binary function. * * @param f Binary function. - * @param fixed Value to which the first argument of {@code f} is set. + * @param fixed value to which the first argument of {@code f} is set. * @return the unary function h(x) = f(fixed, x) */ public static UnivariateFunction fix1stArgument(final BivariateFunction f, @@ -392,7 +392,7 @@ public class FunctionUtils { * Creates a unary function by fixing the second argument of a binary function. * * @param f Binary function. - * @param fixed Value to which the second argument of {@code f} is set. + * @param fixed value to which the second argument of {@code f} is set. * @return the unary function h(x) = f(x, fixed) */ public static UnivariateFunction fix2ndArgument(final BivariateFunction f, @@ -407,10 +407,10 @@ public class FunctionUtils { /** * Samples the specified univariate real function on the specified interval. - * <br/> + * <p> * The interval is divided equally into {@code n} sections and sample points * are taken from {@code min} to {@code max - (max - min) / n}; therefore - * {@code f} is not sampled at the upper bound {@code max}. + * {@code f} is not sampled at the upper bound {@code max}.</p> * * @param f Function to be sampled * @param min Lower bound of the interval (included). @@ -442,7 +442,9 @@ public class FunctionUtils { return s; } - /** Convert a {@link UnivariateDifferentiableFunction} into a {@link DifferentiableUnivariateFunction}. + /** + * Convert a {@link UnivariateDifferentiableFunction} into a {@link DifferentiableUnivariateFunction}. + * * @param f function to convert * @return converted function * @deprecated this conversion method is temporary in version 3.1, as the {@link @@ -470,10 +472,11 @@ public class FunctionUtils { }; } - /** Convert a {@link DifferentiableUnivariateFunction} into a {@link UnivariateDifferentiableFunction}. + /** + * Convert a {@link DifferentiableUnivariateFunction} into a {@link UnivariateDifferentiableFunction}. * <p> * Note that the converted function is able to handle {@link DerivativeStructure} up to order one. - * If the function is called with higher order, a {@link NumberIsTooLargeException} will be thrown. + * If the function is called with higher order, a {@link NumberIsTooLargeException} is thrown. * </p> * @param f function to convert * @return converted function @@ -518,7 +521,9 @@ public class FunctionUtils { }; } - /** Convert a {@link MultivariateDifferentiableFunction} into a {@link DifferentiableMultivariateFunction}. + /** + * Convert a {@link MultivariateDifferentiableFunction} into a {@link DifferentiableMultivariateFunction}. + * * @param f function to convert * @return converted function * @deprecated this conversion method is temporary in version 3.1, as the {@link @@ -592,7 +597,8 @@ public class FunctionUtils { }; } - /** Convert a {@link DifferentiableMultivariateFunction} into a {@link MultivariateDifferentiableFunction}. + /** + * Convert a {@link DifferentiableMultivariateFunction} into a {@link MultivariateDifferentiableFunction}. * <p> * Note that the converted function is able to handle {@link DerivativeStructure} elements * that all have the same number of free parameters and order, and with order at most 1. @@ -666,7 +672,9 @@ public class FunctionUtils { }; } - /** Convert a {@link MultivariateDifferentiableVectorFunction} into a {@link DifferentiableMultivariateVectorFunction}. + /** + * Convert a {@link MultivariateDifferentiableVectorFunction} into a {@link DifferentiableMultivariateVectorFunction}. + * * @param f function to convert * @return converted function * @deprecated this conversion method is temporary in version 3.1, as the {@link @@ -716,7 +724,8 @@ public class FunctionUtils { }; } - /** Convert a {@link DifferentiableMultivariateVectorFunction} into a {@link MultivariateDifferentiableVectorFunction}. + /** + * Convert a {@link DifferentiableMultivariateVectorFunction} into a {@link MultivariateDifferentiableVectorFunction}. * <p> * Note that the converted function is able to handle {@link DerivativeStructure} elements * that all have the same number of free parameters and order, and with order at most 1. http://git-wip-us.apache.org/repos/asf/commons-math/blob/523774aa/src/main/java/org/apache/commons/math3/analysis/RealFieldUnivariateFunction.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/math3/analysis/RealFieldUnivariateFunction.java b/src/main/java/org/apache/commons/math3/analysis/RealFieldUnivariateFunction.java index 0c6d8a2..278b3f8 100644 --- a/src/main/java/org/apache/commons/math3/analysis/RealFieldUnivariateFunction.java +++ b/src/main/java/org/apache/commons/math3/analysis/RealFieldUnivariateFunction.java @@ -20,14 +20,14 @@ import org.apache.commons.math3.RealFieldElement; /** * An interface representing a univariate real function. - * <br/> + * <p> * When a <em>user-defined</em> function encounters an error during * evaluation, the {@link #value(RealFieldElement) value} method should throw a - * <em>user-defined</em> unchecked exception. - * <br/> + * <em>user-defined</em> unchecked exception.</p> + * <p> * The following code excerpt shows the recommended way to do that using * a root solver as an example, but the same construct is applicable to - * ODE integrators or optimizers. + * ODE integrators or optimizers.</p> * * <pre> * private static class LocalException extends RuntimeException { http://git-wip-us.apache.org/repos/asf/commons-math/blob/523774aa/src/main/java/org/apache/commons/math3/analysis/UnivariateFunction.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/math3/analysis/UnivariateFunction.java b/src/main/java/org/apache/commons/math3/analysis/UnivariateFunction.java index e99f1f3..dbbc8f6 100644 --- a/src/main/java/org/apache/commons/math3/analysis/UnivariateFunction.java +++ b/src/main/java/org/apache/commons/math3/analysis/UnivariateFunction.java @@ -18,14 +18,14 @@ package org.apache.commons.math3.analysis; /** * An interface representing a univariate real function. - * <br/> + * <p> * When a <em>user-defined</em> function encounters an error during * evaluation, the {@link #value(double) value} method should throw a - * <em>user-defined</em> unchecked exception. - * <br/> + * <em>user-defined</em> unchecked exception.</p> + * <p> * The following code excerpt shows the recommended way to do that using * a root solver as an example, but the same construct is applicable to - * ODE integrators or optimizers. + * ODE integrators or optimizers.</p> * * <pre> * private static class LocalException extends RuntimeException { http://git-wip-us.apache.org/repos/asf/commons-math/blob/523774aa/src/main/java/org/apache/commons/math3/analysis/differentiation/DSCompiler.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/math3/analysis/differentiation/DSCompiler.java b/src/main/java/org/apache/commons/math3/analysis/differentiation/DSCompiler.java index 45a3331..15fa499 100644 --- a/src/main/java/org/apache/commons/math3/analysis/differentiation/DSCompiler.java +++ b/src/main/java/org/apache/commons/math3/analysis/differentiation/DSCompiler.java @@ -71,8 +71,7 @@ import org.apache.commons.math3.util.MathArrays; * <p>This class is mainly used as the engine for scalar variable {@link DerivativeStructure}. * It can also be used directly to hold several variables in arrays for more complex data * structures. User can for example store a vector of n variables depending on three x, y - * and z free parameters in one array as follows: - * <pre> + * and z free parameters in one array as follows:</p> <pre> * // parameter 0 is x, parameter 1 is y, parameter 2 is z * int parameters = 3; * DSCompiler compiler = DSCompiler.getCompiler(parameters, order); @@ -80,7 +79,7 @@ import org.apache.commons.math3.util.MathArrays; * * // pack all elements in a single array * double[] array = new double[n * size]; - * for (int i = 0; i < n; ++i) { + * for (int i = 0; i < n; ++i) { * * // we know value is guaranteed to be the first element * array[i * size] = v[i]; @@ -94,13 +93,12 @@ import org.apache.commons.math3.util.MathArrays; * * } * </pre> - * Then in another function, user can perform some operations on all elements stored - * in the single array, such as a simple product of all variables: - * <pre> + * <p>Then in another function, user can perform some operations on all elements stored + * in the single array, such as a simple product of all variables:</p> <pre> * // compute the product of all elements * double[] product = new double[size]; * prod[0] = 1.0; - * for (int i = 0; i < n; ++i) { + * for (int i = 0; i < n; ++i) { * double[] tmp = product.clone(); * compiler.multiply(tmp, 0, array, i * size, product, 0); * } @@ -120,7 +118,7 @@ import org.apache.commons.math3.util.MathArrays; * double dPdYdY = product[compiler.getPartialDerivativeIndex(0, 2, 0)]; * double dPdYdZ = product[compiler.getPartialDerivativeIndex(0, 1, 1)]; * double dPdZdZ = product[compiler.getPartialDerivativeIndex(0, 0, 2)]; - * </p> + * </pre> * @see DerivativeStructure * @since 3.1 */ http://git-wip-us.apache.org/repos/asf/commons-math/blob/523774aa/src/main/java/org/apache/commons/math3/analysis/differentiation/DerivativeStructure.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/math3/analysis/differentiation/DerivativeStructure.java b/src/main/java/org/apache/commons/math3/analysis/differentiation/DerivativeStructure.java index c625931..da976fc 100644 --- a/src/main/java/org/apache/commons/math3/analysis/differentiation/DerivativeStructure.java +++ b/src/main/java/org/apache/commons/math3/analysis/differentiation/DerivativeStructure.java @@ -18,9 +18,9 @@ package org.apache.commons.math3.analysis.differentiation; import java.io.Serializable; -import org.apache.commons.math3.RealFieldElement; import org.apache.commons.math3.Field; import org.apache.commons.math3.FieldElement; +import org.apache.commons.math3.RealFieldElement; import org.apache.commons.math3.exception.DimensionMismatchException; import org.apache.commons.math3.exception.MathArithmeticException; import org.apache.commons.math3.exception.NumberIsTooLargeException; @@ -34,7 +34,7 @@ import org.apache.commons.math3.util.MathUtils; * numbers described in Dan Kalman's paper <a * href="http://www1.american.edu/cas/mathstat/People/kalman/pdffiles/mmgautodiff.pdf";>Doubly * Recursive Multivariate Automatic Differentiation</a>, Mathematics Magazine, vol. 75, - * no. 3, June 2002.</p>. Rall's numbers are an extension to the real numbers used + * no. 3, June 2002. Rall's numbers are an extension to the real numbers used * throughout mathematical expressions; they hold the derivative together with the * value of a function. Dan Kalman's derivative structures hold all partial derivatives * up to any specified order, with respect to any number of free parameters. Rall's @@ -554,7 +554,7 @@ public class DerivativeStructure implements RealFieldElement<DerivativeStructure /** * Returns the hypotenuse of a triangle with sides {@code x} and {@code y} - * - sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>)<br/> + * - sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>) * avoiding intermediate overflow or underflow. * * <ul> http://git-wip-us.apache.org/repos/asf/commons-math/blob/523774aa/src/main/java/org/apache/commons/math3/analysis/differentiation/FiniteDifferencesDifferentiator.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/math3/analysis/differentiation/FiniteDifferencesDifferentiator.java b/src/main/java/org/apache/commons/math3/analysis/differentiation/FiniteDifferencesDifferentiator.java index ea92809..c2f1002 100644 --- a/src/main/java/org/apache/commons/math3/analysis/differentiation/FiniteDifferencesDifferentiator.java +++ b/src/main/java/org/apache/commons/math3/analysis/differentiation/FiniteDifferencesDifferentiator.java @@ -34,7 +34,7 @@ import org.apache.commons.math3.util.FastMath; * UnivariateVectorFunction univariate vector functions} or {@link * UnivariateMatrixFunction univariate matrix functions}). These * wrapper objects compute derivatives in addition to function - * value. + * values. * </p> * <p> * The wrapper objects work by calling the underlying function on @@ -62,9 +62,10 @@ import org.apache.commons.math3.util.FastMath; * <li>step size = 1.0e-6, second order derivative error about 148</li> * <li>step size = 1.0e-6, fourth order derivative error about 6.35e+14</li> * </ul> + * <p> * This example shows that the small step size is really bad, even simply - * for second order derivative! - * </p> + * for second order derivative!</p> + * * @since 3.1 */ public class FiniteDifferencesDifferentiator http://git-wip-us.apache.org/repos/asf/commons-math/blob/523774aa/src/main/java/org/apache/commons/math3/analysis/differentiation/SparseGradient.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/math3/analysis/differentiation/SparseGradient.java b/src/main/java/org/apache/commons/math3/analysis/differentiation/SparseGradient.java index 59fcea5..8a8d8ae 100644 --- a/src/main/java/org/apache/commons/math3/analysis/differentiation/SparseGradient.java +++ b/src/main/java/org/apache/commons/math3/analysis/differentiation/SparseGradient.java @@ -432,7 +432,7 @@ public class SparseGradient implements RealFieldElement<SparseGradient>, Seriali /** * Returns the hypotenuse of a triangle with sides {@code x} and {@code y} - * - sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>)<br/> + * - sqrt(<i>x</i><sup>2</sup> +<i>y</i><sup>2</sup>) * avoiding intermediate overflow or underflow. * * <ul> http://git-wip-us.apache.org/repos/asf/commons-math/blob/523774aa/src/main/java/org/apache/commons/math3/analysis/function/StepFunction.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/math3/analysis/function/StepFunction.java b/src/main/java/org/apache/commons/math3/analysis/function/StepFunction.java index 51e3678..e3d16be 100644 --- a/src/main/java/org/apache/commons/math3/analysis/function/StepFunction.java +++ b/src/main/java/org/apache/commons/math3/analysis/function/StepFunction.java @@ -18,11 +18,12 @@ package org.apache.commons.math3.analysis.function; import java.util.Arrays; + import org.apache.commons.math3.analysis.UnivariateFunction; import org.apache.commons.math3.exception.DimensionMismatchException; +import org.apache.commons.math3.exception.NoDataException; import org.apache.commons.math3.exception.NonMonotonicSequenceException; import org.apache.commons.math3.exception.NullArgumentException; -import org.apache.commons.math3.exception.NoDataException; import org.apache.commons.math3.util.MathArrays; /** @@ -40,10 +41,10 @@ public class StepFunction implements UnivariateFunction { /** * Builds a step function from a list of arguments and the corresponding * values. Specifically, returns the function h(x) defined by <pre><code> - * h(x) = y[0] for all x < x[1] - * y[1] for x[1] <= x < x[2] + * h(x) = y[0] for all x < x[1] + * y[1] for x[1] ≤ x < x[2] * ... - * y[y.length - 1] for x >= x[x.length - 1] + * y[y.length - 1] for x ≥ x[x.length - 1] * </code></pre> * The value of {@code x[0]} is ignored, but it must be strictly less than * {@code x[1]}.
