org.apache.commons.math3.optimization.general

## Class AbstractLeastSquaresOptimizer

- java.lang.Object
- - org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer<DifferentiableMultivariateVectorFunction>
  - - org.apache.commons.math3.optimization.general.AbstractLeastSquaresOptimizer

- All Implemented Interfaces:
    BaseMultivariateVectorOptimizer<DifferentiableMultivariateVectorFunction>, BaseOptimizer<PointVectorValuePair>, DifferentiableMultivariateVectorOptimizer
  Direct Known Subclasses:
    GaussNewtonOptimizer, LevenbergMarquardtOptimizer

      public abstract class AbstractLeastSquaresOptimizer
      extends BaseAbstractMultivariateVectorOptimizer<DifferentiableMultivariateVectorFunction>
      implements DifferentiableMultivariateVectorOptimizer

  Base class for implementing least squares optimizers. It handles the boilerplate methods associated to thresholds settings, jacobian and error estimation.
  This class uses the `DifferentiableMultivariateVectorFunction.jacobian()` of the function argument in method `optimize` and assumes that, in the matrix returned by the `value` method, the rows iterate on the model functions while the columns iterate on the parameters; thus, the numbers of rows is equal to the length of the `target` array while the number of columns is equal to the length of the `startPoint` array.
  Since:
    1.2
  Version:
    $Id: AbstractLeastSquaresOptimizer.java 1295552 2012-03-01 13:14:32Z erans $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `cols` Number of columns of the jacobian matrix.
    `protected double` | `cost` Cost value (square root of the sum of the residuals).
    `protected double[]` | `objective` Current objective function value.
    `protected double[]` | `point` Current point.
    `protected int` | `rows` Number of rows of the jacobian matrix.
    `protected double[][]` | `weightedResidualJacobian` Jacobian matrix of the weighted residuals.
    `protected double[]` | `weightedResiduals` Weighted residuals

    - ### Fields inherited from class org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer

      `evaluations`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractLeastSquaresOptimizer()` Simple constructor with default settings.
    `protected` | `AbstractLeastSquaresOptimizer(ConvergenceChecker<PointVectorValuePair> checker)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `double` | `getChiSquare()` Get a Chi-Square-like value assuming the N residuals follow N distinct normal distributions centered on 0 and whose variances are the reciprocal of the weights.
    `double[][]` | `getCovariances()` Get the covariance matrix of the optimized parameters.
    `double[][]` | `getCovariances(double threshold)` Get the covariance matrix of the optimized parameters.
    `int` | `getJacobianEvaluations()`
    `double` | `getRMS()` Get the Root Mean Square value.
    `double[]` | `guessParametersErrors()` Guess the errors in optimized parameters.
    `PointVectorValuePair` | `optimize(int maxEval, DifferentiableMultivariateVectorFunction f, double[] target, double[] weights, double[] startPoint)` Optimize an objective function.
    `protected void` | `updateJacobian()` Update the jacobian matrix.
    `protected void` | `updateResidualsAndCost()` Update the residuals array and cost function value.

    - ### Methods inherited from class org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer

      `computeObjectiveValue, doOptimize, getConvergenceChecker, getEvaluations, getMaxEvaluations, getStartPoint, getTargetRef, getWeightRef`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.apache.commons.math3.optimization.BaseOptimizer

      `getConvergenceChecker, getEvaluations, getMaxEvaluations`

- - ### Field Detail

    - #### weightedResidualJacobian

          protected double[][] weightedResidualJacobian

      Jacobian matrix of the weighted residuals. This matrix is in canonical form just after the calls to `updateJacobian()`, but may be modified by the solver in the derived class (the `Levenberg-Marquardt optimizer` does this).

    - #### cols

          protected int cols

      Number of columns of the jacobian matrix.

    - #### rows

          protected int rows

      Number of rows of the jacobian matrix.

    - #### point

          protected double[] point

      Current point.

    - #### objective

          protected double[] objective

      Current objective function value.

    - #### weightedResiduals

          protected double[] weightedResiduals

      Weighted residuals

    - #### cost

          protected double cost

      Cost value (square root of the sum of the residuals).

  - ### Constructor Detail

    - #### AbstractLeastSquaresOptimizer

          protected AbstractLeastSquaresOptimizer()

      Simple constructor with default settings. The convergence check is set to a `SimpleVectorValueChecker`.

    - #### AbstractLeastSquaresOptimizer

          protected AbstractLeastSquaresOptimizer(ConvergenceChecker<PointVectorValuePair> checker)

      Parameters:
        `checker` - Convergence checker.

  - ### Method Detail

    - #### getJacobianEvaluations

          public int getJacobianEvaluations()

      Returns:
        the number of evaluations of the Jacobian function.

    - #### updateJacobian

          protected void updateJacobian()

      Update the jacobian matrix.
      Throws:
        `DimensionMismatchException` - if the Jacobian dimension does not match problem dimension.

    - #### updateResidualsAndCost

          protected void updateResidualsAndCost()

      Update the residuals array and cost function value.
      Throws:
        `DimensionMismatchException` - if the dimension does not match the problem dimension.
        `TooManyEvaluationsException` - if the maximal number of evaluations is exceeded.

    - #### getRMS

          public double getRMS()

      Get the Root Mean Square value. Get the Root Mean Square value, i.e. the root of the arithmetic mean of the square of all weighted residuals. This is related to the criterion that is minimized by the optimizer as follows: if c if the criterion, and n is the number of measurements, then the RMS is sqrt (c/n).
      Returns:
        RMS value

    - #### getChiSquare

          public double getChiSquare()

      Get a Chi-Square-like value assuming the N residuals follow N distinct normal distributions centered on 0 and whose variances are the reciprocal of the weights.
      Returns:
        chi-square value

    - #### getCovariances

          public double[][] getCovariances()

      Get the covariance matrix of the optimized parameters.
      Returns:
        the covariance matrix.
      Throws:
        `SingularMatrixException` - if the covariance matrix cannot be computed (singular problem).
      See Also:
        `getCovariances(double)`

    - #### getCovariances

          public double[][] getCovariances(double threshold)

      Get the covariance matrix of the optimized parameters.
      Note that this operation involves the inversion of the `JTJ` matrix, where `J` is the Jacobian matrix. The `threshold` parameter is a way for the caller to specify that the result of this computation should be considered meaningless, and thus trigger an exception.
      Parameters:
        `threshold` - Singularity threshold.
      Returns:
        the covariance matrix.
      Throws:
        `SingularMatrixException` - if the covariance matrix cannot be computed (singular problem).

    - #### guessParametersErrors

          public double[] guessParametersErrors()

      Guess the errors in optimized parameters. Guessing is covariance-based: It only gives a rough order of magnitude.
      Returns:
        errors in optimized parameters
      Throws:
        `SingularMatrixException` - if the covariances matrix cannot be computed.
        `NumberIsTooSmallException` - if the number of degrees of freedom is not positive, i.e. the number of measurements is less or equal to the number of parameters.

    - #### optimize

          public PointVectorValuePair optimize(int maxEval,
                                      DifferentiableMultivariateVectorFunction f,
                                      double[] target,
                                      double[] weights,
                                      double[] startPoint)

      Optimize an objective function. Optimization is considered to be a weighted least-squares minimization. The cost function to be minimized is `∑weighti(objectivei - targeti)2`
      Specified by:
        `optimize` in interface `BaseMultivariateVectorOptimizer<DifferentiableMultivariateVectorFunction>`
      Overrides:
        `optimize` in class `BaseAbstractMultivariateVectorOptimizer<DifferentiableMultivariateVectorFunction>`
      Parameters:
        `maxEval` - Maximum number of function evaluations.
        `f` - Objective function.
        `target` - Target value for the objective functions at optimum.
        `weights` - Weights for the least squares cost computation.
        `startPoint` - Start point for optimization.
      Returns:
        the point/value pair giving the optimal value for objective function.

Copyright © 2003-2012 The Apache Software Foundation. All Rights Reserved.