## 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: 925812 $ $Date: 2010-03-21 11:49:31 -0400 (Sun, 21 Mar 2010) $

Field Summary
`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.

Constructor Summary
`protected` `AbstractLeastSquaresOptimizer()` Simple constructor with default settings.

Method Summary
`protected abstract VectorialPointValuePair` `doOptimize()` Perform the bulk of optimization algorithm.
`double` `getChiSquare()` Get the Chi-Square value.
`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.

### 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 the Chi-Square value.

  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-2011 Apache Software Foundation