Nonlinear Minimization subject to Box Constraints

DESCRIPTION:

Local minimizer for smooth nonlinear functions subject to bound-constrained parameters.

USAGE:

nlminb(start, objective, gradient=NULL, hessian=NULL,
       scale=1, control=NULL, lower=-Inf, upper=Inf, ...)

REQUIRED ARGUMENTS:

start
p-vector of initial values for the parameters. Missing values ( NAs) are not allowed.
objective
real-valued S-PLUS function that computes the value of the objective function to be minimized. This function must be of the form f(x, <<additional arguments>>), where x is the vector of parameters over which the minimization takes place. Users can accumulate information through attributes of the value of objective. If the attributes include any additional arguments for objective, the next call to objective uses the new values of those arguments.

OPTIONAL ARGUMENTS:

gradient
vector-valued S-PLUS function that computes the gradient of the objective function. This function must be of the form g(x, <<additional arguments>>), where x is the vector of parameters over which the minimization takes place. As for objective, users can accumulate information through attributes of the value of gradient. It cannot be assumed that the value of x on a given call to gradient is the same as the value of x used in the previous call to objective. If gradient is not supplied, the gradient is estimated by finite differences. Entries of the Hessian matrix may also be supplied by gradient. In this case, the value of gradient should be a list with components named gradient and hessian, where the hessian components is a numeric vector representing the lower triangle of the Hessian matrix with entries in the following order: (1,1), (2,1), (2,2), (3,1), (3,2), (3,3), ... That is, the ijth (and jith) entry of the Hessian appears in the (max(i,j)*(max(i,j)-1))/2 + min(i,j) position of the array.
hessian
either a vector-valued S-PLUS function that computes the entries of the Hessian matrix of the objective function, or a logical variable indicating whether or not the Hessian computation takes place within gradient. If hessian is a function, it must be of the form h(x, <<additional arguments>>), where x is the vector of parameters over which the minimization takes place; x should return a numeric vector representing the lower triangle of the Hessian matrix with entries in the order as given above under gradient. As for objective and gradient, users can accumulate information through attributes of the value of hessian. The function hessian is always called immediately after a call to gradient with the same value of x, and will not be used if gradient is not specified. If gradient==NULL, hessian==NULL, or hessian==F, the algorithm uses a quasi-Newton method to approximate curvature.
scale
either a single positive value or a numeric vector with positive components of length equal to the number of parameters to be used to scale the parameter vector. Although scale can have a great effect on the performance of the algorithm, it is not known how to choose it optimally. If hessian is not supplied, scale remains constant throughout the optimization. If hessian is supplied, automatic updating of the scale vector can be selected through control. The default value is unscaled: scale=1.
control
a list of parameters by which the user can control various aspects of the minmization. For details, see the help file for nlminb.control.
lower, upper
either a single numeric value or a vector of length equal to the number of parameters giving lower or upper bounds for the parameter values. The absence of a bound may be indicated by either NA or NULL, or by -Inf and Inf. The default is unconstrained minimization: lower=-Inf and upper=Inf.
...
additional arguments are passed to the objective, gradient and/or hessian functions

VALUE:

a list with the following values:
parameters
the final values of the parameters over which the optimization takes place.
objective
the final value of the objective.
message
a statement of the reason for termination. The possible messages and their meanings are as follows:
X

successive parameter values are within a specified tolerance of each other.

RELATIVE
successive objective values are within a specified tolerance of each other.
BOTH
both of the above.
ABSOLUTE
applies only if the minimum is meant to be zero, as for example solving a system of nonlinear equations using a least-squares objective.
SINGULAR
this happens when the optimization algorithm thinks it can't make any further progress because it has too many degrees of freedom. If you get this message, it usually means that the objective function is either not differentiable, or it may not have an optimum.
FALSE
this is what gets returned when the optimization algorithm can't make further progress. This usual cause of this is that the user has supplied a gradient, but the gradient is computed incorrectly.

The optimization also might stop if it exceeds a prescribed number of function evaluations, or a prescribed iteration limit.
grad.norm
the final norm of the objective gradient. If there are active bounds, then components corresponding to active bounds are excluded from the norm calculation. If the number of active bounds is equal to the number of parameters, NA is returned.
iterations
the total number of iterations before termination.
f.evals
the total number of residual evaluations before termination.
g.evals
the total number of jacobian evaluations before termination.
scale
the final value of the scale vector.
hessian
the final value of the Hessian matrix. This is present only if hessian is supplied initially.
aux
the final value of the function attributes.

DETAILS:

The nlminb command is intended for functions that have at least two continuous derivatives on all of the feasible region, including the boundary. For best results, the gradient of the objective should be supplied whenever possible. Supplying the Hessian matrix as well will sometimes, but not always, lead to a substantial decrease in the number of iterations required to reach a minimum. If the Hessian matrix is supplied, it is recommended that it be computed within gradient for greater efficiency. Function and derivative values should be computed in C or Fortran within the outer S-PLUS function for greater efficiency.

The nlminb function is based on the Fortran functions dmnfb, dmngb, and dmnhb (Gay (1983; 1984), A T & T (1984)) from NETLIB (Dongarra and Grosse (1987)).

REFERENCES:

A.T.&T. Bell Laboratories (1984). PORT Mathematical Subroutine Library Manual.

Dongarra, J.J. and Grosse, E. (1987). Distribution of mathematical software via electronic mail. Communications of the ACM 30: 403-407.

Gay, D.M. (1983). Algorithm 611. Subroutines for Unconstrained Minimization using a Model/Trust-Region Approach. ACM Transactions on Mathematical Software 9: 503-524.

Gay, D.M. (1984). A trust region approach to linearly constrained optimization. Numerical Analysis. Proceedings, Dundee 1983. Springer: Berlin.

SEE ALSO:

, , , , . .

EXAMPLES:

# This example minimizes a sum of squares
# with known solution y.
sumsq <- function(x,y) {sum((x-y)^2)}
y <- rep(1,5)
x0 <- rnorm(length(y))
nlminb(start=x0, obj=sumsq, y=y)

# Now use bounds with a y that has some components
# outside the bounds.
y <- c( 0, 2, 0, -2, 0)
nlminb(start=x0, obj=sumsq, lower=-1, upper=1,
       y=y)

# Try using the gradient.
sumsq.g <- function(x,y) {2*(x-y)}
nlminb(start=x0, obj=sumsq, grad=sumsq.g, lo=-1,
       up=1, y=y)

# Now use the hessian, too.
sumsq.gh <- function(x,y)
   {
        n <- length(y)
        i <- 1:n
        ii <- (i*(i-1))/2 + i
        l <- (n*(n+1))/2
        list(gradient = 2*(x-y),
             hessian = replace( rep(0,l), ii, 2))
    }
nlminb(st=x0, obj=sumsq, grad=sumsq.gh, hes=T,
       lo=-1, up=1, y=y)