# comodo-detidor v3.2.3

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

---

## Description

`comodo-detidor` is a tool designed to **detide** comodo-compliant NetCDF outputs and produce **tidal atlases**. It is used by **CTOH** (Centre de Topographie des Océans et de l'Hydrosphère).

The tool performs **spectral analysis** on a given list of tidal waves and generates:

- Detided output files.
- Tidal atlases (amplitude and phase maps for each tidal constituent).

> **Note:** The time variable in input files **must comply with the [CF conventions](http://cfconventions.org/cf-conventions/cf-conventions.html#time-coordinate)**.

---

## Usage

```bash
comodo-detidor file1 [file2 ...] [OPTIONS] -d wave1 [wave2 ...]
```

---

## Options

### **General Options**


| Option                      | Description                                                                                             |
| --------------------------- | ------------------------------------------------------------------------------------------------------- |
| `--help`, `-h`              | Display help and exit.                                                                                  |
| `--nodal=no`                | Disable nodal corrections.                                                                              |
| `--time-variable <name>`    | Alternative name for the time variable (default: `time`).                                               |
| `--time-attributes <attrs>` | Alternative time attributes (e.g., `"seconds since YYYY/MM/DD"` or `"days since YYYY/MM/DD HH:MM:SS"`). |


---

### **Input/Output Options**


| Option                   | Description                                                                                                         |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `-l <file>`              | Path to a file containing a list of input files (overrides command-line file list).                                 |
| `-g <file>`              | Path to the grid file (required if coordinates are missing in input files and atlases/control points are used).     |
| `-p <dir>`               | Output directory. **Recommended:** Use a different hard drive for detiding to improve performance.                  |
| `-v <var1> [var2 ...]`   | List of variables to detide (e.g., `ssh`, `tem`, `sal`, `XE`).                                                      |
| `-d <wave1> [wave2 ...]` | List of tidal waves to analyze. See [Wave list and Spectra](#wave-lists-spectra2). |
| `--spectrum <name>`       | Specifies the detiding spectrum by name. See [Wave list and Spectra](#wave-lists-spectra2). |


---

### **Atlas Options**


| Option           | Description                                                                                                                                  |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `-a`             | Produce tidal atlases.                                                                                                                       |
| `--only-atlases` | Produce **only** atlases (no detiding). Implies `-a`.                                                                                        |
| `--load-atlases` | Load existing atlases (no analysis). Currently disables `--control`.                                                                         |
| `-1`             | Store all atlases in **one file per variable**. ⚠️ **Warning:** Files produced with this option **cannot** be used with `comodo-admittance`. |


---

### **Analysis Options**


| Option                             | Description                                                                                                                                                                           |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-c <file>`, `--control <file>`    | Path to a file containing control points (ASCII format: number of points followed by `longitude latitude [layer]`).                                                                   |
| `--drying`                         | Account for slight variations in the mask at each time frame. Useful for cases with dynamically changing land-sea masks.                                                              |
| `--take-first`                     | If time frames are simultaneous, use the **first** one.                                                                                                                               |
| `--take-last`                      | If time frames are simultaneous, use the **last** one.                                                                                                                                |
| `--band-cut <f1> <f2>`             | Band-cut filter: specify two frequencies (in deg/h) to exclude waves outside this range.                                                                                              |
| `--averaging <time>`               | **Deprecated.** Use `--averaging-interval` instead.                                                                                                                                   |
| `--averaging-interval <[min:max]>` | Time integration range (in seconds) for time-averaged data (e.g., `"[-3600:0]"` for hourly averages).                                                                                 |
| `--altimetry`                      | Special mode for altimetry data. Implies `--load-atlases -v elevation`. Do **not** prepend `detided_` to output variable names. Also copies `Pa` and mesh variables without detiding. |


---

### **Date Options**


| Option      | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| `-s <date>` | Start date for analysis. See [Date Formats](#date-formats7). |
| `-f <date>` | End date for analysis. See [Date Formats](#date-formats7).   |
| `-o <date>` | Default date origin. See [Date Formats](#date-formats7).     |


---

### **Miscellaneous Options**


| Option | Description                                                                           |
| ------ | ------------------------------------------------------------------------------------- |
| `-t`   | Display separation tables for all harmonics and list of files within time boundaries. |


---

(date-formats7)=
## 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-lists-spectra2)=
## Wave Lists and Spectra

You can specify:

1. **Individual waves**  (run [showarg](../infos/showarg.md) to see the full list of available waves):
  - A good start is Q1 O1 P1 K1 N2 M2 S2 K2 M4 MS4. 
2. **Predefined spectra**  (see [showarg](../infos/showarg.md) <spectra> to get associated waves and the duration needed for wave separation):
  - `ESTUARINE`
  - `ESTUARINE-HF`
  - `COMODO`
  - `COASTAL`
  - `COASTAL-HF`
  - `SHELF`
  - `SHELF-HF`
  - `DEEP`
  - `DEEP-HF`
  - `REDUCED`
  - `CURRENTS-HF`
  - `FES2022c`
  - `AVISO-FES-SP`
  - `AVISO-FES-ADMITTANCE`
  - `AVISO-FES-LP`
  - `AVISO-FES-LP-PROXY`

---

## Examples

### **Basic Detiding**

Detide variables `ssh`, `tem`, and `sal` for waves `M2`, `S2`, `N2`, `K2`:

```bash
comodo-detidor -s 15/12/2008 -f 28/02/2009 \
  -l files.list -control control.dat \
  -g grille_domconcat.nc \
  -v ssh tem sal \
  -a -d M2 S2 N2 K2
```

### **Detiding with Custom Waves**

Detide variable `XE` for a custom set of waves:

```bash
comodo-detidor -s 02/01/2000 \
  -control control.dat \
  -v XE \
  -a \
  -d K1 O1 Q1 M2 S2 N2 K2 L2 2N2 2NS2 2SM2 2SN2 MK3 M4 SN4 MS4 3MS4 MN4 S4 M6 2MS6
```

### **Only Generate Atlases**

Generate atlases without detiding:

```bash
comodo-detidor -l files.list \
  -g grille_domconcat.nc \
  -v ssh \
  --only-atlases \
  -d M2 S2 N2 K2
```

### **Load Existing Atlases**

Load precomputed atlases for detiding:

```bash
comodo-detidor -l files.list \
  --load-atlases \
  -v elevation \
  -d M2 S2
```

### **Altimetry Mode**

Process altimetry data (implies `--load-atlases -v elevation`):

```bash
comodo-detidor -l files.list \
  --altimetry \
  -d M2 S2 K1
```

### **Band-Cut Filtering**

Exclude waves outside the frequency range `[5, 20]` deg/h:

```bash
comodo-detidor -l files.list \
  -v ssh \
  --band-cut 5 20 \
  -d M2 S2 K1 O1
```

### **Time Averaging**

Specify a time-averaging interval of `[-3600:0]` (1 hour backward):

```bash
comodo-detidor -l files.list \
  -v ssh \
  --averaging-interval "[-3600:0]" \
  -d M2 S2
```

### **Using a Predefined Spectrum**

Use the `COMODO` spectrum:

```bash
comodo-detidor -l files.list \
  -v ssh \
  -a \
  -d COMODO
```

---

## Environment Variables

`comodo-detidor` 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-detidor -l files.list -v ssh -d M2 S2
```

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

---

## Notes

1. **Input Files:**
  - Must be **comodo-compliant NetCDF** files.
  - The time variable must follow **CF conventions**.
2. **Output:**
  - Detided files are saved in the specified output directory (`-p`).
  - Atlases are generated if `-a` or `--only-atlases` is used.
3. **Performance:**
  - For large datasets, use `-p` to output to a **different hard drive** to avoid I/O bottlenecks.
  - Adjust `OMP_NUM_THREADS` based on available CPU resources.
4. **Mask Handling:**
  - Use `--drying` for cases where the land-sea mask varies slightly between frames.
  - For more complex masking (e.g., many points masked), consider using `adcp` instead.
5. **Simultaneous Frames:**
  - Use `--take-first` or `--take-last` to handle simultaneous time frames.

---

## See Also

- [CF Conventions for Time Coordinates](http://cfconventions.org/cf-conventions/cf-conventions.html#time-coordinate)
- [`showarg`](../infos/showarg.md) (for listing available waves)
- [`comodo-admittance`](../tidal-processing/comodo-admittance) (for further analysis)