Changes between Version 12 and Version 13 of Users/Model Interfacing/AGRIF


Ignore:
Timestamp:
2018-08-31T12:20:34+02:00 (2 years ago)
Author:
nicolasmartin
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • Users/Model Interfacing/AGRIF

    v12 v13  
    66 
    77[[span(Page in progress, style=background-color:lime)]] 
    8  
    98 
    109 
     
    1413This pages provides guidelines how to use AGRIF in NEMO. For a more technical description of the library itself, please refer to the following page: [http://agrif.imag.fr]. 
    1514 
     15 
    1616== Compilation 
     17 
    1718Activating AGRIF requires to append the cpp key "key_agrif" at compilation time:  
    18 {{{ 
    19 ./makenemo add_key "key_agrif" 
    20 }}} 
    21 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.  
     19 
     20{{{#!sh 
     21./makenemo add_key 'key_agrif' 
     22}}} 
     23 
     24Although 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. 
    2225 
    2326 
    2427== Definition of the grid hierarchy 
     28 
    2529An 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 VORTEX test case, is given below:  
     30 
    2631{{{ 
    27321 
     
    29340 
    3035}}} 
     36 
    3137The first line indicates the number of zooms (1). The second line contains the starting and ending indices in both directions on the root grid (19 38 19 38) 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 cfgs/AGRIF_DEMO/EXPREF reference configuration directory (NEMO 4.0 only).  
    3238 
     
    3541Note 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.  
    3642 
     43 
    3744== Preprocessing 
     45 
    3846Knowing the refinement factors and area, a pre-processing tool (utils/tools/NESTING directory) 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 utils/tools/NESTING directory as a guide. These correspond to the namelists used to create AGRIF_DEMO inputs.  
    3947 
     48 
    4049== Namelist options 
     50 
    4151Each child 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: 
     52 
    4253{{{ 
    4354!----------------------------------------------------------------------- 
     
    5061/ 
    5162}}} 
     63 
    5264where sponge layer coefficients have to be chosen according to the child grid mesh size. 
    5365 
     66 
    5467== Available in the forthcoming 4.0 
     68 
    5569The [wiki:Users/Announcement_4.0.beta_release 4.0 beta release is now available] and includes new capabilities, configurations and test cases with AGRIF: 
    5670 
    57 === New capabilities from NEMO 3.6 to NEMO 4.0  
     71 
     72=== New capabilities from NEMO 3.6 to NEMO 4.0 
     73 
    5874AGRIF 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. 
    5975 
     
    196212 * [[span(''Important notice concerning the change of ghost cells number:'', style=background-color:yellow)]] 
    197213The 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 VORTEX example above for NEMO 4.0, the "old" NEMO 3.6 corresponding file would contain: 
     214 
    198215{{{ 
    1992161 
     
    2012180 
    202219}}} 
     220 
    203221++ Of course, output files are now greater by 4 points in each direction. 
     222 
     223 
    204224=== New reference configuration with AGRIF: AGRIF_DEMO  
    205225 
    206 AGRIF_DEMO is based on the [wiki:Users/ReferenceConfigurations/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.    
    207   {{{#!td style="border: none;" 
    208     [[Image(wiki:Users/ModelInterfacing/AGRIF:AGRIF_DEMO.jpg,width=600)]] 
    209   }}} 
     226AGRIF_DEMO is based on the [wiki:Users/ReferenceConfigurations/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. 
     227 
     228   {{{#!td style="border: none;" 
     229   [[Image(wiki:Users/ModelInterfacing/AGRIF:AGRIF_DEMO.jpg,width=600)]] 
     230   }}} 
    210231 
    211232Corresponding AGRIF_FixedGrids.in file is given by: 
     233 
    212234{{{ 
    2132352 
     
    220242}}} 
    221243 
     244 
    222245=== New tests cases demonstrating some major features of AGRIF with NEMO: 
     246 
    223247 * tests/ICEDYN:  
    224248 
     
    228252 
    229253 * tests/VORTEX: 
     254 
    230255This 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 successfully nested grids how the vortex smoothly propagates out of the refined grids.  
    231256  
    232   {{{#!td style="border: none;" 
    233     [[Image(wiki:Users/ModelInterfacing/AGRIF:VORTEX_anim.gif,width=600)]] 
    234   }}} 
     257   {{{#!td style="border: none;" 
     258   [[Image(wiki:Users/ModelInterfacing/AGRIF:VORTEX_anim.gif,width=600)]] 
     259   }}}