# fes-converter v3.2.3

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

---

## Description

`fes-converter` standardizes the discretization of tidal waves to a **common discretization pair**. By default, it uses **LGP2** for equilibrium, sequential, spectral, and assimilated conventions.

This tool ensures consistency in the representation of tidal data across different input formats and discretizations.

---

## Usage

```bash
fes-converter input [OPTIONS]
```

---

## Options


| Option                              | Description                                                                                                                                                                                                          |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-h`, `--help`                      | Display help and exit.                                                                                                                                                                                               |
| `-i <convention> <var1> [var2 ...]` | Input convention and **2 to 6 variable names**. Defaults depend on the wave type (see [Convention](#convention26)).                                                                                            |
| `-o <convention> <var1> [var2 ...]` | Output convention and **2 to 6 variable names**. Default: `/home/data/tides/FES2014/distribution_fes2014b/synthesis/unstructured/WAVE.FES2014-unified.nc a_eta_LGP2 G_eta_LGP2 a_u_DNP1 G_u_DNP1 a_v_DNP1 G_v_DNP1`. |
| `-d <pair>`                         | **Deprecated.** Use `-oD` instead. Output discretization pair (default: `DNP1xLGP2`).                                                                                                                                |
| `-oD <pair>`                        | Output discretization pair (e.g., `DNP1xLGP2`).                                                                                                                                                                      |
| `-iD <pair>`                        | Input discretization pair. **Required** if input and output discretizations differ.                                                                                                                                  |
| `-m <file>`                         | Path to the mesh file.                                                                                                                                                                                               |
| `--diffusion`                       | When converting from **LGP0 to LGP1**, use diffusion instead of projection.                                                                                                                                          |


---

(convention26)=
### Convention

If `-i` is not specified, the tool uses the following defaults based on the wave type:


| Wave Type       | Convention                                                                                    | Variables                                                                                |
| --------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Equilibrium** | `/home/data/tides/FES2014/distribution_fes2014c/equilibrium/unstructured/WAVE.FES2014b-UG.nc` | `Ha`, `Hg`                                                                               |
| **Sequential**  | `/home/data/tides/FES2014/distribution_fes2014a/HYDRO/unstructured/WAVE.sequential.nc`        | `a_eta_LGP1`, `G_eta_LGP1`, `a_u_LGP1`, `G_u_LGP1`, `a_v_LGP1`, `G_v_LGP1`               |
| **Spectral**    | `/home/data/tides/FES2014/distribution_fes2014a/HYDRO/unstructured/WAVE.spectral.nc`          | `a_eta_LGP2`, `G_eta_LGP2`, `a_u_DNP1`, `G_u_DNP1`, `a_v_DNP1`, `G_v_DNP1`               |
| **Assimilated** | `/home/data/tides/FES2014/distribution_fes2014b/ASSIMILE+COURANTS/unstructured/WAVE.EnOI.nc`  | `analysis_Ha`, `analysis_Hg`, `analysis_Ua`, `analysis_Ug`, `analysis_Va`, `analysis_Vg` |


---

## Examples

### **Basic Conversion**

Convert input data using default discretization (`DNP1xLGP2`):

```bash
fes-converter M2
```

### **Specify Input and Output Conventions**

Convert from a **spectral** input to a custom output:

```bash
fes-converter -i /home/data/tides/FES2014/distribution_fes2014a/HYDRO/unstructured/WAVE.spectral.nc a_eta_LGP2 G_eta_LGP2 \
  -o /home/data/tides/FES2014/output.nc a_eta_LGP2 G_eta_LGP2
```

### **Custom Discretization Pairs**

Convert using explicit input and output discretization pairs:

```bash
fes-converter -iD LGP1xLGP1 -oD DNP1xLGP2 \
  -i /home/data/tides/FES2014/input.nc a_eta_LGP1 G_eta_LGP1 \
  -o /home/data/tides/FES2014/output.nc a_eta_LGP2 G_eta_LGP2
```

### **Diffusion for LGP0 to LGP1 Conversion**

Use diffusion instead of projection when converting from **LGP0 to LGP1**:

```bash
fes-converter --diffusion \
  -i /home/data/tides/FES2014/input.nc a_eta_LGP0 G_eta_LGP0 \
  -o /home/data/tides/FES2014/output.nc a_eta_LGP1 G_eta_LGP1
```

### **Convert Multiple Waves**

Convert multiple waves (e.g., `M2`, `S2`, `K1`) with a custom output:

```bash
fes-converter M2 S2 K1 \
  -o /home/data/tides/FES2014/output.nc a_eta_LGP2 G_eta_LGP2 a_u_DNP1 G_u_DNP1
```

---

## Environment Variables

`fes-converter` does not rely on specific environment variables. However, ensure that:

- Input and output file paths are **accessible** and **writable**.
- The system has sufficient **memory** for large datasets.

---

## Notes

1. **Input/Output Variables:**
  - The `-i` and `-o` options **require 3 to 7 parameters**: 1 file convention + 2 to 6 variable names.
  - If `-i` is omitted, the tool uses **default conventions** based on the wave type.
2. **Discretization Pairs:**
  - If `-iD` is not specified, the tool assumes the input discretization matches the output discretization (`-oD`).
  - The `-d` option is **deprecated**. Use `-oD` instead.
3. **Mesh File:**
  - The `-m` option is used to specify a **mesh file** for the conversion process.
4. **Diffusion vs. Projection:**
  - The `--diffusion` option is **only relevant** when converting from **LGP0 to LGP1**. It ensures smoother transitions in the output data.

---

## See Also

- [FES2014 Documentation](https://www.legos.obs-mip.fr/en/activities/space-geodesy/altimetry/tide-models/fes)
- [Discretization in Finite Element Models](https://en.wikipedia.org/wiki/Finite_element_method#Discretization)