# 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](https://www.dynaconf.com) object. This
page lists every key, grouped the way the namelist is, and ends with a
[namelist-to-settings map](#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:

```toml
[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](../tutorials/subsets.md).

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](../tutorials/stopping.md). |

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](../tutorials/seeding.md).

## 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](../output.md).

## Monitoring and logging

*Fortran: `log_level`.*

| Key | Type | Default | Description |
|---|---|---|---|
| `runmonitor_backend` | str | `"print"` | `"print"`, `"log"` or `"rich"`. See [Monitoring](../tools/monitoring.md). |
| `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 |

```python
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](../tutorials/new_gcm.md)) |
| `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"` |