# adcp v3.2.3

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

---

## Description

`adcp` is a tool designed to **detide comodo-compliant NetCDF data with many holes** (e.g., missing or masked values) and produce **tidal atlases**. It 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
adcp file1 [file2 ...] [OPTIONS] -d wave1 [wave2 ...]
```

---

## Options

### **General Options**


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


---

### **Input/Output Options**


| Option                   | Description                                                                                                                      |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `-l <file>`              | Path to a file containing a list of input files (overrides command-line file list).                                              |
| `-v <var1> [var2 ...]`   | List of variables to detide (e.g., `ssh`, `tem`, `sal`, `XE`).                                                                   |
| `-g <file>`              | Path to the grid file. Required if coordinates are missing in input files and you want to produce atlases or use control points. |
| `-d <wave1> [wave2 ...]` | List of tidal waves to analyze (e.g., `Q1`, `O1`, `P1`, `K1`, `N2`, `M2`, `S2`, `K2`, `M4`, `MS4`).                              |
| `-p <dir>`               | Output directory. **Recommended:** Use a different hard drive for detiding to improve performance.                               |


---

### **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]`). |
| `--nodal=no`                       | Disable nodal corrections.                                                                                          |
| `--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).               |
| `--save_psd`                       | Save the power spectral density in `psd_r1_c.py`.                                                                   |


---

### **Date Options**


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


---

(date-formats6)=
## 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

You can specify a list of tidal waves to analyze. A good starting point is:

```
Q1 O1 P1 K1 N2 M2 S2 K2 M4 MS4
```

---

## Examples

### **Basic Detiding**

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

```bash
adcp -s 15/12/2008 -f 28/02/2009 \
  -l files.list \
  -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
adcp -s 02/01/2000 \
  -v XE \
  -a \
  -d Q1 O1 P1 K1 N2 M2 S2 K2 M4 MS4
```

### **Only Generate Atlases**

Generate atlases without detiding:

```bash
adcp -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
adcp -l files.list \
  --load-atlases \
  -v elevation \
  -d M2 S2
```

### **Band-Cut Filtering**

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

```bash
adcp -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
adcp -l files.list \
  -v ssh \
  --averaging-interval "[-3600:0]" \
  -d M2 S2
```

### **Save Power Spectral Density**

Save the power spectral density for further analysis:

```bash
adcp -l files.list \
  -v ssh \
  --save_psd \
  -d M2 S2 K1
```

---

## Environment Variables

`adcp` 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 adcp -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**.
  - Suitable for datasets with **many holes or missing values** (e.g., ADCP data).
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. **Simultaneous Frames:**
  - Use `--take-first` or `--take-last` to handle simultaneous time frames.
5. **Incompatible Options:**
  - `--load-atlases` is incompatible with both `-a` and `--only-atlases`.

---

## See Also

- [CF Conventions for Time Coordinates](http://cfconventions.org/cf-conventions/cf-conventions.html#time-coordinate)
- [comodo-ocean.fr](https://www.comodo-ocean.fr/) (for additional tools and resources)