# convert-nf v3.2.3 **Mercurial revision 5770:c90c3015e72d | 2026-05-22** --- ## Description `convert-nf` is a tool used to **convert TUGOm outputs**. It is utilized by **CTOH** (Centre de Topographie des Océans et de l'Hydrosphère). - If no grid is provided using `-z` or `-g`, the tool produces **unstructured outputs**. - If a grid is provided, it **interpolates the data to a structured grid**. > **Input Formats:** > > - TUGOm's binary format (default). > - If no binary file is found, it falls back to TUGOm's NetCDF format. --- ## Usage ```bash convert-nf [OPTIONS] ``` --- ## Options ### **General Options** | Option | Description | | --------------- | ------------------------------------------------------------------ | | `--help` | Display help and exit. | | `--mesh ` | Input mesh file (used if mesh data is not present in input files). | --- ### **Input/Output Variables** | Option | Description | | -------------- | --------------------------------------------------------------- | | `--ssh ` | SSH (Sea Surface Height) variable name in input files. | | `--u ` | Zonal velocity variable name in input files. | | `--v ` | Meridional velocity variable name in input files. | | `--p ` | Pressure variable name in input files. | | `--ibd ` | Inverse Barometer Departure (IBD) variable name in input files. | --- ### **Output Content Options** | Option | Description | | ----------- | -------------------------------------------------------- | | `-pressure` | Include pressure in the output. | | `-currents` | Include currents in the output. | | `-ibd` | Include Inverse Barometer Departure (IBD) in the output. | | `-s1` | Enable detiding of the **S1** tidal constituent. | | `-s2` | Enable detiding of the **S2** tidal constituent. | | `-sa` | Enable detiding of the **Sa** tidal constituent. | | `-cm` | Scale output values to **centimeters**. | --- ### **File and Directory Options** | Option | Description | | ----------- | ----------------------------------------------------------------------------------------------------------- | | `-p ` | Root name for forcing files (default: `forcing-`). | | `-h ` | Root name for analysis files (default: `analysis-`). If used as the last argument, displays help and exits. | | `-d ` | Input directory (default: `.`). | | `-o ` | Output directory (default: `.`). | | `-z ` | Output grid zone name. | | `-g ` | Output grid file. | --- ### **Processing Options** | Option | Description | | ---------------------- | ------------------------------------------------------------------ | | `-s ` | Start date in `mm/yyyy` format. | | `-e ` | End date in `mm/yyyy` format. | | `-f ` | Output format: `cdf` (NetCDF, default) or `ascii`. | | `-r` | Input files are **reduced** and their names end with `.reduced-6`. | | `-i ` | Frame stride (default: `1`). | | `--duplicate-varnames` | Allow duplicate variable names in the output. | | `-deflate ` | Set the compression level for NetCDF output (default: `4`). | | `--mapping ` | Mapping string to define the output grid. | --- ## Examples ### **Basic Conversion to NetCDF** Convert TUGOm outputs to NetCDF with default settings: ```bash convert-nf -d /path/to/input -o /path/to/output ``` ### **Convert with Custom Variable Names** Specify custom variable names for SSH, zonal velocity, and meridional velocity: ```bash convert-nf --ssh sea_surface_height --u u_velocity --v v_velocity -d /input -o /output ``` ### **Include Pressure and Currents** Convert and include pressure and currents in the output: ```bash convert-nf -pressure -currents -d /input -o /output ``` ### **Detide Specific Constituents** Enable detiding for **S1**, **S2**, and **Sa** constituents: ```bash convert-nf -s1 -s2 -sa -d /input -o /output ``` ### **Scale Output to Centimeters** Convert and scale output values to centimeters: ```bash convert-nf -cm -d /input -o /output ``` ### **Use a Structured Grid** Interpolate to a structured grid using a grid file: ```bash convert-nf -g /path/to/grid.nc -d /input -o /output ``` ### **Convert Reduced Files** Process reduced input files (names ending with `.reduced-6`): ```bash convert-nf -r -d /input -o /output ``` ### **Custom Output Format (ASCII)** Convert to ASCII format instead of NetCDF: ```bash convert-nf -f ascii -d /input -o /output ``` ### **Specify Date Range** Convert files for a specific date range (e.g., January 2020 to December 2020): ```bash convert-nf -s 01/2020 -e 12/2020 -d /input -o /output ``` ### **Use Custom Root Names** Specify custom root names for forcing and analysis files: ```bash convert-nf -p custom_forcing -h custom_analysis -d /input -o /output ``` ### **Enable Detiding and Include IBD** Enable detiding for **S2** and include Inverse Barometer Departure (IBD): ```bash convert-nf -s2 -ibd -d /input -o /output ``` --- ## Environment Variables `convert-nf` does not explicitly rely on environment variables for its core functionality. However, it may inherit environment settings from the system or parent processes, such as: - **`PATH`**: For locating executable files. - **`LD_LIBRARY_PATH`**: For locating shared libraries (if applicable). --- ## Notes 1. **Input Files:** - The tool expects **TUGOm binary or NetCDF** files as input. - If no grid is provided (`-z` or `-g`), outputs will be **unstructured**. 2. **Output Files:** - By default, outputs are saved in **NetCDF format** (`cdf`). - Use `-f ascii` for ASCII output. 3. **Detiding:** - Detiding is optional and can be enabled for **S1**, **S2**, or **Sa** constituents using `-s1`, `-s2`, or `-sa`. 4. **Grid Interpolation:** - If a grid is provided (`-g` or `-z`), the tool interpolates data to a **structured grid**. - The `--mapping` option allows defining a custom grid via a string. 5. **Compression:** - NetCDF outputs are compressed by default (level `4`). Adjust with `-deflate `. 6. **Reduced Files:** - Use `-r` if input files are reduced and end with `.reduced-6`. 7. **Frame Stride:** - Use `-i ` to process every `n`-th frame (e.g., `-i 2` processes every other frame). --- ## See Also - [TUGOm Model](https://www.tugom.fr/) (for input file formats and conventions) - [CTOH](https://www.ctoh.legos.obs-mip.fr/) (Centre de Topographie des Océans et de l'Hydrosphère) - [NetCDF Documentation](https://www.unidata.ucar.edu/software/netcdf/) (for output format details)