tracmass.time_dependent_streaming#

tracmass.time_dependent_streaming(state, grid, fluxes, fluxes_fn=None, *, iter_sub=1, max_iter=100_000, n_windows=None, max_sub_iter_per_window=10_000, timax_seconds=_UNSET, traj_max_time=_UNSET, recorder=_UNSET, monitor=_UNSET, no_wflux=_UNSET, pace_factor=5, n_particle_batches=_UNSET, rampup_windows=_UNSET, rampup_substeps=_UNSET, seed_freq=_UNSET)[source]#

Multi-window integration using per-particle flux stencil extraction.

At each sub-cycle, only the flux values needed for each particle’s current cell are loaded via vectorised xarray point indexing — no rectangular patch is pre-allocated. This makes the approach viable for widely scattered particles and very long runs where a bounding-box patch would cover most of the global grid.

The JAX while_loop used by time_dependent() and time_dependent_patched() is replaced by a Python for-loop, with one Dask compute and one JAX JIT call per sub-cycle. The total number of Python iterations is n_windows × (subcycles per window), typically on the order of n_windows × 10–20 for monthly GLORYS windows.

The GCM window duration is taken from grid.timestep; it does not need to be supplied separately.

Parameters:

  • state (ParticleState) – Initial particle state.

  • grid (gcm.GridFields) – Static grid geometry. grid.timestep sets the window duration.

  • fluxes (gcm.LazyFluxFields) – Lazy flux data for the first two time slots.

  • fluxes_fn (callable or None) – Called as fluxes_fn(dtm) to load the next window. If None, inferred from fluxes.fluxes_fn (set automatically by new_flux()).

  • iter_sub (int) – Sub-cycles per GCM step; sets minimum sub-cycle duration grid.timestep / iter_sub.

  • max_iter (int) – Maximum number of sub-cycles over the entire run.

  • n_windows (int or None, optional) – Number of GCM time windows to integrate over. Default None — derived from the flux buffer as fluxes.n_windows, i.e. enough windows to reach the dtm_end given to tracmass.gcm.new_flux(); 1 if no dtm_end was given.

  • max_sub_iter_per_window (int) – Safety cap on sub-cycles within each window. Default 10 000.

  • 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().

  • recorder (ParticleRecorder or str or None, optional) – Where to stream active-particle snapshots (each window boundary) and deactivation events, all to one Parquet file (event_type column). Pass a ParticleRecorder to manage the file yourself, or a path string to have one built and closed for you. None disables recording. When omitted, a recorder is built from settings (output_name / auto_record / base_output_dir); if neither output_name nor auto_record is set, nothing is written. See tracmass.runsetup.

  • monitor (RunMonitor or str or None, optional) – Controls progress output. Pass a RunMonitor instance, or a backend name ("print", "log", "rich") to have one built for you. None suppresses all output. When omitted, the backend is taken from the runmonitor_backend setting (default "print"). A monitor / recorder built here is entered and exited automatically, so no with block is needed.

  • no_wflux (bool, optional) – When True, vertical (w) fluxes are ignored and particles are confined to their initial depth layer. 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) – Accepted for API compatibility with the full-grid integrators (steady_state() / time_dependent()) — resolved from the n_particle_batches setting when omitted — but has no effect here. The streaming variant already processes all particles in a single Python loop without a JAX while_loop, so there is no per-call GPU scratch allocation to reduce. Default 1.

  • rampup_windows (int, optional) – Not supported here: a ramp-up (from the arguments or the rampup_windows setting) raises NotImplementedError; use time_dependent() or time_dependent_patched().

  • rampup_substeps (int, optional) – Not supported here: a ramp-up (from the arguments or the rampup_windows setting) raises NotImplementedError; use time_dependent() or time_dependent_patched().

  • seed_freq (str or None, optional) – Release a copy of state again every seed_freq (pandas frequency, e.g. "30D" or "MS"), as in time_dependent(). When omitted, from seed_freq in the [env.seed] settings table.

  • pace_factor (int)

Returns:

ParticleState – Final particle state in global grid coordinates.

Return type:

ParticleState