metocean-predictor v3.2.3¶

Mercurial revision 5770:c90c3015e72d | 2026-05-22

Description¶

metocean-predictor is a tool designed to predict tidal currents and elevations based on harmonic analysis. It uses tidal atlases to compute:

Maximum current (if 4 or 6 variables are provided: U_amplitude, U_phase, [V_amplitude, V_phase, [W_amplitude, W_phase]]).
Minimum and maximum elevations (if 2 variables are provided: amplitude and phase).

Usage¶

metocean-predictor -a atlas_convention -v U_amplitude U_phase [V_amplitude V_phase [W_amplitude W_phase]] -w wave1 [wave2 ...]

Options¶

Option	Description
`-h`, `--help`	Display help and exit.
`-a <convention>`	Atlas file name convention. See Convention below.
`-s <date>`	Start date for predictions. Default: `2000`.
`-f <date>`	End date for predictions. Default: `2018` (inclusive).
`-i <value><unit>`	Time increment for predictions. Default: `1800s` (30 minutes). Units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days).
`-v <var1> <var2> [...]`	List of variable names for amplitude and phase (up to 3 pairs).
`-o <file>`	Output file name. Default: `max.nc`.
`-w <wave1> [wave2 ...]`	List of tidal waves to predict.

Convention¶

The atlas file name convention supports dynamic placeholders:

"WAVE" → Replaced by the uppercase wave name (e.g., M2).
"wave" → Replaced by the lowercase wave name (e.g., m2).
"Wave" → Replaced by the capitalized wave name (e.g., M2 → M2, K1 → K1).

Note: If the file exists without any replacements, no substitution is performed.

Date Formats¶

Supported formats:

yyyy/mm/dd HH:MM:SS.SSS
dd/mm/yyyy HH:MM:SS.SSS
mm/yyyy

Notes:

The least significant parts (seconds, minutes, hours, days, months) are optional.

The separator can be any non-numeric character (e.g., /, -, `` ).

End dates are inclusive. Examples:

2000 → 2001/01/01 00:00:00

2000/01 → 2000/02/01 00:00:00

2000/01/01 → 2000/01/02 00:00:00

2000/01/01 00 → 2000/01/01 01:00:00

2000/01/01 00:00 → 2000/01/01 00:01:00

Wave List¶

You can specify any tidal wave supported by the tool. Use showarg (from the comodo toolkit) to list available waves.

Examples¶

Predict Maximum Current (4 Variables)¶

Predict maximum current for waves M2 and S2 using amplitude and phase variables for U and V components:

metocean-predictor \
  -a "tide_WAVE_amplitude_phase.nc" \
  -v U_amplitude U_phase V_amplitude V_phase \
  -w M2 S2 \
  -s 2000/01/01 \
  -f 2000/01/02 \
  -i 3600s \
  -o max_current.nc

Predict Maximum Current (6 Variables)¶

Predict maximum current for waves M2, S2, and K1 using amplitude and phase variables for U, V, and W components:

metocean-predictor \
  -a "tide_Wave_amplitude_phase.nc" \
  -v U_amplitude U_phase V_amplitude V_phase W_amplitude W_phase \
  -w M2 S2 K1 \
  -s 2000/01/01 \
  -f 2000/01/02 \
  -i 1800s \
  -o max_current_3d.nc

Predict Minimum and Maximum Elevations (2 Variables)¶

Predict minimum and maximum elevations for waves M2 and S2:

metocean-predictor \
  -a "tide_WAVE_elevation.nc" \
  -v elevation_amplitude elevation_phase \
  -w M2 S2 \
  -s 2000/01/01 \
  -f 2000/01/02 \
  -i 3600s \
  -o elevation_extremes.nc

Use Default Dates and Increment¶

Predict maximum current for waves M2 and K1 using default dates (2000 to 2018) and time increment (1800s):

metocean-predictor \
  -a "tide_WAVE.nc" \
  -v U_amplitude U_phase V_amplitude V_phase \
  -w M2 K1 \
  -o default_prediction.nc

Custom Time Increment¶

Predict elevations with a time increment of 1 hour:

metocean-predictor \
  -a "tide_WAVE.nc" \
  -v elevation_amplitude elevation_phase \
  -w M2 S2 \
  -s 2000/01/01 \
  -f 2000/01/03 \
  -i 1h \
  -o hourly_elevation.nc

Environment Variables¶

metocean-predictor 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 metocean-predictor -a "tide_WAVE.nc" -v U_amplitude U_phase -w M2 S2

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

Notes¶

Input Requirements:

Atlas files must follow the specified convention.
Variables must be provided in pairs (amplitude and phase) for each component (e.g., U_amplitude and U_phase).
The number of variables must be 2, 4, or 6 (for 1, 2, or 3 components, respectively).

Output:

The output file (-o) contains:
- max: Maximum values (current speed or elevation).
- maxdir: Direction of maximum current (if 4 or 6 variables are provided).
- min: Minimum values (if 2 variables are provided).

Performance:

For large datasets, adjust OMP_NUM_THREADS to match the number of available CPU cores.
The tool automatically parallelizes computations using OpenMP.

Time Handling:

The time increment (-i) must be specified with a unit (s, m, h, or d).
The start (-s) and end (-f) dates are inclusive.