Build a nest

2.8. Build a nest#

To represent fine-scale phenomena, CROCO offers the ability to create zooms of increased resolution. Two options exist:

  • AGRIF zoom: AGRIF is a library that allows to run CROCO with several embedded domains together. (see documentation in CROCO documentation) Parent and child(s) domain are run simultaneously, coupling the domains at the barotropic time step.

    • advantages: 2-way feedback to the parent domain is possible and can significantly improve results of the larger domain, coupling at the highest possible frequency, consistency of numerics, any number of nesting levels is allowed.

    • drawbacks: requires to run the parent and child(s) grids simultaneously, nesting ratio should be 3 or 5, in the current state, the AGRIF zooms in CROCO must have the same vertical resolution as the parent.

  • offline zoom: Creating a grid of the desired resolution, which boundaries are inside a grid from a larger CROCO domain, already modelled. In such case, the higher-resolution grid takes as initialization and boundary conditions, those from the larger CROCO simulation. The simulations are independent and no feedback from the higer-resolution grid towards the coarser grid is possible. The simulations run separately.

    • advantages: independency, no constraints on the chosen resolution,

    • drawbacks: no feedback to the larger domain, boundary forcing of the zoom depends on the frequency of the parent grid’s history, which may filter out some of the waves present in the parent grid.

2.8.1. AGRIF zoom#

2.8.1.1. Child grid#

  • Edit the grid_zoom_agrif.ini configuration file.

First check the [Croco_Files] section:

croco_files_dir

Path of the CROCO files directory

croco_grd_prefix

Prefix for the CROCO grid file that will be created

To build an AGRIF nested grid you will have to define in [Zoom_Options] section:

is_zoom = True
is_agrif = True
agrif_level = 1
parent_grid = ../results/CROCO_FILES/croco_grd.nc

parent_grid

Path/name of the CROCO parent grid file

Then you will have to fill the [Grid_Zoom_Params] section:

north_obc

True/False: define North boundary status: opened or closed

south_obc

True/False: define South boundary status: opened or closed

west_obc

True/False: define West boundary status: opened or closed

east_obc

True/False: define East boundary status: opened or closed

merging_area

number of child-grid points representing the bathymetry merging zone with that of the parent grid

Note

To create your nested grid file your parent grid file must exists.

Open boundaries and merging_area help to modifies child grid bottom topography in the vicinity of forced open boundaries to exactly match topography interpolated from the parent grid right at the boundary, while at the same time, making smooth transition into the interior of child grid domain where the topography is expected to be less smoothed as the resolution is higher. This topographic match is essential for flux conservation.

Then fill the [Grid_Zoom_Agrif] section to place your AGRIF zoom within the parent grid:

coef

refinement coefficient between the parent and the child grid. It should be 3 or 5

imin

starting index of the parent grid in x-direction

imax

ending index of the parent grid in x-direction

jmin

starting index of the parent grid in y-direction

jmax

ending index of the parent grid in y-direction

Note

AGRIF requires a perfect match of the psi points at boundaries. The procedure to build the AGRIF grid may thus slightly change the grid location or number of points to match this criterion.

Fill the [Grid_Smoothing_Params] section:

hmin

Minimum depth [m] used at the shore. Depends on resolution (e.g., dx=100km → hmin=300, dx=25km → hmin=150). Affects smoothing, which works on grad(h)/h.

hmax

Maximum depth [m]. Limits bathymetry to prevent extrapolation below available input levels.

rfact

Maximum slope parameter, r-fact = grad(h)/h, used during smoothing. Lower values yield smoother results.

smooth_meth

Smoothing method to use. Options: 'smooth', 'lsmooth', 'lsmooth_legacy', 'lsmooth2', 'lsmooth1', 'cond_rx0_topo'. See online “Build the grid” documentation for more details.

Fill the [Grid_Isolated_Waterbodies] to eventually mask isolated water bodies:

mask_isolated_waterbodies

True/False flag to activate/deactivate functionality

main_water_body_x_idx

Index of the starting point (in the main water body) in x-direction

main_water_body_y_idx

Index of the starting point (in the main water body) in y-direction

Fill the [Grid_Input_Files] section:

topo_file

Path/name of the source bathymetry file you want to use

topo_file_reader

keyword for the data reader to use in readers.jsonc file for dimension name correspondance

shp_file

Path/name of the source coastline file you want to use

  • Launch the script:

    ./make_grid.py grid_zoom_agrif.ini

  • When saving the grid, two files are created:

    • the child grid file: croco_grd.nc.1

    • a file named AGRIF_FixedGrids.in. This file contains information on the zoom position and refinment. This file is needed by CROCO to run with AGRIF.

Warning

In the current state, the generation of AGRIF_FixedGrids.in works well when having only one AGRIF zoom, but not with several successive zooms. You may have to edit it “by hand”.

Note

You can also use the nb_make_grid_zoom.ipynb to locate and build your child grid. It allows you to vizualise the grid position, and eventually edit the mask and bathymetry.

2.8.1.2. Child IBC#

For AGRIF zoom, only the initial file has to be created. You can use make_ini.py after editing the ibc.ini or ibc_zoom_agrif.ini file to set [Zoom_Options] for your nest.

Only the initial conditions have to be created, as the boundary conditions are provided online by the parent domain.

Note

For AGRIF zoom, [Sigma_Params] need to be the same than parent ini/bry files.

After editing the ibc.ini or ibc_zoom_agrif.ini file, launch the initial conditions creation:

python make_ini.py ibc_zoom_agrif.ini

It will create files, named as:

croco_ini_{ibc_prefix}_Y????M??.nc.1

2.8.2. Offline zoom#

2.8.2.1. Child grid#

  • Edit the grid_zoom_offline.ini configuration file.

To build an AGRIF nested grid you will have to define in [Zoom_Options] section:

is_zoom = True
is_agrif = False

Then you will have to fill the [Grid_Zoom_Params] section:

north_obc

True/False: define North boundary status: opened or closed

south_obc

True/False: define South boundary status: opened or closed

west_obc

True/False: define West boundary status: opened or closed

east_obc

True/False: define East boundary status: opened or closed

merging_area

number of child-grid points representing the bathymetry merging zone with that of the parent grid

parent_grid

Path/name of the CROCO parent grid file

Note

To create your nested grid file your parent grid file must exists.

Open boundaries and merging_area help to modifies child grid bottom topography in the vicinity of forced open boundaries to exactly match topography interpolated from the parent grid right at the boundary, while at the same time, making smooth transition into the interior of child grid domain where the topography is expected to be less smoothed as the resolution is higher. This topographic match is essential for flux conservation.

Then fill the [Grid_Position] to determine the grid location, and fill the other sections ([Croco_Files], [Grid_Input_Files], [Grid_Smoothing_Params], [Grid_Isolated_Waterbodies]) as you would do to build your main grid.

  • Launch the script:

    ./make_grid.py grid_zoom_offline.ini

  • Check your grid file:

    croco_grd_zoom_offline.nc

Note

You can also use the nb_make_grid_zoom.ipynb to locate and build your child grid. It allows you to vizualise the grid position, and eventually edit the mask and bathymetry.

2.8.2.2. Child IBC#

For offline zooms, initial and boundary conditions have to be created.

You can use make_ini.py and make_bry.py after editing the configuration file (e.g. ibc_zoom_offline.ini.

In the case of offline zoom, the scripts call Fortran subroutines that interpolate from your parent croco grid to the croco zoom grid.

You should provide path and prefix of your croco parent outputs (ibc_prefix = croco_his, ibc_dir = ../results/SCRATCH/)

For initial condition, you need to provide the ini_filedate and ini_idx to use in this file.

For boundary conditions, all available files will be used.

As the scripts use Fortran subroutines, they are generally fast.

After editing the ibc_zoom_offline.ini or ibc_zoom_agrif.ini file, launch the initial conditions creation:

python make_ini.py ibc_zoom_offline.ini
python make_bry.py ibc_zoom_offline.ini

It will create files, named as:

croco_ini_zoom_offline_Y????M??.nc
croco_bry_zoom_offline_Y????M??.nc
Contents