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).
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¶

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).

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:

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

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

Testing Mode¶

Run in testing mode to verify internal calculations:

ellipse -t

Single Wave Analysis¶

Calculate ellipses for a single wave (M2):

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

Multiple Waves¶

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

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:

OMP_NUM_THREADS=4 ellipse grid.nc ssh "WAVE-VAR.nc" U V M2 S2

Notes¶

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.

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).

Performance:

For large grids, adjust OMP_NUM_THREADS to optimize performance based on available CPU cores.

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.

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.