# 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

```bash
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](#convention38) 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). |


---

(convention38)=
## 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:

1. **PEPS Tile Number**:
  - Format: Optional `T` + 2 digits (UTM zone) + 3 letters (UTM latitude band, etc.).
  - Example: `T31NCD` or `31NCD`.
2. **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.
3. **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:

```bash
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`:

```bash
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]`:

```bash
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]`:

```bash
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`):

```bash
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`:

```bash
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):

```bash
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:

```bash
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:**

```bash
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

1. **Atlas File Convention**:
  - Ensure the convention matches the naming pattern of your atlas files.
  - Placeholders (`WAVE`, `wave`, `Wave`) are case-sensitive.
2. **Command Input**:
  - Commands can be piped via standard input or read from a file.
  - PEPS tile names and ISO 8601 dates are valid commands.
3. **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).
4. **Coordinate Systems**:
  - `--lonlat` accepts both single coordinates and bounding boxes.
  - Separators in coordinates can be any non-numeric character (e.g., `,`, `;`, `:`, `-`).
5. **Output**:
  - Default output is in JSON format.
  - Dates in output follow the **basic ISO 8601 format** (e.g., `20260806T120000`).

---

## See Also

- [ISO 8601 Date Format](https://en.wikipedia.org/wiki/ISO_8601)
- [OpenMP Documentation](https://www.openmp.org/)
- [PEPS Products](https://peps.cnes.fr/)