tracmass.steady_state#

tracmass.steady_state(state, grid, fluxes, *, iter_sub=1, max_iter=100_000, timax_seconds=_UNSET, traj_max_time=_UNSET, scheme='tstep', no_wflux=_UNSET, n_particle_batches=_UNSET)[source]#

Single-window steady-state integration.

The flux direction (forward/backward) is determined by grid.reverse, as set when the grid was created via tracmass.gcm.new_grid() or tracmass.gcm.new_flux().

Parameters:

  • state (ParticleState) – Initial particle state.

  • grid (gcm.GridFields) – Static grid geometry from tracmass.gcm.new_grid() or tracmass.gcm.new_flux(). Pass dtm_end earlier than dtm_start to either for backward-in-time trajectories.

  • fluxes (gcm.FluxFields) – Time-varying flux data for the current time window.

  • iter_sub (int) – Number of sub-cycles per GCM step (ignored when scheme=’analytical’).

  • max_iter (int) – Maximum number of sub-cycles.

  • timax_seconds (float, optional) – Maximum trajectory lifetime in seconds, counted from each particle’s release (tt - t0). Pass this or traj_max_time, not both.

  • traj_max_time (str or None, optional) – The same lifetime as a pd.Timedelta string ("30D", "12h") or in calendar units ("1M", "6M", "1Q", "1Y", measured from the run’s start, fluxes.dtm). Particles past it stop with reason time. When neither is passed, from the traj_max_time setting (default: no limit). See tracmass.runsetup.traj_max_seconds().

  • scheme (str) – Advection scheme: "tstep" (default) or "analytical".

  • no_wflux (bool, optional) – When True, vertical (w) fluxes are ignored and particles are confined to their initial depth layer (ka never changes). When not passed, resolved from the move_vertically setting as no_wflux = not move_vertically (default move_vertically=True, i.e. no_wflux=False). See tracmass.config.move_vertically().

  • n_particle_batches (int, optional) – Split particles into this many equal-sized groups and run each group through lax.while_loop separately, capping the peak per-call GPU scratch allocation to roughly 1 / n_particle_batches. When not passed, taken from the n_particle_batches setting (default 1 — no batching); an explicit value wins. See tracmass.config.n_particle_batches() and time_dependent() for the full rationale.

Returns:

  • ParticleState with final positions.

  • For multi-window integration with field updates, use :func:`time_dependent.`

Return type:

ParticleState