Warning, /doc/examples/deep_convection/deep_convection.rst is written in an unsupported language. File is not indexed.
view on githubraw file Latest commit 0bad585a on 2022-02-16 18:55:09 UTC
1c8cebb321 Jeff*0001 .. _sec_deep_convection:
d67096e55c Jeff*0002
1c8cebb321 Jeff*0003 Deep Convection
0004 ===============
d67096e55c Jeff*0005
0006 (in directory: :filelink:`verification/tutorial_deep_convection/`)
0007
0008 .. figure:: figs/simulation_config.png
0009 :width: 80%
0010 :align: center
0011 :alt: deep convection setup
0012 :name: tut_deep_cvct_config
0013
0014 Schematic of simulation domain for the surface driven convection experiment. The domain is doubly periodic with an initially uniform temperature of 20 :sup:`o`\ C.
0015
0016 This experiment, :numref:`tut_deep_cvct_config`, showcasing
0017 MITgcm’s non-hydrostatic capability, was designed to explore the
0018 temporal and spatial characteristics of convection plumes as they might
0019 exist during a period of oceanic deep convection. It is
0020
0021 - non-hydrostatic
0022
0023 - doubly-periodic with cubic geometry
0024
0025 - discretized with 50 m resolution in :math:`x, y, z`
0026
0027 - Cartesian
0028
0029 - on an :math:`f`-plane
0030
0031 - using a linear equation of state
0032
0033 Overview
0034 --------
0035
0036 The model domain consists of an approximately 3 km square by 1 km deep
0037 box of initially unstratified, resting fluid. The domain is doubly
0038 periodic.
0039
0040 The experiment has 20 levels in the vertical, each of equal thickness
0041 :math:`\Delta z =` 50 m (the horizontal resolution is also 50 m). The
0042 fluid is initially unstratified with a uniform reference potential
0043 temperature :math:`\theta =` 20 :sup:`o`\ C. The equation of state
0044 used in this experiment is linear
0045
0046 .. math::
0047 \rho = \rho_{0} ( 1 - \alpha_{\theta}\theta^{'} )
0048 :label: eg-bconv-linear1_eos
0049
0050 which is implemented in the model as a density anomaly equation
0051
0052 .. math::
0053 \rho^{'} = -\rho_{0}\alpha_{\theta}\theta^{'}
0054 :label: eg-bconv-linear1_eos_pert
0055
0056 with :math:`\rho_{0}=1000\,{\rm kg\,m}^{-3}` and
0057 :math:`\alpha_{\theta}=2\times10^{-4}\,{\rm degrees}^{-1}`. Integrated
0058 forward in this configuration, the model state variable :varlink:`theta` is
0059 equivalent to either in-situ temperature, :math:`T`, or potential
0060 temperature, :math:`\theta`. For consistency with other examples, in
0061 which the equation of state is non-linear, we use :math:`\theta` to
0062 represent temperature here. This is the quantity that is carried in the
0063 model core equations.
0064
0065 As the fluid in the surface layer is cooled (at a mean rate of 800
0066 Wm\ :math:`^2`), it becomes convectively unstable and overturns, at
0067 first close to the grid-scale, but, as the flow matures, on larger
0068 scales (:numref:`tut_deep_cvct_vert_section` and
0069 :numref:`tut_deep_cvct_surf_section`), under the influence of rotation
0070 (:math:`f_o = 10^{-4}` s\ :math:`^{-1}`).
0071
0072 .. figure:: figs/verticalsection.png
0073 :width: 80%
0074 :align: center
0075 :alt: vertical section deep cvct exp
0076 :name: tut_deep_cvct_vert_section
0077
0078 Vertical section
0079
0080 .. figure:: figs/surfacesection.png
0081 :width: 80%
0082 :align: center
0083 :alt: surface section deep cvct exp
0084 :name: tut_deep_cvct_surf_section
0085
0086 Surface section
0087
0088 Model parameters are specified in file :filelink:`input/data <verification/tutorial_deep_convection/input/data>`. The grid dimensions
0089 are prescribed in :filelink:`code/SIZE.h <verification/tutorial_deep_convection/code/SIZE.h>`. The forcing (file ``input/Qsurf.bin``) is
0090 specified in a binary data file generated using the Matlab script
0091 :filelink:`input/gendata.m <verification/tutorial_deep_convection/input/gendata.m>`.
0092
0093 Equations solved
0094 ----------------
0095
0096 The model is configured in non-hydrostatic form, that is, all terms in
0097 the Navier Stokes equations are retained and the pressure field is
0098 found, subject to appropriate boundary conditions, through inversion of
0099 a 3-D elliptic equation.
0100
0101 The implicit free surface form of the pressure equation described in
0102 Marshall et. al (1997) :cite:`marshall:97a` is employed. A
0103 horizontal Laplacian operator :math:`\nabla_{h}^2` provides viscous
0104 dissipation. The thermodynamic forcing appears as a sink in the
0105 equation for potential temperature :math:`\theta`. This produces a set of equations
0106 solved in this configuration as follows:
0107
0108 .. math::
0109
0110 \begin{aligned}
0111 \frac{Du}{Dt} - fv +
0112 \frac{1}{\rho}\frac{\partial p^{'}}{\partial x} -
0113 \nabla_{h}\cdot A_{h}\nabla_{h}u -
0114 \frac{\partial}{\partial z}A_{z}\frac{\partial u}{\partial z}
0bad585a21 Navi*0115 & =
d67096e55c Jeff*0116 \begin{cases}
0117 0 & \text{(surface)} \\
0118 0 & \text{(interior)}
0119 \end{cases}
0120 \\
0121 \frac{Dv}{Dt} + fu +
0122 \frac{1}{\rho}\frac{\partial p^{'}}{\partial y} -
0123 \nabla_{h}\cdot A_{h}\nabla_{h}v -
0124 \frac{\partial}{\partial z}A_{z}\frac{\partial v}{\partial z}
0bad585a21 Navi*0125 & =
d67096e55c Jeff*0126 \begin{cases}
0127 0 & \text{(surface)} \\
0128 0 & \text{(interior)}
0129 \end{cases}
0130 \\
0131 \frac{Dw}{Dt} + g \frac{\rho^{'}}{\rho} +
0132 \frac{1}{\rho}\frac{\partial p^{'}}{\partial z} -
0133 \nabla_{h}\cdot A_{h}\nabla_{h}w -
0134 \frac{\partial}{\partial z}A_{z}\frac{\partial w}{\partial z}
0bad585a21 Navi*0135 & =
d67096e55c Jeff*0136 \begin{cases}
0137 0 & \text{(surface)} \\
0138 0 & \text{(interior)}
0139 \end{cases}
0140 \\
0141 \frac{\partial u}{\partial x} +
0142 \frac{\partial v}{\partial y} +
0143 \frac{\partial w}{\partial z} +
0bad585a21 Navi*0144 &=
d67096e55c Jeff*0145 0
0146 \\
0147 \frac{D\theta}{Dt} -
0148 \nabla_{h}\cdot K_{h}\nabla_{h}\theta
0149 - \frac{\partial}{\partial z}K_{z}\frac{\partial\theta}{\partial z}
0bad585a21 Navi*0150 & =
d67096e55c Jeff*0151 \begin{cases}
0152 {\cal F}_\theta & \text{(surface)} \\
0153 0 & \text{(interior)}
0154 \end{cases}
0155 \end{aligned}
0156
0157 where :math:`u=\frac{Dx}{Dt}`, :math:`v=\frac{Dy}{Dt}` and
0158 :math:`w=\frac{Dz}{Dt}` are the components of the flow vector in
0159 directions :math:`x`, :math:`y` and :math:`z`. The pressure is
0160 diagnosed through inversion (subject to appropriate boundary
0161 conditions) of a 3-D elliptic equation derived from the divergence of
0162 the momentum equations and continuity (see :numref:`finding_the_pressure_field`).
0163
0164 Discrete numerical configuration
0165 --------------------------------
0166
0167 The domain is discretized with a uniform grid spacing in each direction.
0168 There are 64 grid cells in directions :math:`x` and :math:`y` and 20
0169 vertical levels thus the domain comprises a total of just over 80,000
0170 gridpoints.
0171
0172 Numerical stability criteria and other considerations
0173 -----------------------------------------------------
0174
0175 For a heat flux of 800 Wm\ :math:`^2` and a rotation rate of
0176 :math:`10^{-4}` s\ :math:`^{-1}` the plume-scale can be expected to be a
0177 few hundred meters guiding our choice of grid resolution. This in turn
0178 restricts the timestep we can take. It is also desirable to minimize the
0179 level of diffusion and viscosity we apply.
0180
0181 For this class of problem it is generally the advective time-scale which
0182 restricts the timestep.
0183
0184 For an extreme maximum flow speed of :math:`| \vec{u} | = 1 ms^{-1}`,
0185 at a resolution of 50 m, the implied maximum timestep for stability,
0186 :math:`\delta t_u` is
0187
0188 .. math::
0189 \delta t_u = \frac{\Delta x}{| \vec{u} |} = 50 s
0190
0191 The choice of :math:`\delta t = 10` s is a safe 20 percent of this
0192 maximum.
0193
0194 Interpreted in terms of a mixing-length hypothesis, a magnitude of
0195 Laplacian diffusion coefficient :math:`\kappa_h (=
0196 \kappa_v) = 0.1` m\ :math:`^2`\ s\ :math:`^{-1}` is consistent with an
0197 eddy velocity of 2 mm s\ :math:`^{-1}` correlated over 50 m.
0198
0199 Experiment configuration
0200 ------------------------
0201
0202 The model configuration for this experiment resides under the directory
0203 *verification/convection/*. The experiment files
0204
0205 - :filelink:`code/CPP_OPTIONS.h <verification/tutorial_deep_convection/code/CPP_OPTIONS.h>`
0206 - :filelink:`code/SIZE.h <verification/tutorial_deep_convection/code/SIZE.h>`
0207 - :filelink:`input/data <verification/tutorial_deep_convection/input/data>`
0208 - :filelink:`input/data.pkg <verification/tutorial_deep_convection/input/data.pkg>`
0209 - :filelink:`input/eedata <verification/tutorial_deep_convection/input/eedata>`
0210 - ``input/Qsurf.bin``,
0211
0212 contain the code customizations and parameter settings for this
0213 experiment. Below we describe these experiment-specific customizations.
0214
0215 File :filelink:`code/CPP_OPTIONS.h <verification/tutorial_deep_convection/code/CPP_OPTIONS.h>`
0216 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0217
0218 This file uses standard default values and does not contain
0219 customizations for this experiment.
0220
0221 File :filelink:`code/SIZE.h <verification/tutorial_deep_convection/code/SIZE.h>`
0222 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0223
0224 .. literalinclude:: ../../../verification/tutorial_deep_convection/code/SIZE.h
0225 :linenos:
0226 :caption: verification/tutorial_deep_convection/code/SIZE.h
0227
0228 Three lines are customized in this file. These prescribe the domain grid
0229 dimensions.
0230
0231 - Line 45,
0232
0233 ::
0234
0235 sNx=50,
0236
0237 this line sets the lateral domain extent in grid points for the axis
0238 aligned with the :math:`x`-coordinate.
0239
0240 - Line 46,
0241
0242 ::
0243
0244 sNy=50,
0245
0246 this line sets the lateral domain extent in grid points for the axis
0247 aligned with the :math:`y`-coordinate.
0248
0249 - Line 55,
0250
0251 ::
0252
0253 Nr=50,
0254
0255 this line sets the vertical domain extent in grid points.
0256
0257 File :filelink:`input/data <verification/tutorial_deep_convection/input/data>`
0258 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0259
0260 .. literalinclude:: ../../../verification/tutorial_deep_convection/input/data
0261 :linenos:
0262 :caption: verification/tutorial_deep_convection/input/data
0263
0264 This file specifies the main parameters
0265 for the experiment. The parameters that are significant for this
0266 configuration are
0267
0268 - Line 7,
0269
0270 ::
0271
0272 tRef=20*20.0,
0273
0274 this line sets the initial and reference values of potential
0275 temperature at each model level in units of
0276 :math:`^{\circ}\mathrm{C}`. Here the value is arbitrary since, in
0277 this case, the flow evolves independently of the absolute magnitude
0278 of the reference temperature. For each depth level the initial and
0279 reference profiles will be uniform in :math:`x` and :math:`y`.
0280
0281 - Line 8,
0282
0283 ::
0284
0285 sRef=20*35.0,
0286
0287 this line sets the initial and reference values of salinity at each
0288 model level in units of ppt. In this case salinity is set to an
0289 (arbitrary) uniform value of 35.0 ppt. However since, in this
0290 example, density is independent of salinity, an appropriately defined
0291 initial salinity could provide a useful passive tracer. For each
0292 depth level the initial and reference profiles will be uniform in
0293 :math:`x` and :math:`y`.
0294
0295 - Line 9,
0296
0297 ::
0298
0299 viscAh=0.1,
0300
0301 this line sets the horizontal Laplacian dissipation coefficient to
0302 0.1 :math:`{\rm m^{2}s^{-1}}`. Boundary conditions for this operator
0303 are specified later.
0304
0305 - Line 10,
0306
0307 ::
0308
0309 viscAz=0.1,
0310
0311 this line sets the vertical Laplacian frictional dissipation
0312 coefficient to 0.1 :math:`{\rm m^{2}s^{-1}}`. Boundary conditions for
0313 this operator are specified later.
0314
0315 - Line 11,
0316
0317 ::
0318
0319 no_slip_sides=.FALSE.
0320
0321 this line selects a free-slip lateral boundary condition for the
0322 horizontal Laplacian friction operator e.g.
0323 :math:`\frac{\partial u}{\partial y}`\ =0 along boundaries in
0324 :math:`y` and :math:`\frac{\partial v}{\partial x}`\ =0 along
0325 boundaries in :math:`x`.
0326
0327 - Lines 12,
0328
0329 ::
0330
0331 no_slip_bottom=.TRUE.
0332
0333 this line selects a no-slip boundary condition for the bottom
0334 boundary condition in the vertical Laplacian friction operator e.g.,
0335 :math:`u=v=0` at :math:`z=-H`, where :math:`H` is the local depth of
0336 the domain.
0337
0338 - Line 13,
0339
0340 ::
0341
0342 diffKhT=0.1,
0343
0344 this line sets the horizontal diffusion coefficient for temperature
0345 to 0.1 :math:`\rm m^{2}s^{-1}`. The boundary condition on this
0346 operator is
0347 :math:`\frac{\partial}{\partial x}=\frac{\partial}{\partial y}=0` at
0348 all boundaries.
0349
0350 - Line 14,
0351
0352 ::
0353
0354 diffKzT=0.1,
0355
0356 this line sets the vertical diffusion coefficient for temperature to
0357 0.1 :math:`{\rm m^{2}s^{-1}}`. The boundary condition on this
0358 operator is :math:`\frac{\partial}{\partial z}` = 0 on all
0359 boundaries.
0360
0361 - Line 15,
0362
0363 ::
0364
0365 f0=1E-4,
0366
0367 this line sets the Coriolis parameter to :math:`1 \times 10^{-4}`
0368 s\ :math:`^{-1}`. Since :math:`\beta = 0.0` this value is then
0369 adopted throughout the domain.
0370
0371 - Line 16,
0372
0373 ::
0374
0375 beta=0.E-11,
0376
0377 this line sets the the variation of Coriolis parameter with latitude
0378 to :math:`0`.
0379
0380 - Line 17,
0381
0382 ::
0383
0384 tAlpha=2.E-4,
0385
0386 This line sets the thermal expansion coefficient for the fluid to
0387 :math:`2 \times 10^{-4}` :sup:`o`\ C\ :math:`^{-1}`.
0388
0389 - Line 18,
0390
0391 ::
0392
0393 sBeta=0,
0394
0395 This line sets the saline expansion coefficient for the fluid to
0396 :math:`0`, consistent with salt’s passive role in this example.
0397
0398 - Line 23-24,
0399
0400 ::
0401
0402 rigidLid=.FALSE.,
0403 implicitFreeSurface=.TRUE.,
0404
0405 Selects the barotropic pressure equation to be the implicit free
0406 surface formulation.
0407
0408 - Line 26,
0409
0410 ::
0411
0412 eosType='LINEAR',
0413
0414 Selects the linear form of the equation of state.
0415
0416 - Line 27,
0417
0418 ::
0419
0420 nonHydrostatic=.TRUE.,
0421
0422 Selects for non-hydrostatic code.
0423
0424 - Line 33,
0425
0426 ::
0427
0428 cg2dMaxIters=1000,
0429
0430 Inactive - the pressure field in a non-hydrostatic simulation is
0431 inverted through a 3-D elliptic equation.
0432
0433 - Line 34,
0434
0435 ::
0436
0437 cg2dTargetResidual=1.E-9,
0438
0439 Inactive - the pressure field in a non-hydrostatic simulation is
0440 inverted through a 3-D elliptic equation.
0441
0442 - Line 35,
0443
0444 ::
0445
0446 cg3dMaxIters=40,
0447
0448 This line sets the maximum number of iterations the
0449 3-D conjugate gradient solver will use to 40,
0450 **irrespective of the convergence criteria being met**.
0451
0452 - Line 36,
0453
0454 ::
0455
0456 cg3dTargetResidual=1.E-9,
0457
0458 Sets the tolerance which the 3-D conjugate gradient
0459 solver will use to test for convergence in equation :eq:`phi-nh` to
0460 :math:`1 \times 10^{-9}`. The solver will iterate until the tolerance
0461 falls below this value or until the maximum number of solver
0462 iterations is reached.
0463
0464 - Line43,
0465
0466 ::
0467
0468 nTimeSteps=8640.,
0469
0470 Sets the number of timesteps at which this simulation will terminate
0471 (in this case 8640 timesteps or 1 day or :math:`\delta t = 10` s). At
0472 the end of a simulation a checkpoint file is automatically written so
0473 that a numerical experiment can consist of multiple stages.
0474
0475 - Line 44,
0476
0477 ::
0478
0479 deltaT=10,
0480
0481 Sets the timestep :math:`\delta t` to 10 s.
0482
0483 - Line 57,
0484
0485 ::
0486
0487 dXspacing=50.0,
0488
0489 Sets horizontal (:math:`x`-direction) grid interval to 50 m.
0490
0491 - Line 58,
0492
0493 ::
0494
0495 dYspacing=50.0,
0496
0497 Sets horizontal (:math:`y`-direction) grid interval to 50 m.
0498
0499 - Line 59,
0500
0501 ::
0502
0503 delZ=20*50.0,
0504
0505 Sets vertical grid spacing to 50 m. Must be consistent with
0506 :filelink:`code/SIZE.h <verification/tutorial_deep_convection/code/SIZE.h>`.
0507 Here, 20 corresponds to the number of vertical levels.
0508
0509 - Line64,
0510
0511 ::
0512
0513 surfQfile='Qsurf.bin'
0514
0515 This line specifies the name of the file from which the surface heat
0516 flux is read. This file is a 2-D (:math:`x,y`) map. It is
0517 assumed to contain 64-bit binary numbers giving the value of
0518 :math:`Q` (W m\ :math:`^2`) to be applied in each surface grid cell,
0519 ordered with the :math:`x` coordinate varying fastest. The points are
0520 ordered from low coordinate to high coordinate for both axes. The
0521 matlab program :filelink:`input/gendata.m <verification/tutorial_deep_convection/input/gendata.m>`
0522 shows how to generate the surface
0523 heat flux file used in the example.
0524
0525 File :filelink:`input/data.pkg <verification/tutorial_deep_convection/input/data.pkg>`
0526 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0527
0528 This file uses standard default values and does not contain
0529 customizations for this experiment.
0530
0531 File :filelink:`input/eedata <verification/tutorial_deep_convection/input/eedata>`
0532 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0533
0534 This file uses standard default values and does not contain
0535 customizations for this experiment.
0536
0537 File ``input/Qsurf.bin``
0538 ~~~~~~~~~~~~~~~~~~~~~~~~
0539
0540 The file ``input/Qsurf.bin`` specifies a 2-D (:math:`x,y`) map
0541 of heat flux values where
0542 :math:`Q = Q_o \times ( 0.5 + \mbox{random number between 0 and 1})`.
0543
0544 In the example :math:`Q_o = 800` W m\ :math:`^{-2}` so that values of
0545 :math:`Q` lie in the range 400 to 1200 W m\ :math:`^{-2}` with a mean of
0546 :math:`Q_o`. Although the flux models a loss, because it is directed
0547 upwards, according to the model’s sign convention, :math:`Q` is
0548 positive.
0549
