# vertical-eigenmodes v3.2.3

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

---

## Description

`vertical-eigenmodes` computes **vertical modes**, **spectral decomposition**, and **barotropic/baroclinic energy fluxes** from harmonic data. It supports multiple ocean models and datasets, allowing for flexible configurations of input variables and grid definitions.

---

## Usage

```bash
vertical-eigenmodes [OPTIONS]
```

---

## Options

### **Standard Options**


| Option                     | Description                                                                                                                                                                                                          | Default                |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `-h`, `--help`             | Display help and exit.                                                                                                                                                                                               | -                      |
| `-m <model>`               | Specify the model. Supported models: `NEMO`, `NEMO-snapshot`, `SYMPHONIE`, `SYMPHONIE-spectral`, `SYMPHONIE-snapshot-hybrid`, `ORCA`, `ORCA12`, `ORCA12-monthly`, `GLORYS`, `WOA2005`, `WOA2009`, `ECCO`, `LEVITUS`. | -                      |
| `-r <rootname>`            | Root name for output files.                                                                                                                                                                                          | Same as the model name |
| `--compute-modes=[yes|no]` | Whether to (re)compute vertical modes.                                                                                                                                                                               | `yes`                  |
| `--decomposition=[yes|no]` | Whether to (re)compute spectral decomposition.                                                                                                                                                                       | `yes`                  |
| `--recomposition=[yes|no]` | Whether to (re)compute spectral recomposition.                                                                                                                                                                       | `yes`                  |
| `-nmodes <N>`              | Number of vertical modes to compute.                                                                                                                                                                                 | `10`                   |
| `-nrecomposed <N>`         | Number of modes to project during recomposition.                                                                                                                                                                     | `10`                   |
| `-narchived <N>`           | Number of saved modes for snapshot models.                                                                                                                                                                           | `-1`                   |
| `-w <tidal_wave>`          | Tidal wave to analyze.                                                                                                                                                                                               | `M2`                   |


---

### **Grid and Variable Definitions**


| Option                                             | Description                          | Format                                                                      |
| -------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------- |
| `--grid <STANDARD_FILE_DEFINITION>`                | Grid information.                    | `"gridFile=<path> maskFile=<path> e3t=<var> e3u=<var> e3v=<var> e3w=<var>"` |
| `--ambient-density <STANDARD_FILE_DEFINITION>`     | Mean density for vertical modes.     | `"dataFile=<path> maskFile=<path> variable=<var> mask=<var>"`               |
| `--ambient-temperature <STANDARD_FILE_DEFINITION>` | Mean temperature for vertical modes. | `"dataFile=<path> maskFile=<path> variable=<var> mask=<var>"`               |
| `--ambient-salinity <STANDARD_FILE_DEFINITION>`    | Mean salinity for vertical modes.    | `"dataFile=<path> maskFile=<path> variable=<var> mask=<var>"`               |
| `-t_var <STANDARD_FILE_DEFINITION>`                | Temperature anomaly.                 | `"dataFile=<path> mask=<var> variable=<var>"`                               |
| `-s_var <STANDARD_FILE_DEFINITION>`                | Salinity anomaly.                    | `"dataFile=<path> mask=<var> variable=<var>"`                               |
| `-r_var <STANDARD_FILE_DEFINITION>`                | Density anomaly.                     | `"dataFile=<path> mask=<var> variable=<var>"`                               |
| `-u_var <STANDARD_FILE_DEFINITION>`                | Zonal velocity anomaly.              | `"dataFile=<path> mask=<var> variable=<var>"`                               |
| `-v_var <STANDARD_FILE_DEFINITION>`                | Meridional velocity anomaly.         | `"dataFile=<path> mask=<var> variable=<var>"`                               |
| `-w_var <STANDARD_FILE_DEFINITION>`                | Vertical velocity anomaly.           | `"dataFile=<path> mask=<var> variable=<var>"`                               |


> **Note:** For **complex variables**, use: `"dataFile=<path> mask=<var> amplitude=<var> phaselag=<var>"`.  
> **Warning:** Relative paths **must** start with `./`.

---

### **Additional Options**


| Option                           | Description                                                                       | Default |
| -------------------------------- | --------------------------------------------------------------------------------- | ------- |
| `-unstructured <discretisation>` | Discretization for unstructured grids.                                            | -       |
| `-b <bathymetry_file>`           | Additional bathymetry file (not needed for models).                               | -       |
| `-deflate [0-9]`                 | Compression level for output files (`0` = no compression, `9` = max compression). | `0`     |
| `--debug`                        | Enable debug mode.                                                                | -       |
| `--verbose`                      | Enable verbose mode.                                                              | -       |
| `--normalisation=[yes|no]`       | Whether to normalize vertical modes.                                              | `yes`   |
| `-nprocs <N>`                    | Number of processes to use.                                                       | -       |


---

## Examples

### **Basic Usage with NEMO Model**

Compute vertical modes for the `NEMO` model with default settings:

```bash
vertical-eigenmodes -m NEMO -r NEMO_output
```

---

### **Custom Vertical Modes and Decomposition**

Compute 15 vertical modes and enable spectral decomposition for the `SYMPHONIE` model:

```bash
vertical-eigenmodes -m SYMPHONIE \
  -nmodes 15 \
  --compute-modes=yes \
  --decomposition=yes \
  -r SYMPHONIE_output
```

---

### **Specify Grid and Ambient Variables**

Define grid and ambient variables for `NEMO`:

```bash
vertical-eigenmodes -m NEMO \
  --grid "gridFile=grid.nc maskFile=mask.nc e3t=e3t e3u=e3u e3v=e3v e3w=e3w" \
  --ambient-density "dataFile=rhop.nc maskFile=mask.nc variable=rhop mask=tmask" \
  --ambient-temperature "dataFile=temp.nc maskFile=mask.nc variable=temp mask=tmask" \
  --ambient-salinity "dataFile=sal.nc maskFile=mask.nc variable=sal mask=tmask" \
  -r NEMO_custom
```

---

### **Analyze a Specific Tidal Wave**

Compute vertical modes for the `M2` tidal wave with `WOA2009` data:

```bash
vertical-eigenmodes -m WOA2009 \
  -w M2 \
  -t_var "dataFile=./temp_annual_1deg.nc mask=tmask variable=t_an" \
  -s_var "dataFile=./salinity_annual_1deg.nc mask=tmask variable=s_an" \
  -r WOA2009_M2
```

---

### **Recompute Only Spectral Decomposition**

Skip vertical modes computation and only recompute spectral decomposition:

```bash
vertical-eigenmodes -m NEMO-spectral \
  --compute-modes=no \
  --decomposition=yes \
  -r NEMO_decomp
```

---

### **Use Compression for Output Files**

Enable compression (level 5) for output files:

```bash
vertical-eigenmodes -m SYMPHONIE \
  -deflate 5 \
  -r SYMPHONIE_compressed
```

---

### **Unstructured Grid**

Specify discretization for an unstructured grid:

```bash
vertical-eigenmodes -m SYMPHONIE-snapshot-hybrid \
  -unstructured "discretization=FV" \
  -r SYMPHONIE_unstructured
```

---

### **Monthly Processing with ORCA12**

Process monthly data for the `ORCA12` model:

```bash
vertical-eigenmodes -m ORCA12-monthly \
  -r ORCA12_monthly \
  -nmodes 12
```

---

## Environment Variables

`vertical-eigenmodes` uses **OpenMP** (version 201511) for parallelization. Key environment variables:


| Variable          | Description                               |
| ----------------- | ----------------------------------------- |
| `OMP_NUM_THREADS` | Number of threads to use.                 |
| `OMP_SCHEDULE`    | Runtime schedule type and chunk size.     |
| `OMP_DYNAMIC`     | Enable/disable dynamic thread adjustment. |
| `OMP_NESTED`      | Enable/disable nested parallelism.        |


**Example:**

```bash
OMP_NUM_THREADS=6 vertical-eigenmodes -m NEMO -r NEMO_parallel
```

> **Note:** If running on a busy machine, limit threads to the number of **free CPUs** to avoid performance degradation.

---

## Notes

1. **Model-Specific Configurations:**
  - Many file or variable names are **model-dependent**. Refer to the documentation of your specific model for details.
  - The `STANDARD_FILE_DEFINITION` format allows flexible configuration of input files, masks, and variables.
2. **Output Files:**
  - Vertical modes are saved in `<rootname>.vertical-modes.nc`.
  - Spectral decomposition results are saved in `<wave>-modal-decomposition.nc`.
  - Spectral recomposition results are saved in `<wave>-modal-recomposition.nc`.
3. **Performance:**
  - Use `-nprocs` to control the number of processes for parallel computation.
  - Adjust `OMP_NUM_THREADS` based on available CPU resources.
4. **Debugging:**
  - Use `--debug` and `--verbose` for troubleshooting.
5. **Deprecated Options:**
  - `-tfile`, `-sfile`, `-rfile`, `-pfile`, `-ufile`, `-mfile` are deprecated. Use `-t_var`, `-s_var`, `-r_var`, `-p_var`, `-u_var`, `--grid` instead.

---

## See Also

- [OpenMP Documentation](https://www.openmp.org/)
- [NetCDF CF Conventions](http://cfconventions.org/)
- Model-specific documentation (e.g., NEMO, SYMPHONIE, ORCA).