# mgr2obc v3.2.3

**Mercurial revision 5770:c90c3015e72d | 2026-05-22**

---

## Description

`mgr2obc` builds **tidal boundary condition files** for a specific grid based on **tide gauge harmonics** (MGR files). This tool is useful for generating open boundary conditions (OBC) for numerical models, ensuring accurate tidal forcing at the boundaries of the computational domain.

---

## Usage

```bash
/home/softs/tools/debug/src/mgr2obc [OPTIONS] wave1 [wave2 ...]
```

---

## Options


| Option             | Description                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------- |
| `-h`, `--help`     | Show this help and exit.                                                                                      |
| `--quadrangle`     | Force the finite element (FE) grid to use **quadrangles** instead of triangles.                               |
| `--grid <options>` | String specifying **grid options** for structured grid generation.                                            |
| `--append`         | Append the new waves to an **existing OBC file**. Ensure the output file name is set using `-o`.              |
| `-dmax <value>`    | Maximum depth (in meters) to select tide gauges. **Default:** `4.0`.                                          |
| `-m <file>`        | Path to the **nei file** of the mesh (mesh connectivity).                                                     |
| `-b <file>`        | Path to the **bel file** of the mesh (boundary elements).                                                     |
| `-g <file>`        | Path to the **MGR file(s)** containing tide gauge harmonics. Can be called multiple times for multiple files. |
| `-o <file>`        | Output file name for the OBC file. **Default:** `tides.obc`.                                                  |
| `-p <path>`        | Path to the directory containing all input files.                                                             |
| `--debug`          | Activate **debug mode** for verbose output.                                                                   |


---

## Examples

### **Basic Usage**

Generate an OBC file for waves `M2` and `S2` using default settings:

```bash
mgr2obc -m mesh.nei -b mesh.bel -g tide_gauges.mgr -o output.obc M2 S2
```

### **Using Quadrangle Elements**

Force the grid to use quadrangles instead of triangles:

```bash
mgr2obc --quadrangle -m mesh.nei -b mesh.bel -g tide_gauges.mgr -o output.obc M2 S2
```

### **Appending to an Existing OBC File**

Append new waves (`K1`, `O1`) to an existing OBC file:

```bash
mgr2obc --append -m mesh.nei -b mesh.bel -g tide_gauges.mgr -o existing.obc K1 O1
```

### **Custom Maximum Depth**

Set a custom maximum depth (`10.0` meters) for tide gauge selection:

```bash
mgr2obc -dmax 10.0 -m mesh.nei -b mesh.bel -g tide_gauges.mgr -o output.obc M2 S2
```

### **Specifying Grid Options**

Use custom grid options for structured grid generation:

```bash
mgr2obc --grid "resolution=0.1,method=bilinear" -m mesh.nei -b mesh.bel -g tide_gauges.mgr -o output.obc M2 S2
```

### **Debug Mode**

Enable debug mode for verbose output:

```bash
mgr2obc --debug -m mesh.nei -b mesh.bel -g tide_gauges.mgr -o output.obc M2 S2
```

### **Using Multiple MGR Files**

Specify multiple MGR files for tide gauge data:

```bash
mgr2obc -m mesh.nei -b mesh.bel -g tide_gauges1.mgr -g tide_gauges2.mgr -o output.obc M2 S2
```

### **Custom Output Directory**

Specify a custom directory for input files:

```bash
mgr2obc -p /path/to/files -m mesh.nei -b mesh.bel -g tide_gauges.mgr -o output.obc M2 S2
```

---

## Environment Variables

`mgr2obc` does not rely on specific environment variables. However, ensure that:

- All input files (mesh, MGR, etc.) are accessible from the specified paths.
- The output directory (if custom) has **write permissions**.

---

## Notes

1. **Input Files:**
  - The **nei file** (`-m`) defines the mesh connectivity.
  - The **bel file** (`-b`) defines the boundary elements of the mesh.
  - The **MGR file(s)** (`-g`) contain the harmonic constants for tide gauges.
2. **Wave Selection:**
  - Waves (e.g., `M2`, `S2`, `K1`) must be specified as arguments. These correspond to tidal constituents in the MGR files.
  - If a wave is not found in the MGR file, the tool will exit with an error.
3. **Depth Filtering:**
  - Tide gauges are selected based on their distance from the boundary points. Only gauges within the specified `-dmax` depth are included.
4. **Grid Options:**
  - The `--grid` option allows customization of structured grid generation. Refer to the tool's internal documentation for supported options.
5. **Appending Waves:**
  - When using `--append`, ensure the existing OBC file is compatible with the new waves being added.
6. **Debug Mode:**
  - Use `--debug` to print detailed information about tide gauge selection and processing.

---

## See Also

- [MGR File Format Documentation](https://www.comodo-ocean.fr/) (for tide gauge harmonics)
- [Finite Element Mesh Formats](https://www.comodo-ocean.fr/) (for nei/bel files)