diff --git a/project.properties b/project.properties index e82d987ed..e0517b09d 100644 --- a/project.properties +++ b/project.properties @@ -11,3 +11,11 @@ maven.xdoc.date=left maven.xdoc.version=${pom.currentVersion} maven.xdoc.developmentProcessUrl=http://jakarta.apache.org/commons/charter.html +maven.javadoc.links = http://java.sun.com/j2se/1.4.1/docs/api/,\ + http://jakarta.apache.org/commons/collections/api/,\ + http://jakarta.apache.org/commons/beanutils/api/,\ + http://jakarta.apache.org/commons/logging/api/ +maven.javadoc.links = http://java.sun.com/j2se/1.4.1/docs/api/,\ + http://jakarta.apache.org/commons/collections/api/,\ + http://jakarta.apache.org/commons/beanutils/api/,\ + http://jakarta.apache.org/commons/logging/api/ diff --git a/src/java/org/apache/commons/math/analysis/BrentSolver.java b/src/java/org/apache/commons/math/analysis/BrentSolver.java index 92bd0c484..c0818e177 100644 --- a/src/java/org/apache/commons/math/analysis/BrentSolver.java +++ b/src/java/org/apache/commons/math/analysis/BrentSolver.java @@ -61,7 +61,7 @@ import org.apache.commons.math.MathException; * It will only search for one zero in the given interval. * The function is supposed to be continuous but not necessarily smooth. * - * @version $Revision: 1.3 $ $Date: 2003/07/09 20:02:43 $ + * @version $Revision: 1.4 $ $Date: 2003/07/11 15:59:14 $ */ public class BrentSolver extends UnivariateRealSolverImpl { /** @@ -136,8 +136,8 @@ public class BrentSolver extends UnivariateRealSolverImpl { setResult(x1, i); return result; } - if (Math.abs(oldDelta) < tolerance - || Math.abs(y0) <= Math.abs(y1)) { + if ((Math.abs(oldDelta) < tolerance) || + (Math.abs(y0) <= Math.abs(y1))) { // Force bisection. delta = 0.5 * dx; oldDelta = delta; @@ -161,8 +161,8 @@ public class BrentSolver extends UnivariateRealSolverImpl { } else { p = -p; } - if (2.0 * p >= 1.5 * dx * p1 - Math.abs(tolerance * p1) - || p >= Math.abs(0.5 * oldDelta * p1)) { + if (2.0 * p >= 1.5 * dx * p1 - Math.abs(tolerance * p1) || + p >= Math.abs(0.5 * oldDelta * p1)) { // Inverse quadratic interpolation gives a value // in the wrong direction, or progress is slow. // Fall back to bisection. diff --git a/src/java/org/apache/commons/math/analysis/CubicSplineFunction.java b/src/java/org/apache/commons/math/analysis/CubicSplineFunction.java index 6ec8d16f4..015147b4a 100644 --- a/src/java/org/apache/commons/math/analysis/CubicSplineFunction.java +++ b/src/java/org/apache/commons/math/analysis/CubicSplineFunction.java @@ -64,71 +64,99 @@ import org.apache.commons.math.MathException; * polynominal coefficents are used. * Arguments outside of the domain cause an IllegalArgumentException. * - * @version $Revision: 1.2 $ $Date: 2003/07/09 20:02:43 $ - * + * @version $Revision: 1.3 $ $Date: 2003/07/11 15:59:14 $ */ public class CubicSplineFunction implements UnivariateRealFunction { - // Spline segment interval delimiters. - // Size is N+1 for N segments. + /** Spline segment interval delimiters. Size is N+1 for N segments. */ private double xval[]; - - // The spline segment's polynominal coefficients. - // The first index runs over the intervals, size is N. - // The second index adresses the coefficients in the segment, with - // index 0 being the absolute coefficient and index 3 the coefficient - // for the third power. - // The coefficients are setup so that x runs from 0 to xval[i+1]-xval[i]. + + /** + * The spline segment's polynominal coefficients. + * The first index runs over the intervals, size is N. + * The second index adresses the coefficients in the segment, with + * index 0 being the absolute coefficient and index 3 the coefficient + * for the third power. + * The coefficients are setup so that x runs from 0 to xval[i+1]-xval[i]. + */ private double c[][]; - public CubicSplineFunction(double xval[],double c[][]) { + /** + * Construct a function with the given segment delimiters and polynomial + * coefficients. + * @param xval Spline segment interval delimiters + * @param c spline segment's polynominal coefficients + */ + public CubicSplineFunction(double xval[], double c[][]) { + super(); // TODO: should copy the arguments here, for safety. This could be a major overhead. - this.xval=xval; - this.c=c; + this.xval = xval; + this.c = c; } - /* (non-Javadoc) - * @see org.apache.commons.math.UnivariateRealFunction#value(double) + /** + * Compute the value for the function. + * @param x the point for which the function value should be computed + * @return the value + * @throws MathException if the function couldn't be computed due to + * missing additional data or other environmental problems. + * @see UnivariateRealFunction#value(double) */ public double value(double x) throws MathException { - if(xxval[xval.length-1]) { + if (x < xval[0] || x > xval[xval.length - 1]) { throw new IllegalArgumentException("Argument outside domain"); } - int i=Arrays.binarySearch(xval,x); - if(i<0) { - i=-i-2; + int i = Arrays.binarySearch(xval, x); + if (i < 0) { + i = -i - 2; } - x=x-xval[i]; - return ((c[i][3]*x+c[i][2])*x+c[i][1])*x+c[i][0]; + x = x - xval[i]; + return ((c[i][3] * x + c[i][2]) * x + c[i][1]) * x + c[i][0]; } - /* (non-Javadoc) - * @see org.apache.commons.math.UnivariateRealFunction#firstDerivative(double) + /** + * Compute the value for the first derivative of the function. + * It is recommended to provide this method only if the first derivative is + * analytical. Numerical derivatives may be acceptable in some cases. + * An implementation should throw an UnsupportedOperationException if + * this method is not implemented. + * @param x the point for which the first derivative should be computed + * @return the value + * @throws MathException if the derivative couldn't be computed. + * @see UnivariateRealFunction#firstDerivative(double) */ public double firstDerivative(double x) throws MathException { - if(xxval[xval.length-1]) { + if (x < xval[0] || x > xval[xval.length - 1]) { throw new IllegalArgumentException("Argument outside domain"); } - int i=Arrays.binarySearch(xval,x); - if(i<0) { - i=-i-2; + int i = Arrays.binarySearch(xval, x); + if (i < 0) { + i = -i - 2; } - x=x-xval[i]; - return (3*c[i][3]*x+2*c[i][2])*x+c[i][1]; + x = x - xval[i]; + return (3 * c[i][3] * x + 2 * c[i][2]) * x + c[i][1]; } - /* (non-Javadoc) - * @see org.apache.commons.math.UnivariateRealFunction#secondDerivative(double) + /** + * Compute the value for the second derivative of the function. + * It is recommended to provide this method only if the second derivative is + * analytical. Numerical derivatives may be acceptable in some cases. + * An implementation should throw an UnsupportedOperationException if + * this method is not implemented. + * @param x the point for which the first derivative should be computed + * @return the value + * @throws MathException if the second derivative couldn't be computed. + * @see UnivariateRealFunction#secondDerivative(double) */ public double secondDerivative(double x) throws MathException { - if(xxval[xval.length-1]) { + if (x < xval[0] || x > xval[xval.length - 1]) { throw new IllegalArgumentException("Argument outside domain"); } - int i=Arrays.binarySearch(xval,x); - if(i<0) { - i=-i-2; + int i = Arrays.binarySearch(xval, x); + if (i < 0) { + i = -i - 2; } - x=x-xval[i]; - return 6*c[i][3]*x+2*c[i][2]; + x = x - xval[i]; + return 6 * c[i][3] * x + 2 * c[i][2]; } } diff --git a/src/java/org/apache/commons/math/analysis/SecantSolver.java b/src/java/org/apache/commons/math/analysis/SecantSolver.java index ca5ab4e89..60d12a573 100644 --- a/src/java/org/apache/commons/math/analysis/SecantSolver.java +++ b/src/java/org/apache/commons/math/analysis/SecantSolver.java @@ -63,7 +63,7 @@ import org.apache.commons.math.MathException; * It will only search for one zero in the given interval. * The function is supposed to be continuous but not necessarily smooth. * - * @version $Revision: 1.3 $ $Date: 2003/07/09 20:02:43 $ + * @version $Revision: 1.4 $ $Date: 2003/07/11 15:59:14 $ */ public class SecantSolver extends UnivariateRealSolverImpl { /** @@ -128,8 +128,8 @@ public class SecantSolver extends UnivariateRealSolverImpl { setResult(x1, i); return result; } - if (Math.abs(oldDelta) - < Math.max(relativeAccuracy * Math.abs(x1), absoluteAccuracy)) { + if (Math.abs(oldDelta) < + Math.max(relativeAccuracy * Math.abs(x1), absoluteAccuracy)) { setResult(x1, i); return result; } diff --git a/src/java/org/apache/commons/math/analysis/UnivariateFunction.java b/src/java/org/apache/commons/math/analysis/UnivariateFunction.java deleted file mode 100644 index d5d48594e..000000000 --- a/src/java/org/apache/commons/math/analysis/UnivariateFunction.java +++ /dev/null @@ -1,66 +0,0 @@ -/* ==================================================================== - * The Apache Software License, Version 1.1 - * - * Copyright (c) 2003 The Apache Software Foundation. All rights - * reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in - * the documentation and/or other materials provided with the - * distribution. - * - * 3. The end-user documentation included with the redistribution, if - * any, must include the following acknowlegement: - * "This product includes software developed by the - * Apache Software Foundation (http://www.apache.org/)." - * Alternately, this acknowlegement may appear in the software itself, - * if and wherever such third-party acknowlegements normally appear. - * - * 4. The names "The Jakarta Project", "Commons", and "Apache Software - * Foundation" must not be used to endorse or promote products derived - * from this software without prior written permission. For written - * permission, please contact apache@apache.org. - * - * 5. Products derived from this software may not be called "Apache" - * nor may "Apache" appear in their names without prior written - * permission of the Apache Software Foundation. - * - * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED - * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR - * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF - * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND - * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, - * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT - * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - * ==================================================================== - * - * This software consists of voluntary contributions made by many - * individuals on behalf of the Apache Software Foundation. For more - * information on the Apache Software Foundation, please see - * . - */ -package org.apache.commons.math.analysis; - -/** - * @version $Revision: 1.2 $ $Date: 2003/07/09 20:02:43 $ - */ -public interface UnivariateFunction { - // TODO: More documentation - - /** - * - */ - double evaluate(double x); -} diff --git a/src/java/org/apache/commons/math/analysis/UnivariateRealFunction.java b/src/java/org/apache/commons/math/analysis/UnivariateRealFunction.java index 29240e267..fb6774c6d 100644 --- a/src/java/org/apache/commons/math/analysis/UnivariateRealFunction.java +++ b/src/java/org/apache/commons/math/analysis/UnivariateRealFunction.java @@ -62,10 +62,9 @@ import org.apache.commons.math.MathException; * that derivatives are evaluated after the value, the evaluation algorithm * should throw an InvalidStateException if it can't cope with this. * - * @version $Revision: 1.2 $ $Date: 2003/07/09 20:02:43 $ + * @version $Revision: 1.3 $ $Date: 2003/07/11 15:59:14 $ */ public interface UnivariateRealFunction { - /** * Compute the value for the function. * @param x the point for which the function value should be computed @@ -74,7 +73,6 @@ public interface UnivariateRealFunction { * missing additional data or other environmental problems. * @throws RuntimeException if the operation isn't supported, the argument * was outside the supported domain or any other problem. - * */ public double value(double x) throws MathException; @@ -89,7 +87,6 @@ public interface UnivariateRealFunction { * @throws MathException if the derivative couldn't be computed. * @throws RuntimeException if the operation isn't supported, the argument * was outside the supported domain or any other problem. - * */ public double firstDerivative(double x) throws MathException; @@ -104,7 +101,6 @@ public interface UnivariateRealFunction { * @throws MathException if the second derivative couldn't be computed. * @throws RuntimeException if the operation isn't supported, the argument * was outside the supported domain or any other problem. - * */ public double secondDerivative(double x) throws MathException; } diff --git a/src/java/org/apache/commons/math/analysis/UnivariateRealInterpolator.java b/src/java/org/apache/commons/math/analysis/UnivariateRealInterpolator.java index 5122b1a24..6a0f3b2f8 100644 --- a/src/java/org/apache/commons/math/analysis/UnivariateRealInterpolator.java +++ b/src/java/org/apache/commons/math/analysis/UnivariateRealInterpolator.java @@ -56,9 +56,9 @@ package org.apache.commons.math.analysis; import org.apache.commons.math.MathException; /** - * Interface for interpolating a data set. + * Interface for interpolating a data set. * - * @version $Revision: 1.2 $ $Date: 2003/07/09 20:02:43 $ + * @version $Revision: 1.3 $ $Date: 2003/07/11 15:59:14 $ */ public interface UnivariateRealInterpolator { @@ -67,7 +67,8 @@ public interface UnivariateRealInterpolator { * @param xval the arguments for the interpolation points * @param yval the values for the interpolation points * @return a function which interpolates the data set - * @throws MathException if arguments violate assumptions made by the interpolationg algorithm + * @throws MathException if arguments violate assumptions made by the + * interpolationg algorithm */ public UnivariateRealFunction interpolate(double xval[], double yval[]) throws MathException; diff --git a/src/java/org/apache/commons/math/analysis/UnivariateRealSolver.java b/src/java/org/apache/commons/math/analysis/UnivariateRealSolver.java index 960154a29..40d177b05 100644 --- a/src/java/org/apache/commons/math/analysis/UnivariateRealSolver.java +++ b/src/java/org/apache/commons/math/analysis/UnivariateRealSolver.java @@ -60,7 +60,7 @@ import org.apache.commons.math.MathException; * functions. * An implementation will only search for one zero in the given interval. * - * @version $Revision: 1.3 $ $Date: 2003/07/09 20:02:43 $ + * @version $Revision: 1.4 $ $Date: 2003/07/11 15:59:14 $ */ public interface UnivariateRealSolver { @@ -184,7 +184,7 @@ public interface UnivariateRealSolver { * A solver may require that the interval brackets a single zero root. * @param min the lower bound for the interval. * @param max the upper bound for the interval. - * @return the value where the function is zero + * @return a value where the function is zero * @throws MathException if the iteration count was exceeded or the * solver detects convergence problems otherwise. */ @@ -196,7 +196,7 @@ public interface UnivariateRealSolver { * @param min the lower bound for the interval. * @param max the upper bound for the interval. * @param startValue the start value to use - * @return the value where the function is zero + * @return a value where the function is zero * @throws MathException if the iteration count was exceeded or the * solver detects convergence problems otherwise. */ diff --git a/src/java/org/apache/commons/math/analysis/UnivariateRealSolverFactory.java b/src/java/org/apache/commons/math/analysis/UnivariateRealSolverFactory.java index ba404ec58..d9d8f0e6c 100644 --- a/src/java/org/apache/commons/math/analysis/UnivariateRealSolverFactory.java +++ b/src/java/org/apache/commons/math/analysis/UnivariateRealSolverFactory.java @@ -66,12 +66,29 @@ import org.apache.commons.math.MathException; * (this may be controversial, because the configuration data * may also be used for the default solver used by the static * solve() method). - * @version $Revision: 1.2 $ $Date: 2003/07/09 20:02:43 $ + * @version $Revision: 1.3 $ $Date: 2003/07/11 15:59:14 $ */ public class UnivariateRealSolverFactory { - protected UnivariateRealSolverFactory() { + /** + * Default constructor. + */ + private UnivariateRealSolverFactory() { } + /** + * Create a new {@link UnivariateRealSolver} for the given function. The + * actual solver returned can be controlled by defining the + * org.apache.commons.math.analysis.UnivariateRealSolver + * property on the JVM command-line ( + * -Dorg.apache.commons.math.analysis.UnivariateRealSolver= + * class name). The value of the property should be any, + * fully qualified class name for a type that implements the + * {@link UnivariateRealSolver} interface. By default, an instance of + * {@link BrentSolver} is returned. + * @param f the function. + * @return the new solver. + * @throws MathConfigurationException if a + */ public static UnivariateRealSolver newSolver(UnivariateRealFunction f) throws MathConfigurationException { String solverClassName = @@ -81,8 +98,7 @@ public class UnivariateRealSolverFactory { try { Class clazz = Class.forName(solverClassName); Class paramClass[] = new Class[1]; - paramClass[0] = - Class.forName("org.apache.commons.math.analysis.UnivariateRealFunction"); + paramClass[0] = UnivariateRealFunction.class; Object param[] = new Object[1]; param[0] = f; return (UnivariateRealSolver)clazz.getConstructor( @@ -110,17 +126,38 @@ public class UnivariateRealSolverFactory { throw new MathConfigurationException(e); } catch (NoSuchMethodException e) { throw new MathConfigurationException( - "No constructor with UnivariateRealFunction in " - + solverClassName, + "No constructor with UnivariateRealFunction in " + + solverClassName, e); } } + /** + * Convience method to solve for zeros of real univariate functions. A + * default solver is created and used for solving. + * @param f the function. + * @param x0 the lower bound for the interval. + * @param x1 the upper bound for the interval. + * @return a value where the function is zero. + * @throws MathException if the iteration count was exceeded or the + * solver detects convergence problems otherwise. + */ public static double solve(UnivariateRealFunction f, double x0, double x1) throws MathException { return newSolver(f).solve(x0, x1); } + /** + * Convience method to solve for zeros of real univariate functions. A + * default solver is created and used for solving. + * @param f the function. + * @param x0 the lower bound for the interval. + * @param x1 the upper bound for the interval. + * @param absoluteAccuracy the accuracy to be used by the solver. + * @return a value where the function is zero. + * @throws MathException if the iteration count was exceeded or the + * solver detects convergence problems otherwise. + */ public static double solve( UnivariateRealFunction f, double x0,