# ellipse v3.2.3

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

---

## Description

`ellipse` calculates **current ellipses** for tidal analysis. It takes a grid file, a gridded variable, an atlas convention, and the names of longitudinal and latitudinal speed components, then computes ellipses for each specified tidal wave.

- The **grid file** defines the spatial domain.
- The **gridded variable** is used to interpolate speed components (e.g., bathymetry, temperature).
- The **atlas convention** defines the naming pattern for atlas files (see [Convention](#convention35)).
- The **longitudinal and latitudinal speed components** are the variables representing the velocity fields.
- The **waves** are the tidal constituents to analyze (e.g., `M2`, `S2`, `K1`).

For each wave, the tool calculates and saves the tidal current ellipses, including their amplitude, phase, direction, and polarization.

---

## Usage

```bash
ellipse grid_file gridded_varname atlas_convention lon_speed_varname lat_speed_varname wave1 [wave2 ...]
```

---

## Options


| Option         | Description                                                         |
| -------------- | ------------------------------------------------------------------- |
| `-h`, `--help` | Display help and exit.                                              |
| `-t`           | Run in **testing mode** (performs internal calculations and exits). |


---

(convention35)=
## Convention

The **atlas file name convention** supports dynamic placeholders for wave names and variables:


| Placeholder | Replacement                         |
| ----------- | ----------------------------------- |
| `WAVE`      | Uppercase wave name (e.g., `M2`).   |
| `VAR`       | Name of the variable.               |
| `wave`      | Lowercase wave name (e.g., `m2`).   |
| `Wave`      | Capitalized wave name (e.g., `M2`). |


> **Note:** If the file exists without any replacements, no substitution is performed.

---

## Examples

### **Basic Usage**

Calculate ellipses for waves `M2` and `S2` using a grid file, a gridded variable, and speed components `U` and `V`:

```bash
ellipse grid.nc bathymetry "WAVE-VAR.nc" U V M2 S2
```

### **Using a Custom Atlas Convention**

Use a custom naming convention for atlas files (e.g., `tidal_WAVE_VAR.nc`):

```bash
ellipse grid.nc temp "tidal_WAVE_VAR.nc" lon_vel lat_vel K1 O1
```

### **Testing Mode**

Run in testing mode to verify internal calculations:

```bash
ellipse -t
```

### **Single Wave Analysis**

Calculate ellipses for a single wave (`M2`):

```bash
ellipse grid.nc ssh "atlas_WAVE.nc" u v M2
```

### **Multiple Waves**

Calculate ellipses for multiple waves (`M2`, `S2`, `K1`, `O1`):

```bash
ellipse grid.nc ssh "atlas_WAVE.nc" u v M2 S2 K1 O1
```

---

## Environment Variables

`ellipse` uses **OpenMP** for parallelization. Key environment variables to control threading:


| Variable          | Description                                         |
| ----------------- | --------------------------------------------------- |
| `OMP_NUM_THREADS` | Number of threads to use for parallel computations. |
| `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=4 ellipse grid.nc ssh "WAVE-VAR.nc" U V M2 S2
```

---

## Notes

1. **Input Files:**
  - The **grid file** must be a valid NetCDF file containing the grid definition.
  - The **gridded variable** must exist in the grid file or be interpolatable from it.
  - The **speed components** (`lon_speed_varname`, `lat_speed_varname`) must be present in the atlas files.
2. **Output:**
  - For each wave, a NetCDF file named `{wave}-ellipses.nc` is created, containing:
    - **Ellipse parameters**: `M` (maximum velocity), `a` (phase of maximum), `d` (direction of maximum), `m` (minimum velocity), `p` (clockwise polarization).
    - **Rotation data** (if applicable): `c` (cosine of grid rotation), `s` (sine of grid rotation).
    - **Rotated velocity components**: `E` (eastward), `N` (northward).
3. **Performance:**
  - For large grids, adjust `OMP_NUM_THREADS` to optimize performance based on available CPU cores.
4. **File Naming:**
  - The **atlas convention** must match the naming pattern of your atlas files. If the convention includes placeholders (e.g., `WAVE`), they will be replaced by the actual wave names.
5. **Testing Mode:**
  - The `-t` option runs internal tests and prints ellipse parameters for a set of synthetic inputs. It does not process actual data files.

---

## See Also

- [NetCDF CF Conventions](http://cfconventions.org/)
- [OpenMP Documentation](https://www.openmp.org/)
- [`comodo-detidor`](https://www.comodo-ocean.fr/) (for tidal analysis and detiding)