org.apache.commons.math3.optimization.general

Class AbstractLeastSquaresOptimizer

java.lang.Object

org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer<DifferentiableMultivariateVectorFunction>

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

All Implemented Interfaces:

BaseMultivariateVectorOptimizer<DifferentiableMultivariateVectorFunction>, BaseOptimizer<PointVectorValuePair>, DifferentiableMultivariateVectorOptimizer

Direct Known Subclasses:

GaussNewtonOptimizer, LevenbergMarquardtOptimizer

Deprecated.

As of 3.1 (to be removed in 4.0).

@Deprecated
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 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

Fields

Modifier and Type	Field and Description
protected int	cols Deprecated. As of 3.1.
protected double	cost Deprecated. As of 3.1. Field to become "private" in 4.0. Please use setCost(double).
private static double	DEFAULT_SINGULARITY_THRESHOLD Deprecated. As of 3.1.
private int	jacobianEvaluations Deprecated. Number of evaluations of the Jacobian.
private MultivariateDifferentiableVectorFunction	jF Deprecated. Objective function derivatives.
protected double[]	objective Deprecated. As of 3.1.
protected double[]	point Deprecated. As of 3.1.
protected int	rows Deprecated. As of 3.1.
protected double[][]	weightedResidualJacobian Deprecated. As of 3.1. To be removed in 4.0. Please use computeWeightedJacobian(double[]) instead.
protected double[]	weightedResiduals Deprecated. As of 3.1.
private RealMatrix	weightMatrixSqrt Deprecated. Square-root of the weight matrix.

Fields inherited from class org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer

evaluations

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractLeastSquaresOptimizer() Deprecated. See SimpleValueChecker.SimpleValueChecker()
protected	AbstractLeastSquaresOptimizer(ConvergenceChecker<PointVectorValuePair> checker) Deprecated.

Method Summary

Methods

Modifier and Type	Method and Description
protected double	computeCost(double[] residuals) Deprecated. Computes the cost.
double[][]	computeCovariances(double[] params, double threshold) Deprecated. Get the covariance matrix of the optimized parameters.
protected double[]	computeResiduals(double[] objectiveValue) Deprecated. Computes the residuals.
double[]	computeSigma(double[] params, double covarianceSingularityThreshold) Deprecated. Computes an estimate of the standard deviation of the parameters.
protected RealMatrix	computeWeightedJacobian(double[] params) Deprecated. Computes the Jacobian matrix.
double	getChiSquare() Deprecated. 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() Deprecated. As of 3.1. Please use computeCovariances(double[],double) instead.
double[][]	getCovariances(double threshold) Deprecated. As of 3.1. Please use computeCovariances(double[],double) instead.
int	getJacobianEvaluations() Deprecated.
double	getRMS() Deprecated. Get the Root Mean Square value.
RealMatrix	getWeightSquareRoot() Deprecated. Gets the square-root of the weight matrix.
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.
PointVectorValuePair	optimize(int maxEval, DifferentiableMultivariateVectorFunction f, double[] target, double[] weights, double[] startPoint) Deprecated. As of 3.1. Please use optimize(int,MultivariateDifferentiableVectorFunction,OptimizationData...) instead.
PointVectorValuePair	optimize(int maxEval, MultivariateDifferentiableVectorFunction f, double[] target, double[] weights, double[] startPoint) Deprecated. As of 3.1. Please use optimize(int,MultivariateDifferentiableVectorFunction,OptimizationData...) instead.
protected PointVectorValuePair	optimizeInternal(int maxEval, MultivariateDifferentiableVectorFunction f, OptimizationData... optData) Deprecated. As of 3.1. Override is necessary only until this class's generic argument is changed to MultivariateDifferentiableVectorFunction.
protected void	setCost(double cost) Deprecated. Sets the cost.
protected void	setUp() Deprecated. Method which a subclass must override whenever its internal state depend on the input parsed by this base class.
private RealMatrix	squareRoot(RealMatrix m) Deprecated. Computes the square-root of the weight matrix.
protected void	updateJacobian() Deprecated. As of 3.1. Please use computeWeightedJacobian(double[]) instead.
protected void	updateResidualsAndCost() Deprecated. As of 3.1. Please use computeResiduals(double[]), BaseAbstractMultivariateVectorOptimizer.computeObjectiveValue(double[]), computeCost(double[]) and setCost(double) instead.

Methods inherited from class org.apache.commons.math3.optimization.direct.BaseAbstractMultivariateVectorOptimizer

computeObjectiveValue, doOptimize, getConvergenceChecker, getEvaluations, getMaxEvaluations, getObjectiveFunction, getStartPoint, getTarget, getTargetRef, getWeight, getWeightRef, optimize, optimizeInternal, optimizeInternal

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

@Deprecated
private static final double DEFAULT_SINGULARITY_THRESHOLD

Deprecated. As of 3.1.

Singularity threshold (cf. getCovariances(double)).

See Also:

Constant Field Values

weightedResidualJacobian

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

cols

@Deprecated
protected int cols

Deprecated. As of 3.1.

Number of columns of the jacobian matrix.

rows

@Deprecated
protected int rows

Deprecated. As of 3.1.

Number of rows of the jacobian matrix.

point

@Deprecated
protected double[] point

Deprecated. As of 3.1.

Current point.

objective

@Deprecated
protected double[] objective

Deprecated. As of 3.1.

Current objective function value.

weightedResiduals

@Deprecated
protected double[] weightedResiduals

Deprecated. As of 3.1.

Weighted residuals

cost

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

jF

private MultivariateDifferentiableVectorFunction jF

Deprecated.

Objective function derivatives.

jacobianEvaluations

private int jacobianEvaluations

Deprecated.

Number of evaluations of the Jacobian.

weightMatrixSqrt

private RealMatrix weightMatrixSqrt

Deprecated.

Square-root of the weight matrix.

Constructor Detail

AbstractLeastSquaresOptimizer

@Deprecated
protected AbstractLeastSquaresOptimizer()

Deprecated. See SimpleValueChecker.SimpleValueChecker()

Simple constructor with default settings. The convergence check is set to a SimpleVectorValueChecker.

AbstractLeastSquaresOptimizer

protected AbstractLeastSquaresOptimizer(ConvergenceChecker<PointVectorValuePair> checker)

Deprecated.

Parameters:

checker - Convergence checker.

Method Detail

getJacobianEvaluations

public int getJacobianEvaluations()

Deprecated.

Returns:

the number of evaluations of the Jacobian function.

updateJacobian

@Deprecated
protected void updateJacobian()

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

Update the jacobian matrix.

Throws:

DimensionMismatchException - if the Jacobian dimension does not match problem dimension.

computeWeightedJacobian

protected RealMatrix computeWeightedJacobian(double[] params)

Deprecated.

Computes the Jacobian matrix.

Parameters:

params - Model parameters at which to compute the Jacobian.

Returns:

the weighted Jacobian: W^1/2 J.

Throws:

DimensionMismatchException - if the Jacobian dimension does not match problem dimension.

Since:

3.1

updateResidualsAndCost

@Deprecated
protected void updateResidualsAndCost()

Deprecated. As of 3.1. Please use computeResiduals(double[]), BaseAbstractMultivariateVectorOptimizer.computeObjectiveValue(double[]), computeCost(double[]) and setCost(double) instead.

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.

computeCost

protected double computeCost(double[] residuals)

Deprecated.

Computes the cost.

Parameters:

residuals - Residuals.

Returns:

the cost.

Since:

3.1

See Also:

computeResiduals(double[])

getRMS

public double getRMS()

Deprecated.

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

Deprecated.

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

Deprecated.

Gets the square-root of the weight matrix.

Returns:

the square-root of the weight matrix.

Since:

3.1

setCost

protected void setCost(double cost)

Deprecated.

Sets the cost.

Parameters:

cost - Cost value.

Since:

3.1

getCovariances

@Deprecated
public double[][] getCovariances()

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

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

@Deprecated
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 - Singularity threshold.

Returns:

the covariance matrix.

Throws:

SingularMatrixException - if the covariance matrix cannot be computed (singular problem).

computeCovariances

public double[][] computeCovariances(double[] params,
                            double threshold)

Deprecated.

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

Since:

3.1

guessParametersErrors

@Deprecated
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:

an estimate of the standard deviation of the optimized parameters

Throws:

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.

computeSigma

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

Deprecated.

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.

Since:

3.1

optimize

@Deprecated
public PointVectorValuePair optimize(int maxEval,
                                       DifferentiableMultivariateVectorFunction f,
                                       double[] target,
                                       double[] weights,
                                       double[] startPoint)

Deprecated. As of 3.1. Please use optimize(int,MultivariateDifferentiableVectorFunction,OptimizationData...) instead.

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.

optimize

@Deprecated
public PointVectorValuePair optimize(int maxEval,
                                       MultivariateDifferentiableVectorFunction f,
                                       double[] target,
                                       double[] weights,
                                       double[] startPoint)

Deprecated. As of 3.1. Please use optimize(int,MultivariateDifferentiableVectorFunction,OptimizationData...) instead.

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:

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.

maxEval - Maximum number of function evaluations.

Returns:

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

Throws:

DimensionMismatchException - if the start point dimension is wrong.

TooManyEvaluationsException - if the maximal number of evaluations is exceeded.

NullArgumentException - if any argument is null.

optimizeInternal

@Deprecated
protected PointVectorValuePair optimizeInternal(int maxEval,
                                               MultivariateDifferentiableVectorFunction f,
                                               OptimizationData... optData)

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 - Allowed number of evaluations of the objective function.

f - Objective function.

optData - Optimization data. The following data will be looked for:

• Target
• Weight
• InitialGuess

Returns:

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

Throws:

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[])

setUp

protected void setUp()

Deprecated.

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

Overrides:

setUp in class BaseAbstractMultivariateVectorOptimizer<DifferentiableMultivariateVectorFunction>

computeResiduals

protected double[] computeResiduals(double[] objectiveValue)

Deprecated.

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.

Since:

3.1

squareRoot

private RealMatrix squareRoot(RealMatrix m)

Deprecated.

Computes the square-root of the weight matrix.

Parameters:

m - Symmetric, positive-definite (weight) matrix.

Returns:

the square-root of the weight matrix.