tracmass.config and tracmass.driver#

Configuration management for the seaview processor.

This module handles loading and managing configuration settings using Dynaconf. Settings are loaded from multiple locations in order of increasing priority:

  1. Global settings (/etc/seaview/)

  2. User settings (~/.config/seaview/)

  3. Current directory settings (./)

  4. Any trm_*.toml file in the current directory (e.g. trm_omi.toml), sorted by filename

  5. Environment variable specified file (SEAVIEW_SETTINGS_FILE_FOR_DYNACONF)

tracmass.config.ENV#

Default environment name.

Type:

str

tracmass.config.USER_DIR#

Path to user configuration directory.

Type:

pathlib.Path

tracmass.config.GLOB_DIR#

Path to global configuration directory.

Type:

pathlib.Path

tracmass.config.CURR_DIR#

Path to current working directory.

Type:

pathlib.Path

tracmass.config.settings#

The Dynaconf settings object with loaded configuration.

Type:

Dynaconf

tracmass.config.change_env(new_env)[source]#

Change the active Dynaconf environment.

Parameters:

new_env (str) – The environment name to switch to (e.g., ‘development’, ‘production’).

tracmass.config.move_vertically()[source]#

Return the move_vertically flag from settings.

Controls whether particles are advected by the vertical velocity w. Read from the active tracmass.toml environment; defaults to True (particles do move vertically) when the key is absent, matching the historical no_wflux=False / include_wflux=True defaults.

Returns:

bool – True if vertical advection is enabled. The integrators map this to no_wflux = not move_vertically() and the ECCO2 adapter maps it to include_wflux = move_vertically() whenever those arguments are not passed explicitly.

Return type:

bool

tracmass.config.n_particle_batches()[source]#

Return the n_particle_batches factor from settings.

Number of equal-sized particle groups each lax.while_loop call is split into by the full-grid integrators (tracmass.steady_state(), tracmass.time_dependent()), to cap peak per-call GPU scratch memory. Read from the active tracmass.toml environment; defaults to 1 (no batching) when the key is absent or unparseable. time_dependent_patched / time_dependent_streaming accept the argument for API symmetry but do not batch.

Returns:

int – Batching factor, clamped to >= 1.

Return type:

int

tracmass.config.gcm_name(default=None)[source]#

Return the gcm.name adapter name from the active settings environment.

Reads the name key of the [env.gcm] table in tracmass.toml (e.g. "glorys", "ecco2", "theoretical", "fabboni"). A bare gcm = "<name>" string (the pre-[gcm]-table form) is still accepted.

Parameters:

default (str or None, optional) – Value to return when neither form is set. Default None.

Returns:

str or None – The adapter name, or default if unset.

Return type:

str | None

tracmass.config.gcm_subset()[source]#

Return the GCM spatial subset from the active settings environment.

Reads the subset key of the [env.gcm] table in tracmass.toml and returns it as a plain dict with every key in GCM_SUBSET_KEYS present. Missing keys — and keys written as "@none" or false — come back as None (“no limit on that edge”).

Returns:

dict – {"i1": .., "i2": .., "istep": .., "j1": .., "j2": .., "jstep": .., "k1": .., "k2": .., "kstep": ..} — each value an int or None.

Return type:

dict

See also

apply_gcm_subset

push this dict into a GCM adapter’s settings.

Examples

>>> settings.setenv("omi")     # [omi.gcm] subset = { i1 = 2600, ... }
>>> gcm_subset()["i1"]
2600
tracmass.config.apply_gcm_subset(module, subset=None)[source]#

Copy the settings-driven spatial subset into a GCM adapter.

Updates module.settings["subset"] in place so that a subsequent module.fluxes(...) call slices the source grid to the configured region. Only keys with a non-None value are written, so a partially-specified [env.gcm] subset table in tracmass.toml composes with any limits set directly on module.settings["subset"].

Adapters that generate their grid and expose no settings["subset"] (tracmass.gcm.theoretical, tracmass.gcm.fabboni) are left untouched.

Parameters:

  • module (module) – A tracmass.gcm adapter (e.g. tracmass.gcm.ecco2).

  • subset (dict, optional) – Subset mapping to apply. Defaults to gcm_subset() (the active settings environment).

Returns:

dict – The fully-resolved subset (all GCM_SUBSET_KEYS, int or None), whether or not the adapter had a slot to receive it.

Return type:

dict

Examples

>>> from tracmass import gcm
>>> apply_gcm_subset(gcm.glorys)          # honour [env.gcm] subset
>>> gcm.glorys.settings["subset"]["k1"]
1

Settings-driven, single-call entry point for a trajectory run.

run() strings together the usual steps — activate a tracmass.toml environment, build the grid and flux buffer, seed particles, integrate — taking everything not passed explicitly from the active settings:

Setting

Used for

gcm.name

GCM adapter ([env.gcm] name), when gcm is omitted

dtm_start

Start date, when dtm_start is omitted

dtm_end

End date, when dtm_end is omitted

runtime

dtm_end = dtm_start + runtime when no end date is set; a negative value ("-180D") gives a backward run

integrator

"time_dependent" (default), "time_dependent_patched" or "time_dependent_streaming", when integrator is omitted

seed

Seeding table (tracmass.seed.from_settings()), when state is omitted

verbose

Debug output of each run stage (tracmass.verbose), when verbose is omitted

The integrators themselves resolve monitor, recorder, no_wflux and n_particle_batches from settings (see tracmass.runsetup), and n_windows from the flux buffer’s dtm_end.

tracmass.driver.run(dtm_start=None, dtm_end=None, state=None, *, env=None, gcm=None, integrator=None, verbose=None, **kwargs)[source]#

Build the grid and flux buffer, seed, and integrate in one call.

Parameters:

  • dtm_start (str or pd.Timestamp or None, optional) – Start date. Default: the dtm_start setting, else the adapter’s own default date.

  • dtm_end (str or pd.Timestamp or None, optional) – End date; earlier than the start date means a backward run. Default: the dtm_end setting, else start + the runtime setting, else a single window.

  • state (ParticleState or callable or None, optional) – Initial particles, or seed(grid) -> ParticleState called once the grid is built (and env is active, so it can read settings). Default: seed from the [env.seed] settings table via tracmass.seed.from_settings().

  • env (str or None, optional) – tracmass.toml environment to activate first (via settings.setenv; it stays active after the call, which is what adapters and integrators read during the run). Default: keep the current environment.

  • gcm (str or callable or None, optional) – Adapter name or fluxes callable. Default: the gcm.name setting.

  • integrator (str or None, optional) – Name of the integrator, a key of INTEGRATORS. Default: the integrator setting, else "time_dependent".

  • verbose (bool or None, optional) – Print timestamped debug messages for each stage (adapter calls, flux reads and their size, seeding, compilation, each window) to stderr while the run lasts; see tracmass.verbose. Default: the verbose setting, else False.

  • **kwargs – dtm is accepted as an alias for dtm_start (matching the dtm naming of LazyFluxFields); the rest are passed on to the integrator (e.g. iter_sub, monitor, recorder, patch_buffer, n_windows).

Returns:

ParticleState – Final particle state.

Raises:

  • ValueError – If no GCM is given or configured, integrator is unknown, state is omitted and there is no usable [env.seed] table, or a string dtm_start / dtm_end is not a date (e.g. run("omi") where run(env="omi") was meant).

  • TypeError – If both dtm_start and its alias dtm are given. If a particle state or seed callable is passed as dtm_start or dtm_end (the pre-2026-09-30 argument order).

Return type:

ParticleState

Examples

>>> from tracmass import seed
>>> result = tracmass.run(
...     "2020-07-01",
...     state=lambda grid: seed.ijk(10, 20, 10, 20, 1, 1, grid=grid),
...     env="tempvel", integrator="time_dependent_patched",
... )
>>> result = tracmass.run("2007-06-01", env="omi")  # seeding from settings too
>>> result = tracmass.run(dtm="2007-06-01", env="omi")  # same, via the alias