2.4. Build the grid#
The first step in creating a configuration is to build the grid for the region of interest. Subsequent steps, such as defining initial and boundary conditions, depend on the grid and use the CROCO grid file.
To create your grid, you can use:
make_grid.py: script for batch execution without any user interactionnb_make_grid.ipynb: notebook version that allows user interaction: visualizing the grid, eventually manually editing the bathymetry and mask
Both perform the same following steps:
Define the grid position, and compute longitude and latitude
Interpolate the bathymetry onto CROCO grid
Build the land-sea mask
Smooth the bathymetry based on chosen criteria
The notebook version allows additional features:
Visualizing the grid position, bathymetry, and mask
Manually edit the land-sea mask and the bathymetry to modify artifacts, sharp transitions, etc.
Tip
Using the notebook, you can also manually edit the land-sea mask and the bathymetry from an existing CROCO grid file and update the smoothing.
In the following you will be guided to use these scripts to create your grid.
2.4.1. Environment#
Warning
First be sure that you have installed the required Python environment
and activate it (e.g. micromamba activate croco_pyenv).
2.4.2. User-defined parameters#
All the requested user-defined parameters to build the grid are gathered in a
configuration file, here named grid.ini.
This file contains:
[Croco_Files]
croco_files_dir = ../results/CROCO_FILES
croco_grd_prefix = croco_grd
[Zoom_Options]
is_zoom = False
is_agrif = False
agrif_level = 0
[Grid_Position]
central_lon = 15.0
central_lat = -32.0
size_x_km = 1556
size_y_km = 1334
npoints_x = 41
npoints_y = 42
grid_angle = 0.0
[Grid_Smoothing_Params]
hmin = 50.0
hmax = 6000.0
interp_rad = 2
rfact = 0.2
smooth_meth = lsmooth
[Grid_Isolated_Waterbodies]
mask_isolated_waterbodies = False
main_water_body_x_idx = 20
main_water_body_y_idx = 20
[Grid_Input_Files]
topo_file_reader = etopo2
topo_file = ../data/DATASETS_CROCOTOOLS/Topo/etopo2.nc
shp_file = ../data/DATASETS_CROCOTOOLS/gshhs/GSHHS_shp/i/GSHHS_i_L1.shp
The [Croco_Files] section defines the path and prefix for CROCO files:
|
Path of the CROCO files directory |
|
Prefix for the CROCO grid file that will be created.
For a usual grid, the output file will be |
The [Zoom_Options] section defines if the grid is the main grid (parent grid) or a nested grid (zoom or child grid):
|
True/False flag to define if the grid is a zoom or the main grid |
|
True/False flag to define if the grid is an agrif nested grid |
|
integer level of the agrif grid to consider (0 is parent, 1 is first child) |
For starting building the main/parent grid, put False to both these fields,
and 0 to agrif_level.
The [Grid_Position] section defines parameters to position the grid. It is used for the parent grid or for offline zooms (not for Agrif zooms, for which the grid is placed relatively to the parent).
|
Central longitude of the grid |
|
Central latitude of the grid |
|
Size of the domain along x in km |
|
Size of the domain along y in km |
|
Number of points along x |
|
Number of points along y |
|
Rotation angle of the grid (trigonometric convention) |
The grid will be created as a rectangular, orthogonal grid with minimal gridsize
variation.
It uses a Mercator projection around the equator and then rotates the sphere
around its three axes to position the grid wherever it is located.
The grid resolution is given by dividing the domain size by the number of point
in each direction (size_x_km/npoints_x, in km).
The [Grid_Smoothing_Params] section defines the bathymetry smoothing parameters:
|
Minimum depth [m] allowed for each cell. It should be adapted
depending on the chosen resolution
(e.g., |
|
Maximum depth [m]. Limits bathymetry to prevent extrapolation below available input levels. |
|
Interpolation radius (in grid points) for the CROCO grid. Typically between 2 and 8. | |
|
Maximum slope parameter, |
|
Smoothing method to use. Options: |
Since CROCO is a sigma-coordinate model, it is sensitive to pressure gradient errors. Although these are accounted for and reduced by the numerical methods used in the model, it is however necessary to smooth the bathymetry so that the slope is everywhere less than a defined r-factor. The default value for r-factor is set to 0.2 but can be changed by the user. The lower the value, the smoother the topography. Before smoothing, routine uses hmin and hmax to bound topography before smoothing. Topography values lower than hmin, repectively higher than hmax, will be set to hmin, repectively hmax. Then smoothing is performed. Several smoothing methods exists in CROCO, which can be divided into two categories:
rx-condition: smoothes the raw topography until the slope criterion is met
log-smooth: transforms the topography into its logaritm and smoothes it
Here is a brief description of the various available smoothing method:
|
mask-dependent r-factor based on rx-condition, using Neumann boundary condition at the coastline |
|
mask-dependent r-factor based on log_smooth condition |
|
same as lsmooth, but instead of explicitly computing diagonal fluxes apply cross-averaging to 90-degree fluxes |
|
same as lsmooth, but without diagonal fluxes |
|
same as lsmooth but mask independant |
|
it compares pair-wise adjacent points in either X or Y direction and if r-factor exceeds the prescribed maximum, the shallower depth between the two points is increased so that r-factor remains within the limit. Because of inter-dependency among the points the process is repeated iteratively. |
Note
To avoid errors close to the coastline, it is better to choose data with continuity on land.
The bathymetry is then interpolated on the CROCO grid using weighted averaging. Weights are computed with a Hann window and more precisely with its polynomial fit (less costly). When input data is coarser than CROCO grid and no data is found in the radius window, a bi-linear interpolation is performed with the four closest points.
Mask creation is handled by the python library regionmask and can handle any shapefile to define it. CROCO can manage wetting and drying process in coastal areas, in this case the land/sea boundary in CROCO should be extended further than the usual coastline. In that case, the coastline data will be ignored, and the topography data will be used instead. The minimum depth, hmin, thus needs to be set to a value lower than zero. The mask will be drawn at hmin altitude.
The [Grid_Isolated_Waterbodies] section defines parameters used for eventually masking isolated water bodies:
|
True/False flag to activate/deactivate functionality |
|
Index of the starting point (in the main water body) in x-direction |
|
Index of the starting point (in the main water body) in y-direction |
In some cases, mask generation can leave water bodies inside the land (lakes for example) which are not connected to the main water body. If not wanted, the isolated water bodies can be masked using the mask_isolated_waterbodies functionnality. It takes a user-specified initial point, which is assumed to be in the main water body and, starting from this point, considers the adjacent non-masked points as “water”. Extending further, non-masked point are also marked as “water” if at least one its neighbouring points is already marked as “water”. At the end, remaining non-connected water bodies, not marked as “water”, because not connected to the main water body, are masked.
The [Grid_Input_Files] section defines paths of input files:
|
Keyword for the data reader to use in |
|
Path/name of the source bathymetry file |
|
Path/name of the source coastline file |
To build a CROCO grid two input data are necessary:
bathymetry data (netcdf), examples available in DATASETS_CROCOTOOLS/Topo, but any other data can be used by adding a keyword and associated dictionnary in
reader.jsonccoastline data (shapefile), example available in DATASETS_CROCOTOOLS/gshhs, used to build the mask if hmin is positive (if hmin is negative, hmin value will be used instead).
2.4.3. Build the grid with make_grid.py#
Edit the
grid.iniconfiguration file.Launch the script:
./make_grid.py grid.ini
Note
Created your croco_files_dir directory before executing the script.
2.4.4. Build the grid with nb_make_grid.ipynb#
Run the cell for importing dependencies:
%matplotlib widget %load_ext autoreload %autoreload 2 # Import custom modules from Modules.croco_class import CROCO
Run the cell to read and edit the [Croco_Files] section defines directory and path of CROCO files
# Read the config file and create a CROCO instance croco = CROCO("grid.ini") # Edit the appropriate section in the config file croco.edit_section_widget("Croco_Files")
Edit the path for CROCO directory and filname for CROCO grid.
Click the Save changes button to save your new settings in the
configuration local dictionnary.
Run the cell to read and edit the [Grid_Input_Files] section defines directories and path of inputs and outputs files
# Edit the appropriate section in the config file croco.edit_section_widget("Grid_Input_Files")
Edit the paths to your topographic/bathymetric data, coastline shapefile, and output path for CROCO grid.
Click the Save changes button to save your new settings in the
configuration local dictionnary.
Run the cell to edit the [Grid_Position] section defining parameters to postion the grid:
# Edit the appropriate section in the config file croco.edit_section_widget("Grid_Position")
Edit the grid settings.
Click the Save changes button to save your new settings in the
configuration local dictionnary.
Run the cell to create the grid:
# Create lon/lat grid croco.create_grid()
Run the cell to display the grid position on a map:
# Display the grid croco.plot_grid_outline()
If you are happy with the grid position, continue, otherwise change the grid parameters and run the last 2 cells again.
Run the cell to edit the [Grid_Smoothing_params] section defining the bathymetry smoothing parameters:
# Edit the appropriate section in the config file croco.edit_section_widget("Grid_Smoothing_params")
Edit the smoothing parameters settings.
Click the Save changes button to save your new settings in the
configuration local dictionnary.
Run the cell to edit the [Grid_Isolated_Waterbodies] section defining parameters used for eventually masking isolated water bodies:
# Edit the appropriate section in the config file croco.edit_section_widget("Grid_Isolated_Waterbodies")
Edit the parameters for masking isolated water bodies settings.
Click the Save changes button to save your new settings in the
configuration local dictionnary.
Run the cell to interpolate the bathymetry, create the mask, and smooth the bathymetry:
# Interpolate bathymetry, create mask and smooth bathymetry croco.create_mask_and_topo()
The smoothing coefficients are printed as output so you can check if the criteria.
Run the cell to display the bathymetry and mask on a map:
# Display the bathymetry and mask croco.plot_h()
If you are happy with the bathymetry and mask, continue to save cell, otherwise change the smoothing parameters or Grid_Isolated_Waterbodies parameters and run the last cell again.
If you further want to manually edit some bathymetry or mask points, go to the next section of the notebook “Edit mask and bathymetry”.
Run the cell to save your grid in a netcdf file, and save your settings for building the grid in a new configuration file:
Warning
You need to have clicked the Save changes buttons on each section to
actually update the dictionnary and save it properly!
# Save CROCO grid in a netcdf file define as croco_grd
croco.save_grid_nc()
# Save your CROCO grid settings for later use
croco.save_config("grid_new.ini")
Note
Created your croco_files_dir directory before executing the script.
2.4.5. Mask and bathymetry manual edition#
You may want to manually edit the mask or bathymetry of your CROCO grid (e.g. to remove unwanted artifacts, or too sharp transitions).
Interactive tools are provided in nb_make_grid.ipynb to do so: a point
by point editor, and a rectangle selector editor to change a larger area at once.
Run the cell to edit the bathymetry:
# Edit the bathymetry croco.map_editor("h")
You can then choose the Mode to point (point by point change) or
rectangle (rectangle area change at once).
Clike on a point or select a rectangle on the map to edit.
Choose the new value in New value, and click Update to update
it on the map.
You can Undo your change, or Save it into a dedicated file which
path/name has to be given in Save path.
Tip
Note that you can zoom-in/zoom-out on the map with the usual left plot tools to more precisely edit a given area. When using the side-plot tools, dot not forget to click once again on it (e.g. zoom tool) before being able to use point or rectangle selector.
You can similarly edit the mask with the cell:
# Edit the mask croco.map_editor("maskr")
After editing the mask and/or bathymetry, apply the final bathymetry smoothing (note: smoothing is mask-dependent) by running:
# Smooth the bathymetry after bathy/mask edition croco.smooth_after_mask_edit()
Display the final smoothed bathymetry and mask with the cell:
# Display the new bathymetry and mask croco.plot_h()
Eventually edit the CROCO grid file name:
# Edit the appropriate section in the config file croco.edit_section_widget("Files")
Click the Save changes button to save your new settings in the
configuration local dictionnary.
Finally save your new CROCO grid file:
# Save CROCO grid in a netcdf file define as croco_grd croco.save_grid_nc() # Save your CROCO grid settings for later use croco.save_config("grid_new.ini")
2.4.6. Build a nested grid#
To build a nested grid you will have to define in [Zoom_Options] section the variable zoom to True, as well as fill additionnal sections: [Grid_Zoom_Params], [Grid_Zoom_Agrif].
To do so, follow the “Build a nest” tutorial.