# 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

```bash
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](#convention39) 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](#wave-lists-spectra3)                                   |
| `--spectrum <spectrum>`  | Use a predefined spectrum. See [Wave Lists and Spectra](#wave-lists-spectra3). |
| `-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](#date-formats10).                                                                                |
| `-f <date>`        | End date for predictions. See [Date Formats](#date-formats10).                                                                                  |
| `-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-formats10)=
## 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-spectra3)=
## Wave Lists and Spectra

You can specify:

1. **Individual waves** (e.g., `M2`, `S2`, `K1`). Run `showarg` to see the full list of available waves.
2. **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`

---

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

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

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

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

### **Altimetry-Compatible Predictions**

Generate predictions compatible with `AVISO-FES-2.9.5`:

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

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

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

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

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

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

1. **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.
2. **Output:**
  - By default, predictions are saved in **ASCII** (`predictions.dat`) or **NetCDF** (`predictions.nc`).
  - Use `-o` to specify a custom output path.
3. **Performance:**
  - OpenMP parallelization is **automatically activated** for large datasets.
  - For best performance, sort waves by atlas type (or size) using `-w`.
4. **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).
5. **Altimetry Mode:**
  - Use `--prediction-standard AVISO_LEGACY` for compatibility with AVISO-FES standards.

---

## See Also

- [CF Conventions for Time Coordinates](http://cfconventions.org/cf-conventions/cf-conventions.html#time-coordinate)
- [`showarg`](https://www.comodo-ocean.fr/) (for listing available waves)
- [`comodo-calculator`](https://www.comodo-ocean.fr/) (for converting ASCII files to NetCDF)