tides-extension v3.2.3¶

Mercurial revision 5770:c90c3015e72d | 2026-05-22

Description¶

tides-extension expands the spectrum of a set of tidal atlases using the admittance method. It allows you to:

Create missing atlases by interpolating or extrapolating tidal constants for additional waves using the admittance method.
Print coefficients if only wave names are provided (without additional options).

Tip: For better results, use comodo-detidor with a complete list of waves instead of relying solely on tides-extension.

⚠️ Important Warnings¶

Non-linear interactions: When adding frequencies, combinations like K1+O1=M2, K1+P1=S2, and M1+O1=N2 can occur. Run showarg --combinations for more details.

The more non-linear and mixed semi-diurnal the zone is, the less reliable the admittance method becomes.
Input waves must be the strongest in their category. Only the following waves should be used as input:
M2, K2, N2, K1, O1, Q1, Mf, Mm, Mtm.
⚠️ Avoid S2: S2 has a strong radiative component. Do not include S2 in the wave list unless you are fully aware of the risks.

Usage¶

tides-extension [OPTIONS] wave1 wave2 wave3 [wave4 ...]

Note: At least 3 waves must be provided.

Options¶

Option	Description
`-h`, `--help`	Display this help and exit.
`-a <convention>`	Atlas file name convention. See Convention.
`-m <file>`	Mesh file (only used for unstructured grids).
`-v <amp_var> <phase_var>`	Variable names for amplitude and phase (respectively).
`-d <discretisation>`	Discretisation type (e.g., `LGP2`). If unspecified, a structured grid is assumed.
`-p <prefix>`	Prefix for forcing admittance of the last wave. ⚠️ Bug: Not available for unstructured grids yet.
`--keep-average`	Keep the average component. ⚠️ Bug: Only available for unstructured grids yet.
`--suffix <suffix>`	Suffix for output files.
`--standard <name>`	Admittance standard. Supported values: `LEGOS_LEGACY`, `AVISO_PROXY`, `AVISO_LEGACY`.
`--base <waves>`	List of base waves for admittance (space-separated).
`--admittance <waves>`	List of target waves for admittance (space-separated).
`--equilibrium <waves>`	List of target waves for equilibrium (space-separated).

Convention¶

The following placeholders are used in file naming:

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.

Examples¶

Print Coefficients for Given Waves¶

tides-extension M2 S2 K1 O1 N2

Expand Atlas Spectrum Using Admittance (Structured Grid)¶

tides-extension -a WAVE.nc -v amplitude phase \
  --standard AVISO_LEGACY \
  --admittance "2Q1 Sig1 Ro1 Ki1 M1 OO1 Phi1 Pi1 Tta1 KJ2" \
  M2 S2 K1 O1 N2

Expand Atlas Spectrum Using Admittance (Unstructured Grid)¶

tides-extension -a WAVE.nc -m mesh.nc -v a_eta_LGP2 G_eta_LGP2 -d LGP2 \
  --standard AVISO_LEGACY \
  --admittance "2Q1 Sig1 Ro1 Ki1 M1 OO1 Phi1 Pi1 Tta1 KJ2" \
  M2 S2 K1 O1 N2

Expand Atlas Spectrum Using Equilibrium¶

tides-extension -a WAVE.nc -m mesh.nc -v a_eta_LGP2 G_eta_LGP2 -d LGP2 \
  --standard AVISO_LEGACY \
  --equilibrium "MSf" \
  M2 S2 K1 O1

Custom Base Waves for Admittance¶

tides-extension -a WAVE.nc -v amplitude phase \
  --standard LEGOS_LEGACY \
  --base "M2 K2 N2 K1 O1 Q1" \
  --admittance "2Q1 Sig1 Ro1" \
  M2 S2 K1 O1 N2

Using Suffix and Prefix¶

tides-extension -a WAVE.nc -v amplitude phase \
  --suffix _custom \
  -p custom_prefix \
  --admittance "2Q1 Sig1" \
  M2 K1 O1

Environment Variables¶

tides-extension does not directly use environment variables, but it relies on underlying libraries (e.g., NetCDF, OpenMP) that may be influenced by:

Variable	Description
`OMP_NUM_THREADS`	Number of threads for parallel processing (if OpenMP is used).

Notes¶

Input Waves:

Only astronomical waves are supported for admittance and equilibrium methods.
Non-astronomical waves will be ignored with a warning.

Admittance Method:

The method is less reliable in highly non-linear or mixed semi-diurnal zones.
Always verify results when adding frequencies that interact (e.g., K1+O1=M2).

Standards:

LEGOS_LEGACY: Uses user-prescribed pivots and LEGOS tidal potential coefficients.
AVISO_PROXY: Pivots are uniquely defined per wave; coefficients derived from LEGOS tidal potential.
AVISO_LEGACY: Pivots are uniquely defined per wave; coefficients hard-coded to match AVISO libFES settings.

Grid Types:

If -d is unspecified, a structured grid is assumed.
For unstructured grids, provide the mesh file (-m) and discretisation (-d).

Bugs:

--keep-average is only available for unstructured grids.
-p (prefix) is not available for unstructured grids yet.