Package overview

This package provides a modular framework for modeling atmospheric dispersion processes, focusing on the planetary boundary layer (PBL) and scalar transport. It includes three core modules in src for computing vertical profiles, solving advection-diffusion equations, and providing utility functions for diagnostics and input generation. Example run scripts and a test suite are also included to demonstrate usage and ensure reliability.

Core modules in the src subpackage

1. src.pbl_model

   Computes vertical profiles of horizontal wind and eddy diffusivity in the planetary boundary layer using Monin-Obukhov Similarity Theory (MOST).

   Features:

   • Implements surface-layer closure via stability corrections.

   • Supports parameterizations of u_h(z), K_h(z), and K_z(z).

   • Easy to extend with more sophisticated turbulence closures.

   Key functions:

   • src.pbl_model.vertical_profiles()

   • src.pbl_model.psi()

   • src.pbl_model.phi()

2. src.solver

   Solves the steady-state advection-diffusion equation for scalar concentration fields using FFT-based methods and numerical integration schemes.

   Features:

   • Supports Fourier-transformed formulation for horizontal advection-diffusion.

   • Uses linear shooting for boundary value problems in the vertical.

   • Implements Green’s function solver for footprint modeling.

   Key functions:

   • src.solver.steady_state_transport_solver()

   • src.solver.ivp_solver()

3. src.utils

   Provides utility functions for preprocessing, synthetic input generation, and diagnostics.

   Features:

   • Source field generation (e.g., circular/point sources).

   • Wind field constructors and FFT utilities.

   • Pointwise convolution for footprint validation.

   Key functions:

   • src.utils.compute_wind_fields()

   • src.utils.point_source()

   • src.utils.ideal_source()

   • src.utils.point_measurement()

Additional subpackages

1. runs provides example workflows and pre-configured scripts to demonstrate the usage of the package. These scripts showcase how to combine the core modules (src.pbl_model, src.solver, and src.utils) for practical applications, such as footprint modeling or dispersion analysis.

   Features:

   • Example configurations for common use cases.

   • Demonstrates integration of vertical profiles, transport solvers, and diagnostics.

2. tests contains the test suite for validating the functionality and accuracy of the package. The tests ensure that the core modules (src.pbl_model, src.solver, and src.utils) work as expected and provide a framework for extending test coverage.

   Features:

   • Unit tests for individual functions.

   • Integration tests for workflows combining multiple modules.

   • Easy-to-run test scripts for contributors.

Module interactions

• src.pbl_model provides the vertical profiles required by the src.solver module.

• src.solver handles the core transport computation, optionally using Green’s functions for convolution with surface fluxes.

• src.utils supports both src.pbl_model and src.solver with reusable tools for test generation and output diagnostics.

• runs contains examples and user-defined run scripts that utilize the core modules.

• tests ensures the reliability and correctness of the package.

API reference

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