org.apache.commons.math.optimization.general

## Class AbstractLeastSquaresOptimizer

- java.lang.Object
- - org.apache.commons.math.optimization.general.AbstractLeastSquaresOptimizer

- All Implemented Interfaces:
    DifferentiableMultivariateVectorialOptimizer
  Direct Known Subclasses:
    GaussNewtonOptimizer, LevenbergMarquardtOptimizer

      public abstract class AbstractLeastSquaresOptimizer
      extends java.lang.Object
      implements DifferentiableMultivariateVectorialOptimizer

  Base class for implementing least squares optimizers.

  This base class handles the boilerplate methods associated to thresholds settings, jacobian and error estimation.

  Since:
    1.2
  Version:
    $Revision: 1073158 $ $Date: 2011-02-21 22:46:52 +0100 (lun. 21 févr. 2011) $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected VectorialConvergenceChecker` | `checker` Convergence checker.
    `protected int` | `cols` Number of columns of the jacobian matrix.
    `protected double` | `cost` Cost value (square root of the sum of the residuals).
    `static int` | `DEFAULT_MAX_ITERATIONS` Default maximal number of iterations allowed.
    `private DifferentiableMultivariateVectorialFunction` | `function` Objective function.
    `private int` | `iterations` Number of iterations already performed.
    `protected double[][]` | `jacobian` Jacobian matrix.
    `private int` | `jacobianEvaluations` Number of jacobian evaluations.
    `private MultivariateMatrixFunction` | `jF` Objective function derivatives.
    `private int` | `maxEvaluations` Maximal number of evaluations allowed.
    `private int` | `maxIterations` Maximal number of iterations allowed.
    `protected double[]` | `objective` Current objective function value.
    `private int` | `objectiveEvaluations` Number of evaluations already performed.
    `protected double[]` | `point` Current point.
    `protected double[]` | `residuals` Current residuals.
    `protected double[]` | `residualsWeights` Weight for the least squares cost computation.
    `protected int` | `rows` Number of rows of the jacobian matrix.
    `protected double[]` | `targetValues` Target value for the objective functions at optimum.
    `protected double[][]` | `wjacobian` Weighted Jacobian
    `protected double[]` | `wresiduals` Weighted residuals

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractLeastSquaresOptimizer()` Simple constructor with default settings.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract VectorialPointValuePair` | `doOptimize()` Perform the bulk of optimization algorithm.
    `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.
    `VectorialConvergenceChecker` | `getConvergenceChecker()` Get the convergence checker.
    `double[][]` | `getCovariances()` Get the covariance matrix of optimized parameters.
    `int` | `getEvaluations()` Get the number of evaluations of the objective function.
    `int` | `getIterations()` Get the number of iterations realized by the algorithm.
    `int` | `getJacobianEvaluations()` Get the number of evaluations of the objective function jacobian .
    `int` | `getMaxEvaluations()` Get the maximal number of functions evaluations.
    `int` | `getMaxIterations()` Get the maximal number of iterations of the algorithm.
    `double` | `getRMS()` Get the Root Mean Square value.
    `double[]` | `guessParametersErrors()` Guess the errors in optimized parameters.
    `protected void` | `incrementIterationsCounter()` Increment the iterations counter by 1.
    `VectorialPointValuePair` | `optimize(DifferentiableMultivariateVectorialFunction f, double[] target, double[] weights, double[] startPoint)` Optimizes an objective function.
    `void` | `setConvergenceChecker(VectorialConvergenceChecker convergenceChecker)` Set the convergence checker.
    `void` | `setMaxEvaluations(int maxEvaluations)` Set the maximal number of functions evaluations.
    `void` | `setMaxIterations(int maxIterations)` Set the maximal number of iterations of the algorithm.
    `protected void` | `updateJacobian()` Update the jacobian matrix.
    `protected void` | `updateResidualsAndCost()` Update the residuals array and cost function value.

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

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

- - ### Field Detail

    - #### DEFAULT_MAX_ITERATIONS

          public static final int DEFAULT_MAX_ITERATIONS

      Default maximal number of iterations allowed.
      See Also:
        Constant Field Values

    - #### checker

          protected VectorialConvergenceChecker checker

      Convergence checker.

    - #### jacobian

          protected double[][] jacobian

      Jacobian matrix.

      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.

    - #### targetValues

          protected double[] targetValues

      Target value for the objective functions at optimum.
      Since:
        2.1

    - #### residualsWeights

          protected double[] residualsWeights

      Weight for the least squares cost computation.
      Since:
        2.1

    - #### point

          protected double[] point

      Current point.

    - #### objective

          protected double[] objective

      Current objective function value.

    - #### residuals

          protected double[] residuals

      Current residuals.

    - #### wjacobian

          protected double[][] wjacobian

      Weighted Jacobian

    - #### wresiduals

          protected double[] wresiduals

      Weighted residuals

    - #### cost

          protected double cost

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

    - #### maxIterations

          private int maxIterations

      Maximal number of iterations allowed.

    - #### iterations

          private int iterations

      Number of iterations already performed.

    - #### maxEvaluations

          private int maxEvaluations

      Maximal number of evaluations allowed.

    - #### objectiveEvaluations

          private int objectiveEvaluations

      Number of evaluations already performed.

    - #### jacobianEvaluations

          private int jacobianEvaluations

      Number of jacobian evaluations.

    - #### function

          private DifferentiableMultivariateVectorialFunction function

      Objective function.

    - #### jF

          private MultivariateMatrixFunction jF

      Objective function derivatives.

  - ### Constructor Detail

    - #### AbstractLeastSquaresOptimizer

          protected AbstractLeastSquaresOptimizer()

      Simple constructor with default settings.

      The convergence check is set to a `SimpleVectorialValueChecker` and the maximal number of evaluation is set to its default value.

  - ### Method Detail

    - #### setMaxIterations

          public void setMaxIterations(int maxIterations)

      Set the maximal number of iterations of the algorithm.
      Specified by:
        `setMaxIterations` in interface `DifferentiableMultivariateVectorialOptimizer`
      Parameters:
        `maxIterations` - maximal number of function calls .

    - #### getMaxIterations

          public int getMaxIterations()

      Get the maximal number of iterations of the algorithm.
      Specified by:
        `getMaxIterations` in interface `DifferentiableMultivariateVectorialOptimizer`
      Returns:
        maximal number of iterations

    - #### getIterations

          public int getIterations()

      Get the number of iterations realized by the algorithm.
      Specified by:
        `getIterations` in interface `DifferentiableMultivariateVectorialOptimizer`
      Returns:
        number of iterations

    - #### setMaxEvaluations

          public void setMaxEvaluations(int maxEvaluations)

      Set the maximal number of functions evaluations.
      Specified by:
        `setMaxEvaluations` in interface `DifferentiableMultivariateVectorialOptimizer`
      Parameters:
        `maxEvaluations` - maximal number of function evaluations

    - #### getMaxEvaluations

          public int getMaxEvaluations()

      Get the maximal number of functions evaluations.
      Specified by:
        `getMaxEvaluations` in interface `DifferentiableMultivariateVectorialOptimizer`
      Returns:
        maximal number of functions evaluations

    - #### getEvaluations

          public int getEvaluations()

      Get the number of evaluations of the objective function.

      The number of evaluation correspond to the last call to the `optimize` method. It is 0 if the method has not been called yet.

      Specified by:
        `getEvaluations` in interface `DifferentiableMultivariateVectorialOptimizer`
      Returns:
        number of evaluations of the objective function

    - #### getJacobianEvaluations

          public int getJacobianEvaluations()

      Get the number of evaluations of the objective function jacobian .

      The number of evaluation correspond to the last call to the `optimize` method. It is 0 if the method has not been called yet.

      Specified by:
        `getJacobianEvaluations` in interface `DifferentiableMultivariateVectorialOptimizer`
      Returns:
        number of evaluations of the objective function jacobian

    - #### setConvergenceChecker

          public void setConvergenceChecker(VectorialConvergenceChecker convergenceChecker)

      Set the convergence checker.
      Specified by:
        `setConvergenceChecker` in interface `DifferentiableMultivariateVectorialOptimizer`
      Parameters:
        `convergenceChecker` - object to use to check for convergence

    - #### getConvergenceChecker

          public VectorialConvergenceChecker getConvergenceChecker()

      Get the convergence checker.
      Specified by:
        `getConvergenceChecker` in interface `DifferentiableMultivariateVectorialOptimizer`
      Returns:
        object used to check for convergence

    - #### incrementIterationsCounter

          protected void incrementIterationsCounter()
                                             throws OptimizationException

      Increment the iterations counter by 1.
      Throws:
        `OptimizationException` - if the maximal number of iterations is exceeded

    - #### updateJacobian

          protected void updateJacobian()
                                 throws FunctionEvaluationException

      Update the jacobian matrix.
      Throws:
        `FunctionEvaluationException` - if the function jacobian cannot be evaluated or its dimension doesn't match problem dimension

    - #### updateResidualsAndCost

          protected void updateResidualsAndCost()
                                         throws FunctionEvaluationException

      Update the residuals array and cost function value.
      Throws:
        `FunctionEvaluationException` - if the function cannot be evaluated or its dimension doesn't match problem dimension or maximal number of 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()
                                    throws FunctionEvaluationException,
                                           OptimizationException

      Get the covariance matrix of optimized parameters.
      Returns:
        covariance matrix
      Throws:
        `FunctionEvaluationException` - if the function jacobian cannot be evaluated
        `OptimizationException` - if the covariance matrix cannot be computed (singular problem)

    - #### guessParametersErrors

          public double[] guessParametersErrors()
                                         throws FunctionEvaluationException,
                                                OptimizationException

      Guess the errors in optimized parameters.

      Guessing is covariance-based, it only gives rough order of magnitude.

      Returns:
        errors in optimized parameters
      Throws:
        `FunctionEvaluationException` - if the function jacobian cannot b evaluated
        `OptimizationException` - if the covariances matrix cannot be computed or the number of degrees of freedom is not positive (number of measurements lesser or equal to number of parameters)

    - #### optimize

          public VectorialPointValuePair optimize(DifferentiableMultivariateVectorialFunction f,
                                         double[] target,
                                         double[] weights,
                                         double[] startPoint)
                                           throws FunctionEvaluationException,
                                                  OptimizationException,
                                                  java.lang.IllegalArgumentException

      Optimizes 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 `DifferentiableMultivariateVectorialOptimizer`
      Parameters:
        `f` - objective function
        `target` - target value for the objective functions at optimum
        `weights` - weight for the least squares cost computation
        `startPoint` - the start point for optimization
      Returns:
        the point/value pair giving the optimal value for objective function
      Throws:
        `FunctionEvaluationException` - if the objective function throws one during the search
        `OptimizationException` - if the algorithm failed to converge
        `java.lang.IllegalArgumentException` - if the start point dimension is wrong

    - #### doOptimize

          protected abstract VectorialPointValuePair doOptimize()
                                                         throws FunctionEvaluationException,
                                                                OptimizationException,
                                                                java.lang.IllegalArgumentException

      Perform the bulk of optimization algorithm.
      Returns:
        the point/value pair giving the optimal value for objective function
      Throws:
        `FunctionEvaluationException` - if the objective function throws one during the search
        `OptimizationException` - if the algorithm failed to converge
        `java.lang.IllegalArgumentException` - if the start point dimension is wrong

Copyright (c) 2003-2013 Apache Software Foundation