Package overview

BLDFM provides a modular framework for modelling atmospheric dispersion and flux footprints in the planetary boundary layer (PBL). It numerically solves the three-dimensional steady-state advection-diffusion equation and computes Green’s function footprints for flux tower networks.

Core modules

1. bldfm.pbl_model

   Computes vertical profiles of horizontal wind and eddy diffusivity using Monin-Obukhov Similarity Theory (MOST).

   Key functions:

   • bldfm.pbl_model.vertical_profiles()

   • bldfm.pbl_model.psi()

   • bldfm.pbl_model.phi()

2. bldfm.solver

   Solves the steady-state advection-diffusion equation using FFT-based methods with linear shooting for the vertical boundary value problem.

   Key functions:

   • bldfm.solver.steady_state_transport_solver()

   • bldfm.solver.ivp_solver()

3. bldfm.utils

   Utility functions for wind field construction, source generation, and diagnostics.

   Key functions:

   • bldfm.utils.compute_wind_fields()

   • bldfm.utils.ideal_source()

   • bldfm.utils.point_measurement()

Configuration and interface

4. bldfm.config_parser

   YAML-based configuration with dataclass schema. Defines BLDFMConfig, TowerConfig, DomainConfig, MetConfig, and related classes.

5. bldfm.interface

   High-level functions that encapsulate the full workflow:

   • run_bldfm_single() – single tower, single timestep

   • run_bldfm_timeseries() – single tower, all timesteps

   • run_bldfm_multitower() – all towers, all timesteps

   • run_bldfm_parallel() – parallel execution over towers, time, or both

6. bldfm.cli

   Command-line interface: bldfm run config.yaml [--dry-run].

Data and I/O

7. bldfm.synthetic

   Generates synthetic meteorological timeseries and tower configurations for testing and prototyping.

8. bldfm.io

   NetCDF export and import of footprint results using xarray with CF-1.8 metadata.

9. bldfm.cache

   Disk-based cache for Green’s function results using SHA-256 keyed .npz files.

Plotting

10. bldfm.plotting

    Visualisation functions for footprint fields, geospatial map overlays, wind roses, and temporal footprint evolution.

Module interactions

• bldfm.pbl_model provides the vertical profiles required by bldfm.solver.

• bldfm.interface orchestrates the full pipeline (wind fields, profiles, solver) driven by bldfm.config_parser.

• bldfm.cache accelerates repeated solves by caching Green’s functions.

• bldfm.io saves and loads multi-tower, multi-timestep results.

• bldfm.plotting visualises solver outputs.

API reference

For detailed information on functions and usage, refer to the API Documentation.