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¶

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.
`–decomposition=[yes	no]`	Whether to (re)compute spectral decomposition.
`–recomposition=[yes	no]`	Whether to (re)compute spectral recomposition.
`-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.
`-nprocs <N>`	Number of processes to use.	-

Examples¶

Basic Usage with NEMO Model¶

Compute vertical modes for the NEMO model with default settings:

vertical-eigenmodes -m NEMO -r NEMO_output

Custom Vertical Modes and Decomposition¶

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

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:

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:

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:

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:

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

Unstructured Grid¶

Specify discretization for an unstructured grid:

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

Monthly Processing with ORCA12¶

Process monthly data for the ORCA12 model:

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:

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¶

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.

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.

Performance:

Use -nprocs to control the number of processes for parallel computation.
Adjust OMP_NUM_THREADS based on available CPU resources.

Debugging:

Use --debug and --verbose for troubleshooting.

Deprecated Options:

-tfile, -sfile, -rfile, -pfile, -ufile, -mfile are deprecated. Use -t_var, -s_var, -r_var, -p_var, -u_var, --grid instead.