s_autodiff/text/doc_ad_grdchk.tex


%**********************************************************************
\section{The gradient check package}
\label{sect:ad_gradient_check}
\label{sec_ad_radient_check}
%**********************************************************************

An indispensable test to validate the gradient computed
via the adjoint is a comparison against finite difference
gradients.
The gradient check package {\it pkg/grdchk} enables such tests
in a straightforward and easy manner.
The driver routine {\it grdchk\_main} is called from
{\it the\_model\_main} after the gradient has been computed
via the adjoint model (cf. flow chart ???).

The gradient check proceeds as follows:
The $i-$th component of the gradient $ (\nabla _{u}{\cal J}^T)_i $
is compared with  the following finite-difference gradient:
\[
\left(\nabla _{u}{\cal J}^T  \right)_i \quad \text{ vs. } \quad
\frac{\partial {\cal J}}{\partial u_i} \, = \,
\frac{ {\cal J}(u_i + \epsilon) - {\cal J}(u_i)}{\epsilon}
\]
A gradient check at point $u_i$ may generally considered to be successful
if the deviation of the ratio between the adjoint and the 
finite difference gradient from unity is less than 1 percent,
\[
1 \, - \, 
\frac{({\rm grad}{\cal J})_i (\text{adjoint})}
{({\rm grad}{\cal J})_i (\text{finite difference})} \, < 1 \%
\]

\subsection{Code description}
~

\subsection{Code configuration}
%
The relevant CPP precompile options are set
in the following files:
%
\begin{itemize}
%
\item {\it .genmakerc} \\
option {\tt grdchk} is added to the {\bf enable list}
(alternatively, {\it genmake} may be invoked with the
option {\tt -enable=grdchk}).
%
\item {\it CPP\_OPTIONS.h} \\
Together with the flag 
{\bf ALLOW\_ADJOINT\_RUN}, define the flag
{\bf ALLOW\_GRADIENT\_CHECK}.
%
\end{itemize}

The relevant runtime flags are set in the files
%
\begin{itemize}
%
\item {\it data.pkg} \\
Set {\bf useGrdchk = .TRUE.}
%
\item {\it data.grdchk}
%
\begin{itemize}
%
\item {\bf grdchk\_eps}
~
\item {\bf nbeg}
~
\item {\bf nstep}
~
\item {\bf nend}
~
\item {\bf grdchkvarindex}
~
%
\end{itemize}
%
\end{itemize}


\input{part5/doc_grdchk_flow}

1	heimbach	1.1
2			%**********************************************************************
3			\section{The gradient check package}
4			\label{sect:ad_gradient_check}
5			\label{sec_ad_radient_check}
6			%**********************************************************************
7
8			An indispensable test to validate the gradient computed
9			via the adjoint is a comparison against finite difference
10			gradients.
11			The gradient check package {\it pkg/grdchk} enables such tests
12			in a straightforward and easy manner.
13			The driver routine {\it grdchk\_main} is called from
14			{\it the\_model\_main} after the gradient has been computed
15			via the adjoint model (cf. flow chart ???).
16
17			The gradient check proceeds as follows:
18			The $i-$th component of the gradient $ (\nabla _{u}{\cal J}^T)_i $
19			is compared with the following finite-difference gradient:
20			\[
21			\left(\nabla _{u}{\cal J}^T \right)_i \quad \text{ vs. } \quad
22			\frac{\partial {\cal J}}{\partial u_i} \, = \,
23			\frac{ {\cal J}(u_i + \epsilon) - {\cal J}(u_i)}{\epsilon}
24			\]
25			A gradient check at point $u_i$ may generally considered to be successful
26			if the deviation of the ratio between the adjoint and the
27			finite difference gradient from unity is less than 1 percent,
28			\[
29			1 \, - \,
30			\frac{({\rm grad}{\cal J})_i (\text{adjoint})}
31			{({\rm grad}{\cal J})_i (\text{finite difference})} \, < 1 \%
32			\]
33
34			\subsection{Code description}
35			~
36
37			\subsection{Code configuration}
38			%
39			The relevant CPP precompile options are set
40			in the following files:
41			%
42			\begin{itemize}
43			%
44			\item {\it .genmakerc} \\
45			option {\tt grdchk} is added to the {\bf enable list}
46			(alternatively, {\it genmake} may be invoked with the
47			option {\tt -enable=grdchk}).
48			%
49			\item {\it CPP\_OPTIONS.h} \\
50			Together with the flag
51			{\bf ALLOW\_ADJOINT\_RUN}, define the flag
52			{\bf ALLOW\_GRADIENT\_CHECK}.
53			%
54			\end{itemize}
55
56			The relevant runtime flags are set in the files
57			%
58			\begin{itemize}
59			%
60			\item {\it data.pkg} \\
61			Set {\bf useGrdchk = .TRUE.}
62			%
63			\item {\it data.grdchk}
64			%
65			\begin{itemize}
66			%
67			\item {\bf grdchk\_eps}
68			~
69			\item {\bf nbeg}
70			~
71			\item {\bf nstep}
72			~
73			\item {\bf nend}
74			~
75			\item {\bf grdchkvarindex}
76			~
77			%
78			\end{itemize}
79			%
80			\end{itemize}
81
82
83			\input{part5/doc_grdchk_flow}
84