| 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 succssor 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 senistivity |
\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 |
|
As of mid-2007 we are also able to generate fairly efficient |
| 31 |
TAMC exploits the chain rule for computing the first |
adjoint code of the MITgcm using a new, open-source AD tool, |
| 32 |
derivative of a function with |
called OpenAD (see \cite{naum-etal:06,utke-etal:08}. |
| 33 |
respect to a set of input variables. |
This enables us for the first time to compare adjoint models |
| 34 |
Treating a given forward code as a composition of operations -- |
generated from different AD tools, providing an additional |
| 35 |
each line representing a compositional element -- the chain rule is |
accuracy check, complementary to finite-difference gradient checks. |
| 36 |
rigorously applied to the code, line by line. The resulting |
OpenAD and its application to MITgcm is described in detail |
| 37 |
tangent linear or adjoint code, |
in section \ref{sec_ad_openad}. |
| 38 |
then, may be thought of as the composition in |
|
| 39 |
forward or reverse order, respectively, of the |
The AD tool exploits the chain rule for computing the first derivative of a |
| 40 |
Jacobian matrices of the forward code compositional elements. |
function with respect to a set of input variables. Treating a given |
| 41 |
|
forward code as a composition of operations -- each line representing |
| 42 |
|
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 |
| 61 |
such as forcing functions) to the $n$-dimensional space |
such as forcing functions) to the $n$-dimensional space |
| 62 |
$V \subset I\!\!R^n$ of |
$V \subset I\!\!R^n$ of |
| 63 |
model output variable $\vec{v}=(v_1,\ldots,v_n)$ |
model output variable $\vec{v}=(v_1,\ldots,v_n)$ |
| 64 |
(model state, model diagnostcs, objective function, ...) |
(model state, model diagnostics, objective function, ...) |
| 65 |
under consideration, |
under consideration, |
| 66 |
% |
% |
| 67 |
\begin{equation} |
\begin{equation} |
| 116 |
$ M $ is just a matrix |
$ M $ is just a matrix |
| 117 |
which can readily be used to find the forward sensitivity of $\vec{v}$ to |
which can readily be used to find the forward sensitivity of $\vec{v}$ to |
| 118 |
perturbations in $u$, |
perturbations in $u$, |
| 119 |
but if there are very many input variables $(>>O(10^{6})$ for |
but if there are very many input variables $(\gg O(10^{6})$ for |
| 120 |
large-scale oceanographic application), it quickly becomes |
large-scale oceanographic application), it quickly becomes |
| 121 |
prohibitive to proceed directly as in (\ref{tangent_linear}), |
prohibitive to proceed directly as in (\ref{tangent_linear}), |
| 122 |
if the impact of each component $ {\bf e_{i}} $ is to be assessed. |
if the impact of each component $ {\bf e_{i}} $ is to be assessed. |
| 141 |
\label{compo} |
\label{compo} |
| 142 |
\end{eqnarray} |
\end{eqnarray} |
| 143 |
% |
% |
| 144 |
The linear approximation of $ {\cal J} $, |
The perturbation of $ {\cal J} $ around a fixed point $ {\cal J}_0 $, |
| 145 |
\[ |
\[ |
| 146 |
{\cal J} \, \approx \, {\cal J}_0 \, + \, \delta {\cal J} |
{\cal J} \, = \, {\cal J}_0 \, + \, \delta {\cal J} |
| 147 |
\] |
\] |
| 148 |
can be expressed in both bases of $ \vec{u} $ and $ \vec{v} $ |
can be expressed in both bases of $ \vec{u} $ and $ \vec{v} $ |
| 149 |
w.r.t. their corresponding inner product |
w.r.t. their corresponding inner product |
| 163 |
\label{deljidentity} |
\label{deljidentity} |
| 164 |
\end{equation} |
\end{equation} |
| 165 |
% |
% |
| 166 |
(note, that the gradient $ \nabla f $ is a pseudo-vector, therefore |
(note, that the gradient $ \nabla f $ is a co-vector, therefore |
| 167 |
its transpose is required in the above inner product). |
its transpose is required in the above inner product). |
| 168 |
Then, using the representation of |
Then, using the representation of |
| 169 |
$ \delta {\cal J} = |
$ \delta {\cal J} = |
| 179 |
\[ |
\[ |
| 180 |
A^{\ast} \, = \, A^T |
A^{\ast} \, = \, A^T |
| 181 |
\] |
\] |
| 182 |
and from eq. (\ref{tangent_linear}), we note that |
and from eq. (\ref{tangent_linear}), (\ref{deljidentity}), |
| 183 |
|
we note that |
| 184 |
(omitting $|$'s): |
(omitting $|$'s): |
| 185 |
% |
% |
| 186 |
\begin{equation} |
\begin{equation} |
| 216 |
$ \delta \vec{u}^{\ast} $ the adjoint variable of the control variable $ \vec{u} $. |
$ \delta \vec{u}^{\ast} $ the adjoint variable of the control variable $ \vec{u} $. |
| 217 |
|
|
| 218 |
The {\sf reverse} nature of the adjoint calculation can be readily |
The {\sf reverse} nature of the adjoint calculation can be readily |
| 219 |
seen as follows. Let us decompose ${\cal J}(u)$, thus: |
seen as follows. |
| 220 |
|
Consider a model integration which consists of $ \Lambda $ |
| 221 |
|
consecutive operations |
| 222 |
|
$ {\cal M}_{\Lambda} ( {\cal M}_{\Lambda-1} ( |
| 223 |
|
...... ( {\cal M}_{\lambda} ( |
| 224 |
|
...... |
| 225 |
|
( {\cal M}_{1} ( {\cal M}_{0}(\vec{u}) )))) $, |
| 226 |
|
where the ${\cal M}$'s could be the elementary steps, i.e. single lines |
| 227 |
|
in the code of the model, or successive time steps of the |
| 228 |
|
model integration, |
| 229 |
|
starting at step 0 and moving up to step $\Lambda$, with intermediate |
| 230 |
|
${\cal M}_{\lambda} (\vec{u}) = \vec{v}^{(\lambda+1)}$ and final |
| 231 |
|
${\cal M}_{\Lambda} (\vec{u}) = \vec{v}^{(\Lambda+1)} = \vec{v}$. |
| 232 |
|
Let ${\cal J}$ be a cost function which explicitly depends on the |
| 233 |
|
final state $\vec{v}$ only |
| 234 |
|
(this restriction is for clarity reasons only). |
| 235 |
|
% |
| 236 |
|
${\cal J}(u)$ may be decomposed according to: |
| 237 |
% |
% |
| 238 |
\begin{equation} |
\begin{equation} |
| 239 |
{\cal J}({\cal M}(\vec{u})) \, = \, |
{\cal J}({\cal M}(\vec{u})) \, = \, |
| 244 |
\label{compos} |
\label{compos} |
| 245 |
\end{equation} |
\end{equation} |
| 246 |
% |
% |
| 247 |
where the ${\cal M}$'s could be the elementary steps, i.e. single lines |
Then, according to the chain rule, the forward calculation reads, |
| 248 |
in the code of the model, |
in terms of the Jacobi matrices |
|
starting at step 0 and moving up to step $\Lambda$, with intermediate |
|
|
${\cal M}_{\lambda} (\vec{u}) = \vec{v}^{(\lambda+1)}$ and final |
|
|
${\cal M}_{\Lambda} (\vec{u}) = \vec{v}^{(\Lambda+1)} = \vec{v}$ |
|
|
Then, according to the chain rule the forward calculation reads in |
|
|
terms of the Jacobi matrices |
|
| 249 |
(we've omitted the $ | $'s which, nevertheless are important |
(we've omitted the $ | $'s which, nevertheless are important |
| 250 |
to the aspect of {\it tangent} linearity; |
to the aspect of {\it tangent} linearity; |
| 251 |
note also that per definition |
note also that by definition |
| 252 |
$ \langle \, \nabla _{v}{\cal J}^T \, , \, \delta \vec{v} \, \rangle |
$ \langle \, \nabla _{v}{\cal J}^T \, , \, \delta \vec{v} \, \rangle |
| 253 |
= \nabla_v {\cal J} \cdot \delta \vec{v} $ ) |
= \nabla_v {\cal J} \cdot \delta \vec{v} $ ) |
| 254 |
% |
% |
| 283 |
% |
% |
| 284 |
clearly expressing the reverse nature of the calculation. |
clearly expressing the reverse nature of the calculation. |
| 285 |
Eq. (\ref{reverse}) is at the heart of automatic adjoint compilers. |
Eq. (\ref{reverse}) is at the heart of automatic adjoint compilers. |
| 286 |
The intermediate steps $\lambda$ in |
If the intermediate steps $\lambda$ in |
| 287 |
eqn. (\ref{compos}) -- (\ref{reverse}) |
eqn. (\ref{compos}) -- (\ref{reverse}) |
| 288 |
could represent the model state (forward or adjoint) at each |
represent the model state (forward or adjoint) at each |
| 289 |
intermediate time step in which case |
intermediate time step as noted above, then correspondingly, |
| 290 |
$ {\cal M}(\vec{v}^{(\lambda)}) = \vec{v}^{(\lambda+1)} $, and correspondingly, |
$ M^T (\delta \vec{v}^{(\lambda) \, \ast}) = |
| 291 |
$ M^T (\delta \vec{v}^{(\lambda) \, \ast}) = \delta \vec{v}^{(\lambda-1) \, \ast} $, |
\delta \vec{v}^{(\lambda-1) \, \ast} $ for the adjoint variables. |
| 292 |
but they can also be viewed more generally as |
It thus becomes evident that the adjoint calculation also |
| 293 |
single lines of code in the numerical algorithm. |
yields the adjoint of each model state component |
| 294 |
In both cases it becomes evident that the adjoint calculation |
$ \vec{v}^{(\lambda)} $ at each intermediate step $ \lambda $, namely |
|
yields at the same time the adjoint of each model state component |
|
|
$ \vec{v}^{(\lambda)} $ at each intermediate step $ l $, namely |
|
| 295 |
% |
% |
| 296 |
\begin{equation} |
\begin{equation} |
| 297 |
\boxed{ |
\boxed{ |
| 307 |
% |
% |
| 308 |
in close analogy to eq. (\ref{adjoint}) |
in close analogy to eq. (\ref{adjoint}) |
| 309 |
We note in passing that that the $\delta \vec{v}^{(\lambda) \, \ast}$ |
We note in passing that that the $\delta \vec{v}^{(\lambda) \, \ast}$ |
| 310 |
are the Lagrange multipliers of the model state $ \vec{v}^{(\lambda)}$. |
are the Lagrange multipliers of the model equations which determine |
| 311 |
|
$ \vec{v}^{(\lambda)}$. |
| 312 |
|
|
| 313 |
In coponents, eq. (\ref{adjoint}) reads as follows. |
In components, eq. (\ref{adjoint}) reads as follows. |
| 314 |
Let |
Let |
| 315 |
\[ |
\[ |
| 316 |
\begin{array}{rclcrcl} |
\begin{array}{rclcrcl} |
| 331 |
\end{array} |
\end{array} |
| 332 |
\] |
\] |
| 333 |
denote the perturbations in $\vec{u}$ and $\vec{v}$, respectively, |
denote the perturbations in $\vec{u}$ and $\vec{v}$, respectively, |
| 334 |
and their adjoint varaiables; |
and their adjoint variables; |
| 335 |
further |
further |
| 336 |
\[ |
\[ |
| 337 |
M \, = \, \left( |
M \, = \, \left( |
| 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 |
\[ |
\begin{equation} |
| 422 |
\footnotesize |
\small |
| 423 |
|
\begin{split} |
| 424 |
\left( |
\left( |
| 425 |
\begin{array}{c} |
\begin{array}{c} |
| 426 |
\delta v^{(\lambda) \, \ast}_1 \\ |
\delta v^{(\lambda) \, \ast}_1 \\ |
| 428 |
\delta v^{(\lambda) \, \ast}_{n_{\lambda}} \\ |
\delta v^{(\lambda) \, \ast}_{n_{\lambda}} \\ |
| 429 |
\end{array} |
\end{array} |
| 430 |
\right) |
\right) |
| 431 |
\, = \, |
\, = & |
| 432 |
\left( |
\left( |
| 433 |
\begin{array}{ccc} |
\begin{array}{ccc} |
| 434 |
\frac{\partial ({\cal M}_{\lambda})_1}{\partial v^{(\lambda)}_1} |
\frac{\partial ({\cal M}_{\lambda})_1}{\partial v^{(\lambda)}_1} |
| 435 |
& \ldots & |
& \ldots \,\, \ldots & |
| 436 |
\frac{\partial ({\cal M}_{\lambda})_{n_{\lambda+1}}}{\partial v^{(\lambda)}_1} \\ |
\frac{\partial ({\cal M}_{\lambda})_{n_{\lambda+1}}}{\partial v^{(\lambda)}_1} \\ |
| 437 |
\vdots & ~ & \vdots \\ |
\vdots & ~ & \vdots \\ |
| 438 |
\frac{\partial ({\cal M}_{\lambda})_1}{\partial v^{(\lambda)}_{n_{\lambda}}} |
\frac{\partial ({\cal M}_{\lambda})_1}{\partial v^{(\lambda)}_{n_{\lambda}}} |
| 439 |
& \ldots & |
& \ldots \,\, \ldots & |
| 440 |
\frac{\partial ({\cal M}_{\lambda})_{n_{\lambda+1}}}{\partial v^{(\lambda)}_{n_{\lambda}}} \\ |
\frac{\partial ({\cal M}_{\lambda})_{n_{\lambda+1}}}{\partial v^{(\lambda)}_{n_{\lambda}}} \\ |
| 441 |
\end{array} |
\end{array} |
| 442 |
\right) |
\right) |
|
% |
|
| 443 |
\cdot |
\cdot |
| 444 |
% |
% |
| 445 |
|
\\ ~ & ~ |
| 446 |
|
\\ ~ & |
| 447 |
|
% |
| 448 |
\left( |
\left( |
| 449 |
\begin{array}{ccc} |
\begin{array}{ccc} |
| 450 |
\frac{\partial ({\cal M}_{\lambda+1})_1}{\partial v^{(\lambda+1)}_1} |
\frac{\partial ({\cal M}_{\lambda+1})_1}{\partial v^{(\lambda+1)}_1} |
| 457 |
\frac{\partial ({\cal M}_{\lambda+1})_{n_{\lambda+2}}}{\partial v^{(\lambda+1)}_{n_{\lambda+1}}} \\ |
\frac{\partial ({\cal M}_{\lambda+1})_{n_{\lambda+2}}}{\partial v^{(\lambda+1)}_{n_{\lambda+1}}} \\ |
| 458 |
\end{array} |
\end{array} |
| 459 |
\right) |
\right) |
| 460 |
\cdot \ldots \ldots \cdot |
\cdot \, \ldots \, \cdot |
| 461 |
\left( |
\left( |
| 462 |
\begin{array}{c} |
\begin{array}{c} |
| 463 |
\delta v^{\ast}_1 \\ |
\delta v^{\ast}_1 \\ |
| 465 |
\delta v^{\ast}_{n} \\ |
\delta v^{\ast}_{n} \\ |
| 466 |
\end{array} |
\end{array} |
| 467 |
\right) |
\right) |
| 468 |
\] |
\end{split} |
| 469 |
|
\end{equation} |
| 470 |
|
|
| 471 |
Eq. (\ref{forward}) and (\ref{reverse}) are perhaps clearest in |
Eq. (\ref{forward}) and (\ref{reverse}) are perhaps clearest in |
| 472 |
showing the advantage of the reverse over the forward mode |
showing the advantage of the reverse over the forward mode |
| 477 |
{\it all} intermediate states $ \vec{v}^{(\lambda)} $) are sought. |
{\it all} intermediate states $ \vec{v}^{(\lambda)} $) are sought. |
| 478 |
In order to be able to solve for each component of the gradient |
In order to be able to solve for each component of the gradient |
| 479 |
$ \partial {\cal J} / \partial u_{i} $ in (\ref{forward}) |
$ \partial {\cal J} / \partial u_{i} $ in (\ref{forward}) |
| 480 |
a forward calulation has to be performed for each component seperately, |
a forward calculation has to be performed for each component separately, |
| 481 |
i.e. $ \delta \vec{u} = \delta u_{i} {\vec{e}_{i}} $ |
i.e. $ \delta \vec{u} = \delta u_{i} {\vec{e}_{i}} $ |
| 482 |
for the $i$-th forward calculation. |
for the $i$-th forward calculation. |
| 483 |
Then, (\ref{forward}) represents the |
Then, (\ref{forward}) represents the |
| 487 |
gradient $\nabla _{u}{\cal J}$ (and all intermediate gradients |
gradient $\nabla _{u}{\cal J}$ (and all intermediate gradients |
| 488 |
$\nabla _{v^{(\lambda)}}{\cal J}$) within a single reverse calculation. |
$\nabla _{v^{(\lambda)}}{\cal J}$) within a single reverse calculation. |
| 489 |
|
|
| 490 |
Note, that in case $ {\cal J} $ is a vector-valued function |
Note, that if $ {\cal J} $ is a vector-valued function |
| 491 |
of dimension $ l > 1 $, |
of dimension $ l > 1 $, |
| 492 |
eq. (\ref{reverse}) has to be modified according to |
eq. (\ref{reverse}) has to be modified according to |
| 493 |
\[ |
\[ |
| 495 |
\, = \, |
\, = \, |
| 496 |
\nabla_u {\cal J}^T \cdot \delta \vec{J} |
\nabla_u {\cal J}^T \cdot \delta \vec{J} |
| 497 |
\] |
\] |
| 498 |
where now $ \delta \vec{J} \in I\!\!R $ is a vector of dimenison $ l $. |
where now $ \delta \vec{J} \in I\!\!R^l $ is a vector of |
| 499 |
|
dimension $ l $. |
| 500 |
In this case $ l $ reverse simulations have to be performed |
In this case $ l $ reverse simulations have to be performed |
| 501 |
for each $ \delta J_{k}, \,\, k = 1, \ldots, l $. |
for each $ \delta J_{k}, \,\, k = 1, \ldots, l $. |
| 502 |
Then, the reverse mode is more efficient as long as |
Then, the reverse mode is more efficient as long as |
| 503 |
$ l < n $, otherwise the forward mode is preferable. |
$ l < n $, otherwise the forward mode is preferable. |
| 504 |
Stricly, the reverse mode is called adjoint mode only for |
Strictly, the reverse mode is called adjoint mode only for |
| 505 |
$ l = 1 $. |
$ l = 1 $. |
| 506 |
|
|
| 507 |
A detailed analysis of the underlying numerical operations |
A detailed analysis of the underlying numerical operations |
| 531 |
\paragraph{Example 2: |
\paragraph{Example 2: |
| 532 |
$ {\cal J} = \langle \, {\cal H}(\vec{v}) - \vec{d} \, , |
$ {\cal J} = \langle \, {\cal H}(\vec{v}) - \vec{d} \, , |
| 533 |
\, {\cal H}(\vec{v}) - \vec{d} \, \rangle $} ~ \\ |
\, {\cal H}(\vec{v}) - \vec{d} \, \rangle $} ~ \\ |
| 534 |
The cost function represents the quadratic model vs.data misfit. |
The cost function represents the quadratic model vs. data misfit. |
| 535 |
Here, $ \vec{d} $ is the data vector and $ {\cal H} $ represents the |
Here, $ \vec{d} $ is the data vector and $ {\cal H} $ represents the |
| 536 |
operator which maps the model state space onto the data space. |
operator which maps the model state space onto the data space. |
| 537 |
Then, $ \nabla_v {\cal J} $ takes the form |
Then, $ \nabla_v {\cal J} $ takes the form |
| 562 |
|
|
| 563 |
We note an important aspect of the forward vs. reverse |
We note an important aspect of the forward vs. reverse |
| 564 |
mode calculation. |
mode calculation. |
| 565 |
Because of the locality of the derivative, |
Because of the local character of the derivative |
| 566 |
|
(a derivative is defined w.r.t. a point along the trajectory), |
| 567 |
the intermediate results of the model trajectory |
the intermediate results of the model trajectory |
| 568 |
$\vec{v}^{(\lambda+1)}={\cal M}_{\lambda}(v^{(\lambda)})$ |
$\vec{v}^{(\lambda+1)}={\cal M}_{\lambda}(v^{(\lambda)})$ |
| 569 |
are needed to evaluate the intermediate Jacobian |
may be required to evaluate the intermediate Jacobian |
| 570 |
$M_{\lambda}|_{\vec{v}^{(\lambda)}} \, \delta \vec{v}^{(\lambda)} $. |
$M_{\lambda}|_{\vec{v}^{(\lambda)}} \, \delta \vec{v}^{(\lambda)} $. |
| 571 |
|
This is the case e.g. for nonlinear expressions |
| 572 |
|
(momentum advection, nonlinear equation of state), state-dependent |
| 573 |
|
conditional statements (parameterization schemes). |
| 574 |
In the forward mode, the intermediate results are required |
In the forward mode, the intermediate results are required |
| 575 |
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}$, |
| 576 |
in the reverse mode they are required in the reverse order. |
but in the reverse mode they are required in the reverse order. |
| 577 |
Thus, in the reverse mode the trajectory of the forward model |
Thus, in the reverse mode the trajectory of the forward model |
| 578 |
integration ${\cal M}$ has to be stored to be available in the reverse |
integration ${\cal M}$ has to be stored to be available in the reverse |
| 579 |
calculation. Alternatively, the model state would have to be |
calculation. Alternatively, the complete model state up to the |
| 580 |
recomputed whenever its value is required. |
point of evaluation has to be recomputed whenever its value is required. |
| 581 |
|
|
| 582 |
A method to balance the amount of recomputations vs. |
A method to balance the amount of recomputations vs. |
| 583 |
storage requirements is called {\sf checkpointing} |
storage requirements is called {\sf checkpointing} |
| 584 |
(e.g. \cite{res-eta:98}). |
(e.g. \cite{gri:92}, \cite{res-eta:98}). |
| 585 |
It is depicted in Fig. ... for a 3-level checkpointing |
It is depicted in \ref{fig:3levelcheck} for a 3-level checkpointing |
| 586 |
[as concrete example, we give explicit numbers for a 3-day |
[as an example, we give explicit numbers for a 3-day |
| 587 |
integration with a 1-hourly timestep in square brackets]. |
integration with a 1-hourly timestep in square brackets]. |
| 588 |
\begin{itemize} |
\begin{itemize} |
| 589 |
% |
% |
| 591 |
In a first step, the model trajectory is subdivided into |
In a first step, the model trajectory is subdivided into |
| 592 |
$ {n}^{lev3} $ subsections [$ {n}^{lev3} $=3 1-day intervals], |
$ {n}^{lev3} $ subsections [$ {n}^{lev3} $=3 1-day intervals], |
| 593 |
with the label $lev3$ for this outermost loop. |
with the label $lev3$ for this outermost loop. |
| 594 |
The model is then integrated over the full trajectory, |
The model is then integrated along the full trajectory, |
| 595 |
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 |
| 596 |
[i.e. 3 times, at |
[i.e. 3 times, at |
| 597 |
$ i = 0,1,2 $ corresponding to $ k_{i}^{lev3} = 0, 24, 48 $]. |
$ i = 0,1,2 $ corresponding to $ k_{i}^{lev3} = 0, 24, 48 $]. |
| 598 |
|
In addition, the cost function is computed, if needed. |
| 599 |
% |
% |
| 600 |
\item [$lev2$] |
\item [$lev2$] |
| 601 |
In a second step each subsection is itself divided into |
In a second step each subsection itself is divided into |
| 602 |
$ {n}^{lev2} $ subsubsections |
$ {n}^{lev2} $ subsections |
| 603 |
[$ {n}^{lev2} $=4 6-hour intervals per subsection]. |
[$ {n}^{lev2} $=4 6-hour intervals per subsection]. |
| 604 |
The model picks up at the last outermost dumped state |
The model picks up at the last outermost dumped state |
| 605 |
$ v_{k_{n}^{lev3}} $ and is integrated forward in time over |
$ v_{k_{n}^{lev3}} $ and is integrated forward in time along |
| 606 |
the last subsection, with the label $lev2$ for this |
the last subsection, with the label $lev2$ for this |
| 607 |
intermediate loop. |
intermediate loop. |
| 608 |
The model state is now stored only at every $ k_{i}^{lev2} $-th |
The model state is now stored to disk at every $ k_{i}^{lev2} $-th |
| 609 |
timestep |
timestep |
| 610 |
[i.e. 4 times, at |
[i.e. 4 times, at |
| 611 |
$ 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 $]. |
| 612 |
% |
% |
| 613 |
\item [$lev1$] |
\item [$lev1$] |
| 614 |
Finally, the mode picks up at the last intermediate dump state |
Finally, the model picks up at the last intermediate dump state |
| 615 |
$ v_{k_{n}^{lev2}} $ and is integrated forward in time over |
$ v_{k_{n}^{lev2}} $ and is integrated forward in time along |
| 616 |
the last subsubsection, with the label $lev1$ for this |
the last subsection, with the label $lev1$ for this |
| 617 |
intermediate loop. |
intermediate loop. |
| 618 |
Within this subsubsection only, the model state is stored |
Within this sub-subsection only, parts of the model state is stored |
| 619 |
at every timestep |
to memory at every timestep |
| 620 |
[i.e. every hour $ i=0,...,5$ corresponding to |
[i.e. every hour $ i=0,...,5$ corresponding to |
| 621 |
$ k_{i}^{lev1} = 66, 67, \ldots, 71 $]. |
$ k_{i}^{lev1} = 66, 67, \ldots, 71 $]. |
| 622 |
Thus, the final state $ v_n = v_{k_{n}^{lev1}} $ is reached |
The final state $ v_n = v_{k_{n}^{lev1}} $ is reached |
| 623 |
and the model state of all peceeding timesteps over the last |
and the model state of all preceding timesteps along the last |
| 624 |
subsubsections are available, enabling integration backwards |
innermost subsection are available, enabling integration backwards |
| 625 |
in time over the last subsubsection. |
in time along the last subsection. |
| 626 |
Thus, the adjoint can be computed over this last |
The adjoint can thus be computed along this last |
| 627 |
subsubsection $k_{n}^{lev2}$. |
subsection $k_{n}^{lev2}$. |
| 628 |
% |
% |
| 629 |
\end{itemize} |
\end{itemize} |
| 630 |
% |
% |
| 631 |
This procedure is repeated consecutively for each previous |
This procedure is repeated consecutively for each previous |
| 632 |
subsubsection $k_{n-1}^{lev2}, \ldots, k_{1}^{lev2} $ |
subsection $k_{n-1}^{lev2}, \ldots, k_{1}^{lev2} $ |
| 633 |
carrying the adjoint computation to the initial time |
carrying the adjoint computation to the initial time |
| 634 |
of the subsection $k_{n}^{lev3}$. |
of the subsection $k_{n}^{lev3}$. |
| 635 |
Then, the procedure is repeated for the previous subsection |
Then, the procedure is repeated for the previous subsection |
| 640 |
For the full model trajectory of |
For the full model trajectory of |
| 641 |
$ n^{lev3} \cdot n^{lev2} \cdot n^{lev1} $ timesteps |
$ n^{lev3} \cdot n^{lev2} \cdot n^{lev1} $ timesteps |
| 642 |
the required storing of the model state was significantly reduced to |
the required storing of the model state was significantly reduced to |
| 643 |
$ n^{lev1} + n^{lev2} + n^{lev3} $ |
$ n^{lev2} + n^{lev3} $ to disk and roughly $ n^{lev1} $ to memory |
| 644 |
[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 |
| 645 |
the model state was stored 13 times]. |
the model state was stored 7 times to disk and roughly 6 times |
| 646 |
|
to memory]. |
| 647 |
This saving in memory comes at a cost of a required |
This saving in memory comes at a cost of a required |
| 648 |
3 full forward integrations of the model (one for each |
3 full forward integrations of the model (one for each |
| 649 |
checkpointing level). |
checkpointing level). |
| 650 |
The balance of storage vs. recomputation certainly depends |
The optimal balance of storage vs. recomputation certainly depends |
| 651 |
on the computing resources available. |
on the computing resources available and may be adjusted by |
| 652 |
|
adjusting the partitioning among the |
| 653 |
|
$ n^{lev3}, \,\, n^{lev2}, \,\, n^{lev1} $. |
| 654 |
|
|
| 655 |
\begin{figure}[t!] |
\begin{figure}[t!] |
| 656 |
\centering |
\begin{center} |
| 657 |
%\psdraft |
%\psdraft |
| 658 |
\psfrag{v_k1^lev3}{\mathinfigure{v_{k_{1}^{lev3}}}} |
%\psfrag{v_k1^lev3}{\mathinfigure{v_{k_{1}^{lev3}}}} |
| 659 |
\psfrag{v_kn-1^lev3}{\mathinfigure{v_{k_{n-1}^{lev3}}}} |
%\psfrag{v_kn-1^lev3}{\mathinfigure{v_{k_{n-1}^{lev3}}}} |
| 660 |
\psfrag{v_kn^lev3}{\mathinfigure{v_{k_{n}^{lev3}}}} |
%\psfrag{v_kn^lev3}{\mathinfigure{v_{k_{n}^{lev3}}}} |
| 661 |
\psfrag{v_k1^lev2}{\mathinfigure{v_{k_{1}^{lev2}}}} |
%\psfrag{v_k1^lev2}{\mathinfigure{v_{k_{1}^{lev2}}}} |
| 662 |
\psfrag{v_kn-1^lev2}{\mathinfigure{v_{k_{n-1}^{lev2}}}} |
%\psfrag{v_kn-1^lev2}{\mathinfigure{v_{k_{n-1}^{lev2}}}} |
| 663 |
\psfrag{v_kn^lev2}{\mathinfigure{v_{k_{n}^{lev2}}}} |
%\psfrag{v_kn^lev2}{\mathinfigure{v_{k_{n}^{lev2}}}} |
| 664 |
\psfrag{v_k1^lev1}{\mathinfigure{v_{k_{1}^{lev1}}}} |
%\psfrag{v_k1^lev1}{\mathinfigure{v_{k_{1}^{lev1}}}} |
| 665 |
\psfrag{v_kn^lev1}{\mathinfigure{v_{k_{n}^{lev1}}}} |
%\psfrag{v_kn^lev1}{\mathinfigure{v_{k_{n}^{lev1}}}} |
| 666 |
\mbox{\epsfig{file=part5/checkpointing.eps, width=0.8\textwidth}} |
%\mbox{\epsfig{file=s_autodiff/figs/checkpointing.eps, width=0.8\textwidth}} |
| 667 |
|
\resizebox{5.5in}{!}{\includegraphics{s_autodiff/figs/checkpointing.eps}} |
| 668 |
%\psfull |
%\psfull |
| 669 |
\caption |
\end{center} |
| 670 |
{Schematic view of intermediate dump and restart for |
\caption{ |
| 671 |
|
Schematic view of intermediate dump and restart for |
| 672 |
3-level checkpointing.} |
3-level checkpointing.} |
| 673 |
\label{fig:erswns} |
\label{fig:3levelcheck} |
| 674 |
\end{figure} |
\end{figure} |
| 675 |
|
|
| 676 |
\subsection{Optimal perturbations} |
% \subsection{Optimal perturbations} |
| 677 |
\label{optpert} |
% \label{sec_optpert} |
| 678 |
|
|
| 679 |
|
|
| 680 |
\subsection{Error covariance estimate and Hessian matrix} |
% \subsection{Error covariance estimate and Hessian matrix} |
| 681 |
\label{sec_hessian} |
% \label{sec_hessian} |
| 682 |
|
|
| 683 |
\newpage |
\newpage |
| 684 |
|
|
| 685 |
%********************************************************************** |
%********************************************************************** |
| 686 |
\section{AD-specific setup by example: sensitivity of carbon sequestration} |
\section{TLM and ADM generation in general} |
| 687 |
\label{sec_ad_setup_ex} |
\label{sec_ad_setup_gen} |
| 688 |
|
\begin{rawhtml} |
| 689 |
|
<!-- CMIREDIR:sec_ad_setup_gen: --> |
| 690 |
|
\end{rawhtml} |
| 691 |
%********************************************************************** |
%********************************************************************** |
| 692 |
|
|
| 693 |
The MITGCM has been adapted to enable AD using TAMC or TAF |
In this section we describe in a general fashion |
| 694 |
(we'll refer to TAMC and TAF interchangeably, except where |
the parts of the code that are relevant for automatic |
| 695 |
distinctions are explicitly mentioned). |
differentiation using the software tool TAF. |
| 696 |
The present description, therefore, is specific to the |
Modifications to use OpenAD are described in \ref{sec_ad_openad}. |
| 697 |
use of TAMC as AD tool. |
|
| 698 |
The following sections describe the steps which are necessary to |
\input{s_autodiff/text/doc_ad_the_model} |
| 699 |
generate a tangent linear or adjoint model of the MITGCM. |
|
| 700 |
We take as an example the sensitivity of carbon sequestration |
The basic flow is depicted in \ref{fig:adthemodel}. |
| 701 |
in the ocean. |
If CPP option \texttt{ALLOW\_AUTODIFF\_TAMC} is defined, |
| 702 |
The AD-relevant hooks in the code are sketched in |
the driver routine |
| 703 |
\reffig{adthemodel}, \reffig{adthemain}. |
{\it the\_model\_main}, instead of calling {\it the\_main\_loop}, |
| 704 |
|
invokes the adjoint of this routine, {\it adthe\_main\_loop} |
| 705 |
\subsection{Overview of the experiment} |
(case \texttt{\#define ALLOW\_ADJOINT\_RUN}), or |
| 706 |
|
the tangent linear of this routine {\it g\_the\_main\_loop} |
| 707 |
We describe an adjoint sensitivity analysis of outgassing from |
(case \texttt{\#define ALLOW\_TANGENTLINEAR\_RUN}), |
| 708 |
the ocean into the atmosphere of a carbon like tracer injected |
which are the toplevel routines in terms of automatic differentiation. |
| 709 |
into the ocean interior (see \cite{hil-eta:01}). |
The routines {\it adthe\_main\_loop} or {\it g\_the\_main\_loop} |
| 710 |
|
are generated by TAF. |
| 711 |
\subsubsection{Passive tracer equation} |
It contains both the forward integration of the full model, the |
| 712 |
|
cost function calculation, |
| 713 |
For this work the MITGCM was augmented with a thermodynamically |
any additional storing that is required for efficient checkpointing, |
| 714 |
inactive tracer, $C$. Tracer residing in the ocean |
and the reverse integration of the adjoint model. |
| 715 |
model surface layer is outgassed according to a relaxation time scale, |
|
| 716 |
$\mu$. Within the ocean interior, the tracer is passively advected |
[DESCRIBE IN A SEPARATE SECTION THE WORKING OF THE TLM] |
| 717 |
by the ocean model currents. The full equation for the time evolution |
|
| 718 |
% |
In Fig. \ref{fig:adthemodel} |
| 719 |
\begin{equation} |
the structure of {\it adthe\_main\_loop} has been strongly |
| 720 |
\label{carbon_ddt} |
simplified to focus on the essentials; in particular, no checkpointing |
| 721 |
\frac{\partial C}{\partial t} \, = \, |
procedures are shown here. |
| 722 |
-U\cdot \nabla C \, - \, \mu C \, + \, \Gamma(C) \,+ \, S |
Prior to the call of {\it adthe\_main\_loop}, the routine |
| 723 |
\end{equation} |
{\it ctrl\_unpack} is invoked to unpack the control vector |
| 724 |
% |
or initialise the control variables. |
| 725 |
also includes a source term $S$. This term |
Following the call of {\it adthe\_main\_loop}, |
| 726 |
represents interior sources of $C$ such as would arise due to |
the routine {\it ctrl\_pack} |
| 727 |
direct injection. |
is invoked to pack the control vector |
| 728 |
The velocity term, $U$, is the sum of the |
(cf. Section \ref{section_ctrl}). |
| 729 |
model Eulerian circulation and an eddy-induced velocity, the latter |
If gradient checks are to be performed, the option |
| 730 |
parameterized according to Gent/McWilliams (\cite{gen:90, dan:95}). |
{\tt ALLOW\_GRADIENT\_CHECK} is defined. In this case |
| 731 |
The convection function, $\Gamma$, mixes $C$ vertically wherever the |
the driver routine {\it grdchk\_main} is called after |
| 732 |
fluid is locally statically unstable. |
the gradient has been computed via the adjoint |
| 733 |
|
(cf. Section \ref{section_grdchk}). |
| 734 |
The outgassing time scale, $\mu$, in eqn. (\ref{carbon_ddt}) |
|
| 735 |
is set so that \( 1/\mu \sim 1 \ \mathrm{year} \) for the surface |
%------------------------------------------------------------------ |
| 736 |
ocean and $\mu=0$ elsewhere. With this value, eqn. (\ref{carbon_ddt}) |
|
| 737 |
is valid as a prognostic equation for small perturbations in oceanic |
\subsection{General setup |
| 738 |
carbon concentrations. This configuration provides a |
\label{section_ad_setup}} |
| 739 |
powerful tool for examining the impact of large-scale ocean circulation |
|
| 740 |
on $ CO_2 $ outgassing due to interior injections. |
In order to configure AD-related setups the following packages need |
| 741 |
As source we choose a constant in time injection of |
to be enabled: |
| 742 |
$ S = 1 \,\, {\rm mol / s}$. |
{\it |
| 743 |
|
\begin{table}[h!] |
| 744 |
\subsubsection{Model configuration} |
\begin{tabular}{l} |
| 745 |
|
autodiff \\ |
| 746 |
The model configuration employed has a constant |
ctrl \\ |
| 747 |
$4^\circ \times 4^\circ$ resolution horizontal grid and realistic |
cost \\ |
| 748 |
geography and bathymetry. Twenty vertical layers are used with |
grdchk \\ |
| 749 |
vertical spacing ranging |
\end{tabular} |
| 750 |
from 50 m near the surface to 815 m at depth. |
\end{table} |
| 751 |
Driven to steady-state by climatalogical wind-stress, heat and |
} |
| 752 |
fresh-water forcing the model reproduces well known large-scale |
The packages are enabled by adding them to your experiment-specific |
| 753 |
features of the ocean general circulation. |
configuration file |
| 754 |
|
{\it packages.conf} (see Section ???). |
| 755 |
\subsubsection{Outgassing cost function} |
|
| 756 |
|
The following AD-specific CPP option files need to be customized: |
|
To quantify and understand outgassing due to injections of $C$ |
|
|
in eqn. (\ref{carbon_ddt}), |
|
|
we define a cost function $ {\cal J} $ that measures the total amount of |
|
|
tracer outgassed at each timestep: |
|
|
% |
|
|
\begin{equation} |
|
|
\label{cost_tracer} |
|
|
{\cal J}(t=T)=\int_{t=0}^{t=T}\int_{A} \mu C \, dA \, dt |
|
|
\end{equation} |
|
|
% |
|
|
Equation(\ref{cost_tracer}) integrates the outgassing term, $\mu C$, |
|
|
from (\ref{carbon_ddt}) |
|
|
over the entire ocean surface area, $A$, and accumulates it |
|
|
up to time $T$. |
|
|
Physically, ${\cal J}$ can be thought of as representing the amount of |
|
|
$CO_2$ that our model predicts would be outgassed following an |
|
|
injection at rate $S$. |
|
|
The sensitivity of ${\cal J}$ to the spatial location of $S$, |
|
|
$\frac{\partial {\cal J}}{\partial S}$, |
|
|
can be used to identify regions from which circulation |
|
|
would cause $CO_2$ to rapidly outgas following injection |
|
|
and regions in which $CO_2$ injections would remain effectively |
|
|
sequesterd within the ocean. |
|
|
|
|
|
\subsection{Code configuration} |
|
|
|
|
|
The model configuration for this experiment resides under the |
|
|
directory {\it verification/carbon/}. |
|
|
The code customisation routines are in {\it verification/carbon/code/}: |
|
| 757 |
% |
% |
| 758 |
\begin{itemize} |
\begin{itemize} |
| 759 |
% |
% |
| 760 |
\item {\it .genmakerc} |
\item {\it ECCO\_CPPOPTIONS.h} \\ |
| 761 |
% |
This header file collects CPP options for the packages |
| 762 |
\item {\it COST\_CPPOPTIONS.h} |
{\it autodiff, cost, ctrl} as well as AD-unrelated options for |
| 763 |
% |
the external forcing package {\it exf}. |
| 764 |
\item {\it CPP\_EEOPTIONS.h} |
\footnote{NOTE: These options are not set in their package-specific |
| 765 |
% |
headers such as {\it COST\_CPPOPTIONS.h}, but are instead collected |
| 766 |
\item {\it CPP\_OPTIONS.h} |
in the single header file {\it ECCO\_CPPOPTIONS.h}. |
| 767 |
% |
The package-specific header files serve as simple |
| 768 |
\item {\it CTRL\_OPTIONS.h} |
placeholders at this point.} |
| 769 |
% |
% |
| 770 |
\item {\it ECCO\_OPTIONS.h} |
\item {\it tamc.h} \\ |
| 771 |
% |
This header configures the splitting of the time stepping loop |
| 772 |
\item {\it SIZE.h} |
w.r.t. the 3-level checkpointing (see section ???). |
| 773 |
% |
|
|
\item {\it adcommon.h} |
|
|
% |
|
|
\item {\it tamc.h} |
|
| 774 |
% |
% |
| 775 |
\end{itemize} |
\end{itemize} |
| 776 |
|
|
| 777 |
|
%------------------------------------------------------------------ |
| 778 |
|
|
| 779 |
|
\subsection{Building the AD code using TAF |
| 780 |
|
\label{section_ad_build}} |
| 781 |
|
|
| 782 |
|
The build process of an AD code is very similar to building |
| 783 |
|
the forward model. However, depending on which AD code one wishes |
| 784 |
|
to generate, and on which AD tool is available (TAF or TAMC), |
| 785 |
|
the following {\tt make} targets are available: |
| 786 |
|
|
| 787 |
|
\begin{table}[h!] |
| 788 |
|
{\footnotesize |
| 789 |
|
\begin{tabular}{|ccll|} |
| 790 |
|
\hline |
| 791 |
|
~ & {\it AD-target} & {\it output} & {\it description} \\ |
| 792 |
|
\hline |
| 793 |
|
\hline |
| 794 |
|
(1) & {\tt <MODE><TOOL>only} & {\tt <MODE>\_<TOOL>\_output.f} & |
| 795 |
|
generates code for $<$MODE$>$ using $<$TOOL$>$ \\ |
| 796 |
|
~ & ~ & ~ & no {\tt make} dependencies on {\tt .F .h} \\ |
| 797 |
|
~ & ~ & ~ & useful for compiling on remote platforms \\ |
| 798 |
|
\hline |
| 799 |
|
(2) & {\tt <MODE><TOOL>} & {\tt <MODE>\_<TOOL>\_output.f} & |
| 800 |
|
generates code for $<$MODE$>$ using $<$TOOL$>$ \\ |
| 801 |
|
~ & ~ & ~ & includes {\tt make} dependencies on {\tt .F .h} \\ |
| 802 |
|
~ & ~ & ~ & i.e. input for $<$TOOL$>$ may be re-generated \\ |
| 803 |
|
\hline |
| 804 |
|
(3) & {\tt <MODE>all} & {\tt mitgcmuv\_<MODE>} & |
| 805 |
|
generates code for $<$MODE$>$ using $<$TOOL$>$ \\ |
| 806 |
|
~ & ~ & ~ & and compiles all code \\ |
| 807 |
|
~ & ~ & ~ & (use of TAF is set as default) \\ |
| 808 |
|
\hline |
| 809 |
|
\end{tabular} |
| 810 |
|
} |
| 811 |
|
\end{table} |
| 812 |
% |
% |
| 813 |
The runtime flag and parameters settings are contained in |
Here, the following placeholders are used |
|
{\it verification/carbon/input/}, |
|
|
together with the forcing fields and and restart files: |
|
| 814 |
% |
% |
| 815 |
\begin{itemize} |
\begin{itemize} |
| 816 |
% |
% |
| 817 |
\item {\it data} |
\item $<$TOOL$>$ |
|
% |
|
|
\item {\it data.cost} |
|
|
% |
|
|
\item {\it data.ctrl} |
|
|
% |
|
|
\item {\it data.pkg} |
|
|
% |
|
|
\item {\it eedata} |
|
| 818 |
% |
% |
| 819 |
\item {\it topog.bin} |
\begin{itemize} |
|
% |
|
|
\item {\it windx.bin, windy.bin} |
|
|
% |
|
|
\item {\it salt.bin, theta.bin} |
|
|
% |
|
|
\item {\it SSS.bin, SST.bin} |
|
| 820 |
% |
% |
| 821 |
\item {\it pickup*} |
\item {\tt TAF} |
| 822 |
|
\item {\tt TAMC} |
| 823 |
% |
% |
| 824 |
\end{itemize} |
\end{itemize} |
| 825 |
% |
% |
| 826 |
Finally, the file to generate the adjoint code resides in |
\item $<$MODE$>$ |
|
$ adjoint/ $: |
|
| 827 |
% |
% |
| 828 |
\begin{itemize} |
\begin{itemize} |
| 829 |
% |
% |
| 830 |
\item {\it makefile} |
\item {\tt ad} generates the adjoint model (ADM) |
| 831 |
|
\item {\tt ftl} generates the tangent linear model (TLM) |
| 832 |
|
\item {\tt svd} generates both ADM and TLM for \\ |
| 833 |
|
singular value decomposition (SVD) type calculations |
| 834 |
% |
% |
| 835 |
\end{itemize} |
\end{itemize} |
| 836 |
% |
% |
| 837 |
|
\end{itemize} |
| 838 |
|
|
| 839 |
Below we describe the customisations of this files which are |
For example, to generate the adjoint model using TAF after routines ({\tt .F}) |
| 840 |
specific to this experiment. |
or headers ({\tt .h}) have been modified, but without compilation, |
| 841 |
|
type {\tt make adtaf}; |
| 842 |
\subsubsection{File {\it .genmakerc}} |
or, to generate the tangent linear model using TAMC without |
| 843 |
This file overwites default settings of {\it genmake}. |
re-generating the input code, type {\tt make ftltamconly}. |
|
In the present example it is used to switch on the following |
|
|
packages which are related to automatic differentiation |
|
|
and are disabled by default: \\ |
|
|
\hspace*{4ex} {\tt set ENABLE=( autodiff cost ctrl ecco )} \\ |
|
|
Other packages which are not needed are switched off: \\ |
|
|
\hspace*{4ex} {\tt set DISABLE=( aim obcs zonal\_filt shap\_filt cal exf )} |
|
|
|
|
|
\subsubsection{File {\it COST\_CPPOPTIONS.h, CTRL\_OPTIONS.h}} |
|
|
|
|
|
These files used to contain package-specific CPP-options |
|
|
(see Section \ref{???}). |
|
|
For technical reasons those options have been grouped together |
|
|
in the file {\it ECCO\_OPTIONS.h}. |
|
|
To retain the modularity, the files have been kept and contain |
|
|
the standard include of the {\it CPP\_OPTIONS.h} file. |
|
|
|
|
|
\subsubsection{File {\it CPP\_EEOPTIONS.h}} |
|
|
|
|
|
This file contains 'wrapper'-specific CPP options. |
|
|
It only needs to be changed if the code is to be run |
|
|
in parallel environment (see Section \ref{???}). |
|
|
|
|
|
\subsubsection{File {\it CPP\_OPTIONS.h}} |
|
|
|
|
|
This file contains model-specific CPP options |
|
|
(see Section \ref{???}). |
|
|
Most options are related to the forward model setup. |
|
|
They are identical to the global steady circulation setup of |
|
|
{\it verification/exp2/}. |
|
|
The option specific to this experiment is \\ |
|
|
\hspace*{4ex} {\tt \#define ALLOW\_MIT\_ADJOINT\_RUN} \\ |
|
|
This flag enables the inclusion of some AD-related fields |
|
|
concerning initialisation, link between control variables |
|
|
and forward model variables, and the call to the top-level |
|
|
forward/adjoint subroutine {\it adthe\_main\_loop} |
|
|
instead of {\it the\_main\_loop}. |
|
|
|
|
|
\subsubsection{File {\it ECCO\_OPTIONS.h}} |
|
| 844 |
|
|
|
The CPP options of several AD-related packages are grouped |
|
|
in this file: |
|
|
% |
|
|
\begin{itemize} |
|
|
% |
|
|
\item |
|
|
Adjoint support package: {\it pkg/autodiff/} \\ |
|
|
This package contains hand-written adjoint code such as |
|
|
active file handling, flow directives for files which must not |
|
|
be differentiated, and TAMC-specific header files. \\ |
|
|
\hspace*{4ex} {\tt \#define ALLOW\_AUTODIFF\_TAMC} \\ |
|
|
defines TAMC-related features in the code. \\ |
|
|
\hspace*{4ex} {\tt \#define ALLOW\_TAMC\_CHECKPOINTING} \\ |
|
|
enables the checkpointing feature of TAMC |
|
|
(see Section \ref{???}). |
|
|
In the present example a 3-level checkpointing is implemented. |
|
|
The code contains the relevant store directives, common block |
|
|
and tape initialisations, storing key computation, |
|
|
and loop index handling. |
|
|
The checkpointing length at each level is defined in |
|
|
file {\it tamc.h}, cf. below. |
|
|
% |
|
|
\item Cost function package: {\it pkg/cost/} \\ |
|
|
This package contains all relevant routines for |
|
|
initialising, accumulating and finalizing the cost function |
|
|
(see Section \ref{???}). \\ |
|
|
\hspace*{4ex} {\tt \#define ALLOW\_COST} \\ |
|
|
enables all general aspects of the cost function handling, |
|
|
in particular the hooks in the foorward code for |
|
|
initialising, accumulating and finalizing the cost function. \\ |
|
|
\hspace*{4ex} {\tt \#define ALLOW\_COST\_TRACER} \\ |
|
|
includes the subroutine with the cost function for this |
|
|
particular experiment, eqn. (\ref{cost_tracer}). |
|
|
% |
|
|
\item Control variable package: {\it pkg/ctrl/} \\ |
|
|
This package contains all relevant routines for |
|
|
the handling of the control vector. |
|
|
Each control variable can be enabled/disabled with its own flag: \\ |
|
|
\begin{tabular}{ll} |
|
|
\hspace*{2ex} {\tt \#define ALLOW\_THETA0\_CONTROL} & |
|
|
initial temperature \\ |
|
|
\hspace*{2ex} {\tt \#define ALLOW\_SALT0\_CONTROL} & |
|
|
initial salinity \\ |
|
|
\hspace*{2ex} {\tt \#define ALLOW\_TR0\_CONTROL} & |
|
|
initial passive tracer concentration \\ |
|
|
\hspace*{2ex} {\tt \#define ALLOW\_TAUU0\_CONTROL} & |
|
|
zonal wind stress \\ |
|
|
\hspace*{2ex} {\tt \#define ALLOW\_TAUV0\_CONTROL} & |
|
|
meridional wind stress \\ |
|
|
\hspace*{2ex} {\tt \#define ALLOW\_SFLUX0\_CONTROL} & |
|
|
freshwater flux \\ |
|
|
\hspace*{2ex} {\tt \#define ALLOW\_HFLUX0\_CONTROL} & |
|
|
heat flux \\ |
|
|
\hspace*{2ex} {\tt \#undef ALLOW\_DIFFKR\_CONTROL} & |
|
|
diapycnal diffusivity \\ |
|
|
\hspace*{2ex} {\tt \#undef ALLOW\_KAPPAGM\_CONTROL} & |
|
|
isopycnal diffusivity \\ |
|
|
\end{tabular} |
|
|
% |
|
|
\end{itemize} |
|
| 845 |
|
|
| 846 |
\subsubsection{File {\it SIZE.h}} |
A typical full build process to generate the ADM via TAF would |
| 847 |
|
look like follows: |
| 848 |
|
\begin{verbatim} |
| 849 |
|
% mkdir build |
| 850 |
|
% cd build |
| 851 |
|
% ../../../tools/genmake2 -mods=../code_ad |
| 852 |
|
% make depend |
| 853 |
|
% make adall |
| 854 |
|
\end{verbatim} |
| 855 |
|
|
| 856 |
The file contains the grid point dimensions of the forward |
%------------------------------------------------------------------ |
|
model. It is identical to the {\it verification/exp2/}: \\ |
|
|
\hspace*{4ex} {\tt sNx = 90} \\ |
|
|
\hspace*{4ex} {\tt sNy = 40} \\ |
|
|
\hspace*{4ex} {\tt Nr = 20} \\ |
|
|
It correpsponds to a single-tile/single-processor setup: |
|
|
{\tt nSx = nSy = 1, nPx = nPy = 1}, |
|
|
with standard overlap dimensioning |
|
|
{\tt OLx = OLy = 3}. |
|
|
|
|
|
\subsubsection{File {\it adcommon.h}} |
|
|
|
|
|
This file contains common blocks of some adjoint variables |
|
|
that are generated by TAMC. |
|
|
The common blocks are used by the adjoint support routine |
|
|
{\it addummy\_in\_stepping} which needs to access those variables: |
|
|
|
|
|
\begin{tabular}{ll} |
|
|
\hspace*{4ex} {\tt common /addynvars\_r/} & |
|
|
\hspace*{4ex} is related to {\it DYNVARS.h} \\ |
|
|
\hspace*{4ex} {\tt common /addynvars\_cd/} & |
|
|
\hspace*{4ex} is related to {\it DYNVARS.h} \\ |
|
|
\hspace*{4ex} {\tt common /adtr1\_r/} & |
|
|
\hspace*{4ex} is related to {\it TR1.h} \\ |
|
|
\hspace*{4ex} {\tt common /adffields/} & |
|
|
\hspace*{4ex} is related to {\it FFIELDS.h}\\ |
|
|
\end{tabular} |
|
| 857 |
|
|
| 858 |
Note that if the structure of the common block changes in the |
\subsection{The AD build process in detail |
| 859 |
above header files of the forward code, the structure |
\label{section_ad_build_detail}} |
|
of the adjoint common blocks will change accordingly. |
|
|
Thus, it has to be made sure that the structure of the |
|
|
adjoint common block in the hand-written file {\it adcommon.h} |
|
|
complies with the automatically generated adjoint common blocks |
|
|
in {\it adjoint\_model.F}. |
|
| 860 |
|
|
| 861 |
\subsubsection{File {\it tamc.h}} |
The {\tt make <MODE>all} target consists of the following procedures: |
| 862 |
|
|
| 863 |
This routine contains the dimensions for TAMC checkpointing. |
\begin{enumerate} |
| 864 |
% |
% |
| 865 |
|
\item |
| 866 |
|
A header file {\tt AD\_CONFIG.h} is generated which contains a CPP option |
| 867 |
|
on which code ought to be generated. Depending on the {\tt make} target, |
| 868 |
|
the contents is one of the following: |
| 869 |
\begin{itemize} |
\begin{itemize} |
| 870 |
|
\item |
| 871 |
|
{\tt \#define ALLOW\_ADJOINT\_RUN} |
| 872 |
|
\item |
| 873 |
|
{\tt \#define ALLOW\_TANGENTLINEAR\_RUN} |
| 874 |
|
\item |
| 875 |
|
{\tt \#define ALLOW\_ECCO\_OPTIMIZATION} |
| 876 |
|
\end{itemize} |
| 877 |
% |
% |
| 878 |
\item {\tt \#ifdef ALLOW\_TAMC\_CHECKPOINTING} \\ |
\item |
| 879 |
3-level checkpointing is enabled, i.e. the timestepping |
A single file {\tt <MODE>\_input\_code.f} is concatenated |
| 880 |
is divided into three different levels (see Section \ref{???}). |
consisting of all {\tt .f} files that are part of the list {\bf AD\_FILES} |
| 881 |
The model state of the outermost ({\tt nchklev\_3}) and the |
and all {\tt .flow} files that are part of the list {\bf AD\_FLOW\_FILES}. |
| 882 |
itermediate ({\tt nchklev\_2}) timestepping loop are stored to file |
% |
| 883 |
(handled in {\it the\_main\_loop}). |
\item |
| 884 |
The innermost loop ({\tt nchklev\_1}) |
The AD tool is invoked with the {\tt <MODE>\_<TOOL>\_FLAGS}. |
| 885 |
avoids I/O by storing all required variables |
The default AD tool flags in {\tt genmake2} can be overrwritten by |
| 886 |
to common blocks. This storing may also be necessary if |
an {\tt adjoint\_options} file (similar to the platform-specific |
| 887 |
no checkpointing is chosen |
{\tt build\_options}, see Section ???. |
| 888 |
(nonlinear functions, if-statements, iterative loops, ...). |
The AD tool writes the resulting AD code into the file |
| 889 |
In the present example the dimensions are chosen as follows: \\ |
{\tt <MODE>\_input\_code\_ad.f} |
| 890 |
\hspace*{4ex} {\tt nchklev\_1 = 36 } \\ |
% |
| 891 |
\hspace*{4ex} {\tt nchklev\_2 = 30 } \\ |
\item |
| 892 |
\hspace*{4ex} {\tt nchklev\_3 = 60 } \\ |
A short sed script {\tt adjoint\_sed} is applied to |
| 893 |
To guarantee that the checkpointing intervals span the entire |
{\tt <MODE>\_input\_code\_ad.f} |
| 894 |
integration period the relation \\ |
to reinstate {\bf myThid} into the CALL argument list of active file I/O. |
| 895 |
\hspace*{4ex} {\tt nchklev\_1*nchklev\_2*nchklev\_3 $ \ge $ nTimeSteps} \\ |
The result is written to file {\tt <MODE>\_<TOOL>\_output.f}. |
| 896 |
where {\tt nTimeSteps} is either specified in {\it data} |
% |
| 897 |
or computed via \\ |
\item |
| 898 |
\hspace*{4ex} {\tt nTimeSteps = (endTime-startTime)/deltaTClock }. |
All routines are compiled and an executable is generated |
| 899 |
% |
(see Table ???). |
|
\item {\tt \#undef ALLOW\_TAMC\_CHECKPOINTING} \\ |
|
|
No checkpointing is enabled. |
|
|
In this case the relevant counter is {\tt nchklev\_0}. |
|
|
Similar to above, the following relation has to be satisfied \\ |
|
|
\hspace*{4ex} {\tt nchklev\_0 $ \ge $ nTimeSteps}. |
|
| 900 |
% |
% |
| 901 |
\end{itemize} |
\end{enumerate} |
| 902 |
|
|
| 903 |
\subsubsection{File {\it makefile}} |
\subsubsection{The list AD\_FILES and {\tt .list} files} |
| 904 |
|
|
| 905 |
This file contains all relevant paramter flags and |
Not all routines are presented to the AD tool. |
| 906 |
lists to run TAMC. |
Routines typically hidden are diagnostics routines which |
| 907 |
It is assumed that TAMC is available to you, either locally, |
do not influence the cost function, but may create |
| 908 |
being installed on your network, or remotely through the 'TAMC Utility'. |
artificial flow dependencies such as I/O of active variables. |
| 909 |
TAMC is called with the command {\tt tamc} followed by a |
|
| 910 |
number of options. They are described in detail in the |
{\tt genmake2} generates a list (or variable) {\bf AD\_FILES} |
| 911 |
TAMC manual \cite{gie:99}. |
which contains all routines that are shown to the AD tool. |
| 912 |
Here we briefly discuss the main flags used in the {\it makefile} |
This list is put together from all files with suffix {\tt .list} |
| 913 |
|
that {\tt genmake2} finds in its search directories. |
| 914 |
|
The list file for the core MITgcm routines is in {\tt model/src/} |
| 915 |
|
is called {\tt model\_ad\_diff.list}. |
| 916 |
|
Note that no wrapper routine is shown to TAF. These are either |
| 917 |
|
not visible at all to the AD code, or hand-written AD code |
| 918 |
|
is available (see next section). |
| 919 |
|
|
| 920 |
|
Each package directory contains its package-specific |
| 921 |
|
list file {\tt <PKG>\_ad\_diff.list}. For example, |
| 922 |
|
{\tt pkg/ptracers/} contains the file {\tt ptracers\_ad\_diff.list}. |
| 923 |
|
Thus, enabling a package will automatically extend the |
| 924 |
|
{\bf AD\_FILES} list of {\tt genmake2} to incorporate the |
| 925 |
|
package-specific routines. |
| 926 |
|
Note that you will need to regenerate the {\tt Makefile} if |
| 927 |
|
you enable a package (e.g. by adding it to {\tt packages.conf}) |
| 928 |
|
and a {\tt Makefile} already exists. |
| 929 |
|
|
| 930 |
|
\subsubsection{The list AD\_FLOW\_FILES and {\tt .flow} files} |
| 931 |
|
|
| 932 |
|
TAMC and TAF can evaluate user-specified directives |
| 933 |
|
that start with a specific syntax ({\tt CADJ}, {\tt C\$TAF}, {\tt !\$TAF}). |
| 934 |
|
The main categories of directives are STORE directives and |
| 935 |
|
FLOW directives. Here, we are concerned with flow directives, |
| 936 |
|
store directives are treated elsewhere. |
| 937 |
|
|
| 938 |
|
Flow directives enable the AD tool to evaluate how it should treat |
| 939 |
|
routines that are 'hidden' by the user, i.e. routines which are |
| 940 |
|
not contained in the {\bf AD\_FILES} list (see previous section), |
| 941 |
|
but which are called in part of the code that the AD tool does see. |
| 942 |
|
The flow directive tell the AD tool |
| 943 |
% |
% |
| 944 |
\begin{itemize} |
\begin{itemize} |
|
\item [{\tt tamc}] {\tt |
|
|
-input <variable names> |
|
|
-output <variable name> ... \\ |
|
|
-toplevel <S/R name> -reverse <file names> |
|
|
} |
|
|
\end{itemize} |
|
| 945 |
% |
% |
| 946 |
\begin{itemize} |
\item which subroutine arguments are input/output |
| 947 |
% |
\item which subroutine arguments are active |
| 948 |
\item {\tt -toplevel <S/R name>} \\ |
\item which subroutine arguments are required to compute the cost |
| 949 |
Name of the toplevel routine, with respect to which the |
\item which subroutine arguments are dependent |
|
control flow analysis is performed. |
|
|
% |
|
|
\item {\tt -input <variable names>} \\ |
|
|
List of independent variables $ u $ with respect to which the |
|
|
dependent variable $ J $ is differentiated. |
|
|
% |
|
|
\item {\tt -output <variable name>} \\ |
|
|
Dependent variable $ J $ which is to be differentiated. |
|
|
% |
|
|
\item {\tt -reverse <file names>} \\ |
|
|
Adjoint code is generated to compute the sensitivity of an |
|
|
independent variable w.r.t. many dependent variables. |
|
|
The generated adjoint top-level routine computes the product |
|
|
of the transposed Jacobian matrix $ M^T $ times |
|
|
the gradient vector $ \nabla_v J $. |
|
|
\\ |
|
|
{\tt <file names>} refers to the list of files {\it .f} which are to be |
|
|
analyzed by TAMC. This list is generally smaller than the full list |
|
|
of code to be compiled. The files not contained are either |
|
|
above the top-level routine (some initialisations), or are |
|
|
deliberately hidden from TAMC, either because hand-written |
|
|
adjoint routines exist, or the routines must not (or don't have to) |
|
|
be differentiated. For each routine which is part of the flow tree |
|
|
of the top-level routine, but deliberately hidden from TAMC, |
|
|
a corresponding file {\it .flow} exists containing flow directives |
|
|
for TAMC. |
|
| 950 |
% |
% |
| 951 |
\end{itemize} |
\end{itemize} |
| 952 |
|
% |
| 953 |
|
The syntax for the flow directives can be found in the |
| 954 |
|
AD tool manuals. |
| 955 |
|
|
| 956 |
|
{\tt genmake2} generates a list (or variable) {\bf AD\_FLOW\_FILES} |
| 957 |
|
which contains all files with suffix{\tt .flow} that it finds |
| 958 |
|
in its search directories. |
| 959 |
|
The flow directives for the core MITgcm routines of |
| 960 |
|
{\tt eesupp/src/} and {\tt model/src/} |
| 961 |
|
reside in {\tt pkg/autodiff/}. |
| 962 |
|
This directory also contains hand-written adjoint code |
| 963 |
|
for the MITgcm WRAPPER (section \ref{chap:sarch}). |
| 964 |
|
|
| 965 |
|
Flow directives for package-specific routines are contained in |
| 966 |
|
the corresponding package directories in the file |
| 967 |
|
{\tt <PKG>\_ad.flow}, e.g. ptracers-specific directives are in |
| 968 |
|
{\tt ptracers\_ad.flow}. |
| 969 |
|
|
| 970 |
|
\subsubsection{Store directives for 3-level checkpointing} |
| 971 |
|
|
| 972 |
|
The storing that is required at each period of the |
| 973 |
|
3-level checkpointing is controled by three |
| 974 |
|
top-level headers. |
| 975 |
|
|
| 976 |
\subsubsection{File {\it data}} |
\begin{verbatim} |
| 977 |
|
do ilev_3 = 1, nchklev_3 |
| 978 |
\subsubsection{File {\it data.cost}} |
# include ``checkpoint_lev3.h'' |
| 979 |
|
do ilev_2 = 1, nchklev_2 |
| 980 |
\subsubsection{File {\it data.ctrl}} |
# include ``checkpoint_lev2.h'' |
| 981 |
|
do ilev_1 = 1, nchklev_1 |
| 982 |
\subsubsection{File {\it data.pkg}} |
# include ``checkpoint_lev1.h'' |
| 983 |
|
|
| 984 |
\subsubsection{File {\it eedata}} |
... |
| 985 |
|
|
| 986 |
\subsubsection{File {\it topog.bin}} |
end do |
| 987 |
|
end do |
| 988 |
\subsubsection{File {\it windx.bin, windy.bin}} |
end do |
| 989 |
|
\end{verbatim} |
|
\subsubsection{File {\it salt.bin, theta.bin}} |
|
| 990 |
|
|
| 991 |
\subsubsection{File {\it SSS.bin, SST.bin}} |
All files {\tt checkpoint\_lev?.h} are contained in directory |
| 992 |
|
{\tt pkg/autodiff/}. |
| 993 |
|
|
|
\subsubsection{File {\it pickup*}} |
|
| 994 |
|
|
| 995 |
\subsection{Compiling the model and its adjoint} |
\subsubsection{Changing the default AD tool flags: ad\_options files} |
| 996 |
|
|
|
\newpage |
|
| 997 |
|
|
| 998 |
%********************************************************************** |
\subsubsection{Hand-written adjoint code} |
|
\section{TLM and ADM code generation in general} |
|
|
\label{sec_ad_setup_gen} |
|
|
%********************************************************************** |
|
| 999 |
|
|
| 1000 |
In this section we describe in a general fashion |
%------------------------------------------------------------------ |
|
the parts of the code that are relevant for automatic |
|
|
differentiation using the software tool TAMC. |
|
| 1001 |
|
|
| 1002 |
\subsection{The cost function (dependent variable)} |
\subsection{The cost function (dependent variable) |
| 1003 |
|
\label{section_cost}} |
| 1004 |
|
|
| 1005 |
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}. |
| 1006 |
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 |
| 1007 |
$ {\cal J}(\vec{u}) \, = \, {\cal J}(M(\vec{u})) $. |
$ {\cal J}(\vec{u}) \, = \, {\cal J}(M(\vec{u})) $. |
| 1008 |
The input is referred to as the |
The input are referred to as the |
| 1009 |
{\sf independent variables} or {\sf control variables}. |
{\sf independent variables} or {\sf control variables}. |
| 1010 |
All aspects relevant to the treatment of the cost function $ {\cal J} $ |
All aspects relevant to the treatment of the cost function $ {\cal J} $ |
| 1011 |
(parameter setting, initialisation, incrementation, |
(parameter setting, initialization, accumulation, |
| 1012 |
final evaluation), are controled by the package {\it pkg/cost}. |
final evaluation), are controlled by the package {\it pkg/cost}. |
| 1013 |
|
The aspects relevant to the treatment of the independent variables |
| 1014 |
|
are controlled by the package {\it pkg/ctrl} and will be treated |
| 1015 |
|
in the next section. |
| 1016 |
|
|
| 1017 |
|
\input{s_autodiff/text/doc_cost_flow} |
| 1018 |
|
|
| 1019 |
|
\subsubsection{Enabling the package} |
| 1020 |
|
|
|
\subsubsection{genmake and CPP options} |
|
|
% |
|
|
\begin{itemize} |
|
|
% |
|
|
\item |
|
| 1021 |
\fbox{ |
\fbox{ |
| 1022 |
\begin{minipage}{12cm} |
\begin{minipage}{12cm} |
| 1023 |
{\it genmake}, {\it CPP\_OPTIONS.h}, {\it ECCO\_CPPOPTIONS.h} |
{\it packages.conf}, {\it ECCO\_CPPOPTIONS.h} |
| 1024 |
\end{minipage} |
\end{minipage} |
| 1025 |
} |
} |
| 1026 |
\end{itemize} |
\begin{itemize} |
|
% |
|
|
The directory {\it pkg/cost} can be included to the |
|
|
compile list in 3 different ways (cf. Section \ref{???}): |
|
| 1027 |
% |
% |
| 1028 |
\begin{enumerate} |
\item |
| 1029 |
|
The package is enabled by adding {\it cost} to your file {\it packages.conf} |
| 1030 |
|
(see Section ???) |
| 1031 |
% |
% |
| 1032 |
\item {\it genmake}: \\ |
\item |
| 1033 |
Change the default settngs in the file {\it genmake} by adding |
|
| 1034 |
{\bf cost} to the {\bf enable} list (not recommended). |
|
| 1035 |
% |
\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}. |
|
| 1036 |
% |
% |
| 1037 |
\end{enumerate} |
|
| 1038 |
Since the cost function is usually used in conjunction with |
N.B.: In general the following packages ought to be enabled |
| 1039 |
automatic differentiation, the CPP option |
simultaneously: {\it autodiff, cost, ctrl}. |
|
{\bf ALLOW\_ADJOINT\_RUN} should be defined |
|
|
(file {\it CPP\_OPTIONS.h}). |
|
| 1040 |
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}. |
| 1041 |
Each specific cost function contribution has its own option. |
Each specific cost function contribution has its own option. |
| 1042 |
For the present example the option is {\bf ALLOW\_COST\_TRACER}. |
For the present example the option is {\bf ALLOW\_COST\_TRACER}. |
| 1043 |
All cost-specific options are set in {\it ECCO\_CPPOPTIONS.h} |
All cost-specific options are set in {\it ECCO\_CPPOPTIONS.h} |
| 1044 |
|
Since the cost function is usually used in conjunction with |
| 1045 |
|
automatic differentiation, the CPP option |
| 1046 |
|
{\bf ALLOW\_ADJOINT\_RUN} (file {\it CPP\_OPTIONS.h}) and |
| 1047 |
|
{\bf ALLOW\_AUTODIFF\_TAMC} (file {\it ECCO\_CPPOPTIONS.h}) |
| 1048 |
|
should be defined. |
| 1049 |
|
|
| 1050 |
\subsubsection{Initialisation} |
\subsubsection{Initialization} |
| 1051 |
% |
% |
| 1052 |
The initialisation of the {\it cost} package is readily enabled |
The initialization of the {\it cost} package is readily enabled |
| 1053 |
as soon as the CPP option {\bf ALLOW\_ADJOINT\_RUN} is defined. |
as soon as the CPP option {\bf ALLOW\_COST} is defined. |
| 1054 |
% |
% |
| 1055 |
\begin{itemize} |
\begin{itemize} |
| 1056 |
% |
% |
| 1080 |
} |
} |
| 1081 |
\\ |
\\ |
| 1082 |
This S/R |
This S/R |
| 1083 |
initialises the different cost function contributions. |
initializes the different cost function contributions. |
| 1084 |
The contribtion for the present example is {\bf objf\_tracer} |
The contribution for the present example is {\bf objf\_tracer} |
| 1085 |
which is defined on each tile (bi,bj). |
which is defined on each tile (bi,bj). |
| 1086 |
% |
% |
| 1087 |
\end{itemize} |
\end{itemize} |
| 1088 |
% |
% |
| 1089 |
\subsubsection{Incrementation} |
\subsubsection{Accumulation} |
| 1090 |
% |
% |
| 1091 |
\begin{itemize} |
\begin{itemize} |
| 1092 |
% |
% |
| 1124 |
\begin{equation} |
\begin{equation} |
| 1125 |
{\cal J} \, = \, |
{\cal J} \, = \, |
| 1126 |
{\rm fc} \, = \, |
{\rm fc} \, = \, |
| 1127 |
{\rm mult\_tracer} \sum_{bi,\,bj}^{nSx,\,nSy} |
{\rm mult\_tracer} \sum_{\text{global sum}} \sum_{bi,\,bj}^{nSx,\,nSy} |
| 1128 |
{\rm objf\_tracer}(bi,bj) \, + \, ... |
{\rm objf\_tracer}(bi,bj) \, + \, ... |
| 1129 |
\end{equation} |
\end{equation} |
| 1130 |
% |
% |
| 1131 |
The total cost function {\bf fc} will be the |
The total cost function {\bf fc} will be the |
| 1132 |
'dependent' variable in the argument list for TAMC, i.e. |
'dependent' variable in the argument list for TAF, i.e. |
| 1133 |
\begin{verbatim} |
\begin{verbatim} |
| 1134 |
tamc -output 'fc' ... |
taf -output 'fc' ... |
| 1135 |
\end{verbatim} |
\end{verbatim} |
| 1136 |
|
|
| 1137 |
\begin{figure}[t!] |
%%%% \end{document} |
|
\input{part5/doc_ad_the_model} |
|
|
\label{fig:adthemodel} |
|
|
\caption{~} |
|
|
\end{figure} |
|
| 1138 |
|
|
| 1139 |
\begin{figure} |
\input{s_autodiff/text/doc_ad_the_main} |
|
\input{part5/doc_ad_the_main} |
|
|
\label{fig:adthemain} |
|
|
\caption{~} |
|
|
\end{figure} |
|
| 1140 |
|
|
| 1141 |
\subsection{The control variables (independent variables)} |
\subsection{The control variables (independent variables) |
| 1142 |
|
\label{section_ctrl}} |
| 1143 |
|
|
| 1144 |
The control variables are a subset of the model input |
The control variables are a subset of the model input |
| 1145 |
(initial conditions, boundary conditions, model parameters). |
(initial conditions, boundary conditions, model parameters). |
| 1146 |
Here we identify them with the variable $ \vec{u} $. |
Here we identify them with the variable $ \vec{u} $. |
| 1147 |
All intermediate variables whose derivative w.r.t. control |
All intermediate variables whose derivative w.r.t. control |
| 1148 |
variables don't vanish are called {\sf active variables}. |
variables do not vanish are called {\sf active variables}. |
| 1149 |
All subroutines whose derivative w.r.t. the control variables |
All subroutines whose derivative w.r.t. the control variables |
| 1150 |
don't vanish are called {\sf active routines}. |
don't vanish are called {\sf active routines}. |
| 1151 |
Read and write operations from and to file can be viewed |
Read and write operations from and to file can be viewed |
| 1153 |
active variables are written and from which active variables |
active variables are written and from which active variables |
| 1154 |
are read are called {\sf active files}. |
are read are called {\sf active files}. |
| 1155 |
All aspects relevant to the treatment of the control variables |
All aspects relevant to the treatment of the control variables |
| 1156 |
(parameter setting, initialisation, perturbation) |
(parameter setting, initialization, perturbation) |
| 1157 |
are controled by the package {\it pkg/ctrl}. |
are controlled by the package {\it pkg/ctrl}. |
| 1158 |
|
|
| 1159 |
|
\input{s_autodiff/text/doc_ctrl_flow} |
| 1160 |
|
|
| 1161 |
\subsubsection{genmake and CPP options} |
\subsubsection{genmake and CPP options} |
| 1162 |
% |
% |
| 1172 |
% |
% |
| 1173 |
To enable the directory to be included to the compile list, |
To enable the directory to be included to the compile list, |
| 1174 |
{\bf ctrl} has to be added to the {\bf enable} list in |
{\bf ctrl} has to be added to the {\bf enable} list in |
| 1175 |
{\it .genmakerc} (or {\it genmake} itself). |
{\it .genmakerc} or in {\it genmake} itself (analogous to {\it cost} |
| 1176 |
|
package, cf. previous section). |
| 1177 |
Each control variable is enabled via its own CPP option |
Each control variable is enabled via its own CPP option |
| 1178 |
in {\it ECCO\_CPPOPTIONS.h}. |
in {\it ECCO\_CPPOPTIONS.h}. |
| 1179 |
|
|
| 1180 |
\subsubsection{Initialisation} |
\subsubsection{Initialization} |
| 1181 |
% |
% |
| 1182 |
\begin{itemize} |
\begin{itemize} |
| 1183 |
% |
% |
| 1214 |
\\ |
\\ |
| 1215 |
% |
% |
| 1216 |
Two important issues related to the handling of the control |
Two important issues related to the handling of the control |
| 1217 |
variables in the MITGCM need to be addressed. |
variables in MITgcm need to be addressed. |
| 1218 |
First, in order to save memory, the control variable arrays |
First, in order to save memory, the control variable arrays |
| 1219 |
are not kept in memory, but rather read from file and added |
are not kept in memory, but rather read from file and added |
| 1220 |
to the initial (or first guess) fields. |
to the initial fields during the model initialization phase. |
| 1221 |
Similarly, the corresponding adjoint fields which represent |
Similarly, the corresponding adjoint fields which represent |
| 1222 |
the gradient of the cost function w.r.t. the control variables |
the gradient of the cost function w.r.t. the control variables |
| 1223 |
are written to to file. |
are written to file at the end of the adjoint integration. |
| 1224 |
Second, in addition to the files holding the 2-dim. and 3-dim. |
Second, in addition to the files holding the 2-dim. and 3-dim. |
| 1225 |
control variables and the gradient, a 1-dim. {\sf control vector} |
control variables and the corresponding cost gradients, |
| 1226 |
|
a 1-dim. {\sf control vector} |
| 1227 |
and {\sf gradient vector} are written to file. They contain |
and {\sf gradient vector} are written to file. They contain |
| 1228 |
only the wet points of the control variables and the corresponding |
only the wet points of the control variables and the corresponding |
| 1229 |
gradient. |
gradient. |
| 1230 |
This leads to a significant data compression. |
This leads to a significant data compression. |
| 1231 |
Furthermore, the control and the gradient vector can be passed to a |
Furthermore, an option is available |
| 1232 |
|
({\tt ALLOW\_NONDIMENSIONAL\_CONTROL\_IO}) to |
| 1233 |
|
non-dimensionalise the control and gradient vector, |
| 1234 |
|
which otherwise would contain different pieces of different |
| 1235 |
|
magnitudes and units. |
| 1236 |
|
Finally, the control and gradient vector can be passed to a |
| 1237 |
minimization routine if an update of the control variables |
minimization routine if an update of the control variables |
| 1238 |
is sought as part of a minimization exercise. |
is sought as part of a minimization exercise. |
| 1239 |
|
|
| 1244 |
|
|
| 1245 |
\subsubsection{Perturbation of the independent variables} |
\subsubsection{Perturbation of the independent variables} |
| 1246 |
% |
% |
| 1247 |
The dependency chain for differentiation starts |
The dependency flow for differentiation w.r.t. the controls |
| 1248 |
with adding a perturbation onto the the input variable, |
starts with adding a perturbation onto the input variable, |
| 1249 |
thus defining the independent or control variables for TAMC. |
thus defining the independent or control variables for TAF. |
| 1250 |
Three classes of controls may be considered: |
Three types of controls may be considered: |
| 1251 |
% |
% |
| 1252 |
\begin{itemize} |
\begin{itemize} |
| 1253 |
% |
% |
| 1262 |
Consider as an example the initial tracer distribution |
Consider as an example the initial tracer distribution |
| 1263 |
{\bf tr1} as control variable. |
{\bf tr1} as control variable. |
| 1264 |
After {\bf tr1} has been initialised in |
After {\bf tr1} has been initialised in |
| 1265 |
{\it ini\_tr1} (dynamical variables including |
{\it ini\_tr1} (dynamical variables such as |
| 1266 |
temperature and salinity are initialised in {\it ini\_fields}), |
temperature and salinity are initialised in {\it ini\_fields}), |
| 1267 |
a perturbation anomaly is added to the field in S/R |
a perturbation anomaly is added to the field in S/R |
| 1268 |
{\it ctrl\_map\_ini} |
{\it ctrl\_map\_ini} |
| 1275 |
\end{split} |
\end{split} |
| 1276 |
\end{equation} |
\end{equation} |
| 1277 |
% |
% |
| 1278 |
In principle {\bf xx\_tr1} is a 3-dim. global array |
{\bf xx\_tr1} is a 3-dim. global array |
| 1279 |
holding the perturbation. In the case of a simple |
holding the perturbation. In the case of a simple |
| 1280 |
sensitivity study this array is identical to zero. |
sensitivity study this array is identical to zero. |
| 1281 |
However, it's specification is essential since TAMC |
However, it's specification is essential in the context |
| 1282 |
|
of automatic differentiation since TAF |
| 1283 |
treats the corresponding line in the code symbolically |
treats the corresponding line in the code symbolically |
| 1284 |
when determining the differentiation chain and its origin. |
when determining the differentiation chain and its origin. |
| 1285 |
Thus, the variable names are part of the argument list |
Thus, the variable names are part of the argument list |
| 1286 |
when calling TAMC: |
when calling TAF: |
| 1287 |
% |
% |
| 1288 |
\begin{verbatim} |
\begin{verbatim} |
| 1289 |
tamc -input 'xx_tr1 ...' ... |
taf -input 'xx_tr1 ...' ... |
| 1290 |
\end{verbatim} |
\end{verbatim} |
| 1291 |
% |
% |
| 1292 |
Now, as mentioned above, the MITGCM avoids maintaining |
Now, as mentioned above, MITgcm avoids maintaining |
| 1293 |
an array for each control variable by reading the |
an array for each control variable by reading the |
| 1294 |
perturbation to a temporary array from file. |
perturbation to a temporary array from file. |
| 1295 |
To ensure the symbolic link to be recognized by TAMC, a scalar |
To ensure the symbolic link to be recognized by TAF, a scalar |
| 1296 |
dummy variable {\bf xx\_tr1\_dummy} is introduced |
dummy variable {\bf xx\_tr1\_dummy} is introduced |
| 1297 |
and an 'active read' routine of the adjoint support |
and an 'active read' routine of the adjoint support |
| 1298 |
package {\it pkg/autodiff} is invoked. |
package {\it pkg/autodiff} is invoked. |
| 1299 |
The read-procedure is tagged with the variable |
The read-procedure is tagged with the variable |
| 1300 |
{\bf xx\_tr1\_dummy} enabbling TAMC to recognize the |
{\bf xx\_tr1\_dummy} enabling TAF to recognize the |
| 1301 |
initialisation of the perturbation. |
initialization of the perturbation. |
| 1302 |
The modified call of TAMC thus reads |
The modified call of TAF thus reads |
| 1303 |
% |
% |
| 1304 |
\begin{verbatim} |
\begin{verbatim} |
| 1305 |
tamc -input 'xx_tr1_dummy ...' ... |
taf -input 'xx_tr1_dummy ...' ... |
| 1306 |
\end{verbatim} |
\end{verbatim} |
| 1307 |
% |
% |
| 1308 |
and the modified operation to (\ref{perturb}) |
and the modified operation to (\ref{perturb}) |
| 1317 |
% |
% |
| 1318 |
Note, that reading an active variable corresponds |
Note, that reading an active variable corresponds |
| 1319 |
to a variable assignment. Its derivative corresponds |
to a variable assignment. Its derivative corresponds |
| 1320 |
to a write statement of the adjoint variable. |
to a write statement of the adjoint variable, followed by |
| 1321 |
|
a reset. |
| 1322 |
The 'active file' routines have been designed |
The 'active file' routines have been designed |
| 1323 |
to support active read and corresponding active write |
to support active read and corresponding adjoint active write |
| 1324 |
operations. |
operations (and vice versa). |
| 1325 |
% |
% |
| 1326 |
\item |
\item |
| 1327 |
\fbox{ |
\fbox{ |
| 1338 |
Note however an important difference: |
Note however an important difference: |
| 1339 |
Since the boundary values are time dependent with a new |
Since the boundary values are time dependent with a new |
| 1340 |
forcing field applied at each time steps, |
forcing field applied at each time steps, |
| 1341 |
the general problem may be be thought of as |
the general problem may be thought of as |
| 1342 |
a new control variable at each time step, i.e. |
a new control variable at each time step |
| 1343 |
|
(or, if the perturbation is averaged over a certain period, |
| 1344 |
|
at each $ N $ timesteps), i.e. |
| 1345 |
\[ |
\[ |
| 1346 |
u_{\rm forcing} \, = \, |
u_{\rm forcing} \, = \, |
| 1347 |
\{ \, u_{\rm forcing} ( t_n ) \, \}_{ |
\{ \, u_{\rm forcing} ( t_n ) \, \}_{ |
| 1366 |
% |
% |
| 1367 |
This routine is not yet implemented, but would proceed |
This routine is not yet implemented, but would proceed |
| 1368 |
proceed along the same lines as the initial value sensitivity. |
proceed along the same lines as the initial value sensitivity. |
| 1369 |
|
The mixing parameters {\bf diffkr} and {\bf kapgm} |
| 1370 |
|
are currently added as controls in {\it ctrl\_map\_ini.F}. |
| 1371 |
% |
% |
| 1372 |
\end{itemize} |
\end{itemize} |
| 1373 |
% |
% |
| 1374 |
|
|
| 1375 |
\subsubsection{Output of adjoint variables and gradient} |
\subsubsection{Output of adjoint variables and gradient} |
| 1376 |
% |
% |
| 1377 |
Two ways exist to generate output of adjoint fields. |
Several ways exist to generate output of adjoint fields. |
| 1378 |
% |
% |
| 1379 |
\begin{itemize} |
\begin{itemize} |
| 1380 |
% |
% |
| 1381 |
\item |
\item |
| 1382 |
\fbox{ |
\fbox{ |
| 1383 |
\begin{minipage}{12cm} |
\begin{minipage}{12cm} |
| 1384 |
{\it ctrl\_pack}: |
{\it ctrl\_map\_ini, ctrl\_map\_forcing}: |
| 1385 |
\end{minipage} |
\end{minipage} |
| 1386 |
} |
} |
| 1387 |
\\ |
\\ |
|
At the end of the forward/adjoint integration, the S/R |
|
|
{\it ctrl\_pack} is called which mirrors S/R {\it ctrl\_unpack}. |
|
|
It writes the following files: |
|
|
% |
|
| 1388 |
\begin{itemize} |
\begin{itemize} |
| 1389 |
% |
% |
| 1390 |
\item {\bf xx\_...}: the control variable fields |
\item {\bf xx\_...}: the control variable fields \\ |
| 1391 |
|
Before the forward integration, the control |
| 1392 |
|
variables are read from file {\bf xx\_ ...} and added to |
| 1393 |
|
the model field. |
| 1394 |
% |
% |
| 1395 |
\item {\bf adxx\_...}: the adjoint variable fields, i.e. the gradient |
\item {\bf adxx\_...}: the adjoint variable fields, i.e. the gradient |
| 1396 |
$ \nabla _{u}{\cal J} $ for each control variable, |
$ \nabla _{u}{\cal J} $ for each control variable \\ |
| 1397 |
|
After the adjoint integration the corresponding adjoint |
| 1398 |
|
variables are written to {\bf adxx\_ ...}. |
| 1399 |
% |
% |
| 1400 |
\item {\bf vector\_ctrl}: the control vector |
\end{itemize} |
| 1401 |
% |
% |
| 1402 |
\item {\bf vector\_grad}: the gradient vector |
\item |
| 1403 |
|
\fbox{ |
| 1404 |
|
\begin{minipage}{12cm} |
| 1405 |
|
{\it ctrl\_unpack, ctrl\_pack}: |
| 1406 |
|
\end{minipage} |
| 1407 |
|
} |
| 1408 |
|
\\ |
| 1409 |
|
% |
| 1410 |
|
\begin{itemize} |
| 1411 |
|
% |
| 1412 |
|
\item {\bf vector\_ctrl}: the control vector \\ |
| 1413 |
|
At the very beginning of the model initialization, |
| 1414 |
|
the updated compressed control vector is read (or initialised) |
| 1415 |
|
and distributed to 2-dim. and 3-dim. control variable fields. |
| 1416 |
|
% |
| 1417 |
|
\item {\bf vector\_grad}: the gradient vector \\ |
| 1418 |
|
At the very end of the adjoint integration, |
| 1419 |
|
the 2-dim. and 3-dim. adjoint variables are read, |
| 1420 |
|
compressed to a single vector and written to file. |
| 1421 |
% |
% |
| 1422 |
\end{itemize} |
\end{itemize} |
| 1423 |
% |
% |
| 1429 |
} |
} |
| 1430 |
\\ |
\\ |
| 1431 |
In addition to writing the gradient at the end of the |
In addition to writing the gradient at the end of the |
| 1432 |
forward/adjoint integration, many more adjoint variables, |
forward/adjoint integration, many more adjoint variables |
| 1433 |
representing the Lagrange multipliers of the model state |
of the model state |
| 1434 |
w.r.t. the model state |
at intermediate times can be written using S/R |
|
at different times can be written using S/R |
|
| 1435 |
{\it addummy\_in\_stepping}. |
{\it addummy\_in\_stepping}. |
| 1436 |
This routine is part of the adjoint support package |
This routine is part of the adjoint support package |
| 1437 |
{\it pkg/autodiff} (cf.f. below). |
{\it pkg/autodiff} (cf.f. below). |
| 1438 |
|
The procedure is enabled using via the CPP-option |
| 1439 |
|
{\bf ALLOW\_AUTODIFF\_MONITOR} (file {\it ECCO\_CPPOPTIONS.h}). |
| 1440 |
To be part of the adjoint code, the corresponding S/R |
To be part of the adjoint code, the corresponding S/R |
| 1441 |
{\it dummy\_in\_stepping} has to be called in the forward |
{\it dummy\_in\_stepping} has to be called in the forward |
| 1442 |
model (S/R {\it the\_main\_loop}) at the appropriate place. |
model (S/R {\it the\_main\_loop}) at the appropriate place. |
| 1443 |
|
The adjoint common blocks are extracted from the adjoint code |
| 1444 |
|
via the header file {\it adcommon.h}. |
| 1445 |
|
|
| 1446 |
{\it dummy\_in\_stepping} is essentially empty, |
{\it dummy\_in\_stepping} is essentially empty, |
| 1447 |
the corresponding adjoint routine is hand-written rather |
the corresponding adjoint routine is hand-written rather |
| 1449 |
Appropriate flow directives ({\it dummy\_in\_stepping.flow}) |
Appropriate flow directives ({\it dummy\_in\_stepping.flow}) |
| 1450 |
ensure that TAMC does not automatically |
ensure that TAMC does not automatically |
| 1451 |
generate {\it addummy\_in\_stepping} by trying to differentiate |
generate {\it addummy\_in\_stepping} by trying to differentiate |
| 1452 |
{\it dummy\_in\_stepping}, but rather takes the hand-written routine. |
{\it dummy\_in\_stepping}, but instead refers to |
| 1453 |
|
the hand-written routine. |
| 1454 |
|
|
| 1455 |
{\it dummy\_in\_stepping} is called in the forward code |
{\it dummy\_in\_stepping} is called in the forward code |
| 1456 |
at the beginning of each |
at the beginning of each |
| 1460 |
{\it addynamics}. |
{\it addynamics}. |
| 1461 |
|
|
| 1462 |
{\it addummy\_in\_stepping} includes the header files |
{\it addummy\_in\_stepping} includes the header files |
| 1463 |
{\it adffields.h, addynamics.h, adtr1.h}. |
{\it adcommon.h}. |
| 1464 |
These header files are also hand-written. They contain |
This header file is also hand-written. It contains |
| 1465 |
the common blocks {\bf /addynvars\_r/}, {\bf /addynvars\_cd/}, |
the common blocks |
| 1466 |
|
{\bf /addynvars\_r/}, {\bf /addynvars\_cd/}, |
| 1467 |
|
{\bf /addynvars\_diffkr/}, {\bf /addynvars\_kapgm/}, |
| 1468 |
{\bf /adtr1\_r/}, {\bf /adffields/}, |
{\bf /adtr1\_r/}, {\bf /adffields/}, |
| 1469 |
which have been extracted from the adjoint code to enable |
which have been extracted from the adjoint code to enable |
| 1470 |
access to the adjoint variables. |
access to the adjoint variables. |
| 1471 |
|
|
| 1472 |
|
{\bf WARNING:} If the structure of the common blocks |
| 1473 |
|
{\bf /dynvars\_r/}, {\bf /dynvars\_cd/}, etc., changes |
| 1474 |
|
similar changes will occur in the adjoint common blocks. |
| 1475 |
|
Therefore, consistency between the TAMC-generated common blocks |
| 1476 |
|
and those in {\it adcommon.h} have to be checked. |
| 1477 |
% |
% |
| 1478 |
\end{itemize} |
\end{itemize} |
| 1479 |
|
|
| 1488 |
with the value of the cost function itself $ {\cal J}(u_{[k]}) $ |
with the value of the cost function itself $ {\cal J}(u_{[k]}) $ |
| 1489 |
at iteration step $ k $ serve |
at iteration step $ k $ serve |
| 1490 |
as input to a minimization routine (e.g. quasi-Newton method, |
as input to a minimization routine (e.g. quasi-Newton method, |
| 1491 |
conjugate gradient, ...) to compute an update in the |
conjugate gradient, ... \cite{gil-lem:89}) |
| 1492 |
|
to compute an update in the |
| 1493 |
control variable for iteration step $k+1$ |
control variable for iteration step $k+1$ |
| 1494 |
\[ |
\[ |
| 1495 |
u_{[k+1]} \, = \, u_{[0]} \, + \, \Delta u_{[k+1]} |
u_{[k+1]} \, = \, u_{[0]} \, + \, \Delta u_{[k+1]} |
| 1503 |
and the minimization routine. |
and the minimization routine. |
| 1504 |
|
|
| 1505 |
\begin{eqnarray*} |
\begin{eqnarray*} |
| 1506 |
\footnotesize |
\scriptsize |
| 1507 |
\begin{array}{ccccc} |
\begin{array}{ccccc} |
| 1508 |
u_{[0]} \,\, , \,\, \Delta u_{[k]} & ~ & ~ & ~ & ~ \\ |
u_{[0]} \,\, , \,\, \Delta u_{[k]} & ~ & ~ & ~ & ~ \\ |
| 1509 |
{\Big\downarrow} |
{\Big\downarrow} |
| 1520 |
{\cal J}_{[k]} = {\cal J} \left( M \left( u_{[k]} \right) \right)} \\ |
{\cal J}_{[k]} = {\cal J} \left( M \left( u_{[k]} \right) \right)} \\ |
| 1521 |
\multicolumn{1}{|c}{~} & ~ & ~ & ~ & \multicolumn{1}{c|}{~} \\ |
\multicolumn{1}{|c}{~} & ~ & ~ & ~ & \multicolumn{1}{c|}{~} \\ |
| 1522 |
\hline |
\hline |
| 1523 |
|
\multicolumn{1}{|c}{~} & ~ & ~ & ~ & \multicolumn{1}{c|}{~} \\ |
| 1524 |
|
\multicolumn{1}{|c}{~} & ~ & ~ & ~ & \multicolumn{1}{c|}{{\Big\downarrow}} \\ |
| 1525 |
|
\multicolumn{1}{|c}{~} & ~ & ~ & ~ & \multicolumn{1}{c|}{~} \\ |
| 1526 |
\hline |
\hline |
| 1527 |
\multicolumn{1}{|c}{~} & ~ & ~ & ~ & \multicolumn{1}{c|}{~} \\ |
\multicolumn{1}{|c}{~} & ~ & ~ & ~ & \multicolumn{1}{c|}{~} \\ |
| 1528 |
\multicolumn{1}{|c}{ |
\multicolumn{1}{|c}{ |
| 1529 |
\nabla_u {\cal J}_{[k]} (\delta {\cal J}) = |
\nabla_u {\cal J}_{[k]} (\delta {\cal J}) = |
| 1530 |
T\!\!^{\ast} \cdot \nabla_v {\cal J} |_{v_{[k]}} (\delta {\cal J})} & |
T^{\ast} \cdot \nabla_v {\cal J} |_{v_{[k]}} (\delta {\cal J})} & |
| 1531 |
\stackrel{\bf adjoint}{\mathbf \longleftarrow} & |
\stackrel{\bf adjoint}{\mathbf \longleftarrow} & |
| 1532 |
ad \, v_{[k]} (\delta {\cal J}) = |
ad \, v_{[k]} (\delta {\cal J}) = |
| 1533 |
\nabla_v {\cal J} |_{v_{[k]}} (\delta {\cal J}) & |
\nabla_v {\cal J} |_{v_{[k]}} (\delta {\cal J}) & |
| 1536 |
\multicolumn{1}{|c}{~} & ~ & ~ & ~ & \multicolumn{1}{c|}{~} \\ |
\multicolumn{1}{|c}{~} & ~ & ~ & ~ & \multicolumn{1}{c|}{~} \\ |
| 1537 |
\hline |
\hline |
| 1538 |
~ & ~ & ~ & ~ & ~ \\ |
~ & ~ & ~ & ~ & ~ \\ |
| 1539 |
~ & ~ & |
\hspace*{15ex}{\Bigg\downarrow} |
| 1540 |
{\cal J}_{[k]} \qquad {\Bigg\downarrow} \qquad \nabla_u {\cal J}_{[k]} |
\quad {\cal J}_{[k]}, \quad \nabla_u {\cal J}_{[k]} |
| 1541 |
& ~ & ~ \\ |
& ~ & ~ & ~ & ~ \\ |
| 1542 |
~ & ~ & ~ & ~ & ~ \\ |
~ & ~ & ~ & ~ & ~ \\ |
| 1543 |
\hline |
\hline |
| 1544 |
\multicolumn{1}{|c}{~} & ~ & ~ & ~ & \multicolumn{1}{c|}{~} \\ |
\multicolumn{1}{|c}{~} & ~ & ~ & ~ & \multicolumn{1}{c|}{~} \\ |
| 1566 |
|
|
| 1567 |
\vspace*{0.5cm} |
\vspace*{0.5cm} |
| 1568 |
|
|
| 1569 |
|
{\scriptsize |
| 1570 |
\begin{tabular}{ccccc} |
\begin{tabular}{ccccc} |
| 1571 |
{\bf vector\_ctrl\_$<$k$>$ } & ~ & ~ & ~ & ~ \\ |
{\bf vector\_ctrl\_$<$k$>$ } & ~ & ~ & ~ & ~ \\ |
| 1572 |
{\big\downarrow} & ~ & ~ & ~ & ~ \\ |
{\big\downarrow} & ~ & ~ & ~ & ~ \\ |
| 1577 |
\cline{3-3} |
\cline{3-3} |
| 1578 |
\multicolumn{1}{l}{\bf xx\_theta0...$<$k$>$} & ~ & |
\multicolumn{1}{l}{\bf xx\_theta0...$<$k$>$} & ~ & |
| 1579 |
\multicolumn{1}{|c|}{~} & ~ & ~ \\ |
\multicolumn{1}{|c|}{~} & ~ & ~ \\ |
| 1580 |
\multicolumn{1}{l}{\bf xx\_salt0...$<$k$>$} & $\longrightarrow$ & |
\multicolumn{1}{l}{\bf xx\_salt0...$<$k$>$} & |
| 1581 |
|
$\stackrel{\mbox{read}}{\longrightarrow}$ & |
| 1582 |
\multicolumn{1}{|c|}{forward integration} & ~ & ~ \\ |
\multicolumn{1}{|c|}{forward integration} & ~ & ~ \\ |
| 1583 |
\multicolumn{1}{l}{\bf \vdots} & ~ & \multicolumn{1}{|c|}{~} |
\multicolumn{1}{l}{\bf \vdots} & ~ & \multicolumn{1}{|c|}{~} |
| 1584 |
& ~ & ~ \\ |
& ~ & ~ \\ |
| 1585 |
\cline{3-3} |
\cline{3-3} |
| 1586 |
~ & ~ & ~ & ~ & ~ \\ |
~ & ~ & $\downarrow$ & ~ & ~ \\ |
| 1587 |
\cline{3-3} |
\cline{3-3} |
| 1588 |
~ & ~ & |
~ & ~ & |
| 1589 |
\multicolumn{1}{|c|}{~} & ~ & |
\multicolumn{1}{|c|}{~} & ~ & |
| 1590 |
\multicolumn{1}{l}{\bf adxx\_theta0...$<$k$>$} \\ |
\multicolumn{1}{l}{\bf adxx\_theta0...$<$k$>$} \\ |
| 1591 |
~ & ~ & \multicolumn{1}{|c|}{adjoint integration} & |
~ & ~ & \multicolumn{1}{|c|}{adjoint integration} & |
| 1592 |
$\longrightarrow$ & |
$\stackrel{\mbox{write}}{\longrightarrow}$ & |
| 1593 |
\multicolumn{1}{l}{\bf adxx\_salt0...$<$k$>$} \\ |
\multicolumn{1}{l}{\bf adxx\_salt0...$<$k$>$} \\ |
| 1594 |
~ & ~ & \multicolumn{1}{|c|}{~} |
~ & ~ & \multicolumn{1}{|c|}{~} |
| 1595 |
& ~ & \multicolumn{1}{l}{\bf \vdots} \\ |
& ~ & \multicolumn{1}{l}{\bf \vdots} \\ |
| 1601 |
~ & ~ & ~ & ~ & {\big\downarrow} \\ |
~ & ~ & ~ & ~ & {\big\downarrow} \\ |
| 1602 |
~ & ~ & ~ & ~ & {\bf vector\_grad\_$<$k$>$ } \\ |
~ & ~ & ~ & ~ & {\bf vector\_grad\_$<$k$>$ } \\ |
| 1603 |
\end{tabular} |
\end{tabular} |
| 1604 |
|
} |
| 1605 |
|
|
| 1606 |
\vspace*{0.5cm} |
\vspace*{0.5cm} |
| 1607 |
|
|
| 1608 |
|
|
| 1609 |
{\it ctrl\_unpack} reads in the updated control vector |
{\it ctrl\_unpack} reads the updated control vector |
| 1610 |
{\bf vector\_ctrl\_$<$k$>$}. |
{\bf vector\_ctrl\_$<$k$>$}. |
| 1611 |
It distributes the different control variables to |
It distributes the different control variables to |
| 1612 |
2-dim. and 3-dim. files {\it xx\_...$<$k$>$}. |
2-dim. and 3-dim. files {\it xx\_...$<$k$>$}. |
| 1613 |
During the forward integration the control variables |
At the start of the forward integration the control variables |
| 1614 |
are read from {\it xx\_...$<$k$>$}. |
are read from {\it xx\_...$<$k$>$} and added to the |
| 1615 |
Correspondingly, the adjoint fields are written |
field. |
| 1616 |
|
Correspondingly, at the end of the adjoint integration |
| 1617 |
|
the adjoint fields are written |
| 1618 |
to {\it adxx\_...$<$k$>$}, again via the active file routines. |
to {\it adxx\_...$<$k$>$}, again via the active file routines. |
| 1619 |
Finally, {\it ctrl\_pack} collects all adjoint field files |
Finally, {\it ctrl\_pack} collects all adjoint files |
| 1620 |
and writes them to the compressed vector file |
and writes them to the compressed vector file |
| 1621 |
{\bf vector\_grad\_$<$k$>$}. |
{\bf vector\_grad\_$<$k$>$}. |
|
|
|
|
\subsection{TLM and ADM generation via TAMC} |
|
|
|
|
|
|
|
|
|
|
|
\subsection{Flow directives and adjoint support routines} |
|
|
|
|
|
\subsection{Store directives and checkpointing} |
|
|
|
|
|
\subsection{Gradient checks} |
|
|
|
|
|
\subsection{Second derivative generation via TAMC} |
|
|
|
|
|
\section{Example of adjoint code} |
|
Parent Directory
| 
Revision Log
| 
Revision Graph
| 
Patch