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.cache

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

Plotting

9. Plotting functions (footprint fields, geospatial map overlays, wind roses, temporal footprint evolution) are provided by abl-tk. Import them from abltk.plotting (see Shared infrastructure below).

Pipeline architecture

The solver pipeline proceeds in four stages. The high-level interface (bldfm.interface) runs all four automatically; the low-level API lets you call each stage individually.

                 YAML file / dict
                       │
              load_config / parse_config_dict
                       │
                       ▼
                  BLDFMConfig
                       │
       ┌───────────────┼────────────────┐
       │          High-level            │
       │   run_bldfm_single/timeseries  │
       │   run_bldfm_multitower         │
       │   run_bldfm_parallel           │
       └───────────────┬────────────────┘
                       │  internally calls ▼
         ┌─────────────┼─────────────────┐
         │                               │
         ▼                               │
compute_wind_fields()  [utils]           │
         │                               │
         ▼                               │
vertical_profiles()    [pbl_model]       │
         │                               │
         ▼                               │
ideal_source()         [utils]           │
         │             (if no flux given)│
         ▼                               │
steady_state_transport_solver()  [solver]│
         │                               │
         └───────────────┬───────────────┘
                         ▼
              result dict {grid, conc, flx, …}
                         │
           ┌─────────────┼──────────────────┐
           │             │                  │
           ▼             ▼                  ▼
   GreensFunctionCache  save_netcdf()     plot_*()
       [cache]         [abltk.io]       [abltk.plotting]

Design philosophy: high-level vs. low-level API

BLDFM exposes two tiers of API, each targeting a different use case.

High-level API — bldfm.interface

The four run_bldfm_* functions accept a BLDFMConfig object and return result dictionaries. Configuration objects carry every parameter (domain, towers, meteorology, solver options), making runs reproducible from a single YAML file. Use this tier for production science workflows, batch runs, and the CLI.

Low-level API — individual modules

The core functions vertical_profiles(), steady_state_transport_solver(), compute_wind_fields(), and ideal_source() can be called directly with plain NumPy arrays and scalars. This gives full control over intermediate results and is suited for custom parameter sweeps, debugging, or building new wrappers. Note that vertical_profiles() is intentionally not re-exported in the top-level __all__; import it explicitly from bldfm.pbl_model when working at this level.

Choosing a tier. Start with the high-level API. Drop to the low-level API when you need to inspect or modify intermediate quantities (e.g. vertical profiles), run the solver with non-standard inputs, or integrate BLDFM into a larger modelling framework.

Shared infrastructure (abl-tk)

BLDFM shares I/O, plotting, logging, and configuration utilities with abl-tk, a companion library that avoids code duplication across the framework. abl-tk is installed automatically as a dependency of BLDFM.

Plotting and I/O functions that were previously available in bldfm.plotting and bldfm.io have been moved to abltk. Import them directly:

from abltk.plotting import plot_footprint_field, plot_footprint_on_map
from abltk.io.netcdf import save_netcdf, load_netcdf

API reference

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