/[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.20 by edhill, Wed Apr 5 02:27:33 2006 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.  However, unlike a
14  they parse a program code as input and produce a new program code  pure source-to-source translation, the output program represents a new
15  as output.  algorithm, such as the evaluation of the Jacobian, the Hessian, or
16  However, unlike a pure source-to-source translation, the output program  higher derivative operators.  In principle, a variety of derived
17  represents a new algorithm, such as the evaluation of the  algorithms can be generated automatically in this way.
18  Jacobian, the Hessian, or higher derivative operators.  
19  In principle, a variety of derived algorithms  MITgcm has been adapted for use with the Tangent linear and Adjoint
20  can be generated automatically in this way.  Model Compiler (TAMC) and its successor TAF (Transformation of
21    Algorithms in Fortran), developed by Ralf Giering (\cite{gie-kam:98},
22  The MITGCM has been adapted for use with the  \cite{gie:99,gie:00}).  The first application of the adjoint of MITgcm
23  Tangent linear and Adjoint Model Compiler (TAMC) and its successor TAF  for sensitivity studies has been published by \cite{maro-eta:99}.
24  (Transformation of Algorithms in Fortran), developed  \cite{sta-eta:97,sta-eta:01} use MITgcm and its adjoint for ocean
25  by Ralf Giering (\cite{gie-kam:98}, \cite{gie:99,gie:00}).  state estimation studies.  In the following we shall refer to TAMC and
26  The first application of the adjoint of the MITGCM for sensitivity  TAF synonymously, except were explicitly stated otherwise.
27  studies has been published by \cite{maro-eta:99}.  
28  \cite{sta-eta:97,sta-eta:01} use the MITGCM and its adjoint  TAMC exploits the chain rule for computing the first derivative of a
29  for ocean state estimation studies.  function with respect to a set of input variables.  Treating a given
30  In the following we shall refer to TAMC and TAF synonymously,  forward code as a composition of operations -- each line representing
31  except were explicitly stated otherwise.  a compositional element, the chain rule is rigorously applied to the
32    code, line by line. The resulting tangent linear or adjoint code,
33  TAMC exploits the chain rule for computing the first  then, may be thought of as the composition in forward or reverse
34  derivative of a function with  order, respectively, of the Jacobian matrices of the forward code's
35  respect to a set of input variables.  compositional elements.
 Treating a given forward code as a composition of operations --  
 each line representing a compositional element, the chain rule is  
 rigorously applied to the code, line by line. The resulting  
 tangent linear or adjoint code,  
 then, may be thought of as the composition in  
 forward or reverse order, respectively, of the  
 Jacobian matrices of the forward code's compositional elements.  
36    
37  %**********************************************************************  %**********************************************************************
38  \section{Some basic algebra}  \section{Some basic algebra}
39  \label{sec_ad_algebra}  \label{sec_ad_algebra}
40    \begin{rawhtml}
41    <!-- CMIREDIR:sec_ad_algebra: -->
42    \end{rawhtml}
43  %**********************************************************************  %**********************************************************************
44    
45  Let $ \cal{M} $ be a general nonlinear, model, i.e. a  Let $ \cal{M} $ be a general nonlinear, model, i.e. a
# Line 557  Because of the local character of the de Line 555  Because of the local character of the de
555  (a derivative is defined w.r.t. a point along the trajectory),  (a derivative is defined w.r.t. a point along the trajectory),
556  the intermediate results of the model trajectory  the intermediate results of the model trajectory
557  $\vec{v}^{(\lambda+1)}={\cal M}_{\lambda}(v^{(\lambda)})$  $\vec{v}^{(\lambda+1)}={\cal M}_{\lambda}(v^{(\lambda)})$
558  are needed to evaluate the intermediate Jacobian  may be required to evaluate the intermediate Jacobian
559  $M_{\lambda}|_{\vec{v}^{(\lambda)}} \, \delta \vec{v}^{(\lambda)} $.  $M_{\lambda}|_{\vec{v}^{(\lambda)}} \, \delta \vec{v}^{(\lambda)} $.
560    This is the case e.g. for nonlinear expressions
561    (momentum advection, nonlinear equation of state), state-dependent
562    conditional statements (parameterization schemes).
563  In the forward mode, the intermediate results are required  In the forward mode, the intermediate results are required
564  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}$,
565  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 570  point of evaluation has to be recomputed
570    
571  A method to balance the amount of recomputations vs.  A method to balance the amount of recomputations vs.
572  storage requirements is called {\sf checkpointing}  storage requirements is called {\sf checkpointing}
573  (e.g. \cite{res-eta:98}).  (e.g. \cite{gri:92}, \cite{res-eta:98}).
574  It is depicted in \ref{fig:3levelcheck} for a 3-level checkpointing  It is depicted in \ref{fig:3levelcheck} for a 3-level checkpointing
575  [as an example, we give explicit numbers for a 3-day  [as an example, we give explicit numbers for a 3-day
576  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 581  In a first step, the model trajectory is
581  $ {n}^{lev3} $ subsections [$ {n}^{lev3} $=3 1-day intervals],  $ {n}^{lev3} $ subsections [$ {n}^{lev3} $=3 1-day intervals],
582  with the label $lev3$ for this outermost loop.  with the label $lev3$ for this outermost loop.
583  The model is then integrated along the full trajectory,  The model is then integrated along the full trajectory,
584  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
585  [i.e. 3 times, at  [i.e. 3 times, at
586  $ i = 0,1,2 $ corresponding to $ k_{i}^{lev3} = 0, 24, 48 $].  $ i = 0,1,2 $ corresponding to $ k_{i}^{lev3} = 0, 24, 48 $].
587    In addition, the cost function is computed, if needed.
588  %  %
589  \item [$lev2$]  \item [$lev2$]
590  In a second step each subsection itself is divided into  In a second step each subsection itself is divided into
591  $ {n}^{lev2} $ sub-subsections  $ {n}^{lev2} $ subsections
592  [$ {n}^{lev2} $=4 6-hour intervals per subsection].  [$ {n}^{lev2} $=4 6-hour intervals per subsection].
593  The model picks up at the last outermost dumped state  The model picks up at the last outermost dumped state
594  $ v_{k_{n}^{lev3}} $ and is integrated forward in time along  $ v_{k_{n}^{lev3}} $ and is integrated forward in time along
595  the last subsection, with the label $lev2$ for this    the last subsection, with the label $lev2$ for this  
596  intermediate loop.  intermediate loop.
597  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
598  timestep  timestep
599  [i.e. 4 times, at  [i.e. 4 times, at
600  $ 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 602  $ i = 0,1,2,3 $ corresponding to $ k_{i}
602  \item [$lev1$]  \item [$lev1$]
603  Finally, the model picks up at the last intermediate dump state  Finally, the model picks up at the last intermediate dump state
604  $ v_{k_{n}^{lev2}} $ and is integrated forward in time along  $ v_{k_{n}^{lev2}} $ and is integrated forward in time along
605  the last sub-subsection, with the label $lev1$ for this    the last subsection, with the label $lev1$ for this  
606  intermediate loop.  intermediate loop.
607  Within this sub-subsection only, the model state is stored  Within this sub-subsection only, parts of the model state is stored
608  at every timestep  to memory at every timestep
609  [i.e. every hour $ i=0,...,5$ corresponding to  [i.e. every hour $ i=0,...,5$ corresponding to
610  $ k_{i}^{lev1} = 66, 67, \ldots, 71 $].  $ k_{i}^{lev1} = 66, 67, \ldots, 71 $].
611  Thus, the  final state $ v_n = v_{k_{n}^{lev1}} $ is reached  The  final state $ v_n = v_{k_{n}^{lev1}} $ is reached
612  and the model state of all proceeding timesteps along the last  and the model state of all preceding timesteps along the last
613  sub-subsections are available, enabling integration backwards  innermost subsection are available, enabling integration backwards
614  in time along the last sub-subsection.  in time along the last subsection.
615  Thus, the adjoint can be computed along this last  The adjoint can thus be computed along this last
616  sub-subsection $k_{n}^{lev2}$.  subsection $k_{n}^{lev2}$.
617  %  %
618  \end{itemize}  \end{itemize}
619  %  %
620  This procedure is repeated consecutively for each previous  This procedure is repeated consecutively for each previous
621  sub-subsection $k_{n-1}^{lev2}, \ldots, k_{1}^{lev2} $  subsection $k_{n-1}^{lev2}, \ldots, k_{1}^{lev2} $
622  carrying the adjoint computation to the initial time  carrying the adjoint computation to the initial time
623  of the subsection $k_{n}^{lev3}$.  of the subsection $k_{n}^{lev3}$.
624  Then, the procedure is repeated for the previous subsection  Then, the procedure is repeated for the previous subsection
# Line 627  $k_{1}^{lev3}$. Line 629  $k_{1}^{lev3}$.
629  For the full model trajectory of  For the full model trajectory of
630  $ n^{lev3} \cdot n^{lev2} \cdot n^{lev1} $ timesteps  $ n^{lev3} \cdot n^{lev2} \cdot n^{lev1} $ timesteps
631  the required storing of the model state was significantly reduced to  the required storing of the model state was significantly reduced to
632  $ n^{lev1} + n^{lev2} + n^{lev3} $  $ n^{lev2} + n^{lev3} $ to disk and roughly $ n^{lev1} $ to memory
633  [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
634  the model state was stored 13 times].  the model state was stored 7 times to disk and roughly 6 times
635    to memory].
636  This saving in memory comes at a cost of a required  This saving in memory comes at a cost of a required
637  3 full forward integrations of the model (one for each  3 full forward integrations of the model (one for each
638  checkpointing level).  checkpointing level).
639  The balance of storage vs. recomputation certainly depends  The optimal balance of storage vs. recomputation certainly depends
640  on the computing resources available.  on the computing resources available and may be adjusted by
641    adjusting the partitioning among the
642    $ n^{lev3}, \,\, n^{lev2}, \,\, n^{lev1} $.
643    
644  \begin{figure}[t!]  \begin{figure}[t!]
645  \begin{center}  \begin{center}
# Line 669  Schematic view of intermediate dump and Line 674  Schematic view of intermediate dump and
674  %**********************************************************************  %**********************************************************************
675  \section{TLM and ADM generation in general}  \section{TLM and ADM generation in general}
676  \label{sec_ad_setup_gen}  \label{sec_ad_setup_gen}
677    \begin{rawhtml}
678    <!-- CMIREDIR:sec_ad_setup_gen: -->
679    \end{rawhtml}
680  %**********************************************************************  %**********************************************************************
681    
682  In this section we describe in a general fashion  In this section we describe in a general fashion
683  the parts of the code that are relevant for automatic  the parts of the code that are relevant for automatic
684  differentiation using the software tool TAMC.  differentiation using the software tool TAF.
685    
686  \input{part5/doc_ad_the_model}  \input{part5/doc_ad_the_model}
687    
688  The basic flow is depicted in \ref{fig:adthemodel}.  The basic flow is depicted in \ref{fig:adthemodel}.
689  If the option {\tt ALLOW\_AUTODIFF\_TAMC} is defined, the driver routine  If CPP option \texttt{ALLOW\_AUTODIFF\_TAMC} is defined,
690    the driver routine
691  {\it the\_model\_main}, instead of calling {\it the\_main\_loop},  {\it the\_model\_main}, instead of calling {\it the\_main\_loop},
692  invokes the adjoint of this routine, {\it adthe\_main\_loop},  invokes the adjoint of this routine, {\it adthe\_main\_loop}
693  which is the toplevel routine in terms of reverse mode computation.  (case \texttt{\#define ALLOW\_ADJOINT\_RUN}), or
694  The routine {\it adthe\_main\_loop} has been generated using TAMC.  the tangent linear of this routine {\it g\_the\_main\_loop}
695  It contains both the forward integration of the full model,  (case \texttt{\#define ALLOW\_TANGENTLINEAR\_RUN}),
696    which are the toplevel routines in terms of automatic differentiation.
697    The routines {\it adthe\_main\_loop} or {\it g\_the\_main\_loop}
698    are generated by TAF.
699    It contains both the forward integration of the full model, the
700    cost function calculation,
701  any additional storing that is required for efficient checkpointing,  any additional storing that is required for efficient checkpointing,
702  and the reverse integration of the adjoint model.  and the reverse integration of the adjoint model.
703  The structure of {\it adthe\_main\_loop} has been strongly  
704  simplified for clarification; in particular, no checkpointing  [DESCRIBE IN A SEPARATE SECTION THE WORKING OF THE TLM]
705    
706    In Fig. \ref{fig:adthemodel}
707    the structure of {\it adthe\_main\_loop} has been strongly
708    simplified to focus on the essentials; in particular, no checkpointing
709  procedures are shown here.  procedures are shown here.
710  Prior to the call of {\it adthe\_main\_loop}, the routine  Prior to the call of {\it adthe\_main\_loop}, the routine
711  {\it ctrl\_unpack} is invoked to unpack the control vector,  {\it ctrl\_unpack} is invoked to unpack the control vector
712  and following that call, the routine {\it ctrl\_pack}  or initialise the control variables.
713    Following the call of {\it adthe\_main\_loop},
714    the routine {\it ctrl\_pack}
715  is invoked to pack the control vector  is invoked to pack the control vector
716  (cf. Section \ref{section_ctrl}).  (cf. Section \ref{section_ctrl}).
717  If gradient checks are to be performed, the option  If gradient checks are to be performed, the option
# Line 700  the driver routine {\it grdchk\_main} is Line 720  the driver routine {\it grdchk\_main} is
720  the gradient has been computed via the adjoint  the gradient has been computed via the adjoint
721  (cf. Section \ref{section_grdchk}).  (cf. Section \ref{section_grdchk}).
722    
723    %------------------------------------------------------------------
724    
725    \subsection{General setup
726    \label{section_ad_setup}}
727    
728    In order to configure AD-related setups the following packages need
729    to be enabled:
730    {\it
731    \begin{table}[h!]
732    \begin{tabular}{l}
733    autodiff \\
734    ctrl \\
735    cost \\
736    grdchk \\
737    \end{tabular}
738    \end{table}
739    }
740    The packages are enabled by adding them to your experiment-specific
741    configuration file
742    {\it packages.conf} (see Section ???).
743    
744    The following AD-specific CPP option files need to be customized:
745    %
746    \begin{itemize}
747    %
748    \item {\it ECCO\_CPPOPTIONS.h} \\
749    This header file collects CPP options for the packages
750    {\it autodiff, cost, ctrl} as well as AD-unrelated options for
751    the external forcing package {\it exf}.
752    \footnote{NOTE: These options are not set in their package-specific
753    headers such as {\it COST\_CPPOPTIONS.h}, but are instead collected
754    in the single header file {\it ECCO\_CPPOPTIONS.h}.
755    The package-specific header files serve as simple
756    placeholders at this point.}
757    %
758    \item {\it tamc.h} \\
759    This header configures the splitting of the time stepping loop
760    w.r.t. the 3-level checkpointing (see section ???).
761    
762    %
763    \end{itemize}
764    
765    %------------------------------------------------------------------
766    
767    \subsection{Building the AD code
768    \label{section_ad_build}}
769    
770    The build process of an AD code is very similar to building
771    the forward model. However, depending on which AD code one wishes
772    to generate, and on which AD tool is available (TAF or TAMC),
773    the following {\tt make} targets are available:
774    
775    \begin{table}[h!]
776    {\footnotesize
777    \begin{tabular}{ccll}
778    ~ & {\it AD-target} & {\it output} & {\it description} \\
779    \hline
780    \hline
781    (1) & {\tt <MODE><TOOL>only} & {\tt <MODE>\_<TOOL>\_output.f}  &
782    generates code for $<$MODE$>$ using $<$TOOL$>$ \\
783    ~ & ~ & ~ & no {\tt make} dependencies on {\tt .F .h} \\
784    ~ & ~ & ~ & useful for compiling on remote platforms \\
785    \hline
786    (2) & {\tt <MODE><TOOL>} & {\tt <MODE>\_<TOOL>\_output.f}  &
787    generates code for $<$MODE$>$ using $<$TOOL$>$ \\
788    ~ & ~ & ~ & includes {\tt make} dependencies on {\tt .F .h} \\
789    ~ & ~ & ~ & i.e. input for $<$TOOL$>$ may be re-generated \\
790    \hline
791    (3) & {\tt <MODE>all} & {\tt mitgcmuv\_<MODE>}  &
792    generates code for $<$MODE$>$ using $<$TOOL$>$ \\
793    ~ & ~ & ~ & and compiles all code \\
794    ~ & ~ & ~ & (use of TAF is set as default) \\
795    \hline
796    \hline
797    \end{tabular}
798    }
799    \end{table}
800    %
801    Here, the following placeholders are used
802    %
803    \begin{itemize}
804    %
805    \item [$<$TOOL$>$]
806    %
807    \begin{itemize}
808    %
809    \item {\tt TAF}
810    \item {\tt TAMC}
811    %
812    \end{itemize}
813    %
814    \item [$<$MODE$>$]
815    %
816    \begin{itemize}
817    %
818    \item {\tt ad} generates the adjoint model (ADM)
819    \item {\tt ftl} generates the tangent linear model (TLM)
820    \item {\tt svd} generates both ADM and TLM for \\
821    singular value decomposition (SVD) type calculations
822    %
823    \end{itemize}
824    %
825    \end{itemize}
826    
827    For example, to generate the adjoint model using TAF after routines ({\tt .F})
828    or headers ({\tt .h}) have been modified, but without compilation,
829    type {\tt make adtaf};
830    or, to generate the tangent linear model using TAMC without
831    re-generating the input code, type {\tt make ftltamconly}.
832    
833    
834    A typical full build process to generate the ADM via TAF would
835    look like follows:
836    \begin{verbatim}
837    % mkdir build
838    % cd build
839    % ../../../tools/genmake2 -mods=../code_ad
840    % make depend
841    % make adall
842    \end{verbatim}
843    
844    %------------------------------------------------------------------
845    
846    \subsection{The AD build process in detail
847    \label{section_ad_build_detail}}
848    
849    The {\tt make <MODE>all} target consists of the following procedures:
850    
851    \begin{enumerate}
852    %
853    \item
854    A header file {\tt AD\_CONFIG.h} is generated which contains a CPP option
855    on which code ought to be generated. Depending on the {\tt make} target,
856    the contents is
857    \begin{itemize}
858    \item
859    {\tt \#define ALLOW\_ADJOINT\_RUN}
860    \item
861    {\tt \#define ALLOW\_TANGENTLINEAR\_RUN}
862    \item
863    {\tt \#define ALLOW\_ECCO\_OPTIMIZATION}
864    \end{itemize}
865    %
866    \item
867    A single file {\tt <MODE>\_input\_code.f} is concatenated
868    consisting of all {\tt .f} files that are part of the list {\bf AD\_FILES}
869    and all {\tt .flow} files that are part of the list {\bf AD\_FLOW\_FILES}.
870    %
871    \item
872    The AD tool is invoked with the {\bf <MODE>\_<TOOL>\_FLAGS}.
873    The default AD tool flags in {\tt genmake2} can be overrwritten by
874    an {\tt adjoint\_options} file (similar to the platform-specific
875    {\tt build\_options}, see Section ???.
876    The AD tool writes the resulting AD code into the file
877    {\tt <MODE>\_input\_code\_ad.f}
878    %
879    \item
880    A short sed script {\tt adjoint\_sed} is applied to
881    {\tt <MODE>\_input\_code\_ad.f}
882    to reinstate {\bf myThid} into the CALL argument list of active file I/O.
883    The result is written to file {\tt <MODE>\_<TOOL>\_output.f}.
884    %
885    \item
886    All routines are compiled and an executable is generated
887    (see Table ???).
888    %
889    \end{enumerate}
890    
891    \subsubsection{The list AD\_FILES and {\tt .list} files}
892    
893    Not all routines are presented to the AD tool.
894    Routines typically hidden are diagnostics routines which
895    do not influence the cost function, but may create
896    artificial flow dependencies such as I/O of active variables.
897    
898    {\tt genmake2} generates a list (or variable) {\bf AD\_FILES}
899    which contains all routines that are shown to the AD tool.
900    This list is put together from all files with suffix {\tt .list}
901    that {\tt genmake2} finds in its search directories.
902    The list file for the core MITgcm routines is in {\tt model/src/}
903    is called {\tt model\_ad\_diff.list}.
904    Note that no wrapper routine is shown to TAF. These are either
905    not visible at all to the AD code, or hand-written AD code
906    is available (see next section).
907    
908    Each package directory contains its package-specific
909    list file {\tt <PKG>\_ad\_diff.list}. For example,
910    {\tt pkg/ptracers/} contains the file {\tt ptracers\_ad\_diff.list}.
911    Thus, enabling a package will automatically extend the
912    {\bf AD\_FILES} list of {\tt genmake2} to incorporate the
913    package-specific routines.
914    Note that you will need to regenerate the {\tt Makefile} if
915    you enable a package (e.g. by adding it to {\tt packages.conf})
916    and a {\tt Makefile} already exists.
917    
918    \subsubsection{The list AD\_FLOW\_FILES and {\tt .flow} files}
919    
920    TAMC and TAF can evaluate user-specified directives
921    that start with a specific syntax ({\tt CADJ}, {\tt C\$TAF}, {\tt !\$TAF}).
922    The main categories of directives are STORE directives and
923    FLOW directives. Here, we are concerned with flow directives,
924    store directives are treated elsewhere.
925    
926    Flow directives enable the AD tool to evaluate how it should treat
927    routines that are 'hidden' by the user, i.e. routines which are
928    not contained in the {\bf AD\_FILES} list (see previous section),
929    but which are called in part of the code that the AD tool does see.
930    The flow directive tell the AD tool
931    %
932    \begin{itemize}
933    %
934    \item which subroutine arguments are input/output
935    \item which subroutine arguments are active
936    \item which subroutine arguments are required to compute the cost
937    \item which subroutine arguments are dependent
938    %
939    \end{itemize}
940    %
941    The syntax for the flow directives can be found in the
942    AD tool manuals.
943    
944    {\tt genmake2} generates a list (or variable) {\bf AD\_FLOW\_FILES}
945    which contains all files with suffix{\tt .flow} that it finds
946    in its search directories.
947    The flow directives for the core MITgcm routines of
948    {\tt eesupp/src/} and {\tt model/src/}
949    reside in {\tt pkg/autodiff/}.
950    This directory also contains hand-written adjoint code
951    for the MITgcm WRAPPER (section \ref{chap:sarch}).
952    
953    Flow directives for package-specific routines are contained in
954    the corresponding package directories in the file
955    {\tt <PKG>\_ad.flow}, e.g. ptracers-specific directives are in
956    {\tt ptracers\_ad.flow}.
957    
958    \subsubsection{Store directives for 3-level checkpointing}
959    
960    The storing that is required at each period of the
961    3-level checkpointing is controled by three
962    top-level headers.
963    
964    \begin{verbatim}
965    do ilev_3 = 1, nchklev_3
966    #  include ``checkpoint_lev3.h''
967       do ilev_2 = 1, nchklev_2
968    #     include ``checkpoint_lev2.h''
969          do ilev_1 = 1, nchklev_1
970    #        include ``checkpoint_lev1.h''
971    
972    ...
973    
974          end do
975       end do
976    end do
977    \end{verbatim}
978    
979    All files {\tt checkpoint\_lev?.h} are contained in directory
980    {\tt pkg/autodiff/}.
981    
982    
983    \subsubsection{Changing the default AD tool flags: ad\_options files}
984    
985    
986    \subsubsection{Hand-written adjoint code}
987    
988    %------------------------------------------------------------------
989    
990  \subsection{The cost function (dependent variable)  \subsection{The cost function (dependent variable)
991  \label{section_cost}}  \label{section_cost}}
992    
993  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}.
994  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
995  $ {\cal J}(\vec{u}) \, = \, {\cal J}(M(\vec{u})) $.  $ {\cal J}(\vec{u}) \, = \, {\cal J}(M(\vec{u})) $.
996  The input is referred to as the  The input are referred to as the
997  {\sf independent variables} or {\sf control variables}.  {\sf independent variables} or {\sf control variables}.
998  All aspects relevant to the treatment of the cost function $ {\cal J} $  All aspects relevant to the treatment of the cost function $ {\cal J} $
999  (parameter setting, initialization, accumulation,  (parameter setting, initialization, accumulation,
1000  final evaluation), are controlled by the package {\it pkg/cost}.  final evaluation), are controlled by the package {\it pkg/cost}.
1001    The aspects relevant to the treatment of the independent variables
1002    are controlled by the package {\it pkg/ctrl} and will be treated
1003    in the next section.
1004    
1005  \input{part5/doc_cost_flow}  \input{part5/doc_cost_flow}
1006    
1007  \subsubsection{genmake and CPP options}  \subsubsection{Enabling the package}
1008  %  
 \begin{itemize}  
 %  
 \item  
1009  \fbox{  \fbox{
1010  \begin{minipage}{12cm}  \begin{minipage}{12cm}
1011  {\it genmake}, {\it CPP\_OPTIONS.h}, {\it ECCO\_CPPOPTIONS.h}  {\it packages.conf}, {\it ECCO\_CPPOPTIONS.h}
1012  \end{minipage}  \end{minipage}
1013  }  }
1014  \end{itemize}  \begin{itemize}
1015  %  %
1016  The directory {\it pkg/cost} can be included to the  \item
1017  compile list in 3 different ways (cf. Section \ref{???}):  The package is enabled by adding {\it cost} to your file {\it packages.conf}
1018    (see Section ???)
1019  %  %
1020  \begin{enumerate}  \item
1021  %  
1022  \item {\it genmake}: \\  
1023  Change the default settings in the file {\it genmake} by adding  \end{itemize}
 {\bf cost} to the {\bf enable} list (not recommended).  
 %  
 \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}.  
1024  %  %
1025  \end{enumerate}  
1026    N.B.: In general the following packages ought to be enabled
1027    simultaneously: {\it autodiff, cost, ctrl}.
1028  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}.
1029  Each specific cost function contribution has its own option.  Each specific cost function contribution has its own option.
1030  For the present example the option is {\bf ALLOW\_COST\_TRACER}.  For the present example the option is {\bf ALLOW\_COST\_TRACER}.
1031  All cost-specific options are set in {\it ECCO\_CPPOPTIONS.h}  All cost-specific options are set in {\it ECCO\_CPPOPTIONS.h}
1032  Since the cost function is usually used in conjunction with  Since the cost function is usually used in conjunction with
1033  automatic differentiation, the CPP option  automatic differentiation, the CPP option
1034  {\bf ALLOW\_ADJOINT\_RUN} should be defined  {\bf ALLOW\_ADJOINT\_RUN} (file {\it CPP\_OPTIONS.h}) and
1035  (file {\it CPP\_OPTIONS.h}).  {\bf ALLOW\_AUTODIFF\_TAMC} (file {\it ECCO\_CPPOPTIONS.h})
1036    should be defined.
1037    
1038  \subsubsection{Initialization}  \subsubsection{Initialization}
1039  %  %
1040  The initialization of the {\it cost} package is readily enabled  The initialization of the {\it cost} package is readily enabled
1041  as soon as the CPP option {\bf ALLOW\_ADJOINT\_RUN} is defined.  as soon as the CPP option {\bf ALLOW\_COST} is defined.
1042  %  %
1043  \begin{itemize}  \begin{itemize}
1044  %  %
# Line 831  from each contribution and sums over all Line 1112  from each contribution and sums over all
1112  \begin{equation}  \begin{equation}
1113  {\cal J} \, = \,  {\cal J} \, = \,
1114  {\rm fc} \, = \,  {\rm fc} \, = \,
1115  {\rm mult\_tracer} \sum_{bi,\,bj}^{nSx,\,nSy}  {\rm mult\_tracer} \sum_{\text{global sum}} \sum_{bi,\,bj}^{nSx,\,nSy}
1116  {\rm objf\_tracer}(bi,bj) \, + \, ...  {\rm objf\_tracer}(bi,bj) \, + \, ...
1117  \end{equation}  \end{equation}
1118  %  %
# Line 879  are controlled by the package {\it pkg/c Line 1160  are controlled by the package {\it pkg/c
1160  %  %
1161  To enable the directory to be included to the compile list,  To enable the directory to be included to the compile list,
1162  {\bf ctrl} has to be added to the {\bf enable} list in  {\bf ctrl} has to be added to the {\bf enable} list in
1163  {\it .genmakerc} (or {\it genmake} itself).  {\it .genmakerc} or in {\it genmake} itself (analogous to {\it cost}
1164    package, cf. previous section).
1165  Each control variable is enabled via its own CPP option  Each control variable is enabled via its own CPP option
1166  in {\it ECCO\_CPPOPTIONS.h}.  in {\it ECCO\_CPPOPTIONS.h}.
1167    
# Line 920  and their gradients: {\it ctrl\_unpack} Line 1202  and their gradients: {\it ctrl\_unpack}
1202  \\  \\
1203  %  %
1204  Two important issues related to the handling of the control  Two important issues related to the handling of the control
1205  variables in the MITGCM need to be addressed.  variables in MITgcm need to be addressed.
1206  First, in order to save memory, the control variable arrays  First, in order to save memory, the control variable arrays
1207  are not kept in memory, but rather read from file and added  are not kept in memory, but rather read from file and added
1208  to the initial fields during the model initialization phase.  to the initial fields during the model initialization phase.
# Line 995  when calling TAMC: Line 1277  when calling TAMC:
1277  tamc -input 'xx_tr1 ...' ...  tamc -input 'xx_tr1 ...' ...
1278  \end{verbatim}  \end{verbatim}
1279  %  %
1280  Now, as mentioned above, the MITGCM avoids maintaining  Now, as mentioned above, MITgcm avoids maintaining
1281  an array for each control variable by reading the  an array for each control variable by reading the
1282  perturbation to a temporary array from file.  perturbation to a temporary array from file.
1283  To ensure the symbolic link to be recognized by TAMC, a scalar  To ensure the symbolic link to be recognized by TAMC, a scalar
# Line 1023  in the code takes on the form Line 1305  in the code takes on the form
1305  %  %
1306  Note, that reading an active variable corresponds  Note, that reading an active variable corresponds
1307  to a variable assignment. Its derivative corresponds  to a variable assignment. Its derivative corresponds
1308  to a write statement of the adjoint variable.  to a write statement of the adjoint variable, followed by
1309    a reset.
1310  The 'active file' routines have been designed  The 'active file' routines have been designed
1311  to support active read and corresponding adjoint active write  to support active read and corresponding adjoint active write
1312  operations (and vice versa).  operations (and vice versa).
# Line 1140  at intermediate times can be written usi Line 1423  at intermediate times can be written usi
1423  {\it addummy\_in\_stepping}.  {\it addummy\_in\_stepping}.
1424  This routine is part of the adjoint support package  This routine is part of the adjoint support package
1425  {\it pkg/autodiff} (cf.f. below).  {\it pkg/autodiff} (cf.f. below).
1426    The procedure is enabled using via the CPP-option
1427    {\bf ALLOW\_AUTODIFF\_MONITOR} (file {\it ECCO\_CPPOPTIONS.h}).
1428  To be part of the adjoint code, the corresponding S/R  To be part of the adjoint code, the corresponding S/R
1429  {\it dummy\_in\_stepping} has to be called in the forward  {\it dummy\_in\_stepping} has to be called in the forward
1430  model (S/R {\it the\_main\_loop}) at the appropriate place.  model (S/R {\it the\_main\_loop}) at the appropriate place.
1431    The adjoint common blocks are extracted from the adjoint code
1432    via the header file {\it adcommon.h}.
1433    
1434  {\it dummy\_in\_stepping} is essentially empty,  {\it dummy\_in\_stepping} is essentially empty,
1435  the corresponding adjoint routine is hand-written rather  the corresponding adjoint routine is hand-written rather
# Line 1169  the common blocks Line 1456  the common blocks
1456  {\bf /adtr1\_r/}, {\bf /adffields/},  {\bf /adtr1\_r/}, {\bf /adffields/},
1457  which have been extracted from the adjoint code to enable  which have been extracted from the adjoint code to enable
1458  access to the adjoint variables.  access to the adjoint variables.
1459    
1460    {\bf WARNING:} If the structure of the common blocks
1461    {\bf /dynvars\_r/}, {\bf /dynvars\_cd/}, etc., changes
1462    similar changes will occur in the adjoint common blocks.
1463    Therefore, consistency between the TAMC-generated common blocks
1464    and those in {\it adcommon.h} have to be checked.
1465  %  %
1466  \end{itemize}  \end{itemize}
1467    
Legend:
Removed from v.1.14  
changed lines
  Added in v.1.20
  ViewVC Help
Powered by ViewVC 1.1.22