source: NEMO/trunk/cfgs/AGRIF_DEMO/README.rst @ 10201

Last change on this file since 10201 was 10201, checked in by nicolasmartin, 2 years ago

Various modifications related to the setting of a NEMO Quick Start Guide

  • Add missing namelist blocks from ICE and TOP
  • Create a hidden .global.rst to gather common URL links
  • Convert animated gif to frames images for PDF export
  • Place different README.rst appropriately in the code structure and refer to them with symbolic links in doc/rst/source
File size: 4.6 KB
Line 
1Embedded zooms with AGRIF
2=========================
3
4.. include:: .global.rst
5
6.. contents::
7   :local:
8
9--------
10Overview
11--------
12
13AGRIF (Adaptive Grid Refinement In Fortran) is a library that allows the seamless space and time refinement over
14rectangular regions in NEMO.
15Refinement factors can be odd or even (usually lower than 5 to maintain stability).
16Interaction between grid is "two-ways" in the sense that the parent grid feeds the child grid open boundaries and
17the child grid provides volume averages of prognostic variables once a given number of time step is completed.
18These pages provide guidelines how to use AGRIF in NEMO.
19For a more technical description of the library itself, please refer to http://agrif.imag.fr.
20
21-----------
22Compilation
23-----------
24
25Activating 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
31Although this is transparent to users, the way the code is processed during compilation is different from
32the standard case:
33a preprocessing stage (the so called "conv" program) translates the actual code so that
34saved arrays may be switched in memory space from one domain to an other.
35
36--------------------------------
37Definition of the grid hierarchy
38--------------------------------
39
40An additional text file ``AGRIF_FixedGrids.in`` is required at run time.
41This is where the grid hierarchy is defined.
42An 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
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 ``AGRIF_DEMO`` reference configuration directory.
54
55[Add some plots here with grid staggering and positioning ?]
56
57When creating the nested domain, one must keep in mind that the child domain is shifted toward north-east and
58depends on the number of ghost cells as illustrated by the (attempted) drawing below for nbghostcells=1 and
59nbghostcells=3.
60The 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
64Note that rectangular regions must be defined so that they are connected to a single parent grid.
65Hence, defining overlapping grids with the same refinement ratio will not work properly,
66boundary data exchange and update being only performed between root and child grids.
67Use of east-west periodic or north-fold boundary conditions is not allowed in child grids either.
68Defining for instance a circumpolar zoom in a global model is therefore not possible.
69
70-------------
71Preprocessing
72-------------
73
74Knowing 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).
76The key is to ensure volume matching near the child grid interface,
77a step done by invoking the ``Agrif_create_bathy.exe`` program.
78You may use the namelists provided in the ``NESTING`` directory as a guide.
79These correspond to the namelists used to create ``AGRIF_DEMO`` inputs.
80
81----------------
82Namelist options
83----------------
84
85Each 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
87the grid hierarchy).
88Consistent time steps and number of steps with the chosen time refinement have to be provided.
89Specific 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
102where sponge layer coefficients have to be chosen according to the child grid mesh size.
103The sponge area is hard coded in NEMO and applies on the following grid points:
1042 x refinement factor (from i=1+nbghostcells+1 to i=1+nbghostcells+sponge_area)
105
106----------
107References
108----------
109
110.. bibliography:: zooms.bib
111   :all:
112   :style: unsrt
Note: See TracBrowser for help on using the repository browser.