# 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: 1. Grid building 2. Set landmask 3. Interpolate topography 4. Invert topography 5. Apply topography threshold --- ## Usage ```bash 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 ` | Root name for output files. Default: `symphonie`. | | `-n ` | Path to the notebook file. | | `-g ` | Path to the grid file. **Disables `-n`**. | | `-format ` | `fprintf` format for SYMPHONIE ASCII files. Default: `" %6.1f"`. | --- ### **Landmask Options** | Option | Description | |--------|-------------| | `-vmask ` | Landmask variable name. **Disables landmask processing**. | | `--no_mask` | Disable mask creation. **Disables landmask processing**. | | `-s ` | Path to a shorelines file. Default: `/home/data/shorelines/gshhs-2.2/gshhs_f.cst`. | | `-p ` | 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 ` | Force isobath polygon from smoothed shoreline. Default: `-0.4` meters. | | `-dx ` | Resolution for the smoothing grid in meters. Default: 1/8 of the original grid. | | `-f ` | Multiplicative factor for the smoothing length scale. Default: `1`. | | `--point ` | Reference coordinates for landmask building. Template: `"[;]"`. | | `--exclude ` | Path to an optional exclusion polygon file. | | `--checks` | Ensure landmask polygon is safe. | | `--keep-pools` | Keep created pools on landmask. | | `--increment ` | Increment for grid frontier. Default: `10`. | | `--show_map` | Save smoothed field as a NetCDF file. | --- ### **Topography Options** | Option | Description | |--------|-------------| | `-vtopo ` | Topography variable name. **Disables topography interpolation**. | | `-b ` | Path to a bathymetry file. Multiple bathymetry files are allowed, ordered by increasing priority. | | `-inv` | Disable altitude-to-depth conversion. | | `-zmin ` | 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 ` | Grid variable name at T point. | | `-variable_f ` | Grid variable name at F point. | --- ## Examples ### **Basic Grid Configuration** Process a notebook file with default settings: ```bash grid-config my_notebook.nc ``` --- ### **Custom Output Root Name** Set a custom root name for output files: ```bash grid-config -r my_output my_notebook.nc ``` --- ### **Use a Grid File Instead of Notebook** Process a grid file directly: ```bash grid-config -g my_grid.nc ``` --- ### **Disable Landmask Processing** Skip landmask processing and use an existing landmask variable: ```bash grid-config -g my_grid.nc -vmask landmask_var ``` --- ### **Custom Shorelines File** Use a custom shorelines file: ```bash grid-config -n my_notebook.nc -s /path/to/shorelines.cst ``` --- ### **Smooth Landmask Polygons** Smooth landmask polygons from a polygons file: ```bash grid-config -n my_notebook.nc -p polygons.plg --smooth ``` --- ### **Custom Isobath Contour** Force an isobath polygon at `-0.2` meters: ```bash grid-config -n my_notebook.nc --isocontour -0.2 ``` --- ### **Custom Smoothing Resolution** Set a custom resolution for the smoothing grid: ```bash grid-config -n my_notebook.nc -dx 1000 ``` --- ### **Exclude Specific Polygons** Exclude specific polygons from the landmask: ```bash grid-config -n my_notebook.nc --exclude exclusion.plg ``` --- ### **Use Averaging Interpolation** Use averaging interpolation for bathymetry: ```bash grid-config -n my_notebook.nc -average ``` --- ### **Multiple Bathymetry Files** Use multiple bathymetry files with priority ordering: ```bash grid-config -n my_notebook.nc -b bathy1.nc -b bathy2.nc ``` --- ### **Disable Altitude-to-Depth Conversion** Disable conversion of altitude to depth: ```bash grid-config -n my_notebook.nc -inv ``` --- ### **Set Minimum Topography Value** Constrain topography values above `-5000` meters: ```bash grid-config -n my_notebook.nc -zmin -5000 ``` --- ### **Reference Coordinates for Landmask** Set reference coordinates for landmask building: ```bash grid-config -n my_notebook.nc --point "[2.5;48.0]" ``` --- ### **Keep Pools on Landmask** Keep created pools on the landmask: ```bash grid-config -n my_notebook.nc --keep-pools ``` --- ### **Save Smoothed Field as NetCDF** Save the smoothed landmask field as a NetCDF file: ```bash 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 1. **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**. 2. **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. 3. **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. 4. **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). 5. **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`). 6. **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. --- ## See Also - [SYMPHONIE Model](https://www.symphonie-model.org/) - [GSHHS Shorelines Dataset](https://www.ngdc.noaa.gov/mgg/shorelines/gshhs.html) - [NetCDF Format](https://www.unidata.ucar.edu/software/netcdf/)