/[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.14 by cnh, Thu Feb 28 19:32:20 2002 UTC revision 1.24 by jmc, Tue Aug 31 20:56:21 2010 UTC
# Line 1  Line 1 
1  % $Header$  % $Header$
2  % $Name$  % $Name$
3    
4    Author: Patrick Heimbach
5    
6  {\sf Automatic differentiation} (AD), also referred to as algorithmic  {\sf Automatic differentiation} (AD), also referred to as algorithmic
7  (or, more loosely, computational) differentiation, involves  (or, more loosely, computational) differentiation, involves
8  automatically deriving code to calculate  automatically deriving code to calculate partial derivatives from an
9  partial derivatives from an existing fully non-linear prognostic code.  existing fully non-linear prognostic code.  (see \cite{gri:00}).  A
10  (see \cite{gri:00}).  software tool is used that parses and transforms source files
11  A software tool is used that parses and transforms source files  according to a set of linguistic and mathematical rules.  AD tools are
12  according to a set of linguistic and mathematical rules.  like source-to-source translators in that they parse a program code as
13  AD tools are like source-to-source translators in that  input and produce a new program code as output
14  they parse a program code as input and produce a new program code  (we restrict our discussion to source-to-source tools, ignoring
15  as output.  operator-overloading tools).  However, unlike a
16  However, unlike a pure source-to-source translation, the output program  pure source-to-source translation, the output program represents a new
17  represents a new algorithm, such as the evaluation of the  algorithm, such as the evaluation of the Jacobian, the Hessian, or
18  Jacobian, the Hessian, or higher derivative operators.  higher derivative operators.  In principle, a variety of derived
19  In principle, a variety of derived algorithms  algorithms can be generated automatically in this way.
20  can be generated automatically in this way.  
21    MITgcm has been adapted for use with the Tangent linear and Adjoint
22  The MITGCM has been adapted for use with the  Model Compiler (TAMC) and its successor TAF (Transformation of
23  Tangent linear and Adjoint Model Compiler (TAMC) and its successor TAF  Algorithms in Fortran), developed by Ralf Giering (\cite{gie-kam:98},
24  (Transformation of Algorithms in Fortran), developed  \cite{gie:99,gie:00}).  The first application of the adjoint of MITgcm
25  by Ralf Giering (\cite{gie-kam:98}, \cite{gie:99,gie:00}).  for sensitivity studies has been published by \cite{maro-eta:99}.
26  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
27  studies has been published by \cite{maro-eta:99}.  state estimation studies.  In the following we shall refer to TAMC and
28  \cite{sta-eta:97,sta-eta:01} use the MITGCM and its adjoint  TAF synonymously, except were explicitly stated otherwise.
29  for ocean state estimation studies.  
30  In the following we shall refer to TAMC and TAF synonymously,  As of mid-2007 we are also able to generate fairly efficient
31  except were explicitly stated otherwise.  adjoint code of the MITgcm using a new, open-source AD tool,
32    called OpenAD (see \cite{naum-etal:06,utke-etal:08}.
33  TAMC exploits the chain rule for computing the first  This enables us for the first time to compare adjoint models
34  derivative of a function with  generated from different AD tools, providing an additional
35  respect to a set of input variables.  accuracy check, complementary to finite-difference gradient checks.
36  Treating a given forward code as a composition of operations --  OpenAD and its application to  MITgcm is described in detail
37  each line representing a compositional element, the chain rule is  in section \ref{sec_ad_openad}.
38  rigorously applied to the code, line by line. The resulting  
39  tangent linear or adjoint code,  The AD tool exploits the chain rule for computing the first derivative of a
40  then, may be thought of as the composition in  function with respect to a set of input variables.  Treating a given
41  forward or reverse order, respectively, of the  forward code as a composition of operations -- each line representing
42  Jacobian matrices of the forward code's compositional elements.  a compositional element, the chain rule is rigorously applied to the
43    code, line by line. The resulting tangent linear or adjoint code,
44    then, may be thought of as the composition in forward or reverse
45    order, respectively, of the Jacobian matrices of the forward code's
46    compositional elements.
47    
48  %**********************************************************************  %**********************************************************************
49  \section{Some basic algebra}  \section{Some basic algebra}
50  \label{sec_ad_algebra}  \label{sec_ad_algebra}
51    \begin{rawhtml}
52    <!-- CMIREDIR:sec_ad_algebra: -->
53    \end{rawhtml}
54  %**********************************************************************  %**********************************************************************
55    
56  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 65  model output variable $\vec{v}=(v_1,\ldo
65  under consideration,  under consideration,
66  %  %
67  \begin{equation}  \begin{equation}
68  \begin{split}  \begin{aligned}
69  {\cal M} \, : & \, U \,\, \longrightarrow \, V \\  {\cal M} \, : & \, U \,\, \longrightarrow \, V \\
70  ~      & \, \vec{u} \,\, \longmapsto \, \vec{v} \, = \,  ~      & \, \vec{u} \,\, \longmapsto \, \vec{v} \, = \,
71  {\cal M}(\vec{u})  {\cal M}(\vec{u})
72  \label{fulloperator}  \label{fulloperator}
73  \end{split}  \end{aligned}
74  \end{equation}  \end{equation}
75  %  %
76  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 150  w.r.t. their corresponding inner product
150  $\left\langle \,\, , \,\, \right\rangle $  $\left\langle \,\, , \,\, \right\rangle $
151  %  %
152  \begin{equation}  \begin{equation}
153  \begin{split}  \begin{aligned}
154  {\cal J} & = \,  {\cal J} & = \,
155  {\cal J} |_{\vec{u}^{(0)}} \, + \,  {\cal J} |_{\vec{u}^{(0)}} \, + \,
156  \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 159  $\left\langle \,\, , \,\, \right\rangle
159  {\cal J} |_{\vec{v}^{(0)}} \, + \,  {\cal J} |_{\vec{v}^{(0)}} \, + \,
160  \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
161  \, + \, O(\delta \vec{v}^2)  \, + \, O(\delta \vec{v}^2)
162  \end{split}  \end{aligned}
163  \label{deljidentity}  \label{deljidentity}
164  \end{equation}  \end{equation}
165  %  %
# Line 191  the gradient $ \nabla _{u}{\cal J} $ can Line 200  the gradient $ \nabla _{u}{\cal J} $ can
200  invoking the adjoint $ M^{\ast } $ of the tangent linear model $ M $  invoking the adjoint $ M^{\ast } $ of the tangent linear model $ M $
201  %  %
202  \begin{equation}  \begin{equation}
203  \begin{split}  \begin{aligned}
204  \nabla _{u}{\cal J}^T |_{\vec{u}} &  \nabla _{u}{\cal J}^T |_{\vec{u}} &
205  = \, M^T |_{\vec{u}} \cdot \nabla _{v}{\cal J}^T |_{\vec{v}}  \\  = \, M^T |_{\vec{u}} \cdot \nabla _{v}{\cal J}^T |_{\vec{v}}  \\
206  ~ & = \, M^T |_{\vec{u}} \cdot \delta \vec{v}^{\ast} \\  ~ & = \, M^T |_{\vec{u}} \cdot \delta \vec{v}^{\ast} \\
207  ~ & = \, \delta \vec{u}^{\ast}  ~ & = \, \delta \vec{u}^{\ast}
208  \end{split}  \end{aligned}
209  \label{adjoint}  \label{adjoint}
210  \end{equation}  \end{equation}
211  %  %
# Line 244  $ \langle \, \nabla _{v}{\cal J}^T \, , Line 253  $ \langle \, \nabla _{v}{\cal J}^T \, ,
253  = \nabla_v {\cal J} \cdot \delta \vec{v} $ )  = \nabla_v {\cal J} \cdot \delta \vec{v} $ )
254  %  %
255  \begin{equation}  \begin{equation}
256  \begin{split}  \begin{aligned}
257  \nabla_v {\cal J} (M(\delta \vec{u})) & = \,  \nabla_v {\cal J} (M(\delta \vec{u})) & = \,
258  \nabla_v {\cal J} \cdot M_{\Lambda}  \nabla_v {\cal J} \cdot M_{\Lambda}
259  \cdot ...... \cdot M_{\lambda} \cdot ...... \cdot  \cdot ...... \cdot M_{\lambda} \cdot ...... \cdot
260  M_{1} \cdot M_{0} \cdot \delta \vec{u} \\  M_{1} \cdot M_{0} \cdot \delta \vec{u} \\
261  ~ & = \, \nabla_v {\cal J} \cdot \delta \vec{v} \\  ~ & = \, \nabla_v {\cal J} \cdot \delta \vec{v} \\
262  \end{split}  \end{aligned}
263  \label{forward}  \label{forward}
264  \end{equation}  \end{equation}
265  %  %
# Line 258  whereas in reverse mode we have Line 267  whereas in reverse mode we have
267  %  %
268  \begin{equation}  \begin{equation}
269  \boxed{  \boxed{
270  \begin{split}  \begin{aligned}
271  M^T ( \nabla_v {\cal J}^T) & = \,  M^T ( \nabla_v {\cal J}^T) & = \,
272  M_{0}^T \cdot M_{1}^T  M_{0}^T \cdot M_{1}^T
273  \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 276  M_{\Lambda}^T \cdot \nabla_v {\cal J}^T
276  \cdot ...... \cdot  \cdot ...... \cdot
277  \nabla_{v^{(\lambda)}} {\cal J}^T \\  \nabla_{v^{(\lambda)}} {\cal J}^T \\
278  ~ & = \, \nabla_u {\cal J}^T  ~ & = \, \nabla_u {\cal J}^T
279  \end{split}  \end{aligned}
280  }  }
281  \label{reverse}  \label{reverse}
282  \end{equation}  \end{equation}
# Line 286  $ \vec{v}^{(\lambda)} $ at each intermed Line 295  $ \vec{v}^{(\lambda)} $ at each intermed
295  %  %
296  \begin{equation}  \begin{equation}
297  \boxed{  \boxed{
298  \begin{split}  \begin{aligned}
299  \nabla_{v^{(\lambda)}} {\cal J}^T |_{\vec{v}^{(\lambda)}}  \nabla_{v^{(\lambda)}} {\cal J}^T |_{\vec{v}^{(\lambda)}}
300  & = \,  & = \,
301  M_{\lambda}^T |_{\vec{v}^{(\lambda)}} \cdot ...... \cdot  M_{\lambda}^T |_{\vec{v}^{(\lambda)}} \cdot ...... \cdot
302  M_{\Lambda}^T |_{\vec{v}^{(\lambda)}} \cdot \delta \vec{v}^{\ast} \\  M_{\Lambda}^T |_{\vec{v}^{(\lambda)}} \cdot \delta \vec{v}^{\ast} \\
303  ~ & = \, \delta \vec{v}^{(\lambda) \, \ast}  ~ & = \, \delta \vec{v}^{(\lambda) \, \ast}
304  \end{split}  \end{aligned}
305  }  }
306  \end{equation}  \end{equation}
307  %  %
# Line 409  and the shorthand notation for the adjoi Line 418  and the shorthand notation for the adjoi
418  $ \delta v^{(\lambda) \, \ast}_{j} = \frac{\partial}{\partial v^{(\lambda)}_{j}}  $ \delta v^{(\lambda) \, \ast}_{j} = \frac{\partial}{\partial v^{(\lambda)}_{j}}
419  {\cal J}^T $, $ j = 1, \ldots , n_{\lambda} $,  {\cal J}^T $, $ j = 1, \ldots , n_{\lambda} $,
420  for intermediate components, yielding  for intermediate components, yielding
421    {\small
422  \begin{equation}  \begin{equation}
423  \small  \begin{aligned}
 \begin{split}  
424  \left(  \left(
425  \begin{array}{c}  \begin{array}{c}
426  \delta v^{(\lambda) \, \ast}_1 \\  \delta v^{(\lambda) \, \ast}_1 \\
# Line 456  for intermediate components, yielding Line 465  for intermediate components, yielding
465  \delta v^{\ast}_{n} \\  \delta v^{\ast}_{n} \\
466  \end{array}  \end{array}
467  \right)  \right)
468  \end{split}  \end{aligned}
469  \end{equation}  \end{equation}
470    }
471    
472  Eq. (\ref{forward}) and (\ref{reverse}) are perhaps clearest in  Eq. (\ref{forward}) and (\ref{reverse}) are perhaps clearest in
473  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 538  operator which maps the model state spac
538  Then, $ \nabla_v {\cal J} $ takes the form  Then, $ \nabla_v {\cal J} $ takes the form
539  %  %
540  \begin{equation*}  \begin{equation*}
541  \begin{split}  \begin{aligned}
542  \nabla_v {\cal J}^T & = \, 2 \, \, H \cdot  \nabla_v {\cal J}^T & = \, 2 \, \, H \cdot
543  \left( \, {\cal H}(\vec{v}) - \vec{d} \, \right) \\  \left( \, {\cal H}(\vec{v}) - \vec{d} \, \right) \\
544  ~          & = \, 2 \sum_{j} \left\{ \sum_k  ~          & = \, 2 \sum_{j} \left\{ \sum_k
545  \frac{\partial {\cal H}_k}{\partial v_{j}}  \frac{\partial {\cal H}_k}{\partial v_{j}}
546  \left( {\cal H}_k (\vec{v}) - d_k \right)  \left( {\cal H}_k (\vec{v}) - d_k \right)
547  \right\} \, {\vec{f}_{j}} \\  \right\} \, {\vec{f}_{j}} \\
548  \end{split}  \end{aligned}
549  \end{equation*}  \end{equation*}
550  %  %
551  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 557  Because of the local character of the de Line 567  Because of the local character of the de
567  (a derivative is defined w.r.t. a point along the trajectory),  (a derivative is defined w.r.t. a point along the trajectory),
568  the intermediate results of the model trajectory  the intermediate results of the model trajectory
569  $\vec{v}^{(\lambda+1)}={\cal M}_{\lambda}(v^{(\lambda)})$  $\vec{v}^{(\lambda+1)}={\cal M}_{\lambda}(v^{(\lambda)})$
570  are needed to evaluate the intermediate Jacobian  may be required to evaluate the intermediate Jacobian
571  $M_{\lambda}|_{\vec{v}^{(\lambda)}} \, \delta \vec{v}^{(\lambda)} $.  $M_{\lambda}|_{\vec{v}^{(\lambda)}} \, \delta \vec{v}^{(\lambda)} $.
572    This is the case e.g. for nonlinear expressions
573    (momentum advection, nonlinear equation of state), state-dependent
574    conditional statements (parameterization schemes).
575  In the forward mode, the intermediate results are required  In the forward mode, the intermediate results are required
576  in the same order as computed by the full forward model ${\cal M}$,  in the same order as computed by the full forward model ${\cal M}$,
577  but in the reverse mode they are required in the reverse order.  but in the reverse mode they are required in the reverse order.
# Line 569  point of evaluation has to be recomputed Line 582  point of evaluation has to be recomputed
582    
583  A method to balance the amount of recomputations vs.  A method to balance the amount of recomputations vs.
584  storage requirements is called {\sf checkpointing}  storage requirements is called {\sf checkpointing}
585  (e.g. \cite{res-eta:98}).  (e.g. \cite{gri:92}, \cite{res-eta:98}).
586  It is depicted in \ref{fig:3levelcheck} for a 3-level checkpointing  It is depicted in \ref{fig:3levelcheck} for a 3-level checkpointing
587  [as an example, we give explicit numbers for a 3-day  [as an example, we give explicit numbers for a 3-day
588  integration with a 1-hourly timestep in square brackets].  integration with a 1-hourly timestep in square brackets].
# Line 580  In a first step, the model trajectory is Line 593  In a first step, the model trajectory is
593  $ {n}^{lev3} $ subsections [$ {n}^{lev3} $=3 1-day intervals],  $ {n}^{lev3} $ subsections [$ {n}^{lev3} $=3 1-day intervals],
594  with the label $lev3$ for this outermost loop.  with the label $lev3$ for this outermost loop.
595  The model is then integrated along the full trajectory,  The model is then integrated along the full trajectory,
596  and the model state stored only at every $ k_{i}^{lev3} $-th timestep  and the model state stored to disk only at every $ k_{i}^{lev3} $-th timestep
597  [i.e. 3 times, at  [i.e. 3 times, at
598  $ i = 0,1,2 $ corresponding to $ k_{i}^{lev3} = 0, 24, 48 $].  $ i = 0,1,2 $ corresponding to $ k_{i}^{lev3} = 0, 24, 48 $].
599    In addition, the cost function is computed, if needed.
600  %  %
601  \item [$lev2$]  \item [$lev2$]
602  In a second step each subsection itself is divided into  In a second step each subsection itself is divided into
603  $ {n}^{lev2} $ sub-subsections  $ {n}^{lev2} $ subsections
604  [$ {n}^{lev2} $=4 6-hour intervals per subsection].  [$ {n}^{lev2} $=4 6-hour intervals per subsection].
605  The model picks up at the last outermost dumped state  The model picks up at the last outermost dumped state
606  $ v_{k_{n}^{lev3}} $ and is integrated forward in time along  $ v_{k_{n}^{lev3}} $ and is integrated forward in time along
607  the last subsection, with the label $lev2$ for this    the last subsection, with the label $lev2$ for this  
608  intermediate loop.  intermediate loop.
609  The model state is now stored at every $ k_{i}^{lev2} $-th  The model state is now stored to disk at every $ k_{i}^{lev2} $-th
610  timestep  timestep
611  [i.e. 4 times, at  [i.e. 4 times, at
612  $ i = 0,1,2,3 $ corresponding to $ k_{i}^{lev2} = 48, 54, 60, 66 $].  $ i = 0,1,2,3 $ corresponding to $ k_{i}^{lev2} = 48, 54, 60, 66 $].
# Line 600  $ i = 0,1,2,3 $ corresponding to $ k_{i} Line 614  $ i = 0,1,2,3 $ corresponding to $ k_{i}
614  \item [$lev1$]  \item [$lev1$]
615  Finally, the model picks up at the last intermediate dump state  Finally, the model picks up at the last intermediate dump state
616  $ v_{k_{n}^{lev2}} $ and is integrated forward in time along  $ v_{k_{n}^{lev2}} $ and is integrated forward in time along
617  the last sub-subsection, with the label $lev1$ for this    the last subsection, with the label $lev1$ for this  
618  intermediate loop.  intermediate loop.
619  Within this sub-subsection only, the model state is stored  Within this sub-subsection only, parts of the model state is stored
620  at every timestep  to memory at every timestep
621  [i.e. every hour $ i=0,...,5$ corresponding to  [i.e. every hour $ i=0,...,5$ corresponding to
622  $ k_{i}^{lev1} = 66, 67, \ldots, 71 $].  $ k_{i}^{lev1} = 66, 67, \ldots, 71 $].
623  Thus, the  final state $ v_n = v_{k_{n}^{lev1}} $ is reached  The  final state $ v_n = v_{k_{n}^{lev1}} $ is reached
624  and the model state of all proceeding timesteps along the last  and the model state of all preceding timesteps along the last
625  sub-subsections are available, enabling integration backwards  innermost subsection are available, enabling integration backwards
626  in time along the last sub-subsection.  in time along the last subsection.
627  Thus, the adjoint can be computed along this last  The adjoint can thus be computed along this last
628  sub-subsection $k_{n}^{lev2}$.  subsection $k_{n}^{lev2}$.
629  %  %
630  \end{itemize}  \end{itemize}
631  %  %
632  This procedure is repeated consecutively for each previous  This procedure is repeated consecutively for each previous
633  sub-subsection $k_{n-1}^{lev2}, \ldots, k_{1}^{lev2} $  subsection $k_{n-1}^{lev2}, \ldots, k_{1}^{lev2} $
634  carrying the adjoint computation to the initial time  carrying the adjoint computation to the initial time
635  of the subsection $k_{n}^{lev3}$.  of the subsection $k_{n}^{lev3}$.
636  Then, the procedure is repeated for the previous subsection  Then, the procedure is repeated for the previous subsection
# Line 627  $k_{1}^{lev3}$. Line 641  $k_{1}^{lev3}$.
641  For the full model trajectory of  For the full model trajectory of
642  $ n^{lev3} \cdot n^{lev2} \cdot n^{lev1} $ timesteps  $ n^{lev3} \cdot n^{lev2} \cdot n^{lev1} $ timesteps
643  the required storing of the model state was significantly reduced to  the required storing of the model state was significantly reduced to
644  $ n^{lev1} + n^{lev2} + n^{lev3} $  $ n^{lev2} + n^{lev3} $ to disk and roughly $ n^{lev1} $ to memory
645  [i.e. for the 3-day integration with a total oof 72 timesteps  [i.e. for the 3-day integration with a total oof 72 timesteps
646  the model state was stored 13 times].  the model state was stored 7 times to disk and roughly 6 times
647    to memory].
648  This saving in memory comes at a cost of a required  This saving in memory comes at a cost of a required
649  3 full forward integrations of the model (one for each  3 full forward integrations of the model (one for each
650  checkpointing level).  checkpointing level).
651  The balance of storage vs. recomputation certainly depends  The optimal balance of storage vs. recomputation certainly depends
652  on the computing resources available.  on the computing resources available and may be adjusted by
653    adjusting the partitioning among the
654    $ n^{lev3}, \,\, n^{lev2}, \,\, n^{lev1} $.
655    
656  \begin{figure}[t!]  \begin{figure}[t!]
657  \begin{center}  \begin{center}
# Line 647  on the computing resources available. Line 664  on the computing resources available.
664  %\psfrag{v_kn^lev2}{\mathinfigure{v_{k_{n}^{lev2}}}}  %\psfrag{v_kn^lev2}{\mathinfigure{v_{k_{n}^{lev2}}}}
665  %\psfrag{v_k1^lev1}{\mathinfigure{v_{k_{1}^{lev1}}}}  %\psfrag{v_k1^lev1}{\mathinfigure{v_{k_{1}^{lev1}}}}
666  %\psfrag{v_kn^lev1}{\mathinfigure{v_{k_{n}^{lev1}}}}  %\psfrag{v_kn^lev1}{\mathinfigure{v_{k_{n}^{lev1}}}}
667  %\mbox{\epsfig{file=part5/checkpointing.eps, width=0.8\textwidth}}  %\mbox{\epsfig{file=s_autodiff/figs/checkpointing.eps, width=0.8\textwidth}}
668  \resizebox{5.5in}{!}{\includegraphics{part5/checkpointing.eps}}  \resizebox{5.5in}{!}{\includegraphics{s_autodiff/figs/checkpointing.eps}}
669  %\psfull  %\psfull
670  \end{center}  \end{center}
671  \caption{  \caption{
# Line 669  Schematic view of intermediate dump and Line 686  Schematic view of intermediate dump and
686  %**********************************************************************  %**********************************************************************
687  \section{TLM and ADM generation in general}  \section{TLM and ADM generation in general}
688  \label{sec_ad_setup_gen}  \label{sec_ad_setup_gen}
689    \begin{rawhtml}
690    <!-- CMIREDIR:sec_ad_setup_gen: -->
691    \end{rawhtml}
692  %**********************************************************************  %**********************************************************************
693    
694  In this section we describe in a general fashion  In this section we describe in a general fashion
695  the parts of the code that are relevant for automatic  the parts of the code that are relevant for automatic
696  differentiation using the software tool TAMC.  differentiation using the software tool TAF.
697    Modifications to use OpenAD are described in \ref{sec_ad_openad}.
698    
699  \input{part5/doc_ad_the_model}  \input{s_autodiff/text/doc_ad_the_model}
700    
701  The basic flow is depicted in \ref{fig:adthemodel}.  The basic flow is depicted in \ref{fig:adthemodel}.
702  If the option {\tt ALLOW\_AUTODIFF\_TAMC} is defined, the driver routine  If CPP option \texttt{ALLOW\_AUTODIFF\_TAMC} is defined,
703    the driver routine
704  {\it the\_model\_main}, instead of calling {\it the\_main\_loop},  {\it the\_model\_main}, instead of calling {\it the\_main\_loop},
705  invokes the adjoint of this routine, {\it adthe\_main\_loop},  invokes the adjoint of this routine, {\it adthe\_main\_loop}
706  which is the toplevel routine in terms of reverse mode computation.  (case \texttt{\#define ALLOW\_ADJOINT\_RUN}), or
707  The routine {\it adthe\_main\_loop} has been generated using TAMC.  the tangent linear of this routine {\it g\_the\_main\_loop}
708  It contains both the forward integration of the full model,  (case \texttt{\#define ALLOW\_TANGENTLINEAR\_RUN}),
709    which are the toplevel routines in terms of automatic differentiation.
710    The routines {\it adthe\_main\_loop} or {\it g\_the\_main\_loop}
711    are generated by TAF.
712    It contains both the forward integration of the full model, the
713    cost function calculation,
714  any additional storing that is required for efficient checkpointing,  any additional storing that is required for efficient checkpointing,
715  and the reverse integration of the adjoint model.  and the reverse integration of the adjoint model.
716  The structure of {\it adthe\_main\_loop} has been strongly  
717  simplified for clarification; in particular, no checkpointing  [DESCRIBE IN A SEPARATE SECTION THE WORKING OF THE TLM]
718    
719    In Fig. \ref{fig:adthemodel}
720    the structure of {\it adthe\_main\_loop} has been strongly
721    simplified to focus on the essentials; in particular, no checkpointing
722  procedures are shown here.  procedures are shown here.
723  Prior to the call of {\it adthe\_main\_loop}, the routine  Prior to the call of {\it adthe\_main\_loop}, the routine
724  {\it ctrl\_unpack} is invoked to unpack the control vector,  {\it ctrl\_unpack} is invoked to unpack the control vector
725  and following that call, the routine {\it ctrl\_pack}  or initialise the control variables.
726    Following the call of {\it adthe\_main\_loop},
727    the routine {\it ctrl\_pack}
728  is invoked to pack the control vector  is invoked to pack the control vector
729  (cf. Section \ref{section_ctrl}).  (cf. Section \ref{section_ctrl}).
730  If gradient checks are to be performed, the option  If gradient checks are to be performed, the option
731  {\tt ALLOW\_GRADIENT\_CHECK} is defined. In this case  {\tt ALLOW\_GRADIENT\_CHECK} is defined. In this case
732  the driver routine {\it grdchk\_main} is called after  the driver routine {\it grdchk\_main} is called after
733  the gradient has been computed via the adjoint  the gradient has been computed via the adjoint
734  (cf. Section \ref{section_grdchk}).  (cf. Section \ref{sec:ad_gradient_check}).
735    
736    %------------------------------------------------------------------
737    
738    \subsection{General setup
739    \label{section_ad_setup}}
740    
741    In order to configure AD-related setups the following packages need
742    to be enabled:
743    {\it
744    \begin{table}[!ht]
745    \begin{tabular}{l}
746    autodiff \\
747    ctrl \\
748    cost \\
749    grdchk \\
750    \end{tabular}
751    \end{table}
752    }
753    The packages are enabled by adding them to your experiment-specific
754    configuration file
755    {\it packages.conf} (see Section ???).
756    
757    The following AD-specific CPP option files need to be customized:
758    %
759    \begin{itemize}
760    %
761    \item {\it ECCO\_CPPOPTIONS.h} \\
762    This header file collects CPP options for the packages
763    {\it autodiff, cost, ctrl} as well as AD-unrelated options for
764    the external forcing package {\it exf}.
765    \footnote{NOTE: These options are not set in their package-specific
766    headers such as {\it COST\_CPPOPTIONS.h}, but are instead collected
767    in the single header file {\it ECCO\_CPPOPTIONS.h}.
768    The package-specific header files serve as simple
769    placeholders at this point.}
770    %
771    \item {\it tamc.h} \\
772    This header configures the splitting of the time stepping loop
773    w.r.t. the 3-level checkpointing (see section ???).
774    
775    %
776    \end{itemize}
777    
778    %------------------------------------------------------------------
779    
780    \subsection{Building the AD code using TAF
781    \label{section_ad_build}}
782    
783    The build process of an AD code is very similar to building
784    the forward model. However, depending on which AD code one wishes
785    to generate, and on which AD tool is available (TAF or TAMC),
786    the following {\tt make} targets are available:
787    
788    \begin{table}[!ht]
789    {\footnotesize
790    \begin{tabular}{|ccll|}
791    \hline
792    ~ & {\it AD-target} & {\it output} & {\it description} \\
793    \hline
794    \hline
795    (1) & {\tt <MODE><TOOL>only} & {\tt <MODE>\_<TOOL>\_output.f}  &
796    generates code for $<$MODE$>$ using $<$TOOL$>$ \\
797    ~ & ~ & ~ & no {\tt make} dependencies on {\tt .F .h} \\
798    ~ & ~ & ~ & useful for compiling on remote platforms \\
799    \hline
800    (2) & {\tt <MODE><TOOL>} & {\tt <MODE>\_<TOOL>\_output.f}  &
801    generates code for $<$MODE$>$ using $<$TOOL$>$ \\
802    ~ & ~ & ~ & includes {\tt make} dependencies on {\tt .F .h} \\
803    ~ & ~ & ~ & i.e. input for $<$TOOL$>$ may be re-generated \\
804    \hline
805    (3) & {\tt <MODE>all} & {\tt mitgcmuv\_<MODE>}  &
806    generates code for $<$MODE$>$ using $<$TOOL$>$ \\
807    ~ & ~ & ~ & and compiles all code \\
808    ~ & ~ & ~ & (use of TAF is set as default) \\
809    \hline
810    \end{tabular}
811    }
812    \end{table}
813    %
814    Here, the following placeholders are used
815    %
816    \begin{itemize}
817    %
818    \item $<$TOOL$>$
819    %
820    \begin{itemize}
821    %
822    \item {\tt TAF}
823    \item {\tt TAMC}
824    %
825    \end{itemize}
826    %
827    \item $<$MODE$>$
828    %
829    \begin{itemize}
830    %
831    \item {\tt ad} generates the adjoint model (ADM)
832    \item {\tt ftl} generates the tangent linear model (TLM)
833    \item {\tt svd} generates both ADM and TLM for \\
834    singular value decomposition (SVD) type calculations
835    %
836    \end{itemize}
837    %
838    \end{itemize}
839    
840    For example, to generate the adjoint model using TAF after routines ({\tt .F})
841    or headers ({\tt .h}) have been modified, but without compilation,
842    type {\tt make adtaf};
843    or, to generate the tangent linear model using TAMC without
844    re-generating the input code, type {\tt make ftltamconly}.
845    
846    
847    A typical full build process to generate the ADM via TAF would
848    look like follows:
849    \begin{verbatim}
850    % mkdir build
851    % cd build
852    % ../../../tools/genmake2 -mods=../code_ad
853    % make depend
854    % make adall
855    \end{verbatim}
856    
857    %------------------------------------------------------------------
858    
859    \subsection{The AD build process in detail
860    \label{section_ad_build_detail}}
861    
862    The {\tt make <MODE>all} target consists of the following procedures:
863    
864    \begin{enumerate}
865    %
866    \item
867    A header file {\tt AD\_CONFIG.h} is generated which contains a CPP option
868    on which code ought to be generated. Depending on the {\tt make} target,
869    the contents is one of the following:
870    \begin{itemize}
871    \item
872    {\tt \#define ALLOW\_ADJOINT\_RUN}
873    \item
874    {\tt \#define ALLOW\_TANGENTLINEAR\_RUN}
875    \item
876    {\tt \#define ALLOW\_ECCO\_OPTIMIZATION}
877    \end{itemize}
878    %
879    \item
880    A single file {\tt <MODE>\_input\_code.f} is concatenated
881    consisting of all {\tt .f} files that are part of the list {\bf AD\_FILES}
882    and all {\tt .flow} files that are part of the list {\bf AD\_FLOW\_FILES}.
883    %
884    \item
885    The AD tool is invoked with the {\tt <MODE>\_<TOOL>\_FLAGS}.
886    The default AD tool flags in {\tt genmake2} can be overrwritten by
887    an {\tt adjoint\_options} file (similar to the platform-specific
888    {\tt build\_options}, see Section ???.
889    The AD tool writes the resulting AD code into the file
890    {\tt <MODE>\_input\_code\_ad.f}
891    %
892    \item
893    A short sed script {\tt adjoint\_sed} is applied to
894    {\tt <MODE>\_input\_code\_ad.f}
895    to reinstate {\bf myThid} into the CALL argument list of active file I/O.
896    The result is written to file {\tt <MODE>\_<TOOL>\_output.f}.
897    %
898    \item
899    All routines are compiled and an executable is generated
900    (see Table ???).
901    %
902    \end{enumerate}
903    
904    \subsubsection{The list AD\_FILES and {\tt .list} files}
905    
906    Not all routines are presented to the AD tool.
907    Routines typically hidden are diagnostics routines which
908    do not influence the cost function, but may create
909    artificial flow dependencies such as I/O of active variables.
910    
911    {\tt genmake2} generates a list (or variable) {\bf AD\_FILES}
912    which contains all routines that are shown to the AD tool.
913    This list is put together from all files with suffix {\tt .list}
914    that {\tt genmake2} finds in its search directories.
915    The list file for the core MITgcm routines is in {\tt model/src/}
916    is called {\tt model\_ad\_diff.list}.
917    Note that no wrapper routine is shown to TAF. These are either
918    not visible at all to the AD code, or hand-written AD code
919    is available (see next section).
920    
921    Each package directory contains its package-specific
922    list file {\tt <PKG>\_ad\_diff.list}. For example,
923    {\tt pkg/ptracers/} contains the file {\tt ptracers\_ad\_diff.list}.
924    Thus, enabling a package will automatically extend the
925    {\bf AD\_FILES} list of {\tt genmake2} to incorporate the
926    package-specific routines.
927    Note that you will need to regenerate the {\tt Makefile} if
928    you enable a package (e.g. by adding it to {\tt packages.conf})
929    and a {\tt Makefile} already exists.
930    
931    \subsubsection{The list AD\_FLOW\_FILES and {\tt .flow} files}
932    
933    TAMC and TAF can evaluate user-specified directives
934    that start with a specific syntax ({\tt CADJ}, {\tt C\$TAF}, {\tt !\$TAF}).
935    The main categories of directives are STORE directives and
936    FLOW directives. Here, we are concerned with flow directives,
937    store directives are treated elsewhere.
938    
939    Flow directives enable the AD tool to evaluate how it should treat
940    routines that are 'hidden' by the user, i.e. routines which are
941    not contained in the {\bf AD\_FILES} list (see previous section),
942    but which are called in part of the code that the AD tool does see.
943    The flow directive tell the AD tool
944    %
945    \begin{itemize}
946    %
947    \item which subroutine arguments are input/output
948    \item which subroutine arguments are active
949    \item which subroutine arguments are required to compute the cost
950    \item which subroutine arguments are dependent
951    %
952    \end{itemize}
953    %
954    The syntax for the flow directives can be found in the
955    AD tool manuals.
956    
957    {\tt genmake2} generates a list (or variable) {\bf AD\_FLOW\_FILES}
958    which contains all files with suffix{\tt .flow} that it finds
959    in its search directories.
960    The flow directives for the core MITgcm routines of
961    {\tt eesupp/src/} and {\tt model/src/}
962    reside in {\tt pkg/autodiff/}.
963    This directory also contains hand-written adjoint code
964    for the MITgcm WRAPPER (section \ref{chap:sarch}).
965    
966    Flow directives for package-specific routines are contained in
967    the corresponding package directories in the file
968    {\tt <PKG>\_ad.flow}, e.g. ptracers-specific directives are in
969    {\tt ptracers\_ad.flow}.
970    
971    \subsubsection{Store directives for 3-level checkpointing}
972    
973    The storing that is required at each period of the
974    3-level checkpointing is controled by three
975    top-level headers.
976    
977    \begin{verbatim}
978    do ilev_3 = 1, nchklev_3
979    #  include ``checkpoint_lev3.h''
980       do ilev_2 = 1, nchklev_2
981    #     include ``checkpoint_lev2.h''
982          do ilev_1 = 1, nchklev_1
983    #        include ``checkpoint_lev1.h''
984    
985    ...
986    
987          end do
988       end do
989    end do
990    \end{verbatim}
991    
992    All files {\tt checkpoint\_lev?.h} are contained in directory
993    {\tt pkg/autodiff/}.
994    
995    
996    \subsubsection{Changing the default AD tool flags: ad\_options files}
997    
998    
999    \subsubsection{Hand-written adjoint code}
1000    
1001    %------------------------------------------------------------------
1002    
1003  \subsection{The cost function (dependent variable)  \subsection{The cost function (dependent variable)
1004  \label{section_cost}}  \label{section_cost}}
# Line 706  the gradient has been computed via the a Line 1006  the gradient has been computed via the a
1006  The cost function $ {\cal J} $ is referred to as the {\sf dependent variable}.  The cost function $ {\cal J} $ is referred to as the {\sf dependent variable}.
1007  It is a function of the input variables $ \vec{u} $ via the composition  It is a function of the input variables $ \vec{u} $ via the composition
1008  $ {\cal J}(\vec{u}) \, = \, {\cal J}(M(\vec{u})) $.  $ {\cal J}(\vec{u}) \, = \, {\cal J}(M(\vec{u})) $.
1009  The input is referred to as the  The input are referred to as the
1010  {\sf independent variables} or {\sf control variables}.  {\sf independent variables} or {\sf control variables}.
1011  All aspects relevant to the treatment of the cost function $ {\cal J} $  All aspects relevant to the treatment of the cost function $ {\cal J} $
1012  (parameter setting, initialization, accumulation,  (parameter setting, initialization, accumulation,
1013  final evaluation), are controlled by the package {\it pkg/cost}.  final evaluation), are controlled by the package {\it pkg/cost}.
1014    The aspects relevant to the treatment of the independent variables
1015    are controlled by the package {\it pkg/ctrl} and will be treated
1016    in the next section.
1017    
1018  \input{part5/doc_cost_flow}  \input{s_autodiff/text/doc_cost_flow}
1019    
1020    \subsubsection{Enabling the package}
1021    
 \subsubsection{genmake and CPP options}  
 %  
 \begin{itemize}  
 %  
 \item  
1022  \fbox{  \fbox{
1023  \begin{minipage}{12cm}  \begin{minipage}{12cm}
1024  {\it genmake}, {\it CPP\_OPTIONS.h}, {\it ECCO\_CPPOPTIONS.h}  {\it packages.conf}, {\it ECCO\_CPPOPTIONS.h}
1025  \end{minipage}  \end{minipage}
1026  }  }
1027  \end{itemize}  \begin{itemize}
 %  
 The directory {\it pkg/cost} can be included to the  
 compile list in 3 different ways (cf. Section \ref{???}):  
1028  %  %
1029  \begin{enumerate}  \item
1030    The package is enabled by adding {\it cost} to your file {\it packages.conf}
1031    (see Section ???)
1032  %  %
1033  \item {\it genmake}: \\  \item
1034  Change the default settings in the file {\it genmake} by adding  
1035  {\bf cost} to the {\bf enable} list (not recommended).  
1036  %  \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}.  
1037  %  %
1038  \end{enumerate}  
1039    N.B.: In general the following packages ought to be enabled
1040    simultaneously: {\it autodiff, cost, ctrl}.
1041  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}.
1042  Each specific cost function contribution has its own option.  Each specific cost function contribution has its own option.
1043  For the present example the option is {\bf ALLOW\_COST\_TRACER}.  For the present example the option is {\bf ALLOW\_COST\_TRACER}.
1044  All cost-specific options are set in {\it ECCO\_CPPOPTIONS.h}  All cost-specific options are set in {\it ECCO\_CPPOPTIONS.h}
1045  Since the cost function is usually used in conjunction with  Since the cost function is usually used in conjunction with
1046  automatic differentiation, the CPP option  automatic differentiation, the CPP option
1047  {\bf ALLOW\_ADJOINT\_RUN} should be defined  {\bf ALLOW\_ADJOINT\_RUN} (file {\it CPP\_OPTIONS.h}) and
1048  (file {\it CPP\_OPTIONS.h}).  {\bf ALLOW\_AUTODIFF\_TAMC} (file {\it ECCO\_CPPOPTIONS.h})
1049    should be defined.
1050    
1051  \subsubsection{Initialization}  \subsubsection{Initialization}
1052  %  %
1053  The initialization of the {\it cost} package is readily enabled  The initialization of the {\it cost} package is readily enabled
1054  as soon as the CPP option {\bf ALLOW\_ADJOINT\_RUN} is defined.  as soon as the CPP option {\bf ALLOW\_COST} is defined.
1055  %  %
1056  \begin{itemize}  \begin{itemize}
1057  %  %
# Line 811  Within this 'driver' routine, S/R are ca Line 1105  Within this 'driver' routine, S/R are ca
1105  the chosen cost function contributions.  the chosen cost function contributions.
1106  In the present example ({\bf ALLOW\_COST\_TRACER}),  In the present example ({\bf ALLOW\_COST\_TRACER}),
1107  S/R {\it cost\_tracer} is called.  S/R {\it cost\_tracer} is called.
1108  It accumulates {\bf objf\_tracer} according to eqn. (\ref{???}).  It accumulates {\bf objf\_tracer} according to eqn. (ref:ask-the-author).
1109  %  %
1110  \subsubsection{Finalize all contributions}  \subsubsection{Finalize all contributions}
1111  %  %
# Line 831  from each contribution and sums over all Line 1125  from each contribution and sums over all
1125  \begin{equation}  \begin{equation}
1126  {\cal J} \, = \,  {\cal J} \, = \,
1127  {\rm fc} \, = \,  {\rm fc} \, = \,
1128  {\rm mult\_tracer} \sum_{bi,\,bj}^{nSx,\,nSy}  {\rm mult\_tracer} \sum_{\text{global sum}} \sum_{bi,\,bj}^{nSx,\,nSy}
1129  {\rm objf\_tracer}(bi,bj) \, + \, ...  {\rm objf\_tracer}(bi,bj) \, + \, ...
1130  \end{equation}  \end{equation}
1131  %  %
1132  The total cost function {\bf fc} will be the  The total cost function {\bf fc} will be the
1133  'dependent' variable in the argument list for TAMC, i.e.  'dependent' variable in the argument list for TAF, i.e.
1134  \begin{verbatim}  \begin{verbatim}
1135  tamc -output 'fc' ...  taf -output 'fc' ...
1136  \end{verbatim}  \end{verbatim}
1137    
1138  %%%% \end{document}  %%%% \end{document}
1139    
1140  \input{part5/doc_ad_the_main}  \input{s_autodiff/text/doc_ad_the_main}
1141    
1142  \subsection{The control variables (independent variables)  \subsection{The control variables (independent variables)
1143  \label{section_ctrl}}  \label{section_ctrl}}
# Line 863  All aspects relevant to the treatment of Line 1157  All aspects relevant to the treatment of
1157  (parameter setting, initialization, perturbation)  (parameter setting, initialization, perturbation)
1158  are controlled by the package {\it pkg/ctrl}.  are controlled by the package {\it pkg/ctrl}.
1159    
1160  \input{part5/doc_ctrl_flow}  \input{s_autodiff/text/doc_ctrl_flow}
1161    
1162  \subsubsection{genmake and CPP options}  \subsubsection{genmake and CPP options}
1163  %  %
# Line 879  are controlled by the package {\it pkg/c Line 1173  are controlled by the package {\it pkg/c
1173  %  %
1174  To enable the directory to be included to the compile list,  To enable the directory to be included to the compile list,
1175  {\bf ctrl} has to be added to the {\bf enable} list in  {\bf ctrl} has to be added to the {\bf enable} list in
1176  {\it .genmakerc} (or {\it genmake} itself).  {\it .genmakerc} or in {\it genmake} itself (analogous to {\it cost}
1177    package, cf. previous section).
1178  Each control variable is enabled via its own CPP option  Each control variable is enabled via its own CPP option
1179  in {\it ECCO\_CPPOPTIONS.h}.  in {\it ECCO\_CPPOPTIONS.h}.
1180    
# Line 920  and their gradients: {\it ctrl\_unpack} Line 1215  and their gradients: {\it ctrl\_unpack}
1215  \\  \\
1216  %  %
1217  Two important issues related to the handling of the control  Two important issues related to the handling of the control
1218  variables in the MITGCM need to be addressed.  variables in MITgcm need to be addressed.
1219  First, in order to save memory, the control variable arrays  First, in order to save memory, the control variable arrays
1220  are not kept in memory, but rather read from file and added  are not kept in memory, but rather read from file and added
1221  to the initial fields during the model initialization phase.  to the initial fields during the model initialization phase.
# Line 952  and gradient are generated and initialis Line 1247  and gradient are generated and initialis
1247  %  %
1248  The dependency flow for differentiation w.r.t. the controls  The dependency flow for differentiation w.r.t. the controls
1249  starts with adding a perturbation onto the input variable,  starts with adding a perturbation onto the input variable,
1250  thus defining the independent or control variables for TAMC.  thus defining the independent or control variables for TAF.
1251  Three types of controls may be considered:  Three types of controls may be considered:
1252  %  %
1253  \begin{itemize}  \begin{itemize}
# Line 973  temperature and salinity are initialised Line 1268  temperature and salinity are initialised
1268  a perturbation anomaly is added to the field in S/R  a perturbation anomaly is added to the field in S/R
1269  {\it ctrl\_map\_ini}  {\it ctrl\_map\_ini}
1270  %  %
1271    %\begin{eqnarray}
1272  \begin{equation}  \begin{equation}
1273  \begin{split}  \begin{aligned}
1274  u         & = \, u_{[0]} \, + \, \Delta u \\  u         & = \, u_{[0]} \, + \, \Delta u \\
1275  {\bf tr1}(...) & = \, {\bf tr1_{ini}}(...) \, + \, {\bf xx\_tr1}(...)  {\bf tr1}(...) & = \, {\bf tr1_{ini}}(...) \, + \, {\bf xx\_tr1}(...)
1276  \label{perturb}  \label{perturb}
1277  \end{split}  \end{aligned}
1278  \end{equation}  \end{equation}
1279    %\end{eqnarray}
1280  %  %
1281  {\bf xx\_tr1} is a 3-dim. global array  {\bf xx\_tr1} is a 3-dim. global array
1282  holding the perturbation. In the case of a simple  holding the perturbation. In the case of a simple
1283  sensitivity study this array is identical to zero.  sensitivity study this array is identical to zero.
1284  However, it's specification is essential in the context  However, it's specification is essential in the context
1285  of automatic differentiation since TAMC  of automatic differentiation since TAF
1286  treats the corresponding line in the code symbolically  treats the corresponding line in the code symbolically
1287  when determining the differentiation chain and its origin.  when determining the differentiation chain and its origin.
1288  Thus, the variable names are part of the argument list  Thus, the variable names are part of the argument list
1289  when calling TAMC:  when calling TAF:
1290  %  %
1291  \begin{verbatim}  \begin{verbatim}
1292  tamc -input 'xx_tr1 ...' ...  taf -input 'xx_tr1 ...' ...
1293  \end{verbatim}  \end{verbatim}
1294  %  %
1295  Now, as mentioned above, the MITGCM avoids maintaining  Now, as mentioned above, MITgcm avoids maintaining
1296  an array for each control variable by reading the  an array for each control variable by reading the
1297  perturbation to a temporary array from file.  perturbation to a temporary array from file.
1298  To ensure the symbolic link to be recognized by TAMC, a scalar  To ensure the symbolic link to be recognized by TAF, a scalar
1299  dummy variable {\bf xx\_tr1\_dummy} is introduced  dummy variable {\bf xx\_tr1\_dummy} is introduced
1300  and an 'active read' routine of the adjoint support  and an 'active read' routine of the adjoint support
1301  package {\it pkg/autodiff} is invoked.  package {\it pkg/autodiff} is invoked.
1302  The read-procedure is tagged with the variable  The read-procedure is tagged with the variable
1303  {\bf xx\_tr1\_dummy} enabling TAMC to recognize the  {\bf xx\_tr1\_dummy} enabling TAF to recognize the
1304  initialization of the perturbation.  initialization of the perturbation.
1305  The modified call of TAMC thus reads  The modified call of TAF thus reads
1306  %  %
1307  \begin{verbatim}  \begin{verbatim}
1308  tamc -input 'xx_tr1_dummy ...' ...  taf -input 'xx_tr1_dummy ...' ...
1309  \end{verbatim}  \end{verbatim}
1310  %  %
1311  and the modified operation to (\ref{perturb})  and the modified operation to (\ref{perturb})
# Line 1023  in the code takes on the form Line 1320  in the code takes on the form
1320  %  %
1321  Note, that reading an active variable corresponds  Note, that reading an active variable corresponds
1322  to a variable assignment. Its derivative corresponds  to a variable assignment. Its derivative corresponds
1323  to a write statement of the adjoint variable.  to a write statement of the adjoint variable, followed by
1324    a reset.
1325  The 'active file' routines have been designed  The 'active file' routines have been designed
1326  to support active read and corresponding adjoint active write  to support active read and corresponding adjoint active write
1327  operations (and vice versa).  operations (and vice versa).
# Line 1140  at intermediate times can be written usi Line 1438  at intermediate times can be written usi
1438  {\it addummy\_in\_stepping}.  {\it addummy\_in\_stepping}.
1439  This routine is part of the adjoint support package  This routine is part of the adjoint support package
1440  {\it pkg/autodiff} (cf.f. below).  {\it pkg/autodiff} (cf.f. below).
1441    The procedure is enabled using via the CPP-option
1442    {\bf ALLOW\_AUTODIFF\_MONITOR} (file {\it ECCO\_CPPOPTIONS.h}).
1443  To be part of the adjoint code, the corresponding S/R  To be part of the adjoint code, the corresponding S/R
1444  {\it dummy\_in\_stepping} has to be called in the forward  {\it dummy\_in\_stepping} has to be called in the forward
1445  model (S/R {\it the\_main\_loop}) at the appropriate place.  model (S/R {\it the\_main\_loop}) at the appropriate place.
1446    The adjoint common blocks are extracted from the adjoint code
1447    via the header file {\it adcommon.h}.
1448    
1449  {\it dummy\_in\_stepping} is essentially empty,  {\it dummy\_in\_stepping} is essentially empty,
1450  the corresponding adjoint routine is hand-written rather  the corresponding adjoint routine is hand-written rather
# Line 1169  the common blocks Line 1471  the common blocks
1471  {\bf /adtr1\_r/}, {\bf /adffields/},  {\bf /adtr1\_r/}, {\bf /adffields/},
1472  which have been extracted from the adjoint code to enable  which have been extracted from the adjoint code to enable
1473  access to the adjoint variables.  access to the adjoint variables.
1474    
1475    {\bf WARNING:} If the structure of the common blocks
1476    {\bf /dynvars\_r/}, {\bf /dynvars\_cd/}, etc., changes
1477    similar changes will occur in the adjoint common blocks.
1478    Therefore, consistency between the TAMC-generated common blocks
1479    and those in {\it adcommon.h} have to be checked.
1480  %  %
1481  \end{itemize}  \end{itemize}
1482    
# Line 1194  u_{[k+1]} \, = \,  u_{[0]} \, + \, \Delt Line 1502  u_{[k+1]} \, = \,  u_{[0]} \, + \, \Delt
1502  $ u_{[k+1]} $ then serves as input for a forward/adjoint run  $ u_{[k+1]} $ then serves as input for a forward/adjoint run
1503  to determine $ {\cal J} $ and $ \nabla _{u}{\cal J} $ at iteration step  to determine $ {\cal J} $ and $ \nabla _{u}{\cal J} $ at iteration step
1504  $ k+1 $.  $ k+1 $.
1505  Tab. \ref{???} sketches the flow between forward/adjoint model  Tab. ref:ask-the-author sketches the flow between forward/adjoint model
1506  and the minimization routine.  and the minimization routine.
1507    
1508    {\scriptsize
1509  \begin{eqnarray*}  \begin{eqnarray*}
 \scriptsize  
1510  \begin{array}{ccccc}  \begin{array}{ccccc}
1511  u_{[0]} \,\, ,  \,\, \Delta u_{[k]}    & ~ & ~ & ~ & ~ \\  u_{[0]} \,\, ,  \,\, \Delta u_{[k]}    & ~ & ~ & ~ & ~ \\
1512  {\Big\downarrow}  {\Big\downarrow}
# Line 1249  ad \, v_{[k]} (\delta {\cal J}) = Line 1557  ad \, v_{[k]} (\delta {\cal J}) =
1557   ~ & ~ & ~ & ~ & \Delta u_{[k+1]} \\   ~ & ~ & ~ & ~ & \Delta u_{[k+1]} \\
1558  \end{array}  \end{array}
1559  \end{eqnarray*}  \end{eqnarray*}
1560    }
1561    
1562  The routines {\it ctrl\_unpack} and {\it ctrl\_pack} provide  The routines {\it ctrl\_unpack} and {\it ctrl\_pack} provide
1563  the link between the model and the minimization routine.  the link between the model and the minimization routine.
1564  As described in Section \ref{???}  As described in Section ref:ask-the-author
1565  the {\it unpack} and {\it pack} routines read and write  the {\it unpack} and {\it pack} routines read and write
1566  control and gradient {\it vectors} which are compressed  control and gradient {\it vectors} which are compressed
1567  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.14  
changed lines
  Added in v.1.24
  ViewVC Help
Powered by ViewVC 1.1.22