# turbulence v3.2.3

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

---

## Description

The `turbulence` program computes the **vertical diffusivity** associated with a current profile. It supports multiple diagnostic methods to analyze turbulence and diffusion coefficients based on input data.

---

## Usage

```bash
turbulence -f FILE [OPTIONS]
```

---

## Options


| Option         | Description                                                                                              |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| `-h`, `--help` | Print this help and exit.                                                                                |
| `-f <file>`    | Specify the input **LGD file** name. **Required.**                                                       |
| `-o <file>`    | Specify the **output file** name.                                                                        |
| `-d <n>`       | Specify the time step (`dt`) for explicit time stepping (in seconds).                                    |
| `-i <n>`       | Number of iterations to compute **TKE (Turbulent Kinetic Energy)**. Must be an integer.                  |
| `-t <n>`       | Specify the diagnostic method (integer):                                                                 |
|                | **`0`** : Use a specified/hard-coded **linear velocity profile**.                                        |
|                | **`1`** (default) : Read an **LGD file** and use the **Kepsilon** turbulence model.                      |
|                | **`2`** : Read an **LGD file** and use the **Gaspar scheme**.                                            |
|                | **`5`** : Read **real velocity time series** (not harmonic coefficients) and use the **Kepsilon** model. |


---

## Examples

### **Default Kepsilon Model**

Run with default settings (Kepsilon model) on an LGD file:

```bash
turbulence -f input.lgd -o output.lgd
```

### **Custom Time Step and Iterations**

Specify a time step of `10.0` seconds and `50` iterations:

```bash
turbulence -f input.lgd -o output.lgd -d 10.0 -i 50
```

### **Linear Velocity Profile**

Use a hard-coded linear velocity profile:

```bash
turbulence -f input.lgd -o output.lgd -t 0
```

### **Gaspar Scheme**

Use the Gaspar scheme for turbulence modeling:

```bash
turbulence -f input.lgd -o output.lgd -t 2
```

### **Real Velocity Time Series**

Process real velocity time series (not harmonic coefficients):

```bash
turbulence -f velocity_data.lgd -o output.lgd -t 5 -i 100 -d 5.0
```

---

## Environment Variables

This program does not explicitly rely on environment variables. However, it uses **OpenMP** for parallelization if compiled with OpenMP support. You can control parallel execution using standard OpenMP environment variables:


| Variable          | Description                                      |
| ----------------- | ------------------------------------------------ |
| `OMP_NUM_THREADS` | Number of threads to use for parallel execution. |


**Example:**

```bash
OMP_NUM_THREADS=4 turbulence -f input.lgd -o output.lgd
```

---

## Notes

1. **Input File Format:**
  - The input file (`-f`) must be in **LGD format** (a structured ASCII format for oceanographic data).
  - For `-t 0`, the program uses a hard-coded linear velocity profile.
  - For `-t 1` or `-t 2`, the program reads harmonic coefficients from the LGD file.
  - For `-t 5`, the program reads **real velocity time series** (not harmonic coefficients).
2. **Output:**
  - The output file (`-o`) contains computed turbulence parameters (e.g., diffusion coefficients, TKE, etc.).
  - If no output file is specified, results are saved with a default name.
3. **Performance:**
  - For large datasets, adjust `-i` (iterations) and `-d` (time step) to balance accuracy and computation time.
  - Use `OMP_NUM_THREADS` to optimize performance on multi-core systems.
4. **Diagnostic Methods:**
  - **Kepsilon (`-t 1` or `-t 5`)**: A two-equation turbulence model for computing turbulent kinetic energy and dissipation rate.
  - **Gaspar (`-t 2`)**: An alternative turbulence scheme for specific applications.

---

## See Also

- [LGD File Format Documentation](https://www.comodo-ocean.fr/) (for input/output file specifications)
- [Kepsilon Turbulence Model](https://en.wikipedia.org/wiki/K-epsilon_turbulence_model)
- [Gaspar et al. (1990) Turbulence Scheme](https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/JC095iC03p03225)