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
2	%**********************************************************************
3	\section{The gradient check package}
4	\label{sec:ad_gradient_check}
5	\label{sec_ad_radient_check}
6	\begin{rawhtml}
7	<!-- CMIREDIR:sec_ad_radient_check: -->
8	\end{rawhtml}
9	%**********************************************************************
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	\input{s_autodiff/text/doc_grdchk_flow}
87