A Modular Arbitrary-Order Ocean-Atmosphere Model -- Stochastic implementation
doc/gen_doc.md
Go to the documentation of this file.
1 # Modular arbitrary-order ocean-atmosphere model: MAOOAM -- Stochastic Fortran implementation #
2 
3 ## About ##
4 
5 (c) 2013-2018 Lesley De Cruz and Jonathan Demaeyer
6 
7 See [LICENSE.txt](../../LICENSE.txt) for license information.
8 
9 This software is provided as supplementary material with:
10 
11 * De Cruz, L., Demaeyer, J. and Vannitsem, S.: The Modular Arbitrary-Order
12 Ocean-Atmosphere Model: MAOOAM v1.0, Geosci. Model Dev., 9, 2793-2808,
13 [doi:10.5194/gmd-9-2793-2016](http://dx.doi.org/10.5194/gmd-9-2793-2016), 2016.
14 
15 for the MAOOAM original code, and with
16 
17 * Demaeyer, J. and Vannitsem, S.: Comparison of stochastic parameterizations in
18 the framework of a coupled ocean-atmosphere model, Nonlin. Processes Geophys.
19 Discuss., 2018.
20 
21 for the stochastic part.
22 
23 **Please cite both articles if you use (a part of) this software for a
24 publication.**
25 
26 The authors would appreciate it if you could also send a reprint of
27 your paper to <lesley.decruz@meteo.be>, <jonathan.demaeyer@meteo.be> and
28 <svn@meteo.be>.
29 
30 Consult the MAOOAM [code repository](http://www.github.com/Climdyn/MAOOAM)
31 for updates, and [our website](http://climdyn.meteo.be) for additional
32 resources.
33 
34 A pdf version of this manual is available [here](../latex/Reference_manual.pdf).
35 
36 ------------------------------------------------------------------------
37 
38 ## Installation ##
39 
40 The program can be installed with Makefile. We provide configuration files for
41 two compilers : gfortran and ifort.
42 
43 By default, gfortran is selected. To select one or the other, simply modify the
44 Makefile accordingly or pass the COMPILER flag to `make`. If gfortran is
45 selected, the code should be compiled with gfortran 4.7+ (allows for
46 allocatable arrays in namelists). If ifort is selected, the code has been
47 tested with the version 14.0.2 and we do not guarantee compatibility with older
48 compiler version.
49 
50 To install, unpack the archive in a folder or clone with git:
51 
52 ```bash
53 git clone https://github.com/Climdyn/MAOOAM.git
54 cd MAOOAM
55 ```
56 
57 and run:
58 
59 ```bash
60 make
61 ```
62 By default, the inner products of the basis functions, used to compute the
63 coefficients of the ODEs, are not stored in memory. If you want to enable the
64 storage in memory of these inner products, run make with the following flag:
65 
66 ```bash
67 make RES=store
68 ```
69 
70 Depending on the chosen resolution, storing the inner products may result in a
71 huge memory usage and is not recommended unless you need them for a specific
72 purpose.
73 
74  Remark: The command "make clean" removes the compiled files.
75 
76 ------------------------------------------------------------------------
77 
78 ## Description of the files ##
79 
80 The model tendencies are represented through a tensor called aotensor which
81 includes all the coefficients. This tensor is computed once at the program
82 initialization.
83 
84 The following files are part of the MAOOAM model alone:
85 
86 * maooam.f90 : Main program.
87 * aotensor_def.f90 : Tensor aotensor computation module.
88 * IC_def.f90 : A module which loads the user specified initial condition.
89 * inprod_analytic.f90 : Inner products computation module.
90 * rk2_integrator.f90 : A module which contains the Heun integrator for the model equations.
91 * rk4_integrator.f90 : A module which contains the RK4 integrator for the model equations.
92 * Makefile : The Makefile.
93 * params.f90 : The model parameters module.
94 * tl_ad_tensor.f90 : Tangent Linear (TL) and Adjoint (AD) model tensors definition module
95 * rk2_tl_ad_integrator.f90 : Heun Tangent Linear (TL) and Adjoint (AD) model integrators module
96 * rk4_tl_ad_integrator.f90 : RK4 Tangent Linear (TL) and Adjoint (AD) model integrators module
97 * test_tl_ad.f90 : Tests for the Tangent Linear (TL) and Adjoint (AD) model versions
98 * README.md : A read me file.
99 * LICENSE.txt : The license text of the program.
100 * util.f90 : A module with various useful functions.
101 * tensor.f90 : Tensor utility module.
102 * stat.f90 : A module for statistic accumulation.
103 * params.nml : A namelist to specify the model parameters.
104 * int_params.nml : A namelist to specify the integration parameters.
105 * modeselection.nml : A namelist to specify which spectral decomposition will be used.
106 
107 with the addition of the files:
108 
109 * maooam_stoch.f90 : Stochastic implementation of MAOOAM.
110 * maooam_MTV.f90 : Main program - MTV implementation for MAOOAM.
111 * maooam_WL.f90 : Main program - WL implementation for MAOOAM.
112 * corrmod.f90 : Unresolved variables correlation matrix initialization module.
113 * corr_tensor.f90 : Correlations and derivatives for the memory term of the WL parameterization.
114 * dec_tensor.f90 : Tensor resolved-unresolved components decomposition module.
115 * int_comp.f90 : Utility module containing the routines to perform the integration of functions.
116 * int_corr.f90 : Module to compute or load the integrals of the correlation matrices.
117 * MAR.f90 : Multidimensional AutoRegressive (MAR) module to generate the correlation for the WL parameterization.
118 * memory.f90 : WL parameterization memory term \f$M_3\f$ computation module.
119 * MTV_int_tensor.f90 : MTV tensors computation module.
120 * MTV_sigma_tensor.f90 : MTV noise sigma matrices computation module.
121 * WL_tensor.f90 : WL tensors computation module.
122 * rk2_stoch_integrator.f90 : Stochastic RK2 integration routines module.
123 * rk2_ss_integrator.f90 : Stochastic uncoupled resolved nonlinear and tangent linear RK2 dynamics integration module.
124 * rk2_MTV_integrator.f90 : MTV RK2 integration routines module.
125 * rk2_WL_integrator.f90 : WL RK2 integration routines module.
126 * sf_def.f90 : Module to select the resolved-unresolved components.
127 * SF.nml : A namelist to select the resolved-unresolved components.
128 * sqrt_mod.f90 : Utility module with various routine to compute matrix square root.
129 * stoch_mod.f90 : Utility module containing the stochastic related routines.
130 * stoch_params.f90 : Stochastic models parameters module.
131 * stoch_params.nml : A namelist to specify the stochastic models parameters.
132 
133 which belong specifically to the stochastic implementation.
134 
135 
136 ------------------------------------------------------------------------
137 
138 ## MAOOAM Usage ##
139 
140 The user first has to fill the params.nml and int_params.nml namelist files according to their needs.
141 Indeed, model and integration parameters can be specified respectively in the params.nml and int_params.nml namelist files. Some examples related to already published article are available in the params folder.
142 
143 The modeselection.nml namelist can then be filled :
144 * NBOC and NBATM specify the number of blocks that will be used in respectively the ocean and
145  the atmosphere. Each block corresponds to a given x and y wavenumber.
146 * The OMS and AMS arrays are integer arrays which specify which wavenumbers of
147  the spectral decomposition will be used in respectively the ocean and the
148  atmosphere. Their shapes are OMS(NBOC,2) and AMS(NBATM,2).
149 * The first dimension specifies the number attributed by the user to the block and the second
150  dimension specifies the x and the y wavenumbers.
151 * The VDDG model, described in Vannitsem et al. (2015) is given as an example
152  in the archive.
153 * Note that the variables of the model are numbered according to the chosen
154  order of the blocks.
155 
156 The Makefile allows to change the integrator being used for the time evolution.
157 The user should modify it according to its need.
158 By default a RK2 scheme is selected.
159 
160 Finally, the IC.nml file specifying the initial condition should be defined. To
161 obtain an example of this configuration file corresponding to the model you
162 have previously defined, simply delete the current IC.nml file (if it exists)
163 and run the program :
164 
165  ./maooam
166 
167 It will generate a new one and start with the 0 initial condition. If you want another
168 initial condition, stop the program, fill the newly generated file and restart :
169 
170  ./maooam
171 
172 It will generate two files :
173  * evol_field.dat : the recorded time evolution of the variables.
174  * mean_field.dat : the mean field (the climatology)
175 
176 The tangent linear and adjoint models of MAOOAM are provided in the
177 tl_ad_tensor, rk2_tl_ad_integrator and rk4_tl_ad_integrator modules. It is
178 documented [here](tl_ad_doc.md).
179 
180 ------------------------------------------------------------------------
181 
182 ## Stochastic code usage ##
183 
184 The user first has to fill the MAOOAM model namelist files according to their needs (see the previous section).
185 Additional namelist files for the fine tuning of the parameterization must then be filled,
186 and some "definition" files (with the extension .def) must be provided. An example is provided with the code.
187 
188 Full details over the parameterization options and definition files are available [here](sto_doc.md).
189 
190 The program "maooam_stoch" will generate the evolution of the full stochastic dynamics with the command:
191 
192  ./maooam_stoch
193 
194 or any other dynamics if specified as an argument (see the header of [maooam_stoch.f90](./maooam_stoch.f90)).
195 It will generate two files :
196  * evol_field.dat : the recorded time evolution of the variables.
197  * mean_field.dat : the mean field (the climatology)
198 
199 The program "maooam_MTV" will generate the evolution of the MTV parameterization evolution, with the command:
200 
201  ./maooam_MTV
202 
203 It will generate three files :
204  * evol_MTV.dat : the recorded time evolution of the variables.
205  * ptend_MTV.dat : the recorded time evolution of the tendencies (used for debugging).
206  * mean_field_MTV.dat : the mean field (the climatology)
207 
208 The program "maooam_WL" will generate the evolution of the MTV parameterization evolution, with the command:
209 
210  ./maooam_WL
211 
212 It will generate three files :
213  * evol_WL.dat : the recorded time evolution of the variables.
214  * ptend_WL.dat : the recorded time evolution of the tendencies (used for debugging).
215  * mean_field_WL.dat : the mean field (the climatology)
216 
217 ------------------------------------------------------------------------
218 
219 ## MAOOAM Implementation notes ##
220 
221 As the system of differential equations is at most bilinear in \f$z_j\f$ (\f$j=1..n\f$),
222 \f$\boldsymbol{z}\f$ being the array of variables, it can be expressed as a tensor
223  contraction :
224 
225 \f[ \frac{d z_i}{dt} = \sum_{j,k=0}^{ndim} \, \mathcal{T}_{i,j,k} \, z_k \; z_j \f]
226 
227 with \f$z_0 = 1\f$.
228 
229 
230 The tensor aotensor_def::aotensor is the tensor \f$\mathcal{T}\f$ that encodes the differential equations is composed so that:
231 
232 * \f$\mathcal{T}_{i,j,k}\f$ contains the contribution of \f$dz_i/dt\f$ proportional to \f$ z_j \, z_k\f$.
233 * Furthermore, \f$z_0\f$ is always equal to 1, so that \f$\mathcal{T}_{i,0,0}\f$ is the constant
234 contribution to \f$dz_i/dt\f$
235 * \f$\mathcal{T}_{i,j,0} + \mathcal{T}_{i,0,j}\f$ is the contribution to \f$dz_i/dt\f$ which is linear in
236 \f$z_j\f$.
237 
238 Ideally, the tensor aotensor_def::aotensor is composed as an upper triangular matrix
239 (in the last two coordinates).
240 
241 The tensor for this model is composed in the aotensor_def module and uses the
242 inner products defined in the inprod_analytic module.
243 
244 ------------------------------------------------------------------------
245 
246 ## Stochastic code implementation notes ##
247 
248 A stochastic version of MAOOAM and two stochastic parameterization methods
249 (MTV and WL) are provided with this code.
250 
251 The stochastic version of MAOOAM is given by
252 
253 \f[ \frac{d \boldsymbol{z}}{dt} = f(\boldsymbol{z})+ \boldsymbol{q} \cdot \boldsymbol{dW} (t)\f]
254 
255 where \f$\boldsymbol{dW}\f$ is a vector of standard Gaussian White noise and where several choice for \f$f(\boldsymbol{z})\f$ are available.
256 For instance, the default choice is to use the full dynamics:
257 \f[ f(\boldsymbol{z}) = \sum_{j,k=0}^{ndim} \, \mathcal{T}_{i,j,k} \, z_k \; z_j . \f]
258 The implementation uses the tensorial framework described above and add some noise to it.
259 This stochastic version is further detailed [here](sto_doc.md).
260 
261 The MTV parameterization for MAOOAM is given by
262 
263 \f[ \frac{d\boldsymbol{x}}{dt} = F_x(\boldsymbol{x}) + \frac{1}{\delta} R(\boldsymbol{x}) + G(\boldsymbol{x}) + \sqrt{2} \,\, \boldsymbol{\sigma}(\boldsymbol{x}) \cdot \boldsymbol{dW} \f]
264 
265 where \f$\boldsymbol{x}\f$ is the set of resolved variables and \f$\boldsymbol{dW}\f$ is a vector of standard Gaussian White noise.
266 \f$F_x\f$ is the set of tendencies of resolved system alone and \f$\delta\f$ is the timescale separation parameter.
267 
268 The WL parameterizations for MAOOAM is given by
269 
270 \f[\frac{d\boldsymbol{x}}{dt} = F_x(\boldsymbol{x}) + \varepsilon \, M_1(\boldsymbol{x}) + \varepsilon^2 \, M_2(\boldsymbol{x},t) + \varepsilon^2 \, M_3 (\boldsymbol{x},t)\f]
271 
272 where \f$\varepsilon\f$ is the resolved-unresolved components coupling strenght and where the different terms \f$M_i\f$ account for different effect.
273 
274 The implementation for these two approaches uses the tensorial framework described above, with the addition of new tensors to account for the
275 terms \f$R,G,\sigma,M_1,M_2,M_3\f$. They are detailed more completely [here](sto_doc.md).
276 
277 
278 
279 ------------------------------------------------------------------------
280 
281 ## Final Remarks ##
282 
283 The authors would like to thank Kris for help with the lua2fortran project. It
284 has greatly reduced the amount of (error-prone) work.
285 
286  No animals were harmed during the coding process.