# gridit-cdf v3.2.3

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

---

## Description

`gridit-cdf` converts **unstructured tidal atlases** into **structured grids**. It is designed to process tidal data and generate structured outputs for further analysis or visualization.

---

## Usage

```bash
gridit-cdf input [OPTIONS] wave1 [wave2 ...]
```

---

## Options

### **General Options**


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


---

### **Grid Definition Options**


| Option                             | Description                                                                                                                                                                                                           |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--mapping`                        | Define grid mapping as `[lonmin:dlon:lonmax; latmin:dlat:latmax]. `dlon` and `dlat` are optional. Supported units: `d` (degrees), `m` (minutes), `'` (arcminutes), `s` (seconds), `"` (arcseconds)`.                                                                                                                                                    |
| `-z`                               | Zone name or global resolution.                                                                                                                                                                                       |


---

### **Input/Output Options**


| Option    | Description                                                             |
| --------- | ----------------------------------------------------------------------- |
| `-c`      | NetCDF input atlas file name convention.                                |
| `-p`      | Directory containing the atlas files. Default: Current directory (`.`). |
| `-o`      | Output root convention. Default: `WAVE.generic`.                        |
| `-a`      | Frame index to process. Default: `-1` (last frame).                     |
| `--ascii` | Use ASCII input format.                                                 |


---

### **Variable and Wave Options**


| Option            | Description                                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `-v`              | Up to **6 variable names** for amplitudes and phases of `e`, `u`, and `v`. Default: Computed from discretization (as TUGO would). |
| `-g`              | Grid file followed by up to **3 gridded variable names** for `e`, `u`, and `v`.                                                   |
| `-discretisation` | Discretization pair for NetCDF input atlas. Used for default variable names if not explicitly provided.                           |
| `-`               | Separator between variable name list and wave names.                                                                              |


---

### **Mesh and Notebook Options**


| Option | Description    |
| ------ | -------------- |
| `-n`   | Notebook file. |
| `-m`   | Mesh file.     |


---

### **Advanced Options**


| Option          | Description                                         |
| --------------- | --------------------------------------------------- |
| `--persistence` | Number of iterations for growth of unmasked pixels. |
| `--subsampling` | Subsampling factor. Default: `1` (no subsampling).  |


---

## Examples

### **Basic Conversion with Global Zone**

Convert tidal atlas for wave `M2` using the `DNP1xLGP2` discretization:

```bash
gridit-cdf -z global -c WAVE.spectral.nc -o WAVE.FES2012 M2 -discretisation DNP1xLGP2
```

### **Custom Mapping and Variable**

Convert tidal atlas with a custom mapping and variable `WaveDragRow`:

```bash
gridit-cdf --mapping [:1m:,:1m:] -c WAVE.spectral.energy.nc -v WaveDragRow -o energy-RG M2
```

### **Specify Grid Resolution**

Convert tidal atlas with a resolution of `0.5` degrees:

```bash
gridit-cdf -dx 0.5 -dy 0.5 -c WAVE.spectral.nc -o WAVE.output M2 S2
```

### **Use ASCII Input**

Convert ASCII-formatted tidal atlas:

```bash
gridit-cdf --ascii -m mesh_file.nc -c WAVE.ascii -o WAVE.output M2
```

### **Process Multiple Waves**

Convert tidal atlas for multiple waves (`M2`, `S2`, `K1`):

```bash
gridit-cdf -z global -c WAVE.spectral.nc -o WAVE.FES2012 M2 S2 K1
```

### **Custom Grid Span**

Convert tidal atlas with a custom grid span:

```bash
gridit-cdf -xmin -10 -xmax 10 -ymin -5 -ymax 5 -c WAVE.spectral.nc -o WAVE.output M2
```

---

## Environment Variables

`gridit-cdf` does not explicitly rely on environment variables for its core functionality. However, if used in a parallelized environment (e.g., with OpenMP), standard environment variables like `OMP_NUM_THREADS` may influence performance.

---

## Notes

1. **Conventions for File Naming:**
  - `WAVE` is replaced by the **uppercase** wave name (e.g., `M2`).
  - `wave` is replaced by the **lowercase** wave name (e.g., `m2`).
  - `Wave` is replaced by the **capitalized** wave name (e.g., `M2`).
  - If the file exists without replacements, no substitution is performed.
2. **Variable Naming:**
  - If `-v` is not specified, variable names are computed from the discretization.
  - Up to **6 variables** can be specified for amplitudes and phases.
3. **Grid Files:**
  - If `-g` is used, up to **3 gridded variables** can be specified for `e`, `u`, and `v`.
4. **Subsampling:**
  - Use `--subsampling` to reduce the resolution of the output grid.
5. **Persistence:**
  - `--persistence` controls the iterative growth of unmasked pixels, useful for filling gaps in the data.

---

## See Also

- [`tides-converter`](https://www.comodo-ocean.fr/) (for additional tidal data processing tools)