/* --------------------------------------------------------------------------
CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-22 Bradley M. Bell

CppAD is distributed under the terms of the
             Eclipse Public License Version 2.0.

This Source Code may also be made available under the following
Secondary License when the conditions for such availability set forth
in the Eclipse Public License, Version 2.0 are satisfied:
      GNU General Public License, Version 2.0 or later.
---------------------------------------------------------------------------- */
$begin atomic_four_lin_ode$$
$spell
    nr
    nc
    mul
    lin
    Rosen
    Simpon
    nnz
$$

$section
    Atomic First Order Linear ODE Method: Example Implementation
$$

$head Under construction$$
This example is under construction and not yet ready for use.

$head Syntax$$
$codei%atomic_lin_ode %ode%(%name%)
%$$
$icode%call_id% = %lin_ode%.set(%r%, %pattern%, %transpose%)
%$$
$icode%lin_ode%.get(%call_id%, %r%, %pattern%, %transpose%)
%$$
$icode%lin_ode%(%call_id%, %x%, %y%)
%$$

$head z(t, x)$$
Construct an atomic operation that computes an
approximate solution of the first order linear initial value ODE
$latex \[
    z_t (t, x) = A(x) z(t, x) \W{,} z(0, x) = b(x)
\] $$
where
$latex z : \B{R} \times \B{R}^n \rightarrow \B{R}^m$$,
$latex A : \B{R}^n \rightarrow \B{R}^{m \times m}$$,
$latex b : \B{R}^n \rightarrow  \B{R}^m$$,
and the subscript $latex t$$ denotes partial differentiation w.r.t $latex t$$.

$head y(x)$$
This input value of the elements of $icode y$$ does not matter.
Upon return it is the final value of the ODE solution,
$latex y(x) = z(r, x)$$.

$subhead m$$
We use $icode m$$ to denote the size of the vector $icode y$$.
This is the number of equations in the ODE.

$head call_id$$
This is a return value (argument) for the $code set$$ ($code get$$) routine.

$head r$$
This is the value of $icode t$$ at which we are approximating $latex z(t, x)$$.
This is a argument (return value) for the $code set$$ ($code get$$) routine.

$head pattern$$
This is a sparsity pattern.
This is a argument (return value) for the $code set$$ ($code get$$) routine.

$subhead nnz$$
We use $icode nnz$$ to denote $icode%pattern%.nnz()%$$.

$subhead row$$
We use $icode row$$ to denote $icode%pattern%.row()%$$.

$subhead col$$
We use $icode col$$ to denote $icode%pattern%.col()%$$.

$head transpose$$
If $icode transpose$$ is true (false) the sparsity pattern is for
$latex A(x)^\R{T}$$ ($latex A(x)$$).
This is a argument (return value) for the $code set$$ ($code get$$) routine.

$head x$$
We use $icode x$$ to denote the argument to the atomic function.

$subhead n$$
The size of the vector $icode x$$ is
$latex n = nnz + m$$.

$subhead A(x)$$
This matrix stored in the same order as $icode pattern$$
at the beginning of the vector $icode x$$.
To be specific,
if $icode transpose$$ is true (false),
for $icode%k% = 0, %...%, %nnz%-1%$$,
$latex A_{j,i} (x)$$ ( $latex A_{i,j} (x)$$ ) is equal to
$latex x[k]$$ where $icode%i% = %row%[%k%]%$$ and  $icode%j% = %col%[%k%]%$$.

$subhead b(x)$$
This vector is stored at the end of
$icode x$$; i.e. its $th j$$ element is
$latex b_j (x) = x[ nnz + j ]$$


$head Approximations$$

$subhead Rosen34$$
The $cref/Rosen34/atomic_four_lin_ode_base_lin_ode.hpp/Rosen34/$$ routine
is used to approximate the solution of the ODE.
Any initial value ODE solver can be used for this purpose.

$subhead Simpon's Rule$$
$cref/Simpon's rule/atomic_four_lin_ode_reverse.hpp/Simpon's Rule/$$
is used to approximate the integral
$latex \[
    \int_0^r \lambda_i (t, x) z_j (r, x) \R{d} t
\] $$
Any other approximation for this integral can be used.

$childtable%
    include/cppad/example/atomic_four/lin_ode/implement.omh
    %example/atomic_four/lin_ode/forward.cpp
    %example/atomic_four/lin_ode/reverse.cpp
    %example/atomic_four/lin_ode/sparsity.cpp
%$$

$end
