= Using AGRIF for embedded zooms in NEMO [[PageOutline(2-3)]] Last edition: '''[[Wikinfo(changed_ts)]]''' by '''[[Wikinfo(changed_by)]]''' [[span(Page in progress, style=background-color:lime)]] == Overview AGRIF (Adaptive Grid Refinement In Fortran) is a library that allows the seamless space and time refinement over rectangular regions in NEMO. Refinement factors can be odd or even (usually lower than 5 to maintain stability). Interaction between grid is "two-ways" in the sense that the parent grid feeds the child grid open boundaries and the child grid provides volume averages of prognostic variables once a given number of time step is completed. These pages provide guidelines how to use AGRIF in NEMO. For a more technical description of the library itself, please refer to the following link: [http://agrif.imag.fr]. == Compilation Activating AGRIF requires to append the cpp key "key_agrif" at compilation time: {{{#!sh ./makenemo add_key 'key_agrif' }}} Although this is transparent to users, the way the code is processed during compilation is different from the standard case: a preprocessing stage (the so called "conv" program) translates the actual code so that saved arrays may be be switched in memory space from one domain to an other. == Definition of the grid hierarchy An additional text file `AGRIF_FixedGrids.in` is required at run time. This is where the grid hierarchy is defined. An example of such a file, here taken from the [source:/NEMO/releases/r4.0/r4.0-HEAD/tests/ICE_AGRIF 'ICE_AGRIF' test case], is given below: {{{ 1 34 63 34 63 3 3 3 0 }}} The first line indicates the number of zooms (1). The second line contains the starting and ending indices in both directions on the root grid (imin=34 imax=63 jmin=34 jmax=63) followed by the space and time refinement factors (3 3 3). The last line is the number of child grid nested in the refined region (0). A more complex example with telescoping grids can be found below and in the [source:/NEMO/trunk/cfgs/AGRIF_DEMO@10075 'AGRIF_DEMO' reference configuration directory] (NEMO 4.0 only). [[span(''Add some plots here with grid staggering and positioning ?'', style=background-color:lime)]] When creating the nested domain, one must keep in mind that the child domain is shifted toward north-east and depends on the number of ghost cells as illustrated by the (attempted) drawing below for nbghostcells=1 and nbghostcells=3. The grid refinement is 3 and nxfin is the number of child grid points in i-direction. [[Image(agrif_grid_position.jpg,33%,center)]] Note that rectangular regions must be defined so that they are connected to a single parent grid. Hence, defining overlapping grids with the same refinement ratio will not work properly, boundary data exchange and update being only performed between root and child grids. Use of east-west periodic or north-fold boundary conditions is not allowed in child grids either. Defining for instance a circumpolar zoom in a global model is therefore not possible. == Preprocessing Knowing the refinement factors and area, a [source:/utils/tools/NESTING@10029 pre-processing tool] may help to create needed input files (mesh file, restart, climatological and forcing files). The key is to ensure volume matching near the child grid interface, a step done by invoking the Agrif_create_bathy.exe program. You may use the namelists provided in the `NESTING` directory as a guide. These correspond to the namelists used to create `AGRIF_DEMO` inputs. == Namelist options Each child grid expects to read its own namelist so that different numerical choices can be made (these should be stored in the form `1_namelist_cfg`, `2_namelist_cfg`, etc... according to their rank in the grid hierarchy). Consistent time steps and number of steps with the chosen time refinement have to be provided. Specific to AGRIF is the following block: {{{#!fortran !----------------------------------------------------------------------- &namagrif ! AGRIF zoom ("key_agrif") !----------------------------------------------------------------------- ln_spc_dyn = .true. ! use 0 as special value for dynamics rn_sponge_tra = 2880. ! coefficient for tracer sponge layer [m2/s] rn_sponge_dyn = 2880. ! coefficient for dynamics sponge layer [m2/s] ln_chk_bathy = .false. ! =T check the parent bathymetry / }}} where sponge layer coefficients have to be chosen according to the child grid mesh size. The sponge area is hard coded in NEMO and applies on the following grid points: 2 x refinement factor (from i=1+nbghostcells+1 to i=1+nbghostcells+sponge_area) == Available in the forthcoming 4.0 The 4.0 release is now available and includes new capabilities, configurations and test cases with AGRIF: === New capabilities from NEMO 3.6 to NEMO 4.0 AGRIF is continuously maintained so that it could be activated with all NEMO components (OPA, sea-ice, TOP). Depending on NEMO version, it is nevertheless not the case so that some options may not be compatible with the use of online grid refinement. Check out the table below to know the status according to the NEMO release you may use. * Status of available options with AGRIF (if not listed, option is compatible with AGRIF): ||= =||= NEMO 3.6 =||= NEMO 4.0 =|| || LIM2 || yes || - || || LIM3/SI3 || no || yes || || TOP || yes || yes || || GLS vertical mixing || no || yes || || z* || no || yes || || z~ || no || no || || Lagrangian icebergs || no || no || || East-west periodic and/or north fold bcs in zooms || no || no || || Online timing || no || no || || Stochastic parameterization || no || no || || Vertical coordinate change in zooms (key_vertical) || no || yes, but not tested || || Number of ghost cells || 1 (hard coded) || 3 (parameter) || * [[span(''Important notice concerning the change of ghost cells number:'', style=background-color:yellow)]] The default number of ghost cells (i.e. the number of cells that serve as open boundary data provision) has been increased from 1 to 3 in NEMO 4.0. This allows to properly handle boundary conditions for numerical schemes that have a discretization order greater than 2. On the user point of view this does not change anything++ except in the definition of level 1 grids in the `AGRIF_FixedGrids.in` file. In order to retrieve exactly the position of a nested grid in NEMO 4.0 one has to shift indices by 2 points to the south-west. Taking the `ICEDYN` example above for NEMO 4.0, the "old" NEMO 3.6 corresponding file would contain: {{{ 1 36 65 36 65 3 3 3 0 }}} ++ Child grid output files are now greater by 4 points in each direction. === New reference configuration with AGRIF: `AGRIF_DEMO` {{{#!table class='' {{{#!td [[Image(AGRIF_DEMO.jpg)]] }}} {{{#!td style='width: 3%' }}} {{{#!td style='width: 25%, text-align=left' `AGRIF_DEMO` is based on the [wiki:Users/ReferenceConfigurations/ORCA2_LIM3_PISCES ORCA2_LIM3_PISCES] global 2° configuration but it includes 3 online nested grids that demonstrate the overall capabilities of AGRIF in a realistic context, including nesting sea ice models. The configuration includes a 1:1 grid in the Pacific and two successively nested grids with odd and even refinement ratios over the Arctic ocean. The finest grid spanning the whole Svalbard archipelago is of particular interest to check that sea ice coupling is done properly. The 1:1 grid, used alone, is used as a benchmark to check that the solution is not corrupted by grid exchanges. Note that since grids interact only at the baroclinic time level, numerically exact results can not be achieved in the 1:1 case. One has to switch to a fully explicit in place of a split explicit free surface scheme in order to retrieve perfect reproducibility. }}} }}} Corresponding AGRIF_FixedGrids.in file is given by: {{{ 2 42 82 49 91 1 1 1 122 153 110 143 4 4 4 0 1 38 80 71 111 3 3 3 0 }}} === New tests cases demonstrating some major features of AGRIF with NEMO: * `tests/ICEDYN`: [[span(''Clement to add an illustration here ?'', style=background-color:lime)]] This is an East-west + north-south periodic channel. The configuration includes an AGRIF zoom (1:3) in the middle of the basin to test how an ice patch is advected through it but one can also test the advection schemes (Prather and Ultimate-Macho) by removing the key_agrif in the cpp keys. * `tests/VORTEX`: This test case illustrates the propagation of an anticyclonic eddy over a Beta plan and a flat bottom. It is implemented here with an online refined subdomain (1:3) out of which the vortex propagates. It serves as a benchmark for quantitative estimates of nesting errors as in Debreu et al. (2012), Penven et al. (2006) or Spall and Holland (1991). The animation below (sea level anomaly in meters) illustrates with two 1:2 successively nested grids how the vortex smoothly propagates out of the refined grids. [[Image(VORTEX_anim.gif,width=600,align=center)]] == References Debreu, L., P. Marchesiello, P. Penven and G. Cambon, 2012: Two-way nesting in split-explicit ocean models: Algorithms, implementation and validation. Ocean Modelling, 49-50, 1-21. [https://doi.org/10.1016/j.ocemod.2012.03.003] Penven, P., L. Debreu, P. Marchesiello and J. C. Mc Williams, 2006: Evaluation and application of the ROMS 1-way embedding procedure to the central california upwelling system. Ocean Modelling, 12, 157-187. [https://doi.org/10.1016/j.ocemod.2005.05.002] Spall, M. A. and W. R. Holland, 1991: A Nested Primitive Equation Model for Oceanic Applications. J. Phys. Ocean., 21, 205-220. [https://doi.org/10.1175/1520-0485(1991)021<0205:ANPEMF>2.0.CO;2]