JMSLTM Numerical Library 5.0.1

com.imsl.math
Class NonlinLeastSquares

java.lang.Object
  extended by com.imsl.math.NonlinLeastSquares
All Implemented Interfaces:
Serializable, Cloneable

public class NonlinLeastSquares
extends Object
implements Serializable, Cloneable

Nonlinear least squares.

NonlinLeastSquares is based on the MINPACK routine LMDIF by Moré et al. (1980). It uses a modified Levenberg-Marquardt method to solve nonlinear least squares problems. The problem is stated as follows:

mathop {min }limits_{x in R^n } 
  frac{1}{2}Fleft( x right)^T Fleft( x right) = frac{1}{2}sumlimits_{i = 1}^m 
  {f_i } left( x right)^2

where m ge n, F:,,R^n to R^m, and f_i(x) is the i-th component function of F(x). From a current point, the algorithm uses the trust region approach:

mathop {min }limits_{x_n  in R^n } left| 
  {Fleft( {x_c } right) + Jleft( {x_c } right)left( {x_n  - x_c } right)} 
  right|_2

subject to

left| {x_n  - x_c } right|_2 le 
  delta _c

to get a new point x_n, which is computed as

x_n  = x_c  - left( {Jleft( {x_c } 
  right)^T Jleft( {x_c } right) + mu _c I} right)^{ - 1} Jleft( {x_c } 
  right)^T Fleft( {x_c } right)

where mu _c = 0 if  delta _c ge left| 
  {left( {Jleft( {x_c } right)^T Jleft( {x_c } right)} right)^{-1} ,,Jleft( 
  {x_c } right)^T Fleft( {x_c } right)} right|_2 and mu _c > 0 otherwise. F(x_c) and J(x_c) are the function values and the Jacobian evaluated at the current point x_c. This procedure is repeated until the stopping criteria are satisfied. For more details, see Levenberg (1944), Marquardt (1963), or Dennis and Schnabel (1983, Chapter 10).

A finite-difference method is used to estimate the Jacobian when the user supplied function, f, defines the least-squares problem. Whenever the exact Jacobian can be easily provided, f should implement NonlinLeastSquares.Jacobian.

See Also:
Finite Differences Example, Jacobian Example, Serialized Form

Nested Class Summary
static class NonlinLeastSquares.FalseConvergenceException
          The iterates appear to be converging to a non-critical point.
static interface NonlinLeastSquares.Function
          Public interface for the user supplied function to the NonlinLeastSquares object.
static interface NonlinLeastSquares.Jacobian
          Public interface for the user supplied function to the NonlinLeastSquares object.
static class NonlinLeastSquares.RelativeFunctionConvergenceException
          The scaled and predicted reductions in the function are less than or equal to the relative function convergence tolerance.
static class NonlinLeastSquares.StepMaxException
          Either the function is unbounded below, has a finite asymptote in some direction, or the maximum stepsize is too small.
static class NonlinLeastSquares.StepToleranceException
          Various possible errors involving the step tolerance.
static class NonlinLeastSquares.TooManyIterationsException
          Too many iterations.
 
Constructor Summary
NonlinLeastSquares(int m, int n)
          Creates an object to solve a nonlinear least squares problem.
 
Method Summary
 int getErrorStatus()
          Get information about the performance of NonlinLeastSquares.
 void setAbsoluteTolerance(double absoluteTolerance)
          Set the absolute function tolerance.
 void setDigits(int ngood)
          Set the number of good digits in the function.
 void setFalseConvergenceTolerance(double falseConvergenceTolerance)
          Set the false convergence tolerance.
 void setFscale(double[] fscale)
          Set the diagonal scaling matrix for the functions.
 void setGradientTolerance(double gradientTolerance)
          Set the gradient tolerance used to compute the gradient.
 void setGuess(double[] xguess)
          Set the initial guess of the minimum point of the input function.
 void setInitialTrustRegion(double initialTrustRegion)
          Set the initial trust region radius.
 void setMaximumStepsize(double maximumStepsize)
          Set the maximum allowable stepsize to use.
 void setMaxIterations(int maxIterations)
          Set the maximum number of iterations allowed.
 void setRelativeTolerance(double relativeTolerance)
          Set the relative function tolerance.
 void setStepTolerance(double stepTolerance)
          Set the step tolerance used to step between two points.
 void setXscale(double[] xscale)
          Set the diagonal scaling matrix for the variables.
 double[] solve(NonlinLeastSquares.Function F)
          Solve a nonlinear least-squares problem using a modified Levenberg-Marquardt algorithm and a Jacobian.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

NonlinLeastSquares

public NonlinLeastSquares(int m,
                          int n)
Creates an object to solve a nonlinear least squares problem.

Parameters:
m - is the number of functions
n - is the number of variables. n must be less than or equal to m.
Method Detail

getErrorStatus

public int getErrorStatus()
Get information about the performance of NonlinLeastSquares.

Returns:
an int specifying information about convergence.
valuemeaning
0All convergence tests were met.
1Scaled step tolerance was satisfied. The current point may be an approximate local solution, or the algorithm is making very slow progress and is not near a solution, or StepTolerance is too big.
2Scaled actual and predicted reductions in the function are less than or equal to the relative function convergence tolerance RelativeTolerance.
3Iterates appear to be converging to a noncritical point. Incorrect gradient information, a discontinuous function, or stopping tolerances being too tight may be the cause.
4Five consecutive steps with the maximum stepsize have been taken. Either the function is unbounded below, or has a finite asymptote in some direction, or the maximum stepsize is too small.

See Also:
setRelativeTolerance(double), setStepTolerance(double)

setAbsoluteTolerance

public void setAbsoluteTolerance(double absoluteTolerance)
Set the absolute function tolerance. If this member function is not called, 1.0e-32 is used as the absolute function tolerance.

Parameters:
absoluteTolerance - a double scalar value specifying the absolute function tolerance
Throws:
IllegalArgumentException - is thrown if absoluteTolerance is less than or equal to 0

setDigits

public void setDigits(int ngood)
Set the number of good digits in the function. If this member function is not called, the number of good digits is set to 7.

Parameters:
ngood - an int specifying the number of good digits in the user supplied function which defines the least-squares problem
Throws:
IllegalArgumentException - is thrown if ngood is less than or equal to 0

setFalseConvergenceTolerance

public void setFalseConvergenceTolerance(double falseConvergenceTolerance)
Set the false convergence tolerance. If this member function is not called, 100.0e-16 is used as the false convergence tolerance.

Parameters:
falseConvergenceTolerance - a double scalar value specifying the false convergence tolerance
Throws:
IllegalArgumentException - is thrown if falseConvergenceTolerance is less than or equal to 0

setFscale

public void setFscale(double[] fscale)
Set the diagonal scaling matrix for the functions. If this member function is not called, the identity is used.

Parameters:
fscale - a double array specifying the diagonal scaling matrix for the functions
Throws:
IllegalArgumentException - is thrown if any of the elements of fscale is less than or equal to 0

setGradientTolerance

public void setGradientTolerance(double gradientTolerance)
Set the gradient tolerance used to compute the gradient. If this member function is not called, the cube root of machine precision squared is used to compute the gradient.

Parameters:
gradientTolerance - a double specifying the gradient tolerance used to compute the gradient
Throws:
IllegalArgumentException - is thrown if gradientTolerance is less than or equal to 0

setGuess

public void setGuess(double[] xguess)
Set the initial guess of the minimum point of the input function. If this member function is not called, an initial guess of 0.0 is used.

Parameters:
xguess - a double array specifying the initial guess of the minimum point of the input function

setInitialTrustRegion

public void setInitialTrustRegion(double initialTrustRegion)
Set the initial trust region radius. If this member function is not called, a default is set based on the initial scaled Cauchy step.

Parameters:
initialTrustRegion - a double scalar value specifying the initial trust region radius
Throws:
IllegalArgumentException - is thrown if initialTrustRegion is less than or equal to 0

setMaximumStepsize

public void setMaximumStepsize(double maximumStepsize)
Set the maximum allowable stepsize to use. If this member function is not called, maximum stepsize is set to a default value based on a scaled xguess.

Parameters:
maximumStepsize - a nonnegative double value specifying the maximum allowable stepsize
Throws:
IllegalArgumentException - is thrown if maximumStepsize is less than or equal to 0

setMaxIterations

public void setMaxIterations(int maxIterations)
Set the maximum number of iterations allowed. If this member function is not called, the maximum number of iterations is set to 100.

Parameters:
maxIterations - an int specifying the maximum number of iterations allowed
Throws:
IllegalArgumentException - is thrown if maxIterations is less than or equal to 0

setRelativeTolerance

public void setRelativeTolerance(double relativeTolerance)
Set the relative function tolerance. If this member function is not called, 1.0e-20 is used as the relative function tolerance.

Parameters:
relativeTolerance - a double scalar value specifying the relative function tolerance
Throws:
IllegalArgumentException - is thrown if relativeTolerance is less than or equal to 0

setStepTolerance

public void setStepTolerance(double stepTolerance)
Set the step tolerance used to step between two points. If this member function is not called, the cube root of machine precision is used as the step tolerance.

Parameters:
stepTolerance - a double scalar value specifying the step tolerance used to step between two points
Throws:
IllegalArgumentException - is thrown if stepTolerance is less than or equal to 0

setXscale

public void setXscale(double[] xscale)
Set the diagonal scaling matrix for the variables. If this member function is not called, the identity is used.

Parameters:
xscale - a double array specifying the diagonal scaling matrix for the variables
Throws:
IllegalArgumentException - is thrown if any of the elements of xscale is less than or equal to 0

solve

public double[] solve(NonlinLeastSquares.Function F)
               throws NonlinLeastSquares.TooManyIterationsException
Solve a nonlinear least-squares problem using a modified Levenberg-Marquardt algorithm and a Jacobian.

Parameters:
F - User supplied function that defines the least-squares problem. If F implements Jacobian then its Jacobian is used. Otherwise, a finite difference Jacobian is used.
Returns:
a double array of length n containing the approximate solution
Throws:
NonlinLeastSquares.TooManyIterationsException - is thrown if the number of iterations exceeds MaxIterations. MaxIterations is set to 100 by default.

JMSLTM Numerical Library 5.0.1

Copyright © 1970-2008 Visual Numerics, Inc.
Built July 8 2008.