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

Javadoc fixes with Java 8. 

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1591664 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Thomas Neidhart 2014-05-01 13:48:02 +00:00
parent 9bab875f03
commit 6abd9f7508
46 changed files with 239 additions and 272 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
src/main/java/org/apache/commons/math3/RealFieldElement.java
View File

@ -53,7 +53,7 @@ public interface RealFieldElement<T> extends FieldElement<T> {
/** '&divide;' operator. /** '&divide;' operator.
* @param a right hand side parameter of the operator * @param a right hand side parameter of the operator
* @return this&divides;a * @return this&divide;a
*/ */
T divide(double a); T divide(double a);
@ -89,7 +89,7 @@ public interface RealFieldElement<T> extends FieldElement<T> {
T floor(); 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. /** 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 &le; this &le; r + 0.5
*/ */
T rint(); T rint();
@ -131,7 +131,7 @@ public interface RealFieldElement<T> extends FieldElement<T> {
/** /**
* Returns the hypotenuse of a triangle with sides {@code this} and {@code y} * Returns the hypotenuse of a triangle with sides {@code this} and {@code y}
* - sqrt(<i>this</i><sup>2</sup>&nbsp;+<i>y</i><sup>2</sup>)<br/> * - sqrt(<i>this</i><sup>2</sup>&nbsp;+<i>y</i><sup>2</sup>)
* avoiding intermediate overflow or underflow. * avoiding intermediate overflow or underflow.
* *
* <ul> * <ul>

20
src/main/java/org/apache/commons/math3/complex/Complex.java
View File

@ -32,7 +32,7 @@ import org.apache.commons.math3.util.Precision;
/** /**
* Representation of a Complex number, i.e. a number which has both a * Representation of a Complex number, i.e. a number which has both a
* real and imaginary part. * real and imaginary part.
* <br/> * <p>
* Implementations of arithmetic operations handle {@code NaN} and * Implementations of arithmetic operations handle {@code NaN} and
* infinite values according to the rules for {@link java.lang.Double}, i.e. * infinite values according to the rules for {@link java.lang.Double}, i.e.
* {@link #equals} is an equivalence relation for all instances that have * {@link #equals} is an equivalence relation for all instances that have
@ -50,7 +50,7 @@ import org.apache.commons.math3.util.Precision;
* equals for primitive double} in {@link org.apache.commons.math3.util.Precision} * equals for primitive double} in {@link org.apache.commons.math3.util.Precision}
* conforms with IEEE-754 while this class conforms with the standard behavior * conforms with IEEE-754 while this class conforms with the standard behavior
* for Java object types. * for Java object types.
* <br/> * <p>
* Implements Serializable since 2.0 * Implements Serializable since 2.0
* *
* @version $Id$ * @version $Id$
@ -144,7 +144,7 @@ public class Complex implements FieldElement<Complex>, Serializable {
* (a + bi) + (c + di) = (a+c) + (b+d)i * (a + bi) + (c + di) = (a+c) + (b+d)i
* </code> * </code>
* </pre> * </pre>
* <br/> * <p>
* If either {@code this} or {@code addend} has a {@code NaN} value in * If either {@code this} or {@code addend} has a {@code NaN} value in
* either part, {@link #NaN} is returned; otherwise {@code Infinite} * either part, {@link #NaN} is returned; otherwise {@code Infinite}
* and {@code NaN} values are returned in the parts of the result * and {@code NaN} values are returned in the parts of the result
@ -183,10 +183,10 @@ public class Complex implements FieldElement<Complex>, Serializable {
/** /**
* Return the conjugate of this complex number. * Return the conjugate of this complex number.
* The conjugate of {@code a + bi} is {@code a - bi}. * The conjugate of {@code a + bi} is {@code a - bi}.
* <br/> * <p>
* {@link #NaN} is returned if either the real or imaginary * {@link #NaN} is returned if either the real or imaginary
* part of this Complex number equals {@code Double.NaN}. * part of this Complex number equals {@code Double.NaN}.
* <br/> * <p>
* If the imaginary part is infinite, and the real part is not * If the imaginary part is infinite, and the real part is not
* {@code NaN}, the returned value has infinite imaginary part * {@code NaN}, the returned value has infinite imaginary part
* of the opposite sign, e.g. the conjugate of * of the opposite sign, e.g. the conjugate of
@ -217,7 +217,7 @@ public class Complex implements FieldElement<Complex>, Serializable {
* <a href="http://doi.acm.org/10.1145/1039813.1039814"> * <a href="http://doi.acm.org/10.1145/1039813.1039814">
* prescaling of operands</a> to limit the effects of overflows and * prescaling of operands</a> to limit the effects of overflows and
* underflows in the computation. * underflows in the computation.
* <br/> * <p>
* {@code Infinite} and {@code NaN} values are handled according to the * {@code Infinite} and {@code NaN} values are handled according to the
* following rules, applied in the order presented: * following rules, applied in the order presented:
* <ul> * <ul>
@ -508,12 +508,12 @@ public class Complex implements FieldElement<Complex>, Serializable {
* </pre> * </pre>
* Returns {@link #NaN} if either {@code this} or {@code factor} has one or * Returns {@link #NaN} if either {@code this} or {@code factor} has one or
* more {@code NaN} parts. * more {@code NaN} parts.
* <br/> * <p>
* Returns {@link #INF} if neither {@code this} nor {@code factor} has one * Returns {@link #INF} if neither {@code this} nor {@code factor} has one
* or more {@code NaN} parts and if either {@code this} or {@code factor} * or more {@code NaN} parts and if either {@code this} or {@code factor}
* has one or more infinite parts (same result is returned regardless of * has one or more infinite parts (same result is returned regardless of
* the sign of the components). * the sign of the components).
* <br/> * <p>
* Returns finite values in components of the result per the definitional * Returns finite values in components of the result per the definitional
* formula in all remaining cases. * formula in all remaining cases.
* *
@ -724,10 +724,10 @@ public class Complex implements FieldElement<Complex>, Serializable {
* where the (real) functions on the right-hand side are * where the (real) functions on the right-hand side are
* {@link FastMath#sin}, {@link FastMath#cos}, * {@link FastMath#sin}, {@link FastMath#cos},
* {@link FastMath#cosh} and {@link FastMath#sinh}. * {@link FastMath#cosh} and {@link FastMath#sinh}.
* <br/> * <p>
* Returns {@link Complex#NaN} if either real or imaginary part of the * Returns {@link Complex#NaN} if either real or imaginary part of the
* input argument is {@code NaN}. * input argument is {@code NaN}.
* <br/> * <p>
* Infinite values in real or imaginary parts of the input may result in * Infinite values in real or imaginary parts of the input may result in
* infinite or NaN values returned in parts of the result. * infinite or NaN values returned in parts of the result.
* <pre> * <pre>

4
src/main/java/org/apache/commons/math3/geometry/enclosing/WelzlEncloser.java
View File

@ -32,10 +32,10 @@ import org.apache.commons.math3.geometry.Space;
* href="http://www.inf.ethz.ch/personal/gaertner/texts/own_work/esa99_final.pdf">Fast and * href="http://www.inf.ethz.ch/personal/gaertner/texts/own_work/esa99_final.pdf">Fast and
* Robust Smallest Enclosing Balls</a>, by Bernd Gärtner and further modified in * Robust Smallest Enclosing Balls</a>, by Bernd Gärtner and further modified in
* paper <a * paper <a
* href=http://www.idt.mdh.se/kurser/ct3340/ht12/MINICONFERENCE/FinalPapers/ircse12_submission_30.pdf"> * href="http://www.idt.mdh.se/kurser/ct3340/ht12/MINICONFERENCE/FinalPapers/ircse12_submission_30.pdf">
* Efficient Computation of Smallest Enclosing Balls in Three Dimensions</a> by Linus Källberg * Efficient Computation of Smallest Enclosing Balls in Three Dimensions</a> by Linus Källberg
* to avoid performing local copies of data have been included. * to avoid performing local copies of data have been included.
* </p> *
* @param <S> Space type. * @param <S> Space type.
* @param <P> Point type. * @param <P> Point type.
* @version $Id$ * @version $Id$

6
src/main/java/org/apache/commons/math3/geometry/euclidean/threed/FieldRotation.java
View File

@ -19,8 +19,8 @@ package org.apache.commons.math3.geometry.euclidean.threed;
import java.io.Serializable; import java.io.Serializable;
import org.apache.commons.math3.RealFieldElement;
import org.apache.commons.math3.Field; import org.apache.commons.math3.Field;
import org.apache.commons.math3.RealFieldElement;
import org.apache.commons.math3.exception.MathArithmeticException; import org.apache.commons.math3.exception.MathArithmeticException;
import org.apache.commons.math3.exception.MathIllegalArgumentException; import org.apache.commons.math3.exception.MathIllegalArgumentException;
import org.apache.commons.math3.exception.util.LocalizedFormats; import org.apache.commons.math3.exception.util.LocalizedFormats;
@ -1158,9 +1158,7 @@ public class FieldRotation<T extends RealFieldElement<T>> implements Serializabl
* or very different. It is mathematically defined as the angle of * or very different. It is mathematically defined as the angle of
* the rotation r that prepended to one of the rotations gives the other * the rotation r that prepended to one of the rotations gives the other
* one:</p> * one:</p>
* <pre> * <code>r<sub>1</sub>(r) = r<sub>2</sub></code>
* r<sub>1</sub>(r) = r<sub>2</sub>
* </pre>
* <p>This distance is an angle between 0 and &pi;. Its value is the smallest * <p>This distance is an angle between 0 and &pi;. Its value is the smallest
* possible upper bound of the angle in radians between r<sub>1</sub>(v) * possible upper bound of the angle in radians between r<sub>1</sub>(v)
* and r<sub>2</sub>(v) for all possible vectors v. This upper bound is * and r<sub>2</sub>(v) for all possible vectors v. This upper bound is

2
src/main/java/org/apache/commons/math3/geometry/euclidean/threed/FieldVector3D.java
View File

@ -539,7 +539,7 @@ public class FieldVector3D<T extends RealFieldElement<T>> implements Serializabl
* Vector3D k = u.normalize(); * Vector3D k = u.normalize();
* Vector3D i = k.orthogonal(); * Vector3D i = k.orthogonal();
* Vector3D j = Vector3D.crossProduct(k, i); * Vector3D j = Vector3D.crossProduct(k, i);
* </code></pre></p> * </code></pre>
* @return a new normalized vector orthogonal to the instance * @return a new normalized vector orthogonal to the instance
* @exception MathArithmeticException if the norm of the instance is null * @exception MathArithmeticException if the norm of the instance is null
*/ */

4
src/main/java/org/apache/commons/math3/geometry/euclidean/threed/Rotation.java
View File

@ -1029,9 +1029,7 @@ public class Rotation implements Serializable {
* or very different. It is mathematically defined as the angle of * or very different. It is mathematically defined as the angle of
* the rotation r that prepended to one of the rotations gives the other * the rotation r that prepended to one of the rotations gives the other
* one:</p> * one:</p>
* <pre> * <code>r<sub>1</sub>(r) = r<sub>2</sub></code>
* r<sub>1</sub>(r) = r<sub>2</sub>
* </pre>
* <p>This distance is an angle between 0 and &pi;. Its value is the smallest * <p>This distance is an angle between 0 and &pi;. Its value is the smallest
* possible upper bound of the angle in radians between r<sub>1</sub>(v) * possible upper bound of the angle in radians between r<sub>1</sub>(v)
* and r<sub>2</sub>(v) for all possible vectors v. This upper bound is * and r<sub>2</sub>(v) for all possible vectors v. This upper bound is

2
src/main/java/org/apache/commons/math3/geometry/euclidean/threed/Vector3D.java
View File

@ -313,7 +313,7 @@ public class Vector3D implements Serializable, Vector<Euclidean3D> {
* Vector3D k = u.normalize(); * Vector3D k = u.normalize();
* Vector3D i = k.orthogonal(); * Vector3D i = k.orthogonal();
* Vector3D j = Vector3D.crossProduct(k, i); * Vector3D j = Vector3D.crossProduct(k, i);
* </code></pre></p> * </code></pre>
* @return a new normalized vector orthogonal to the instance * @return a new normalized vector orthogonal to the instance
* @exception MathArithmeticException if the norm of the instance is null * @exception MathArithmeticException if the norm of the instance is null
*/ */

24
src/main/java/org/apache/commons/math3/geometry/partitioning/Embedding.java
View File

@ -20,30 +20,28 @@ import org.apache.commons.math3.geometry.Point;
import org.apache.commons.math3.geometry.Space; import org.apache.commons.math3.geometry.Space;
/** This interface defines mappers between a space and one of its sub-spaces. /** This interface defines mappers between a space and one of its sub-spaces.
* <p>
* <p>Sub-spaces are the lower dimensions subsets of a n-dimensions * Sub-spaces are the lower dimensions subsets of a n-dimensions
* space. The (n-1)-dimension sub-spaces are specific sub-spaces known * space. The (n-1)-dimension sub-spaces are specific sub-spaces known
* as {@link Hyperplane hyperplanes}. This interface can be used regardless * as {@link Hyperplane hyperplanes}. This interface can be used regardless
* of the dimensions differences. As an example, {@link * of the dimensions differences. As an example, {@link
* org.apache.commons.math3.geometry.euclidean.threed.Line Line} in 3D * org.apache.commons.math3.geometry.euclidean.threed.Line Line} in 3D
* implements Embedding<{@link * implements Embedding&lt;{@link
* org.apache.commons.math3.geometry.euclidean.threed.Vector3D Vector3D}, {link * org.apache.commons.math3.geometry.euclidean.threed.Vector3D Vector3D}, {@link
* org.apache.commons.math3.geometry.euclidean.oned.Vector1D Vector1D>, i.e. it * org.apache.commons.math3.geometry.euclidean.oned.Vector1D Vector1D}&gt;, i.e. it
* maps directly dimensions 3 and 1.</p> * maps directly dimensions 3 and 1.
* <p>
* <p>In the 3D euclidean space, hyperplanes are 2D planes, and the 1D * In the 3D euclidean space, hyperplanes are 2D planes, and the 1D
* sub-spaces are lines.</p> * sub-spaces are lines.
* <p> * <p>
* Note that this interface is <em>not</em> intended to be implemented * Note that this interface is <em>not</em> intended to be implemented
* by Apache Commons Math users, it is only intended to be implemented * by Apache Commons Math users, it is only intended to be implemented
* within the library itself. New methods may be added even for minor * within the library itself. New methods may be added even for minor
* versions, which breaks compatibility for external implementations. * versions, which breaks compatibility for external implementations.
* </p> *
* @param <S> Type of the embedding space. * @param <S> Type of the embedding space.
* @param <T> Type of the embedded sub-space. * @param <T> Type of the embedded sub-space.
*
* @see Hyperplane * @see Hyperplane
* @version $Id$ * @version $Id$
* @since 3.0 * @since 3.0

2
src/main/java/org/apache/commons/math3/geometry/partitioning/utilities/OrderedTuple.java
View File

@ -44,7 +44,7 @@ import org.apache.commons.math3.util.FastMath;
* given range. This is depicted in dimension 2 by the following * given range. This is depicted in dimension 2 by the following
* picture:</p> * picture:</p>
* *
* <img src="doc-files/OrderedTuple.png" /> * <img src="doc-files/OrderedTuple.png" alt="OrderedTuple">
* *
* <p>This picture shows a set of 100000 random 2-D pairs having their * <p>This picture shows a set of 100000 random 2-D pairs having their
* first component between -50 and +150 and their second component * first component between -50 and +150 and their second component

2
src/main/java/org/apache/commons/math3/geometry/spherical/twod/SphericalPolygonsSet.java
View File

@ -431,7 +431,7 @@ public class SphericalPolygonsSet extends AbstractRegion<Sphere2D, Sphere1D> {
* <pre> * <pre>
* // compute region, plus an enclosing spherical cap * // compute region, plus an enclosing spherical cap
* SphericalPolygonsSet complexShape = ...; * SphericalPolygonsSet complexShape = ...;
* EnclosingBall<Sphere2D, S2Point> cap = complexShape.getEnclosingCap(); * EnclosingBall&lt;Sphere2D, S2Point&gt; cap = complexShape.getEnclosingCap();
* *
* // check lots of points * // check lots of points
* for (Vector3D p : points) { * for (Vector3D p : points) {

6
src/main/java/org/apache/commons/math3/optim/BaseMultiStartMultivariateOptimizer.java
View File

@ -23,7 +23,7 @@ import org.apache.commons.math3.random.RandomVectorGenerator;
/** /**
* Base class multi-start optimizer for a multivariate function. * Base class multi-start optimizer for a multivariate function.
* <br/> * <p>
* This class wraps an optimizer in order to use it several times in * This class wraps an optimizer in order to use it several times in
* turn with different starting points (trying to avoid being trapped * turn with different starting points (trying to avoid being trapped
* in a local extremum when looking for a global one). * in a local extremum when looking for a global one).
@ -102,7 +102,7 @@ public abstract class BaseMultiStartMultivariateOptimizer<PAIR>
* restarts. The {@code optimize} method returns the best point only. * restarts. The {@code optimize} method returns the best point only.
* This method returns all the points found at the end of each starts, * This method returns all the points found at the end of each starts,
* including the best one already returned by the {@code optimize} method. * including the best one already returned by the {@code optimize} method.
* <br/> * <p>
* The returned array as one element for each start as specified * The returned array as one element for each start as specified
* in the constructor. It is ordered with the results from the * in the constructor. It is ordered with the results from the
* runs that did converge first, sorted from best to worst * runs that did converge first, sorted from best to worst
@ -113,7 +113,7 @@ public abstract class BaseMultiStartMultivariateOptimizer<PAIR>
* an exception. * an exception.
* This also means that if the first element is not {@code null}, it is * This also means that if the first element is not {@code null}, it is
* the best point found across all starts. * the best point found across all starts.
* <br/> * <p>
* The behaviour is undefined if this method is called before * The behaviour is undefined if this method is called before
* {@code optimize}; it will likely throw {@code NullPointerException}. * {@code optimize}; it will likely throw {@code NullPointerException}.
* *

4
src/main/java/org/apache/commons/math3/optim/ConvergenceChecker.java
View File

@ -20,11 +20,11 @@ package org.apache.commons.math3.optim;
/** /**
* This interface specifies how to check if an optimization algorithm has * This interface specifies how to check if an optimization algorithm has
* converged. * converged.
* <br/> * <p>
* Deciding if convergence has been reached is a problem-dependent issue. The * Deciding if convergence has been reached is a problem-dependent issue. The
* user should provide a class implementing this interface to allow the * user should provide a class implementing this interface to allow the
* optimization algorithm to stop its search according to the problem at hand. * optimization algorithm to stop its search according to the problem at hand.
* <br/> * <p>
* For convenience, three implementations that fit simple needs are already * For convenience, three implementations that fit simple needs are already
* provided: {@link SimpleValueChecker}, {@link SimpleVectorValueChecker} and * provided: {@link SimpleValueChecker}, {@link SimpleVectorValueChecker} and
* {@link SimplePointChecker}. The first two consider that convergence is * {@link SimplePointChecker}. The first two consider that convergence is

2
src/main/java/org/apache/commons/math3/optim/InitialGuess.java
View File

@ -19,7 +19,7 @@ package org.apache.commons.math3.optim;
/** /**
* Starting point (first guess) of the optimization procedure. * Starting point (first guess) of the optimization procedure.
* <br/> * <p>
* Immutable class. * Immutable class.
* *
* @version $Id$ * @version $Id$

2
src/main/java/org/apache/commons/math3/optim/SimpleBounds.java
View File

@ -22,7 +22,7 @@ import java.util.Arrays;
* Simple optimization constraints: lower and upper bounds. * Simple optimization constraints: lower and upper bounds.
* The valid range of the parameters is an interval that can be infinite * The valid range of the parameters is an interval that can be infinite
* (in one or both directions). * (in one or both directions).
* <br/> * <p>
* Immutable class. * Immutable class.
* *
* @version $Id$ * @version $Id$

2
src/main/java/org/apache/commons/math3/optim/SimpleValueChecker.java
View File

@ -28,7 +28,7 @@ import org.apache.commons.math3.exception.NotStrictlyPositiveException;
* difference between the objective function values is smaller than a * difference between the objective function values is smaller than a
* threshold or if either the absolute difference between the objective * threshold or if either the absolute difference between the objective
* function values is smaller than another threshold. * function values is smaller than another threshold.
* <br/> * <p>
* The {@link #converged(int,PointValuePair,PointValuePair) converged} * The {@link #converged(int,PointValuePair,PointValuePair) converged}
* method will also return {@code true} if the number of iterations has been set * method will also return {@code true} if the number of iterations has been set
* (see {@link #SimpleValueChecker(double,double,int) this constructor}). * (see {@link #SimpleValueChecker(double,double,int) this constructor}).

2
src/main/java/org/apache/commons/math3/optim/SimpleVectorValueChecker.java
View File

@ -28,7 +28,7 @@ import org.apache.commons.math3.exception.NotStrictlyPositiveException;
* difference between the objective function values is smaller than a * difference between the objective function values is smaller than a
* threshold or if either the absolute difference between the objective * threshold or if either the absolute difference between the objective
* function values is smaller than another threshold for all vectors elements. * function values is smaller than another threshold for all vectors elements.
* <br/> * <p>
* The {@link #converged(int,PointVectorValuePair,PointVectorValuePair) converged} * The {@link #converged(int,PointVectorValuePair,PointVectorValuePair) converged}
* method will also return {@code true} if the number of iterations has been set * method will also return {@code true} if the number of iterations has been set
* (see {@link #SimpleVectorValueChecker(double,double,int) this constructor}). * (see {@link #SimpleVectorValueChecker(double,double,int) this constructor}).

15
src/main/java/org/apache/commons/math3/optim/package-info.java
View File

@ -23,14 +23,12 @@
* a scalar function, called the * a scalar function, called the
* {@link org.apache.commons.math3.optim.nonlinear.scalar.ObjectiveFunction <em>objective * {@link org.apache.commons.math3.optim.nonlinear.scalar.ObjectiveFunction <em>objective
* function</em>}. * function</em>}.
* <br/> * <p>
* For some scalar objective functions the gradient can be computed (analytically * For some scalar objective functions the gradient can be computed (analytically
* or numerically). Algorithms that use this knowledge are defined in the * or numerically). Algorithms that use this knowledge are defined in the
* {@link org.apache.commons.math3.optim.nonlinear.scalar.gradient} package. * {@link org.apache.commons.math3.optim.nonlinear.scalar.gradient} package.
* The algorithms that do not need this additional information are located in * The algorithms that do not need this additional information are located in
* the {@link org.apache.commons.math3.optim.nonlinear.scalar.noderiv} package. * the {@link org.apache.commons.math3.optim.nonlinear.scalar.noderiv} package.
* </p>
*
* <p> * <p>
* Some problems are solved more efficiently by algorithms that, instead of an * Some problems are solved more efficiently by algorithms that, instead of an
* objective function, need access to a * objective function, need access to a
@ -40,22 +38,20 @@
* {@link org.apache.commons.math3.optim.nonlinear.vector.Target target values}. * {@link org.apache.commons.math3.optim.nonlinear.vector.Target target values}.
* Those algorithms are located in the * Those algorithms are located in the
* {@link org.apache.commons.math3.optim.nonlinear.vector} package. * {@link org.apache.commons.math3.optim.nonlinear.vector} package.
* <br/> * <p>
* Algorithms that also require the * Algorithms that also require the
* {@link org.apache.commons.math3.optim.nonlinear.vector.ModelFunctionJacobian * {@link org.apache.commons.math3.optim.nonlinear.vector.ModelFunctionJacobian
* Jacobian matrix of the model} are located in the * Jacobian matrix of the model} are located in the
* {@link org.apache.commons.math3.optim.nonlinear.vector.jacobian} package. * {@link org.apache.commons.math3.optim.nonlinear.vector.jacobian} package.
* <br/> * <p>
* The {@link org.apache.commons.math3.optim.nonlinear.vector.jacobian.AbstractLeastSquaresOptimizer * The {@link org.apache.commons.math3.optim.nonlinear.vector.jacobian.AbstractLeastSquaresOptimizer
* non-linear least-squares optimizers} are a specialization of the the latter, * non-linear least-squares optimizers} are a specialization of the the latter,
* that minimize the distance (called <em>cost</em> or <em>&chi;<sup>2</sup></em>) * that minimize the distance (called <em>cost</em> or <em>&chi;<sup>2</sup></em>)
* between model and observations. * between model and observations.
* <br/> * <p>
* For cases where the Jacobian cannot be provided, a utility class will * For cases where the Jacobian cannot be provided, a utility class will
* {@link org.apache.commons.math3.optim.nonlinear.scalar.LeastSquaresConverter * {@link org.apache.commons.math3.optim.nonlinear.scalar.LeastSquaresConverter
* convert} a (vector) model into a (scalar) objective function. * convert} a (vector) model into a (scalar) objective function.
* </p>
*
* <p> * <p>
* This package provides common functionality for the optimization algorithms. * This package provides common functionality for the optimization algorithms.
* Abstract classes ({@link org.apache.commons.math3.optim.BaseOptimizer} and * Abstract classes ({@link org.apache.commons.math3.optim.BaseOptimizer} and
@ -64,14 +60,11 @@
* evaluations} and {@link org.apache.commons.math3.optim.MaxIter iterations} * evaluations} and {@link org.apache.commons.math3.optim.MaxIter iterations}
* counters and a user-defined * counters and a user-defined
* {@link org.apache.commons.math3.optim.ConvergenceChecker convergence checker}. * {@link org.apache.commons.math3.optim.ConvergenceChecker convergence checker}.
* </p>
*
* <p> * <p>
* For each of the optimizer types, there is a special implementation that * For each of the optimizer types, there is a special implementation that
* wraps an optimizer instance and provides a "multi-start" feature: it calls * wraps an optimizer instance and provides a "multi-start" feature: it calls
* the underlying optimizer several times with different starting points and * the underlying optimizer several times with different starting points and
* returns the best optimum found, or all optima if so desired. * returns the best optimum found, or all optima if so desired.
* This could be useful to avoid being trapped in a local extremum. * This could be useful to avoid being trapped in a local extremum.
* </p>
*/ */
package org.apache.commons.math3.optim; package org.apache.commons.math3.optim;

2
src/main/java/org/apache/commons/math3/optimization/BaseMultivariateMultiStartOptimizer.java
View File

@ -94,7 +94,7 @@ public class BaseMultivariateMultiStartOptimizer<FUNC extends MultivariateFuncti
* returns all the points found at the end of each starts, * returns all the points found at the end of each starts,
* including the best one already returned by the {@link * including the best one already returned by the {@link
* #optimize(int,MultivariateFunction,GoalType,double[]) optimize} method. * #optimize(int,MultivariateFunction,GoalType,double[]) optimize} method.
* <br/> * <p>
* The returned array as one element for each start as specified * The returned array as one element for each start as specified
* in the constructor. It is ordered with the results from the * in the constructor. It is ordered with the results from the
* runs that did converge first, sorted from best to worst * runs that did converge first, sorted from best to worst

2
src/main/java/org/apache/commons/math3/optimization/BaseMultivariateVectorMultiStartOptimizer.java
View File

@ -94,7 +94,7 @@ public class BaseMultivariateVectorMultiStartOptimizer<FUNC extends Multivariate
* returns all the points found at the end of each starts, including * returns all the points found at the end of each starts, including
* the best one already returned by the {@link * the best one already returned by the {@link
* #optimize(int,MultivariateVectorFunction,double[],double[],double[]) optimize} method. * #optimize(int,MultivariateVectorFunction,double[],double[],double[]) optimize} method.
* <br/> * <p>
* The returned array as one element for each start as specified * The returned array as one element for each start as specified
* in the constructor. It is ordered with the results from the * in the constructor. It is ordered with the results from the
* runs that did converge first, sorted from best to worst * runs that did converge first, sorted from best to worst

4
src/main/java/org/apache/commons/math3/optimization/ConvergenceChecker.java
View File

@ -20,11 +20,11 @@ package org.apache.commons.math3.optimization;
/** /**
* This interface specifies how to check if an optimization algorithm has * This interface specifies how to check if an optimization algorithm has
* converged. * converged.
* <br/> * <p>
* Deciding if convergence has been reached is a problem-dependent issue. The * Deciding if convergence has been reached is a problem-dependent issue. The
* user should provide a class implementing this interface to allow the * user should provide a class implementing this interface to allow the
* optimization algorithm to stop its search according to the problem at hand. * optimization algorithm to stop its search according to the problem at hand.
* <br/> * <p>
* For convenience, three implementations that fit simple needs are already * For convenience, three implementations that fit simple needs are already
* provided: {@link SimpleValueChecker}, {@link SimpleVectorValueChecker} and * provided: {@link SimpleValueChecker}, {@link SimpleVectorValueChecker} and
* {@link SimplePointChecker}. The first two consider that convergence is * {@link SimplePointChecker}. The first two consider that convergence is

2
src/main/java/org/apache/commons/math3/optimization/InitialGuess.java
View File

@ -19,7 +19,7 @@ package org.apache.commons.math3.optimization;
/** /**
* Starting point (first guess) of the optimization procedure. * Starting point (first guess) of the optimization procedure.
* <br/> * <p>
* Immutable class. * Immutable class.
* *
* @version $Id$ * @version $Id$

11
src/main/java/org/apache/commons/math3/optimization/LeastSquaresConverter.java
View File

@ -85,9 +85,10 @@ public class LeastSquaresConverter implements MultivariateFunction {
* <p> * <p>
* The scalar objective function value is computed as: * The scalar objective function value is computed as:
* <pre> * <pre>
* <code>
* objective = &sum;weight<sub>i</sub>(observation<sub>i</sub>-objective<sub>i</sub>)<sup>2</sup> * objective = &sum;weight<sub>i</sub>(observation<sub>i</sub>-objective<sub>i</sub>)<sup>2</sup>
* </code>
* </pre> * </pre>
* </p>
* <p> * <p>
* Weights can be used for example to combine residuals with different standard * Weights can be used for example to combine residuals with different standard
* deviations. As an example, consider a residuals array in which even elements * deviations. As an example, consider a residuals array in which even elements
@ -96,12 +97,11 @@ public class LeastSquaresConverter implements MultivariateFunction {
* In this case, the weights array should be initialized with value * In this case, the weights array should be initialized with value
* 1.0/(0.01<sup>2</sup>) in the even elements and 1.0/(15.0<sup>2</sup>) in the * 1.0/(0.01<sup>2</sup>) in the even elements and 1.0/(15.0<sup>2</sup>) in the
* odd elements (i.e. reciprocals of variances). * odd elements (i.e. reciprocals of variances).
* </p>
* <p> * <p>
* The array computed by the objective function, the observations array and the * The array computed by the objective function, the observations array and the
* weights array must have consistent sizes or a {@link DimensionMismatchException} * weights array must have consistent sizes or a {@link DimensionMismatchException}
* will be triggered while computing the scalar objective. * will be triggered while computing the scalar objective.
* </p> *
* @param function vectorial residuals function to wrap * @param function vectorial residuals function to wrap
* @param observations observations to be compared to objective function to compute residuals * @param observations observations to be compared to objective function to compute residuals
* @param weights weights to apply to the residuals * @param weights weights to apply to the residuals
@ -124,14 +124,15 @@ public class LeastSquaresConverter implements MultivariateFunction {
* <p> * <p>
* The scalar objective function value is computed as: * The scalar objective function value is computed as:
* <pre> * <pre>
* <code>
* objective = y<sup>T</sup>y with y = scale&times;(observation-objective) * objective = y<sup>T</sup>y with y = scale&times;(observation-objective)
* </code>
* </pre> * </pre>
* </p>
* <p> * <p>
* The array computed by the objective function, the observations array and the * The array computed by the objective function, the observations array and the
* the scaling matrix must have consistent sizes or a {@link DimensionMismatchException} * the scaling matrix must have consistent sizes or a {@link DimensionMismatchException}
* will be triggered while computing the scalar objective. * will be triggered while computing the scalar objective.
* </p> *
* @param function vectorial residuals function to wrap * @param function vectorial residuals function to wrap
* @param observations observations to be compared to objective function to compute residuals * @param observations observations to be compared to objective function to compute residuals
* @param scale scaling matrix * @param scale scaling matrix

2
src/main/java/org/apache/commons/math3/optimization/SimpleBounds.java
View File

@ -21,7 +21,7 @@ package org.apache.commons.math3.optimization;
* Simple optimization constraints: lower and upper bounds. * Simple optimization constraints: lower and upper bounds.
* The valid range of the parameters is an interval that can be infinite * The valid range of the parameters is an interval that can be infinite
* (in one or both directions). * (in one or both directions).
* <br/> * <p>
* Immutable class. * Immutable class.
* *
* @version $Id$ * @version $Id$

2
src/main/java/org/apache/commons/math3/optimization/SimplePointChecker.java
View File

@ -29,7 +29,7 @@ import org.apache.commons.math3.exception.NotStrictlyPositiveException;
* difference between each point coordinate are smaller than a threshold * difference between each point coordinate are smaller than a threshold
* or if either the absolute difference between the point coordinates are * or if either the absolute difference between the point coordinates are
* smaller than another threshold. * smaller than another threshold.
* <br/> * <p>
* The {@link #converged(int,Pair,Pair) converged} method will also return * The {@link #converged(int,Pair,Pair) converged} method will also return
* {@code true} if the number of iterations has been set (see * {@code true} if the number of iterations has been set (see
* {@link #SimplePointChecker(double,double,int) this constructor}). * {@link #SimplePointChecker(double,double,int) this constructor}).

2
src/main/java/org/apache/commons/math3/optimization/SimpleValueChecker.java
View File

@ -28,7 +28,7 @@ import org.apache.commons.math3.exception.NotStrictlyPositiveException;
* difference between the objective function values is smaller than a * difference between the objective function values is smaller than a
* threshold or if either the absolute difference between the objective * threshold or if either the absolute difference between the objective
* function values is smaller than another threshold. * function values is smaller than another threshold.
* <br/> * <p>
* The {@link #converged(int,PointValuePair,PointValuePair) converged} * The {@link #converged(int,PointValuePair,PointValuePair) converged}
* method will also return {@code true} if the number of iterations has been set * method will also return {@code true} if the number of iterations has been set
* (see {@link #SimpleValueChecker(double,double,int) this constructor}). * (see {@link #SimpleValueChecker(double,double,int) this constructor}).

2
src/main/java/org/apache/commons/math3/optimization/SimpleVectorValueChecker.java
View File

@ -28,7 +28,7 @@ import org.apache.commons.math3.exception.NotStrictlyPositiveException;
* difference between the objective function values is smaller than a * difference between the objective function values is smaller than a
* threshold or if either the absolute difference between the objective * threshold or if either the absolute difference between the objective
* function values is smaller than another threshold for all vectors elements. * function values is smaller than another threshold for all vectors elements.
* <br/> * <p>
* The {@link #converged(int,PointVectorValuePair,PointVectorValuePair) converged} * The {@link #converged(int,PointVectorValuePair,PointVectorValuePair) converged}
* method will also return {@code true} if the number of iterations has been set * method will also return {@code true} if the number of iterations has been set
* (see {@link #SimpleVectorValueChecker(double,double,int) this constructor}). * (see {@link #SimpleVectorValueChecker(double,double,int) this constructor}).

2
src/main/java/org/apache/commons/math3/optimization/Target.java
View File

@ -21,7 +21,7 @@ package org.apache.commons.math3.optimization;
* Target of the optimization procedure. * Target of the optimization procedure.
* They are the values which the objective vector function must reproduce * They are the values which the objective vector function must reproduce
* When the parameters of the model have been optimized. * When the parameters of the model have been optimized.
* <br/> * <p>
* Immutable class. * Immutable class.
* *
* @version $Id$ * @version $Id$

2
src/main/java/org/apache/commons/math3/optimization/Weight.java
View File

@ -23,7 +23,7 @@ import org.apache.commons.math3.linear.NonSquareMatrixException;
/** /**
* Weight matrix of the residuals between model and observations. * Weight matrix of the residuals between model and observations.
* <br/> * <p>
* Immutable class. * Immutable class.
* *
* @version $Id$ * @version $Id$

2
src/main/java/org/apache/commons/math3/optimization/fitting/CurveFitter.java
View File

@ -30,7 +30,7 @@ import org.apache.commons.math3.optimization.MultivariateDifferentiableVectorOpt
import org.apache.commons.math3.optimization.PointVectorValuePair; import org.apache.commons.math3.optimization.PointVectorValuePair;
/** Fitter for parametric univariate real functions y = f(x). /** Fitter for parametric univariate real functions y = f(x).
* <br/> * <p>
* When a univariate real function y = f(x) does depend on some * When a univariate real function y = f(x) does depend on some
* unknown parameters p<sub>0</sub>, p<sub>1</sub> ... p<sub>n-1</sub>, * unknown parameters p<sub>0</sub>, p<sub>1</sub> ... p<sub>n-1</sub>,
* this class can be used to find these parameters. It does this * this class can be used to find these parameters. It does this

8
src/main/java/org/apache/commons/math3/optimization/fitting/HarmonicFitter.java
View File

@ -17,17 +17,17 @@
package org.apache.commons.math3.optimization.fitting; package org.apache.commons.math3.optimization.fitting;
import org.apache.commons.math3.optimization.DifferentiableMultivariateVectorOptimizer;
import org.apache.commons.math3.analysis.function.HarmonicOscillator; import org.apache.commons.math3.analysis.function.HarmonicOscillator;
import org.apache.commons.math3.exception.ZeroException;
import org.apache.commons.math3.exception.NumberIsTooSmallException;
import org.apache.commons.math3.exception.MathIllegalStateException; import org.apache.commons.math3.exception.MathIllegalStateException;
import org.apache.commons.math3.exception.NumberIsTooSmallException;
import org.apache.commons.math3.exception.ZeroException;
import org.apache.commons.math3.exception.util.LocalizedFormats; import org.apache.commons.math3.exception.util.LocalizedFormats;
import org.apache.commons.math3.optimization.DifferentiableMultivariateVectorOptimizer;
import org.apache.commons.math3.util.FastMath; import org.apache.commons.math3.util.FastMath;
/** /**
* Class that implements a curve fitting specialized for sinusoids. * Class that implements a curve fitting specialized for sinusoids.
* * <p>
* Harmonic fitting is a very simple case of curve fitting. The * Harmonic fitting is a very simple case of curve fitting. The
* estimated coefficients are the amplitude a, the pulsation &omega; and * estimated coefficients are the amplitude a, the pulsation &omega; and
* the phase &phi;: <code>f (t) = a cos (&omega; t + &phi;)</code>. They are * the phase &phi;: <code>f (t) = a cos (&omega; t + &phi;)</code>. They are

21
src/main/java/org/apache/commons/math3/optimization/general/AbstractLeastSquaresOptimizer.java
View File

@ -19,25 +19,26 @@ package org.apache.commons.math3.optimization.general;
import org.apache.commons.math3.analysis.DifferentiableMultivariateVectorFunction; import org.apache.commons.math3.analysis.DifferentiableMultivariateVectorFunction;
import org.apache.commons.math3.analysis.FunctionUtils; import org.apache.commons.math3.analysis.FunctionUtils;
import org.apache.commons.math3.analysis.MultivariateVectorFunction;
import org.apache.commons.math3.analysis.differentiation.DerivativeStructure; import org.apache.commons.math3.analysis.differentiation.DerivativeStructure;
import org.apache.commons.math3.analysis.differentiation.MultivariateDifferentiableVectorFunction; import org.apache.commons.math3.analysis.differentiation.MultivariateDifferentiableVectorFunction;
import org.apache.commons.math3.exception.DimensionMismatchException; import org.apache.commons.math3.exception.DimensionMismatchException;
import org.apache.commons.math3.exception.NumberIsTooSmallException; import org.apache.commons.math3.exception.NumberIsTooSmallException;
import org.apache.commons.math3.exception.util.LocalizedFormats; import org.apache.commons.math3.exception.util.LocalizedFormats;
import org.apache.commons.math3.linear.ArrayRealVector; import org.apache.commons.math3.linear.ArrayRealVector;
import org.apache.commons.math3.linear.RealMatrix;
import org.apache.commons.math3.linear.DiagonalMatrix;
import org.apache.commons.math3.linear.DecompositionSolver; import org.apache.commons.math3.linear.DecompositionSolver;
import org.apache.commons.math3.linear.DiagonalMatrix;
import org.apache.commons.math3.linear.EigenDecomposition;
import org.apache.commons.math3.linear.MatrixUtils; import org.apache.commons.math3.linear.MatrixUtils;
import org.apache.commons.math3.linear.QRDecomposition; import org.apache.commons.math3.linear.QRDecomposition;
import org.apache.commons.math3.linear.EigenDecomposition; import org.apache.commons.math3.linear.RealMatrix;
import org.apache.commons.math3.optimization.OptimizationData;
import org.apache.commons.math3.optimization.InitialGuess;
import org.apache.commons.math3.optimization.Target;
import org.apache.commons.math3.optimization.Weight;
import org.apache.commons.math3.optimization.ConvergenceChecker; import org.apache.commons.math3.optimization.ConvergenceChecker;
import org.apache.commons.math3.optimization.DifferentiableMultivariateVectorOptimizer; import org.apache.commons.math3.optimization.DifferentiableMultivariateVectorOptimizer;
import org.apache.commons.math3.optimization.InitialGuess;
import org.apache.commons.math3.optimization.OptimizationData;
import org.apache.commons.math3.optimization.PointVectorValuePair; import org.apache.commons.math3.optimization.PointVectorValuePair;
import org.apache.commons.math3.optimization.Target;
import org.apache.commons.math3.optimization.Weight;
import org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer; import org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer;
import org.apache.commons.math3.util.FastMath; import org.apache.commons.math3.util.FastMath;
@ -45,7 +46,7 @@ import org.apache.commons.math3.util.FastMath;
* Base class for implementing least squares optimizers. * Base class for implementing least squares optimizers.
* It handles the boilerplate methods associated to thresholds settings, * It handles the boilerplate methods associated to thresholds settings,
* Jacobian and error estimation. * Jacobian and error estimation.
* <br/> * <p>
* This class constructs the Jacobian matrix of the function argument in method * This class constructs the Jacobian matrix of the function argument in method
* {@link BaseAbstractMultivariateVectorOptimizer#optimize(int,MultivariateVectorFunction,OptimizationData[]) * {@link BaseAbstractMultivariateVectorOptimizer#optimize(int,MultivariateVectorFunction,OptimizationData[])
* optimize} and assumes that the rows of that matrix iterate on the model * optimize} and assumes that the rows of that matrix iterate on the model
@ -287,7 +288,7 @@ public abstract class AbstractLeastSquaresOptimizer
/** /**
* Get the covariance matrix of the optimized parameters. * Get the covariance matrix of the optimized parameters.
* <br/> * <p>
* Note that this operation involves the inversion of the * Note that this operation involves the inversion of the
* <code>J<sup>T</sup>J</code> matrix, where {@code J} is the * <code>J<sup>T</sup>J</code> matrix, where {@code J} is the
* Jacobian matrix. * Jacobian matrix.
@ -309,7 +310,7 @@ public abstract class AbstractLeastSquaresOptimizer
/** /**
* Get the covariance matrix of the optimized parameters. * Get the covariance matrix of the optimized parameters.
* <br/> * <p>
* Note that this operation involves the inversion of the * Note that this operation involves the inversion of the
* <code>J<sup>T</sup>J</code> matrix, where {@code J} is the * <code>J<sup>T</sup>J</code> matrix, where {@code J} is the
* Jacobian matrix. * Jacobian matrix.

12
src/main/java/org/apache/commons/math3/optimization/general/LevenbergMarquardtOptimizer.java
View File

@ -20,11 +20,11 @@ import java.util.Arrays;
import org.apache.commons.math3.exception.ConvergenceException; import org.apache.commons.math3.exception.ConvergenceException;
import org.apache.commons.math3.exception.util.LocalizedFormats; import org.apache.commons.math3.exception.util.LocalizedFormats;
import org.apache.commons.math3.optimization.PointVectorValuePair;
import org.apache.commons.math3.optimization.ConvergenceChecker;
import org.apache.commons.math3.linear.RealMatrix; import org.apache.commons.math3.linear.RealMatrix;
import org.apache.commons.math3.util.Precision; import org.apache.commons.math3.optimization.ConvergenceChecker;
import org.apache.commons.math3.optimization.PointVectorValuePair;
import org.apache.commons.math3.util.FastMath; import org.apache.commons.math3.util.FastMath;
import org.apache.commons.math3.util.Precision;
/** /**
@ -52,9 +52,9 @@ import org.apache.commons.math3.util.FastMath;
* </ul> * </ul>
* The redistribution policy for MINPACK is available <a * The redistribution policy for MINPACK is available <a
* href="http://www.netlib.org/minpack/disclaimer">here</a>, for convenience, it * href="http://www.netlib.org/minpack/disclaimer">here</a>, for convenience, it
* is reproduced below.</p> * is reproduced below.
* *
* <table border="0" width="80%" cellpadding="10" align="center" bgcolor="#E0E0E0"> * <table border="0" width="80%" cellpadding="10" align="center" bgcolor="#E0E0E0" summary="Copyright">
* <tr><td> * <tr><td>
* Minpack Copyright Notice (1999) University of Chicago. * Minpack Copyright Notice (1999) University of Chicago.
* All rights reserved * All rights reserved
@ -99,7 +99,7 @@ import org.apache.commons.math3.util.FastMath;
* (INCLUDING NEGLIGENCE OR STRICT LIABILITY), OR OTHERWISE, * (INCLUDING NEGLIGENCE OR STRICT LIABILITY), OR OTHERWISE,
* EVEN IF ANY OF SAID PARTIES HAS BEEN WARNED OF THE * EVEN IF ANY OF SAID PARTIES HAS BEEN WARNED OF THE
* POSSIBILITY OF SUCH LOSS OR DAMAGES.</strong></li> * POSSIBILITY OF SUCH LOSS OR DAMAGES.</strong></li>
* <ol></td></tr> * </ol></td></tr>
* </table> * </table>
* @version $Id$ * @version $Id$
* @deprecated As of 3.1 (to be removed in 4.0). * @deprecated As of 3.1 (to be removed in 4.0).

4
src/main/java/org/apache/commons/math3/optimization/package-info.java
View File

@ -16,12 +16,11 @@
*/ */
/** /**
* <h2>All classes and sub-packages of this package are deprecated.</h2> * <h2>All classes and sub-packages of this package are deprecated.</h2>
* <h3>Please use their replacements, to be found under * <h3>Please use their replacements, to be found under:</h3>
* <ul> * <ul>
* <li>{@link org.apache.commons.math3.optim}</li> * <li>{@link org.apache.commons.math3.optim}</li>
* <li>{@link org.apache.commons.math3.fitting}</li> * <li>{@link org.apache.commons.math3.fitting}</li>
* </ul> * </ul>
* </h3>
* *
* <p> * <p>
* This package provides common interfaces for the optimization algorithms * This package provides common interfaces for the optimization algorithms
@ -54,7 +53,6 @@
* org.apache.commons.math3.analysis.differentiation.MultivariateDifferentiableVectorFunction * org.apache.commons.math3.analysis.differentiation.MultivariateDifferentiableVectorFunction
* multivariate differentiable vectorial functions}</li> * multivariate differentiable vectorial functions}</li>
* </ul> * </ul>
* </p>
* *
* <p> * <p>
* Despite there are only four types of supported optimizers, it is possible to optimize a * Despite there are only four types of supported optimizers, it is possible to optimize a

8
src/main/java/org/apache/commons/math3/optimization/univariate/BrentOptimizer.java
View File

@ -16,12 +16,12 @@
*/ */
package org.apache.commons.math3.optimization.univariate; package org.apache.commons.math3.optimization.univariate;
import org.apache.commons.math3.util.Precision;
import org.apache.commons.math3.util.FastMath;
import org.apache.commons.math3.exception.NumberIsTooSmallException;
import org.apache.commons.math3.exception.NotStrictlyPositiveException; import org.apache.commons.math3.exception.NotStrictlyPositiveException;
import org.apache.commons.math3.exception.NumberIsTooSmallException;
import org.apache.commons.math3.optimization.ConvergenceChecker; import org.apache.commons.math3.optimization.ConvergenceChecker;
import org.apache.commons.math3.optimization.GoalType; import org.apache.commons.math3.optimization.GoalType;
import org.apache.commons.math3.util.FastMath;
import org.apache.commons.math3.util.Precision;
/** /**
* For a function defined on some interval {@code (lo, hi)}, this class * For a function defined on some interval {@code (lo, hi)}, this class
@ -30,7 +30,7 @@ import org.apache.commons.math3.optimization.GoalType;
* It implements Richard Brent's algorithm (from his book "Algorithms for * It implements Richard Brent's algorithm (from his book "Algorithms for
* Minimization without Derivatives", p. 79) for finding minima of real * Minimization without Derivatives", p. 79) for finding minima of real
* univariate functions. * univariate functions.
* <br/> * <p>
* This code is an adaptation, partly based on the Python code from SciPy * This code is an adaptation, partly based on the Python code from SciPy
* (module "optimize.py" v0.5); the original algorithm is also modified * (module "optimize.py" v0.5); the original algorithm is also modified
* <ul> * <ul>

4
src/main/java/org/apache/commons/math3/optimization/univariate/SimpleUnivariateValueChecker.java
View File

@ -17,9 +17,9 @@
package org.apache.commons.math3.optimization.univariate; package org.apache.commons.math3.optimization.univariate;
import org.apache.commons.math3.util.FastMath;
import org.apache.commons.math3.exception.NotStrictlyPositiveException; import org.apache.commons.math3.exception.NotStrictlyPositiveException;
import org.apache.commons.math3.optimization.AbstractConvergenceChecker; import org.apache.commons.math3.optimization.AbstractConvergenceChecker;
import org.apache.commons.math3.util.FastMath;
/** /**
* Simple implementation of the * Simple implementation of the
@ -30,7 +30,7 @@ import org.apache.commons.math3.optimization.AbstractConvergenceChecker;
* difference between the objective function values is smaller than a * difference between the objective function values is smaller than a
* threshold or if either the absolute difference between the objective * threshold or if either the absolute difference between the objective
* function values is smaller than another threshold. * function values is smaller than another threshold.
* <br/> * <p>
* The {@link #converged(int,UnivariatePointValuePair,UnivariatePointValuePair) * The {@link #converged(int,UnivariatePointValuePair,UnivariatePointValuePair)
* converged} method will also return {@code true} if the number of iterations * converged} method will also return {@code true} if the number of iterations
* has been set (see {@link #SimpleUnivariateValueChecker(double,double,int) * has been set (see {@link #SimpleUnivariateValueChecker(double,double,int)

8
src/main/java/org/apache/commons/math3/optimization/univariate/UnivariateMultiStartOptimizer.java
View File

@ -25,14 +25,14 @@ import org.apache.commons.math3.exception.MathIllegalStateException;
import org.apache.commons.math3.exception.NotStrictlyPositiveException; import org.apache.commons.math3.exception.NotStrictlyPositiveException;
import org.apache.commons.math3.exception.NullArgumentException; import org.apache.commons.math3.exception.NullArgumentException;
import org.apache.commons.math3.exception.util.LocalizedFormats; import org.apache.commons.math3.exception.util.LocalizedFormats;
import org.apache.commons.math3.random.RandomGenerator;
import org.apache.commons.math3.optimization.GoalType;
import org.apache.commons.math3.optimization.ConvergenceChecker; import org.apache.commons.math3.optimization.ConvergenceChecker;
import org.apache.commons.math3.optimization.GoalType;
import org.apache.commons.math3.random.RandomGenerator;
/** /**
* Special implementation of the {@link UnivariateOptimizer} interface * Special implementation of the {@link UnivariateOptimizer} interface
* adding multi-start features to an existing optimizer. * adding multi-start features to an existing optimizer.
* * <p>
* This class wraps a classical optimizer to use it several times in * This class wraps a classical optimizer to use it several times in
* turn with different starting points in order to avoid being trapped * turn with different starting points in order to avoid being trapped
* into a local extremum when looking for a global one. * into a local extremum when looking for a global one.
@ -113,7 +113,7 @@ public class UnivariateMultiStartOptimizer<FUNC extends UnivariateFunction>
* found at the end of each starts, including the best one already * found at the end of each starts, including the best one already
* returned by the {@link #optimize(int,UnivariateFunction,GoalType,double,double) optimize} * returned by the {@link #optimize(int,UnivariateFunction,GoalType,double,double) optimize}
* method. * method.
* <br/> * <p>
* The returned array as one element for each start as specified * The returned array as one element for each start as specified
* in the constructor. It is ordered with the results from the * in the constructor. It is ordered with the results from the
* runs that did converge first, sorted from best to worst * runs that did converge first, sorted from best to worst

15
src/main/java/org/apache/commons/math3/util/ArithmeticUtils.java
View File

@ -85,7 +85,7 @@ public final class ArithmeticUtils {
* {@code < Long.MAX_VALUE} is 66. If the computed value exceeds * {@code < Long.MAX_VALUE} is 66. If the computed value exceeds
* {@code Long.MAX_VALUE} an {@code ArithMeticException} is * {@code Long.MAX_VALUE} an {@code ArithMeticException} is
* thrown.</li> * thrown.</li>
* </ul></p> * </ul>
* *
* @param n the size of the set * @param n the size of the set
* @param k the size of the subsets to be counted * @param k the size of the subsets to be counted
@ -114,10 +114,10 @@ public final class ArithmeticUtils {
* <li> {@code 0 <= k <= n } (otherwise * <li> {@code 0 <= k <= n } (otherwise
* {@code IllegalArgumentException} is thrown)</li> * {@code IllegalArgumentException} is thrown)</li>
* <li> The result is small enough to fit into a {@code double}. The * <li> The result is small enough to fit into a {@code double}. The
* largest value of {@code n} for which all coefficients are < * largest value of {@code n} for which all coefficients are &lt;
* Double.MAX_VALUE is 1029. If the computed value exceeds Double.MAX_VALUE, * Double.MAX_VALUE is 1029. If the computed value exceeds Double.MAX_VALUE,
* Double.POSITIVE_INFINITY is returned</li> * Double.POSITIVE_INFINITY is returned</li>
* </ul></p> * </ul>
* *
* @param n the size of the set * @param n the size of the set
* @param k the size of the subsets to be counted * @param k the size of the subsets to be counted
@ -145,7 +145,7 @@ public final class ArithmeticUtils {
* <ul> * <ul>
* <li> {@code 0 <= k <= n } (otherwise * <li> {@code 0 <= k <= n } (otherwise
* {@code IllegalArgumentException} is thrown)</li> * {@code IllegalArgumentException} is thrown)</li>
* </ul></p> * </ul>
* *
* @param n the size of the set * @param n the size of the set
* @param k the size of the subsets to be counted * @param k the size of the subsets to be counted
@ -172,11 +172,10 @@ public final class ArithmeticUtils {
* <li> {@code n >= 0} (otherwise * <li> {@code n >= 0} (otherwise
* {@code IllegalArgumentException} is thrown)</li> * {@code IllegalArgumentException} is thrown)</li>
* <li> The result is small enough to fit into a {@code long}. The * <li> The result is small enough to fit into a {@code long}. The
* largest value of {@code n} for which {@code n!} < * largest value of {@code n} for which {@code n!} &lt;
* Long.MAX_VALUE} is 20. If the computed value exceeds {@code Long.MAX_VALUE} * Long.MAX_VALUE} is 20. If the computed value exceeds {@code Long.MAX_VALUE}
* an {@code ArithMeticException } is thrown.</li> * an {@code ArithMeticException } is thrown.</li>
* </ul> * </ul>
* </p>
* *
* @param n argument * @param n argument
* @return {@code n!} * @return {@code n!}
@ -229,7 +228,7 @@ public final class ArithmeticUtils {
* numbers, using a modified version of the "binary gcd" method. * numbers, using a modified version of the "binary gcd" method.
* See Knuth 4.5.2 algorithm B. * See Knuth 4.5.2 algorithm B.
* The algorithm is due to Josef Stein (1961). * The algorithm is due to Josef Stein (1961).
* <br/> * <p>
* Special cases: * Special cases:
* <ul> * <ul>
* <li>The invocations * <li>The invocations
@ -316,7 +315,7 @@ public final class ArithmeticUtils {
* and modulo operations. * and modulo operations.
* See Knuth 4.5.2 algorithm B. * See Knuth 4.5.2 algorithm B.
* The algorithm is due to Josef Stein (1961). * The algorithm is due to Josef Stein (1961).
* <br/> * <p>
* Special cases: * Special cases:
* <ul> * <ul>
* <li>The result of {@code gcd(x, x)}, {@code gcd(0, x)} and * <li>The result of {@code gcd(x, x)}, {@code gcd(0, x)} and

17
src/main/java/org/apache/commons/math3/util/Combinations.java
View File

@ -16,13 +16,14 @@
*/ */
package org.apache.commons.math3.util; package org.apache.commons.math3.util;
import java.util.Iterator;
import java.util.Comparator;
import java.util.Arrays;
import java.util.NoSuchElementException;
import java.io.Serializable; import java.io.Serializable;
import org.apache.commons.math3.exception.MathInternalError; import java.util.Arrays;
import java.util.Comparator;
import java.util.Iterator;
import java.util.NoSuchElementException;
import org.apache.commons.math3.exception.DimensionMismatchException; import org.apache.commons.math3.exception.DimensionMismatchException;
import org.apache.commons.math3.exception.MathInternalError;
import org.apache.commons.math3.exception.OutOfRangeException; import org.apache.commons.math3.exception.OutOfRangeException;
/** /**
@ -61,8 +62,7 @@ public class Combinations implements Iterable<int[]> {
* For example, {@code new Combinations(4, 2).iterator()} returns * For example, {@code new Combinations(4, 2).iterator()} returns
* an iterator that will generate the following sequence of arrays * an iterator that will generate the following sequence of arrays
* on successive calls to * on successive calls to
* {@code next()}:<br/> * {@code next()}: {@code [0, 1], [0, 2], [1, 2], [0, 3], [1, 3], [2, 3]}
* {@code [0, 1], [0, 2], [1, 2], [0, 3], [1, 3], [2, 3]}
* </p> * </p>
* If {@code k == 0} an iterator containing an empty array is returned; * If {@code k == 0} an iterator containing an empty array is returned;
* if {@code k == n} an iterator containing [0, ..., n - 1] is returned. * if {@code k == n} an iterator containing [0, ..., n - 1] is returned.
@ -89,8 +89,7 @@ public class Combinations implements Iterable<int[]> {
* For example, {@code new Combinations(4, 2).iterator()} returns * For example, {@code new Combinations(4, 2).iterator()} returns
* an iterator that will generate the following sequence of arrays * an iterator that will generate the following sequence of arrays
* on successive calls to * on successive calls to
* {@code next()}:<br/> * {@code next()}: {@code [0, 1], [0, 2], [1, 2], [0, 3], [1, 3], [2, 3]}
* {@code [0, 1], [0, 2], [1, 2], [0, 3], [1, 3], [2, 3]}
* </p> * </p>
* If {@code k == 0} an iterator containing an empty array is returned; * If {@code k == 0} an iterator containing an empty array is returned;
* if {@code k == n} an iterator containing [0, ..., n - 1] is returned. * if {@code k == n} an iterator containing [0, ..., n - 1] is returned.

16
src/main/java/org/apache/commons/math3/util/CombinatoricsUtils.java
View File

@ -67,7 +67,7 @@ public final class CombinatoricsUtils {
* {@code < Long.MAX_VALUE} is 66. If the computed value exceeds * {@code < Long.MAX_VALUE} is 66. If the computed value exceeds
* {@code Long.MAX_VALUE} an {@code ArithMeticException} is * {@code Long.MAX_VALUE} an {@code ArithMeticException} is
* thrown.</li> * thrown.</li>
* </ul></p> * </ul>
* *
* @param n the size of the set * @param n the size of the set
* @param k the size of the subsets to be counted * @param k the size of the subsets to be counted
@ -145,10 +145,10 @@ public final class CombinatoricsUtils {
* <li> {@code 0 <= k <= n } (otherwise * <li> {@code 0 <= k <= n } (otherwise
* {@code IllegalArgumentException} is thrown)</li> * {@code IllegalArgumentException} is thrown)</li>
* <li> The result is small enough to fit into a {@code double}. The * <li> The result is small enough to fit into a {@code double}. The
* largest value of {@code n} for which all coefficients are < * largest value of {@code n} for which all coefficients are &lt;
* Double.MAX_VALUE is 1029. If the computed value exceeds Double.MAX_VALUE, * Double.MAX_VALUE is 1029. If the computed value exceeds Double.MAX_VALUE,
* Double.POSITIVE_INFINITY is returned</li> * Double.POSITIVE_INFINITY is returned</li>
* </ul></p> * </ul>
* *
* @param n the size of the set * @param n the size of the set
* @param k the size of the subsets to be counted * @param k the size of the subsets to be counted
@ -193,7 +193,7 @@ public final class CombinatoricsUtils {
* <ul> * <ul>
* <li> {@code 0 <= k <= n } (otherwise * <li> {@code 0 <= k <= n } (otherwise
* {@code IllegalArgumentException} is thrown)</li> * {@code IllegalArgumentException} is thrown)</li>
* </ul></p> * </ul>
* *
* @param n the size of the set * @param n the size of the set
* @param k the size of the subsets to be counted * @param k the size of the subsets to be counted
@ -261,11 +261,10 @@ public final class CombinatoricsUtils {
* <li> {@code n >= 0} (otherwise * <li> {@code n >= 0} (otherwise
* {@code IllegalArgumentException} is thrown)</li> * {@code IllegalArgumentException} is thrown)</li>
* <li> The result is small enough to fit into a {@code long}. The * <li> The result is small enough to fit into a {@code long}. The
* largest value of {@code n} for which {@code n!} < * largest value of {@code n} for which {@code n!} &lt;
* Long.MAX_VALUE} is 20. If the computed value exceeds {@code Long.MAX_VALUE} * Long.MAX_VALUE} is 20. If the computed value exceeds {@code Long.MAX_VALUE}
* an {@code ArithMeticException } is thrown.</li> * an {@code ArithMeticException } is thrown.</li>
* </ul> * </ul>
* </p>
* *
* @param n argument * @param n argument
* @return {@code n!} * @return {@code n!}
@ -341,7 +340,7 @@ public final class CombinatoricsUtils {
* <p> * <p>
* The preconditions are {@code 0 <= k <= n } (otherwise * The preconditions are {@code 0 <= k <= n } (otherwise
* {@code NotPositiveException} is thrown) * {@code NotPositiveException} is thrown)
* </p> *
* @param n the size of the set * @param n the size of the set
* @param k the number of non-empty subsets * @param k the number of non-empty subsets
* @return {@code S(n,k)} * @return {@code S(n,k)}
@ -426,8 +425,7 @@ public final class CombinatoricsUtils {
* they are visited in lexicographic order with significance from right to * they are visited in lexicographic order with significance from right to
* left. For example, combinationsIterator(4, 2) returns an Iterator that * left. For example, combinationsIterator(4, 2) returns an Iterator that
* will generate the following sequence of arrays on successive calls to * will generate the following sequence of arrays on successive calls to
* {@code next()}:<br/> * {@code next()}: {@code [0, 1], [0, 2], [1, 2], [0, 3], [1, 3], [2, 3]}
* {@code [0, 1], [0, 2], [1, 2], [0, 3], [1, 3], [2, 3]}
* </p> * </p>
* If {@code k == 0} an Iterator containing an empty array is returned and * If {@code k == 0} an Iterator containing an empty array is returned and
* if {@code k == n} an Iterator containing [0, ..., n -1] is returned. * if {@code k == n} an Iterator containing [0, ..., n -1] is returned.

3
src/main/java/org/apache/commons/math3/util/ContinuedFraction.java
View File

@ -23,14 +23,12 @@ import org.apache.commons.math3.exception.util.LocalizedFormats;
/** /**
* Provides a generic means to evaluate continued fractions. Subclasses simply * Provides a generic means to evaluate continued fractions. Subclasses simply
* provided the a and b coefficients to evaluate the continued fraction. * provided the a and b coefficients to evaluate the continued fraction.
*
* <p> * <p>
* References: * References:
* <ul> * <ul>
* <li><a href="http://mathworld.wolfram.com/ContinuedFraction.html"> * <li><a href="http://mathworld.wolfram.com/ContinuedFraction.html">
* Continued Fraction</a></li> * Continued Fraction</a></li>
* </ul> * </ul>
* </p>
* *
* @version $Id$ * @version $Id$
*/ */
@ -111,7 +109,6 @@ public abstract class ContinuedFraction {
* </ul> * </ul>
* <b>Note:</b> the implementation uses the terms a<sub>i</sub> and b<sub>i</sub> as defined in * <b>Note:</b> the implementation uses the terms a<sub>i</sub> and b<sub>i</sub> as defined in
* <a href="http://mathworld.wolfram.com/ContinuedFraction.html">Continued Fraction @ MathWorld</a>. * <a href="http://mathworld.wolfram.com/ContinuedFraction.html">Continued Fraction @ MathWorld</a>.
* </p>
* *
* @param x the evaluation point. * @param x the evaluation point.
* @param epsilon maximum error allowed. * @param epsilon maximum error allowed.

18
src/main/java/org/apache/commons/math3/util/FastMath.java
View File

@ -27,13 +27,11 @@ import java.io.PrintStream;
* {@code Math.cbrt(y)}), user can directly change the class and use the * {@code Math.cbrt(y)}), user can directly change the class and use the
* methods as is (using {@code FastMath.sin(x)} or {@code FastMath.cbrt(y)} * methods as is (using {@code FastMath.sin(x)} or {@code FastMath.cbrt(y)}
* in the previous example). * in the previous example).
* </p>
* <p> * <p>
* FastMath speed is achieved by relying heavily on optimizing compilers * FastMath speed is achieved by relying heavily on optimizing compilers
* to native code present in many JVMs today and use of large tables. * to native code present in many JVMs today and use of large tables.
* The larger tables are lazily initialised on first use, so that the setup * The larger tables are lazily initialised on first use, so that the setup
* time does not penalise methods that don't need them. * time does not penalise methods that don't need them.
* </p>
* <p> * <p>
* Note that FastMath is * Note that FastMath is
* extensively used inside Apache Commons Math, so by calling some algorithms, * extensively used inside Apache Commons Math, so by calling some algorithms,
@ -42,7 +40,6 @@ import java.io.PrintStream;
* Performance figures for a specific JVM and hardware can be evaluated by * Performance figures for a specific JVM and hardware can be evaluated by
* running the FastMathTestPerformance tests in the test directory of the source * running the FastMathTestPerformance tests in the test directory of the source
* distribution. * distribution.
* </p>
* <p> * <p>
* FastMath accuracy should be mostly independent of the JVM as it relies only * FastMath accuracy should be mostly independent of the JVM as it relies only
* on IEEE-754 basic operations and on embedded tables. Almost all operations * on IEEE-754 basic operations and on embedded tables. Almost all operations
@ -51,7 +48,6 @@ import java.io.PrintStream;
* guarantee for <em>every</em> double numbers input (see William Kahan's <a * guarantee for <em>every</em> double numbers input (see William Kahan's <a
* href="http://en.wikipedia.org/wiki/Rounding#The_table-maker.27s_dilemma">Table * href="http://en.wikipedia.org/wiki/Rounding#The_table-maker.27s_dilemma">Table
* Maker's Dilemma</a>). * Maker's Dilemma</a>).
* </p>
* <p> * <p>
* FastMath additionally implements the following methods not found in Math/StrictMath: * FastMath additionally implements the following methods not found in Math/StrictMath:
* <ul> * <ul>
@ -73,7 +69,7 @@ import java.io.PrintStream;
* <li>{@link #nextUp(float)}</li> * <li>{@link #nextUp(float)}</li>
* <li>{@link #scalb(float, int)}</li> * <li>{@link #scalb(float, int)}</li>
* </ul> * </ul>
* </p> *
* @version $Id$ * @version $Id$
* @since 2.2 * @since 2.2
*/ */
@ -3237,7 +3233,7 @@ public class FastMath {
* <li>+MIN_VALUE</li> * <li>+MIN_VALUE</li>
* <li>+MAX_VALUE</li> * <li>+MAX_VALUE</li>
* <li>+INFINITY</li> * <li>+INFINITY</li>
* <li></li> * </ul>
* <p> * <p>
* If arguments compare equal, then the second argument is returned. * If arguments compare equal, then the second argument is returned.
* <p> * <p>
@ -3293,7 +3289,7 @@ public class FastMath {
* <li>+MIN_VALUE</li> * <li>+MIN_VALUE</li>
* <li>+MAX_VALUE</li> * <li>+MAX_VALUE</li>
* <li>+INFINITY</li> * <li>+INFINITY</li>
* <li></li> * </ul>
* <p> * <p>
* If arguments compare equal, then the second argument is returned. * If arguments compare equal, then the second argument is returned.
* <p> * <p>
@ -3337,7 +3333,7 @@ public class FastMath {
/** Get the largest whole number smaller than x. /** Get the largest whole number smaller than x.
* @param x number from which floor is requested * @param x number from which floor is requested
* @return a double number f such that f is an integer f <= x < f + 1.0 * @return a double number f such that f is an integer f &le; x &lt; f + 1.0
*/ */
public static double floor(double x) { public static double floor(double x) {
long y; long y;
@ -3364,7 +3360,7 @@ public class FastMath {
/** Get the smallest whole number larger than x. /** Get the smallest whole number larger than x.
* @param x number from which ceil is requested * @param x number from which ceil is requested
* @return a double number c such that c is an integer c - 1.0 < x <= c * @return a double number c such that c is an integer c - 1.0 &lt; x &le; c
*/ */
public static double ceil(double x) { public static double ceil(double x) {
double y; double y;
@ -3389,7 +3385,7 @@ public class FastMath {
/** Get the whole number that is the nearest to x, or the even one if x is exactly half way between two integers. /** Get the whole number that is the nearest to x, or the even one if x is exactly half way between two integers.
* @param x number from which nearest whole number is requested * @param x number from which nearest whole number is requested
* @return a double number r such that r is an integer r - 0.5 <= x <= r + 0.5 * @return a double number r such that r is an integer r - 0.5 &le; x &le; r + 0.5
*/ */
public static double rint(double x) { public static double rint(double x) {
double y = floor(x); double y = floor(x);
@ -3564,7 +3560,7 @@ public class FastMath {
/** /**
* Returns the hypotenuse of a triangle with sides {@code x} and {@code y} * Returns the hypotenuse of a triangle with sides {@code x} and {@code y}
* - sqrt(<i>x</i><sup>2</sup>&nbsp;+<i>y</i><sup>2</sup>)<br/> * - sqrt(<i>x</i><sup>2</sup>&nbsp;+<i>y</i><sup>2</sup>)
* avoiding intermediate overflow or underflow. * avoiding intermediate overflow or underflow.
* *
* <ul> * <ul>

53
src/main/java/org/apache/commons/math3/util/MathArrays.java
View File

@ -25,8 +25,6 @@ import java.util.Comparator;
import java.util.List; import java.util.List;
import org.apache.commons.math3.Field; import org.apache.commons.math3.Field;
import org.apache.commons.math3.random.RandomGenerator;
import org.apache.commons.math3.random.Well19937c;
import org.apache.commons.math3.distribution.UniformIntegerDistribution; import org.apache.commons.math3.distribution.UniformIntegerDistribution;
import org.apache.commons.math3.exception.DimensionMismatchException; import org.apache.commons.math3.exception.DimensionMismatchException;
import org.apache.commons.math3.exception.MathArithmeticException; import org.apache.commons.math3.exception.MathArithmeticException;
@ -39,6 +37,8 @@ import org.apache.commons.math3.exception.NotStrictlyPositiveException;
import org.apache.commons.math3.exception.NullArgumentException; import org.apache.commons.math3.exception.NullArgumentException;
import org.apache.commons.math3.exception.NumberIsTooLargeException; import org.apache.commons.math3.exception.NumberIsTooLargeException;
import org.apache.commons.math3.exception.util.LocalizedFormats; import org.apache.commons.math3.exception.util.LocalizedFormats;
import org.apache.commons.math3.random.RandomGenerator;
import org.apache.commons.math3.random.Well19937c;
/** /**
* Arrays utilities. * Arrays utilities.
@ -95,9 +95,9 @@ public class MathArrays {
} }
/** /**
* <p>Multiply each element of an array by a value.</p> * Multiply each element of an array by a value.
* * <p>
* <p>The array is modified in place (no copy is created).</p> * The array is modified in place (no copy is created).
* *
* @param arr Array to scale * @param arr Array to scale
* @param val Scalar * @param val Scalar
@ -490,7 +490,7 @@ public class MathArrays {
} }
/** /**
* Check that all entries of the input array are >= 0. * Check that all entries of the input array are &ge; 0.
* *
* @param in Array to be tested * @param in Array to be tested
* @throws NotPositiveException if any array entries are less than 0. * @throws NotPositiveException if any array entries are less than 0.
@ -506,7 +506,7 @@ public class MathArrays {
} }
/** /**
* Check all entries of the input array are >= 0. * Check all entries of the input array are &ge; 0.
* *
* @param in Array to be tested * @param in Array to be tested
* @throws NotPositiveException if any array entries are less than 0. * @throws NotPositiveException if any array entries are less than 0.
@ -526,12 +526,12 @@ public class MathArrays {
/** /**
* Returns the Cartesian norm (2-norm), handling both overflow and underflow. * Returns the Cartesian norm (2-norm), handling both overflow and underflow.
* Translation of the minpack enorm subroutine. * Translation of the minpack enorm subroutine.
* * <p>
* The redistribution policy for MINPACK is available * The redistribution policy for MINPACK is available
* <a href="http://www.netlib.org/minpack/disclaimer">here</a>, for * <a href="http://www.netlib.org/minpack/disclaimer">here</a>, for
* convenience, it is reproduced below.</p> * convenience, it is reproduced below.
* * <p>
* <table border="0" width="80%" cellpadding="10" align="center" bgcolor="#E0E0E0"> * <table border="0" width="80%" cellpadding="10" align="center" bgcolor="#E0E0E0" summary="Copyright">
* <tr><td> * <tr><td>
* Minpack Copyright Notice (1999) University of Chicago. * Minpack Copyright Notice (1999) University of Chicago.
* All rights reserved * All rights reserved
@ -576,7 +576,7 @@ public class MathArrays {
* (INCLUDING NEGLIGENCE OR STRICT LIABILITY), OR OTHERWISE, * (INCLUDING NEGLIGENCE OR STRICT LIABILITY), OR OTHERWISE,
* EVEN IF ANY OF SAID PARTIES HAS BEEN WARNED OF THE * EVEN IF ANY OF SAID PARTIES HAS BEEN WARNED OF THE
* POSSIBILITY OF SUCH LOSS OR DAMAGES.</strong></li> * POSSIBILITY OF SUCH LOSS OR DAMAGES.</strong></li>
* <ol></td></tr> * </ol></td></tr>
* </table> * </table>
* *
* @param v Vector of doubles. * @param v Vector of doubles.
@ -804,7 +804,7 @@ public class MathArrays {
* <code>a<sub>i</sub> b<sub>i</sub></code> to high accuracy. * <code>a<sub>i</sub> b<sub>i</sub></code> to high accuracy.
* It does so by using specific multiplication and addition algorithms to * It does so by using specific multiplication and addition algorithms to
* preserve accuracy and reduce cancellation effects. * preserve accuracy and reduce cancellation effects.
* <br/> * <p>
* It is based on the 2005 paper * It is based on the 2005 paper
* <a href="http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.2.1547"> * <a href="http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.2.1547">
* Accurate Sum and Dot Product</a> by Takeshi Ogita, Siegfried M. Rump, * Accurate Sum and Dot Product</a> by Takeshi Ogita, Siegfried M. Rump,
@ -1277,7 +1277,7 @@ public class MathArrays {
* Normalizes an array to make it sum to a specified value. * Normalizes an array to make it sum to a specified value.
* Returns the result of the transformation * Returns the result of the transformation
* <pre> * <pre>
* x |-> x * normalizedSum / sum * x |-&gt; x * normalizedSum / sum
* </pre> * </pre>
* applied to each non-NaN element x of the input array, where sum is the * applied to each non-NaN element x of the input array, where sum is the
* sum of the non-NaN entries in the input array. * sum of the non-NaN entries in the input array.
@ -1458,7 +1458,7 @@ public class MathArrays {
/** /**
* Shuffle the entries of the given array, using the * Shuffle the entries of the given array, using the
* <a href="http://en.wikipedia.org/wiki/Fisher–Yates_shuffle#The_modern_algorithm"> * <a href="http://en.wikipedia.org/wiki/Fisher-Yates_shuffle#The_modern_algorithm">
* Fisher–Yates</a> algorithm. * Fisher–Yates</a> algorithm.
* The {@code start} and {@code pos} parameters select which portion * The {@code start} and {@code pos} parameters select which portion
* of the array is randomized and which is left untouched. * of the array is randomized and which is left untouched.
@ -1557,9 +1557,8 @@ public class MathArrays {
* positive length</li> * positive length</li>
* <li>throws <code>MathIllegalArgumentException</code> if the array is null or * <li>throws <code>MathIllegalArgumentException</code> if the array is null or
* or the indices are invalid</li> * or the indices are invalid</li>
* <li>returns <code>false</li> if the array is non-null, but * <li>returns <code>false</code> if the array is non-null, but <code>length</code> is 0.</li>
* <code>length</code> is 0. * </ul>
* </ul></p>
* *
* @param values the input array * @param values the input array
* @param begin index of the first array element to include * @param begin index of the first array element to include
@ -1582,9 +1581,9 @@ public class MathArrays {
* non-negative length</li> * non-negative length</li>
* <li>throws <code>IllegalArgumentException</code> if the array is null or * <li>throws <code>IllegalArgumentException</code> if the array is null or
* or the indices are invalid</li> * or the indices are invalid</li>
* <li>returns <code>false</li> if the array is non-null, but * <li>returns <code>false</code> if the array is non-null, but
* <code>length</code> is 0 unless <code>allowEmpty</code> is <code>true</code> * <code>length</code> is 0 unless <code>allowEmpty</code> is <code>true</code></li>
* </ul></p> * </ul>
* *
* @param values the input array * @param values the input array
* @param begin index of the first array element to include * @param begin index of the first array element to include
@ -1639,9 +1638,9 @@ public class MathArrays {
* <li>the weights array contains negative values</li> * <li>the weights array contains negative values</li>
* <li>the start and length arguments do not determine a valid array</li></ul> * <li>the start and length arguments do not determine a valid array</li></ul>
* </li> * </li>
* <li>returns <code>false</li> if the array is non-null, but * <li>returns <code>false</code> if the array is non-null, but
* <code>length</code> is 0. * <code>length</code> is 0.</li>
* </ul></p> * </ul>
* *
* @param values the input array * @param values the input array
* @param weights the weights array * @param weights the weights array
@ -1676,9 +1675,9 @@ public class MathArrays {
* <li>the weights array contains negative values</li> * <li>the weights array contains negative values</li>
* <li>the start and length arguments do not determine a valid array</li></ul> * <li>the start and length arguments do not determine a valid array</li></ul>
* </li> * </li>
* <li>returns <code>false</li> if the array is non-null, but * <li>returns <code>false</code> if the array is non-null, but
* <code>length</code> is 0 unless <code>allowEmpty</code> is <code>true</code>. * <code>length</code> is 0 unless <code>allowEmpty</code> is <code>true</code>.</li>
* </ul></p> * </ul>
* *
* @param values the input array. * @param values the input array.
* @param weights the weights array. * @param weights the weights array.

20
src/main/java/org/apache/commons/math3/util/MathUtils.java
View File

@ -84,9 +84,9 @@ public final class MathUtils {
* Normalize an angle in a 2&pi; wide interval around a center value. * Normalize an angle in a 2&pi; wide interval around a center value.
* <p>This method has three main uses:</p> * <p>This method has three main uses:</p>
* <ul> * <ul>
* <li>normalize an angle between 0 and 2&pi;:<br/> * <li>normalize an angle between 0 and 2&pi;:<br>
* {@code a = MathUtils.normalizeAngle(a, FastMath.PI);}</li> * {@code a = MathUtils.normalizeAngle(a, FastMath.PI);}</li>
* <li>normalize an angle between -&pi; and +&pi;<br/> * <li>normalize an angle between -&pi; and +&pi;<br>
* {@code a = MathUtils.normalizeAngle(a, 0.0);}</li> * {@code a = MathUtils.normalizeAngle(a, 0.0);}</li>
* <li>compute the angle between two defining angular positions:<br> * <li>compute the angle between two defining angular positions:<br>
* {@code angle = MathUtils.normalizeAngle(end, start) - start;}</li> * {@code angle = MathUtils.normalizeAngle(end, start) - start;}</li>
@ -104,14 +104,14 @@ public final class MathUtils {
} }
/** /**
* <p>Reduce {@code |a - offset|} to the primary interval * Reduce {@code |a - offset|} to the primary interval
* {@code [0, |period|)}.</p> * {@code [0, |period|)}.
* * <p>
* <p>Specifically, the value returned is <br/> * Specifically, the value returned is <br>
* {@code a - |period| * floor((a - offset) / |period|) - offset}.</p> * {@code a - |period| * floor((a - offset) / |period|) - offset}.
* * <p>
* <p>If any of the parameters are {@code NaN} or infinite, the result is * If any of the parameters are {@code NaN} or infinite, the result is
* {@code NaN}.</p> * {@code NaN}.
* *
* @param a Value to reduce. * @param a Value to reduce.
* @param period Period. * @param period Period.

2
src/main/java/org/apache/commons/math3/util/Pair.java
View File

@ -18,7 +18,7 @@ package org.apache.commons.math3.util;
/** /**
* Generic pair. * Generic pair.
* <br/> * <p>
* Although the instances of this class are immutable, it is impossible * Although the instances of this class are immutable, it is impossible
* to ensure that the references passed to the constructor will not be * to ensure that the references passed to the constructor will not be
* modified by the caller. * modified by the caller.

6
src/main/java/org/apache/commons/math3/util/Precision.java
View File

@ -47,7 +47,7 @@ public class Precision {
/** /**
* Safe minimum, such that {@code 1 / SAFE_MIN} does not overflow. * Safe minimum, such that {@code 1 / SAFE_MIN} does not overflow.
* <br/> * <p>
* In IEEE 754 arithmetic, this is also the smallest normalized * In IEEE 754 arithmetic, this is also the smallest normalized
* number 2<sup>-1022</sup>. * number 2<sup>-1022</sup>.
*/ */
@ -92,7 +92,7 @@ public class Precision {
* @param eps the amount of error to allow when checking for equality * @param eps the amount of error to allow when checking for equality
* @return <ul><li>0 if {@link #equals(double, double, double) equals(x, y, eps)}</li> * @return <ul><li>0 if {@link #equals(double, double, double) equals(x, y, eps)}</li>
* <li>&lt; 0 if !{@link #equals(double, double, double) equals(x, y, eps)} &amp;&amp; x &lt; y</li> * <li>&lt; 0 if !{@link #equals(double, double, double) equals(x, y, eps)} &amp;&amp; x &lt; y</li>
* <li>> 0 if !{@link #equals(double, double, double) equals(x, y, eps)} &amp;&amp; x > y</li></ul> * <li>&gt; 0 if !{@link #equals(double, double, double) equals(x, y, eps)} &amp;&amp; x &gt; y</li></ul>
*/ */
public static int compareTo(double x, double y, double eps) { public static int compareTo(double x, double y, double eps) {
if (equals(x, y, eps)) { if (equals(x, y, eps)) {
@ -118,7 +118,7 @@ public class Precision {
* values between {@code x} and {@code y}. * values between {@code x} and {@code y}.
* @return <ul><li>0 if {@link #equals(double, double, int) equals(x, y, maxUlps)}</li> * @return <ul><li>0 if {@link #equals(double, double, int) equals(x, y, maxUlps)}</li>
* <li>&lt; 0 if !{@link #equals(double, double, int) equals(x, y, maxUlps)} &amp;&amp; x &lt; y</li> * <li>&lt; 0 if !{@link #equals(double, double, int) equals(x, y, maxUlps)} &amp;&amp; x &lt; y</li>
* <li>> 0 if !{@link #equals(double, double, int) equals(x, y, maxUlps)} &amp;&amp; x > y</li></ul> * <li>&gt; 0 if !{@link #equals(double, double, int) equals(x, y, maxUlps)} &amp;&amp; x &gt; y</li></ul>
*/ */
public static int compareTo(final double x, final double y, final int maxUlps) { public static int compareTo(final double x, final double y, final int maxUlps) {
if (equals(x, y, maxUlps)) { if (equals(x, y, maxUlps)) {

70
src/main/java/org/apache/commons/math3/util/ResizableDoubleArray.java
View File

@ -22,8 +22,8 @@ import java.util.Arrays;
import org.apache.commons.math3.exception.MathIllegalArgumentException; import org.apache.commons.math3.exception.MathIllegalArgumentException;
import org.apache.commons.math3.exception.MathIllegalStateException; import org.apache.commons.math3.exception.MathIllegalStateException;
import org.apache.commons.math3.exception.MathInternalError; import org.apache.commons.math3.exception.MathInternalError;
import org.apache.commons.math3.exception.NullArgumentException;
import org.apache.commons.math3.exception.NotStrictlyPositiveException; import org.apache.commons.math3.exception.NotStrictlyPositiveException;
import org.apache.commons.math3.exception.NullArgumentException;
import org.apache.commons.math3.exception.NumberIsTooSmallException; import org.apache.commons.math3.exception.NumberIsTooSmallException;
import org.apache.commons.math3.exception.util.LocalizedFormats; import org.apache.commons.math3.exception.util.LocalizedFormats;
@ -220,7 +220,6 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
* <li>{@code expansionMode = MULTIPLICATIVE}</li> * <li>{@code expansionMode = MULTIPLICATIVE}</li>
* <li>{@code contractionCriterion = 0.5 + expansionFactor}</li> * <li>{@code contractionCriterion = 0.5 + expansionFactor}</li>
* </ul> * </ul>
* <br/>
* Throws IllegalArgumentException if the following conditions are * Throws IllegalArgumentException if the following conditions are
* not met: * not met:
* <ul> * <ul>
@ -251,7 +250,6 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
* <li>{@code expansionMode = MULTIPLICATIVE}</li> * <li>{@code expansionMode = MULTIPLICATIVE}</li>
* <li>{@code contractionCriterion = 0.5 + expansionFactor}</li> * <li>{@code contractionCriterion = 0.5 + expansionFactor}</li>
* </ul> * </ul>
* <br/>
* Throws IllegalArgumentException if the following conditions are * Throws IllegalArgumentException if the following conditions are
* not met: * not met:
* <ul> * <ul>
@ -277,7 +275,7 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
* Creates an instance with the specified initialCapacity, * Creates an instance with the specified initialCapacity,
* expansionFactor, and contractionCriterion. * expansionFactor, and contractionCriterion.
* The expansion mode will default to {@code MULTIPLICATIVE}. * The expansion mode will default to {@code MULTIPLICATIVE}.
* <br/> * <p>
* Throws IllegalArgumentException if the following conditions are * Throws IllegalArgumentException if the following conditions are
* not met: * not met:
* <ul> * <ul>
@ -308,7 +306,7 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
* Creates an instance with the specified initial capacity, * Creates an instance with the specified initial capacity,
* expansion factor, and contraction criteria. * expansion factor, and contraction criteria.
* The expansion mode will default to {@code MULTIPLICATIVE}. * The expansion mode will default to {@code MULTIPLICATIVE}.
* <br/> * <p>
* Throws IllegalArgumentException if the following conditions are * Throws IllegalArgumentException if the following conditions are
* not met: * not met:
* <ul> * <ul>
@ -318,8 +316,7 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
* </ul> * </ul>
* *
* @param initialCapacity Initial size of the internal storage array.. * @param initialCapacity Initial size of the internal storage array..
* @param expansionFactor The array will be expanded based on this * @param expansionFactor The array will be expanded based on this parameter.
* parameter.
* @param contractionCriterion Contraction criterion. * @param contractionCriterion Contraction criterion.
* @throws MathIllegalArgumentException if the parameters are not valid. * @throws MathIllegalArgumentException if the parameters are not valid.
* @since 3.1 * @since 3.1
@ -336,18 +333,17 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
} }
/** /**
* <p> * Create a ResizableArray with the specified properties.
* Create a ResizableArray with the specified properties.</p>
* <p> * <p>
* Throws IllegalArgumentException if the following conditions are * Throws IllegalArgumentException if the following conditions are
* not met: * not met:
* <ul> * <ul>
* <li><code>initialCapacity > 0</code></li> * <li><code>initialCapacity &gt; 0</code></li>
* <li><code>expansionFactor > 1</code></li> * <li><code>expansionFactor &gt; 1</code></li>
* <li><code>contractionFactor >= expansionFactor</code></li> * <li><code>contractionFactor &ge; expansionFactor</code></li>
* <li><code>expansionMode in {MULTIPLICATIVE_MODE, ADDITIVE_MODE}</code> * <li><code>expansionMode in {MULTIPLICATIVE_MODE, ADDITIVE_MODE}</code>
* </li> * </li>
* </ul></p> * </ul>
* *
* @param initialCapacity the initial size of the internal storage array * @param initialCapacity the initial size of the internal storage array
* @param expansionFactor the array will be expanded based on this * @param expansionFactor the array will be expanded based on this
@ -376,12 +372,12 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
/** /**
* Creates an instance with the specified properties. * Creates an instance with the specified properties.
* <br/> * <p>
* Throws MathIllegalArgumentException if the following conditions are * Throws MathIllegalArgumentException if the following conditions are
* not met: * not met:
* <ul> * <ul>
* <li>{@code initialCapacity > 0}</li> * <li>{@code initialCapacity &gt; 0}</li>
* <li>{@code expansionFactor > 1}</li> * <li>{@code expansionFactor &gt; 1}</li>
* <li>{@code contractionCriterion >= expansionFactor}</li> * <li>{@code contractionCriterion >= expansionFactor}</li>
* </ul> * </ul>
* *
@ -419,9 +415,9 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
/** /**
* Copy constructor. Creates a new ResizableDoubleArray that is a deep, * Copy constructor. Creates a new ResizableDoubleArray that is a deep,
* fresh copy of the original. Needs to acquire synchronization lock * fresh copy of the original. Needs to acquire synchronization lock on original.
* on original. Original may not be null; otherwise a {@link NullArgumentException} * <p>
* is thrown. * Original may not be null; otherwise a {@link NullArgumentException} is thrown.
* *
* @param original array to copy * @param original array to copy
* @exception NullArgumentException if original is null * @exception NullArgumentException if original is null
@ -465,12 +461,10 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
* Adds an element to the end of the array and removes the first * Adds an element to the end of the array and removes the first
* element in the array. Returns the discarded first element. * element in the array. Returns the discarded first element.
* The effect is similar to a push operation in a FIFO queue. * The effect is similar to a push operation in a FIFO queue.
* </p>
* <p> * <p>
* Example: If the array contains the elements 1, 2, 3, 4 (in that order) * Example: If the array contains the elements 1, 2, 3, 4 (in that order)
* and addElementRolling(5) is invoked, the result is an array containing * and addElementRolling(5) is invoked, the result is an array containing
* the entries 2, 3, 4, 5 and the value returned is 1. * the entries 2, 3, 4, 5 and the value returned is 1.
* </p>
* *
* @param value Value to be added to the array. * @param value Value to be added to the array.
* @return the value which has been discarded or "pushed" out of the array * @return the value which has been discarded or "pushed" out of the array
@ -523,7 +517,7 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
/** /**
* Checks the expansion factor and the contraction criterion and throws an * Checks the expansion factor and the contraction criterion and throws an
* IllegalArgumentException if the contractionCriteria is less than the * IllegalArgumentException if the contractionCriteria is less than the
* expansionCriteria * expansionCriteria.
* *
* @param expansion factor to be checked * @param expansion factor to be checked
* @param contraction criteria to be checked * @param contraction criteria to be checked
@ -586,8 +580,7 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
/** /**
* Contracts the storage array to the (size of the element set) + 1 - to * Contracts the storage array to the (size of the element set) + 1 - to
* avoid a zero length array. This function also resets the startIndex to * avoid a zero length array. This function also resets the startIndex to zero.
* zero.
*/ */
public synchronized void contract() { public synchronized void contract() {
final double[] tempArray = new double[numElements + 1]; final double[] tempArray = new double[numElements + 1];
@ -878,15 +871,15 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
* Provides <em>direct</em> access to the internal storage array. * Provides <em>direct</em> access to the internal storage array.
* Please note that this method returns a reference to this object's * Please note that this method returns a reference to this object's
* storage array, not a copy. * storage array, not a copy.
* <br/> * <p>
* To correctly address elements of the array, the "start index" is * To correctly address elements of the array, the "start index" is
* required (available via the {@link #getStartIndex() getStartIndex} * required (available via the {@link #getStartIndex() getStartIndex}
* method. * method.
* <br/> * <p>
* This method should only be used to avoid copying the internal array. * This method should only be used to avoid copying the internal array.
* The returned value <em>must</em> be used for reading only; other * The returned value <em>must</em> be used for reading only; other
* uses could lead to this object becoming inconsistent. * uses could lead to this object becoming inconsistent.
* <br/> * <p>
* The {@link #getElements} method has no such limitation since it * The {@link #getElements} method has no such limitation since it
* returns a copy of this array's addressable elements. * returns a copy of this array's addressable elements.
* *
@ -976,11 +969,11 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
* Sets the expansionFactor. Throws IllegalArgumentException if the * Sets the expansionFactor. Throws IllegalArgumentException if the
* the following conditions are not met: * the following conditions are not met:
* <ul> * <ul>
* <li><code>expansionFactor > 1</code></li> * <li><code>expansionFactor &gt; 1</code></li>
* <li><code>contractionFactor >= expansionFactor</code></li> * <li><code>contractionFactor &ge; expansionFactor</code></li>
* </ul> * </ul>
* @param expansionFactor the new expansion factor value. * @param expansionFactor the new expansion factor value.
* @throws MathIllegalArgumentException if expansionFactor is <= 1 or greater * @throws MathIllegalArgumentException if expansionFactor is &le; 1 or greater
* than contractionFactor * than contractionFactor
* @deprecated As of 3.1 (to be removed in 4.0 as field will become "final"). * @deprecated As of 3.1 (to be removed in 4.0 as field will become "final").
*/ */
@ -1102,15 +1095,14 @@ public class ResizableDoubleArray implements DoubleArray, Serializable {
} }
/** /**
* <p>Copies source to dest, copying the underlying data, so dest is * Copies source to dest, copying the underlying data, so dest is
* a new, independent copy of source. Does not contract before * a new, independent copy of source. Does not contract before the copy.
* the copy.</p> * <p>
* * Obtains synchronization locks on both source and dest
* <p>Obtains synchronization locks on both source and dest * (in that order) before performing the copy.
* (in that order) before performing the copy.</p> * <p>
* * Neither source nor dest may be null; otherwise a {@link NullArgumentException}
* <p>Neither source nor dest may be null; otherwise a {@link NullArgumentException} * is thrown.
* is thrown</p>
* *
* @param source ResizableDoubleArray to copy * @param source ResizableDoubleArray to copy
* @param dest ResizableArray to replace with a copy of the source array * @param dest ResizableArray to replace with a copy of the source array