predictor v3.2.3¶

Mercurial revision 5770:c90c3015e72d | 2026-05-22

Description¶

predictor is a tool designed to interpolate tidal constants and predict tides at specified points using provided tidal atlases. It is used by CTOH (Centre de Topographie des Océans et de l’Hydrosphère).

If start and end dates are provided, it generates tidal predictions for the specified time range.
OpenMP parallelization is activated automatically if there are many points per time step.

Usage¶

predictor [-p lon_lat_list] -a atlas_convention [-s start -f end] -w wave1 [wave2 ...] [OPTIONS]

Options¶

General Options¶

Option	Description
`-h`, `--help`	Display help and exit.
`--verbose`	Force printing of constants when in altimetry mode (see `-p` option).
`--nodal=no`	Disable nodal corrections.
`--spring-neap`	Print spring/neap times for the first point.

Input/Output Options¶

Option	Description
`-p <file>`	Path to a file containing control points. Can be:

An ASCII file with the number of control points followed by their coordinates (longitude latitude).
A pattern of NetCDF files with latitude, longitude, and time variables (see -o option).
If not provided, predictions are made for all points in the atlas. |
| -m <file> | Path to save/load extracted constants. |
| -a <convention> | Atlas file name convention. See Convention for details. |
| -g <file> | Path to the atlas grid or mesh file. |
| -o <file> | Path for the output file. The format depends on the input:
NetCDF if:
- -p is not provided, or
- -p specifies a NetCDF file with a time variable, or
- -o ends with .nc.
ASCII otherwise.
Default: predictions.dat, predictions.nc, or %s-predictions.nc (where %s is the input file path).
If empty, predictions are added to the input file. |

Wave and Spectrum Options¶

Option	Description
`-w <wave1> [wave2 ...]`	List of waves to predict. For optimal speed, sort waves by atlas type (or size). See Wave Lists and Spectra
`--spectrum <spectrum>`	Use a predefined spectrum. See Wave Lists and Spectra.
`-cm`	Use if atlases are in centimeters (scales values by 0.01).

Time Options¶

Option	Description
`-s <date>`	Start date for predictions. See Date Formats.
`-f <date>`	End date for predictions. See Date Formats.
`-i <value><unit>`	Time increment for predictions. `<unit>` can be `s` (seconds, default), `m` (minutes), `h` (hours), or `d` (days). Default: `3600s` (1 hour).

Output Customization¶

Option	Description
`-v <var1> [var2]`	Variable names for amplitude and phase. Default: `Ha Hg`.
`--output-var <name>`	Name of the NetCDF output variable. Default: `prediction`.
`--references <string>`	String for the `references` attribute of the output variable.
`--unit <string>`	Unit for the output variable. Default: `m`.
`--long_name <string>`	Long name for the output variable.
`--standard_name <string>`	Standard name for the output variable.

Advanced Options¶

Option	Description
`--time <format>`	Format of the time variable in ASCII files. Options:

CNES: Days since 1950/01/01 00:00.
ELAPSED: Days since the start date.
CALENDAR: Human-readable dates (yyyy/mm/dd HH:MM:SS.S).
Default: ELAPSED CALENDAR. |
| --extrapolation-distance <value> | Extrapolation distance in meters. |
| --mass-conservation <0|1|2> | Mass conservation correction:
0: No correction.
1: Standard mass correction.
2: Buggy CLS mass correction. |
| --astronomic-angles <method> | Method for astronomic angles: linearSchureman or Meeus. |
| --prediction-standard <standard> | Prediction standard. If set to AVISO_LEGACY, implies:
--admittance-target AVISO-FES-ADMITTANCE
--equilibrium-target AVISO-FES-LP
--astronomic-angles AVISO-FES-2.9.5 |
| --admittance-target <target> | Target for admittance-derived waves. |
| --equilibrium-target <target> | Target for equilibrium-derived waves. |
| --with-statistics | Enable statistical computations. |
| --without-storage | Disable storing predictions. |
| --hint <variable> | Hint for parsing input NetCDF files (e.g., variable name for time/lat/lon). |

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 Lists and Spectra¶

You can specify:

Individual waves (e.g., M2, S2, K1). Run showarg to see the full list of available waves.
Predefined spectra:

ESTUARINE
ESTUARINE-HF
COMODO
COASTAL
COASTAL-HF
SHELF
SHELF-HF
DEEP
DEEP-HF
REDUCED
CURRENTS-HF
FES2022c
AVISO-FES-SP
AVISO-FES-ADMITTANCE
AVISO-FES-LP
AVISO-FES-LP-PROXY

Convention¶

The atlas file name convention uses the following 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).

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

Examples¶

Basic Prediction¶

Predict tides for waves M2 and S2 at points listed in control.dat:

predictor -p control.dat -a WAVE.nc -g mesh.nc -w M2 S2

Prediction with Time Range¶

Predict tides from 2000/01/01 to 2000/01/10 with a 1-hour increment:

predictor -p control.dat -a WAVE.nc -g mesh.nc \
  -s 2000/01/01 -f 2000/01/10 -i 1h \
  -w M2 S2 K1 O1

Using a Predefined Spectrum¶

Use the FES2022c spectrum for predictions:

predictor -p control.dat -a WAVE.nc -g mesh.nc \
  --spectrum FES2022c

Altimetry-Compatible Predictions¶

Generate predictions compatible with AVISO-FES-2.9.5:

predictor -p control.dat -a WAVE.nc -g mesh.nc \
  --prediction-standard AVISO_LEGACY \
  -w MKS2 MSqm 2N2 La2 Mu2 Nu2 MN4 MS4 MSf_nL Mtm Ssa E2 J1 K1 K2 L2 M2 M4 N2 O1 P1 Q1 S2 M3 M6 M8 Mf Mm N4 R2 S1 S4 Sa T2

Predict for All Atlas Points¶

Predict tides for all points in the atlas (no -p option):

predictor -a WAVE.nc -g mesh.nc \
  -s 2000/01/01 -f 2000/01/10 \
  -w M2 S2

NetCDF Output with Custom Variables¶

Save predictions to a NetCDF file with custom variable names:

predictor -p control.dat -a WAVE.nc -g mesh.nc \
  -o predictions.nc \
  -v amplitude phase \
  --output-var tidal_prediction \
  --unit meters \
  --long_name "Tidal prediction" \
  -w M2 S2

Using a Time Template¶

Specify the time format for ASCII output:

predictor -p control.dat -a WAVE.nc -g mesh.nc \
  --time "CNES CALENDAR" \
  -s 2000/01/01 -f 2000/01/10 \
  -w M2 S2

Extrapolation and Mass Conservation¶

Enable extrapolation and mass conservation:

predictor -p control.dat -a WAVE.nc -g mesh.nc \
  --extrapolation-distance 1000 \
  --mass-conservation 1 \
  -w M2 S2

Environment Variables¶

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 predictor -p control.dat -a WAVE.nc -w M2 S2

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

Notes¶

Input Files:

Atlas files must follow the convention specified with -a.
If -p is a NetCDF file, it must contain latitude, longitude, and optionally time variables.

Output:

By default, predictions are saved in ASCII (predictions.dat) or NetCDF (predictions.nc).
Use -o to specify a custom output path.

Performance:

OpenMP parallelization is automatically activated for large datasets.
For best performance, sort waves by atlas type (or size) using -w.

Time Handling:

If -s and -f are not provided, predictions are made for the entire time range of the input files.
Use -i to specify a custom time increment (default: 1 hour).

Altimetry Mode:

Use --prediction-standard AVISO_LEGACY for compatibility with AVISO-FES standards.