# mgr-predictor v3.2.3

**Mercurial revision 5770:c90c3015e72d | 2026-05-22**

---

## Description

`mgr-predictor` predicts tides from a given **mgr (tidal constituents) file**, which contains tidal wave amplitudes and phase lags for one or multiple stations. The input file can be in **ASCII or NetCDF format**.

If start and end dates are provided, the tool:

- Predicts tides for the specified period.
- Optionally computes **spring/neap tide times** (if `--extrema` is enabled).

---

## Usage

```bash
mgr-predictor -m input_mgr_file -s start_date -f end_date -i time_incrementUNITS -w wave1 [wave2 ...] [OPTIONS] [station1 station2 ...]
```

---

## Options


| Option                   | Description                                                                                                                                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-h`, `--help`           | Display help and exit.                                                                                                                                                                            |
| `-m <file>`              | Path to the input **mgr file** (contains tidal wave amplitudes and phase lags).                                                                                                                   |
| `-s <date>`              | Start date for predictions. See [Date Formats](#date-formats9).                                                                                                                                    |
| `-f <date>`              | End date for predictions. See [Date Formats](#date-formats9).                                                                                                                                      |
| `-i <value><unit>`       | Time increment for predictions. **No space** between value and unit (e.g., `-i600s`). Supported units: `s` (seconds, default), `m` (minutes), `h` (hours), `d` (days). Default: `3600s` (1 hour). |
| `-w <wave1> [wave2 ...]` | List of tidal waves to predict.                                                                                                                                                                   |
| `--nodal=no`             | Disable nodal corrections.                                                                                                                                                                        |
| `--extrema`              | **Not fully functional.** Enable computation of extrema and spring/neap tide times.                                                                                                               |
| `-o <file>`              | **Not used.** Path to the ASCII output file. Default: `predictions.dat`.                                                                                                                          |
| `--format <format>`      | Specify the format of the input mgr file (e.g., `LEGOS_ASCII`).                                                                                                                                   |
| `--time <template>`      | Specify a time template for output (e.g., `CNES`).                                                                                                                                                |
| `--currents`             | Enable currents mode.                                                                                                                                                                             |
| `--modulator <string>`   | Specify a modulator string for advanced predictions (e.g., for discharge or regression-based adjustments).                                                                                        |


---

(date-formats9)=
## 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`

---

## Examples

### **Basic Prediction**

Predict tides for waves `M2` and `S2` from `2020/01/01` to `2020/01/10` with a 1-hour increment:

```bash
mgr-predictor -m input.mgr -s 2020/01/01 -f 2020/01/10 -i3600s -w M2 S2
```

### **Prediction for Specific Stations**

Predict tides for stations `station1` and `station2`:

```bash
mgr-predictor -m input.mgr -s 2020/01/01 -f 2020/01/10 -i3600s -w M2 S2 station1 station2
```

### **Custom Time Increment**

Predict tides with a 30-minute increment:

```bash
mgr-predictor -m input.mgr -s 2020/01/01 -f 2020/01/10 -i1800s -w M2 S2
```

### **Disable Nodal Corrections**

Predict tides without nodal corrections:

```bash
mgr-predictor -m input.mgr -s 2020/01/01 -f 2020/01/10 -i3600s --nodal=no -w M2 S2
```

### **Enable Spring/Neap Tide Computation**

Predict tides and compute spring/neap tide times:

```bash
mgr-predictor -m input.mgr -s 2020/01/01 -f 2020/01/10 -i3600s --extrema -w M2 S2
```

### **Specify Input File Format**

Predict tides using a specific mgr file format:

```bash
mgr-predictor -m input.mgr --format LEGOS_ASCII -s 2020/01/01 -f 2020/01/10 -i3600s -w M2 S2
```

### **Use a Modulator for Advanced Predictions**

Predict tides with a modulator (e.g., for discharge adjustments):

```bash
mgr-predictor -m input.mgr -s 2020/01/01 -f 2020/01/10 -i3600s \
  --modulator "dischargeFile=/path/to/discharge.gnu target=0 method=exponential Q0=200" \
  -w M2 S2
```

### **Enable Currents Mode**

Predict tides in currents mode:

```bash
mgr-predictor -m input.mgr -s 2020/01/01 -f 2020/01/10 -i3600s --currents -w M2 S2
```

---

## Environment Variables

`mgr-predictor` does not explicitly rely on environment variables for its core functionality. However, if used in a parallelized environment (e.g., with OpenMP), you may need to configure:


| Variable          | Description                                |
| ----------------- | ------------------------------------------ |
| `OMP_NUM_THREADS` | Number of threads for parallel processing. |


---

## Notes

1. **Input File Requirements:**
  - The input mgr file must contain **tidal wave amplitudes and phase lags** for the specified stations.
  - Supported formats: **ASCII (default: `LEGOS_ASCII`)** or **NetCDF**.
2. **Date Handling:**
  - Both **start (`-s`)** and **end (`-f`)** dates must be provided for predictions.
  - If no time increment (`-i`) is specified, the default is **3600 seconds (1 hour)**.
3. **Stations:**
  - If no stations are specified, predictions are computed for **all stations** in the input file.
  - To predict for specific stations, list them as arguments after the options.
4. **Output:**
  - By default, predictions are saved to `predictions.dat` (ASCII format).
  - The `--time` option allows customizing the time template for output files (e.g., `CNES`).
5. **Spring/Neap Tide Computation:**
  - The `--extrema` option is **not fully functional** but is intended to compute spring/neap tide times.
6. **Modulator:**
  - The `--modulator` option allows for advanced predictions, such as adjusting for river discharge or other external factors.

---

## See Also

- [CF Conventions for Time Coordinates](http://cfconventions.org/cf-conventions/cf-conventions.html#time-coordinate)
- [Legos MGR Format Documentation](https://www.legos.obs-mip.fr/)