Settings reference

Fortran TRACMASS reads its run options from a namelist (namelist.in), split into groups such as INIT_GRID_TIME, INIT_SEEDING and INIT_KILLZONES. TRACMASS-JAX reads them from TOML settings files through tracmass.settings, a Dynaconf object. This page lists every key, grouped the way the namelist is, and ends with a namelist-to-settings map.

Every setting is optional. The value of an argument passed to tracmass.run or to an integrator always wins over the setting of the same name.

Settings files

tracmass.settings merges these files, later ones winning:

1. /etc/tracmass/tracmass.toml and /etc/tracmass/.secrets.toml

2. ~/.config/tracmass/tracmass.toml and .secrets.toml

3. ./tracmass.toml and ./.secrets.toml in the current directory

4. every trm_*.toml in the current directory, sorted by file name

5. the file named by the environment variable SEAVIEW_SETTINGS_FILE_FOR_DYNACONF, if set

The trm_*.toml files let a script carry its own run settings (for example trm_omi.toml with an [omi] table) next to a shared tracmass.toml, without editing the shared file.

Environments

Each top-level table is an environment. [default] applies to all of them, and the active environment’s values override it:

[default]
base_output_dir = "/data/raid/trm/"
runmonitor_backend = "rich"
n_particle_batches = 8

[omi]
dtm_start = "2010-06-01"
runtime = "180D"
move_vertically = false
output_name = "trm_omi"

[omi.gcm]
name = "glorys"
subset = { i1 = 2600, i2 = 3700, j1 = 500, j2 = 1600, k1 = 1, k2 = 2 }

[omi.seed]
approach = "ijk"
i_sub_num = 4
j_sub_num = 4
box = { i1 = 2610, i2 = 2620, j1 = 510, j2 = 520, k1 = 1, k2 = 1 }

Activate an environment with tracmass.run(env="omi") or tracmass.settings.setenv("omi"). Values can also be set from the shell with the SEAVIEW_ prefix, e.g. SEAVIEW_VERBOSE=true.

Grid and GCM — [env.gcm]

Fortran: INIT_GRID_DESCRIPTION, INIT_GRID_SIZE, INIT_GRID_SUBDOMAIN.

Key	Type	Default	Description
gcm.name	str	—	Adapter in tracmass.gcm: "glorys", "ecco2", "scrippsgog", "theoretical", "fabboni". A bare gcm = "glorys" also works.
gcm.subset.i1, i2	int	none	0-based slice limits on the model x axis (TRACMASS cells, halo removed).
gcm.subset.j1, j2	int	none	0-based slice limits on the model y axis.
gcm.subset.k1, k2	int	none	1-based levels to keep (k1 = 1 is the first level).
gcm.subset.istep, jstep, kstep	int	none	Optional strides. Positions are then in strided-cell units.

Omitted subset keys, or keys set to "@none", mean “no limit on that edge”. A subset in x turns off zonal periodicity (iperio = 0). See Subsets.

Grid sizes (imt, jmt, km), periodicity (iperio, jperio), cell areas and thicknesses are not settings. The adapter returns them with the fluxes.

Run time — start, end, direction

Fortran: INIT_START_DATE, INIT_RUN_TIME, INIT_GRID_TIME.

Key	Type	Default	Description
dtm_start	date string	adapter default	First snapshot of the run.
dtm_end	date string	—	Last time of the run. Earlier than dtm_start means a backward run.
runtime	Timedelta string	—	Used when dtm_end is not set: dtm_end = dtm_start + runtime. "180D" runs forward, "-180D" backward.

The GCM output interval (Fortran ngcm_step, ngcm_unit) comes from the adapter (grid.timestep). The number of windows is ceil(|dtm_end - dtm_start| / timestep). Without dtm_end a run is one window.

Integration

Fortran: INIT_GRID_TIME (iter), INIT_KILLZONES (timax), Makefile options (w_explicit, time_analytical).

Key	Type	Default	Description
integrator	str	"time_dependent"	"time_dependent", "time_dependent_patched" or "time_dependent_streaming". Read by tracmass.run only.
move_vertically	bool	true	false keeps particles on their seeding level (no_wflux=True), and the vertical flux is not read at all.
n_particle_batches	int	1	Split the particles into this many groups, one compiled loop per group, to cap GPU memory. Used by steady_state and time_dependent.
traj_max_time	str	no limit	Stop each particle this long after its own release: "30D", "12h", "2W", or calendar "1M", "1Q", "1Y". See Stopping trajectories.

These options have no setting and are passed as arguments, either to the integrator or through tracmass.run(..., iter_sub=4):

Argument	Default	Description
iter_sub	1	Sub-steps per GCM window (Fortran iter). No step crosses a sub-step boundary.
scheme	"tstep"	"tstep" or "analytical" (full-grid integrators only).
max_iter	100000	Cap on the total number of sub-cycles.
max_sub_iter_per_window	10000	Cap per window. Particles still running then stop with reason iter_limit.
pace_factor	5	How strictly slow particles are stopped (reason too_slow).
patch_buffer	50	time_dependent_patched: cells added on each side of the particle box.
patch_granularity	100	time_dependent_patched: patch sizes are rounded up to multiples of this, to limit recompilation.
timax_seconds	no limit	The same as traj_max_time, in seconds.

Seeding — [env.seed]

Fortran: INIT_SEEDING.

Key	Type	Default	Description
approach	str	"ijk"	"ijk", "latlon_box", "latlon_point" or "latlon_list".
box	table	—	ijk: {i1, i2, j1, j2, k1, k2}, 1-based cells, absolute (full-grid) i/j. latlon_box: {lat1, lat2, lon1, lon2, k1, k2}.
lat, lon, dlat, dlon	float	—	latlon_point: a box of half-width dlat (and dlon, default dlat) around a point. For latlon_list: lists of positions.
seed_file	path	—	latlon_list: a .csv or .parquet file with lat, lon (and optionally k) columns.
kpos	int	1	Level for 2-D seeding when no k1/k2 or k column is given.
use_subset_coordinates	bool	false	ijk: the box is relative to [env.gcm] subset instead of absolute.
sub_dist	str	"rect_xyz"	How particles are placed inside a cell: "rect_xyz" (a regular sub-grid) or anything else for the cell centre.
i_sub_num, j_sub_num, k_sub_num	int	1	Particles per cell in each direction for "rect_xyz" (Fortran partQuant with nqua = 1).
seed_freq	pandas frequency	—	Release the particles again every seed_freq ("7D", "MS", "QS", …), counted from dtm_start.

See Seeding.

Output and recording

Fortran: INIT_WRITE_TRAJ.

Key	Type	Default	Description
output_name	str	—	File-name stem. Setting it turns on automatic recording.
auto_record	bool	false	Turn on automatic recording with the stem trm_{env}.
base_output_dir	path	current dir	Directory for the trajectory files.
use_sub_folder	bool	false	Write to {base_output_dir}/{output_name or env}/ (created if needed).
rampup_windows	int	0	Save positions more often during the first windows.
rampup_substeps	int	5	Saves per window during ramp-up.

The file name is {base_output_dir}[/{sub folder}]/{stem}_{forward|reverse}_{dtm_start}.parquet. With neither output_name nor auto_record, nothing is written unless you pass recorder=. See Output.

Monitoring and logging

Fortran: log_level.

Key	Type	Default	Description
runmonitor_backend	str	"print"	"print", "log" or "rich". See Monitoring.
verbose	bool	false	Time-stamped debug output for every stage of a run.

Data sources (process-wide)

The tracmass.seagrid modules, which read the reanalysis data, keep their own module-level settings dict rather than reading tracmass.toml:

Key	Default	Description
disk	"raid"	Local cache root: /data/{disk}/...
product	per adapter	Dataset name, part of the cache path
host	per adapter	Remote server (OPeNDAP / THREDDS / HTTPS)
timestep	1 day	Native output interval of the dataset

from tracmass.seagrid import glorys
glorys.settings["disk"] = "scratch"     # read /data/scratch/mercator/...

Changing these affects every run in the Python process.

Namelist-to-settings map

Namelist group	Fortran variable	TRACMASS-JAX
INIT_GRID_DESCRIPTION	physDataDir, physPrefixForm, *GridName, ueul_name, …	The GCM adapter ([env.gcm] name) and its seagrid module
INIT_GRID_SIZE	imt, jmt, km, iperio, jperio, kmt_name, dzt_name, …	Returned by the adapter’s fluxes() (see Adding a GCM)
INIT_GRID_SUBDOMAIN	l_subdom, imindom, imaxdom, jmindom, jmaxdom	[env.gcm] subset (i1, i2, j1, j2, k1, k2)
INIT_GRID_TIME	ngcm_step, ngcm_unit	Adapter timestep (grid.timestep)
	iter	iter_sub argument
INIT_START_DATE	startYear … startSec	dtm_start
	noleap, mon30day	not needed: dates are pandas timestamps from the data
INIT_RUN_TIME	intrun	dtm_end or runtime (or n_windows)
	loopYears, loopStartYear, loopEndYear	not supported
	log_level	runmonitor_backend, verbose
INIT_WRITE_TRAJ	write_frec	positions every window; rampup_windows/rampup_substeps for denser saves
	outDataDir, outDataFile	base_output_dir, output_name, use_sub_folder
	timeformat, write_form, l_compress	not needed: Parquet with timestamps, compressed
INIT_SEEDING	ist1, ist2, jst1, jst2, kst1, kst2	[env.seed] box
	SeedType, seedfile, maskfile	approach; seed.mask, seed.from_df, seed_file
	nqua, partQuant	sub_dist, i_sub_num, j_sub_num, k_sub_num
	isec, idir	not needed: particles are seeded at cell centres or sub-grid points; direction from dtm_start/dtm_end
	nff	direction from the order of dtm_start and dtm_end
	tst1, tst2, seedTime	seed_freq
INIT_KILLZONES	timax	traj_max_time (or timax_seconds)
	exitType, ienw, iene, jens, jenn	not yet; particles stop at domain edges and land
	l_nosurface	not yet
INIT_TRACERS, INIT_TRACERS_SEEDING	l_tracers, …	not yet
INIT_POSTPROCESS	l_psi, l_offline, l_divergence, …	not yet (analyse the Parquet output instead)
INIT_ACTIVE	l_diffusion, ah, av	not yet
Makefile	two-dimensional trajectories	move_vertically = false
Makefile	time-analytical scheme	scheme="analytical"