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#

You can find an example of configuration file in Example/benguela_multifiles/grid_zoom_agrif.ini. This file contains several sections.

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 zooms, the boundary conditions are directly manage by Agrif, only the initial condition have to be computed from a Z-coordinate OGCM like the parent grid (see Build initial and boundary conditions).

You can use make_ini.py after editing the ibc.ini or ibc_zoom_agrif.ini file to set [Zoom_Options] for your nest.

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#

You can find an example of configuration file in Example/benguela_multifiles/grid_zoom_offline.ini. This file contains several sections.

To build an OFFLINE 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 using a S-coordinate to S-coordinate transformation perform by Fortran subroutines that interpolate from your parent croco grid to the croco zoom grid. You can use make_ini.py and make_bry.py and the needed parameters are fewer than in the case of Z-coordinate to S-Coordinate transformation. Each section of parameters needed for zoom offline case is described here:

The [Croco_Files] section in zoom offline case :

croco_files_dir

Path of the CROCO files directory

croco_grd_prefix

Prefix for the CROCO grid file

croco_ini_prefix

Prefix used for the CROCO initial file, usually = croco_ini

croco_bry_prefix

Prefix used for CROCO boundary files, usually = croco_bry

The [Zoom_Options] section in zoom offline case:

is_zoom

True for a zoom offline

is_agrif

False for a zoom offline

parent_grid

Path of the CROCO parent grid file

The [Times] section, start and end date are not needed in zoom offline case, the initial date is found using ini_idx parameters in IBC_Input_Files section:

Yorig, Morig, Dorig, Horig

year, month, day, hour of the time origin date

The origin date defines the time at which data are referenced in CROCO files (e.g. days since XXXX:XX:XX). It must be consistent between boundary and surface forcing conditions if you are not using USE_CALENDAR precompilation key in CROCO.

The [Sigma_Params] section defines the stretching parameters for the sigma coordinate, it is the same for all cases (zoom offline or not):

theta_s

Vertical sigma-coordinate surface stretching parameter

theta_b

Vertical sigma-coordinate bottom stretching parameter

N

Number of vertical sigma levels

hc

Vertical sigma-coordinate critical depth parameter, giving approximately the transition depth between the horizontal surface levels and the bottom terrain following levels.

The [IBC_Options] section in zoom offline case:

obc_dict

define boundary status: opened or closed (1=open , [S W E N])

tracers

list of tracers to consider. Names defined here must also be defined in your reader

The [IBC_Input_Files] section in zoom offline case:

ibc_dir

path of input data

ibc_prefix

prefix of input data filenames (expected filename form is prefix_Y????M??ibc_extension, example croco_his_Y2013M01.nc)

ibc_extension

extension (e.g. .nc or .cdf) of input data filenames (expected filename form is prefix_Y????M??ibc_extension, example croco_his_Y2013M01.nc)

ini_filedate

date in the filename of the initial file to read

ini_idx

time index to read in the input file used for initial conditions

For boundary conditions, all available files in ibc_dir will be used.

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

After editing the configuration 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