\Header{deriv}{Symbolic and Algorithmic Derivatives of Simple Expressions}
\alias{D}{deriv}
\alias{deriv.default}{deriv}
\alias{deriv.formula}{deriv}
\keyword{math}{deriv}
\keyword{nonlinear}{deriv}
\begin{Usage}
\begin{verbatim}
D(expr, namevec)
deriv(expr, namevec, function.arg = NULL, tag = ".expr")
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{expr}] expression which should be derivated
\item[\texttt{namevec}] character vector, giving the variable names with
respect to which derivatives will be computed.
\item[\texttt{function.arg}] ... ?? ...
\item[\texttt{tag}] ... ?? ...
\end{ldescription}
\end{Arguments}
\begin{Description}
\texttt{D} is modelled after its S pendant for taking simple symbolic
derivatives.

\texttt{deriv} is a \emph{generic} function with a default and a
\texttt{\Link{formula}} method.  It returns a \texttt{\Link{call}} for
computing the \texttt{expr} and its (partial) derivatives,
simultaneously.  It uses so-called \emph{``algorithmic
derivatives''}.

Currently, \texttt{deriv.formula} just calls \texttt{deriv.default} after
extracting the expression to the right of \texttt{$\,\tilde{\,}$}.\end{Description}
\begin{Value}
\texttt{D} returns an expression and therefore can easily be iterated
for higher derivatives.

\texttt{deriv} returns a \texttt{\Link{call}} object which becomes an
\texttt{\Link{expression}} when evaluated once.  Evaluation of the
latter expression returns the function values with a
\texttt{".gradient"} attribute containing the gradient matrix.\end{Value}
\begin{Note}
This help page should be fixed up by one of R\&R or someone else who
fluently speaks the language in \file{\$RHOME/src/main/deriv.c}.

It's author, MM, has only got a vague idea and thinks that a help page
is better than none.\end{Note}
\begin{References}
A. Griewank, G. F. Corliss (1991).
\emph{Automatic Differentiation of Algorithms: Theory, Implementation,
and Application}.
SIAM proceedings, Philadelphia.\end{References}
\begin{SeeAlso}
\texttt{\Link{nlm}} for numeric minimization which should make use of
derivatives.\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, c("x", "y")) )

( dxy <- deriv(trig.exp, c("x", "y")) )
y <- 1
eval(dxy)
eval(D.sc)
\end{ExampleCode}
\end{Examples}

