source: NEMO/branches/2019/dev_r11643_ENHANCE-11_CEthe_Shaconemo_diags/cfgs/AGRIF_DEMO/README.rst @ 11998

Last change on this file since 11998 was 10460, checked in by nicolasmartin, 23 months ago

Small modifications regarding README(s) and ReST files

File size: 4.5 KB
Line 
1**************
2Embedded zooms
3**************
4
5.. contents::
6   :local:
7
8Overview
9========
10
11AGRIF (Adaptive Grid Refinement In Fortran) is a library that allows the seamless space and time refinement over
12rectangular regions in NEMO.
13Refinement factors can be odd or even (usually lower than 5 to maintain stability).
14Interaction between grid is "two-ways" in the sense that the parent grid feeds the child grid open boundaries and
15the child grid provides volume averages of prognostic variables once a given number of time step is completed.
16These pages provide guidelines how to use AGRIF in NEMO.
17For a more technical description of the library itself, please refer to http://agrif.imag.fr.
18
19Compilation
20===========
21
22Activating AGRIF requires to append the cpp key ``key_agrif`` at compilation time:
23
24.. code-block:: sh
25
26   ./makenemo add_key 'key_agrif'
27
28Although this is transparent to users, the way the code is processed during compilation is different from
29the standard case:
30a preprocessing stage (the so called "conv" program) translates the actual code so that
31saved arrays may be switched in memory space from one domain to an other.
32
33Definition of the grid hierarchy
34================================
35
36An additional text file ``AGRIF_FixedGrids.in`` is required at run time.
37This is where the grid hierarchy is defined.
38An example of such a file, here taken from the ``ICEDYN`` test case, is given below::
39
40   1
41   34 63 34 63 3 3 3
42   0
43
44The first line indicates the number of zooms (1).
45The second line contains the starting and ending indices in both directions on the root grid
46(imin=34 imax=63 jmin=34 jmax=63) followed by the space and time refinement factors (3 3 3).
47The last line is the number of child grid nested in the refined region (0).
48A more complex example with telescoping grids can be found below and
49in the ``AGRIF_DEMO`` reference configuration directory.
50
51[Add some plots here with grid staggering and positioning ?]
52
53When creating the nested domain, one must keep in mind that the child domain is shifted toward north-east and
54depends on the number of ghost cells as illustrated by the (attempted) drawing below for nbghostcells=1 and
55nbghostcells=3.
56The grid refinement is 3 and nxfin is the number of child grid points in i-direction. 
57
58.. image:: _static/agrif_grid_position.jpg
59
60Note that rectangular regions must be defined so that they are connected to a single parent grid.
61Hence, defining overlapping grids with the same refinement ratio will not work properly,
62boundary data exchange and update being only performed between root and child grids.
63Use of east-west periodic or north-fold boundary conditions is not allowed in child grids either.
64Defining for instance a circumpolar zoom in a global model is therefore not possible.
65
66Preprocessing
67=============
68
69Knowing the refinement factors and area, a ``NESTING`` pre-processing tool may help to create needed input files
70(mesh file, restart, climatological and forcing files).
71The key is to ensure volume matching near the child grid interface,
72a step done by invoking the ``Agrif_create_bathy.exe`` program.
73You may use the namelists provided in the ``NESTING`` directory as a guide.
74These correspond to the namelists used to create ``AGRIF_DEMO`` inputs.
75
76Namelist options
77================
78
79Each child grid expects to read its own namelist so that different numerical choices can be made
80(these should be stored in the form ``1_namelist_cfg``, ``2_namelist_cfg``, etc... according to their rank in
81the grid hierarchy).
82Consistent time steps and number of steps with the chosen time refinement have to be provided.
83Specific to AGRIF is the following block:
84
85.. code-block:: fortran
86
87   !-----------------------------------------------------------------------
88   &namagrif      !  AGRIF zoom                                            ("key_agrif")
89   !-----------------------------------------------------------------------
90      ln_spc_dyn    = .true.  !  use 0 as special value for dynamics
91      rn_sponge_tra = 2880.   !  coefficient for tracer   sponge layer [m2/s]
92      rn_sponge_dyn = 2880.   !  coefficient for dynamics sponge layer [m2/s]
93      ln_chk_bathy  = .false. !  =T  check the parent bathymetry
94   /             
95
96where sponge layer coefficients have to be chosen according to the child grid mesh size.
97The sponge area is hard coded in NEMO and applies on the following grid points:
982 x refinement factor (from i=1+nbghostcells+1 to i=1+nbghostcells+sponge_area)
99
100References
101==========
102
103.. bibliography:: zooms.bib
104   :all:
105   :style: unsrt
106   :labelprefix: A
107   :keyprefix: a-
Note: See TracBrowser for help on using the repository browser.