\Header{deriv}{Symbolic and Algorithmic Derivatives of Simple Expressions}
\alias{D}{deriv}
\methalias{deriv.default}{deriv}
\methalias{deriv.formula}{deriv}
\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, namevec, function.arg = NULL, tag = ".expr")
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{expr}] \code{\Link{expression}} or \code{\Link{call}} which should
be differentiated.
\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, a character vector of arguments for
a function return. \bold{Note:} this is incompatible with S.
\item[\code{tag}] character; the prefix to be used for the locally created
variables in result.
\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{\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''}.

Currently, \code{deriv.formula} just calls \code{deriv.default} after
extracting the expression to the right of \code{\textasciitilde{}}.\end{Details}
\begin{Value}
\code{D} returns a call and therefore can easily be iterated
for higher derivatives.

\code{deriv} normally returns an \code{\Link{expression}} object.
Its evaluation returns the function values with a
\code{".gradient"} attribute containing the gradient matrix.
If \code{function.arg} is specified, it returns a function.\end{Value}
\begin{Note}\relax
This help page should be fixed up by one of R\&R or someone else who
fluently speaks the language in \file{\$R\_HOME/src/main/deriv.c}.

Its author, MM, has only got a vague idea and thinks that a help page
is better than none.\end{Note}
\begin{References}\relax
Griewank, A.  and  Corliss, G. F. (1991)
\emph{Automatic Differentiation of Algorithms: Theory, Implementation,
and Application}.
SIAM proceedings, Philadelphia.\end{References}
\begin{SeeAlso}\relax
\code{\Link{nlm}} and \code{\Link{optim}} for numeric minimization
which could make use of derivatives,
\code{\Link{nls}} in package \code{nls}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## formula argument :
dx2x <- deriv(~ x^2, "x") ; dx2x
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)
stopifnot(eval(D.sc) ==
          attr(eval(dxy),"gradient")[,"x"])

## function returned:
deriv(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()" :

-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{ExampleCode}
\end{Examples}

