peps-predictor v3.2.3¶

Mercurial revision 5770:c90c3015e72d | 2026-05-22

Description¶

peps-predictor is a tool designed to predict tides for PEPS images. It uses tidal atlases to generate predictions for specified waves at given locations or dates.

Usage¶

peps-predictor [OPTIONS]

Commands can be provided via:

Command-line arguments.
Standard input (default for -c and -o).
A command file (specified with -c).

Options¶

Option	Description
`--help`, `-h`	Display help and exit.
`-a <convention>`	Atlas file name convention. See Convention below.
`-g <file>`	Atlas mesh file. Only required if the mesh is not embedded in the atlas.
`-v <var1> [var2]`	Variable names for amplitude and phase. Default: `Ha Hg`.
`-w <wave1> [wave2 ...]`	List of waves to predict. For optimal speed, sort waves by atlas type (or size).
`-c <file>`	Path to the command file. Default: `-` (standard input).
`-o <file>`	Path to the output file. Default: `-` (standard output).
`-n <intervals>`	Number of interpolation intervals per tile side. Default: `10` (11x11 = 121 interpolations).
`--lonlat <coordinates>`	Specify coordinates as `[lon;lat]` (implies `-n 0`) or `[lonmin:lonmax;latmin:latmax]` (separator can be any non-numeric character).

Convention¶

The atlas file name convention supports 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.

Commands¶

Commands are separated by whitespace or _ and can be:

PEPS Tile Number:

Format: Optional T + 2 digits (UTM zone) + 3 letters (UTM latitude band, etc.).
Example: T31NCD or 31NCD.

Date:

Extended ISO 8601 format: yyyy/mm/dd,HH:MM:SS.SSS (separator can be any non-numeric character).
Basic ISO 8601 format: yyyymmddTHHMMSS.

Note: PEPS product names can be used directly as commands.

Options:

-o, -n, --lonlat: Can be specified as commands.
-h: Display help.

Examples¶

Predict Tides for a PEPS Tile¶

Predict tides for tile 31NCD using default settings:

peps-predictor -a "atlas_{WAVE}.nc" -w M2 S2 K1 -c commands.txt
echo "31NCD" | peps-predictor -a "atlas_{WAVE}.nc" -w M2 S2

Predict Tides for a Specific Date¶

Predict tides for 2026/08/06 12:00:00:

peps-predictor -a "atlas_{WAVE}.nc" -w M2 S2 -o prediction.json
echo "2026/08/06,12:00:00" | peps-predictor -a "atlas_{WAVE}.nc" -w M2 S2

Predict Tides for a Coordinate¶

Predict tides for a single coordinate [2.35;48.85]:

peps-predictor -a "atlas_{WAVE}.nc" -w M2 S2 --lonlat "[2.35;48.85]"

Predict Tides for a Bounding Box¶

Predict tides for a bounding box [lonmin:lonmax;latmin:latmax]:

peps-predictor -a "atlas_{WAVE}.nc" -w M2 S2 --lonlat "[2.0:3.0;48.0:49.0]"

Use a Custom Command File¶

Read commands from a file (commands.txt):

peps-predictor -a "atlas_{WAVE}.nc" -w M2 S2 -c commands.txt

Custom Variables and Output¶

Use custom amplitude/phase variables (amp, phase) and save output to output.json:

peps-predictor -a "atlas_{WAVE}.nc" -v amp phase -w M2 S2 -o output.json

Adjust Interpolation Resolution¶

Set the number of interpolation intervals per tile side to 20 (21x21 = 441 interpolations):

peps-predictor -a "atlas_{WAVE}.nc" -w M2 S2 -n 20

Combine Tile and Date Commands¶

Predict tides for a tile and a date in one command:

peps-predictor -a "atlas_{WAVE}.nc" -w M2 S2 -c - <<EOF
31NCD
2026/08/06,12:00:00
EOF

Environment Variables¶

peps-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 peps-predictor -a "atlas_{WAVE}.nc" -w M2 S2

Note: On a machine with high CPU load, limit threads to the number of free CPUs to avoid performance degradation.

Notes¶

Atlas File Convention:

Ensure the convention matches the naming pattern of your atlas files.
Placeholders (WAVE, wave, Wave) are case-sensitive.

Command Input:

Commands can be piped via standard input or read from a file.
PEPS tile names and ISO 8601 dates are valid commands.

Performance:

Sort waves by atlas type (or size) to optimize speed.
Use -n to adjust interpolation resolution (higher values increase accuracy but slow down computation).

Coordinate Systems:

--lonlat accepts both single coordinates and bounding boxes.
Separators in coordinates can be any non-numeric character (e.g., ,, ;, :, -).

Output:

Default output is in JSON format.
Dates in output follow the basic ISO 8601 format (e.g., 20260806T120000).