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