source: NEMO/branches/2019/dev_ASINTER-01-05_merged/cfgs/AGRIF_DEMO/README.rst @ 12165

Last change on this file since 12165 was 12165, checked in by davestorkey, 10 months ago

2019/dev_ASINTER-01-05_merged: Update to r12072 of trunk.

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