Configuration Reference

Note

For a quick alphabetical lookup of all configuration parameters, see Configuration Variable Index.

A TRITON configuration file (.cfg) defines everything needed to launch a run:

Input data: paths to DEMs, roughness maps, and hydrographs
Numerical settings: timestep control, CFL limit, tolerances
Forcing and boundaries: streamflow, runoff, and external conditions
Outputs: format, frequency, and file naming conventions

Each case directory under input/ contains its own configuration file. For example, the Allatoona case provides:

input/allatoona/allatoona.cfg

This file is a good starting template: adjust paths and parameters to match your own domain.

Important

Unless an absolute path is given, all file paths in the configuration are resolved relative to your working directory (where you launch TRITON), not the location of the .cfg file itself.

Configuration Overview

The following sections describe each configuration block in detail, using input/allatoona/allatoona.cfg as a concrete example. The configuration file specifies all aspects of a TRITON run, grouped into these blocks.

Input and Output Folders 

Two global parameters define the base locations for inputs and outputs. All other file paths in the configuration are interpreted relative to these folders.

input_folder: base directory for input files (DEMs, maps, hydrographs).

Example (Allatoona):
```
input_folder="input"
```

output_folder: directory where TRITON writes results.

Example (Allatoona):
```
output_folder="output"
```

Important

Absolute paths should not be used for the input and output folder locations. The locations of these folders are resolved relative to the TRITON executable.

Topography 

The first and most important input is the Digital Elevation Model (DEM), which defines the spatial extent and resolution of the simulation domain.

dem_filename: path to the Digital Elevation Model file.

Example (Allatoona):
```
dem_filename="input/allatoona/allatoona.dem"
```

DEM files can be provided in Esri ASCII raster (ASC) or TRITON binary (BIN) format. Conversion utilities between ASCII and binary are provided in the tools/ directory. (#tosort).

ASCII DEM format

An ASCII DEM begins with a six-line header followed by the elevation matrix. For example, the Allatoona DEM starts with:

ncols         591
nrows         673
xllcorner     719559.01581497
yllcorner     3765449.3800973
cellsize      30
NODATA_value  -9999
305.2047 301.1886 297.5595 297.4224 302.5769 ...

The six header lines define the grid dimensions, spatial reference, resolution, and NODATA value.
The matrix that follows contains elevations for nrows × ncols cells.

Important

TRITON requires the DEM (and all other rasters such as Manning’s n and runoff maps) to be in a projected coordinate system with units in meters.
All rasters must have the same grid size, extent, resolution, and alignment as the DEM. Any mismatch will cause TRITON to fail at startup.

Note

The NODATA field is required by the ESRI ASCII raster format. TRITON does not apply any special treatment to NODATA values — they are read literally as part of the matrix. If negative values such as -9999 are present, they will be interpreted as very deep pits, which may destabilize a simulation.

Input and Output Formats 

TRITON supports multiple file formats for inputs and outputs. The following parameters control how rasters are read and written.

input_format: format of input rasters. Options: - ASC: ASCII grid (readable, easy to debug) - BIN: TRITON binary format (compact, faster I/O)

Example:
```
input_format=ASC
```

output_format: format of output rasters. Options: - ASC: ASCII grid - BIN: TRITON binary - GTIFF: GeoTIFF (GIS-ready, supports georeferencing)

Example:
```
output_format=BIN
```

projection (required if ``output_format=GTIFF``): EPSG code or WKT string used to embed spatial reference in GeoTIFF outputs. Ignored for ASC and BIN.

Example:
```
projection="EPSG:32614"
```
Note

Must be a valid EPSG code (e.g. EPSG:4326) or a complete WKT definition. If missing or invalid, GeoTIFF outputs will lack spatial reference.

output_option: how outputs are written in parallel runs. Options: - SEQ: gather all subdomains into a single file per variable - PAR: write one file per subdomain (faster, especially on clusters)

Example:
```
output_option=SEQ
```
Tip

With output_option=PAR and output_format=GTIFF, TRITON also writes a .vrt (Virtual Raster) file. The .vrt references all tiles and appears as a seamless raster in GIS tools without duplicating data.

outfile_pattern: naming convention for output files. Placeholders are replaced by case name, variable, and timestep indices. Normally left at default.

Example:
```
outfile_pattern="%s/%s/%s_%02d_%02d"
```

Hydrologic Forcing 

TRITON can be driven by streamflow hydrographs at specified inflow locations, by runoff hydrographs over distributed zones, or by a combination of both. The Allatoona example demonstrates both types of inputs.

Streamflow Hydrograph

num_sources: number of inflow points (streamflow sources). Must match the number of discharge columns in the hydrograph file.

Example (Allatoona):
```
num_sources=2
```

hydrograph_filename: path to the file containing streamflow hydrographs.

Example (Allatoona):
```
hydrograph_filename="input/allatoona/allatoona.hyg"
```
File format: - Column 1 = time (hours) - Columns 2…N = discharge (m³/s), one per source - Lines beginning with % are treated as comments and ignored

Example file (.hyg):
```
% Hydrograph
% Time(hr) Q1(cms) Q2(cms)
0,1.787598324,6.142665492
3,2.966903878,9.077155463
6,3.602809745,12.16067761
```

src_loc_file: file with the Cartesian coordinates of inflow locations. Row order must match the column order in hydrograph_filename.

Example (Allatoona):
```
src_loc_file="input/allatoona/allatoona.src"
```
Example file (.src):
```
% X  Y  (projected meters)
735404.711,3780498.492
736616.216,3776851.088
```

Note

Units: time in hours, discharge in m³/s.
num_sources must equal the number of discharge columns in the hydrograph.
Comment lines starting with % are allowed and ignored by the reader.

Runoff Hydrograph

num_runoffs: number of distinct runoff zones in the domain. Must match the number of runoff columns in the hydrograph file.

Example (Allatoona):
```
num_runoffs=156
```

runoff_filename: path to the file containing runoff hydrographs.

Example (Allatoona):
```
runoff_filename="input/allatoona/allatoona.roff"
```
File format: - Column 1 = time (hours) - Columns 2…N = runoff rates (mm/hour), one per zone - Number of runoff columns must equal num_runoffs - Lines beginning with % are treated as comments and ignored

Example file (.roff):
```
% Runoff Hydrograph
% Time(h) Zone0(mm/hr) Zone1(mm/hr) ...
0.0,0.0,0.0,0.0,...
0.5,0.1,0.0,0.0,...
1.0,0.3,0.1,0.0,...
```

runoff_map: raster assigning each grid cell to a runoff zone. Zone IDs must be integers starting from 0 up to num_runoffs-1. The map must align exactly with the DEM.

Example (Allatoona):
```
runoff_map="input/allatoona/allatoona.rmap"
```

Important

The runoff map must use the same grid, resolution, and projection as the DEM.
Zone IDs in runoff_map must correspond exactly to the columns in the runoff hydrograph file.
Zones are numbered starting at 0.
Units: time in hours, runoff in mm/hour.
Note that .asc file raster should not include header.

Note

Streamflow and runoff forcing can be used independently or together.

Examples: - A dam-break test may use only streamflow hydrographs. - A watershed-scale flood may combine distributed runoff with a few streamflow

sources.

TRITON superimposes all sources during simulation. Be careful to avoid double-counting inflows if both streamflow and runoff are applied in overlapping regions.

Surface Roughness (Manning’s n)

TRITON accounts for surface roughness using Manning’s n coefficients. Roughness can be specified either as a spatial raster or as a constant value.

n_infile: path to a raster of Manning’s n values. - Must have the same grid, extent, and projection as the DEM - Supported formats: ASCII (.asc) or binary (.bin). Note that .asc file raster should not include header.

Example (Allatoona):
```
n_infile="input/allatoona/allatoona.mann"
```

const_mann: constant Manning’s n value applied to the entire domain.

Example:
```
const_mann=0.035
```

Important

If n_infile is provided, it overrides const_mann.
The Manning raster must align exactly with the DEM grid.

External Boundaries 

By default, TRITON treats all domain edges as closed. To allow inflow/outflow, you must define external boundaries.

num_extbc: number of boundary segments. Must equal the number of rows in extbc_file.

Example (Allatoona):
```
num_extbc=2
```

extbc_file: file listing boundary segments.

Example (Allatoona):
```
extbc_file="input/allatoona/allatoona.extbc"
```

extbc_dir: directory containing boundary-related files.

Example (Allatoona):
```
extbc_dir="input/allatoona/"
```

Boundary File Format

Each row in extbc_file defines one boundary segment with:

Type (integer code)
X1, Y1: coordinates of the first endpoint (projected meters)
X2, Y2: coordinates of the second endpoint (projected meters)
BC parameter(s): depends on boundary type

Boundary type codes:

Code	Meaning
0	Free flow (supercritical outflow)
1	Level vs. time (requires time–level file)
2	Normal slope (requires slope value)
3	Froude number (requires Froude value)

Example ("input/allatoona/allatoona.extbc"):

% BC Type, X1, Y1, X2, Y2, BC
3,719569.048,3785624.114,723849.375,3785624.114,0.5
3,719569.048,3785624.114,719569.048,3782029.877,0.5

Here both boundaries are Type 3 (Froude number), so the last column (0.5) specifies the Froude value.
Coordinates are in meters, same projected CRS as the DEM.

Example for a Type 1 time–level file referenced by a boundary row:

% time (hr), water level (m)
0,255.0
0,255.2
0,255.5

Note

If explicit boundaries are defined (num_extbc > 0), they override the global open_boundaries switch for the specified segments only. Other domain edges remain subject to the global setting.

Simulation Control 

This block sets the simulation timing and timestep control.

sim_start_time: simulation start time (seconds).

Example:
```
sim_start_time=0
```

sim_duration: total simulation length (seconds).

Example (Allatoona):
```
sim_duration=432000   # 5 days
```

checkpoint_id: restart index. Options: - 0 = start fresh - >0 = restart from the specified checkpoint

time_increment_fixed: timestep mode. Options: - 0 = adaptive timestep (default, CFL-controlled) - 1 = fixed timestep (use time_step)

time_step: fixed timestep size (seconds). Used only if time_increment_fixed=1.

Example:
```
time_step=5.0
```

Note

Adaptive timestepping (time_increment_fixed=0) is recommended for most cases.

Important

Stability is controlled by the Courant number (courant in Miscellaneous Parameters). Keep courant <= 0.5 for reliable runs.

Output Control 

This block controls raster outputs, observation time series, and logging.

print_option: raster output fields. Options: - h = water depth only - huv = water depth + discharges (qx, qy)

Example (Allatoona):
```
print_option=h
```

print_interval: time interval between raster outputs (seconds).

Example:
```
print_interval=1800   # every 30 minutes
```

time_series_flag: enable writing hydrograph time series at observation points. Options: - 0 = disabled - 1 = enabled

observation_loc_file: path to the file with observation point coordinates.

Example file:
```
%X-Location,Y-Location
727430.089,3772474.295
```

print_observation: interval (seconds) for writing time series at observation points. - Independent of print_interval (raster outputs) - Can be set smaller than print_interval to record hydrographs more frequently

without the cost of writing large raster files

Example:
```
print_observation=300   # every 5 minutes
```

it_print: iteration interval for diagnostic log messages to console/log.

Example:
```
it_print=100
```

Note

Raster outputs are controlled by print_option and print_interval.
Time series outputs require both time_series_flag=1 and a valid observation_loc_file.
print_observation sets the interval for time series output. Use a finer interval (e.g., 5 min) to capture detailed hydrographs, while keeping print_interval (rasters) coarser (e.g., 30–60 min) for efficiency.
This balance avoids excessive raster output while still providing dense time series data for analysis.
Console/log verbosity is controlled by it_print.

Initial Conditions 

TRITON starts dry unless initial condition files are provided.

h_infile: initial depth raster
qx_infile: initial discharge (x)
qy_infile: initial discharge (y)

Example:

h_infile="input/allatoona/allatoona.inith"
qx_infile="input/allatoona/allatoona.initqx"
qy_infile="input/allatoona/allatoona.inityq"

In Allatoona these are empty, so it starts dry.

Note

These rasters must match the DEM grid. Typically used for hot start or after spinup.

Miscellaneous Parameters 

Advanced settings for stability and parallel performance.

courant: Courant–Friedrichs–Lewy (CFL) number controlling stability. Recommended ≤ 0.5.

Example:
```
courant=0.5
```

hextra: depth tolerance (meters). Below this threshold, velocities are set to zero to avoid instabilities.

Example:
```
hextra=0.001
```

gpu_direct_flag: GPU-aware MPI communication. Options: - 0 = off (safe default) - 1 = on (use only with CUDA-aware MPI builds)

domain_decomposition: domain partitioning mode. Options: - static = fixed partitioning (default) - dynamic = partitions updated periodically

factor_interval_domain_decomposition: update frequency for dynamic domain decomposition (integer factor of print_interval).

Example:
```
factor_interval_domain_decomposition=10
```

open_boundaries: global switch for external boundary conditions. Options: - 0 = closed boundaries (default) - 1 = all domain edges open

Note

If explicit external boundaries are defined (num_extbc > 0), they override this global switch for the specified segments only. Other edges remain subject to the global setting.

it_count: internal iteration counter. Normally left at 0 (used internally for restarts/checkpoints).

Quick Sanity Checks

DEM, Manning, and runoff map share the same grid and CRS.
Input rasters are ASC/BIN. If outputs are GTIFF, set projection="EPSG:xxxx".
Hydrograph columns = num_sources; runoff columns = num_runoffs.
Inflow order matches hydrograph column order.
Boundary count = num_extbc; coords in projected meters.
courant <= 0.5; adaptive timestep recommended.

Note

Unless an absolute path is given, all file paths in the configuration are resolved relative to the directory where you launch the run (your working directory), not necessarily the location of the .cfg file.