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

\name{deriv}
\title{Symbolic and Algorithmic Derivatives of Simple Expressions}
\alias{D}
\alias{deriv}
\alias{deriv.default}
\alias{deriv.formula}
\alias{deriv3}
\alias{deriv3.default}
\alias{deriv3.formula}
\description{
  Compute derivatives of simple expressions, symbolically and algorithmically.
}
\usage{
    D (expr, name)
 deriv(expr, \dots)
deriv3(expr, \dots)

 \method{deriv}{default}(expr, namevec, function.arg = NULL, tag = ".expr",
       hessian = FALSE, \dots)
 \method{deriv}{formula}(expr, namevec, function.arg = NULL, tag = ".expr",
       hessian = FALSE, \dots)

\method{deriv3}{default}(expr, namevec, function.arg = NULL, tag = ".expr",
       hessian = TRUE, \dots)
\method{deriv3}{formula}(expr, namevec, function.arg = NULL, tag = ".expr",
       hessian = TRUE, \dots)
}
\arguments{
  \item{expr}{a \code{\link{expression}} or \code{\link{call}} or
    (except \code{D}) a formula with no lhs.}
  \item{name,namevec}{character vector, giving the variable names (only
    one for \code{D()}) with respect to which derivatives will be
    computed.}
  \item{function.arg}{if specified and non-\code{NULL}, a character
    vector of arguments for a function return, or a function (with empty
    body) or \code{TRUE}, the latter indicating that a function with
    argument names \code{namevec} should be used.}
  \item{tag}{character; the prefix to be used for the locally created
    variables in result.}
  \item{hessian}{a logical value indicating whether the second derivatives
    should be calculated and incorporated in the return value.}
  \item{\dots}{arguments to be passed to or from methods.}
}
\details{
  \code{D} is modelled after its S namesake for taking simple symbolic
  derivatives.

  \code{deriv} is a \emph{generic} function with a default and a
  \code{\link{formula}} method.  It returns a \code{\link{call}} for
  computing the \code{expr} and its (partial) derivatives,
  simultaneously.  It uses so-called \emph{algorithmic derivatives}.  If
  \code{function.arg} is a function, its arguments can have default
  values, see the \code{fx} example below.

  Currently, \code{deriv.formula} just calls \code{deriv.default} after
  extracting the expression to the right of \code{~}.

  \code{deriv3} and its methods are equivalent to \code{deriv} and its
  methods except that \code{hessian} defaults to \code{TRUE} for
  \code{deriv3}.

  The internal code knows about the arithmetic operators \code{+},
  \code{-}, \code{*}, \code{/} and \code{^}, and the single-variable
  functions \code{exp}, \code{log}, \code{sin}, \code{cos}, \code{tan},
  \code{sinh}, \code{cosh}, \code{sqrt}, \code{pnorm}, \code{dnorm},
  \code{asin}, \code{acos}, \code{atan}, \code{gamma}, \code{lgamma},
  \code{digamma} and \code{trigamma}, as well as \code{psigamma} for one
  or two arguments (but derivative only with respect to the first).
  (Note that only the standard normal distribution is considered.)
  \cr
  Since \R 3.4.0, the single-variable functions \code{\link{log1p}},
  \code{expm1}, \code{log2}, \code{log10}, \code{\link{cospi}},
  \code{sinpi}, \code{tanpi}, \code{\link{factorial}}, and
  \code{lfactorial} are supported as well.
}
\value{
  \code{D} returns a call and therefore can easily be iterated
  for higher derivatives.

  \code{deriv} and \code{deriv3} normally return an
  \code{\link{expression}} object whose evaluation returns the function
  values with a \code{"gradient"} attribute containing the gradient
  matrix.  If \code{hessian} is \code{TRUE} the evaluation also returns
  a \code{"hessian"} attribute containing the Hessian array.

  If \code{function.arg} is not \code{NULL}, \code{deriv} and
  \code{deriv3} return a function with those arguments rather than an
  expression.
}
\references{
  Griewank, A.  and  Corliss, G. F. (1991)
  \emph{Automatic Differentiation of Algorithms: Theory, Implementation,
    and Application}.
  SIAM proceedings, Philadelphia.

  Bates, D. M. and Chambers, J. M. (1992)
  \emph{Nonlinear models.}
  Chapter 10 of \emph{Statistical Models in S}
  eds J. M. Chambers and T. J. Hastie, Wadsworth & Brooks/Cole.
}
\seealso{
  \code{\link{nlm}} and \code{\link{optim}} for numeric minimization
  which could make use of derivatives,
}
\examples{
## formula argument :
dx2x <- deriv(~ x^2, "x") ; dx2x
\dontrun{expression({
         .value <- x^2
         .grad <- array(0, c(length(.value), 1), list(NULL, c("x")))
         .grad[, "x"] <- 2 * x
         attr(.value, "gradient") <- .grad
         .value
})}
mode(dx2x)
x <- -1:2
eval(dx2x)

## Something 'tougher':
trig.exp <- expression(sin(cos(x + y^2)))
( D.sc <- D(trig.exp, "x") )
all.equal(D(trig.exp[[1]], "x"), D.sc)

( dxy <- deriv(trig.exp, c("x", "y")) )
y <- 1
eval(dxy)
eval(D.sc)

## function returned:
deriv((y ~ sin(cos(x) * y)), c("x","y"), func = TRUE)

## function with defaulted arguments:
(fx <- deriv(y ~ b0 + b1 * 2^(-x/th), c("b0", "b1", "th"),
             function(b0, b1, th, x = 1:7){} ) )
fx(2, 3, 4)

## First derivative

D(expression(x^2), "x")
stopifnot(D(as.name("x"), "x") == 1)

## Higher derivatives
deriv3(y ~ b0 + b1 * 2^(-x/th), c("b0", "b1", "th"),
     c("b0", "b1", "th", "x") )

## Higher derivatives:
DD <- function(expr, name, order = 1) {
   if(order < 1) stop("'order' must be >= 1")
   if(order == 1) D(expr, name)
   else DD(D(expr, name), name, order - 1)
}
DD(expression(sin(x^2)), "x", 3)
## showing the limits of the internal "simplify()" :
\dontrun{
-sin(x^2) * (2 * x) * 2 + ((cos(x^2) * (2 * x) * (2 * x) + sin(x^2) *
    2) * (2 * x) + sin(x^2) * (2 * x) * 2)
}

## New (R 3.4.0, 2017):
D(quote(log1p(x^2)), "x") ## log1p(x) = log(1 + x)
stopifnot(identical(
       D(quote(log1p(x^2)), "x"),
       D(quote(log(1+x^2)), "x")))
D(quote(expm1(x^2)), "x") ## expm1(x) = exp(x) - 1
stopifnot(identical(
       D(quote(expm1(x^2)), "x") -> Dex1,
       D(quote(exp(x^2)-1), "x")),
       identical(Dex1, quote(exp(x^2) * (2 * x))))

D(quote(sinpi(x^2)), "x") ## sinpi(x) = sin(pi*x)
D(quote(cospi(x^2)), "x") ## cospi(x) = cos(pi*x)
D(quote(tanpi(x^2)), "x") ## tanpi(x) = tan(pi*x)

stopifnot(identical(D(quote(log2 (x^2)), "x"),
                    quote(2 * x/(x^2 * log(2)))),
          identical(D(quote(log10(x^2)), "x"),
                    quote(2 * x/(x^2 * log(10)))))

}
\keyword{math}
\keyword{nonlinear}