\HeaderA{deriv}{Symbolic and Algorithmic Derivatives of Simple Expressions}{deriv}
\aliasA{D}{deriv}{D}
\methaliasA{deriv.default}{deriv}{deriv.default}
\methaliasA{deriv.formula}{deriv}{deriv.formula}
\aliasA{deriv3}{deriv}{deriv3}
\methaliasA{deriv3.default}{deriv}{deriv3.default}
\methaliasA{deriv3.formula}{deriv}{deriv3.formula}
\keyword{math}{deriv}
\keyword{nonlinear}{deriv}
\begin{Description}\relax
Compute derivatives of simple expressions, symbolically.
\end{Description}
\begin{Usage}
\begin{verbatim}
    D (expr, name)
 deriv(expr, ...)
deriv3(expr, ...)

 ## Default S3 method:
 deriv(expr, namevec, function.arg = NULL, tag = ".expr",
       hessian = FALSE, ...)
 ## S3 method for class 'formula':
 deriv(expr, namevec, function.arg = NULL, tag = ".expr",
       hessian = FALSE, ...)

## Default S3 method:
deriv3(expr, namevec, function.arg = NULL, tag = ".expr",
       hessian = TRUE, ...)
## S3 method for class 'formula':
deriv3(expr, namevec, function.arg = NULL, tag = ".expr",
       hessian = TRUE, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{expr}] A \code{\LinkA{expression}{expression}} or \code{\LinkA{call}{call}} or
(except \code{D}) a formula with no lhs.
\item[\code{name,namevec}] character vector, giving the variable names (only
one for \code{D()}) with respect to which derivatives will be
computed.
\item[\code{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[\code{tag}] character; the prefix to be used for the locally created
variables in result.
\item[\code{hessian}] a logical value indicating whether the second derivatives
should be calculated and incorporated in the return value.
\item[\code{...}] arguments to tbe passed to or from methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\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{\LinkA{formula}{formula}} method.  It returns a \code{\LinkA{call}{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{\textasciitilde{}}.

\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{\textasciicircum{}}, 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.)
\end{Details}
\begin{Value}
\code{D} returns a call and therefore can easily be iterated
for higher derivatives.

\code{deriv} and \code{deriv3} normally return an
\code{\LinkA{expression}{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.
\end{Value}
\begin{References}\relax
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.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{nlm}{nlm}} and \code{\LinkA{optim}{optim}} for numeric minimization
which could make use of derivatives,
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## formula argument :
dx2x <- deriv(~ x^2, "x") ; dx2x
## Not run: 
expression({
         .value <- x^2
         .grad <- array(0, c(length(.value), 1), list(NULL, c("x")))
         .grad[, "x"] <- 2 * x
         attr(.value, "gradient") <- .grad
         .value
})
## End(Not run)
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)

## 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()" :
## Not run: 
-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)
## End(Not run)
\end{ExampleCode}
\end{Examples}

