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¶

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 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.

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:

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:

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:

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

Using Quadrangles¶

Use quadrangles for the mesh:

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

Masking Zero Depth¶

Treat zero depth as masked:

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):

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:

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:

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):

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:

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¶

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).

Output:

The default output file is tides.obc.
If --append is used, the tool adds new waves to the existing file.

Variables:

Default variables: Ha, Hg, Ua, Ug, Va, Vg.
You can override this list with -v. Terminate the list with an empty string ("").

Wave Names:

Wave names are case-sensitive and must match the atlas file names (after convention replacement).

Extrapolation:

The --extrapolation-distance option is useful for filling gaps in tidal data near boundaries.