Quickstart tutorial

BLDFM computes flux footprints and atmospheric dispersion fields for eddy-covariance tower networks by solving the steady-state advection-diffusion equation. This guide gets you from installation to your first footprint plot in about 5 minutes.

Prerequisites: Python >= 3.10 (a conda environment is recommended) and the BLDFM repository cloned locally. All commands below assume you are in the repository root.

Step 1: Install

$ pip install -e .

# Optional: plotting extras (contextily, windrose, plotly)
$ pip install -e ".[plotting]"

Verify the installation:

$ python -c "import bldfm; print('BLDFM imported successfully')"

Step 2: Initialize and load a config

import bldfm

bldfm.initialize()

config = bldfm.load_config("examples/configs/footprint.yaml")

print(f"Domain: {config.domain.nx} x {config.domain.ny}, nz={config.domain.nz}")
print(f"Tower: {config.towers[0].name} at z={config.towers[0].z_m} m")
print(f"Mode: {'footprint' if config.solver.footprint else 'concentration'}")

Expected output:

Domain: 512 x 256, nz=32
Tower: tower_1 at z=10.0 m
Mode: footprint

initialize() creates the logs/ and plots/ directories and configures logging. It only runs once – subsequent calls are no-ops.

Step 3: Run the solver and plot

Compute a footprint and visualise it with 50 % and 80 % cumulative contours:

from bldfm import run_bldfm_single, plot_footprint_field
import matplotlib
matplotlib.use("Agg")          # use "TkAgg" or remove for interactive display
import matplotlib.pyplot as plt

result = run_bldfm_single(config, config.towers[0])

print(f"Result keys: {sorted(result.keys())}")
print(f"Footprint shape: {result['flx'].shape}")

ax = plot_footprint_field(
    result["flx"], result["grid"],
    contour_pcts=[0.5, 0.8],
    title="My first BLDFM footprint",
)
plt.savefig("plots/tutorial_first_footprint.png", dpi=150, bbox_inches="tight")
print("Saved plots/tutorial_first_footprint.png")

You should see a 2D pcolormesh of a neutral footprint with two dashed contour lines (50 % and 80 % cumulative footprint). The footprint plume extends upwind of the tower position.

Step 4: Command-line alternative

The same workflow is available from the shell via the bldfm CLI:

# Validate the config without running the solver
$ bldfm run examples/configs/footprint.yaml --dry-run

# Run the full solve
$ bldfm run examples/configs/footprint.yaml

# Run and save footprint plots to plots/
$ bldfm run examples/configs/footprint.yaml --plot

The --dry-run flag prints the parsed configuration and exits. The --plot flag saves a footprint PNG for each tower and timestep to plots/.

Next steps

  • Full Tutorial: Learn the complete API – configuration, timeseries, multi-tower, parallel execution, I/O, and all plotting functions.

  • Quick Reference: Concise code snippets for common workflows.

  • API Reference: Detailed documentation for all modules and functions.