% File src/library/stats/man/constrOptim.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2010 R Core Team
% Distributed under GPL 2 or later

\name{constrOptim}
\alias{constrOptim}
\title{Linearly Constrained Optimization}
\description{
Minimise a function subject to linear inequality constraints using an
adaptive barrier algorithm.
}
\usage{
constrOptim(theta, f, grad, ui, ci, mu = 1e-04, control = list(),
            method = if(is.null(grad)) "Nelder-Mead" else "BFGS",
            outer.iterations = 100, outer.eps = 1e-05, \dots,
            hessian = FALSE)
}
\arguments{
  \item{theta}{numeric (vector) starting value (of length \eqn{p}): must
    be in the feasible region.}
  \item{f}{function to minimise (see below).}
  \item{grad}{gradient of \code{f} (a \code{\link{function}} as well),
    or \code{NULL} (see below).}
  \item{ui}{constraint matrix (\eqn{k \times p}{k x p}), see below.}
  \item{ci}{constraint vector of length \eqn{k} (see below).}
  \item{mu}{(Small) tuning parameter.}
  \item{control, method, hessian}{passed to \code{\link{optim}}.}
  \item{outer.iterations}{iterations of the barrier algorithm.}
  \item{outer.eps}{non-negative number; the relative convergence
    tolerance of the barrier algorithm.}
  \item{\dots}{Other named arguments to be passed to \code{f} and \code{grad}:
    needs to be passed through \code{\link{optim}} so should not match its
    argument names.}
}
\details{
  The feasible region is defined by \code{ui \%*\% theta - ci >= 0}. The
  starting value must be in the interior of the feasible region, but the
  minimum may be on the boundary.

  A logarithmic barrier is added to enforce the constraints and then
  \code{\link{optim}} is called. The barrier function is chosen so that
  the objective function should decrease at each outer iteration. Minima
  in the interior of the feasible region are typically found quite
  quickly, but a substantial number of outer iterations may be needed
  for a minimum on the boundary.

  The tuning parameter \code{mu} multiplies the barrier term. Its precise
  value is often relatively unimportant. As \code{mu} increases the
  augmented objective function becomes closer to the original objective
  function but also less smooth near the boundary of the feasible
  region.

  Any \code{optim} method that permits infinite values for the
  objective function may be used (currently all but "L-BFGS-B").

  The objective function \code{f} takes as first argument the vector
  of parameters over which minimisation is to take place.  It should
  return a scalar result. Optional arguments \code{\dots} will be
  passed to \code{optim} and then (if not used by \code{optim}) to
  \code{f}. As with \code{optim}, the default is to minimise, but
  maximisation can be performed by setting \code{control$fnscale} to a
  negative value.

  The gradient function \code{grad} must be supplied except with
  \code{method = "Nelder-Mead"}.  It should take arguments matching
  those of \code{f} and return a vector containing the gradient.

}
\value{
  As for \code{\link{optim}}, but with two extra components:
  \code{barrier.value} giving the value of the barrier function at the
  optimum and \code{outer.iterations} gives the
  number of outer iterations (calls to \code{optim}).
  The \code{counts} component contains the \emph{sum} of all
  \code{\link{optim}()$counts}.
}

\references{
  K. Lange \emph{Numerical Analysis for Statisticians.} Springer
  2001, p185ff
}

\seealso{
  \code{\link{optim}}, especially \code{method = "L-BFGS-B"} which
  does box-constrained optimisation.
}

\examples{\donttest{
## from optim
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))
}

optim(c(-1.2,1), fr, grr)
#Box-constraint, optimum on the boundary
constrOptim(c(-1.2,0.9), fr, grr, ui = rbind(c(-1,0), c(0,-1)), ci = c(-1,-1))
#  x <= 0.9,  y - x > 0.1
constrOptim(c(.5,0), fr, grr, ui = rbind(c(-1,0), c(1,-1)), ci = c(-0.9,0.1))


## Solves linear and quadratic programming problems
## but needs a feasible starting value
#
# from example(solve.QP) in 'quadprog'
# no derivative
fQP <- function(b) {-sum(c(0,5,0)*b)+0.5*sum(b*b)}
Amat       <- matrix(c(-4,-3,0,2,1,0,0,-2,1), 3, 3)
bvec       <- c(-8, 2, 0)
constrOptim(c(2,-1,-1), fQP, NULL, ui = t(Amat), ci = bvec)
# derivative
gQP <- function(b) {-c(0, 5, 0) + b}
constrOptim(c(2,-1,-1), fQP, gQP, ui = t(Amat), ci = bvec)

## Now with maximisation instead of minimisation
hQP <- function(b) {sum(c(0,5,0)*b)-0.5*sum(b*b)}
constrOptim(c(2,-1,-1), hQP, NULL, ui = t(Amat), ci = bvec,
            control = list(fnscale = -1))
}}
\keyword{optimize}