grid-config v3.2.3¶

Mercurial revision 5786:5c8b45563631 | 2026-08-04

Description¶

grid-config is a tool designed to set landmask and interpolate topography for a given grid. The processing order is as follows:

Grid building
Set landmask
Interpolate topography
Invert topography
Apply topography threshold

Usage¶

grid-config [OPTIONS] notebookFile

Options¶

General Options¶

Option	Description
`-h`, `--help`	Show help and exit.
`--debug`	Enable debug verbose mode.

Input/Output Options¶

Option	Description
`-r <rootname>`	Root name for output files. Default: `symphonie`.
`-n <file>`	Path to the notebook file.
`-g <file>`	Path to the grid file. Disables `-n`.
`-format <format>`	`fprintf` format for SYMPHONIE ASCII files. Default: `" %6.1f"`.

Landmask Options¶

Option	Description
`-vmask <var>`	Landmask variable name. Disables landmask processing.
`--no_mask`	Disable mask creation. Disables landmask processing.
`-s <file>`	Path to a shorelines file. Default: `/home/data/shorelines/gshhs-2.2/gshhs_f.cst`.
`-p <file>`	Path to a landmask polygons file. Disables `-s`. If not provided, polygons are computed from the shorelines dataset.
`--smooth`	Smooth landmask polygons provided with `-p`. If `-p` is not provided, this option is ignored. Produces polygons for isobaths `[0.2, 0.1, 0.0, -0.1, -0.2, -0.3, -0.4]` meters (`<0` for land, `>0` for ocean).
`--isocontour <depth>`	Force isobath polygon from smoothed shoreline. Default: `-0.4` meters.
`-dx <resolution>`	Resolution for the smoothing grid in meters. Default: 1/8 of the original grid.
`-f <factor>`	Multiplicative factor for the smoothing length scale. Default: `1`.
`--point <coordinates>`	Reference coordinates for landmask building. Template: `"[<lon>;<lat>]"`.
`--exclude <file>`	Path to an optional exclusion polygon file.
`--checks`	Ensure landmask polygon is safe.
`--keep-pools`	Keep created pools on landmask.
`--increment <value>`	Increment for grid frontier. Default: `10`.
`--show_map`	Save smoothed field as a NetCDF file.

Topography Options¶

Option	Description
`-vtopo <var>`	Topography variable name. Disables topography interpolation.
`-b <file>`	Path to a bathymetry file. Multiple bathymetry files are allowed, ordered by increasing priority.
`-inv`	Disable altitude-to-depth conversion.
`-zmin <value>`	Topography values will be constrained above this minimum. Default: `-99999`.

Interpolation Options¶

Option	Description
`-average`	Use averaging interpolation for bathymetry.
`-pointwise`	Use pointwise interpolation for bathymetry. Default.
`-variable_t <var>`	Grid variable name at T point.
`-variable_f <var>`	Grid variable name at F point.

Examples¶

Basic Grid Configuration¶

Process a notebook file with default settings:

grid-config my_notebook.nc

Custom Output Root Name¶

Set a custom root name for output files:

grid-config -r my_output my_notebook.nc

Use a Grid File Instead of Notebook¶

Process a grid file directly:

grid-config -g my_grid.nc

Disable Landmask Processing¶

Skip landmask processing and use an existing landmask variable:

grid-config -g my_grid.nc -vmask landmask_var

Custom Shorelines File¶

Use a custom shorelines file:

grid-config -n my_notebook.nc -s /path/to/shorelines.cst

Smooth Landmask Polygons¶

Smooth landmask polygons from a polygons file:

grid-config -n my_notebook.nc -p polygons.plg --smooth

Custom Isobath Contour¶

Force an isobath polygon at -0.2 meters:

grid-config -n my_notebook.nc --isocontour -0.2

Custom Smoothing Resolution¶

Set a custom resolution for the smoothing grid:

grid-config -n my_notebook.nc -dx 1000

Exclude Specific Polygons¶

Exclude specific polygons from the landmask:

grid-config -n my_notebook.nc --exclude exclusion.plg

Use Averaging Interpolation¶

Use averaging interpolation for bathymetry:

grid-config -n my_notebook.nc -average

Multiple Bathymetry Files¶

Use multiple bathymetry files with priority ordering:

grid-config -n my_notebook.nc -b bathy1.nc -b bathy2.nc

Disable Altitude-to-Depth Conversion¶

Disable conversion of altitude to depth:

grid-config -n my_notebook.nc -inv

Set Minimum Topography Value¶

Constrain topography values above -5000 meters:

grid-config -n my_notebook.nc -zmin -5000

Reference Coordinates for Landmask¶

Set reference coordinates for landmask building:

grid-config -n my_notebook.nc --point "[2.5;48.0]"

Keep Pools on Landmask¶

Keep created pools on the landmask:

grid-config -n my_notebook.nc --keep-pools

Save Smoothed Field as NetCDF¶

Save the smoothed landmask field as a NetCDF file:

grid-config -n my_notebook.nc --show_map

Environment Variables¶

grid-config does not rely on specific environment variables. However, ensure that:

Input files (notebook, grid, shorelines, bathymetry) are accessible.
Output directories are writable.

Notes¶

Input Files:
- The notebook file (-n) or grid file (-g) is required.
- If -g is provided, -n is disabled.
- If -vmask or --no_mask is provided, landmask processing is disabled.
- If -vtopo is provided, topography interpolation is disabled.
Landmask Processing:
- If -p (polygons file) is not provided, polygons are computed from the shorelines dataset (-s).
- The --smooth option only applies if -p is provided.
- The --isocontour option forces a specific isobath polygon from the smoothed shoreline.
Bathymetry Interpolation:
- Multiple bathymetry files (-b) can be provided. They are processed in reverse order of priority (last file has highest priority).
- Use -average or -pointwise to switch between interpolation methods.
Topography Constraints:
- The -zmin option ensures topography values do not fall below the specified minimum.
- The -inv option disables altitude-to-depth conversion (useful if input data is already in depth units).
Output Files:
- Output files are named using the -r root name (default: symphonie).
- Files generated include:
  - NetCDF files for spherical and mercator coordinates (e.g., symphonie.chk.spherical.nc, symphonie.chk.mercator.nc).
  - ASCII files for topography and mask (e.g., symphonie.chk.topo.asc, symphonie.chk.mask.asc).
  - SYMPHONIE ASCII file (e.g., symphonie.bathycote_in.dat).
Grid Types:
- The tool supports both T-grid and F-grid configurations.
- Use -variable_t and -variable_f to specify grid variables at T and F points, respectively.