tracmass.run#

tracmass.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