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