\HeaderA{nlminb}{Optimization using PORT routines}{nlminb}
\keyword{optimize}{nlminb}
\begin{Description}\relax
Unconstrained and constrained optimization using PORT routines.
\end{Description}
\begin{Usage}
\begin{verbatim}
nlminb(start, objective, gradient = NULL, hessian = NULL, ...,
       scale = 1, control = list(), lower = -Inf, upper = Inf)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{start}] numeric vector, initial values for the parameters to be optimized.

\item[\code{objective}] Function to be minimized.  Must return a scalar value (possibly
NA/Inf).  The first argument to \code{objective} is the vector of
parameters to be optimized, whose initial values are supplied
through \code{start}.  Further arguments (fixed during the course of
the optimization) to \code{objective} may be specified as well (see
\code{...}).

\item[\code{gradient}] Optional function that takes the same arguments as \code{objective} and
evaluates the gradient of \code{objective} at its first argument.  Must
return a vector as long as \code{start}.

\item[\code{hessian}] Optional function that takes the same arguments as \code{objective} and
evaluates the hessian of \code{objective} at its first argument.  Must
return a square matrix of order \code{length(start)}.  Only the
lower triangle is used.

\item[\code{...}] Further arguments to be supplied to \code{objective}.
\item[\code{scale}] See PORT documentation (or leave alone).
\item[\code{control}] A list of control parameters. See below for details.
\item[\code{lower, upper}] vectors of lower and upper bounds, replicated to be as long as
\code{start}.  If unspecified, all parameters are assumed to be
unconstrained.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Any names of \code{start} are (as from \R{} 2.8.1) passed
on to \code{objective} and where applicable, \code{gradient} and
\code{hessian}.  The parameter vector will be coerced to double.

The PORT documentation is at
\url{http://netlib.bell-labs.com/cm/cs/cstr/153.pdf}.
\end{Details}
\begin{Value}
A list with components:
\begin{ldescription}
\item[\code{par}] The best set of parameters found.
\item[\code{objective}] The value of \code{objective} corresponding to \code{par}.
\item[\code{convergence}] An integer code. \code{0} indicates successful
convergence.

\item[\code{message}] A character string giving any additional information returned by the
optimizer, or \code{NULL}. For details, see PORT documentation.

\item[\code{iterations}] Number of iterations performed.
\item[\code{evaluations}] Number of objective function and gradient function evaluations
\end{ldescription}
\end{Value}
\begin{Section}{Control parameters}
Possible names in the \code{control} list and their default values
are:
\describe{
\item[\code{eval.max}] Maximum number of evaluations of the objective
function allowed.  Defaults to 200.
\item[\code{iter.max}] Maximum number of iterations allowed.
Defaults to 150.
\item[\code{trace}] The value of the objective function and the parameters
is printed every trace'th iteration.  Defaults to 0 which
indicates no trace information is to be printed.
\item[\code{abs.tol}] Absolute tolerance.  Defaults to \code{1e-20}.
\item[\code{rel.tol}] Relative tolerance.  Defaults to \code{1e-10}.
\item[\code{x.tol}] X tolerance.  Defaults to \code{1.5e-8}.
\item[\code{step.min}] Minimum step size.  Defaults to \code{2.2e-14}.
}
\end{Section}
\begin{Author}\relax
(of \R{} port) Douglas Bates and Deepayan Sarkar.
\end{Author}
\begin{References}\relax
\url{http://netlib.bell-labs.com/netlib/port/}
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{optim}{optim}} and \code{\LinkA{nlm}{nlm}}.

\code{\LinkA{optimize}{optimize}} for one-dimensional minimization and
\code{\LinkA{constrOptim}{constrOptim}} for constrained optimization.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
x <- rnbinom(100, mu = 10, size = 10)
hdev <- function(par) {
    -sum(dnbinom(x, mu = par[1], size = par[2], log = TRUE))
}
nlminb(c(9, 12), hdev)
nlminb(c(20, 20), hdev, lower = 0, upper = Inf)
nlminb(c(20, 20), hdev, lower = 0.001, upper = Inf)

## slightly modified from the S-PLUS help page for nlminb
# 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, 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, sumsq, lower = -1, upper = 1, y = y)
# try using the gradient
sumsq.g <- function(x,y) 2*(x-y)
nlminb(start = x0, sumsq, sumsq.g,
       lower = -1, upper = 1, y = y)
# now use the hessian, too
sumsq.h <- function(x,y) diag(2, nrow = length(x))
nlminb(start = x0, sumsq, sumsq.g, sumsq.h,
       lower = -1, upper = 1, y = y)

## Rest lifted from optim help page

fr <- function(x) {   ## Rosenbrock Banana function
    x1 <- x[1]
    x2 <- x[2]
    100 * (x2 - x1 * x1)^2 + (1 - x1)^2
}
grr <- function(x) { ## Gradient of 'fr'
    x1 <- x[1]
    x2 <- x[2]
    c(-400 * x1 * (x2 - x1 * x1) - 2 * (1 - x1),
       200 *      (x2 - x1 * x1))
}
nlminb(c(-1.2,1), fr)
nlminb(c(-1.2,1), fr, grr)

flb <- function(x)
    { p <- length(x); sum(c(1, rep(4, p-1)) * (x - c(1, x[-p])^2)^2) }
## 25-dimensional box constrained
## par[24] is *not* at boundary
nlminb(rep(3, 25), flb,
          lower=rep(2, 25),
          upper=rep(4, 25))
## trying to use a too small tolerance:
r <- nlminb(rep(3, 25), flb, control = list(rel.tol=1e-16))
stopifnot(grepl("rel.tol", r$message))
\end{ExampleCode}
\end{Examples}

