# atlas2obc v3.2.3

**Mercurial revision 5803:7164e00e8f3d | 2026-08-18**

---

## Description

`atlas2obc` is a tool that **creates open boundary condition (OBC) files** for **TUGOm** (a coastal ocean model). It processes tidal atlas data to generate boundary conditions for specified tidal waves.

---

## Usage

```bash
atlas2obc OPTIONS wave1 [wave2 ...]
```

---

## Options


| Option                                | Description                                                                                                                                  |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--help`, `-h`                        | Display help and exit.                                                                                                                       |
| `--quadrangle`                        | Use quadrangles instead of triangles for mesh elements.                                                                                      |
| `--zero`                              | Treat **0 depth** as masked (excluded) in the output.                                                                                        |
| `--append`                            | Append points to an existing `.obc` file.                                                                                                    |
| `--extrapolation-distance <distance>` | Set the extrapolation distance (in meters) for tidal data. Default: `5000.0`.                                                                |
| `-m <file>`                           | Path to the **mesh file** in `.nei` format.                                                                                                  |
| `-b <file>`                           | Path to the **boundary element file** in `.bel` format.                                                                                      |
| `-p <dir>`                            | Path to the **directory containing atlas files**. Default: `./`.                                                                             |
| `-c <convention>`                     | Atlas file name convention. Up to **3 uses** of this option are allowed. See [Convention](#convention14) for details.                          |
| `-o <file>`                           | Path to the **output open boundary file**. Default: `tides.obc`.                                                                             |
| `-v <var1> [var2 ...]`                | List of **variable names** (up to 6) to include in the output. Default: `Ha Hg Ua Ug Va Vg`. Terminate the list with an empty string (`""`). |
| `-g <string>`                         | Grid options string for TUGOm, e.g., `file=<rootname> <input keys of mesh_meta>` from the `.intg` file.                                      |


---

(convention14)=
## Convention

The atlas file name convention supports dynamic placeholders:


| Placeholder | Replacement                         |
| ----------- | ----------------------------------- |
| `WAVE`      | Uppercase wave name (e.g., `M2`).   |
| `wave`      | Lowercase wave name (e.g., `m2`).   |
| `Wave`      | Capitalized wave name (e.g., `M2`). |


> **Note:** If the file exists without any replacements, no substitution is performed.

> **Example:** If the convention is `WAVE.FES2014.nc`, the file for wave `M2` will be `M2.FES2014.nc`.

---

## Examples

### **Basic Usage**

Create an OBC file for waves `M2` and `S2`:

```bash
atlas2obc -m mesh.nei -b boundary.bel -p ./atlases -o tides.obc M2 S2
```

### **Using a Custom Atlas Directory**

Specify a custom directory for atlas files:

```bash
atlas2obc -m mesh.nei -b boundary.bel -p /path/to/atlases -o output.obc M2 S2 K1
```

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

Append tidal data for waves `N2` and `K2` to an existing OBC file:

```bash
atlas2obc --append -m mesh.nei -b boundary.bel -p ./atlases -o existing.obc N2 K2
```

### **Using Quadrangles**

Use quadrangles for the mesh:

```bash
atlas2obc --quadrangle -m mesh.nei -b boundary.bel -p ./atlases -o tides.obc M2 S2
```

### **Masking Zero Depth**

Treat zero depth as masked:

```bash
atlas2obc --zero -m mesh.nei -b boundary.bel -p ./atlases -o tides.obc M2 S2
```

### **Custom Variable List**

Specify custom variables (e.g., `Ha`, `Hg`, `Ua`):

```bash
atlas2obc -m mesh.nei -b boundary.bel -p ./atlases -v Ha Hg Ua "" -o tides.obc M2 S2
```

### **Using Multiple Atlas Conventions**

Use up to 3 different naming conventions for atlas files:

```bash
atlas2obc -m mesh.nei -b boundary.bel \
  -p ./atlases \
  -c "WAVE.FES2014.nc" \
  -c "wave_amp.nc" \
  -c "Wave_pha.nc" \
  -o tides.obc M2 S2
```

### **Grid Options for TUGOm**

Specify grid options for TUGOm:

```bash
atlas2obc -m mesh.nei -b boundary.bel \
  -g "file=my_grid rootname=my_mesh" \
  -p ./atlases \
  -o tides.obc M2 S2
```

### **Extrapolation Distance**

Set a custom extrapolation distance (e.g., 10,000 meters):

```bash
atlas2obc --extrapolation-distance 10000 -m mesh.nei -b boundary.bel -p ./atlases -o tides.obc M2 S2
```

### **Tip: Get All Available Atlases**

To process all atlas files in a directory with extension `.FES2014.nc`:

```bash
dir=/path/to/atlases
ext=.FES2014.nc
files=($(cd $dir; echo *$ext))
atlas2obc -m mesh.nei -b boundary.bel -p $dir -c WAVE$ext -o tides.obc ${files[@]/$ext}
```

---

## Environment Variables

`atlas2obc` does not directly use environment variables, but it relies on:

- **File paths** for input/output (mesh, boundary, atlas, and OBC files).
- **TUGOm configurations** (if `-g` is used).

---

## Notes

1. **Input Requirements:**
  - A **mesh file** (`-m`) and a **boundary element file** (`-b`) are **required** unless appending to an existing OBC file (`--append`).
  - Atlas files must follow the specified **naming convention** (`-c`).
2. **Output:**
  - The default output file is `tides.obc`.
  - If `--append` is used, the tool adds new waves to the existing file.
3. **Variables:**
  - Default variables: `Ha`, `Hg`, `Ua`, `Ug`, `Va`, `Vg`.
  - You can override this list with `-v`. Terminate the list with an empty string (`""`).
4. **Wave Names:**
  - Wave names are **case-sensitive** and must match the atlas file names (after convention replacement).
5. **Extrapolation:**
  - The `--extrapolation-distance` option is useful for filling gaps in tidal data near boundaries.

---

## See Also

- [TUGOm Model Documentation](https://www.tugom.fr/)
- [NetCDF CF Conventions](http://cfconventions.org/)