Top Description Fields Constructors Methods
org.apache.commons.math3.optimization.general

public abstract Class AbstractLeastSquaresOptimizer

extends BaseAbstractMultivariateVectorOptimizer<DifferentiableMultivariateVectorFunction>
implements DifferentiableMultivariateVectorOptimizer
Class Inheritance
All Implemented Interfaces
org.apache.commons.math3.optimization.DifferentiableMultivariateVectorOptimizer, org.apache.commons.math3.optimization.BaseMultivariateVectorOptimizer, org.apache.commons.math3.optimization.BaseOptimizer
Known Direct Subclasses
org.apache.commons.math3.optimization.general.GaussNewtonOptimizer, org.apache.commons.math3.optimization.general.LevenbergMarquardtOptimizer
Annotations
@Deprecated
Imports
org.apache.commons.math3.analysis.DifferentiableMultivariateVectorFunction, .FunctionUtils, org.apache.commons.math3.analysis.differentiation.DerivativeStructure, .MultivariateDifferentiableVectorFunction, org.apache.commons.math3.exception.DimensionMismatchException, .NumberIsTooSmallException, org.apache.commons.math3.exception.util.LocalizedFormats, org.apache.commons.math3.linear.ArrayRealVector, .RealMatrix, .DiagonalMatrix, .DecompositionSolver, .MatrixUtils, .QRDecomposition, .EigenDecomposition, org.apache.commons.math3.optimization.OptimizationData, .InitialGuess, .Target, .Weight, .ConvergenceChecker, .DifferentiableMultivariateVectorOptimizer, .PointVectorValuePair, org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer, org.apache.commons.math3.util.FastMath

Deprecated

As of 3.1 (to be removed in 4.0).

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

Field Summary

Modifier and TypeField and Description
protected int
cols

Deprecated As of 3.1.
Number of columns of the jacobian matrix.
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).
private static final double
DEFAULT_SINGULARITY_THRESHOLD

Deprecated As of 3.1.
Singularity threshold (cf. getCovariances(double)).
private int
jacobianEvaluations

Number of evaluations of the Jacobian.

private MultivariateDifferentiableVectorFunction
jF

Objective function derivatives.

protected double[]
objective

Deprecated As of 3.1.
Current objective function value.
protected double[]
point

Deprecated As of 3.1.
Current point.
protected int
rows

Deprecated As of 3.1.
Number of rows of the jacobian matrix.
protected double[][]
weightedResidualJacobian

Deprecated As of 3.1.
Jacobian matrix of the weighted residuals.
protected double[]
weightedResiduals

Deprecated As of 3.1.
Weighted residuals
private RealMatrix
weightMatrixSqrt

Square-root of the weight matrix.

Inherited from org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer:
evaluations

Constructor Summary

AccessConstructor and Description
protected
protected
AbstractLeastSquaresOptimizer(ConvergenceChecker<PointVectorValuePair>
Convergence checker.
checker
)
Deprecated as a consequence of ConvergenceChecker being deprecated.

Method Summary

Modifier and TypeMethod and Description
protected double

Returns:

the cost.
computeCost
(double[]
Residuals.
residuals
)

Computes the cost.

public double[][]

Returns:

the covariance matrix.
computeCovariances
(double[]
Model parameters.
params
,
double
Singularity threshold.
threshold
)

Get the covariance matrix of the optimized parameters.

protected double[]

Returns:

the residuals.
computeResiduals
(double[]
Value of the the objective function. This is the value returned from a call to computeObjectiveValue (whose array argument contains the model parameters).
objectiveValue
)

Computes the residuals.

public double[]

Returns:

an estimate of the standard deviation of the optimized parameters
computeSigma
(double[]
Model parameters.
params
,
double
Singularity threshold (see computeCovariances).
covarianceSingularityThreshold
)

Computes an estimate of the standard deviation of the parameters.

protected RealMatrix

Returns:

the weighted Jacobian: W1/2 J.
computeWeightedJacobian
(double[]
Model parameters at which to compute the Jacobian.
params
)

Computes the Jacobian matrix.

public double

Returns:

chi-square value
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.

public double[][]

Returns:

the covariance matrix.
getCovariances
()
Deprecated As of 3.1. Please use computeCovariances(double[], double) instead.

Get the covariance matrix of the optimized parameters.

public double[][]

Returns:

the covariance matrix.
getCovariances
(double
Singularity threshold.
threshold
)
Deprecated As of 3.1. Please use computeCovariances(double[], double) instead.

Get the covariance matrix of the optimized parameters.

public int

Returns:

the number of evaluations of the Jacobian function.
getJacobianEvaluations
()

public double

Returns:

RMS value
getRMS
()

Get the Root Mean Square value.

public RealMatrix

Returns:

the square-root of the weight matrix.
getWeightSquareRoot
()

Gets the square-root of the weight matrix.

public double[]

Returns:

an estimate of the standard deviation of the optimized parameters
guessParametersErrors
()
Deprecated as of version 3.1, computeSigma(double[], double) should be used instead.

Returns an estimate of the standard deviation of each parameter.

public PointVectorValuePair
optimize(int
Maximum number of function evaluations.
maxEval
,
final DifferentiableMultivariateVectorFunction
Objective function.
f
,
final double[]
Target value for the objective functions at optimum.
target
,
final double[]
Weights for the least squares cost computation.
weights
,
final double[]
Start point for optimization.
startPoint
)

Overrides org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer.optimize.

Implements org.apache.commons.math3.optimization.BaseMultivariateVectorOptimizer.optimize.

Deprecated As of 3.1.

Optimize an objective function.

public PointVectorValuePair

Returns:

the point/value pair giving the optimal value for objective function.
optimize
(final int
Maximum number of function evaluations.
maxEval
,
final MultivariateDifferentiableVectorFunction
Objective function.
f
,
final double[]
Target value for the objective functions at optimum.
target
,
final double[]
Weights for the least squares cost computation.
weights
,
final double[]
Start point for optimization.
startPoint
)

Overrides org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer.optimize.

Implements org.apache.commons.math3.optimization.BaseMultivariateVectorOptimizer.optimize.

Deprecated As of 3.1.

Optimize an objective function.

protected PointVectorValuePair

Returns:

the point/value pair giving the optimal value of the objective function.
optimizeInternal
(final int
Allowed number of evaluations of the objective function.
maxEval
,
final MultivariateDifferentiableVectorFunction
Objective function.
f
,
OptimizationData...
Optimization data. The following data will be looked for:
optData
)

Overrides org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer.optimizeInternal.

Deprecated As of 3.1. Override is necessary only until this class's generic argument is changed to MultivariateDifferentiableVectorFunction.

Optimize an objective function.

protected void
setCost(double
Cost value.
cost
)

Sets the cost.

protected void
setUp()

Overrides org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer.setUp.

Method which a subclass must override whenever its internal state depend on the input parsed by this base class.

private RealMatrix

Returns:

the square-root of the weight matrix.
squareRoot
(RealMatrix
Symmetric, positive-definite (weight) matrix.
m
)

Computes the square-root of the weight matrix.

protected void
updateJacobian()
Deprecated As of 3.1. Please use computeWeightedJacobian(double[]) instead.

Update the jacobian matrix.

protected void
updateResidualsAndCost()
Deprecated As of 3.1.

Update the residuals array and cost function value.

Inherited from org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer:
computeObjectiveValuedoOptimizegetConvergenceCheckergetEvaluationsgetMaxEvaluationsgetObjectiveFunctiongetStartPointgetTargetgetTargetRefgetWeightgetWeightRefoptimizeoptimizeInternal

Field Detail

colsback to summary
protected int cols

Deprecated

As of 3.1.

Number of columns of the jacobian matrix.

Annotations
@Deprecated
costback to summary
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).

Annotations
@Deprecated
DEFAULT_SINGULARITY_THRESHOLDback to summary
private static final double DEFAULT_SINGULARITY_THRESHOLD

Deprecated

As of 3.1.

Singularity threshold (cf. getCovariances(double)).

Annotations
@Deprecated
jacobianEvaluationsback to summary
private int jacobianEvaluations

Number of evaluations of the Jacobian.

jFback to summary
private MultivariateDifferentiableVectorFunction jF

Objective function derivatives.

objectiveback to summary
protected double[] objective

Deprecated

As of 3.1.

Current objective function value.

Annotations
@Deprecated
pointback to summary
protected double[] point

Deprecated

As of 3.1.

Current point.

Annotations
@Deprecated
rowsback to summary
protected int rows

Deprecated

As of 3.1.

Number of rows of the jacobian matrix.

Annotations
@Deprecated
weightedResidualJacobianback to summary
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).

Annotations
@Deprecated
weightedResidualsback to summary
protected double[] weightedResiduals

Deprecated

As of 3.1.

Weighted residuals

Annotations
@Deprecated
weightMatrixSqrtback to summary
private RealMatrix weightMatrixSqrt

Square-root of the weight matrix.

Constructor Detail

AbstractLeastSquaresOptimizerback to summary
protected AbstractLeastSquaresOptimizer()

Simple constructor with default settings. The convergence check is set to a org.apache.commons.math3.optimization.SimpleVectorValueChecker.

Annotations
@Deprecated
AbstractLeastSquaresOptimizerback to summary
protected AbstractLeastSquaresOptimizer(ConvergenceChecker<PointVectorValuePair> checker)

Deprecated

as a consequence of ConvergenceChecker being deprecated. See corresponding docs for further information.

Parameters
checker:ConvergenceChecker<PointVectorValuePair>

Convergence checker.

Method Detail

computeCostback to summary
protected double computeCost(double[] residuals)

Computes the cost.

Parameters
residuals:double[]

Residuals.

Returns:double

the cost.

Since
3.1
See Also
computeResiduals(double[])
computeCovariancesback to summary
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:double[]

Model parameters.

threshold:double

Singularity threshold.

Returns:double[][]

the covariance matrix.

Exceptions
SingularMatrixException:
if the covariance matrix cannot be computed (singular problem).
Since
3.1
computeResidualsback to summary
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:double[]

Value of the the objective function. This is the value returned from a call to computeObjectiveValue (whose array argument contains the model parameters).

Returns:double[]

the residuals.

Exceptions
DimensionMismatchException:
if params has a wrong length.
Since
3.1
computeSigmaback to summary
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:double[]

Model parameters.

covarianceSingularityThreshold:double

Singularity threshold (see computeCovariances).

Returns:double[]

an estimate of the standard deviation of the optimized parameters

Exceptions
SingularMatrixException:
if the covariance matrix cannot be computed.
Since
3.1
computeWeightedJacobianback to summary
protected RealMatrix computeWeightedJacobian(double[] params)

Computes the Jacobian matrix.

Parameters
params:double[]

Model parameters at which to compute the Jacobian.

Returns:RealMatrix

the weighted Jacobian: W1/2 J.

Exceptions
DimensionMismatchException:
if the Jacobian dimension does not match problem dimension.
Since
3.1
getChiSquareback to summary
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:double

chi-square value

getCovariancesback to summary
public double[][] getCovariances()

Deprecated

As of 3.1. Please use computeCovariances(double[], double) instead.

Get the covariance matrix of the optimized parameters.

Returns:double[][]

the covariance matrix.

Annotations
@Deprecated
Exceptions
SingularMatrixException:
if the covariance matrix cannot be computed (singular problem).
See Also
getCovariances(double)
getCovariancesback to summary
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:double

Singularity threshold.

Returns:double[][]

the covariance matrix.

Annotations
@Deprecated
Exceptions
SingularMatrixException:
if the covariance matrix cannot be computed (singular problem).
getJacobianEvaluationsback to summary
public int getJacobianEvaluations()
Returns:int

the number of evaluations of the Jacobian function.

getRMSback to summary
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:double

RMS value

getWeightSquareRootback to summary
public RealMatrix getWeightSquareRoot()

Gets the square-root of the weight matrix.

Returns:RealMatrix

the square-root of the weight matrix.

Since
3.1
guessParametersErrorsback to summary
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:double[]

an estimate of the standard deviation of the optimized parameters

Annotations
@Deprecated
Exceptions
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.
optimizeback to summary
public PointVectorValuePair optimize(int maxEval, final DifferentiableMultivariateVectorFunction f, final double[] target, final double[] weights, final double[] startPoint)

Overrides org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer.optimize.

Implements org.apache.commons.math3.optimization.BaseMultivariateVectorOptimizer.optimize.

Doc from org.apache.commons.math3.optimization.BaseMultivariateVectorOptimizer.optimize.

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:int

Maximum number of function evaluations.

f:DifferentiableMultivariateVectorFunction

Objective function.

target:double[]

Target value for the objective functions at optimum.

weights:double[]

Weights for the least squares cost computation.

startPoint:double[]

Start point for optimization.

Returns:PointVectorValuePair

the point/value pair giving the optimal value for objective function.

Annotations
@Override
@Deprecated
optimizeback to summary
public PointVectorValuePair optimize(final int maxEval, final MultivariateDifferentiableVectorFunction f, final double[] target, final double[] weights, final double[] startPoint)

Overrides org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer.optimize.

Implements org.apache.commons.math3.optimization.BaseMultivariateVectorOptimizer.optimize.

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:int

Maximum number of function evaluations.

f:MultivariateDifferentiableVectorFunction

Objective function.

target:double[]

Target value for the objective functions at optimum.

weights:double[]

Weights for the least squares cost computation.

startPoint:double[]

Start point for optimization.

Returns:PointVectorValuePair

the point/value pair giving the optimal value for objective function.

Annotations
@Deprecated
Exceptions
DimensionMismatchException:
if the start point dimension is wrong.
TooManyEvaluationsException:
if the maximal number of evaluations is exceeded.
NullArgumentException:
if any argument is null.
optimizeInternalback to summary
protected PointVectorValuePair optimizeInternal(final int maxEval, final MultivariateDifferentiableVectorFunction f, OptimizationData... optData)

Overrides org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer.optimizeInternal.

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:int

Allowed number of evaluations of the objective function.

f:MultivariateDifferentiableVectorFunction

Objective function.

optData:OptimizationData[]

Optimization data. The following data will be looked for:

Returns:PointVectorValuePair

the point/value pair giving the optimal value of the objective function.

Annotations
@Deprecated
Exceptions
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, org.apache.commons.math3.analysis.MultivariateVectorFunction, OptimizationData[])
setCostback to summary
protected void setCost(double cost)

Sets the cost.

Parameters
cost:double

Cost value.

Since
3.1
setUpback to summary
protected void setUp()

Overrides org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer.setUp.

Doc from org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer.setUp.

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

Annotations
@Override
squareRootback to summary
private RealMatrix squareRoot(RealMatrix m)

Computes the square-root of the weight matrix.

Parameters
m:RealMatrix

Symmetric, positive-definite (weight) matrix.

Returns:RealMatrix

the square-root of the weight matrix.

updateJacobianback to summary
protected void updateJacobian()

Deprecated

As of 3.1. Please use computeWeightedJacobian(double[]) instead.

Update the jacobian matrix.

Annotations
@Deprecated
Exceptions
DimensionMismatchException:
if the Jacobian dimension does not match problem dimension.
updateResidualsAndCostback to summary
protected void updateResidualsAndCost()

Update the residuals array and cost function value.

Annotations
@Deprecated
Exceptions
DimensionMismatchException:
if the dimension does not match the problem dimension.
TooManyEvaluationsException:
if the maximal number of evaluations is exceeded.