From ffcdf39f8fa7ccd19c5c21a73fccb90c753592cd Mon Sep 17 00:00:00 2001 From: Gilles Sadowski Date: Fri, 5 Apr 2024 13:08:03 +0200 Subject: [PATCH] Update userguide. Some links are still broken (due to the refactoring). --- src/site/xdoc/userguide/analysis.xml | 142 +++++++++++------------ src/site/xdoc/userguide/distribution.xml | 4 +- src/site/xdoc/userguide/exceptions.xml | 14 +-- src/site/xdoc/userguide/filter.xml | 6 +- src/site/xdoc/userguide/fitting.xml | 26 ++--- src/site/xdoc/userguide/genetics.xml | 28 ++--- src/site/xdoc/userguide/leastsquares.xml | 52 ++++----- src/site/xdoc/userguide/linear.xml | 34 +++--- src/site/xdoc/userguide/ml.xml | 22 ++-- src/site/xdoc/userguide/ode.xml | 76 ++++++------ src/site/xdoc/userguide/optimization.xml | 56 ++++----- src/site/xdoc/userguide/overview.xml | 6 +- src/site/xdoc/userguide/random.xml | 8 +- src/site/xdoc/userguide/stat.xml | 106 ++++++++--------- src/site/xdoc/userguide/utilities.xml | 16 +-- 15 files changed, 298 insertions(+), 298 deletions(-) diff --git a/src/site/xdoc/userguide/analysis.xml b/src/site/xdoc/userguide/analysis.xml index 2def6bd0f8..6bd64a27a4 100644 --- a/src/site/xdoc/userguide/analysis.xml +++ b/src/site/xdoc/userguide/analysis.xml @@ -88,13 +88,13 @@

- - UnivariateSolver, - UnivariateDifferentiableSolver and + + UnivariateSolver, + UnivariateDifferentiableSolver and PolynomialSolver provide means to find roots of - univariate real-valued functions, - differentiable univariate real-valued functions, - and polynomial functions respectively. + univariate real-valued functions, + differentiable univariate real-valued functions, + and polynomial functions respectively. A root is the value where the function takes the value 0. Commons-Math includes implementations of the several root-finding algorithms:

@@ -102,85 +102,85 @@ Root solvers NameFunction typeConvergenceNeeds initial bracketingBracket side selection - Bisection - univariate real-valued functions + Bisection + univariate real-valued functions linear, guaranteed yes yes - Brent-Dekker - univariate real-valued functions + Brent-Dekker + univariate real-valued functions super-linear, guaranteed yes no - bracketing nth order Brent - univariate real-valued functions + bracketing nth order Brent + univariate real-valued functions variable order, guaranteed yes yes - Illinois Method - univariate real-valued functions + Illinois Method + univariate real-valued functions super-linear, guaranteed yes yes - Laguerre's Method - polynomial functions + Laguerre's Method + polynomial functions cubic for simple root, linear for multiple root yes no - Muller's Method using bracketing to deal with real-valued functions - univariate real-valued functions + Muller's Method using bracketing to deal with real-valued functions + univariate real-valued functions quadratic close to roots yes no - Muller's Method using modulus to deal with real-valued functions - univariate real-valued functions + Muller's Method using modulus to deal with real-valued functions + univariate real-valued functions quadratic close to root yes no - Newton-Raphson's Method - differentiable univariate real-valued functions + Newton-Raphson's Method + differentiable univariate real-valued functions quadratic, non-guaranteed no no - Pegasus Method - univariate real-valued functions + Pegasus Method + univariate real-valued functions super-linear, guaranteed yes yes - Regula Falsi (false position) Method - univariate real-valued functions + Regula Falsi (false position) Method + univariate real-valued functions linear, guaranteed yes yes - Ridder's Method - univariate real-valued functions + Ridder's Method + univariate real-valued functions super-linear yes no - Secant Method - univariate real-valued functions + Secant Method + univariate real-valued functions super-linear, non-guaranteed yes no @@ -236,9 +236,9 @@ ill-conditioned problems is to be solved, this number can be decreased in order to avoid wasting time. Bracketed + href="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/analysis/solvers/BracketedUnivariateSolver.html">Bracketed solvers also take an allowed solution + href="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/analysis/solvers/AllowedSolution.html">allowed solution enum parameter to specify which side of the final convergence interval should be selected as the root. It can be ANY_SIDE, LEFT_SIDE, RIGHT_SIDE, BELOW_SIDE or ABOVE_SIDE. Left and right are used to specify the root along @@ -372,13 +372,13 @@ double c = UnivariateSolverUtils.forceSide(100, function,

- A + A UnivariateInterpolator is used to find a univariate real-valued function f which for a given set of ordered pairs (xi,yi) yields f(xi)=yi to the best accuracy possible. The result is provided as an object implementing the + href="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/analysis/UnivariateFunction.html"> UnivariateFunction interface. It can therefore be evaluated at any point, including point not belonging to the original set. Currently, only an interpolator for generating natural cubic splines and a polynomial @@ -435,7 +435,7 @@ System.out println("f(" + interpolationX + ") = " + interpolatedY);

Hermite interpolation is an interpolation method that can use derivatives in addition to function values at sample points. The HermiteInterpolator + href="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/analysis/interpolation/HermiteInterpolator.html">HermiteInterpolator class implements this method for vector-valued functions. The sampling points can have any spacing (there are no requirements for a regular grid) and some points may provide derivatives while others don't provide them (or provide derivatives to a smaller order). Points are added one at a time, as shown in the following example: @@ -454,13 +454,13 @@ System.out.println("derivative at x = 0.5: " + interpolator.derivative(0.5)[0]); // should print "interpolation polynomial: 1 + 2 x + 4 x^2 - 4 x^3 + x^4" System.out.println("interpolation polynomial: " + interpolator.getPolynomials()[0]);

- A + A BivariateGridInterpolator is used to find a bivariate real-valued function f which for a given set of tuples (xi,yj,fij) yields f(xi,yj)=fij to the best accuracy possible. The result is provided as an object implementing the - + BivariateFunction interface. It can therefore be evaluated at any point, including a point not belonging to the original set. The arrays xi and yj must be @@ -472,25 +472,25 @@ System.out.println("interpolation polynomial: " + interpolator.getPolynomials()[ are computed from the function values sampled on a grid, as well as the values of the partial derivatives of the function at those grid points. From two-dimensional data sampled on a grid, the - + BicubicSplineInterpolator computes a - + bicubic interpolating function. Prior to computing an interpolating function, the - + SmoothingPolynomialBicubicSplineInterpolator class performs smoothing of the data by computing the polynomial that best fits each of the one-dimensional curves along each of the coordinate axes.

- A + A TrivariateGridInterpolator is used to find a trivariate real-valued function f which for a given set of tuples (xi,yj,zk, fijk) yields f(xi,yj,zk)=fijk to the best accuracy possible. The result is provided as an object implementing the - + TrivariateFunction interface. It can therefore be evaluated at any point, including a point not belonging to the original set. The arrays xi, yj and @@ -503,41 +503,41 @@ System.out.println("interpolation polynomial: " + interpolator.getPolynomials()[ are computed from the function values sampled on a grid, as well as the values of the partial derivatives of the function at those grid points. From three-dimensional data sampled on a grid, the - + TricubicSplineInterpolator computes a - + tricubic interpolating function.

- A + A UnivariateIntegrator provides the means to numerically integrate - + univariate real-valued functions. Commons-Math includes implementations of the following integration algorithms:

- The + The org.apache.commons.math4.analysis.polynomials package provides real coefficients polynomials.

- The + The PolynomialFunction class is the most general one, using traditional coefficients arrays. The - + PolynomialsUtils utility class provides static factory methods to build Chebyshev, Hermite, Jacobi, Laguerre and Legendre polynomials. Coefficients are computed using exact fractions so these factory methods can build polynomials @@ -546,21 +546,21 @@ System.out.println("interpolation polynomial: " + interpolator.getPolynomials()[

- The + The org.apache.commons.math4.analysis.differentiation package provides a general-purpose differentiation framework.

- The core class is + The core class is DerivativeStructure which holds the value and the differentials of a function. This class handles some arbitrary number of free parameters and arbitrary derivation order. It is used both as the input and the output type for the + href="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/analysis/differentiation/UnivariateDifferentiableFunction.html"> UnivariateDifferentiableFunction interface. Any differentiable function should implement this interface.

- The main idea behind the + The main idea behind the DerivativeStructure class is that it can be used almost as a number (i.e. it can be added, multiplied, its square root can be extracted or its cosine computed... However, in addition to computed the value itself when doing these computations, the partial derivatives are also computed @@ -577,7 +577,7 @@ System.out.println("interpolation polynomial: " + interpolator.getPolynomials()[

The workflow of computation of a derivatives of an expression y=f(x) is the following one. First we configure an input parameter x of type + href="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/analysis/differentiation/DerivativeStructure.html"> DerivativeStructure so it will drive the function to compute all derivatives up to order 3 for example. Then we compute y=f(x) normally by passing this parameter to the f function.At the end, we extract from y the value and the derivatives we want. As we have specified @@ -667,28 +667,28 @@ System.out.println("d2g/dxdy = " + g.getPartialDerivative(1, 1); System.out.println("d2g/dy2 = " + g.getPartialDerivative(0, 2);

There are several ways a user can create an implementation of the + href="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/analysis/differentiation/UnivariateDifferentiableFunction.html"> UnivariateDifferentiableFunction interface. The first method is to simply write it directly using - the appropriate methods from + the appropriate methods from DerivativeStructure to compute addition, subtraction, sine, cosine... This is often quite straigthforward and there is no need to remember the rules for differentiation: the user code only represent the function itself, the differentials will be computed automatically under the hood. The second method is to write a classical UnivariateFunction and to + href="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/analysis/UnivariateFunction.html">UnivariateFunction and to pass it to an existing implementation of the + href="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/analysis/differentiation/UnivariateFunctionDifferentiator.html"> UnivariateFunctionDifferentiator interface to retrieve a differentiated version of the same function. The first method is more suited to small functions for which user already control all the underlying code. The second method is more suited to either large functions that would be cumbersome to write using the - + DerivativeStructure API, or functions for which user does not have control to the full underlying code (for example functions that call external libraries).

Apache Commons Math provides one implementation of the + href="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/analysis/differentiation/UnivariateFunctionDifferentiator.html"> UnivariateFunctionDifferentiator interface: + href="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/analysis/differentiation/FiniteDifferencesDifferentiator.html"> FiniteDifferencesDifferentiator. This class creates a wrapper that will call the user-provided function on a grid sample and will use finite differences to compute the derivatives. It takes care of boundaries if the variable is not defined on the whole real line. It is possible to use more points than strictly @@ -726,22 +726,22 @@ for (double x = -10; x < 10; x += 0.1) { }

Note that using + href="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/analysis/differentiation/FiniteDifferencesDifferentiator.html"> FiniteDifferencesDifferentiatora> in order to have a - UnivariateDifferentiableFunction that can be provided to a Newton-Raphson's + href="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/analysis/differentiation/UnivariateDifferentiableFunction.html"> + UnivariateDifferentiableFunction that can be provided to a Newton-Raphson's solver is a very bad idea. The reason is that finite differences are not really accurate and needs lots of additional calls to the basic underlying function. If user initially have only the basic function available and needs to find its roots, it is much more accurate and much more efficient to use a solver that only requires the function values and not the derivatives. A good choice is - to use bracketing + to use bracketing nth order Brent method, which in fact converges faster than Newton-Raphson's and + href="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/analysis/solvers/NewtonRaphsonSolver.html">Newton-Raphson's and can be configured to a highere order (typically 5) than Newton-Raphson which is an order 2 method.

Another implementation of the + href="../commons-math-docs/apidocs/org/apache/commons/math4/legacy/analysis/differentiation/UnivariateFunctionDifferentiator.html"> UnivariateFunctionDifferentiator interface is under development in the related project Apache Commons Nabla. This implementation uses automatic code analysis and generation at binary level. However, at time of writing diff --git a/src/site/xdoc/userguide/distribution.xml b/src/site/xdoc/userguide/distribution.xml index 2f33bae800..8cb9fad8ba 100644 --- a/src/site/xdoc/userguide/distribution.xml +++ b/src/site/xdoc/userguide/distribution.xml @@ -33,12 +33,12 @@ Commons Math provides

The list of observed data points to be passed to fit can be built by incrementally - adding instances to an instance of WeightedObservedPoints, + adding instances to an instance of WeightedObservedPoints, and then retrieve the list of WeightedObservedPoint by calling the toList method on that container. A weight can be associated with each observed point; it allows to take into account uncertainty @@ -81,25 +81,25 @@ Fitting of specific functions are provided through the following classes: @@ -129,11 +129,11 @@ final double[] coeff = fitter.fit(obs.toList());

- The + The AbstractCurveFitter class provides the basic functionality for implementing other curve fitting classes. Users must provide their own implementation of the curve template as a class that implements - the + the ParametricUnivariateFunction interface.

diff --git a/src/site/xdoc/userguide/genetics.xml b/src/site/xdoc/userguide/genetics.xml index bf4c17ce0f..a8e7238999 100644 --- a/src/site/xdoc/userguide/genetics.xml +++ b/src/site/xdoc/userguide/genetics.xml @@ -31,15 +31,15 @@

- + GeneticAlgorithm provides an execution framework for Genetic Algorithms (GA). - - Populations, consisting of + + Populations, consisting of Chromosomes are evolved by the GeneticAlgorithm until a - - StoppingCondition is reached. Evolution is determined by - SelectionPolicy, - MutationPolicy and + + StoppingCondition is reached. Evolution is determined by + SelectionPolicy, + MutationPolicy and Fitness.

@@ -62,10 +62,10 @@