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

Javadoc only. Added missing </p>'s 

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@615734 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Phil Steitz 2008-01-28 06:10:03 +00:00
parent 6956f544e6
commit 87cbe1675e
33 changed files with 226 additions and 209 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/java/org/apache/commons/math/MathException.java
View File

@ -27,9 +27,9 @@ import java.util.ResourceBundle;
/**
* Base class for commons-math checked exceptions.
* <p>
* Supports nesting, emulating JDK 1.4 behavior if necessary.
* Supports nesting, emulating JDK 1.4 behavior if necessary.</p>
* <p>
* Adapted from {@link org.apache.commons.collections.FunctorException}.
* Adapted from {@link org.apache.commons.collections.FunctorException}.</p>
*
* @version $Revision$ $Date$
*/

2
src/java/org/apache/commons/math/analysis/BisectionSolver.java
View File

@ -23,7 +23,7 @@ import org.apache.commons.math.MaxIterationsExceededException;
* Implements the <a href="http://mathworld.wolfram.com/Bisection.html">
* bisection algorithm</a> for finding zeros of univariate real functions.
* <p>
* The function should be continuous but not necessarily smooth.
* The function should be continuous but not necessarily smooth.</p>
*
* @version $Revision$ $Date$
*/

4
src/java/org/apache/commons/math/analysis/BrentSolver.java
View File

@ -24,7 +24,7 @@ import org.apache.commons.math.MaxIterationsExceededException;
* Implements the <a href="http://mathworld.wolfram.com/BrentsMethod.html">
* Brent algorithm</a> for finding zeros of real univariate functions.
* <p>
* The function should be continuous but not necessarily smooth.
* The function should be continuous but not necessarily smooth.</p>
*
* @version $Revision$ $Date$
*/
@ -111,7 +111,7 @@ public class BrentSolver extends UnivariateRealSolverImpl {
* <p>
* Requires that the values of the function at the endpoints have opposite
* signs. An <code>IllegalArgumentException</code> is thrown if this is not
* the case.
* the case.</p>
*
* @param min the lower bound for the interval.
* @param max the upper bound for the interval.

9
src/java/org/apache/commons/math/analysis/DividedDifferenceInterpolator.java
View File

@ -28,7 +28,7 @@ import org.apache.commons.math.DuplicateSampleAbscissaException;
* ISBN 038795452X, chapter 2.
* <p>
* The actual code of Neville's evalution is in PolynomialFunctionLagrangeForm,
* this class provides an easy-to-use interface to it.
* this class provides an easy-to-use interface to it.</p>
*
* @version $Revision$ $Date$
*/
@ -64,7 +64,7 @@ public class DividedDifferenceInterpolator implements UnivariateRealInterpolator
* f[x0,x1,...,x[n-1]](x-x0)(x-x1)...(x-x[n-2])
* Therefore, a[k] = f[x0,x1,...,xk], c[k] = x[k].
* <p>
* Note x[], y[], a[] have the same length but c[]'s size is one less.
* Note x[], y[], a[] have the same length but c[]'s size is one less.</p>
*/
c = new double[x.length-1];
for (int i = 0; i < c.length; i++) {
@ -83,8 +83,9 @@ public class DividedDifferenceInterpolator implements UnivariateRealInterpolator
* The divided difference array is defined recursively by <pre>
* f[x0] = f(x0)
* f[x0,x1,...,xk] = (f(x1,...,xk) - f(x0,...,x[k-1])) / (xk - x0)
* </pre><p>
* The computational complexity is O(N^2).
* </pre></p>
* <p>
* The computational complexity is O(N^2).</p>
*
* @param x the interpolating points array
* @param y the interpolating values array

6
src/java/org/apache/commons/math/analysis/LaguerreSolver.java
View File

@ -28,7 +28,7 @@ import org.apache.commons.math.complex.Complex;
* ISBN 048641454X, chapter 8.
* <p>
* Laguerre's method is global in the sense that it can start with any initial
* approximation and be able to solve all roots from that point.
* approximation and be able to solve all roots from that point.</p>
*
* @version $Revision$ $Date$
*/
@ -69,7 +69,7 @@ public class LaguerreSolver extends UnivariateRealSolverImpl {
/**
* Find a real root in the given interval with initial value.
* <p>
* Requires bracketing condition.
* Requires bracketing condition.</p>
*
* @param min the lower bound for the interval
* @param max the upper bound for the interval
@ -105,7 +105,7 @@ public class LaguerreSolver extends UnivariateRealSolverImpl {
* Complex) may not be a real zero inside [min, max]. For example,
* p(x) = x^3 + 1, min = -2, max = 2, initial = 0. We can either try
* another initial value, or, as we did here, call solveAll() to obtain
* all roots and pick up the one that we're looking for.
* all roots and pick up the one that we're looking for.</p>
*
* @param min the lower bound for the interval
* @param max the upper bound for the interval

16
src/java/org/apache/commons/math/analysis/MullerSolver.java
View File

@ -28,7 +28,7 @@ import org.apache.commons.math.util.MathUtils;
* <p>
* Muller's method applies to both real and complex functions, but here we
* restrict ourselves to real functions. Methods solve() and solve2() find
* real zeros, using different ways to bypass complex arithmetics.
* real zeros, using different ways to bypass complex arithmetics.</p>
*
* @version $Revision$ $Date$
*/
@ -49,7 +49,7 @@ public class MullerSolver extends UnivariateRealSolverImpl {
/**
* Find a real root in the given interval with initial value.
* <p>
* Requires bracketing condition.
* Requires bracketing condition.</p>
*
* @param min the lower bound for the interval
* @param max the upper bound for the interval
@ -84,14 +84,14 @@ public class MullerSolver extends UnivariateRealSolverImpl {
* Original Muller's method would have function evaluation at complex point.
* Since our f(x) is real, we have to find ways to avoid that. Bracketing
* condition is one way to go: by requiring bracketing in every iteration,
* the newly computed approximation is guaranteed to be real.
* the newly computed approximation is guaranteed to be real.</p>
* <p>
* Normally Muller's method converges quadratically in the vicinity of a
* zero, however it may be very slow in regions far away from zeros. For
* example, f(x) = exp(x) - 1, min = -50, max = 100. In such case we use
* bisection as a safety backup if it performs very poorly.
* bisection as a safety backup if it performs very poorly.</p>
* <p>
* The formulas here use divided differences directly.
* The formulas here use divided differences directly.</p>
*
* @param min the lower bound for the interval
* @param max the upper bound for the interval
@ -188,14 +188,14 @@ public class MullerSolver extends UnivariateRealSolverImpl {
* Except for the initial [min, max], solve2() does not require bracketing
* condition, e.g. f(x0), f(x1), f(x2) can have the same sign. If complex
* number arises in the computation, we simply use its modulus as real
* approximation.
* approximation.</p>
* <p>
* Because the interval may not be bracketing, bisection alternative is
* not applicable here. However in practice our treatment usually works
* well, especially near real zeros where the imaginary part of complex
* approximation is often negligible.
* approximation is often negligible.</p>
* <p>
* The formulas here do not use divided differences directly.
* The formulas here do not use divided differences directly.</p>
*
* @param min the lower bound for the interval
* @param max the upper bound for the interval

2
src/java/org/apache/commons/math/analysis/NevilleInterpolator.java
View File

@ -26,7 +26,7 @@ import org.apache.commons.math.MathException;
* chapter 2.
* <p>
* The actual code of Neville's evalution is in PolynomialFunctionLagrangeForm,
* this class provides an easy-to-use interface to it.
* this class provides an easy-to-use interface to it.</p>
*
* @version $Revision$ $Date$
*/

2
src/java/org/apache/commons/math/analysis/NewtonSolver.java
View File

@ -25,7 +25,7 @@ import org.apache.commons.math.MaxIterationsExceededException;
* Implements <a href="http://mathworld.wolfram.com/NewtonsMethod.html">
* Newton's Method</a> for finding zeros of real univariate functions.
* <p>
* The function should be continuous but not necessarily smooth.
* The function should be continuous but not necessarily smooth.</p>
*
* @version $Revision$ $Date$
*/

9
src/java/org/apache/commons/math/analysis/PolynomialFunction.java
View File

@ -22,7 +22,7 @@ import java.io.Serializable;
* Immutable representation of a real polynomial function with real coefficients.
* <p>
* <a href="http://mathworld.wolfram.com/HornersMethod.html">Horner's Method</a>
* is used to evaluate the function.
* is used to evaluate the function.</p>
*
* @version $Revision$ $Date$
*/
@ -45,7 +45,7 @@ public class PolynomialFunction implements DifferentiableUnivariateRealFunction,
* is the length of the array minus 1.
* <p>
* The constructor makes a copy of the input array and assigns the copy to
* the coefficients property.
* the coefficients property.</p>
*
* @param c polynominal coefficients
* @throws NullPointerException if c is null
@ -65,7 +65,8 @@ public class PolynomialFunction implements DifferentiableUnivariateRealFunction,
* <p>
* The value returned is <br>
* <code>coefficients[n] * x^n + ... + coefficients[1] * x + coefficients[0]</code>
*
* </p>
*
* @param x the argument for which the function value should be computed
* @return the value of the polynomial at the given point
* @see UnivariateRealFunction#value(double)
@ -88,7 +89,7 @@ public class PolynomialFunction implements DifferentiableUnivariateRealFunction,
* Returns a copy of the coefficients array.
* <p>
* Changes made to the returned copy will not affect the coefficients of
* the polynomial.
* the polynomial.</p>
*
* @return a fresh copy of the coefficients array
*/

16
src/java/org/apache/commons/math/analysis/PolynomialFunctionLagrangeForm.java
View File

@ -28,7 +28,7 @@ import org.apache.commons.math.FunctionEvaluationException;
* Analysis</b>, ISBN 038795452X, chapter 2.
* <p>
* The approximated function should be smooth enough for Lagrange polynomial
* to work well. Otherwise, consider using splines instead.
* to work well. Otherwise, consider using splines instead.</p>
*
* @version $Revision$ $Date$
*/
@ -59,7 +59,7 @@ public class PolynomialFunctionLagrangeForm implements UnivariateRealFunction,
* Construct a Lagrange polynomial with the given abscissas and function
* values. The order of interpolating points are not important.
* <p>
* The constructor makes copy of the input arrays and assigns them.
* The constructor makes copy of the input arrays and assigns them.</p>
*
* @param x interpolating points
* @param y function values at interpolating points
@ -104,7 +104,7 @@ public class PolynomialFunctionLagrangeForm implements UnivariateRealFunction,
/**
* Returns a copy of the interpolating points array.
* <p>
* Changes made to the returned copy will not affect the polynomial.
* Changes made to the returned copy will not affect the polynomial.</p>
*
* @return a fresh copy of the interpolating points array
*/
@ -117,7 +117,7 @@ public class PolynomialFunctionLagrangeForm implements UnivariateRealFunction,
/**
* Returns a copy of the interpolating values array.
* <p>
* Changes made to the returned copy will not affect the polynomial.
* Changes made to the returned copy will not affect the polynomial.</p>
*
* @return a fresh copy of the interpolating values array
*/
@ -130,7 +130,7 @@ public class PolynomialFunctionLagrangeForm implements UnivariateRealFunction,
/**
* Returns a copy of the coefficients array.
* <p>
* Changes made to the returned copy will not affect the polynomial.
* Changes made to the returned copy will not affect the polynomial.</p>
*
* @return a fresh copy of the coefficients array
*/
@ -149,7 +149,7 @@ public class PolynomialFunctionLagrangeForm implements UnivariateRealFunction,
* Neville's Algorithm</a>. It takes O(N^2) time.
* <p>
* This function is made public static so that users can call it directly
* without instantiating PolynomialFunctionLagrangeForm object.
* without instantiating PolynomialFunctionLagrangeForm object.</p>
*
* @param x the interpolating points array
* @param y the interpolating values array
@ -216,7 +216,7 @@ public class PolynomialFunctionLagrangeForm implements UnivariateRealFunction,
* interpolation data. It takes O(N^2) time.
* <p>
* Note this computation can be ill-conditioned. Use with caution
* and only when it is necessary.
* and only when it is necessary.</p>
*
* @throws ArithmeticException if any abscissas coincide
*/
@ -274,7 +274,7 @@ public class PolynomialFunctionLagrangeForm implements UnivariateRealFunction,
* Verifies that the interpolation arrays are valid.
* <p>
* The interpolating points must be distinct. However it is not
* verified here, it is checked in evaluate() and computeCoefficients().
* verified here, it is checked in evaluate() and computeCoefficients().</p>
*
* @param x the interpolating points array
* @param y the interpolating values array

12
src/java/org/apache/commons/math/analysis/PolynomialFunctionNewtonForm.java
View File

@ -27,7 +27,7 @@ import org.apache.commons.math.FunctionEvaluationException;
* The formula of polynomial in Newton form is
* p(x) = a[0] + a[1](x-c[0]) + a[2](x-c[0])(x-c[1]) + ... +
* a[n](x-c[0])(x-c[1])...(x-c[n-1])
* Note that the length of a[] is one more than the length of c[]
* Note that the length of a[] is one more than the length of c[]</p>
*
* @version $Revision$ $Date$
*/
@ -61,7 +61,7 @@ public class PolynomialFunctionNewtonForm implements UnivariateRealFunction,
* centers are important in that if c[] shuffle, then values of a[] would
* completely change, not just a permutation of old a[].
* <p>
* The constructor makes copy of the input arrays and assigns them.
* The constructor makes copy of the input arrays and assigns them.</p>
*
* @param a the coefficients in Newton form formula
* @param c the centers
@ -102,7 +102,7 @@ public class PolynomialFunctionNewtonForm implements UnivariateRealFunction,
/**
* Returns a copy of coefficients in Newton form formula.
* <p>
* Changes made to the returned copy will not affect the polynomial.
* Changes made to the returned copy will not affect the polynomial.</p>
*
* @return a fresh copy of coefficients in Newton form formula
*/
@ -115,7 +115,7 @@ public class PolynomialFunctionNewtonForm implements UnivariateRealFunction,
/**
* Returns a copy of the centers array.
* <p>
* Changes made to the returned copy will not affect the polynomial.
* Changes made to the returned copy will not affect the polynomial.</p>
*
* @return a fresh copy of the centers array
*/
@ -128,7 +128,7 @@ public class PolynomialFunctionNewtonForm implements UnivariateRealFunction,
/**
* Returns a copy of the coefficients array.
* <p>
* Changes made to the returned copy will not affect the polynomial.
* Changes made to the returned copy will not affect the polynomial.</p>
*
* @return a fresh copy of the coefficients array
*/
@ -194,7 +194,7 @@ public class PolynomialFunctionNewtonForm implements UnivariateRealFunction,
* Verifies that the input arrays are valid.
* <p>
* The centers must be distinct for interpolation purposes, but not
* for general use. Thus it is not verified here.
* for general use. Thus it is not verified here.</p>
*
* @param a the coefficients in Newton form formula
* @param c the centers

18
src/java/org/apache/commons/math/analysis/PolynomialSplineFunction.java
View File

@ -31,14 +31,16 @@ import org.apache.commons.math.ArgumentOutsideDomainException;
* have been computed to match the values of another function at the knot
* points. The value consistency constraints are not currently enforced by
* <code>PolynomialSplineFunction</code> itself, but are assumed to hold among
* the polynomials and knot points passed to the constructor.
* the polynomials and knot points passed to the constructor.</p>
* <p>
* N.B.: The polynomials in the <code>polynomials</code> property must be
* centered on the knot points to compute the spline function values. See below.
* centered on the knot points to compute the spline function values.
* See below.</p>
* <p>
* The domain of the polynomial spline function is
* <code>[smallest knot, largest knot]</code>. Attempts to evaluate the
* function at values outside of this range generate IllegalArgumentExceptions.
* </p>
* <p>
* The value of the polynomial spline function for an argument <code>x</code>
* is computed as follows:
@ -49,7 +51,7 @@ import org.apache.commons.math.ArgumentOutsideDomainException;
* is thrown.</li>
* <li> Let <code>j</code> be the index of the largest knot point that is less
* than or equal to <code>x</code>. The value returned is <br>
* <code>polynomials[j](x - knot[j])</code></li></ol>
* <code>polynomials[j](x - knot[j])</code></li></ol></p>
*
* @version $Revision$ $Date$
*/
@ -83,7 +85,7 @@ public class PolynomialSplineFunction
* and interpolating polynomials.
* <p>
* The constructor copies both arrays and assigns the copies to the knots
* and polynomials properties, respectively.
* and polynomials properties, respectively.</p>
*
* @param knots spline segment interval delimiters
* @param polynomials polynomial functions that make up the spline
@ -118,10 +120,10 @@ public class PolynomialSplineFunction
* Compute the value for the function.
* <p>
* Throws FunctionEvaluationException if v is outside of the domain of the
* function. The domain is [smallest knot, largest knot].
* function. The domain is [smallest knot, largest knot].</p>
* <p>
* See {@link PolynomialSplineFunction} for details on the algorithm for
* computing the value of the function.
* computing the value of the function.</p>
*
* @param v the point for which the function value should be computed
* @return the value
@ -181,7 +183,7 @@ public class PolynomialSplineFunction
* Returns a copy of the interpolating polynomials array.
* <p>
* Returns a fresh copy of the array. Changes made to the copy will
* not affect the polynomials property.
* not affect the polynomials property.</p>
*
* @return the interpolating polynomials
*/
@ -195,7 +197,7 @@ public class PolynomialSplineFunction
* Returns an array copy of the knot points.
* <p>
* Returns a fresh copy of the array. Changes made to the copy
* will not affect the knots property.
* will not affect the knots property.</p>
*
* @return the knot points
*/

6
src/java/org/apache/commons/math/analysis/RiddersSolver.java
View File

@ -27,7 +27,7 @@ import org.apache.commons.math.util.MathUtils;
* of a real continuous function </i>, IEEE Transactions on Circuits and
* Systems, 26 (1979), 979 - 980.
* <p>
* The function should be continuous but not necessarily smooth.
* The function should be continuous but not necessarily smooth.</p>
*
* @version $Revision$ $Date$
*/
@ -48,7 +48,7 @@ public class RiddersSolver extends UnivariateRealSolverImpl {
/**
* Find a root in the given interval with initial value.
* <p>
* Requires bracketing condition.
* Requires bracketing condition.</p>
*
* @param min the lower bound for the interval
* @param max the upper bound for the interval
@ -79,7 +79,7 @@ public class RiddersSolver extends UnivariateRealSolverImpl {
/**
* Find a root in the given interval.
* <p>
* Requires bracketing condition.
* Requires bracketing condition.</p>
*
* @param min the lower bound for the interval
* @param max the upper bound for the interval

2
src/java/org/apache/commons/math/analysis/RombergIntegrator.java
View File

@ -27,7 +27,7 @@ import org.apache.commons.math.MaxIterationsExceededException;
* <p>
* Romberg integration employs k successvie refinements of the trapezoid
* rule to remove error terms less than order O(N^(-2k)). Simpson's rule
* is a special case of k = 2.
* is a special case of k = 2.</p>
*
* @version $Revision$ $Date$
*/

4
src/java/org/apache/commons/math/analysis/SecantSolver.java
View File

@ -32,9 +32,9 @@ import org.apache.commons.math.MaxIterationsExceededException;
* the unrestricted secant algorithm. However, this implementation should in
* general outperform the
* <a href="http://mathworld.wolfram.com/MethodofFalsePosition.html">
* regula falsi method.</a>
* regula falsi method.</a></p>
* <p>
* The function is assumed to be continuous but not necessarily smooth.
* The function is assumed to be continuous but not necessarily smooth.</p>
*
* @version $Revision$ $Date$
*/

2
src/java/org/apache/commons/math/analysis/SimpsonIntegrator.java
View File

@ -26,7 +26,7 @@ import org.apache.commons.math.MaxIterationsExceededException;
* chapter 3.
* <p>
* This implementation employs basic trapezoid rule as building blocks to
* calculate the Simpson's rule of alternating 2/3 and 4/3.
* calculate the Simpson's rule of alternating 2/3 and 4/3.</p>
*
* @version $Revision$ $Date$
*/

6
src/java/org/apache/commons/math/analysis/SplineInterpolator.java
View File

@ -21,22 +21,24 @@ package org.apache.commons.math.analysis;
* <p>
* The {@link #interpolate(double[], double[])} method returns a {@link PolynomialSplineFunction}
* consisting of n cubic polynomials, defined over the subintervals determined by the x values,
* x[0] < x[i] ... < x[n]. The x values are referred to as "knot points."
* x[0] < x[i] ... < x[n]. The x values are referred to as "knot points."</p>
* <p>
* The value of the PolynomialSplineFunction at a point x that is greater than or equal to the smallest
* knot point and strictly less than the largest knot point is computed by finding the subinterval to which
* x belongs and computing the value of the corresponding polynomial at <code>x - x[i] </code> where
* <code>i</code> is the index of the subinterval. See {@link PolynomialSplineFunction} for more details.
* </p>
* <p>
* The interpolating polynomials satisfy: <ol>
* <li>The value of the PolynomialSplineFunction at each of the input x values equals the
* corresponding y value.</li>
* <li>Adjacent polynomials are equal through two derivatives at the knot points (i.e., adjacent polynomials
* "match up" at the knot points, as do their first and second derivatives).</li>
* </ol>
* </ol></p>
* <p>
* The cubic spline interpolation algorithm implemented is as described in R.L. Burden, J.D. Faires,
* <u>Numerical Analysis</u>, 4th Ed., 1989, PWS-Kent, ISBN 0-53491-585-X, pp 126-131.
* </p>
*
* @version $Revision$ $Date$
*

4
src/java/org/apache/commons/math/analysis/TrapezoidIntegrator.java
View File

@ -25,7 +25,7 @@ import org.apache.commons.math.MaxIterationsExceededException;
* reference, see <b>Introduction to Numerical Analysis</b>, ISBN 038795452X,
* chapter 3.
* <p>
* The function should be integrable.
* The function should be integrable.</p>
*
* @version $Revision$ $Date$
*/
@ -53,7 +53,7 @@ public class TrapezoidIntegrator extends UnivariateRealIntegratorImpl {
* <p>
* The interval is divided equally into 2^n sections rather than an
* arbitrary m sections because this configuration can best utilize the
* alrealy computed values.
* alrealy computed values.</p>
*
* @param min the lower bound for the interval
* @param max the upper bound for the interval

18
src/java/org/apache/commons/math/analysis/UnivariateRealIntegrator.java
View File

@ -31,10 +31,10 @@ public interface UnivariateRealIntegrator {
* <p>
* Usually a high iteration count indicates convergence problem. However,
* the "reasonable value" varies widely for different cases. Users are
* advised to use the default value.
* advised to use the default value.</p>
* <p>
* A <code>ConvergenceException</code> will be thrown if this number
* is exceeded.
* is exceeded.</p>
*
* @param count maximum number of iterations
*/
@ -50,7 +50,7 @@ public interface UnivariateRealIntegrator {
/**
* Reset the upper limit for the number of iterations to the default.
* <p>
* The default value is supplied by the implementation.
* The default value is supplied by the implementation.</p>
*
* @see #setMaximalIterationCount(int)
*/
@ -61,10 +61,10 @@ public interface UnivariateRealIntegrator {
* <p>
* Minimal iteration is needed to avoid false early convergence, e.g.
* the sample points happen to be zeroes of the function. Users can
* use the default value or choose one that they see as appropriate.
* use the default value or choose one that they see as appropriate.</p>
* <p>
* A <code>ConvergenceException</code> will be thrown if this number
* is not met.
* is not met.</p>
*
* @param count minimum number of iterations
*/
@ -80,7 +80,7 @@ public interface UnivariateRealIntegrator {
/**
* Reset the lower limit for the number of iterations to the default.
* <p>
* The default value is supplied by the implementation.
* The default value is supplied by the implementation.</p>
*
* @see #setMinimalIterationCount(int)
*/
@ -89,7 +89,7 @@ public interface UnivariateRealIntegrator {
/**
* Set the relative accuracy.
* <p>
* This is used to stop iterations.
* This is used to stop iterations.</p>
*
* @param accuracy the relative accuracy
* @throws IllegalArgumentException if the accuracy can't be achieved
@ -107,7 +107,7 @@ public interface UnivariateRealIntegrator {
/**
* Reset the relative accuracy to the default.
* <p>
* The default value is provided by the implementation.
* The default value is provided by the implementation.</p>
*
* @see #setRelativeAccuracy(double)
*/
@ -145,7 +145,7 @@ public interface UnivariateRealIntegrator {
* help track down performance problems: if the iteration count
* is notoriously high, check whether the function is evaluated
* properly, and whether another integrator is more amenable to the
* problem.
* problem.</p>
*
* @return the last iteration count
* @throws IllegalStateException if there is no result available, either

24
src/java/org/apache/commons/math/analysis/UnivariateRealSolver.java
View File

@ -23,7 +23,7 @@ import org.apache.commons.math.FunctionEvaluationException;
/**
* Interface for (univariate real) rootfinding algorithms.
* <p>
* Implementations will search for only one zero in the given interval.
* Implementations will search for only one zero in the given interval.</p>
*
* @version $Revision$ $Date$
*/
@ -34,10 +34,10 @@ public interface UnivariateRealSolver {
* <p>
* Usually a high iteration count indicates convergence problems. However,
* the "reasonable value" varies widely for different solvers. Users are
* advised to use the default value supplied by the solver.
* advised to use the default value supplied by the solver.</p>
* <p>
* A <code>ConvergenceException</code> will be thrown if this number
* is exceeded.
* is exceeded.</p>
*
* @param count maximum number of iterations
*/
@ -53,7 +53,7 @@ public interface UnivariateRealSolver {
/**
* Reset the upper limit for the number of iterations to the default.
* <p>
* The default value is supplied by the solver implementation.
* The default value is supplied by the solver implementation.</p>
*
* @see #setMaximalIterationCount(int)
*/
@ -65,10 +65,10 @@ public interface UnivariateRealSolver {
* The default is usually choosen so that roots in the interval
* -10..-0.1 and +0.1..+10 can be found with a reasonable accuracy. If the
* expected absolute value of your roots is of much smaller magnitude, set
* this to a smaller value.
* this to a smaller value.</p>
* <p>
* Solvers are advised to do a plausibility check with the relative
* accuracy, but clients should not rely on this.
* accuracy, but clients should not rely on this.</p>
*
* @param accuracy the accuracy.
* @throws IllegalArgumentException if the accuracy can't be achieved by
@ -86,7 +86,7 @@ public interface UnivariateRealSolver {
/**
* Reset the absolute accuracy to the default.
* <p>
* The default value is provided by the solver implementation.
* The default value is provided by the solver implementation.</p>
*/
void resetAbsoluteAccuracy();
@ -94,11 +94,11 @@ public interface UnivariateRealSolver {
* Set the relative accuracy.
* <p>
* This is used to stop iterations if the absolute accuracy can't be
* achieved due to large values or short mantissa length.
* achieved due to large values or short mantissa length.</p>
* <p>
* If this should be the primary criterion for convergence rather then a
* safety measure, set the absolute accuracy to a ridiculously small value,
* like 1E-1000.
* like 1E-1000.</p>
*
* @param accuracy the relative accuracy.
* @throws IllegalArgumentException if the accuracy can't be achieved by
@ -122,10 +122,10 @@ public interface UnivariateRealSolver {
* Set the function value accuracy.
* <p>
* This is used to determine when an evaluated function value or some other
* value which is used as divisor is zero.
* value which is used as divisor is zero.</p>
* <p>
* This is a safety guard and it shouldn't be necessary to change this in
* general.
* general.</p>
*
* @param accuracy the accuracy.
* @throws IllegalArgumentException if the accuracy can't be achieved by
@ -196,7 +196,7 @@ public interface UnivariateRealSolver {
* help track down performance problems: if the iteration count
* is notoriously high, check whether the function is evaluated
* properly, and whether another solver is more amenable to the
* problem.
* problem.</p>
*
* @return the last iteration count.
* @throws IllegalStateException if there is no result available, either

4
src/java/org/apache/commons/math/analysis/UnivariateRealSolverFactory.java
View File

@ -28,10 +28,10 @@ import org.apache.commons.discovery.tools.DiscoverClass;
* <li>Secant method</li>
* </ul>
* Concrete factories extending this class also specify a default solver, instances of which
* are returned by <code>newDefaultSolver()</code>.
* are returned by <code>newDefaultSolver()</code>.</p>
* <p>
* Common usage:<pre>
* SolverFactory factory = UnivariateRealSolverFactory.newInstance();
* SolverFactory factory = UnivariateRealSolverFactory.newInstance();</p>
*
* // create a Brent solver to use with a UnivariateRealFunction f
* BrentSolver solver = factory.newBrentSolver(f);

2
src/java/org/apache/commons/math/analysis/UnivariateRealSolverFactoryImpl.java
View File

@ -20,7 +20,7 @@ package org.apache.commons.math.analysis;
* A concrete {@link UnivariateRealSolverFactory}. This is the default solver factory
* used by commons-math.
* <p>
* The default solver returned by this factory is a {@link BrentSolver}.
* The default solver returned by this factory is a {@link BrentSolver}.</p>
*
* @version $Revision$ $Date$
*/

6
src/java/org/apache/commons/math/analysis/UnivariateRealSolverUtils.java
View File

@ -99,7 +99,7 @@ public class UnivariateRealSolverUtils {
* -- ConvergenceException </li>
* <li> <code> Integer.MAX_VALUE</code> iterations elapse
* -- ConvergenceException </li>
* </ul>
* </ul></p>
* <p>
* <strong>Note: </strong> this method can take
* <code>Integer.MAX_VALUE</code> iterations to throw a
@ -107,7 +107,7 @@ public class UnivariateRealSolverUtils {
* is a root between <code>lowerBound</code> and <code>upperBound</code>
* near <code>initial,</code> it is better to use
* {@link #bracket(UnivariateRealFunction, double, double, double, int)},
* explicitly specifying the maximum number of iterations.
* explicitly specifying the maximum number of iterations.</p>
*
* @param function the function
* @param initial initial midpoint of interval being expanded to
@ -146,7 +146,7 @@ public class UnivariateRealSolverUtils {
* <li> <code> a = lower </code> and <code> b = upper</code>
* -- ConvergenceException </li>
* <li> <code> maximumIterations</code> iterations elapse
* -- ConvergenceException </li></ul>
* -- ConvergenceException </li></ul></p>
*
* @param function the function
* @param initial initial midpoint of interval being expanded to

106
src/java/org/apache/commons/math/complex/Complex.java
View File

@ -28,11 +28,11 @@ import org.apache.commons.math.util.MathUtils;
* infinite values according to the rules for {@link java.lang.Double}
* arithmetic, applying definitional formulas and returning <code>NaN</code> or
* infinite values in real or imaginary parts as these arise in computation.
* See individual method javadocs for details.
* See individual method javadocs for details.</p>
* <p>
* {@link #equals} identifies all values with <code>NaN</code> in either real
* or imaginary part - e.g., <pre>
* <code>1 + NaNi == NaN + i == NaN + NaNi.</code></pre>
* <code>1 + NaNi == NaN + i == NaN + NaNi.</code></pre></p>
*
* @author Apache Software Foundation
* @version $Revision$ $Date$
@ -81,7 +81,7 @@ public class Complex implements Serializable {
* Returns <code>NaN</code> if either real or imaginary part is
* <code>NaN</code> and <code>Double.POSITIVE_INFINITY</code> if
* neither part is <code>NaN</code>, but at least one part takes an infinite
* value.
* value.</p>
*
* @return the absolute value
*/
@ -115,12 +115,12 @@ public class Complex implements Serializable {
* Uses the definitional formula
* <pre>
* (a + bi) + (c + di) = (a+c) + (b+d)i
* </pre>
* </pre></p>
* <p>
* If either this or <code>rhs</code> has a NaN value in either part,
* {@link #NaN} is returned; otherwise Inifinite and NaN values are
* returned in the parts of the result according to the rules for
* {@link java.lang.Double} arithmetic.
* {@link java.lang.Double} arithmetic.</p>
*
* @param rhs the other complex number
* @return the complex number sum
@ -136,12 +136,12 @@ public class Complex implements Serializable {
* "A + Bi" is "A - Bi".
* <p>
* {@link #NaN} is returned if either the real or imaginary
* part of this Complex number equals <code>Double.NaN</code>.
* part of this Complex number equals <code>Double.NaN</code>.</p>
* <p>
* If the imaginary part is infinite, and the real part is not NaN,
* the returned value has infinite imaginary part of the opposite
* sign - e.g. the conjugate of <code>1 + POSITIVE_INFINITY i</code>
* is <code>1 - NEGATIVE_INFINITY i</code>
* is <code>1 - NEGATIVE_INFINITY i</code></p>
*
* @return the conjugate of this Complex object
*/
@ -164,7 +164,7 @@ public class Complex implements Serializable {
* but uses
* <a href="http://doi.acm.org/10.1145/1039813.1039814">
* prescaling of operands</a> to limit the effects of overflows and
* underflows in the computation.
* underflows in the computation.</p>
* <p>
* Infinite and NaN values are handled / returned according to the
* following rules, applied in the order presented:
@ -181,7 +181,7 @@ public class Complex implements Serializable {
* <li>If this is infinite and <code>rhs</code> is finite, NaN values are
* returned in the parts of the result if the {@link java.lang.Double}
* rules applied to the definitional formula force NaN results.</li>
* </ul>
* </ul></p>
*
* @param rhs the other complex number
* @return the complex number quotient
@ -226,12 +226,12 @@ public class Complex implements Serializable {
* <p>
* If both the real and imaginary parts of two Complex numbers
* are exactly the same, and neither is <code>Double.NaN</code>, the two
* Complex objects are considered to be equal.
* Complex objects are considered to be equal.</p>
* <p>
* All <code>NaN</code> values are considered to be equal - i.e, if either
* (or both) real and imaginary parts of the complex number are equal
* to <code>Double.NaN</code>, the complex number is equal to
* <code>Complex.NaN</code>.
* <code>Complex.NaN</code>.</p>
*
* @param other Object to test for equality to this
* @return true if two Complex objects are equal, false if
@ -269,7 +269,7 @@ public class Complex implements Serializable {
/**
* Get a hashCode for the complex number.
* <p>
* All NaN values have the same hash code.
* All NaN values have the same hash code.</p>
*
* @return a hash code value for this object
*/
@ -368,7 +368,7 @@ public class Complex implements Serializable {
* Return the additive inverse of this complex number.
* <p>
* Returns <code>Complex.NaN</code> if either real or imaginary
* part of this Complex number equals <code>Double.NaN</code>.
* part of this Complex number equals <code>Double.NaN</code>.</p>
*
* @return the negation of this complex number
*/
@ -387,12 +387,12 @@ public class Complex implements Serializable {
* Uses the definitional formula
* <pre>
* (a + bi) - (c + di) = (a-c) + (b-d)i
* </pre>
* </pre></p>
* <p>
* If either this or <code>rhs</code> has a NaN value in either part,
* {@link #NaN} is returned; otherwise inifinite and NaN values are
* returned in the parts of the result according to the rules for
* {@link java.lang.Double} arithmetic.
* {@link java.lang.Double} arithmetic. </p>
*
* @param rhs the other complex number
* @return the complex number difference
@ -413,10 +413,10 @@ public class Complex implements Serializable {
* inverse cosine</a> of this complex number.
* <p>
* Implements the formula: <pre>
* <code> acos(z) = -i (log(z + i (sqrt(1 - z<sup>2</sup>))))</code></pre>
* <code> acos(z) = -i (log(z + i (sqrt(1 - z<sup>2</sup>))))</code></pre></p>
* <p>
* Returns {@link Complex#NaN} if either real or imaginary part of the
* input argument is <code>NaN</code> or infinite.
* input argument is <code>NaN</code> or infinite.</p>
*
* @return the inverse cosine of this complex number
* @since 1.2
@ -436,10 +436,10 @@ public class Complex implements Serializable {
* inverse sine</a> of this complex number.
* <p>
* Implements the formula: <pre>
* <code> asin(z) = -i (log(sqrt(1 - z<sup>2</sup>) + iz)) </code></pre>
* <code> asin(z) = -i (log(sqrt(1 - z<sup>2</sup>) + iz)) </code></pre></p>
* <p>
* Returns {@link Complex#NaN} if either real or imaginary part of the
* input argument is <code>NaN</code> or infinite.
* input argument is <code>NaN</code> or infinite.</p>
*
* @return the inverse sine of this complex number.
* @since 1.2
@ -459,10 +459,10 @@ public class Complex implements Serializable {
* inverse tangent</a> of this complex number.
* <p>
* Implements the formula: <pre>
* <code> atan(z) = (i/2) log((i + z)/(i - z)) </code></pre>
* <code> atan(z) = (i/2) log((i + z)/(i - z)) </code></pre></p>
* <p>
* Returns {@link Complex#NaN} if either real or imaginary part of the
* input argument is <code>NaN</code> or infinite.
* input argument is <code>NaN</code> or infinite.</p>
*
* @return the inverse tangent of this complex number
* @since 1.2
@ -486,10 +486,10 @@ public class Complex implements Serializable {
* <code> cos(a + bi) = cos(a)cosh(b) - sin(a)sinh(b)i</code></pre>
* where the (real) functions on the right-hand side are
* {@link java.lang.Math#sin}, {@link java.lang.Math#cos},
* {@link MathUtils#cosh} and {@link MathUtils#sinh}.
* {@link MathUtils#cosh} and {@link MathUtils#sinh}.</p>
* <p>
* Returns {@link Complex#NaN} if either real or imaginary part of the
* input argument is <code>NaN</code>.
* input argument is <code>NaN</code>.</p>
* <p>
* Infinite values in real or imaginary parts of the input may result in
* infinite or NaN values returned in parts of the result.<pre>
@ -497,7 +497,7 @@ public class Complex implements Serializable {
* <code>
* cos(1 &plusmn; INFINITY i) = 1 &#x2213; INFINITY i
* cos(&plusmn;INFINITY + i) = NaN + NaN i
* cos(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i</code></pre>
* cos(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i</code></pre></p>
*
* @return the cosine of this complex number
* @since 1.2
@ -520,10 +520,10 @@ public class Complex implements Serializable {
* <code> cosh(a + bi) = cosh(a)cos(b) + sinh(a)sin(b)i</code></pre>
* where the (real) functions on the right-hand side are
* {@link java.lang.Math#sin}, {@link java.lang.Math#cos},
* {@link MathUtils#cosh} and {@link MathUtils#sinh}.
* {@link MathUtils#cosh} and {@link MathUtils#sinh}.</p>
* <p>
* Returns {@link Complex#NaN} if either real or imaginary part of the
* input argument is <code>NaN</code>.
* input argument is <code>NaN</code>.</p>
* <p>
* Infinite values in real or imaginary parts of the input may result in
* infinite or NaN values returned in parts of the result.<pre>
@ -531,7 +531,7 @@ public class Complex implements Serializable {
* <code>
* cosh(1 &plusmn; INFINITY i) = NaN + NaN i
* cosh(&plusmn;INFINITY + i) = INFINITY &plusmn; INFINITY i
* cosh(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i</code></pre>
* cosh(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i</code></pre></p>
*
* @return the hyperbolic cosine of this complex number.
* @since 1.2
@ -554,10 +554,10 @@ public class Complex implements Serializable {
* <code> exp(a + bi) = exp(a)cos(b) + exp(a)sin(b)i</code></pre>
* where the (real) functions on the right-hand side are
* {@link java.lang.Math#exp}, {@link java.lang.Math#cos}, and
* {@link java.lang.Math#sin}.
* {@link java.lang.Math#sin}.</p>
* <p>
* Returns {@link Complex#NaN} if either real or imaginary part of the
* input argument is <code>NaN</code>.
* input argument is <code>NaN</code>.</p>
* <p>
* Infinite values in real or imaginary parts of the input may result in
* infinite or NaN values returned in parts of the result.<pre>
@ -566,7 +566,7 @@ public class Complex implements Serializable {
* exp(1 &plusmn; INFINITY i) = NaN + NaN i
* exp(INFINITY + i) = INFINITY + INFINITY i
* exp(-INFINITY + i) = 0 + 0i
* exp(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i</code></pre>
* exp(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i</code></pre></p>
*
* @return <i>e</i><sup><code>this</code></sup>
* @since 1.2
@ -589,10 +589,10 @@ public class Complex implements Serializable {
* <code> log(a + bi) = ln(|a + bi|) + arg(a + bi)i</code></pre>
* where ln on the right hand side is {@link java.lang.Math#log},
* <code>|a + bi|</code> is the modulus, {@link Complex#abs}, and
* <code>arg(a + bi) = {@link java.lang.Math#atan2}(b, a)</code>
* <code>arg(a + bi) = {@link java.lang.Math#atan2}(b, a)</code></p>
* <p>
* Returns {@link Complex#NaN} if either real or imaginary part of the
* input argument is <code>NaN</code>.
* input argument is <code>NaN</code>.</p>
* <p>
* Infinite (or critical) values in real or imaginary parts of the input may
* result in infinite or NaN values returned in parts of the result.<pre>
@ -604,7 +604,7 @@ public class Complex implements Serializable {
* log(INFINITY &plusmn; INFINITY i) = INFINITY &plusmn; (&pi;/4)i
* log(-INFINITY &plusmn; INFINITY i) = INFINITY &plusmn; (3&pi;/4)i
* log(0 + 0i) = -INFINITY + 0i
* </code></pre>
* </code></pre></p>
*
* @return ln of this complex number.
* @since 1.2
@ -624,11 +624,11 @@ public class Complex implements Serializable {
* Implements the formula: <pre>
* <code> y<sup>x</sup> = exp(x&middot;log(y))</code></pre>
* where <code>exp</code> and <code>log</code> are {@link #exp} and
* {@link #log}, respectively.
* {@link #log}, respectively.</p>
* <p>
* Returns {@link Complex#NaN} if either real or imaginary part of the
* input argument is <code>NaN</code> or infinite, or if <code>y</code>
* equals {@link Complex#ZERO}.
* equals {@link Complex#ZERO}.</p>
*
* @param x the exponent.
* @return <code>this</code><sup><code>x</code></sup>
@ -652,10 +652,10 @@ public class Complex implements Serializable {
* <code> sin(a + bi) = sin(a)cosh(b) - cos(a)sinh(b)i</code></pre>
* where the (real) functions on the right-hand side are
* {@link java.lang.Math#sin}, {@link java.lang.Math#cos},
* {@link MathUtils#cosh} and {@link MathUtils#sinh}.
* {@link MathUtils#cosh} and {@link MathUtils#sinh}.</p>
* <p>
* Returns {@link Complex#NaN} if either real or imaginary part of the
* input argument is <code>NaN</code>.
* input argument is <code>NaN</code>.</p>
* <p>
* Infinite values in real or imaginary parts of the input may result in
* infinite or NaN values returned in parts of the result.<pre>
@ -663,7 +663,7 @@ public class Complex implements Serializable {
* <code>
* sin(1 &plusmn; INFINITY i) = 1 &plusmn; INFINITY i
* sin(&plusmn;INFINITY + i) = NaN + NaN i
* sin(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i</code></pre>
* sin(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i</code></pre></p>
*
* @return the sine of this complex number.
* @since 1.2
@ -686,10 +686,10 @@ public class Complex implements Serializable {
* <code> sinh(a + bi) = sinh(a)cos(b)) + cosh(a)sin(b)i</code></pre>
* where the (real) functions on the right-hand side are
* {@link java.lang.Math#sin}, {@link java.lang.Math#cos},
* {@link MathUtils#cosh} and {@link MathUtils#sinh}.
* {@link MathUtils#cosh} and {@link MathUtils#sinh}.</p>
* <p>
* Returns {@link Complex#NaN} if either real or imaginary part of the
* input argument is <code>NaN</code>.
* input argument is <code>NaN</code>.</p>
* <p>
* Infinite values in real or imaginary parts of the input may result in
* infinite or NaN values returned in parts of the result.<pre>
@ -697,7 +697,7 @@ public class Complex implements Serializable {
* <code>
* sinh(1 &plusmn; INFINITY i) = NaN + NaN i
* sinh(&plusmn;INFINITY + i) = &plusmn; INFINITY + INFINITY i
* sinh(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i</code></pre
* sinh(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i</code></pre></p>
*
* @return the hyperbolic sine of this complex number
* @since 1.2
@ -725,10 +725,10 @@ public class Complex implements Serializable {
* <li><code>|a| = {@link Math#abs}(a)</code></li>
* <li><code>|a + bi| = {@link Complex#abs}(a + bi) </code></li>
* <li><code>sign(b) = {@link MathUtils#indicator}(b) </code>
* </ul>
* </ul></p>
* <p>
* Returns {@link Complex#NaN} if either real or imaginary part of the
* input argument is <code>NaN</code>.
* input argument is <code>NaN</code>.</p>
* <p>
* Infinite values in real or imaginary parts of the input may result in
* infinite or NaN values returned in parts of the result.<pre>
@ -739,7 +739,7 @@ public class Complex implements Serializable {
* sqrt(-INFINITY + i) = 0 + INFINITY i
* sqrt(INFINITY &plusmn; INFINITY i) = INFINITY + NaN i
* sqrt(-INFINITY &plusmn; INFINITY i) = NaN &plusmn; INFINITY i
* </code></pre>
* </code></pre></p>
*
* @return the square root of this complex number
* @since 1.2
@ -769,13 +769,13 @@ public class Complex implements Serializable {
* number.
* <p>
* Computes the result directly as
* <code>sqrt(Complex.ONE.subtract(z.multiply(z)))</code>.
* <code>sqrt(Complex.ONE.subtract(z.multiply(z)))</code>.</p>
* <p>
* Returns {@link Complex#NaN} if either real or imaginary part of the
* input argument is <code>NaN</code>.
* input argument is <code>NaN</code>.</p>
* <p>
* 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.</p>
*
* @return the square root of 1 - <code>this</code><sup>2</sup>
* @since 1.2
@ -793,10 +793,10 @@ public class Complex implements Serializable {
* <code>tan(a + bi) = sin(2a)/(cos(2a)+cosh(2b)) + [sinh(2b)/(cos(2a)+cosh(2b))]i</code></pre>
* where the (real) functions on the right-hand side are
* {@link java.lang.Math#sin}, {@link java.lang.Math#cos},
* {@link MathUtils#cosh} and {@link MathUtils#sinh}.
* {@link MathUtils#cosh} and {@link MathUtils#sinh}.</p>
* <p>
* Returns {@link Complex#NaN} if either real or imaginary part of the
* input argument is <code>NaN</code>.
* input argument is <code>NaN</code>.</p>
* <p>
* Infinite (or critical) values in real or imaginary parts of the input may
* result in infinite or NaN values returned in parts of the result.<pre>
@ -805,7 +805,7 @@ public class Complex implements Serializable {
* tan(1 &plusmn; INFINITY i) = 0 + NaN i
* tan(&plusmn;INFINITY + i) = NaN + NaN i
* tan(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i
* tan(&plusmn;&pi;/2 + 0 i) = &plusmn;INFINITY + NaN i</code></pre>
* tan(&plusmn;&pi;/2 + 0 i) = &plusmn;INFINITY + NaN i</code></pre></p>
*
* @return the tangent of this complex number
* @since 1.2
@ -831,10 +831,10 @@ public class Complex implements Serializable {
* <code>tan(a + bi) = sinh(2a)/(cosh(2a)+cos(2b)) + [sin(2b)/(cosh(2a)+cos(2b))]i</code></pre>
* where the (real) functions on the right-hand side are
* {@link java.lang.Math#sin}, {@link java.lang.Math#cos},
* {@link MathUtils#cosh} and {@link MathUtils#sinh}.
* {@link MathUtils#cosh} and {@link MathUtils#sinh}.</p>
* <p>
* Returns {@link Complex#NaN} if either real or imaginary part of the
* input argument is <code>NaN</code>.
* input argument is <code>NaN</code>.</p>
* <p>
* Infinite values in real or imaginary parts of the input may result in
* infinite or NaN values returned in parts of the result.<pre>
@ -843,7 +843,7 @@ public class Complex implements Serializable {
* tanh(1 &plusmn; INFINITY i) = NaN + NaN i
* tanh(&plusmn;INFINITY + i) = NaN + 0 i
* tanh(&plusmn;INFINITY &plusmn; INFINITY i) = NaN + NaN i
* tanh(0 + (&pi;/2)i) = NaN + INFINITY i</code></pre>
* tanh(0 + (&pi;/2)i) = NaN + INFINITY i</code></pre></p>
*
* @return the hyperbolic tangent of this complex number
* @since 1.2

6
src/java/org/apache/commons/math/complex/ComplexUtils.java
View File

@ -242,10 +242,10 @@ public class ComplexUtils {
* Creates a complex number from the given polar representation.
* <p>
* The value returned is <code>r&middot;e<sup>i&middot;theta</sup></code>,
* computed as <code>r&middot;cos(theta) + r&middot;sin(theta)i</code>
* computed as <code>r&middot;cos(theta) + r&middot;sin(theta)i</code></p>
* <p>
* If either <code>r</code> or <code>theta</code> is NaN, or
* <code>theta</code> is infinite, {@link Complex#NaN} is returned.
* <code>theta</code> is infinite, {@link Complex#NaN} is returned.</p>
* <p>
* If <code>r</code> is infinite and <code>theta</code> is finite,
* infinite or NaN values may be returned in parts of the result, following
@ -255,7 +255,7 @@ public class ComplexUtils {
* polar2Complex(INFINITY, &pi;/4) = INFINITY + INFINITY i
* polar2Complex(INFINITY, 0) = INFINITY + NaN i
* polar2Complex(INFINITY, -&pi;/4) = INFINITY - INFINITY i
* polar2Complex(INFINITY, 5&pi;/4) = -INFINITY - INFINITY i </code></pre>
* polar2Complex(INFINITY, 5&pi;/4) = -INFINITY - INFINITY i </code></pre></p>
*
* @param r the modulus of the complex number to create
* @param theta the argument of the complex number to create

22
src/java/org/apache/commons/math/random/AbstractRandomGenerator.java
View File

@ -25,7 +25,7 @@ package org.apache.commons.math.random;
* Concrete implementations <strong>must</strong> override
* this method and <strong>should</strong> provide better / more
* performant implementations of the other methods if the underlying PRNG
* supplies them.
* supplies them.</p>
*
* @since 1.1
* @version $Revision$ $Date$
@ -66,7 +66,7 @@ public abstract class AbstractRandomGenerator implements RandomGenerator {
* <p>
* Implementations that do not override the default implementation of
* <code>nextGaussian</code> should include a call to {@link #clear} in the
* implementation of this method.
* implementation of this method.</p>
*
* @param seed the seed value
*/
@ -78,7 +78,7 @@ public abstract class AbstractRandomGenerator implements RandomGenerator {
* the length of the byte array.
* <p>
* The default implementation fills the array with bytes extracted from
* random integers generated using {@link #nextInt}.
* random integers generated using {@link #nextInt}.</p>
*
* @param bytes the non-null byte array in which to put the
* random bytes
@ -108,7 +108,7 @@ public abstract class AbstractRandomGenerator implements RandomGenerator {
* The default implementation provided here returns
* <pre>
* <code>(int) (nextDouble() * Integer.MAX_VALUE)</code>
* </pre>
* </pre></p>
*
* @return the next pseudorandom, uniformly distributed <code>int</code>
* value from this random number generator's sequence
@ -125,7 +125,7 @@ public abstract class AbstractRandomGenerator implements RandomGenerator {
* The default implementation returns
* <pre>
* <code>(int) (nextDouble() * n</code>
* </pre>
* </pre></p>
*
* @param n the bound on the random number to be returned. Must be
* positive.
@ -150,7 +150,7 @@ public abstract class AbstractRandomGenerator implements RandomGenerator {
* The default implementation returns
* <pre>
* <code>(long) (nextDouble() * Long.MAX_VALUE)</code>
* </pre>
* </pre></p>
*
* @return the next pseudorandom, uniformly distributed <code>long</code>
*value from this random number generator's sequence
@ -167,7 +167,7 @@ public abstract class AbstractRandomGenerator implements RandomGenerator {
* The default implementation returns
* <pre>
* <code>nextDouble() <= 0.5</code>
* </pre>
* </pre></p>
*
* @return the next pseudorandom, uniformly distributed
* <code>boolean</code> value from this random number generator's
@ -185,7 +185,7 @@ public abstract class AbstractRandomGenerator implements RandomGenerator {
* The default implementation returns
* <pre>
* <code>(float) nextDouble() </code>
* </pre>
* </pre></p>
*
* @return the next pseudorandom, uniformly distributed <code>float</code>
* value between <code>0.0</code> and <code>1.0</code> from this
@ -201,7 +201,7 @@ public abstract class AbstractRandomGenerator implements RandomGenerator {
* <code>1.0</code> from this random number generator's sequence.
* <p>
* This method provides the underlying source of random data used by the
* other methods.
* other methods.</p>
*
* @return the next pseudorandom, uniformly distributed
* <code>double</code> value between <code>0.0</code> and
@ -216,13 +216,13 @@ public abstract class AbstractRandomGenerator implements RandomGenerator {
* <p>
* The default implementation uses the <em>Polar Method</em>
* due to G.E.P. Box, M.E. Muller and G. Marsaglia, as described in
* D. Knuth, <u>The Art of Computer Programming</u>, 3.4.1C.
* D. Knuth, <u>The Art of Computer Programming</u>, 3.4.1C.</p>
* <p>
* The algorithm generates a pair of independent random values. One of
* these is cached for reuse, so the full algorithm is not executed on each
* activation. Implementations that do not override this method should
* make sure to call {@link #clear} to clear the cached value in the
* implementation of {@link #setSeed(long)}.
* implementation of {@link #setSeed(long)}.</p>
*
* @return the next pseudorandom, Gaussian ("normally") distributed
* <code>double</code> value with mean <code>0.0</code> and

4
src/java/org/apache/commons/math/random/EmpiricalDistribution.java
View File

@ -40,9 +40,9 @@ import org.apache.commons.math.stat.descriptive.StatisticalSummary;
* <li>generating random values from the distribution</li>
* </ul>
* Applications can use <code>EmpiricalDistribution</code> implementations to
* build grouped frequnecy histograms representing the input data or to
* build grouped frequency histograms representing the input data or to
* generate random values "like" those in the input file -- i.e., the values
* generated will follow the distribution of the values in the file.
* generated will follow the distribution of the values in the file.</p>
*
* @version $Revision$ $Date$
*/

7
src/java/org/apache/commons/math/random/NotPositiveDefiniteMatrixException.java
View File

@ -19,9 +19,12 @@ package org.apache.commons.math.random;
import org.apache.commons.math.MathException;
/** This class represents exceptions thrown by the correlated random
/**
* This class represents exceptions thrown by the correlated random
* vector generator.
* @version $Revision:$ $Date$
*
* @since 1.2
* @version $Revision$ $Date$
*/
public class NotPositiveDefiniteMatrixException extends MathException {

55
src/java/org/apache/commons/math/random/RandomData.java
View File

@ -29,12 +29,12 @@ public interface RandomData {
* <p>
* The generated string will be random, but not cryptographically
* secure. To generate cryptographically secure strings, use
* <code>nextSecureHexString</code>
* <code>nextSecureHexString</code></p>
* <p>
* <strong>Preconditions</strong>:<ul>
* <li><code>len > 0</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul>
* </ul></p>
*
* @param len the length of the string to be generated
* @return random string of hex characters of length <code>len</code>
@ -47,12 +47,12 @@ public interface RandomData {
* <p>
* The generated integer will be random, but not cryptographically secure.
* To generate cryptographically secure integer sequences, use
* <code>nextSecureInt</code>.
* <code>nextSecureInt</code>.</p>
* <p>
* <strong>Preconditions</strong>:<ul>
* <li><code>lower < upper</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul>
* </ul></p>
*
* @param lower lower bound for generated integer
* @param upper upper bound for generated integer
@ -68,12 +68,12 @@ public interface RandomData {
* The generated long integer values will be random, but not
* cryptographically secure.
* To generate cryptographically secure sequences of longs, use
* <code>nextSecureLong</code>
* <code>nextSecureLong</code></p>
* <p>
* <strong>Preconditions</strong>:<ul>
* <li><code>lower < upper</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul>
* </ul></p>
*
* @param lower lower bound for generated integer
* @param upper upper bound for generated integer
@ -87,12 +87,12 @@ public interface RandomData {
* sequence.
* <p>
* If cryptographic security is not required,
* use <code>nextHexString()</code>.
* use <code>nextHexString()</code>.</p>
* <p>
* <strong>Preconditions</strong>:<ul>
* <li><code>len > 0</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul>
* </ul></p>
* @param len length of return string
* @return the random hex string
*/
@ -105,16 +105,16 @@ public interface RandomData {
* <p>
* Sequences of integers generated using this method will be
* cryptographically secure. If cryptographic security is not required,
* <code>nextInt</code> should be used instead of this method.
* <code>nextInt</code> should be used instead of this method.</p>
* <p>
* <strong>Definition</strong>:
* <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
* Secure Random Sequence</a>
* Secure Random Sequence</a></p>
* <p>
* <strong>Preconditions</strong>:<ul>
* <li><code>lower < upper</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul>
* </ul></p>
*
* @param lower lower bound for generated integer
* @param upper upper bound for generated integer
@ -125,19 +125,20 @@ public interface RandomData {
/**
* Generates a random long integer between <code>lower</code>
* and <code>upper</code> (endpoints included).<p>
* and <code>upper</code> (endpoints included).
* <p>
* Sequences of long values generated using this method will be
* cryptographically secure. If cryptographic security is not required,
* <code>nextLong</code> should be used instead of this method.
* <code>nextLong</code> should be used instead of this method.</p>
* <p>
* <strong>Definition</strong>:
* <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
* Secure Random Sequence</a>
* Secure Random Sequence</a></p>
* <p>
* <strong>Preconditions</strong>:<ul>
* <li><code>lower < upper</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul>
* </ul></p>
*
* @param lower lower bound for generated integer
* @param upper upper bound for generated integer
@ -152,12 +153,12 @@ public interface RandomData {
* <p>
* <strong>Definition</strong>:
* <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366j.htm">
* Poisson Distribution</a>
* Poisson Distribution</a></p>
* <p>
* <strong>Preconditions</strong>: <ul>
* <li>The specified mean <i>must</i> be positive (otherwise an
* IllegalArgumentException is thrown.)</li>
* </ul>
* </ul></p>
* @param mean Mean of the distribution
* @return poisson deviate with the specified mean
*/
@ -170,12 +171,12 @@ public interface RandomData {
* <p>
* <strong>Definition</strong>:
* <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm">
* Normal Distribution</a>
* Normal Distribution</a></p>
* <p>
* <strong>Preconditions</strong>: <ul>
* <li><code>sigma > 0</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul>
* </ul></p>
* @param mu Mean of the distribution
* @param sigma Standard deviation of the distribution
* @return random value from Gaussian distribution with mean = mu,
@ -189,12 +190,12 @@ public interface RandomData {
* <p>
* <strong>Definition</strong>:
* <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm">
* Exponential Distribution</a>
* Exponential Distribution</a></p>
* <p>
* <strong>Preconditions</strong>: <ul>
* <li><code>mu >= 0</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul>
* </ul></p>
* @param mean Mean of the distribution
* @return random value from exponential distribution
*/
@ -209,12 +210,12 @@ public interface RandomData {
* Uniform Distribution</a> <code>lower</code> and
* <code>upper - lower</code> are the
* <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm">
* location and scale parameters</a>, respectively.
* location and scale parameters</a>, respectively.</p>
* <p>
* <strong>Preconditions</strong>:<ul>
* <li><code>lower < upper</code> (otherwise an IllegalArgumentException
* is thrown.)</li>
* </ul>
* </ul></p>
*
* @param lower lower endpoint of the interval of support
* @param upper upper endpoint of the interval of support
@ -229,14 +230,14 @@ public interface RandomData {
* 0 through n-1</code> (inclusive).
* <p>
* Generated arrays represent permutations
* of <code>n</code> taken <code>k</code> at a time.
* of <code>n</code> taken <code>k</code> at a time.</p>
* <p>
* <strong>Preconditions:</strong><ul>
* <li> <code>k <= n</code></li>
* <li> <code>n > 0</code> </li>
* </ul>
* If the preconditions are not met, an IllegalArgumentException is
* thrown.
* thrown.</p>
*
* @param n domain of the permutation
* @param k size of the permutation
@ -254,14 +255,14 @@ public interface RandomData {
* c</code> are distinct, the resulting object array represents a
* <a href="http://rkb.home.cern.ch/rkb/AN16pp/node250.html#SECTION0002500000000000000000">
* Simple Random Sample</a> of size
* <code>k</code> from the elements of <code>c</code>.
* <code>k</code> from the elements of <code>c</code>.</p>
* <p>
* <strong>Preconditions:</strong><ul>
* <li> k must be less than or equal to the size of c </li>
* <li> c must not be empty </li>
* </ul>
* If the preconditions are not met, an IllegalArgumentException is
* thrown.
* thrown.</p>
*
* @param c collection to be sampled
* @param k size of the sample

34
src/java/org/apache/commons/math/random/RandomDataImpl.java
View File

@ -36,10 +36,10 @@ import java.util.Collection;
* <p>
* Supports reseeding the underlying pseudo-random number generator (PRNG).
* The <code>SecurityProvider</code> and <code>Algorithm</code>
* used by the <code>SecureRandom</code> instance can also be reset.
* used by the <code>SecureRandom</code> instance can also be reset.</p>
* <p>
* For details on the default PRNGs, see {@link java.util.Random} and
* {@link java.security.SecureRandom}.
* {@link java.security.SecureRandom}.</p>
* <p>
* <strong>Usage Notes</strong>: <ul>
* <li>
@ -75,7 +75,7 @@ import java.util.Collection;
* identical).</li>
* <li>
* This implementation is not synchronized.
* </ul>
* </ul></p>
*
* @version $Revision$ $Date$
*/
@ -109,12 +109,14 @@ public class RandomDataImpl implements RandomData, Serializable {
}
/**
* {@inheritDoc}<p>
* <strong>Algorithm Description:</strong> hex strings are generated
* using a 2-step process. <ol>
* <li>
* len/2+1 binary bytes are generated using the underlying Random</li>
* <li>
* Each binary byte is translated into 2 hex digits</li></ol>
* Each binary byte is translated into 2 hex digits</li></ol></p>
*
* @param len the desired string length.
* @return the random string.
*/
@ -190,6 +192,7 @@ public class RandomDataImpl implements RandomData, Serializable {
}
/**
* {@inheritDoc}<p>
* <strong>Algorithm Description:</strong> hex strings are generated in
* 40-byte segments using a 3-step process. <ol>
* <li>
@ -199,6 +202,7 @@ public class RandomDataImpl implements RandomData, Serializable {
* SHA-1 hash is applied to yield a 20-byte binary digest.</li>
* <li>
* Each byte of the binary digest is converted to 2 hex digits.</li></ol>
* </p>
*
* @param len the length of the generated string
* @return the random string
@ -288,17 +292,16 @@ public class RandomDataImpl implements RandomData, Serializable {
}
/**
* Generates a random long value from the Poisson distribution with the
* given mean.
* {@inheritDoc}
* <p>
* <strong>Algorithm Description</strong>:
* Uses simulation of a Poisson process using Uniform deviates, as
* described
* <a href="http://irmi.epfl.ch/cmos/Pmmi/interactive/rng7.htm">
* here.</a>
* here.</a></p>
* <p>
* The Poisson process (and hence value returned) is bounded by
* 1000 * mean.
* 1000 * mean.</p>
*
* @param mean mean of the Poisson distribution.
* @return the random Poisson value.
@ -348,7 +351,7 @@ public class RandomDataImpl implements RandomData, Serializable {
* <strong>Algorithm Description</strong>: Uses the
* <a href="http://www.jesus.ox.ac.uk/~clifford/a5/chap1/node5.html">
* Inversion Method</a> to generate exponentially distributed random values
* from uniform deviates.
* from uniform deviates.</p>
*
* @param mean the mean of the distribution
* @return the random Exponential value
@ -367,11 +370,12 @@ public class RandomDataImpl implements RandomData, Serializable {
}
/**
* {@inheritDoc}<p>
* <strong>Algorithm Description</strong>: scales the output of
* Random.nextDouble(), but rejects 0 values (i.e., will generate another
* random double if Random.nextDouble() returns 0).
* This is necessary to provide a symmetric output interval
* (both endpoints excluded).
* (both endpoints excluded).</p>
*
* @param lower the lower bound.
* @param upper the upper bound.
@ -397,7 +401,7 @@ public class RandomDataImpl implements RandomData, Serializable {
* Returns the RandomGenerator used to generate non-secure
* random data.
* <p>
* Creates and initializes a default generator if null.
* Creates and initializes a default generator if null.</p>
*
* @return the Random used to generate random data
* @since 1.1
@ -413,7 +417,7 @@ public class RandomDataImpl implements RandomData, Serializable {
/**
* Returns the SecureRandom used to generate secure random data.
* <p>
* Creates and initializes if null.
* Creates and initializes if null.</p>
*
* @return the SecureRandom used to generate secure random data
*/
@ -428,7 +432,7 @@ public class RandomDataImpl implements RandomData, Serializable {
/**
* Reseeds the random number generator with the supplied seed.
* <p>
* Will create and initialize if null.
* Will create and initialize if null.</p>
*
* @param seed the seed value to use
*/
@ -443,7 +447,7 @@ public class RandomDataImpl implements RandomData, Serializable {
* Reseeds the secure random number generator with the current time
* in milliseconds.
* <p>
* Will create and initialize if null.
* Will create and initialize if null.</p>
*/
public void reSeedSecure() {
if (secRand == null) {
@ -455,7 +459,7 @@ public class RandomDataImpl implements RandomData, Serializable {
/**
* Reseeds the secure random number generator with the supplied seed.
* <p>
* Will create and initialize if null.
* Will create and initialize if null.</p>
*
* @param seed the seed value to use
*/

5
src/java/org/apache/commons/math/random/RandomVectorGenerator.java
View File

@ -18,9 +18,10 @@
package org.apache.commons.math.random;
/** This interface represents a random generator for whole vectors.
*
* @since 1.2
* @version $Revision$ $Date$
*
*/
public interface RandomVectorGenerator {

2
src/java/org/apache/commons/math/random/UniformRandomGenerator.java
View File

@ -24,6 +24,8 @@ package org.apache.commons.math.random;
* deviation equal to 1. Generated values fall in the range
* [-&#x0221A;3, +&#x0221A;3].</p>
*
* @since 1.2
*
* @version $Revision$ $Date$
*/

16
src/java/org/apache/commons/math/random/ValueServer.java
View File

@ -26,7 +26,7 @@ import java.net.MalformedURLException;
* Generates values for use in simulation applications.
* <p>
* How values are generated is determined by the <code>mode</code>
* property.
* property.</p>
* <p>
* Supported <code>mode</code> values are: <ul>
* <li> DIGEST_MODE -- uses an empirical distribution </li>
@ -38,7 +38,7 @@ import java.net.MalformedURLException;
* <li> GAUSSIAN_MODE -- generates Gaussian distributed random values with
* mean = <code>mu</code> and
* standard deviation = <code>sigma</code></li>
* <li> CONSTANT_MODE -- returns <code>mu</code> every time.</li></ul>
* <li> CONSTANT_MODE -- returns <code>mu</code> every time.</li></ul></p>
*
* @version $Revision$ $Date$
*
@ -142,10 +142,10 @@ public class ValueServer {
* in <code>valuesFileURL</code>, using the default number of bins.
* <p>
* <code>valuesFileURL</code> must exist and be
* readable by *this at runtime.
* readable by *this at runtime.</p>
* <p>
* This method must be called before using <code>getNext()</code>
* with <code>mode = DIGEST_MODE</code>
* with <code>mode = DIGEST_MODE</code></p>
*
* @throws IOException if an I/O error occurs reading the input file
*/
@ -158,11 +158,11 @@ public class ValueServer {
* Computes the empirical distribution using values from the file
* in <code>valuesFileURL</code> and <code>binCount</code> bins.
* <p>
* <code>valuesFileURL</code> must exist and be
* readable by *this at runtime.
* <code>valuesFileURL</code> must exist and be readable by this process
* at runtime.</p>
* <p>
* This method must be called before using <code>getNext()</code>
* with <code>mode = DIGEST_MODE</code>
* with <code>mode = DIGEST_MODE</code></p>
*
* @param binCount the number of bins used in computing the empirical
* distribution
@ -287,7 +287,7 @@ public class ValueServer {
* <strong>Preconditions</strong>: <ul>
* <li>Before this method is called, <code>computeDistribution()</code>
* must have completed successfully; otherwise an
* <code>IllegalStateException</code> will be thrown</li></ul>
* <code>IllegalStateException</code> will be thrown</li></ul></p>
*
* @return next random value from the empirical distribution digest
*/