1 # Modular arbitrary-order ocean-atmosphere model: MAOOAM -- Stochastic Fortran implementation #
5 (c) 2013-2018 Lesley De Cruz and Jonathan Demaeyer
7 See [LICENSE.txt](../../LICENSE.txt) for license information.
9 This software is provided as supplementary material with:
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.
15 for the MAOOAM original code, and with
17 * Demaeyer, J. and Vannitsem, S.: Comparison of stochastic parameterizations in
18 the framework of a coupled ocean-atmosphere model, Nonlin. Processes Geophys.
21 for the stochastic part.
23 **Please cite both articles if you use (a part of) this software for a
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
30 Consult the MAOOAM [code repository](http://www.github.com/Climdyn/MAOOAM)
31 for updates, and [our website](http://climdyn.meteo.be) for additional
34 A pdf version of this manual is available [here](../latex/Reference_manual.pdf).
36 ------------------------------------------------------------------------
40 The program can be installed with Makefile. We provide configuration files for
41 two compilers : gfortran and ifort.
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
50 To install, unpack the archive in a folder or clone with git:
53 git clone https://github.com/Climdyn/MAOOAM.git
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:
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
74 Remark: The command "make clean" removes the compiled files.
76 ------------------------------------------------------------------------
78 ## Description of the files ##
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
84 The following files are part of the MAOOAM model alone:
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.
107 with the addition of the files:
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.
133 which belong specifically to the stochastic implementation.
136 ------------------------------------------------------------------------
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.
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
153 * Note that the variables of the model are numbered according to the chosen
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.
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 :
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 :
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)
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).
180 ------------------------------------------------------------------------
182 ## Stochastic code usage ##
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.
188 Full details over the parameterization options and definition files are available [here](sto_doc.md).
190 The program "maooam_stoch" will generate the evolution of the full stochastic dynamics with the command:
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)
199 The program "maooam_MTV" will generate the evolution of the MTV parameterization evolution, with the command:
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)
208 The program "maooam_WL" will generate the evolution of the MTV parameterization evolution, with the command:
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)
217 ------------------------------------------------------------------------
219 ## MAOOAM Implementation notes ##
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
225 \f[ \frac{d z_i}{dt} = \sum_{j,k=0}^{ndim} \, \mathcal{T}_{i,j,k} \, z_k \; z_j \f]
230 The tensor aotensor_def::aotensor is the tensor \f$\mathcal{T}\f$ that encodes the differential equations is composed so that:
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
238 Ideally, the tensor aotensor_def::aotensor is composed as an upper triangular matrix
239 (in the last two coordinates).
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.
244 ------------------------------------------------------------------------
246 ## Stochastic code implementation notes ##
248 A stochastic version of MAOOAM and two stochastic parameterization methods
249 (MTV and WL) are provided with this code.
251 The stochastic version of MAOOAM is given by
253 \f[ \frac{d \boldsymbol{z}}{dt} = f(\boldsymbol{z})+ \boldsymbol{q} \cdot \boldsymbol{dW} (t)\f]
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).
261 The MTV parameterization for MAOOAM is given by
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]
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.
268 The WL parameterizations for MAOOAM is given by
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]
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.
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).
279 ------------------------------------------------------------------------
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.
286 No animals were harmed during the coding process.