| % File src/library/stats/man/nlminb.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2017 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{nlminb} |
| \alias{nlminb} |
| \title{Optimization using PORT routines } |
| \description{ |
| Unconstrained and box-constrained optimization using PORT routines. |
| |
| For historical compatibility. |
| } |
| \usage{ |
| nlminb(start, objective, gradient = NULL, hessian = NULL, \dots, |
| scale = 1, control = list(), lower = -Inf, upper = Inf) |
| } |
| \arguments{ |
| \item{start}{ |
| numeric vector, initial values for the parameters to be optimized. |
| } |
| \item{objective}{ |
| Function to be minimized. Must return a scalar value. 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{\dots}). |
| } |
| \item{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{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{\dots}{Further arguments to be supplied to \code{objective}.} |
| \item{scale}{See PORT documentation (or leave alone).} |
| \item{control}{A list of control parameters. See below for details.} |
| \item{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. |
| } |
| } |
| \details{ |
| Any names of \code{start} are 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}. |
| |
| If any of the functions returns \code{NA} or \code{NaN} this is an |
| error for the gradient and Hessian, and such values for function |
| evaluation are replaced by \code{+Inf} with a warning. |
| } |
| % see PR#15052. |
| \value{ |
| A list with components: |
| \item{par}{The best set of parameters found.} |
| \item{objective}{The value of \code{objective} corresponding to \code{par}.} |
| \item{convergence}{An integer code. \code{0} indicates successful |
| convergence. |
| } |
| \item{message}{ |
| A character string giving any additional information returned by the |
| optimizer, or \code{NULL}. For details, see PORT documentation. |
| } |
| \item{iterations}{Number of iterations performed.} |
| \item{evaluations}{Number of objective function and gradient function evaluations} |
| } |
| \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.}% MXFCAL |
| \item{\code{iter.max}}{Maximum number of iterations allowed. |
| Defaults to 150.}% MXITER |
| \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 0 so the absolute convergence test is not used. If the objective |
| function is known to be non-negative, the previous default of |
| \code{1e-20} would be more appropriate.}% AFCTOL 31 |
| \item{\code{rel.tol}}{Relative tolerance. Defaults to |
| \code{1e-10}.}% RFCTOL 32 |
| \item{\code{x.tol}}{X tolerance. Defaults to \code{1.5e-8}.}% XCTOL 33 |
| \item{\code{xf.tol}}{false convergence tolerance. Defaults to |
| \code{2.2e-14}.}% XFTOL 34 |
| \item{\code{step.min, step.max}}{Minimum and maximum step size. Both |
| default to \code{1.}.}% LMAX0 35 / LMAXS 36 |
| \item{sing.tol}{singular convergence tolerance; defaults to |
| \code{rel.tol}.}% SCTOL 37 |
| \item{scale.init}{...}% DINIT 38 |
| \item{diff.g}{an estimated bound on the relative error in the |
| objective function value.}% ETA0 42 |
| } |
| } |
| \source{ |
| \url{http://www.netlib.org/port/} |
| } |
| \references{ |
| David M. Gay (1990), |
| Usage summary for selected optimization routines. |
| Computing Science Technical Report 153, AT&T Bell Laboratories, Murray |
| Hill. |
| } |
| \author{ |
| \R port: Douglas Bates and Deepayan Sarkar. |
| |
| Underlying Fortran code by David M. Gay |
| } |
| \seealso{ |
| \code{\link{optim}} (which is preferred) and \code{\link{nlm}}. |
| |
| \code{\link{optimize}} for one-dimensional minimization and |
| \code{\link{constrOptim}} for constrained optimization. |
| } |
| % Lots of near-zeros, platform-specific results. |
| \examples{\donttest{ |
| 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)) |
| }} |
| \keyword{optimize} |