# mesh-topo v3.2.3

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


---

## Description
Interpolates bathymetry and its gradient onto a given finite element (FE) mesh. This tool is designed for ocean modeling applications, allowing for the integration of bathymetric data into unstructured grids.

---

## Usage
```bash
mesh-topo [OPTIONS] -m <mesh_file> -b <bathymetry_file> -p <paire>
```

---
## Options

| Option | Description |
|--------|-------------|
| `-h,--help` | Print this help message. |
| `-m <mesh_file>` | Input mesh file (`.nei` format). Use `mesh-format` to convert from other formats (e.g., GMSH). |
| `-b <bathymetry_file>` | Bathymetry file (netCDF or `.grd` format). |
| `-v <variable>` | Variable name in the bathymetry file (e.g., `z`, `bathymetry`). If not specified, the tool attempts common names. |
| `-o <output_file>` | Output file name (optional). If not specified, files are auto-generated. |
| `-p <paire>` | Computational element pair. **Required**. Valid options: `LGP0xLGP1`, `DGP1xLGP2`, `DNP1xLGP2`, `Q1xQ0`, `CQP1xCQP0`. Determines how topography and its gradient are computed and saved. |
| `--rootname <name>` | Root name for output files (e.g., `output-topo-LGP1-0.s2r`). |
| `--smoothed <iterations>` | Number of smoothing iterations to apply to the bathymetry (default: 0). |
| `--change-sign=<yes\|no>` | Change the sign of bathymetry values (default: `yes`). Models typically expect positive depths. |
| `-missing <value>` | Missing value threshold (default: `99999.9`). |
| `-nomask` | Replace masked values in the bathymetry file with zero. |
| `-debug` | Enable debug mode for verbose output. |
| `-z <zone>` | **Deprecated**: Zone identifier (optional). |
| `-d <discretisation>` | **Deprecated**: Discretisation type. Use `-p` instead. |

---
## Examples

### Basic Usage
Interpolate bathymetry onto a mesh using the `LGP0xLGP1` pair:
```bash
mesh-topo -m mesh.nei -b bathymetry.nc -p LGP0xLGP1
```

### Smoothing Bathymetry
Apply 5 smoothing iterations to the bathymetry:
```bash
mesh-topo -m mesh.nei -b bathymetry.nc -p LGP0xLGP1 --smoothed 5
```

### Custom Output Root Name
Specify a root name for output files:
```bash
mesh-topo -m mesh.nei -b bathymetry.nc -p LGP0xLGP1 --rootname my_output
```

### Disable Sign Change
Disable the automatic sign change for bathymetry values:
```bash
mesh-topo -m mesh.nei -b bathymetry.nc -p LGP0xLGP1 --change-sign=no
```

### Multiple Bathymetry Files
Use multiple bathymetry files (prioritized in order):
```bash
mesh-topo -m mesh.nei -b bathymetry1.nc -b bathymetry2.grd -p LGP0xLGP1
```

---
## Environment Variables
None.

---
## Notes
- **Sign Convention**: By default, `mesh-topo` converts negative depths (common in databases) to positive depths (expected by most ocean models). Use `--change-sign=no` to disable this.
- **Masked Values**: Masked values in the bathymetry file are replaced with the `--missing` threshold. Use `-nomask` to replace them with zero.
- **Discretisation Pairs**: The `-p` option determines the computational pair for topography and its gradient. For example:
  - `LGP0xLGP1`: Topography on elevation nodes, gradient on velocity nodes.
  - `DGP1xLGP2`: Higher-order discretisation for complex geometries.
- **Output Files**: If `-o` is not specified, output files are auto-generated with names like `topo-{discretisation}-0.s2r` (raw interpolation) or `topo-{discretisation}-1.s2r` (optimal estimate).

---
## See Also
- [T-UGOm Tools Documentation](https://sirocco.omp.eu)
- [NetCDF Format](https://www.unidata.ucar.edu/software/netcdf/)
- [GMSH Mesh Format](http://gmsh.info/)
```