/* $Id: forward_two.omh 3472 2014-12-15 13:29:52Z bradbell $ */
/* --------------------------------------------------------------------------
CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-14 Bradley M. Bell

CppAD is distributed under multiple licenses. This distribution is under
the terms of the 
                    Eclipse Public License Version 1.0.

A copy of this license is included in the COPYING file of this distribution.
Please visit http://www.coin-or.org/CppAD/ for information on other licenses.
-------------------------------------------------------------------------- */
$begin forward_two$$
$spell
	Jacobian
	Taylor
	const
$$

$section Second Order Forward Mode: Derivative Values$$

$index Forward, order two$$
$index two, order Forward$$
$index order, two Forward$$


$head Syntax$$
$icode%y2% = %f%.Forward(1, %x2%)%$$

$head Purpose$$
We use $latex F : B^n \rightarrow B^m$$ to denote the
$cref/AD function/glossary/AD Function/$$ corresponding to $icode f$$.
The result of the syntax above is that for
$icode%i% = 0 , %...% , %m%-1%$$,
$codei%
	%y2%[%i%]%$$
	$latex = F_i^{(1)} (x0) * x2 + \frac{1}{2} x1^T * F_i^{(2)} (x0) * x1$$
$pre
$$
where
$latex F^{(1)} (x0)$$ is the Jacobian of $latex F$$, and 
$latex F_i^{(2)} (x0)$$ is the Hessian of th $th i$$ component of $latex F$$,
evaluated at $icode x0$$. 

$head f$$
The object $icode f$$ has prototype
$codei%
	ADFun<%Base%> %f%
%$$
Note that the $cref ADFun$$ object $icode f$$ is not $code const$$.
Before this call to $code Forward$$, the value returned by
$codei%
	%f%.size_order()
%$$
must be greater than or equal two.
After this call it will be will be three (see $cref size_order$$).

$head x0$$
The vector $icode x0$$ in the formula for $icode%y2%[%i%]%$$
corresponds to the previous call to $cref forward_zero$$
using this ADFun object $icode f$$; i.e.,
$codei%
	%f%.Forward(0, %x0%)
%$$
If there is no previous call with the first argument zero,
the value of the $cref/independent/Independent/$$ variables 
during the recording of the AD sequence of operations is used
for $icode x0$$.

$head x1$$
The vector $icode x1$$ in the formula for $icode%y2%[%i%]%$$
corresponds to the previous call to $cref forward_one$$
using this ADFun object $icode f$$; i.e.,
$codei%
	%f%.Forward(1, %x1%)
%$$

$head x2$$
The argument $icode x2$$ has prototype
$codei%
	const %Vector%& %x2%
%$$
(see $cref/Vector/forward_two/Vector/$$ below)
and its size must be equal to $icode n$$, the dimension of the
$cref/domain/seq_property/Domain/$$ space for $icode f$$.

$head y2$$
The result $icode y2$$ has prototype
$codei%
	%Vector% %y2%
%$$
(see $cref/Vector/forward_two/Vector/$$ below)
The size of $icode y1$$ is equal to $icode m$$, the dimension of the
$cref/range/seq_property/Range/$$ space for $icode f$$.
Its value is given element-wise by the formula in the
$cref/purpose/forward_two/Purpose/$$ above.

$head Vector$$
The type $icode Vector$$ must be a $cref SimpleVector$$ class with
$cref/elements of type/SimpleVector/Elements of Specified Type/$$
$icode Base$$.
The routine $cref CheckSimpleVector$$ will generate an error message
if this is not the case.

$head Example$$
The file
$cref forward.cpp$$
contains an example and test of this operation.
It returns true if it succeeds and false otherwise.

$head Special Case$$
This is special case of $cref forward_order$$ where
$latex \[
\begin{array}{rcl}
Y(t) & = F[ X(t) ]
\\
X(t) & = & x^{(0)} t^0 + x^{(1)} * t^1 + \cdots, + x^{(q)} * t^q + o( t^q ) 
\\
Y(t) & = & y^{(0)} t^0 + y^{(1)} * t^1 + \cdots, + y^{(q)} * t^q + o( t^q ) 
\end{array}
\] $$ 
and $latex o( t^q ) * t^{-q} \rightarrow 0$$ as $latex t \rightarrow 0$$.
For this special case, $latex q = 2$$,
$latex x^{(0)}$$ $codei%= %x0%$$,
$latex x^{(1)}$$ $codei%= %x1%$$,
$latex X(t) = x^{(0)} + x^{(1)} t + x^{(2)} t^2$$, and
$latex \[
y^{(0)} + y^{(1)} t  + y^{(2)} t^2 
= 
F [ x^{(0)} + x^{(1)} t + x^{(2)} t^2 ] + o(t^2)
\] $$ 
Restricting our attention to the $th i$$ component, and
taking the derivative with respect to $latex t$$, we obtain
$latex \[
y_i^{(1)} + 2 y_i^{(2)} t 
= 
F_i^{(1)} [ x^{(0)} + x^{(1)} t + x^{(2)} t^2 ] [ x^{(1)} + 2 x^{(2)} t ] 
+ 
o(t)
\] $$
Taking a second derivative with respect to $latex t$$, 
and evaluating at $latex t = 0$$, we obtain
$latex \[
2 y_i^{(2)}
=
[ x^{(1)} ]^T F_i^{(2)} [ x^{(0)} ] x^{(1)}
+
F_i^{(1)} [ x^{(0)} ] 2 x^{(2)} 
\] $$
which agrees with the specification for $icode%y2%[%i%]%$$ in the
$cref/purpose/forward_two/Purpose/$$ above.

$end