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

  Deprecated.
  As of 3.1 (to be removed in 4.0).

      @Deprecated
      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 constructs the Jacobian matrix of the function argument in method `optimize` and assumes that the rows of that matrix iterate on the model functions while the columns iterate on the parameters; thus, the numbers of rows is equal to the dimension of the `Target` while the number of columns is equal to the dimension of the `InitialGuess`.
  Since:
    1.2
  Version:
    $Id: AbstractLeastSquaresOptimizer.java 1422313 2012-12-15 18:53:41Z psteitz $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `cols` Deprecated. As of 3.1.
    `protected double` | `cost` Deprecated. As of 3.1. Field to become "private" in 4.0. Please use `setCost(double)`.
    `private static double` | `DEFAULT_SINGULARITY_THRESHOLD` Deprecated. As of 3.1.
    `private int` | `jacobianEvaluations` Deprecated. Number of evaluations of the Jacobian.
    `private MultivariateDifferentiableVectorFunction` | `jF` Deprecated. Objective function derivatives.
    `protected double[]` | `objective` Deprecated. As of 3.1.
    `protected double[]` | `point` Deprecated. As of 3.1.
    `protected int` | `rows` Deprecated. As of 3.1.
    `protected double[][]` | `weightedResidualJacobian` Deprecated. As of 3.1. To be removed in 4.0. Please use `computeWeightedJacobian(double[])` instead.
    `protected double[]` | `weightedResiduals` Deprecated. As of 3.1.
    `private RealMatrix` | `weightMatrixSqrt` Deprecated. Square-root of the weight matrix.

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

      `evaluations`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractLeastSquaresOptimizer()` Deprecated. See `SimpleValueChecker.SimpleValueChecker()`
    `protected` | `AbstractLeastSquaresOptimizer(ConvergenceChecker<PointVectorValuePair> checker)` Deprecated.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected double` | `computeCost(double[] residuals)` Deprecated. Computes the cost.
    `double[][]` | `computeCovariances(double[] params, double threshold)` Deprecated. Get the covariance matrix of the optimized parameters.
    `protected double[]` | `computeResiduals(double[] objectiveValue)` Deprecated. Computes the residuals.
    `double[]` | `computeSigma(double[] params, double covarianceSingularityThreshold)` Deprecated. Computes an estimate of the standard deviation of the parameters.
    `protected RealMatrix` | `computeWeightedJacobian(double[] params)` Deprecated. Computes the Jacobian matrix.
    `double` | `getChiSquare()` Deprecated. 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()` Deprecated. As of 3.1. Please use `computeCovariances(double[],double)` instead.
    `double[][]` | `getCovariances(double threshold)` Deprecated. As of 3.1. Please use `computeCovariances(double[],double)` instead.
    `int` | `getJacobianEvaluations()` Deprecated.
    `double` | `getRMS()` Deprecated. Get the Root Mean Square value.
    `RealMatrix` | `getWeightSquareRoot()` Deprecated. Gets the square-root of the weight matrix.
    `double[]` | `guessParametersErrors()` Deprecated. as of version 3.1, `computeSigma(double[],double)` should be used instead. It should be emphasized that `guessParametersErrors` and `computeSigma` are not strictly equivalent.
    `PointVectorValuePair` | `optimize(int maxEval, DifferentiableMultivariateVectorFunction f, double[] target, double[] weights, double[] startPoint)` Deprecated. As of 3.1. Please use `optimize(int,MultivariateDifferentiableVectorFunction,OptimizationData...)` instead.
    `PointVectorValuePair` | `optimize(int maxEval, MultivariateDifferentiableVectorFunction f, double[] target, double[] weights, double[] startPoint)` Deprecated. As of 3.1. Please use `optimize(int,MultivariateDifferentiableVectorFunction,OptimizationData...)` instead.
    `protected PointVectorValuePair` | `optimizeInternal(int maxEval, MultivariateDifferentiableVectorFunction f, OptimizationData... optData)` Deprecated. As of 3.1. Override is necessary only until this class's generic argument is changed to `MultivariateDifferentiableVectorFunction`.
    `protected void` | `setCost(double cost)` Deprecated. Sets the cost.
    `protected void` | `setUp()` Deprecated. Method which a subclass must override whenever its internal state depend on the `input` parsed by this base class.
    `private RealMatrix` | `squareRoot(RealMatrix m)` Deprecated. Computes the square-root of the weight matrix.
    `protected void` | `updateJacobian()` Deprecated. As of 3.1. Please use `computeWeightedJacobian(double[])` instead.
    `protected void` | `updateResidualsAndCost()` Deprecated. As of 3.1. Please use `computeResiduals(double[])`, `BaseAbstractMultivariateVectorOptimizer.computeObjectiveValue(double[])`, `computeCost(double[])` and `setCost(double)` instead.

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

      `computeObjectiveValue, doOptimize, getConvergenceChecker, getEvaluations, getMaxEvaluations, getObjectiveFunction, getStartPoint, getTarget, getTargetRef, getWeight, getWeightRef, optimize, optimizeInternal, optimizeInternal`

    - ### 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

    - #### DEFAULT_SINGULARITY_THRESHOLD

          @Deprecated
          private static final double DEFAULT_SINGULARITY_THRESHOLD

      Deprecated. As of 3.1.
      Singularity threshold (cf. `getCovariances(double)`).
      See Also:
        Constant Field Values

    - #### weightedResidualJacobian

          @Deprecated
          protected double[][] weightedResidualJacobian

      Deprecated. As of 3.1. To be removed in 4.0. Please use `computeWeightedJacobian(double[])` instead.
      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

          @Deprecated
          protected int cols

      Deprecated. As of 3.1.
      Number of columns of the jacobian matrix.

    - #### rows

          @Deprecated
          protected int rows

      Deprecated. As of 3.1.
      Number of rows of the jacobian matrix.

    - #### point

          @Deprecated
          protected double[] point

      Deprecated. As of 3.1.
      Current point.

    - #### objective

          @Deprecated
          protected double[] objective

      Deprecated. As of 3.1.
      Current objective function value.

    - #### weightedResiduals

          @Deprecated
          protected double[] weightedResiduals

      Deprecated. As of 3.1.
      Weighted residuals

    - #### cost

          @Deprecated
          protected double cost

      Deprecated. As of 3.1. Field to become "private" in 4.0. Please use `setCost(double)`.
      Cost value (square root of the sum of the residuals).

    - #### jF

          private MultivariateDifferentiableVectorFunction jF

      Deprecated.
      Objective function derivatives.

    - #### jacobianEvaluations

          private int jacobianEvaluations

      Deprecated.
      Number of evaluations of the Jacobian.

    - #### weightMatrixSqrt

          private RealMatrix weightMatrixSqrt

      Deprecated.
      Square-root of the weight matrix.

  - ### Constructor Detail

    - #### AbstractLeastSquaresOptimizer

          @Deprecated
          protected AbstractLeastSquaresOptimizer()

      Deprecated. See `SimpleValueChecker.SimpleValueChecker()`
      Simple constructor with default settings. The convergence check is set to a `SimpleVectorValueChecker`.

    - #### AbstractLeastSquaresOptimizer

          protected AbstractLeastSquaresOptimizer(ConvergenceChecker<PointVectorValuePair> checker)

      Deprecated.
      Parameters:
        `checker` - Convergence checker.

  - ### Method Detail

    - #### getJacobianEvaluations

          public int getJacobianEvaluations()

      Deprecated.
      Returns:
        the number of evaluations of the Jacobian function.

    - #### updateJacobian

          @Deprecated
          protected void updateJacobian()

      Deprecated. As of 3.1. Please use `computeWeightedJacobian(double[])` instead.
      Update the jacobian matrix.
      Throws:
        `DimensionMismatchException` - if the Jacobian dimension does not match problem dimension.

    - #### computeWeightedJacobian

          protected RealMatrix computeWeightedJacobian(double[] params)

      Deprecated.
      Computes the Jacobian matrix.
      Parameters:
        `params` - Model parameters at which to compute the Jacobian.
      Returns:
        the weighted Jacobian: W1/2 J.
      Throws:
        `DimensionMismatchException` - if the Jacobian dimension does not match problem dimension.
      Since:
        3.1

    - #### updateResidualsAndCost

          @Deprecated
          protected void updateResidualsAndCost()

      Deprecated. As of 3.1. Please use `computeResiduals(double[])`, `BaseAbstractMultivariateVectorOptimizer.computeObjectiveValue(double[])`, `computeCost(double[])` and `setCost(double)` instead.
      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.

    - #### computeCost

          protected double computeCost(double[] residuals)

      Deprecated.
      Computes the cost.
      Parameters:
        `residuals` - Residuals.
      Returns:
        the cost.
      Since:
        3.1
      See Also:
        `computeResiduals(double[])`

    - #### getRMS

          public double getRMS()

      Deprecated.
      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()

      Deprecated.
      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

    - #### getWeightSquareRoot

          public RealMatrix getWeightSquareRoot()

      Deprecated.
      Gets the square-root of the weight matrix.
      Returns:
        the square-root of the weight matrix.
      Since:
        3.1

    - #### setCost

          protected void setCost(double cost)

      Deprecated.
      Sets the cost.
      Parameters:
        `cost` - Cost value.
      Since:
        3.1

    - #### getCovariances

          @Deprecated
          public double[][] getCovariances()

      Deprecated. As of 3.1. Please use `computeCovariances(double[],double)` instead.
      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

          @Deprecated
          public double[][] getCovariances(double threshold)

      Deprecated. As of 3.1. Please use `computeCovariances(double[],double)` instead.
      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).

    - #### computeCovariances

          public double[][] computeCovariances(double[] params,
                                      double threshold)

      Deprecated.
      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:
        `params` - Model parameters.
        `threshold` - Singularity threshold.
      Returns:
        the covariance matrix.
      Throws:
        `SingularMatrixException` - if the covariance matrix cannot be computed (singular problem).
      Since:
        3.1

    - #### guessParametersErrors

          @Deprecated
          public double[] guessParametersErrors()

      Deprecated. as of version 3.1, `computeSigma(double[],double)` should be used instead. It should be emphasized that `guessParametersErrors` and `computeSigma` are not strictly equivalent.

      Returns an estimate of the standard deviation of each parameter. The returned values are the so-called (asymptotic) standard errors on the parameters, defined as `sd(a[i]) = sqrt(S / (n - m) * C[i][i])`, where `a[i]` is the optimized value of the `i`-th parameter, `S` is the minimized value of the sum of squares objective function (as returned by `getChiSquare()`), `n` is the number of observations, `m` is the number of parameters and `C` is the covariance matrix.

      See also Wikipedia, or MathWorld, equations (34) and (35) for a particular case.

      Returns:
        an estimate of the standard deviation of the optimized parameters
      Throws:
        `SingularMatrixException` - if the covariance 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.

    - #### computeSigma

          public double[] computeSigma(double[] params,
                              double covarianceSingularityThreshold)

      Deprecated.
      Computes an estimate of the standard deviation of the parameters. The returned values are the square root of the diagonal coefficients of the covariance matrix, `sd(a[i]) ~= sqrt(C[i][i])`, where `a[i]` is the optimized value of the `i`-th parameter, and `C` is the covariance matrix.
      Parameters:
        `params` - Model parameters.
        `covarianceSingularityThreshold` - Singularity threshold (see `computeCovariances`).
      Returns:
        an estimate of the standard deviation of the optimized parameters
      Throws:
        `SingularMatrixException` - if the covariance matrix cannot be computed.
      Since:
        3.1

    - #### optimize

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

      Deprecated. As of 3.1. Please use `optimize(int,MultivariateDifferentiableVectorFunction,OptimizationData...)` instead.
      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.

    - #### optimize

          @Deprecated
          public PointVectorValuePair optimize(int maxEval,
                                                 MultivariateDifferentiableVectorFunction f,
                                                 double[] target,
                                                 double[] weights,
                                                 double[] startPoint)

      Deprecated. As of 3.1. Please use `optimize(int,MultivariateDifferentiableVectorFunction,OptimizationData...)` instead.
      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`
      Parameters:
        `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.
        `maxEval` - Maximum number of function evaluations.
      Returns:
        the point/value pair giving the optimal value for objective function.
      Throws:
        `DimensionMismatchException` - if the start point dimension is wrong.
        `TooManyEvaluationsException` - if the maximal number of evaluations is exceeded.
        `NullArgumentException` - if any argument is `null`.

    - #### optimizeInternal

          @Deprecated
          protected PointVectorValuePair optimizeInternal(int maxEval,
                                                         MultivariateDifferentiableVectorFunction f,
                                                         OptimizationData... optData)

      Deprecated. As of 3.1. Override is necessary only until this class's generic argument is changed to `MultivariateDifferentiableVectorFunction`.
      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`
      Parameters:
        `maxEval` - Allowed number of evaluations of the objective function.
        `f` - Objective function.
        `optData` - Optimization data. The following data will be looked for:
        - `Target`
        - `Weight`
        - `InitialGuess`
      Returns:
        the point/value pair giving the optimal value of the objective function.
      Throws:
        `TooManyEvaluationsException` - if the maximal number of evaluations is exceeded.
        `DimensionMismatchException` - if the target, and weight arguments have inconsistent dimensions.
      Since:
        3.1
      See Also:
        `BaseAbstractMultivariateVectorOptimizer.optimizeInternal(int,MultivariateVectorFunction,OptimizationData[])`

    - #### setUp

          protected void setUp()

      Deprecated.
      Method which a subclass must override whenever its internal state depend on the `input` parsed by this base class. It will be called after the parsing step performed in the `optimize` method and just before `BaseAbstractMultivariateVectorOptimizer.doOptimize()`.
      Overrides:
        `setUp` in class `BaseAbstractMultivariateVectorOptimizer<DifferentiableMultivariateVectorFunction>`

    - #### computeResiduals

          protected double[] computeResiduals(double[] objectiveValue)

      Deprecated.
      Computes the residuals. The residual is the difference between the observed (target) values and the model (objective function) value. There is one residual for each element of the vector-valued function.
      Parameters:
        `objectiveValue` - Value of the the objective function. This is the value returned from a call to `computeObjectiveValue` (whose array argument contains the model parameters).
      Returns:
        the residuals.
      Throws:
        `DimensionMismatchException` - if `params` has a wrong length.
      Since:
        3.1

    - #### squareRoot

          private RealMatrix squareRoot(RealMatrix m)

      Deprecated.
      Computes the square-root of the weight matrix.
      Parameters:
        `m` - Symmetric, positive-definite (weight) matrix.
      Returns:
        the square-root of the weight matrix.

Copyright (c) 2003-2013 Apache Software Foundation