fluxfootprints package

Submodules

fluxfootprints.compare module

fluxfootprints.ep_footprint module

fluxfootprints.ffp_xr module

class fluxfootprints.ffp_xr.ffp_climatology_new(df: DataFrame, domain: ndarray = [-1000.0, 1000.0, -1000.0, 1000.0], dx: int = 10.0, dy: int = 10.0, nx: int = 1000, ny: int = 1000, rs: list | ndarray = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8], crop_height: float = 0.2, atm_bound_height: float = 2000.0, inst_height: float = 2.0, rslayer: bool = False, smooth_data: bool = True, crop: bool = False, verbosity: int = 2, fig: bool = False, logger=None, time=None, crs: int = None, station_x: float = None, station_y: float = None, **kwargs)

Bases: object

Create a footprint‑climatology from a series of individual flux‑footprint estimates using the simple 2‑D parameterisation of Kljun et al. (2015).

The routine

1. computes a footprint for every time step,

2. rotates each footprint into its observed wind direction,

3. aggregates all footprints onto a common grid, and

4. derives user‑requested source‑area contours (rs).

The implementation is based on:

Kljun, N., Calanca, P., Rotach, M. W., & Schmid, H. P. (2015). A simple two‑dimensional parameterisation for flux‑footprint predictions (FFP). Geoscientific Model Development, 8, 3695‑3713. https://doi.org/10.5194/gmd‑8‑3695‑2015

Parameters:

zmfloat or 1‑D array_like

Measurement height above displacement height (i.e.z – d) [m].

z0float or 1‑D array_like or None

Surface roughness length [m]. Either z0 or umean must be provided; if both are given, z0 takes precedence.

umeanfloat or 1‑D array_like or None

Mean wind speed at zm [m s⁻¹].

h1‑D array_like

Boundary‑layer height [m].

ol1‑D array_like

Obukhov length [m].

sigmav1‑D array_like

Standard deviation of lateral velocity fluctuations [m s⁻¹].

ustar1‑D array_like

Friction velocity [m s⁻¹].

wind_dir1‑D array_like

Wind direction in degrees (0–360°, meteorological convention).

Methods

smooth_and_contour([rs])

Compute footprint climatology using xarray structures for efficient, vectorized operations.

calc_xr_footprint
create_xr_dataset
define_domain
prep_df_fields
raise_ffp_exception
run

Returns:

FFPdict

Dictionary with keys (see below) carrying the climatology results.

x_2d, y_2dndarray

2‑D grids (mesh‑grids) of x and y coordinates [m].

fclim_2dndarray

Normalised footprint‑climatology values [m⁻²].

rsndarray or None

Echo of input rs in percent, or None when rs was None.

frndarray or None

Footprint value at each rs contour.

xr, yrlist[ndarray] or None

x‑ and y‑coordinates of every rs contour line.

nint

Number of individual footprints used in the aggregation.

flag_err{0, 1, 2, 3}

Error/status flag: 0 no error, 1 fatal error, 2 some contours outside domain, 3 invalid input rows removed.

Other Parameters:

domainarray_like of float, optional

Domain limits [xmin, xmax, ymin, ymax] [m]. Default is the smaller of

• the minimal rectangle that contains the r % footprint, or

• [-1000, 1000, -1000, 1000].

dx, dyfloat, optional

Grid‑cell size in x and y [m]. Defaults to 2 m. If only dx is given, dy = dx.

nx, nyint, optional

Number of grid cells in x and y. Defaults to 1000×1000. Ignored when dx/dy and domain are supplied (cell size wins).

rsfloat or sequence of float, optional

Source‑area percentages for which contour lines are returned, e.g.80 or [10, 30, 80]. Values may be expressed as percentages (80) or fractions (0.8). Must be 10–90 %. Default is np.arange(10, 90, 10). Use None to skip contour calculations.

rslayer{0, 1}, optional

If 1, allow calculations when zm lies in the roughness sub‑layer (RS). Warning: the model is formally invalid within the RS, so results are only indicative. Requires z0. Default is 0.

smooth_data{0, 1}, optional

Apply a convolution filter to smooth the footprint climatology. Default is 1 (smooth).

crop{0, 1}, optional

Crop the output grid to the extent of the largest requested contour (rs) or, if rs is None, the 80 % contour. Default 0.

pulseint, optional

Print progress every pulse footprints. Default is no output.

verbosity{0, 1, 2}, optional

Verbosity level: 0 = silent, 1 = only fatal messages, 2 = chatty. Default 2.

fig{0, 1}, optional

Plot an example footprint on screen when set to 1. Default 0.

Notes

Implemented by N. Kljun & G. Fratini, originally in MATLAB, ported to Python 3.x (v 1.4, 11 Dec 2019).

Examples

>>> from fluxfootprints import ffp_climatology_new
>>> clim = ffp_climatology_new(
...     zm=2.5,
...     z0=0.1,
...     h=h_series,
...     ol=ol_series,
...     sigmav=sigmav_series,
...     ustar=ustar_series,
...     wind_dir=wd_series,
... )
>>> clim["fclim_2d"].shape
(1000, 1000)

calc_xr_footprint()

create_xr_dataset()

define_domain()

prep_df_fields(h_c=0.2, d_h=None, zm_s=2.0, h_s=2000.0)

raise_ffp_exception(code)

run()

smooth_and_contour(rs=[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8])

Compute footprint climatology using xarray structures for efficient, vectorized operations.

Parameters:

• rs (list) – Contour levels to compute.

• smooth_data (bool) – Whether to smooth data using Gaussian filtering.

Returns:

Aggregated footprint climatology.

Return type:

xr.Dataset

fluxfootprints.footprint_plotting module

fluxfootprints.improved_ffp module

Improved Flux Footprint Prediction (FFP) Module

This module implements the FFP model described in: Kljun, N., P. Calanca, M.W. Rotach, H.P. Schmid, 2015: A simple two-dimensional parameterisation for Flux Footprint Prediction (FFP). Geosci. Model Dev. 8, 3695-3713, doi:10.5194/gmd-8-3695-2015

This version includes improvements for better alignment with the theoretical framework.

class fluxfootprints.improved_ffp.FFPModel(df: DataFrame, domain: list = [-1000.0, 1000.0, -1000.0, 1000.0], dx: float = 10.0, dy: float = 10.0, nx: int = 1000, ny: int = 1000, rs: list = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9], crop_height: float = 0.2, atm_bound_height: float = 2000.0, inst_height: float = 2.0, rslayer: bool = False, smooth_data: bool = True, crop: bool = False, verbosity: int = 2, logger=None, **kwargs)

Bases: object

Flux Footprint Prediction (FFP) model based on Kljun et al. (2015).

This class implements an improved version of the flux footprint model for determining the source area of scalar fluxes measured by eddy covariance towers. It uses atmospheric stability, wind parameters, and terrain configurations to calculate spatial footprints.

Attributes:

REQUIRED_COLUMNSlist of str

Names of required columns in the input DataFrame.

dfpandas.DataFrame

Copy of the input DataFrame used for modeling.

domainlist of float

Spatial domain defined as [xmin, xmax, ymin, ymax].

fclim_2dxarray.DataArray or None

Final footprint climatology after all processing.

f_2dxarray.DataArray or None

Instantaneous 2D footprint estimate.

loggerlogging.Logger

Logger instance for model-level debugging.

Methods

apply_paper_smoothing()	Apply 3x3 smoothing kernel from the Kljun et al. paper.
apply_rsl_corrections()	Apply roughness sublayer (RSL) corrections to crosswind dispersion.
calc_2d_footprint(f_ci_dummy, sigy_dummy)	Calculate the two-dimensional footprint distribution f(x,y).
calc_crosswind_dispersion(xstar_ci_dummy, px)	Compute dimensionless crosswind dispersion with safety checks.
calc_crosswind_extent(r, x_ru, x_rd)	Calculate crosswind extent of source area using parameterized relationships.
calc_crosswind_integrated_extent(r)	Calculate crosswind-integrated footprint extent for relative contribution r.
calc_crosswind_integrated_footprint(x_star)	Calculate the scaled crosswind-integrated footprint F̂y*(X̂*).
calc_crosswind_spread(x)	Calculate the standard deviation of cross-wind spread \(\sigma_y\).
calc_crosswind_spread_xr(x_star)	Calculate the standard deviation of crosswind spread σy.
calc_peak_based_limits(r)	Calculate upwind and downwind distances from the peak location for fraction r.
calc_pi_4()	Calculate Π4 with comprehensive stability function implementation including neutral conditions.
calc_real_footprint_peak(zm, h[, u_zm, ...])	Calculate the real-scale footprint peak location.
calc_scaled_distance_rsl()	Calculate scaled distance X* with roughness sublayer correction.
calc_scaled_footprint_peak()	Calculate the scaled footprint peak location (X*max).
calc_scaled_x(x)	Calculate the scaled distance X* based on wind and height parameters.
calc_unstable_psi(stability_param)	Calculate ψM for unstable atmospheric conditions.
calc_xr_footprint()	Compute the flux footprint using xarray operations.
calculate_pi_groups()	Calculate dimensionless Π groups for analysis.
calculate_source_areas()	Compute source areas for all specified relative contributions.
check_rsl_validity()	Check if the measurement height is above the roughness sublayer.
check_validity_ranges()	Check validity ranges according to equation 27 and other constraints from Kljun et al. (2015).
create_xr_dataset()	Create xarray Dataset from input DataFrame.
define_domain()	Define the spatial computational domain and polar coordinate grids.
get_scalar_value(arr)	Convert an array-like object to a scalar float value.
get_source_area_contour(r, x_ru, x_rd, y_r)	Generate a contour dataset for a given source area.
handle_stability_regimes()	Classify stability regimes and assign model parameters based on regime.
initialize_model_parameters()	Initialize core model parameters (a, b, c, d, ac, bc, cc).
plot_footprint([config, ax, show_contours, ...])	Plot the footprint climatology with optional contours.
prep_df_fields(crop_height, inst_height, ...)	Prepare and normalize input DataFrame fields for footprint calculation.
run([return_result])	Execute the FFP model calculations.
save_results(filename)	Save model results to a netCDF file.
scale_crosswind_dispersion(sigystar_dummy)	Scale the dimensionless crosswind dispersion σy* to real-scale σy.
scale_to_real_distance(x_star)	Convert scaled distance to real distance using Eq.
verify_data(data, name)	Verify the content and structure of a DataArray.
verify_results(data[, name])	Check for NaN or infinite values in the given data.

REQUIRED_COLUMNS = ['sigmav', 'ustar', 'ol', 'wind_dir', 'umean']

apply_paper_smoothing()

Apply 3x3 smoothing kernel from the Kljun et al. paper.

Returns:

xarray.DataArray

Smoothed footprint climatology.

apply_rsl_corrections()

Apply roughness sublayer (RSL) corrections to crosswind dispersion.

calc_2d_footprint(f_ci_dummy, sigy_dummy)

Calculate the two-dimensional footprint distribution f(x,y).

Implementation of Equation 10 from Kljun et al. (2015): f(x,y) = fy(x) * (1/(sqrt(2π)σy)) * exp(-y^2/(2σy^2))

Where: - fy(x) is the crosswind-integrated footprint - σy is the standard deviation of crosswind spread - y is the crosswind distance from the centerline

Parameters:

• f_ci_dummy – Crosswind-integrated footprint

• sigy_dummy – Scaled crosswind dispersion

Returns:

Two-dimensional footprint [m^-2]

Return type:

xr.DataArray

calc_crosswind_dispersion(xstar_ci_dummy, px)

Compute dimensionless crosswind dispersion with safety checks.

Parameters:

xstar_ci_dummyxarray.DataArray

Scaled distance.

pxbool

Condition flag.

Returns:

xarray.DataArray

Dimensionless crosswind dispersion.

calc_crosswind_extent(r: float, x_ru: DataArray, x_rd: DataArray) → DataArray

Calculate crosswind extent of source area using parameterized relationships.

Parameters:

• r – Relative contribution

• x_ru – Upwind distance from peak

• x_rd – Downwind distance from peak

Returns:

Crosswind extent at each distance

Return type:

xr.DataArray

calc_crosswind_integrated_extent(r: float) → DataArray

Calculate crosswind-integrated footprint extent for relative contribution r. Following Equations 23-25 of the paper.

Parameters:

r – Relative contribution (between 0.1 and 0.9)

Returns:

Distance from receptor containing fraction r of footprint

Return type:

xr.DataArray

calc_crosswind_integrated_footprint(x_star)

Calculate the scaled crosswind-integrated footprint F̂y*(X̂*).

Parameters:

x_starxarray.DataArray

Scaled distance from the receptor.

Returns:

xarray.DataArray

The scaled crosswind-integrated footprint.

calc_crosswind_spread(x: float | ndarray) → float | ndarray

Calculate the standard deviation of cross-wind spread \(\sigma_y\).

Implements Eqs. 18-19 from Kljun et al., 2015:

\[\sigma_y^* = a_c \sqrt{\]

rac{b_c lvert X^* vert^2}

{1 + c_c lvert X^*

vert}}

sigma_y =

rac{sigma_y^*}{ ext{scale_const}}

; z_m ; sigma_v / u_*

where

• \(a_c = 2.17\)

• \(b_c = 1.66\)

• \(c_c = 20.0\)

• scale_const depends on stability (see paper).

Parameters:

xfloat or ndarray

Up-wind distance from the receptor [m].

Returns:

float or ndarray

Cross-wind spread \(\sigma_y\) [m].

calc_crosswind_spread_xr(x_star)

Calculate the standard deviation of crosswind spread σy.

Implements Equations 18-19 from Kljun et al. (2015): σy* = ac * sqrt((bc * |X*|^2)/(1 + cc|X*|))

Where ac=2.17, bc=1.66, cc=20.0 (Equation 19)

Real-scale σy is then obtained through: σy = σy*/(scale_const) * zm * σv/u*

Where scale_const depends on stability (Eq. not numbered in paper): - For unstable: 1e-5|zm/L|^(-1) + 0.80 - For stable: 1e-5|zm/L|^(-1) + 0.55

Parameters:

x_star (float or array) – Distance from receptor [m]

Returns:

Standard deviation of crosswind spread [m]

calc_peak_based_limits(r: float) → Tuple[DataArray, DataArray]

Calculate upwind and downwind distances from the peak location for fraction r. Following Eq. 26 of the paper.

Parameters:

r – Relative contribution (between 0.1 and 0.9)

Returns:

Tuple containing upwind and downwind distances from peak

calc_pi_4()

Calculate Π4 with comprehensive stability function implementation including neutral conditions.

Returns:

xr.DataArray

Calculated Π4 values with proper neutral condition handling

calc_real_footprint_peak(zm: float | DataArray, h: float | DataArray, u_zm: float | DataArray = None, ustar: float | DataArray = None, z0: float | DataArray = None, k: float = 0.4) → float | DataArray

Calculate the real-scale footprint peak location. Based on Equations 20-22 of Kljun et al. (2015). Works with both scalar values and xarray DataArrays.

Parameters:

• zm – Measurement height [m]

• h – Boundary layer height [m]

• u_zm – Mean wind speed at measurement height [m/s], optional

• ustar – Friction velocity [m/s], optional

• z0 – Roughness length [m], optional

• k – von Karman constant (default=0.4)

Returns:

Real distance to footprint peak [m] Returns DataArray if inputs are DataArrays, float if inputs are scalars

calc_scaled_distance_rsl()

Calculate scaled distance X* with roughness sublayer correction.

Returns:

xarray.DataArray

Corrected scaled distance.

calc_scaled_footprint_peak() → float

Calculate the scaled footprint peak location (X*max). Based on Equation 20 of Kljun et al. (2015).

Returns:

Scaled distance to footprint peak (constant)

Return type:

float

calc_scaled_x(x: float | ndarray) → float | ndarray

Calculate the scaled distance X* based on wind and height parameters.

Parameters:

xfloat or ndarray

Upwind distance from the receptor.

Returns:

float or ndarray

Scaled distance X*.

calc_unstable_psi(stability_param)

Calculate ψM for unstable atmospheric conditions.

Parameters:

stability_paramxarray.DataArray

Stability parameter zm/L.

Returns:

xarray.DataArray

Stability correction ψM.

calc_xr_footprint()

Compute the flux footprint using xarray operations.

Returns:

xarray.DataArray

Climatological flux footprint.

calculate_pi_groups()

Calculate dimensionless Π groups for analysis.

Returns:

tuple of xarray.DataArray

Π₁, Π₂, Π₃, Π₄ values.

calculate_source_areas()

Compute source areas for all specified relative contributions.

Returns:

dict

Dictionary of contour datasets by contribution level.

check_rsl_validity()

Check if the measurement height is above the roughness sublayer.

Returns:

pandas.Series

Boolean mask of valid rows.

check_validity_ranges()

Check validity ranges according to equation 27 and other constraints from Kljun et al. (2015).

Implements the following validity checks: 1. Height validity (Eq. 27): 20z₀ < zm < he

where he ≈ 0.8h is the entrainment height

2. Stability validity (Eq. 27): -15.5 ≤ zm/L

3. Turbulence validity: u* > 0.1 m/s, σv > 0

4. Roughness sublayer validity: zm > z* ≈ n*hrs where hrs ≈ 10z₀ and 2 ≤ n ≤ 5 (Section 2)

Returns:

xr.Dataset: Dataset containing boolean masks for:

• height_valid: True where 20z₀ < zm < he

• stability_valid: True where -15.5 ≤ zm/L

• turbulence_valid: True where u* > 0.1 and σv > 0

• rsl_valid: True where measurement height above RSL

Combined validity is stored in self.valid_footprint

create_xr_dataset()

Create xarray Dataset from input DataFrame.

define_domain()

Define the spatial computational domain and polar coordinate grids.

get_scalar_value(arr)

Convert an array-like object to a scalar float value.

Parameters:

arrarray-like or scalar

The value to be converted.

Returns:

float

A scalar representation of the input.

get_source_area_contour(r, x_ru, x_rd, y_r)

Generate a contour dataset for a given source area.

Parameters:

rfloat

Relative contribution (0 < r < 1).

x_rufloat

Upwind distance.

x_rdfloat

Downwind distance.

y_rfloat

Crosswind extent.

Returns:

xarray.Dataset

Contour dataset with coordinates and footprint values.

handle_stability_regimes()

Classify stability regimes and assign model parameters based on regime.

Returns:

xarray.Dataset

Dataset with regime-specific masks.

initialize_model_parameters()

Initialize core model parameters (a, b, c, d, ac, bc, cc). Ensures scalar values are assigned.

plot_footprint(config=None, ax=None, show_contours=True, levels=10)

Plot the footprint climatology with optional contours.

Parameters:

• config – Configuration object containing metadata (optional)

• ax – Matplotlib axis to plot on (optional)

• show_contours – Whether to show contour lines

• levels – Number of contour levels or list of levels

Returns:

matplotlib.figure.Figure, matplotlib.axes.Axes

prep_df_fields(crop_height: float, inst_height: float, atm_bound_height: float)

Prepare and normalize input DataFrame fields for footprint calculation.

Parameters:

crop_heightfloat

Vegetation height.

inst_heightfloat

Instrument height.

atm_bound_heightfloat

Atmospheric boundary layer height.

run(return_result: bool = True) → Dataset | None

Execute the FFP model calculations.

Parameters:

return_result – If True, returns complete results dataset

Returns:

Dataset containing footprint results

Return type:

Optional[xr.Dataset]

save_results(filename: str)

Save model results to a netCDF file.

Parameters:

filename – Path where the results should be saved

scale_crosswind_dispersion(sigystar_dummy)

Scale the dimensionless crosswind dispersion σy* to real-scale σy.

Implements the real-scale conversion described in Equations 12-13 and surrounding text of Kljun et al. (2015):

σy = σy*/(scale_const) * zm * σv/u*

where: - σy* is dimensionless crosswind dispersion - scale_const is stability-dependent scaling factor:

For L ≤ 0 (convective): scale_const = min(1, 10⁻⁵|zm/L|⁻¹ + 0.80) For L > 0 (stable): scale_const = min(1, 10⁻⁵|zm/L|⁻¹ + 0.55)

• zm is measurement height

• σv is standard deviation of lateral velocity fluctuations

• u* is friction velocity

Parameters:

sigystar_dummy (xarray.DataArray) – Dimensionless crosswind dispersion σy*

Returns:

Real-scale crosswind dispersion σy [m]

Return type:

xarray.DataArray

Note

Includes numerical safety checks to prevent division by zero and handle potential non-finite values in intermediate calculations.

scale_to_real_distance(x_star: DataArray) → DataArray

Convert scaled distance to real distance using Eq. 6/7.

Parameters:

x_star – Scaled distance X*

Returns:

Real-scale distance

Return type:

xr.DataArray

verify_data(data: DataArray, name: str) → bool

Verify the content and structure of a DataArray.

Parameters:

dataxarray.DataArray

Data array to check.

namestr

Variable name for logging.

Returns:

bool

True if valid, False otherwise.

verify_results(data, name='data')

Check for NaN or infinite values in the given data.

Parameters:

dataarray-like or xarray.DataArray

The data to verify.

namestr, optional

Descriptive name for logging.

fluxfootprints.tools module

fluxfootprints.volk module

Module contents