# **Model inputs and settings :**

## **Usage**

```bash
tugo [OPTIONS] configuration_file.intg
```

## **Configuration file**

A T-UGOm configuration file is an ASCII file  ([Default template file](./default.md)) and is made of several sections where parameters (numerical values, files path, etc..) are set through a keyword identifier. To some extents, it can be compared to a concatenation of Fortran notebooks.

This file can be generated through T-UGOm-GUI, an visulatisation tool provided with the model that will help you navigate through the available options. Otherwise the ASCII file can be directly modify using the documentation below.

> **Note**: at the begining of each run, T-UGOm generated the configuration file used for the run, so you can achive it with the simulation.

**List of sections:**

| **Section** | **Description** |
|-------------|----------------|
| [2D](2D.md) | 2D hydrodynamic model settings, including discretization, time integration, and wave equation form. |
| [3D](3D.md) | 3D hydrodynamic model settings, including vertical discretization, time stepping, and tracer integration. |
| [analysis](analysis.md) | Settings for harmonic analysis, including tidal spectrum, admittance, and spectral solver configurations. |
| [atmosphere](atmosphere.md) | Atmospheric forcing, including wind, pressure, and temperature settings. |
| [boundaries](boundaries.md) | Defines open boundary conditions, including OBC types, relaxation zones, and river inputs. |
| [constraints](constraints.md) | Constraints for elevation, nudging, and relaxation parameters. |
| [diagnostics](diagnostics.md) | Settings for runtime diagnostics, including statistics, collection intervals, and output conventions. |
| [dissipation2D](dissipation2D.md) | 2D dissipation parameters, including bottom friction, horizontal viscosity, and Smagorinsky coefficients. |
| [dissipation3D](dissipation3D.md) | 3D dissipation parameters, including vertical diffusion and turbulence closure. |
| [drifters2D](drifters2D.md) | Settings for 2D drifter simulations, including input files and time intervals. |
| [energy_budget](energy_budget.md) | Energy budget calculations, including harmonic and time-step computations. |
| [fe_archive](fe_archive.md) | Finite element archive settings, including output formats, intervals, and precision. |
| [general](general.md) | General model settings, including time steps, mesh files, and solver configurations. |
| [miscellaneous](miscellaneous.md) | Miscellaneous settings, including stability checks, subcycling, and smoothing options. |
| [ocean_waves](ocean_waves.md) | Ocean wave forcing, including parameterizations, drag, and friction settings. |
| [physics](physics.md) | Physical constants and modes, including gravity, Coriolis, and Love numbers. |
| [samples](samples.md) | Sampling settings for model outputs, including intervals and file conventions. |
| [sea_ice](sea_ice.md) | Sea ice dynamics, including friction, elasticity, and concentration thresholds. |
| [sediment](sediment.md) | Sediment and fluid mud dynamics, including friction coefficients and polygons. |
| [stability_control](stability_control.md) | Stability control parameters, including CFL ratios, subcycling, and instability checks. |
| [stream2D](stream2D.md) | 2D stream function calculations and intervals. |
| [structured_archive](structured_archive.md) | Structured grid archives, including zones, conventions, and output flags. |
| [tides](tides.md) | Tidal forcing, including astronomical potential, LSA, and boundary conditions. |
| [topography_geodesy](topography_geodesy.md) | Topography and geodesy settings, including bathymetry, slopes, and depth offsets. |
| [tracers2D](tracers2D.md) | 2D tracer simulations, including diffusion, advection, and input files. |
| [tracers3D](tracers3D.md) | 3D tracer simulations, including vertical discretization and diffusion. |

## **Runtime options**

In some cases, such as sensitivity studies, it is more convenient to keep a given control file and to change some parameter setting through a T-UGOm optional parameter.

> **WARNING:** Command-line options **override** settings in the input configuration file(s).

A very powerful option is the `-delta` one, which allows to give one or several additional control files to the run, usually to modify a limited set of parameters. For instance, it is very convenient to keep a unique base control file to be used on different computational platforms where paths need to be different. Parameters values will be taken in priority in the last control files where they appear.

### **General Options**


| Option          | Description                                                               |
| --------------- | ------------------------------------------------------------------------- |
| `-h`, `--help`  | Display help and exit.                                                    |
| `--debug`       | Save partitions (only relevant in parallel mode).                         |
| `-old`          | Use if the main configuration file is in the **old format**.              |
| `-delta <file>` | Path to a **delta configuration file** (can be specified multiple times). |


---

### **Input/Output Options**


| Option                         | Description                                             |
| ------------------------------ | ------------------------------------------------------- |
| `--output-path <dir>`          | Path to the **output directory**.                       |
| `--archive-start <days>`       | Start time for **FE archive** (in days).                |
| `--archive-interval <seconds>` | Time interval for **FE archive** (in seconds).          |
| `--meteo-path <dir>`           | Path to the **atmospheric forcing directory**.          |
| `--restart <file>`             | Path to the **restart file** for hot-start simulations. |
| `--separate-mesh <file>`       | Specify a **separate mesh file**.                       |


---

### **Time Control Options**


| Option                                    | Description                                                           |
| ----------------------------------------- | --------------------------------------------------------------------- |
| `--start <time>`                          | **Time origin** in format `YYYY-MM-DD HH:MI:SS` (enclosed in quotes). |
| `--duration <hours>`                      | **Run duration** in hours.                                            |
| `--max-walltime <seconds>`                | **Maximum walltime** for the simulation (in seconds).                 |
| `--time-steps <dt> [sub_dt1 sub_dt2 ...]` | **Main time step** and optional sub-time steps (in seconds).          |


---

### **Model Configuration Options**


| Option                | Description                                                                                    |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| `--hydrostatic=true`  | Force **hydrostatic mode**.                                                                    |
| `--hydrostatic=false` | Force **non-hydrostatic mode**.                                                                |
| `--theta <value>`     | **Semi-implicit factor** (0 = explicit, 1 = fully implicit, default = 0.75).                   |
| `--tau0 <value>`      | **Relaxation coefficient** for the continuity equation in the generalized wave equation.       |
| `--drying=true`       | Enable **wetting/drying mode**.                                                                |
| `--drying=false`      | Disable **wetting/drying mode**.                                                               |
| `--fluid-mud=true`    | Enable **fluid mud friction**.                                                                 |
| `--fluid-mud=false`   | Disable **fluid mud friction**.                                                                |
| `--nlayersmax <n>`    | **Number of layers** for 3D simulations.                                                       |
| `--nreduced <n>`      | **Number of modes** to calculate in 3D (requires `BAROCLINIC-REDUCED` or `BAROCLINIC-NORMAL`). |
| `--mindepth <value>`  | **Minimum depth** (positive below vertical reference level).                                   |


---

### **Topography and Bathymetry Options**


| Option                                              | Description                                                        |
| --------------------------------------------------- | ------------------------------------------------------------------ |
| `--topo <file>`                                     | Input **bottom topography filename**.                              |
| `--slope <file>`                                    | Input **bottom slope filename**.                                   |
| `--variable-depth-offset "polygons=xxx values=xxx"` | **Polygon-wise depth offset** (specify polygons and values files). |
| `--rugosity-values <file>`                          | **Rugosity values file** (polygon-wise setting).                   |
| `--depth-scaling-factor <value>`                    | **Depth scaling factor**.                                          |


---

### **Dissipation and Friction Options**


| Option                  | Description                                          |
| ----------------------- | ---------------------------------------------------- |
| `--smagorinsky <value>` | **Default Smagorinsky coefficient** (dimensionless). |
| `--default-Cd <value>`  | **Default bottom friction coefficient**.             |
| `--default-Z0 <value>`  | **Default bottom roughness length**.                 |
| `--default-IWD <value>` | **Default internal wave drag coefficient**.          |


---

### **Tidal and Harmonic Analysis Options**


| Option                         | Description                                 |
| ------------------------------ | ------------------------------------------- |
| `--spectrum <file>`            | **Tidal spectrum file**.                    |
| `--loading=true`               | Enable **Load Self-Attraction (LSA)**.      |
| `--loading=false`              | Disable **LSA**.                            |
| `--prior <file>`               | **Prior solution file** for tidal analysis. |
| `--tidal-obcs <file>`          | **Tidal open boundary conditions file**.    |
| `--nudging-relaxation <value>` | **Nudging relaxation timescale**.           |


---

### **Boundary and River Options**


| Option               | Description                       |
| -------------------- | --------------------------------- |
| `--rivers <file>`    | **Rivers input settings file**.   |
| `--obcs-mode <mode>` | **Open boundary condition mode**. |


---

### **Ice and Sea Ice Options**


| Option                           | Description                          |
| -------------------------------- | ------------------------------------ |
| `--seaice-concentration <value>` | **Sea ice concentration**.           |
| `--seaice-threshold <value>`     | **Sea ice concentration threshold**. |
| `--seaice-confinement <value>`   | **Sea ice confinement modulation**.  |


---

### **Parallel and Performance Options**


| Option              | Description                                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `--master <mode>`   | **Unpartitioned information processing mode** (`COLLECTIVE`, `NODE`, or `CLUSTER` for MPI). **NODE** is usually optimal for clusters. |
| `--tmpdir <mode>`   | **Temporary directory** for model I/O in cluster mode (`AUTO`, `NONE`, or `<dirname>`).                                               |
| `--nthreads <n>`    | **Number of OpenMP threads** to use.                                                                                                  |
| `--mindzdt <value>` | **Minimum elevation time derivative** to trigger instability flag (typically `O(1.e-04)`).                                            |
| `--max-precision`   | **Maximum precision** for model output.                                                                                               |

---

## Environment Variables


| Variable | Description |
| -------- | ----------- |
| `TMPDIR` | **Temporary directory** for forcing files. If set, copies of forcing files are progressively made and deleted as needed. **Recommended:** Set to a **fast drive** (e.g., SSD) if forcing files are on a slow drive (e.g., NFS). |


> **Note:**
> - If `TMPDIR` is **not set**, you **should** set it manually to a fast drive if forcing files are on a slow drive.
> - If forcing files are **only accessible via SSH**, `TMPDIR` **must** be set to a **local drive** (as `scp` is used for copying).

---


```{toctree}
:maxdepth: 1
default
2D
3D
analysis
atmosphere
boundaries
constraints
diagnostics
dissipation2D
dissipation3D
drifters2D
energy_budget
fe_archive
general
miscellaneous
ocean_waves
physics
samples
sea_ice
sediment
stability_control
stream2D
structured_archive
tides
topography_geodesy
tracers2D
tracers3D