org.apache.commons.math3.optimization.general
Class AbstractLeastSquaresOptimizer

java.lang.Object
  extended by org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer<DifferentiableMultivariateVectorFunction>
      extended by 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
protected  int cols
          Number of columns of the jacobian matrix.
protected  double cost
          Cost value (square root of the sum of the residuals).
private static double DEFAULT_SINGULARITY_THRESHOLD
          Singularity threshold (cf.
private  int jacobianEvaluations
          Number of evaluations of the Jacobian.
private  MultivariateMatrixFunction jF
          Objective function derivatives.
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
protected AbstractLeastSquaresOptimizer()
          Simple constructor with default settings.
protected AbstractLeastSquaresOptimizer(ConvergenceChecker<PointVectorValuePair> checker)
           
 
Method Summary
 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

DEFAULT_SINGULARITY_THRESHOLD

private static final double DEFAULT_SINGULARITY_THRESHOLD
Singularity threshold (cf. getCovariances(double)).

See Also:
Constant Field Values

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


jF

private MultivariateMatrixFunction jF
Objective function derivatives.


jacobianEvaluations

private int jacobianEvaluations
Number of evaluations of the Jacobian.

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 (c) 2003-2013 Apache Software Foundation