From 7b62d0155efebb2748918a5e4f67ac0ee2e759da Mon Sep 17 00:00:00 2001 From: Phil Steitz Date: Mon, 28 Dec 2015 08:29:28 -0700 Subject: [PATCH] Javadoc fixes. --- .../LegendreHighPrecisionRuleFactory.java | 2 +- .../interpolation/LoessInterpolator.java | 26 ++--- .../interpolation/SplineInterpolator.java | 2 +- .../polynomials/PolynomialFunction.java | 10 +- .../polynomials/PolynomialSplineFunction.java | 4 +- .../polynomials/PolynomialsUtils.java | 100 +++++++++--------- 6 files changed, 71 insertions(+), 73 deletions(-) diff --git a/src/main/java/org/apache/commons/math4/analysis/integration/gauss/LegendreHighPrecisionRuleFactory.java b/src/main/java/org/apache/commons/math4/analysis/integration/gauss/LegendreHighPrecisionRuleFactory.java index 81e672724..e4108a239 100644 --- a/src/main/java/org/apache/commons/math4/analysis/integration/gauss/LegendreHighPrecisionRuleFactory.java +++ b/src/main/java/org/apache/commons/math4/analysis/integration/gauss/LegendreHighPrecisionRuleFactory.java @@ -27,7 +27,7 @@ import org.apache.commons.math4.util.Pair; * In this implementation, the lower and upper bounds of the natural interval * of integration are -1 and 1, respectively. * The Legendre polynomials are evaluated using the recurrence relation - * presented in * Abramowitz and Stegun, 1964. * * @since 3.1 diff --git a/src/main/java/org/apache/commons/math4/analysis/interpolation/LoessInterpolator.java b/src/main/java/org/apache/commons/math4/analysis/interpolation/LoessInterpolator.java index f256c1711..1209df50c 100644 --- a/src/main/java/org/apache/commons/math4/analysis/interpolation/LoessInterpolator.java +++ b/src/main/java/org/apache/commons/math4/analysis/interpolation/LoessInterpolator.java @@ -36,14 +36,14 @@ import org.apache.commons.math4.util.MathUtils; * Implements the * Local Regression Algorithm (also Loess, Lowess) for interpolation of * real univariate functions. - *

+ *

* For reference, see - * + * * William S. Cleveland - Robust Locally Weighted Regression and Smoothing - * Scatterplots - *

+ * Scatterplots

+ *

* This class implements both the loess method and serves as an interpolation - * adapter to it, allowing one to build a spline on the obtained loess fit. + * adapter to it, allowing one to build a spline on the obtained loess fit.

* * @since 2.0 */ @@ -65,16 +65,16 @@ public class LoessInterpolator * a particular point, this fraction of source points closest * to the current point is taken into account for computing * a least-squares regression. - *

- * A sensible value is usually 0.25 to 0.5. + *

+ * A sensible value is usually 0.25 to 0.5.

*/ private final double bandwidth; /** * The number of robustness iterations parameter: this many * robustness iterations are done. - *

+ *

* A sensible value is usually 0 (just the initial fit without any - * robustness iterations) to 4. + * robustness iterations) to 4.

*/ private final int robustnessIters; /** @@ -109,10 +109,10 @@ public class LoessInterpolator * @param bandwidth when computing the loess fit at * a particular point, this fraction of source points closest * to the current point is taken into account for computing - * a least-squares regression.
+ * a least-squares regression. * A sensible value is usually 0.25 to 0.5, the default value is * {@link #DEFAULT_BANDWIDTH}. - * @param robustnessIters This many robustness iterations are done.
+ * @param robustnessIters This many robustness iterations are done. * A sensible value is usually 0 (just the initial fit without any * robustness iterations) to 4, the default value is * {@link #DEFAULT_ROBUSTNESS_ITERS}. @@ -130,10 +130,10 @@ public class LoessInterpolator * @param bandwidth when computing the loess fit at * a particular point, this fraction of source points closest * to the current point is taken into account for computing - * a least-squares regression.
+ * a least-squares regression. * A sensible value is usually 0.25 to 0.5, the default value is * {@link #DEFAULT_BANDWIDTH}. - * @param robustnessIters This many robustness iterations are done.
+ * @param robustnessIters This many robustness iterations are done. * A sensible value is usually 0 (just the initial fit without any * robustness iterations) to 4, the default value is * {@link #DEFAULT_ROBUSTNESS_ITERS}. diff --git a/src/main/java/org/apache/commons/math4/analysis/interpolation/SplineInterpolator.java b/src/main/java/org/apache/commons/math4/analysis/interpolation/SplineInterpolator.java index 99d725c77..8de55324b 100644 --- a/src/main/java/org/apache/commons/math4/analysis/interpolation/SplineInterpolator.java +++ b/src/main/java/org/apache/commons/math4/analysis/interpolation/SplineInterpolator.java @@ -29,7 +29,7 @@ import org.apache.commons.math4.util.MathArrays; *

* 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."

+ * @code{x[0] < x[i] ... < x[n].} The x values are referred to as "knot points."

*

* 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 diff --git a/src/main/java/org/apache/commons/math4/analysis/polynomials/PolynomialFunction.java b/src/main/java/org/apache/commons/math4/analysis/polynomials/PolynomialFunction.java index 9d40a1b7b..9333c1eb3 100644 --- a/src/main/java/org/apache/commons/math4/analysis/polynomials/PolynomialFunction.java +++ b/src/main/java/org/apache/commons/math4/analysis/polynomials/PolynomialFunction.java @@ -79,8 +79,8 @@ public class PolynomialFunction implements UnivariateDifferentiableFunction, Ser /** * Compute the value of the function for the given argument. *

- * The value returned is
- * coefficients[n] * x^n + ... + coefficients[1] * x + coefficients[0] + * The value returned is

+ * {@code coefficients[n] * x^n + ... + coefficients[1] * x + coefficients[0]} *

* * @param x Argument for which the function value should be computed. @@ -189,7 +189,7 @@ public class PolynomialFunction implements UnivariateDifferentiableFunction, Ser * Subtract a polynomial from the instance. * * @param p Polynomial to subtract. - * @return a new polynomial which is the difference the instance minus {@code p}. + * @return a new polynomial which is the instance minus {@code p}. */ public PolynomialFunction subtract(final PolynomialFunction p) { // identify the lowest degree polynomial @@ -216,7 +216,7 @@ public class PolynomialFunction implements UnivariateDifferentiableFunction, Ser /** * Negate the instance. * - * @return a new polynomial. + * @return a new polynomial with all coefficients negated */ public PolynomialFunction negate() { double[] newCoefficients = new double[coefficients.length]; @@ -230,7 +230,7 @@ public class PolynomialFunction implements UnivariateDifferentiableFunction, Ser * Multiply the instance by a polynomial. * * @param p Polynomial to multiply by. - * @return a new polynomial. + * @return a new polynomial equal to this times {@code p} */ public PolynomialFunction multiply(final PolynomialFunction p) { double[] newCoefficients = new double[coefficients.length + p.coefficients.length - 1]; diff --git a/src/main/java/org/apache/commons/math4/analysis/polynomials/PolynomialSplineFunction.java b/src/main/java/org/apache/commons/math4/analysis/polynomials/PolynomialSplineFunction.java index afa7eef5e..b842a407f 100644 --- a/src/main/java/org/apache/commons/math4/analysis/polynomials/PolynomialSplineFunction.java +++ b/src/main/java/org/apache/commons/math4/analysis/polynomials/PolynomialSplineFunction.java @@ -57,8 +57,8 @@ import org.apache.commons.math4.util.MathArrays; * than the largest one, an IllegalArgumentException * is thrown. *
  • Let j be the index of the largest knot point that is less - * than or equal to x. The value returned is
    - * polynomials[j](x - knot[j])

    • + * than or equal to x. The value returned is + * {@code polynomials[j](x - knot[j])} * */ public class PolynomialSplineFunction implements UnivariateDifferentiableFunction { diff --git a/src/main/java/org/apache/commons/math4/analysis/polynomials/PolynomialsUtils.java b/src/main/java/org/apache/commons/math4/analysis/polynomials/PolynomialsUtils.java index 346644e9e..c4069792a 100644 --- a/src/main/java/org/apache/commons/math4/analysis/polynomials/PolynomialsUtils.java +++ b/src/main/java/org/apache/commons/math4/analysis/polynomials/PolynomialsUtils.java @@ -90,14 +90,15 @@ public class PolynomialsUtils { /** * Create a Chebyshev polynomial of the first kind. - *

    Chebyshev + *

    Chebyshev * polynomials of the first kind are orthogonal polynomials. - * They can be defined by the following recurrence relations: - * 

    -     *  T0(X)   = 1
-     *  T1(X)   = X
-     *  Tk+1(X) = 2X Tk(X) - Tk-1(X)
-     *

    + * They can be defined by the following recurrence relations:

    + * \( + * T_0(x) = 1 \\ + * T_1(x) = x \\ + * T_{k+1}(x) = 2x T_k(x) - T_{k-1}(x) + * \) + *

    * @param degree degree of the polynomial * @return Chebyshev polynomial of specified degree */ @@ -118,12 +119,13 @@ public class PolynomialsUtils { * Create a Hermite polynomial. *

    Hermite * polynomials are orthogonal polynomials. - * They can be defined by the following recurrence relations: - * 

    -     *  H0(X)   = 1
-     *  H1(X)   = 2X
-     *  Hk+1(X) = 2X Hk(X) - 2k Hk-1(X)
-     *

    + * They can be defined by the following recurrence relations:

    + * \( + * H_0(x) = 1 \\ + * H_1(x) = 2x \\ + * H_{k+1}(x) = 2x H_k(X) - 2k H_{k-1}(x) + * \) + *

    * @param degree degree of the polynomial * @return Hermite polynomial of specified degree @@ -146,12 +148,13 @@ public class PolynomialsUtils { * Create a Laguerre polynomial. *

    Laguerre * polynomials are orthogonal polynomials. - * They can be defined by the following recurrence relations: - * 

    -     *        L0(X)   = 1
-     *        L1(X)   = 1 - X
-     *  (k+1) Lk+1(X) = (2k + 1 - X) Lk(X) - k Lk-1(X)
-     *

    + * They can be defined by the following recurrence relations:

    + * \( + * L_0(x) = 1 \\ + * L_1(x) = 1 - x \\ + * (k+1) L_{k+1}(x) = (2k + 1 - x) L_k(x) - k L_{k-1}(x) + * \) + *

    * @param degree degree of the polynomial * @return Laguerre polynomial of specified degree */ @@ -174,12 +177,13 @@ public class PolynomialsUtils { * Create a Legendre polynomial. *

    Legendre * polynomials are orthogonal polynomials. - * They can be defined by the following recurrence relations: - * 

    -     *        P0(X)   = 1
-     *        P1(X)   = X
-     *  (k+1) Pk+1(X) = (2k+1) X Pk(X) - k Pk-1(X)
-     *

    + * They can be defined by the following recurrence relations:

    + * \( + * P_0(x) = 1 \\ + * P_1(x) = x \\ + * (k+1) P_{k+1}(x) = (2k+1) x P_k(x) - k P_{k-1}(x) + * \) + *

    * @param degree degree of the polynomial * @return Legendre polynomial of specified degree */ @@ -202,14 +206,15 @@ public class PolynomialsUtils { * Create a Jacobi polynomial. *

    Jacobi * polynomials are orthogonal polynomials. - * They can be defined by the following recurrence relations: - * 

    -     *        P0vw(X)   = 1
-     *        P-1vw(X)  = 0
-     *  2k(k + v + w)(2k + v + w - 2) Pkvw(X) =
-     *  (2k + v + w - 1)[(2k + v + w)(2k + v + w - 2) X + v2 - w2] Pk-1vw(X)
-     *  - 2(k + v - 1)(k + w - 1)(2k + v + w) Pk-2vw(X)
-     *

    + * They can be defined by the following recurrence relations:

    + * \( + * P_0^{vw}(x) = 1 \\ + * P_{-1}^{vw}(x) = 0 \\ + * 2k(k + v + w)(2k + v + w - 2) P_k^{vw}(x) = \\ + * (2k + v + w - 1)[(2k + v + w)(2k + v + w - 2) x + v^2 - w^2] P_{k-1}^{vw}(x) \\ + * - 2(k + v - 1)(k + w - 1)(2k + v + w) P_{k-2}^{vw}(x) + * \) + *

    * @param degree degree of the polynomial * @param v first exponent * @param w second exponent @@ -301,27 +306,20 @@ public class PolynomialsUtils { } /** - * Compute the coefficients of the polynomial Ps(x) + * Compute the coefficients of the polynomial \(P_s(x)\) * whose values at point {@code x} will be the same as the those from the - * original polynomial P(x) when computed at {@code x + shift}. - * Thus, if P(x) = Σi ai xi, - * then - * 
    -     *  
-     *   
-     *    
-     *    
-     *   
-     *   
-     *    
-     *    
-     *   
-     *  
    Ps(x)= Σi bi xi
    = Σi ai (x + shift)i
    
-     *
    + * original polynomial \(P(x)\) when computed at {@code x + shift}. + *

    + * More precisely, let \(\Delta = \) {@code shift} and let + * \(P_s(x) = P(x + \Delta)\). The returned array + * consists of the coefficients of \(P_s\). So if \(a_0, ..., a_{n-1}\) + * are the coefficients of \(P\), then the returned array + * \(b_0, ..., b_{n-1}\) satisfies the identity + * \(\sum_{i=0}^{n-1} b_i x^i = \sum_{i=0}^{n-1} a_i (x + \Delta)^i\) for all \(x\). * * @param coefficients Coefficients of the original polynomial. * @param shift Shift value. - * @return the coefficients bi of the shifted + * @return the coefficients \(b_i\) of the shifted * polynomial. */ public static double[] shift(final double[] coefficients, @@ -444,7 +442,7 @@ public class PolynomialsUtils { * Generate recurrence coefficients. * @param k highest degree of the polynomials used in the recurrence * @return an array of three coefficients such that - * Pk+1(X) = (a[0] + a[1] X) Pk(X) - a[2] Pk-1(X) + * \( P_{k+1}(x) = (a[0] + a[1] x) P_k(x) - a[2] P_{k-1}(x) \) */ BigFraction[] generate(int k); }