org.apache.commons.math3.optim.nonlinear.vector.jacobian

## Class AbstractLeastSquaresOptimizer

- java.lang.Object
- - org.apache.commons.math3.optim.BaseOptimizer<PAIR>
  - - org.apache.commons.math3.optim.BaseMultivariateOptimizer<PointVectorValuePair>
    - - org.apache.commons.math3.optim.nonlinear.vector.MultivariateVectorOptimizer
      - - org.apache.commons.math3.optim.nonlinear.vector.JacobianMultivariateVectorOptimizer
        - - org.apache.commons.math3.optim.nonlinear.vector.jacobian.AbstractLeastSquaresOptimizer

- Direct Known Subclasses:
    GaussNewtonOptimizer, LevenbergMarquardtOptimizer

      public abstract class AbstractLeastSquaresOptimizer
      extends JacobianMultivariateVectorOptimizer

  Base class for implementing least-squares optimizers. It provides methods for error estimation.
  Since:
    3.1
  Version:
    $Id$

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private double` | `cost` Cost value (square root of the sum of the residuals).
    `private RealMatrix` | `weightMatrixSqrt` Square-root of the weight matrix.

    - ### Fields inherited from class org.apache.commons.math3.optim.BaseOptimizer

      `evaluations, iterations`

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected double` | `computeCost(double[] residuals)` Computes the cost.
    `double[][]` | `computeCovariances(double[] params, double threshold)` Get the covariance matrix of the optimized parameters.
    `protected double[]` | `computeResiduals(double[] objectiveValue)` Computes the residuals.
    `double[]` | `computeSigma(double[] params, double covarianceSingularityThreshold)` Computes an estimate of the standard deviation of the parameters.
    `protected RealMatrix` | `computeWeightedJacobian(double[] params)` Computes the weighted Jacobian matrix.
    `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` | `getRMS()` Gets the root-mean-square (RMS) value.
    `RealMatrix` | `getWeightSquareRoot()` Gets the square-root of the weight matrix.
    `PointVectorValuePair` | `optimize(OptimizationData... optData)` Stores data and performs the optimization.
    `private void` | `parseOptimizationData(OptimizationData... optData)` Scans the list of (required and optional) optimization data that characterize the problem.
    `protected void` | `setCost(double cost)` Sets the cost.
    `private RealMatrix` | `squareRoot(RealMatrix m)` Computes the square-root of the weight matrix.

    - ### Methods inherited from class org.apache.commons.math3.optim.nonlinear.vector.JacobianMultivariateVectorOptimizer

      `computeJacobian`

    - ### Methods inherited from class org.apache.commons.math3.optim.nonlinear.vector.MultivariateVectorOptimizer

      `computeObjectiveValue, getTarget, getTargetSize, getWeight`

    - ### Methods inherited from class org.apache.commons.math3.optim.BaseMultivariateOptimizer

      `getLowerBound, getStartPoint, getUpperBound`

    - ### Methods inherited from class org.apache.commons.math3.optim.BaseOptimizer

      `doOptimize, getConvergenceChecker, getEvaluations, getIterations, getMaxEvaluations, getMaxIterations, incrementEvaluationCount, incrementIterationCount`

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

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

- - ### Field Detail

    - #### weightMatrixSqrt

          private RealMatrix weightMatrixSqrt

      Square-root of the weight matrix.

    - #### cost

          private double cost

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

  - ### Constructor Detail

    - #### AbstractLeastSquaresOptimizer

          protected AbstractLeastSquaresOptimizer(ConvergenceChecker<PointVectorValuePair> checker)

      Parameters:
        `checker` - Convergence checker.

  - ### Method Detail

    - #### computeWeightedJacobian

          protected RealMatrix computeWeightedJacobian(double[] params)

      Computes the weighted 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.

    - #### computeCost

          protected double computeCost(double[] residuals)

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

    - #### getRMS

          public double getRMS()

      Gets the root-mean-square (RMS) value. The RMS 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:
        the 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

    - #### getWeightSquareRoot

          public RealMatrix getWeightSquareRoot()

      Gets the square-root of the weight matrix.
      Returns:
        the square-root of the weight matrix.

    - #### setCost

          protected void setCost(double cost)

      Sets the cost.
      Parameters:
        `cost` - Cost value.

    - #### computeCovariances

          public double[][] computeCovariances(double[] params,
                                      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:
        `params` - Model parameters.
        `threshold` - Singularity threshold.
      Returns:
        the covariance matrix.
      Throws:
        `SingularMatrixException` - if the covariance matrix cannot be computed (singular problem).

    - #### computeSigma

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

      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.

    - #### optimize

          public PointVectorValuePair optimize(OptimizationData... optData)
                                        throws TooManyEvaluationsException

      Stores data and performs the optimization.
      Overrides:
        `optimize` in class `JacobianMultivariateVectorOptimizer`
      Parameters:
        `optData` - Optimization data. The following data will be looked for:
        - `MaxEval`
        - `InitialGuess`
        - `SimpleBounds`
        - `Target`
        - `Weight`
        - `ModelFunction`
        - `ModelFunctionJacobian`
      Returns:
        a point/value pair that satifies the convergence criteria.
      Throws:
        `TooManyEvaluationsException` - if the maximal number of evaluations is exceeded.
        `DimensionMismatchException` - if the initial guess, target, and weight arguments have inconsistent dimensions.

    - #### computeResiduals

          protected double[] computeResiduals(double[] objectiveValue)

      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.

    - #### parseOptimizationData

          private void parseOptimizationData(OptimizationData... optData)

      Scans the list of (required and optional) optimization data that characterize the problem. If the weight matrix is specified, the `weightMatrixSqrt` field is recomputed.
      Parameters:
        `optData` - Optimization data. The following data will be looked for:
        - `Weight`

    - #### squareRoot

          private RealMatrix squareRoot(RealMatrix m)

      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