Model inputs and settings :¶

Usage¶

tugo [OPTIONS] configuration_file.intg

Configuration file¶

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