1 | ************** |
---|
2 | Embedded zooms |
---|
3 | ************** |
---|
4 | |
---|
5 | .. contents:: |
---|
6 | :local: |
---|
7 | |
---|
8 | Overview |
---|
9 | ======== |
---|
10 | |
---|
11 | AGRIF (Adaptive Grid Refinement In Fortran) is a library that allows the seamless space and time refinement over |
---|
12 | rectangular regions in NEMO. |
---|
13 | Refinement factors can be odd or even (usually lower than 5 to maintain stability). |
---|
14 | Interaction between grid is "two-ways" in the sense that the parent grid feeds the child grid open boundaries and |
---|
15 | the child grid provides volume averages of prognostic variables once a given number of time step is completed. |
---|
16 | These pages provide guidelines how to use AGRIF in NEMO. |
---|
17 | For a more technical description of the library itself, please refer to http://agrif.imag.fr. |
---|
18 | |
---|
19 | Compilation |
---|
20 | =========== |
---|
21 | |
---|
22 | Activating 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 | |
---|
28 | Although this is transparent to users, the way the code is processed during compilation is different from |
---|
29 | the standard case: |
---|
30 | a preprocessing stage (the so called "conv" program) translates the actual code so that |
---|
31 | saved arrays may be switched in memory space from one domain to an other. |
---|
32 | |
---|
33 | Definition of the grid hierarchy |
---|
34 | ================================ |
---|
35 | |
---|
36 | An additional text file ``AGRIF_FixedGrids.in`` is required at run time. |
---|
37 | This is where the grid hierarchy is defined. |
---|
38 | An 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 | |
---|
44 | The first line indicates the number of zooms (1). |
---|
45 | The 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). |
---|
47 | The last line is the number of child grid nested in the refined region (0). |
---|
48 | A more complex example with telescoping grids can be found below and |
---|
49 | in the ``AGRIF_DEMO`` reference configuration directory. |
---|
50 | |
---|
51 | [Add some plots here with grid staggering and positioning ?] |
---|
52 | |
---|
53 | When creating the nested domain, one must keep in mind that the child domain is shifted toward north-east and |
---|
54 | depends on the number of ghost cells as illustrated by the (attempted) drawing below for nbghostcells=1 and |
---|
55 | nbghostcells=3. |
---|
56 | The 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 | |
---|
60 | Note that rectangular regions must be defined so that they are connected to a single parent grid. |
---|
61 | Hence, defining overlapping grids with the same refinement ratio will not work properly, |
---|
62 | boundary data exchange and update being only performed between root and child grids. |
---|
63 | Use of east-west periodic or north-fold boundary conditions is not allowed in child grids either. |
---|
64 | Defining for instance a circumpolar zoom in a global model is therefore not possible. |
---|
65 | |
---|
66 | Preprocessing |
---|
67 | ============= |
---|
68 | |
---|
69 | Knowing 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). |
---|
71 | The key is to ensure volume matching near the child grid interface, |
---|
72 | a step done by invoking the ``Agrif_create_bathy.exe`` program. |
---|
73 | You may use the namelists provided in the ``NESTING`` directory as a guide. |
---|
74 | These correspond to the namelists used to create ``AGRIF_DEMO`` inputs. |
---|
75 | |
---|
76 | Namelist options |
---|
77 | ================ |
---|
78 | |
---|
79 | Each 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 |
---|
81 | the grid hierarchy). |
---|
82 | Consistent time steps and number of steps with the chosen time refinement have to be provided. |
---|
83 | Specific 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 | |
---|
96 | where sponge layer coefficients have to be chosen according to the child grid mesh size. |
---|
97 | The sponge area is hard coded in NEMO and applies on the following grid points: |
---|
98 | 2 x refinement factor (from i=1+nbghostcells+1 to i=1+nbghostcells+sponge_area) |
---|
99 | |
---|
100 | References |
---|
101 | ========== |
---|
102 | |
---|
103 | .. bibliography:: zooms.bib |
---|
104 | :all: |
---|
105 | :style: unsrt |
---|
106 | :labelprefix: A |
---|
107 | :keyprefix: a- |
---|