tracmass.new_flux#

tracmass.new_flux(grid_or_fluxes, fluxes=None, dtm_start=None, dtm_end=None)[source]#

Create the lazy two-slot flux buffer for a run.

Two call forms:

new_flux(fluxes, dtm_start=..., dtm_end=None) -> (GridFields, LazyFluxFields): Build the grid and the flux buffer together. Equivalent to g = new_grid(fluxes, ...); return g, new_flux(g, fluxes, ...) but fetching slot 0 only once. This is the original signature and return type.
new_flux(grid, fluxes, dtm_start=..., dtm_end=None) -> LazyFluxFields: Reuse a GridFields from new_grid() (or an earlier new_flux); build only the flux buffer. grid.reverse and grid.timestep drive direction and step size; dtm_end, if given, is only checked for consistency with grid.reverse.

Flux data (uflux, vflux, wflux, dzt, zstot) is kept as lazy xarray DataArrays and not loaded into device memory until compute() is called. For a backward run (grid.reverse) slot 1 is one grid.timestep further into the past, the velocity fluxes are negated lazily, and each update_flux() call walks lazy.dtm backward through the archive. The fluxes callable is never passed reverse=.

Parameters:

grid_or_fluxes (GridFields or callable or str) – A GridFields selects the grid-reuse form; anything else is the fluxes callable / adapter name of the combined form.
fluxes (callable or str, optional) – The fluxes(dtm) -> xr.Dataset callable (or adapter name). Required — and only used — in the grid-reuse form.
dtm_start (pd.Timestamp or str or None, optional) – Physical time of slot 0 (past). Default None — fluxes is called with no arguments at all, so its own default applies (for gcm.glorys/gcm.ecco2 this falls through to tracmass.seagrid.glorys.open_dataset() / tracmass.seagrid.ecco2.open_dataset()’s own dtm default).
dtm_end (pd.Timestamp or str or None, optional) – When earlier than the resolved dtm_start, activates backward tracking (combined form) or is checked against grid.reverse (grid-reuse form). Stored as lazy.dtm_end, so lazy.n_windows gives the number of windows to reach it and the time_dependent* integrators need no n_windows.

Returns:

tuple[GridFields, LazyFluxFields] or LazyFluxFields – A (grid, lazy) tuple for the combined form; just lazy for the grid-reuse form. lazy.dtm holds the slot-0 timestamp; lazy.timestep / lazy.reverse mirror the grid.

Return type:

tuple[GridFields, LazyFluxFields] | LazyFluxFields