/[MITgcm]/manual/s_autodiff/text/doc_ad_2.tex
ViewVC logotype

Diff of /manual/s_autodiff/text/doc_ad_2.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph | View Patch Patch

revision 1.15 by heimbach, Wed Apr 24 11:01:46 2002 UTC revision 1.23 by jmc, Mon Aug 30 23:09:19 2010 UTC
# Line 1  Line 1 
1  % $Header$  % $Header$
2  % $Name$  % $Name$
3    
4    Author: Patrick Heimbach
5    \label{ask_the_author:doc_ad_2}
6    
7  {\sf Automatic differentiation} (AD), also referred to as algorithmic  {\sf Automatic differentiation} (AD), also referred to as algorithmic
8  (or, more loosely, computational) differentiation, involves  (or, more loosely, computational) differentiation, involves
9  automatically deriving code to calculate  automatically deriving code to calculate partial derivatives from an
10  partial derivatives from an existing fully non-linear prognostic code.  existing fully non-linear prognostic code.  (see \cite{gri:00}).  A
11  (see \cite{gri:00}).  software tool is used that parses and transforms source files
12  A software tool is used that parses and transforms source files  according to a set of linguistic and mathematical rules.  AD tools are
13  according to a set of linguistic and mathematical rules.  like source-to-source translators in that they parse a program code as
14  AD tools are like source-to-source translators in that  input and produce a new program code as output
15  they parse a program code as input and produce a new program code  (we restrict our discussion to source-to-source tools, ignoring
16  as output.  operator-overloading tools).  However, unlike a
17  However, unlike a pure source-to-source translation, the output program  pure source-to-source translation, the output program represents a new
18  represents a new algorithm, such as the evaluation of the  algorithm, such as the evaluation of the Jacobian, the Hessian, or
19  Jacobian, the Hessian, or higher derivative operators.  higher derivative operators.  In principle, a variety of derived
20  In principle, a variety of derived algorithms  algorithms can be generated automatically in this way.
21  can be generated automatically in this way.  
22    MITgcm has been adapted for use with the Tangent linear and Adjoint
23  The MITGCM has been adapted for use with the  Model Compiler (TAMC) and its successor TAF (Transformation of
24  Tangent linear and Adjoint Model Compiler (TAMC) and its successor TAF  Algorithms in Fortran), developed by Ralf Giering (\cite{gie-kam:98},
25  (Transformation of Algorithms in Fortran), developed  \cite{gie:99,gie:00}).  The first application of the adjoint of MITgcm
26  by Ralf Giering (\cite{gie-kam:98}, \cite{gie:99,gie:00}).  for sensitivity studies has been published by \cite{maro-eta:99}.
27  The first application of the adjoint of the MITGCM for sensitivity  \cite{stam-etal:97,stam-etal:02} use MITgcm and its adjoint for ocean
28  studies has been published by \cite{maro-eta:99}.  state estimation studies.  In the following we shall refer to TAMC and
29  \cite{sta-eta:97,sta-eta:01} use the MITGCM and its adjoint  TAF synonymously, except were explicitly stated otherwise.
30  for ocean state estimation studies.  
31  In the following we shall refer to TAMC and TAF synonymously,  As of mid-2007 we are also able to generate fairly efficient
32  except were explicitly stated otherwise.  adjoint code of the MITgcm using a new, open-source AD tool,
33    called OpenAD (see \cite{naum-etal:06,utke-etal:08}.
34  TAMC exploits the chain rule for computing the first  This enables us for the first time to compare adjoint models
35  derivative of a function with  generated from different AD tools, providing an additional
36  respect to a set of input variables.  accuracy check, complementary to finite-difference gradient checks.
37  Treating a given forward code as a composition of operations --  OpenAD and its application to  MITgcm is described in detail
38  each line representing a compositional element, the chain rule is  in section \ref{sec_ad_openad}.
39  rigorously applied to the code, line by line. The resulting  
40  tangent linear or adjoint code,  The AD tool exploits the chain rule for computing the first derivative of a
41  then, may be thought of as the composition in  function with respect to a set of input variables.  Treating a given
42  forward or reverse order, respectively, of the  forward code as a composition of operations -- each line representing
43  Jacobian matrices of the forward code's compositional elements.  a compositional element, the chain rule is rigorously applied to the
44    code, line by line. The resulting tangent linear or adjoint code,
45    then, may be thought of as the composition in forward or reverse
46    order, respectively, of the Jacobian matrices of the forward code's
47    compositional elements.
48    
49  %**********************************************************************  %**********************************************************************
50  \section{Some basic algebra}  \section{Some basic algebra}
51  \label{sec_ad_algebra}  \label{sec_ad_algebra}
52    \begin{rawhtml}
53    <!-- CMIREDIR:sec_ad_algebra: -->
54    \end{rawhtml}
55  %**********************************************************************  %**********************************************************************
56    
57  Let $ \cal{M} $ be a general nonlinear, model, i.e. a  Let $ \cal{M} $ be a general nonlinear, model, i.e. a
# Line 56  model output variable $\vec{v}=(v_1,\ldo Line 66  model output variable $\vec{v}=(v_1,\ldo
66  under consideration,  under consideration,
67  %  %
68  \begin{equation}  \begin{equation}
69  \begin{split}  \begin{aligned}
70  {\cal M} \, : & \, U \,\, \longrightarrow \, V \\  {\cal M} \, : & \, U \,\, \longrightarrow \, V \\
71  ~      & \, \vec{u} \,\, \longmapsto \, \vec{v} \, = \,  ~      & \, \vec{u} \,\, \longmapsto \, \vec{v} \, = \,
72  {\cal M}(\vec{u})  {\cal M}(\vec{u})
73  \label{fulloperator}  \label{fulloperator}
74  \end{split}  \end{aligned}
75  \end{equation}  \end{equation}
76  %  %
77  The vectors $ \vec{u} \in U $ and $ v \in V $ may be represented w.r.t.  The vectors $ \vec{u} \in U $ and $ v \in V $ may be represented w.r.t.
# Line 141  w.r.t. their corresponding inner product Line 151  w.r.t. their corresponding inner product
151  $\left\langle \,\, , \,\, \right\rangle $  $\left\langle \,\, , \,\, \right\rangle $
152  %  %
153  \begin{equation}  \begin{equation}
154  \begin{split}  \begin{aligned}
155  {\cal J} & = \,  {\cal J} & = \,
156  {\cal J} |_{\vec{u}^{(0)}} \, + \,  {\cal J} |_{\vec{u}^{(0)}} \, + \,
157  \left\langle \, \nabla _{u}{\cal J}^T |_{\vec{u}^{(0)}} \, , \, \delta \vec{u} \, \right\rangle  \left\langle \, \nabla _{u}{\cal J}^T |_{\vec{u}^{(0)}} \, , \, \delta \vec{u} \, \right\rangle
# Line 150  $\left\langle \,\, , \,\, \right\rangle Line 160  $\left\langle \,\, , \,\, \right\rangle
160  {\cal J} |_{\vec{v}^{(0)}} \, + \,  {\cal J} |_{\vec{v}^{(0)}} \, + \,
161  \left\langle \, \nabla _{v}{\cal J}^T |_{\vec{v}^{(0)}} \, , \, \delta \vec{v} \, \right\rangle  \left\langle \, \nabla _{v}{\cal J}^T |_{\vec{v}^{(0)}} \, , \, \delta \vec{v} \, \right\rangle
162  \, + \, O(\delta \vec{v}^2)  \, + \, O(\delta \vec{v}^2)
163  \end{split}  \end{aligned}
164  \label{deljidentity}  \label{deljidentity}
165  \end{equation}  \end{equation}
166  %  %
# Line 191  the gradient $ \nabla _{u}{\cal J} $ can Line 201  the gradient $ \nabla _{u}{\cal J} $ can
201  invoking the adjoint $ M^{\ast } $ of the tangent linear model $ M $  invoking the adjoint $ M^{\ast } $ of the tangent linear model $ M $
202  %  %
203  \begin{equation}  \begin{equation}
204  \begin{split}  \begin{aligned}
205  \nabla _{u}{\cal J}^T |_{\vec{u}} &  \nabla _{u}{\cal J}^T |_{\vec{u}} &
206  = \, M^T |_{\vec{u}} \cdot \nabla _{v}{\cal J}^T |_{\vec{v}}  \\  = \, M^T |_{\vec{u}} \cdot \nabla _{v}{\cal J}^T |_{\vec{v}}  \\
207  ~ & = \, M^T |_{\vec{u}} \cdot \delta \vec{v}^{\ast} \\  ~ & = \, M^T |_{\vec{u}} \cdot \delta \vec{v}^{\ast} \\
208  ~ & = \, \delta \vec{u}^{\ast}  ~ & = \, \delta \vec{u}^{\ast}
209  \end{split}  \end{aligned}
210  \label{adjoint}  \label{adjoint}
211  \end{equation}  \end{equation}
212  %  %
# Line 244  $ \langle \, \nabla _{v}{\cal J}^T \, , Line 254  $ \langle \, \nabla _{v}{\cal J}^T \, ,
254  = \nabla_v {\cal J} \cdot \delta \vec{v} $ )  = \nabla_v {\cal J} \cdot \delta \vec{v} $ )
255  %  %
256  \begin{equation}  \begin{equation}
257  \begin{split}  \begin{aligned}
258  \nabla_v {\cal J} (M(\delta \vec{u})) & = \,  \nabla_v {\cal J} (M(\delta \vec{u})) & = \,
259  \nabla_v {\cal J} \cdot M_{\Lambda}  \nabla_v {\cal J} \cdot M_{\Lambda}
260  \cdot ...... \cdot M_{\lambda} \cdot ...... \cdot  \cdot ...... \cdot M_{\lambda} \cdot ...... \cdot
261  M_{1} \cdot M_{0} \cdot \delta \vec{u} \\  M_{1} \cdot M_{0} \cdot \delta \vec{u} \\
262  ~ & = \, \nabla_v {\cal J} \cdot \delta \vec{v} \\  ~ & = \, \nabla_v {\cal J} \cdot \delta \vec{v} \\
263  \end{split}  \end{aligned}
264  \label{forward}  \label{forward}
265  \end{equation}  \end{equation}
266  %  %
# Line 258  whereas in reverse mode we have Line 268  whereas in reverse mode we have
268  %  %
269  \begin{equation}  \begin{equation}
270  \boxed{  \boxed{
271  \begin{split}  \begin{aligned}
272  M^T ( \nabla_v {\cal J}^T) & = \,  M^T ( \nabla_v {\cal J}^T) & = \,
273  M_{0}^T \cdot M_{1}^T  M_{0}^T \cdot M_{1}^T
274  \cdot ...... \cdot M_{\lambda}^T \cdot ...... \cdot  \cdot ...... \cdot M_{\lambda}^T \cdot ...... \cdot
# Line 267  M_{\Lambda}^T \cdot \nabla_v {\cal J}^T Line 277  M_{\Lambda}^T \cdot \nabla_v {\cal J}^T
277  \cdot ...... \cdot  \cdot ...... \cdot
278  \nabla_{v^{(\lambda)}} {\cal J}^T \\  \nabla_{v^{(\lambda)}} {\cal J}^T \\
279  ~ & = \, \nabla_u {\cal J}^T  ~ & = \, \nabla_u {\cal J}^T
280  \end{split}  \end{aligned}
281  }  }
282  \label{reverse}  \label{reverse}
283  \end{equation}  \end{equation}
# Line 286  $ \vec{v}^{(\lambda)} $ at each intermed Line 296  $ \vec{v}^{(\lambda)} $ at each intermed
296  %  %
297  \begin{equation}  \begin{equation}
298  \boxed{  \boxed{
299  \begin{split}  \begin{aligned}
300  \nabla_{v^{(\lambda)}} {\cal J}^T |_{\vec{v}^{(\lambda)}}  \nabla_{v^{(\lambda)}} {\cal J}^T |_{\vec{v}^{(\lambda)}}
301  & = \,  & = \,
302  M_{\lambda}^T |_{\vec{v}^{(\lambda)}} \cdot ...... \cdot  M_{\lambda}^T |_{\vec{v}^{(\lambda)}} \cdot ...... \cdot
303  M_{\Lambda}^T |_{\vec{v}^{(\lambda)}} \cdot \delta \vec{v}^{\ast} \\  M_{\Lambda}^T |_{\vec{v}^{(\lambda)}} \cdot \delta \vec{v}^{\ast} \\
304  ~ & = \, \delta \vec{v}^{(\lambda) \, \ast}  ~ & = \, \delta \vec{v}^{(\lambda) \, \ast}
305  \end{split}  \end{aligned}
306  }  }
307  \end{equation}  \end{equation}
308  %  %
# Line 409  and the shorthand notation for the adjoi Line 419  and the shorthand notation for the adjoi
419  $ \delta v^{(\lambda) \, \ast}_{j} = \frac{\partial}{\partial v^{(\lambda)}_{j}}  $ \delta v^{(\lambda) \, \ast}_{j} = \frac{\partial}{\partial v^{(\lambda)}_{j}}
420  {\cal J}^T $, $ j = 1, \ldots , n_{\lambda} $,  {\cal J}^T $, $ j = 1, \ldots , n_{\lambda} $,
421  for intermediate components, yielding  for intermediate components, yielding
422    {\small
423  \begin{equation}  \begin{equation}
424  \small  \begin{aligned}
 \begin{split}  
425  \left(  \left(
426  \begin{array}{c}  \begin{array}{c}
427  \delta v^{(\lambda) \, \ast}_1 \\  \delta v^{(\lambda) \, \ast}_1 \\
# Line 456  for intermediate components, yielding Line 466  for intermediate components, yielding
466  \delta v^{\ast}_{n} \\  \delta v^{\ast}_{n} \\
467  \end{array}  \end{array}
468  \right)  \right)
469  \end{split}  \end{aligned}
470  \end{equation}  \end{equation}
471    }
472    
473  Eq. (\ref{forward}) and (\ref{reverse}) are perhaps clearest in  Eq. (\ref{forward}) and (\ref{reverse}) are perhaps clearest in
474  showing the advantage of the reverse over the forward mode  showing the advantage of the reverse over the forward mode
# Line 528  operator which maps the model state spac Line 539  operator which maps the model state spac
539  Then, $ \nabla_v {\cal J} $ takes the form  Then, $ \nabla_v {\cal J} $ takes the form
540  %  %
541  \begin{equation*}  \begin{equation*}
542  \begin{split}  \begin{aligned}
543  \nabla_v {\cal J}^T & = \, 2 \, \, H \cdot  \nabla_v {\cal J}^T & = \, 2 \, \, H \cdot
544  \left( \, {\cal H}(\vec{v}) - \vec{d} \, \right) \\  \left( \, {\cal H}(\vec{v}) - \vec{d} \, \right) \\
545  ~          & = \, 2 \sum_{j} \left\{ \sum_k  ~          & = \, 2 \sum_{j} \left\{ \sum_k
546  \frac{\partial {\cal H}_k}{\partial v_{j}}  \frac{\partial {\cal H}_k}{\partial v_{j}}
547  \left( {\cal H}_k (\vec{v}) - d_k \right)  \left( {\cal H}_k (\vec{v}) - d_k \right)
548  \right\} \, {\vec{f}_{j}} \\  \right\} \, {\vec{f}_{j}} \\
549  \end{split}  \end{aligned}
550  \end{equation*}  \end{equation*}
551  %  %
552  where $H_{kj} = \partial {\cal H}_k / \partial v_{j} $ is the  where $H_{kj} = \partial {\cal H}_k / \partial v_{j} $ is the
# Line 654  $ n^{lev3}, \,\, n^{lev2}, \,\, n^{lev1} Line 665  $ n^{lev3}, \,\, n^{lev2}, \,\, n^{lev1}
665  %\psfrag{v_kn^lev2}{\mathinfigure{v_{k_{n}^{lev2}}}}  %\psfrag{v_kn^lev2}{\mathinfigure{v_{k_{n}^{lev2}}}}
666  %\psfrag{v_k1^lev1}{\mathinfigure{v_{k_{1}^{lev1}}}}  %\psfrag{v_k1^lev1}{\mathinfigure{v_{k_{1}^{lev1}}}}
667  %\psfrag{v_kn^lev1}{\mathinfigure{v_{k_{n}^{lev1}}}}  %\psfrag{v_kn^lev1}{\mathinfigure{v_{k_{n}^{lev1}}}}
668  %\mbox{\epsfig{file=part5/checkpointing.eps, width=0.8\textwidth}}  %\mbox{\epsfig{file=s_autodiff/figs/checkpointing.eps, width=0.8\textwidth}}
669  \resizebox{5.5in}{!}{\includegraphics{part5/checkpointing.eps}}  \resizebox{5.5in}{!}{\includegraphics{s_autodiff/figs/checkpointing.eps}}
670  %\psfull  %\psfull
671  \end{center}  \end{center}
672  \caption{  \caption{
# Line 676  Schematic view of intermediate dump and Line 687  Schematic view of intermediate dump and
687  %**********************************************************************  %**********************************************************************
688  \section{TLM and ADM generation in general}  \section{TLM and ADM generation in general}
689  \label{sec_ad_setup_gen}  \label{sec_ad_setup_gen}
690    \begin{rawhtml}
691    <!-- CMIREDIR:sec_ad_setup_gen: -->
692    \end{rawhtml}
693  %**********************************************************************  %**********************************************************************
694    
695  In this section we describe in a general fashion  In this section we describe in a general fashion
696  the parts of the code that are relevant for automatic  the parts of the code that are relevant for automatic
697  differentiation using the software tool TAMC.  differentiation using the software tool TAF.
698    Modifications to use OpenAD are described in \ref{sec_ad_openad}.
699    
700  \input{part5/doc_ad_the_model}  \input{s_autodiff/text/doc_ad_the_model}
701    
702  The basic flow is depicted in \ref{fig:adthemodel}.  The basic flow is depicted in \ref{fig:adthemodel}.
703  If the option {\tt ALLOW\_AUTODIFF\_TAMC} is defined, the driver routine  If CPP option \texttt{ALLOW\_AUTODIFF\_TAMC} is defined,
704    the driver routine
705  {\it the\_model\_main}, instead of calling {\it the\_main\_loop},  {\it the\_model\_main}, instead of calling {\it the\_main\_loop},
706  invokes the adjoint of this routine, {\it adthe\_main\_loop},  invokes the adjoint of this routine, {\it adthe\_main\_loop}
707  which is the toplevel routine in terms of reverse mode computation.  (case \texttt{\#define ALLOW\_ADJOINT\_RUN}), or
708  The routine {\it adthe\_main\_loop} has been generated by TAMC.  the tangent linear of this routine {\it g\_the\_main\_loop}
709  It contains both the forward integration of the full model,  (case \texttt{\#define ALLOW\_TANGENTLINEAR\_RUN}),
710    which are the toplevel routines in terms of automatic differentiation.
711    The routines {\it adthe\_main\_loop} or {\it g\_the\_main\_loop}
712    are generated by TAF.
713    It contains both the forward integration of the full model, the
714    cost function calculation,
715  any additional storing that is required for efficient checkpointing,  any additional storing that is required for efficient checkpointing,
716  and the reverse integration of the adjoint model.  and the reverse integration of the adjoint model.
717  The structure of {\it adthe\_main\_loop} has been strongly  
718  simplified for clarification; in particular, no checkpointing  [DESCRIBE IN A SEPARATE SECTION THE WORKING OF THE TLM]
719    
720    In Fig. \ref{fig:adthemodel}
721    the structure of {\it adthe\_main\_loop} has been strongly
722    simplified to focus on the essentials; in particular, no checkpointing
723  procedures are shown here.  procedures are shown here.
724  Prior to the call of {\it adthe\_main\_loop}, the routine  Prior to the call of {\it adthe\_main\_loop}, the routine
725  {\it ctrl\_unpack} is invoked to unpack the control vector  {\it ctrl\_unpack} is invoked to unpack the control vector
# Line 707  If gradient checks are to be performed, Line 732  If gradient checks are to be performed,
732  {\tt ALLOW\_GRADIENT\_CHECK} is defined. In this case  {\tt ALLOW\_GRADIENT\_CHECK} is defined. In this case
733  the driver routine {\it grdchk\_main} is called after  the driver routine {\it grdchk\_main} is called after
734  the gradient has been computed via the adjoint  the gradient has been computed via the adjoint
735  (cf. Section \ref{section_grdchk}).  (cf. Section \ref{sec:ad_gradient_check}).
736    
737    %------------------------------------------------------------------
738    
739    \subsection{General setup
740    \label{section_ad_setup}}
741    
742    In order to configure AD-related setups the following packages need
743    to be enabled:
744    {\it
745    \begin{table}[!ht]
746    \begin{tabular}{l}
747    autodiff \\
748    ctrl \\
749    cost \\
750    grdchk \\
751    \end{tabular}
752    \end{table}
753    }
754    The packages are enabled by adding them to your experiment-specific
755    configuration file
756    {\it packages.conf} (see Section ???).
757    
758    The following AD-specific CPP option files need to be customized:
759    %
760    \begin{itemize}
761    %
762    \item {\it ECCO\_CPPOPTIONS.h} \\
763    This header file collects CPP options for the packages
764    {\it autodiff, cost, ctrl} as well as AD-unrelated options for
765    the external forcing package {\it exf}.
766    \footnote{NOTE: These options are not set in their package-specific
767    headers such as {\it COST\_CPPOPTIONS.h}, but are instead collected
768    in the single header file {\it ECCO\_CPPOPTIONS.h}.
769    The package-specific header files serve as simple
770    placeholders at this point.}
771    %
772    \item {\it tamc.h} \\
773    This header configures the splitting of the time stepping loop
774    w.r.t. the 3-level checkpointing (see section ???).
775    
776    %
777    \end{itemize}
778    
779    %------------------------------------------------------------------
780    
781    \subsection{Building the AD code using TAF
782    \label{section_ad_build}}
783    
784    The build process of an AD code is very similar to building
785    the forward model. However, depending on which AD code one wishes
786    to generate, and on which AD tool is available (TAF or TAMC),
787    the following {\tt make} targets are available:
788    
789    \begin{table}[!ht]
790    {\footnotesize
791    \begin{tabular}{|ccll|}
792    \hline
793    ~ & {\it AD-target} & {\it output} & {\it description} \\
794    \hline
795    \hline
796    (1) & {\tt <MODE><TOOL>only} & {\tt <MODE>\_<TOOL>\_output.f}  &
797    generates code for $<$MODE$>$ using $<$TOOL$>$ \\
798    ~ & ~ & ~ & no {\tt make} dependencies on {\tt .F .h} \\
799    ~ & ~ & ~ & useful for compiling on remote platforms \\
800    \hline
801    (2) & {\tt <MODE><TOOL>} & {\tt <MODE>\_<TOOL>\_output.f}  &
802    generates code for $<$MODE$>$ using $<$TOOL$>$ \\
803    ~ & ~ & ~ & includes {\tt make} dependencies on {\tt .F .h} \\
804    ~ & ~ & ~ & i.e. input for $<$TOOL$>$ may be re-generated \\
805    \hline
806    (3) & {\tt <MODE>all} & {\tt mitgcmuv\_<MODE>}  &
807    generates code for $<$MODE$>$ using $<$TOOL$>$ \\
808    ~ & ~ & ~ & and compiles all code \\
809    ~ & ~ & ~ & (use of TAF is set as default) \\
810    \hline
811    \end{tabular}
812    }
813    \end{table}
814    %
815    Here, the following placeholders are used
816    %
817    \begin{itemize}
818    %
819    \item $<$TOOL$>$
820    %
821    \begin{itemize}
822    %
823    \item {\tt TAF}
824    \item {\tt TAMC}
825    %
826    \end{itemize}
827    %
828    \item $<$MODE$>$
829    %
830    \begin{itemize}
831    %
832    \item {\tt ad} generates the adjoint model (ADM)
833    \item {\tt ftl} generates the tangent linear model (TLM)
834    \item {\tt svd} generates both ADM and TLM for \\
835    singular value decomposition (SVD) type calculations
836    %
837    \end{itemize}
838    %
839    \end{itemize}
840    
841    For example, to generate the adjoint model using TAF after routines ({\tt .F})
842    or headers ({\tt .h}) have been modified, but without compilation,
843    type {\tt make adtaf};
844    or, to generate the tangent linear model using TAMC without
845    re-generating the input code, type {\tt make ftltamconly}.
846    
847    
848    A typical full build process to generate the ADM via TAF would
849    look like follows:
850    \begin{verbatim}
851    % mkdir build
852    % cd build
853    % ../../../tools/genmake2 -mods=../code_ad
854    % make depend
855    % make adall
856    \end{verbatim}
857    
858    %------------------------------------------------------------------
859    
860    \subsection{The AD build process in detail
861    \label{section_ad_build_detail}}
862    
863    The {\tt make <MODE>all} target consists of the following procedures:
864    
865    \begin{enumerate}
866    %
867    \item
868    A header file {\tt AD\_CONFIG.h} is generated which contains a CPP option
869    on which code ought to be generated. Depending on the {\tt make} target,
870    the contents is one of the following:
871    \begin{itemize}
872    \item
873    {\tt \#define ALLOW\_ADJOINT\_RUN}
874    \item
875    {\tt \#define ALLOW\_TANGENTLINEAR\_RUN}
876    \item
877    {\tt \#define ALLOW\_ECCO\_OPTIMIZATION}
878    \end{itemize}
879    %
880    \item
881    A single file {\tt <MODE>\_input\_code.f} is concatenated
882    consisting of all {\tt .f} files that are part of the list {\bf AD\_FILES}
883    and all {\tt .flow} files that are part of the list {\bf AD\_FLOW\_FILES}.
884    %
885    \item
886    The AD tool is invoked with the {\tt <MODE>\_<TOOL>\_FLAGS}.
887    The default AD tool flags in {\tt genmake2} can be overrwritten by
888    an {\tt adjoint\_options} file (similar to the platform-specific
889    {\tt build\_options}, see Section ???.
890    The AD tool writes the resulting AD code into the file
891    {\tt <MODE>\_input\_code\_ad.f}
892    %
893    \item
894    A short sed script {\tt adjoint\_sed} is applied to
895    {\tt <MODE>\_input\_code\_ad.f}
896    to reinstate {\bf myThid} into the CALL argument list of active file I/O.
897    The result is written to file {\tt <MODE>\_<TOOL>\_output.f}.
898    %
899    \item
900    All routines are compiled and an executable is generated
901    (see Table ???).
902    %
903    \end{enumerate}
904    
905    \subsubsection{The list AD\_FILES and {\tt .list} files}
906    
907    Not all routines are presented to the AD tool.
908    Routines typically hidden are diagnostics routines which
909    do not influence the cost function, but may create
910    artificial flow dependencies such as I/O of active variables.
911    
912    {\tt genmake2} generates a list (or variable) {\bf AD\_FILES}
913    which contains all routines that are shown to the AD tool.
914    This list is put together from all files with suffix {\tt .list}
915    that {\tt genmake2} finds in its search directories.
916    The list file for the core MITgcm routines is in {\tt model/src/}
917    is called {\tt model\_ad\_diff.list}.
918    Note that no wrapper routine is shown to TAF. These are either
919    not visible at all to the AD code, or hand-written AD code
920    is available (see next section).
921    
922    Each package directory contains its package-specific
923    list file {\tt <PKG>\_ad\_diff.list}. For example,
924    {\tt pkg/ptracers/} contains the file {\tt ptracers\_ad\_diff.list}.
925    Thus, enabling a package will automatically extend the
926    {\bf AD\_FILES} list of {\tt genmake2} to incorporate the
927    package-specific routines.
928    Note that you will need to regenerate the {\tt Makefile} if
929    you enable a package (e.g. by adding it to {\tt packages.conf})
930    and a {\tt Makefile} already exists.
931    
932    \subsubsection{The list AD\_FLOW\_FILES and {\tt .flow} files}
933    
934    TAMC and TAF can evaluate user-specified directives
935    that start with a specific syntax ({\tt CADJ}, {\tt C\$TAF}, {\tt !\$TAF}).
936    The main categories of directives are STORE directives and
937    FLOW directives. Here, we are concerned with flow directives,
938    store directives are treated elsewhere.
939    
940    Flow directives enable the AD tool to evaluate how it should treat
941    routines that are 'hidden' by the user, i.e. routines which are
942    not contained in the {\bf AD\_FILES} list (see previous section),
943    but which are called in part of the code that the AD tool does see.
944    The flow directive tell the AD tool
945    %
946    \begin{itemize}
947    %
948    \item which subroutine arguments are input/output
949    \item which subroutine arguments are active
950    \item which subroutine arguments are required to compute the cost
951    \item which subroutine arguments are dependent
952    %
953    \end{itemize}
954    %
955    The syntax for the flow directives can be found in the
956    AD tool manuals.
957    
958    {\tt genmake2} generates a list (or variable) {\bf AD\_FLOW\_FILES}
959    which contains all files with suffix{\tt .flow} that it finds
960    in its search directories.
961    The flow directives for the core MITgcm routines of
962    {\tt eesupp/src/} and {\tt model/src/}
963    reside in {\tt pkg/autodiff/}.
964    This directory also contains hand-written adjoint code
965    for the MITgcm WRAPPER (section \ref{chap:sarch}).
966    
967    Flow directives for package-specific routines are contained in
968    the corresponding package directories in the file
969    {\tt <PKG>\_ad.flow}, e.g. ptracers-specific directives are in
970    {\tt ptracers\_ad.flow}.
971    
972    \subsubsection{Store directives for 3-level checkpointing}
973    
974    The storing that is required at each period of the
975    3-level checkpointing is controled by three
976    top-level headers.
977    
978    \begin{verbatim}
979    do ilev_3 = 1, nchklev_3
980    #  include ``checkpoint_lev3.h''
981       do ilev_2 = 1, nchklev_2
982    #     include ``checkpoint_lev2.h''
983          do ilev_1 = 1, nchklev_1
984    #        include ``checkpoint_lev1.h''
985    
986    ...
987    
988          end do
989       end do
990    end do
991    \end{verbatim}
992    
993    All files {\tt checkpoint\_lev?.h} are contained in directory
994    {\tt pkg/autodiff/}.
995    
996    
997    \subsubsection{Changing the default AD tool flags: ad\_options files}
998    
999    
1000    \subsubsection{Hand-written adjoint code}
1001    
1002    %------------------------------------------------------------------
1003    
1004  \subsection{The cost function (dependent variable)  \subsection{The cost function (dependent variable)
1005  \label{section_cost}}  \label{section_cost}}
# Line 724  The aspects relevant to the treatment of Line 1016  The aspects relevant to the treatment of
1016  are controlled by the package {\it pkg/ctrl} and will be treated  are controlled by the package {\it pkg/ctrl} and will be treated
1017  in the next section.  in the next section.
1018    
1019  \input{part5/doc_cost_flow}  \input{s_autodiff/text/doc_cost_flow}
1020    
1021    \subsubsection{Enabling the package}
1022    
 \subsubsection{genmake and CPP options}  
 %  
 \begin{itemize}  
 %  
 \item  
1023  \fbox{  \fbox{
1024  \begin{minipage}{12cm}  \begin{minipage}{12cm}
1025  {\it genmake}, {\it CPP\_OPTIONS.h}, {\it ECCO\_CPPOPTIONS.h}  {\it packages.conf}, {\it ECCO\_CPPOPTIONS.h}
1026  \end{minipage}  \end{minipage}
1027  }  }
1028  \end{itemize}  \begin{itemize}
 %  
 The directory {\it pkg/cost} can be included to the  
 compile list in 3 different ways (cf. Section \ref{???}):  
1029  %  %
1030  \begin{enumerate}  \item
1031    The package is enabled by adding {\it cost} to your file {\it packages.conf}
1032    (see Section ???)
1033  %  %
1034  \item {\it genmake}: \\  \item
1035  Change the default settings in the file {\it genmake} by adding  
1036  {\bf cost} to the {\bf enable} list (not recommended).  
1037  %  \end{itemize}
 \item {\it .genmakerc}: \\  
 Customize the settings of {\bf enable}, {\bf disable} which are  
 appropriate for your experiment in the file {\it .genmakerc}  
 and add the file to your compile directory.  
 %  
 \item genmake-options: \\  
 Call {\it genmake} with the option  
 {\tt genmake -enable=cost}.  
1038  %  %
1039  \end{enumerate}  
1040  N.B.: In general the following packages ought to be enabled  N.B.: In general the following packages ought to be enabled
1041  simultaneously: {\it autodiff, cost, ctrl}.  simultaneously: {\it autodiff, cost, ctrl}.
1042  The basic CPP option to enable the cost function is {\bf ALLOW\_COST}.  The basic CPP option to enable the cost function is {\bf ALLOW\_COST}.
# Line 826  Within this 'driver' routine, S/R are ca Line 1106  Within this 'driver' routine, S/R are ca
1106  the chosen cost function contributions.  the chosen cost function contributions.
1107  In the present example ({\bf ALLOW\_COST\_TRACER}),  In the present example ({\bf ALLOW\_COST\_TRACER}),
1108  S/R {\it cost\_tracer} is called.  S/R {\it cost\_tracer} is called.
1109  It accumulates {\bf objf\_tracer} according to eqn. (\ref{???}).  It accumulates {\bf objf\_tracer} according to eqn. (\ref{ask_the_author:doc_ad_2}).
1110  %  %
1111  \subsubsection{Finalize all contributions}  \subsubsection{Finalize all contributions}
1112  %  %
# Line 851  from each contribution and sums over all Line 1131  from each contribution and sums over all
1131  \end{equation}  \end{equation}
1132  %  %
1133  The total cost function {\bf fc} will be the  The total cost function {\bf fc} will be the
1134  'dependent' variable in the argument list for TAMC, i.e.  'dependent' variable in the argument list for TAF, i.e.
1135  \begin{verbatim}  \begin{verbatim}
1136  tamc -output 'fc' ...  taf -output 'fc' ...
1137  \end{verbatim}  \end{verbatim}
1138    
1139  %%%% \end{document}  %%%% \end{document}
1140    
1141  \input{part5/doc_ad_the_main}  \input{s_autodiff/text/doc_ad_the_main}
1142    
1143  \subsection{The control variables (independent variables)  \subsection{The control variables (independent variables)
1144  \label{section_ctrl}}  \label{section_ctrl}}
# Line 878  All aspects relevant to the treatment of Line 1158  All aspects relevant to the treatment of
1158  (parameter setting, initialization, perturbation)  (parameter setting, initialization, perturbation)
1159  are controlled by the package {\it pkg/ctrl}.  are controlled by the package {\it pkg/ctrl}.
1160    
1161  \input{part5/doc_ctrl_flow}  \input{s_autodiff/text/doc_ctrl_flow}
1162    
1163  \subsubsection{genmake and CPP options}  \subsubsection{genmake and CPP options}
1164  %  %
# Line 936  and their gradients: {\it ctrl\_unpack} Line 1216  and their gradients: {\it ctrl\_unpack}
1216  \\  \\
1217  %  %
1218  Two important issues related to the handling of the control  Two important issues related to the handling of the control
1219  variables in the MITGCM need to be addressed.  variables in MITgcm need to be addressed.
1220  First, in order to save memory, the control variable arrays  First, in order to save memory, the control variable arrays
1221  are not kept in memory, but rather read from file and added  are not kept in memory, but rather read from file and added
1222  to the initial fields during the model initialization phase.  to the initial fields during the model initialization phase.
# Line 968  and gradient are generated and initialis Line 1248  and gradient are generated and initialis
1248  %  %
1249  The dependency flow for differentiation w.r.t. the controls  The dependency flow for differentiation w.r.t. the controls
1250  starts with adding a perturbation onto the input variable,  starts with adding a perturbation onto the input variable,
1251  thus defining the independent or control variables for TAMC.  thus defining the independent or control variables for TAF.
1252  Three types of controls may be considered:  Three types of controls may be considered:
1253  %  %
1254  \begin{itemize}  \begin{itemize}
# Line 989  temperature and salinity are initialised Line 1269  temperature and salinity are initialised
1269  a perturbation anomaly is added to the field in S/R  a perturbation anomaly is added to the field in S/R
1270  {\it ctrl\_map\_ini}  {\it ctrl\_map\_ini}
1271  %  %
1272    %\begin{eqnarray}
1273  \begin{equation}  \begin{equation}
1274  \begin{split}  \begin{aligned}
1275  u         & = \, u_{[0]} \, + \, \Delta u \\  u         & = \, u_{[0]} \, + \, \Delta u \\
1276  {\bf tr1}(...) & = \, {\bf tr1_{ini}}(...) \, + \, {\bf xx\_tr1}(...)  {\bf tr1}(...) & = \, {\bf tr1_{ini}}(...) \, + \, {\bf xx\_tr1}(...)
1277  \label{perturb}  \label{perturb}
1278  \end{split}  \end{aligned}
1279  \end{equation}  \end{equation}
1280    %\end{eqnarray}
1281  %  %
1282  {\bf xx\_tr1} is a 3-dim. global array  {\bf xx\_tr1} is a 3-dim. global array
1283  holding the perturbation. In the case of a simple  holding the perturbation. In the case of a simple
1284  sensitivity study this array is identical to zero.  sensitivity study this array is identical to zero.
1285  However, it's specification is essential in the context  However, it's specification is essential in the context
1286  of automatic differentiation since TAMC  of automatic differentiation since TAF
1287  treats the corresponding line in the code symbolically  treats the corresponding line in the code symbolically
1288  when determining the differentiation chain and its origin.  when determining the differentiation chain and its origin.
1289  Thus, the variable names are part of the argument list  Thus, the variable names are part of the argument list
1290  when calling TAMC:  when calling TAF:
1291  %  %
1292  \begin{verbatim}  \begin{verbatim}
1293  tamc -input 'xx_tr1 ...' ...  taf -input 'xx_tr1 ...' ...
1294  \end{verbatim}  \end{verbatim}
1295  %  %
1296  Now, as mentioned above, the MITGCM avoids maintaining  Now, as mentioned above, MITgcm avoids maintaining
1297  an array for each control variable by reading the  an array for each control variable by reading the
1298  perturbation to a temporary array from file.  perturbation to a temporary array from file.
1299  To ensure the symbolic link to be recognized by TAMC, a scalar  To ensure the symbolic link to be recognized by TAF, a scalar
1300  dummy variable {\bf xx\_tr1\_dummy} is introduced  dummy variable {\bf xx\_tr1\_dummy} is introduced
1301  and an 'active read' routine of the adjoint support  and an 'active read' routine of the adjoint support
1302  package {\it pkg/autodiff} is invoked.  package {\it pkg/autodiff} is invoked.
1303  The read-procedure is tagged with the variable  The read-procedure is tagged with the variable
1304  {\bf xx\_tr1\_dummy} enabling TAMC to recognize the  {\bf xx\_tr1\_dummy} enabling TAF to recognize the
1305  initialization of the perturbation.  initialization of the perturbation.
1306  The modified call of TAMC thus reads  The modified call of TAF thus reads
1307  %  %
1308  \begin{verbatim}  \begin{verbatim}
1309  tamc -input 'xx_tr1_dummy ...' ...  taf -input 'xx_tr1_dummy ...' ...
1310  \end{verbatim}  \end{verbatim}
1311  %  %
1312  and the modified operation to (\ref{perturb})  and the modified operation to (\ref{perturb})
# Line 1221  u_{[k+1]} \, = \,  u_{[0]} \, + \, \Delt Line 1503  u_{[k+1]} \, = \,  u_{[0]} \, + \, \Delt
1503  $ u_{[k+1]} $ then serves as input for a forward/adjoint run  $ u_{[k+1]} $ then serves as input for a forward/adjoint run
1504  to determine $ {\cal J} $ and $ \nabla _{u}{\cal J} $ at iteration step  to determine $ {\cal J} $ and $ \nabla _{u}{\cal J} $ at iteration step
1505  $ k+1 $.  $ k+1 $.
1506  Tab. \ref{???} sketches the flow between forward/adjoint model  Tab. \ref{ask_the_author:doc_ad_2} sketches the flow between forward/adjoint model
1507  and the minimization routine.  and the minimization routine.
1508    
1509    {\scriptsize
1510  \begin{eqnarray*}  \begin{eqnarray*}
 \scriptsize  
1511  \begin{array}{ccccc}  \begin{array}{ccccc}
1512  u_{[0]} \,\, ,  \,\, \Delta u_{[k]}    & ~ & ~ & ~ & ~ \\  u_{[0]} \,\, ,  \,\, \Delta u_{[k]}    & ~ & ~ & ~ & ~ \\
1513  {\Big\downarrow}  {\Big\downarrow}
# Line 1276  ad \, v_{[k]} (\delta {\cal J}) = Line 1558  ad \, v_{[k]} (\delta {\cal J}) =
1558   ~ & ~ & ~ & ~ & \Delta u_{[k+1]} \\   ~ & ~ & ~ & ~ & \Delta u_{[k+1]} \\
1559  \end{array}  \end{array}
1560  \end{eqnarray*}  \end{eqnarray*}
1561    }
1562    
1563  The routines {\it ctrl\_unpack} and {\it ctrl\_pack} provide  The routines {\it ctrl\_unpack} and {\it ctrl\_pack} provide
1564  the link between the model and the minimization routine.  the link between the model and the minimization routine.
1565  As described in Section \ref{???}  As described in Section \ref{ask_the_author:doc_ad_2}
1566  the {\it unpack} and {\it pack} routines read and write  the {\it unpack} and {\it pack} routines read and write
1567  control and gradient {\it vectors} which are compressed  control and gradient {\it vectors} which are compressed
1568  to contain only wet points, in addition to the full  to contain only wet points, in addition to the full
Legend:
Removed from v.1.15  
changed lines
  Added in v.1.23
  ViewVC Help
Powered by ViewVC 1.1.22