s_autodiff/text/doc_ad_grdchk.tex


%**********************************************************************
\section{The gradient check package}
\label{sec:ad_gradient_check}
\label{sec_ad_radient_check}
\begin{rawhtml}
<!-- CMIREDIR:sec_ad_radient_check: -->
\end{rawhtml}
%**********************************************************************

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{s_autodiff/text/doc_grdchk_flow}

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