Skip to content

High-Resolution Nested Grid

In this page you will learn more about the grid structure used by the SHYFEM-MPI model and how SURF automatically generates it based on your configuration.

The Grid Structure

Arrangement of Variables

The SHYFEM-MPI model uses the Arakawa B-grid for spatial discretization. In this staggered grid system:

  • Horizontal Velocity components — zonal (U) and meridional (V) velocities — are defined at the centroids of triangular grid elements.
  • All other quantities, including vertical velocity (W) and scalars such as temperature (T), salinity (S), and sea surface height (η), are defined at the vertices of the triangles.

Horizontal and vertical grids used by SHYFEM-MPI ocean model. The horizontal and vertical grids used by the SHYFEM-MPI ocean model (image credits: Micaletto et al. (2022)).

Horizontal Grid

The horizontal grid consist of triangles varying in form and size for the discretization of the nested domain, in the framework of Finite Element Methods. Each vertex is associated to the surrounding elements.

For more information on the parametrization of the horizontal grid, see the 2D Grid Generation section.

Vertical Grid

SHYFEM-MPI uses fixed-depth \(z\)-layers for vertical discretization, with uniform horizontal depth but variable vertical thickness.

Variables are vertically staggered (see figure above): stresses and vertical velocity \(W\) are computed at layer interfaces, the free surface is positioned at the top of the uppermost layer (yielding variable top cell volumes), while transports and scalars are defined at layer centers.

For a detailed description of the model's vertical level representation, refer to Micaletto et al. (2022).

The configuration of the vertical level distribution is done via the levels parameter in the JSON configuration file section 🔗Nested Grid and Land-Sea Mask Settings. To know more about how to properly define these parameters, please refer to the Best Practices section.

Grid Generation Steps

The nested high-resolution grid is automatically generated by SURF based on the domain selection and horizontal and vertical resolution settings (see the configuration section 🔗Nested Grid and Land-Sea Mask Settings).

The grid generation process consists of the following main steps:

2D Grid Generation

The generation of the horizontal (2D) unstructured triangular mesh is based on the open-source finite element mesh generator Gmsh

Horizontal and vertical grids used by SHYFEM-MPI ocean model. Schematic representation of horizontal grid parameters.

As represented in the figure above, 5 parameters control the automatic grid generation process. They are:

  • Minimum grid element size (sizemin): Minimum triangle element size, used in the high-resolution zone near the coastline
  • Maximum grid element size (sizemax): Maximum triangle element size, applied in coarser-resolution zones farther from the coast and along open boundaries
  • Minimum distance threshold (distmin): Distance from the coast up to which the element size is constant and equal to sizemin
  • Maximum distance threshold (distmax): Distance from the coast beyond which the element size is constant and equal to sizemax

The region between distmin and distmax forms a transitional zone, where the element size linearly increases from sizemin to sizemax.

For useful tips on how to properly define these parameters, refer to the Configuration Best Practices section.

Grid Corner Smoothing

In order to enhance the accuracy and numerical stability of the simulation, SURF-SHYFEM automatically smooths out the corners of the horizontal grid by replacing sharp edges with Bézier curves.

Boundary Nodes Extraction

Next, the indices of open boundary nodes are automatically extracted and stored in the experiment directory under

1
preprocessing/meshing/mesh/2d/boundaryNodes.dat
This file will later be used to extract open boundary conditions.

Bathymetry Processing

In order to generate the 3D grid, the input bathymetry dataset must first undergo the following processing steps to ensure compatibility with the unstructured grid and the SHYFEM-MPI model:

  • Sea-Over-Land (SOL) Extrapolation : In the particular case of the bathymetry, the SOL procedure is performed to ensure consistency of the coastal boundary representations between the coastline and bathymetry input datasets.

  • Filtering : In general, the bathymetry dataset may contain small-scale noise that may potentially cause numerical instabilities in the simulation. To prevent this, SURF applies a Gaussian low-pass filter with a cut-off standard deviation for the Gaussian kernel (sigma) equal to one.

  • Interpolation to Unstructured Grid : The input bathymetry, originally defined on a structured grid, is subsequently interpolated onto the unstructured grid (at the centroids of grid elements).

3D Grid Generation

The final 3D grid is created by incorporating the processed bathymetry data. The final grid output is provided in both .grd and .bas formats and can be found in the experiment directory under 

1
preprocessing/meshing/mesh/output

Best Practices

Specifying the Domain Polygon

Click here to expand...

Properly defining your nested domain via the Domain polygon variable in the JSON configuration file section 🔗Nested Grid and Land-Sea Mask Settings can help preventing a number of mesh issues such as poor element quality and non-conformity.

Horizontal grid automatically generated for the civitavecchia domain. Horizontal grid automatically generated for the civitavecchia domain.

When defining your nested domain polygon(\(ABCD\) in the figure above), position the vertices so that the connecting edges intersect the coastline as perpendicularly as possible (\(AB \perp SL\) and \(CD \perp SL\)).

It is also advisable to position the open boundary edge opposite the coast to run as parallel as possible to the coastline (\(DA \parallel SL\)).

Open Boundary Positioning

Horizontal grid automatically generated for the civitavecchia domain.

Make sure that your nested domain polygon does not create multiple open boundaries by intersecting features such as islands or other land elements. Currently, SURF-SHYFEM supports only a single open boundary. Support for multiple open boundaries is under development. Stay tuned!

Specifying the Grid Element Size

Click here to expand...

When selecting the Minimum grid element size (sizemin), you should find a balance between an element size small enough to properly capture key coastline features (see e.g. figure above) and large enough to not unreasonably increase your simulation time.

Finding the best set of grid parameters for your nested domain at first glance can be challenging. Therefore, consider testing different settings by repeatedly executing only the Grid Generation task within the SURF Workflow, in order to find the best set of parameters for your use case. At each iteration, to assess the quality of the result, you may inspect the horizontal grid output under $SURF_SHYFEM_DIR/preprocessing/meshing/mesh/2d/grid_2d.png

Configuring the Vertical Levels

Click here to expand...

The levels variable in the JSON configuration file section 🔗Nested Grid and Land-Sea Mask Settings specifies the vertical levels for the model.

The vertical levels must be specified in increasing order. The vertical spacing between levels can be variable, but it is strongly recommended to use either a constant or monotically increasing spacing.

For instance, a correct distribution of vertical levels should look like this: 

"gui_name": "Vertical levels",
"name": "levels",
"required": true,
"value": [2, 4, 6, 8, 10, 15, 20, 25, 30, 35, 40, 50, 60, 70, 80, 100, 120, 140, 160],

SHYFEM-MPI also requires vertical levels to cover the full depth of the nested domain. If the defined levels are insufficient (e.g., basin depth exceeds 160m in the example above), SURF-SHYFEM automatically adds vertical levels as needed to ensure full coverage, simplifying setup and avoiding related errors.