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

start:

p-vector of initial values for the parameters (NAs not allowed).

objective:

a 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 of objective, the next call to objective will use the new values of those arguments.

gradient:

a 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.t 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 else 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, and must 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 or hessian == NULL or hessian == F, the algorithm uses a quasi-Newton method to approximate curvature.

scale:

either a single positive value or else 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, then automatic updating of the scale vector can be selected through control. The default 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 else 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, upper = Inf.

...:

additional arguments for objective, gradient and/or hessian.

parameters:

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.

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 will be 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 (present only if hessian is supplied initially).

aux:

the final value of the function attributes.

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.

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

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

Gay, D. M. (1984). A trust region approach to linearly constrained optimization. in Numerical Analysis. Proceedings, Dundee 1983, F. A Lootsma (ed.), Springer, Berlin, pp. 171-189.

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