tracmass.update_flux#

tracmass.update_flux(*args, fluxes_fn=None)[source]#

Advance the flux buffer by one timestep using a rolling two-slot window.

Two call forms:

update_flux(lazy, fluxes_fn=None) -> LazyFluxFields

Step size and direction come from lazy.timestep / lazy.reverse (set by new_flux()), and fluxes_fn defaults to lazy.fluxes_fn.

update_flux(grid, lazy, fluxes_fn) -> LazyFluxFields

Older form: step size and direction come from grid.timestep / grid.reverse. Still needed for a lazy built by lower-level helpers that do not record timestep.

The time-slot swap is a pure Python dict reference assignment — the old present slot’s DataArrays become the new past slot at zero cost. Only a single call to fluxes_fn is made to load the next timestep’s DataArrays (still lazy for Dask-backed sources).

No Dask computation, no JAX operations, and no GC are needed here; all I/O is deferred until the next compute() call.

The timestep is always positive; for backward runs (reverse is True) lazy.dtm decrements by one timestep per call. The fluxes_fn callable is invoked without reverse= — flux negation is applied by this function after loading.

Parameters:

  • *args – (lazy,), (lazy, fluxes_fn) or (grid, lazy, fluxes_fn); see the call forms above. lazy.dtm is the physical timestamp of the current past (slot 0) time level.

  • fluxes_fn (callable, optional) – fluxes_fn(dtm) -> xr.Dataset for the next window. Defaults to lazy.fluxes_fn.

Returns:

LazyFluxFields – New lazy flux data with dtm advanced (forward) or decremented (backward) by one timestep; all other metadata is carried over.

Raises:

  • TypeError – On a wrong number of positional arguments.

  • ValueError – If no fluxes_fn is given and lazy.fluxes_fn is unset, or if the timestep is unknown (a lazy without timestep needs the (grid, lazy, fluxes_fn) form).

Return type:

LazyFluxFields

Examples

>>> grid, lazy = new_flux(gcm.theoretical.fluxes)
>>> lazy = update_flux(lazy)