# comodo-energy v3.2.3

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

---

## Description

`comodo-energy` calculates the **spectral energy budget** from structured-grid tidal atlases. It computes the following for each specified tidal wave:

- **Stokes' transport**
- **Energy flux**
- **Dissipation rate**

The tool interpolates elevation and speed components at bathymetry points to perform these calculations.

---

## Usage

```bash
comodo-energy bathymetry bathymetry_varname atlas_convention elevation_varname lon_speed_varname lat_speed_varname wave1 [wave2 ...]
```

### Arguments


| Argument             | Description                                                       |
| -------------------- | ----------------------------------------------------------------- |
| `bathymetry`         | Path to the bathymetry file.                                      |
| `bathymetry_varname` | Name of the bathymetry variable in the file.                      |
| `atlas_convention`   | Naming convention for atlas files. See [Convention](#convention33). |
| `elevation_varname`  | Variable name for elevation in the atlas.                         |
| `lon_speed_varname`  | Variable name for the longitudinal speed component.               |
| `lat_speed_varname`  | Variable name for the latitudinal speed component.                |
| `wave1 [wave2 ...]`  | List of tidal waves to analyze (e.g., `M2`, `S2`, `K1`).          |


---

(convention33)=
## Convention

The atlas file naming convention supports the following placeholders:

- `WAVE`: Replaced by the **uppercase** wave name (e.g., `M2`).
- `VAR`: Replaced by the **variable name** (e.g., `elevation`).
- `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.

---

## Options


| Option         | Description            |
| -------------- | ---------------------- |
| `-h`, `--help` | Display help and exit. |


---

## Examples

### **Basic Energy Budget Calculation**

Calculate the energy budget for waves `M2` and `S2`:

```bash
comodo-energy bathymetry.nc depth atlas_convention elevation u v M2 S2
```

### **Single Wave Analysis**

Analyze only the `M2` wave:

```bash
comodo-energy bathymetry.nc depth atlas_convention elevation u v M2
```

### **Multiple Waves with Custom Naming Convention**

Use a custom atlas naming convention (e.g., `tide_{WAVE}_{VAR}.nc`):

```bash
comodo-energy bathymetry.nc depth tide_{WAVE}_{VAR}.nc elevation u v M2 S2 K1
```

---

## Environment Variables

`comodo-energy` 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 comodo-energy bathymetry.nc depth atlas_convention elevation u v M2 S2
```

> **Note:** If running on a machine with high CPU load, limit threads to the number of **free CPUs** to avoid performance degradation.

---

## Notes

1. **Input Files:**
  - The bathymetry file must contain a valid grid and depth data.
  - Atlas files must follow the specified naming convention.
2. **Output:**
  - Results are saved in NetCDF files named `{wave}-energy.nc` for each wave.
  - A `total-energy.nc` file is generated with the total dissipation.
3. **Interpolation:**
  - Elevation and speed components are interpolated at bathymetry points.
4. **Mask Handling:**
  - Masked values (e.g., land points) are excluded from calculations.
5. **Performance:**
  - For large datasets, adjust `OMP_NUM_THREADS` to optimize performance.

---

## See Also

- [CF Conventions](http://cfconventions.org/cf-conventions/cf-conventions.html) (for NetCDF file standards)
- [OpenMP Documentation](https://www.openmp.org/) (for parallelization details)