tracmass.time_dependent_patched#

tracmass.time_dependent_patched(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, patch_buffer=50, patch_granularity=100, pace_factor=5, n_particle_batches=_UNSET, rampup_windows=_UNSET, rampup_substeps=_UNSET, seed_freq=_UNSET)[source]#

Multi-window integration using local flux patches around the particles.

Instead of computing the full global grid, this function computes the bounding box of the active particles at the start of each window, loads only the Zarr chunks that intersect that region plus patch_buffer cells of margin, and runs the advection kernel on the resulting sub-patch.

The patch shape is fixed at initialisation (initial bbox + patch_buffer on each side) so the JAX kernel is compiled exactly once and reused for all windows. Between windows the patch origin is recentred on the current particle centroid (zero-cost re-slicing of the lazy xarray DataArrays) and the patch content is re-computed from the appropriate Zarr chunks.

If particles drift far enough that the patch would need to grow beyond its initial size, those particles are allowed to reach the patch boundary and are treated as leaving the domain (deactivated). Use a generous patch_buffer to prevent this.

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) – Full-grid static 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.

  • max_iter (int) – Maximum sub-cycles.

  • 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 per 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.

  • no_wflux (bool, optional) – Ignore vertical fluxes. 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().

  • patch_buffer (int) – Extra cells added on every side of the particle bounding box.

  • patch_granularity (int, optional) – Patch dimensions are rounded up to the nearest multiple of this value. Limits the number of distinct patch shapes and therefore XLA recompilations as the particle cloud spreads. Default 100.

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

  • 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. Default 1.

  • rampup_windows (int, optional) – Extra event_type="rampup" saves in the first windows, as in time_dependent().

  • rampup_substeps (int, optional) – Extra event_type="rampup" saves in the first windows, as in time_dependent().

  • 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 with final positions in **global** grid coordinates.

Return type:

ParticleState