stilt.footprint.FootprintAccessor.enhancement

FootprintAccessor.enhancement(flux)

Return the modeled enhancement at the receptor, footprint times flux summed over the grid.

The flux is taken at each footprint cell center from the nearest flux cell (stilt.sampling.sample_field()). That is right for flux cells as large as the footprint’s or larger. A finer flux is an error, since each footprint cell would take one small flux cell in place of the mean over its area: put the flux on the footprint grid first, as an area-weighted mean (xESMF’s conservative regridding), or make the footprints on the flux’s grid (sim.calc_footprint(grid=...)). A flux on cells of the footprint’s size whose centers are offset from the footprint’s by more than a tenth of a cell gets a warning, since each footprint cell then straddles two flux cells.

Parameters:

flux (DataArray) – Surface flux on a lat/lon grid (y/x for a projected footprint), in µmol m⁻² s⁻¹ for an enhancement in ppm. A flux with a time dimension is read as steps that start at their labels, as aggregate and project.jacobian read them: each footprint hour takes the last flux step that starts at or before the hour’s start. A monthly flux labeled on the 1st gives every hour of July 20 July’s flux. An hour before the first label gets zero flux, and an hour after the last label takes the last step, since the labels do not say where it ends (add a step of zeros to end it). A flux labeled at the middle of its steps must be relabeled first: shift its labels back by half a step, flux.assign_coords(time=flux.time - half_step). The labels must strictly increase.

Returns:

Enhancement for each footprint time step. .sum() gives the total. A footprint already summed over time gives the total alone.

Return type:

DataArray

Raises:

ValueError – If the flux has a time dimension and the footprint has none, since a time-summed footprint cannot say which flux step each hour meets, if the flux cells are finer than the footprint’s, or if the flux’s time labels do not strictly increase (a repeated label is an error).