# metocean-predictor v3.2.3 **Mercurial revision 5770:c90c3015e72d | 2026-05-22** --- ## Description `metocean-predictor` is a tool designed to **predict tidal currents and elevations** based on harmonic analysis. It uses tidal atlases to compute: - **Maximum current** (if 4 or 6 variables are provided: `U_amplitude`, `U_phase`, `[V_amplitude, V_phase, [W_amplitude, W_phase]]`). - **Minimum and maximum elevations** (if 2 variables are provided: `amplitude` and `phase`). --- ## Usage ```bash metocean-predictor -a atlas_convention -v U_amplitude U_phase [V_amplitude V_phase [W_amplitude W_phase]] -w wave1 [wave2 ...] ``` --- ## Options | Option | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `-h`, `--help` | Display help and exit. | | `-a ` | Atlas file name convention. See [Convention](#convention36) below. | | `-s ` | Start date for predictions. **Default:** `2000`. | | `-f ` | End date for predictions. **Default:** `2018` (inclusive). | | `-i ` | Time increment for predictions. **Default:** `1800s` (30 minutes). **Units:** `s` (seconds), `m` (minutes), `h` (hours), `d` (days). | | `-v [...]` | List of variable names for amplitude and phase (up to 3 pairs). | | `-o ` | Output file name. **Default:** `max.nc`. | | `-w [wave2 ...]` | List of tidal waves to predict. | --- (convention36)= ## Convention The atlas file name convention supports dynamic 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` → `M2`, `K1` → `K1`). > **Note:** If the file exists without any replacements, no substitution is performed. --- ## 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 List You can specify any tidal wave supported by the tool. Use `showarg` (from the comodo toolkit) to list available waves. --- ## Examples ### **Predict Maximum Current (4 Variables)** Predict maximum current for waves `M2` and `S2` using amplitude and phase variables for `U` and `V` components: ```bash metocean-predictor \ -a "tide_WAVE_amplitude_phase.nc" \ -v U_amplitude U_phase V_amplitude V_phase \ -w M2 S2 \ -s 2000/01/01 \ -f 2000/01/02 \ -i 3600s \ -o max_current.nc ``` ### **Predict Maximum Current (6 Variables)** Predict maximum current for waves `M2`, `S2`, and `K1` using amplitude and phase variables for `U`, `V`, and `W` components: ```bash metocean-predictor \ -a "tide_Wave_amplitude_phase.nc" \ -v U_amplitude U_phase V_amplitude V_phase W_amplitude W_phase \ -w M2 S2 K1 \ -s 2000/01/01 \ -f 2000/01/02 \ -i 1800s \ -o max_current_3d.nc ``` ### **Predict Minimum and Maximum Elevations (2 Variables)** Predict minimum and maximum elevations for waves `M2` and `S2`: ```bash metocean-predictor \ -a "tide_WAVE_elevation.nc" \ -v elevation_amplitude elevation_phase \ -w M2 S2 \ -s 2000/01/01 \ -f 2000/01/02 \ -i 3600s \ -o elevation_extremes.nc ``` ### **Use Default Dates and Increment** Predict maximum current for waves `M2` and `K1` using default dates (`2000` to `2018`) and time increment (`1800s`): ```bash metocean-predictor \ -a "tide_WAVE.nc" \ -v U_amplitude U_phase V_amplitude V_phase \ -w M2 K1 \ -o default_prediction.nc ``` ### **Custom Time Increment** Predict elevations with a time increment of `1 hour`: ```bash metocean-predictor \ -a "tide_WAVE.nc" \ -v elevation_amplitude elevation_phase \ -w M2 S2 \ -s 2000/01/01 \ -f 2000/01/03 \ -i 1h \ -o hourly_elevation.nc ``` --- ## Environment Variables `metocean-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 metocean-predictor -a "tide_WAVE.nc" -v U_amplitude U_phase -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 Requirements:** - Atlas files must follow the specified [convention](#convention36). - Variables must be provided in **pairs** (amplitude and phase) for each component (e.g., `U_amplitude` and `U_phase`). - The number of variables must be **2, 4, or 6** (for 1, 2, or 3 components, respectively). 2. **Output:** - The output file (`-o`) contains: - `max`: Maximum values (current speed or elevation). - `maxdir`: Direction of maximum current (if 4 or 6 variables are provided). - `min`: Minimum values (if 2 variables are provided). 3. **Performance:** - For large datasets, adjust `OMP_NUM_THREADS` to match the number of available CPU cores. - The tool automatically parallelizes computations using OpenMP. 4. **Time Handling:** - The time increment (`-i`) must be specified with a unit (`s`, `m`, `h`, or `d`). - The start (`-s`) and end (`-f`) dates are **inclusive**. --- ## 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 tidal waves) - [OpenMP Documentation](https://www.openmp.org/) (for environment variables and parallelization)