API Reference¶

PyAERMOD v1.5 is organized into 29 modules grouped by workflow stage. For a stable, versioned public surface prefer from pyaermod.api import ... — it re-exports every documented name from a single module so your code doesn't depend on internal layout.

Project building¶

Build, read, write, and validate AERMOD input files.

Module	Description
input_generator	Thin facade + `AERMODProject` — `project.write()`, `project.to_aermod_input()`
sources	All 12 source dataclasses, deposition params, `SourcePathway`, background concentrations
receptors	`CartesianGrid`, `PolarGrid`, `DiscreteReceptor`, `ReceptorPathway`
pathways	Enums + `ControlPathway`, `MeteorologyPathway`, `OutputPathway`, `EventPathway`
input_reader	Bidirectional — parse existing `.inp` files back into `AERMODProject`

Validation¶

Module	Description
validator	Per-field range + consistency checks; `Validator.validate()` runs advanced checks by default
validator_advanced	Cross-field checks (stack buoyancy, receptor extent, DFAULT consistency)
regulatory	EPA Appendix W 2017 / 2023 + Screening profile presets with `apply()` and `check()`

Execution¶

Module	Description
runner	`AERMODRunner`, `BatchRunner`, `run_aermod()` subprocess wrappers
runner_utils	Progress, failure diagnostics, batch resume, SLURM templates
cli	`pyaermod` command-line interface (`validate`, `run`, `parse`, `plotfile`, `profile`)

Outputs¶

Module	Description
output_parser	Parse `.out` files to pandas DataFrames
aermod_outputs	Readers for PLOTFILE / MAXIFILE / RANKFILE / SEASONHR / TOXXFILE / deposition
postfile	Binary POSTFILE (UNFORM) + text PLOT format

Visualization¶

Module	Description
visualization	Contour plots, interactive Folium maps, raster export
advanced_viz	3-D surfaces, wind roses, concentration animations

Meteorology¶

Module	Description
aermet	Stage 1 / 2 / 3 input-deck generation; `.SFC` and `.PFL` parsers
aermet_runner	`AERMETRunner.run_stage()`, `run_aermet_pipeline()`
met_ingest	ASOS 1-minute, NOAA ISD, IGRA upper-air, MMIF data ingest
met_qaqc	Missing-data, extremes, stability-consistency checks

Terrain¶

Module	Description
aermap	AERMAP input-file generation
terrain	DEM download, AERMAP runner, elevation pipeline
terrain_utils	NAD27/83/WGS84 datums, SRTM, mosaic, reproject, hill-height diagnostics
geospatial	UTM/WGS84 transforms, GIS export

Downwash¶

Module	Description
bpip	Building-downwash 36-sector projection engine
prime	GEP stack-height rule, PRIME cavity region, project-level BPIP application

Chemistry¶

Module	Description
chemistry_presets	OLM / PVMRM / GRSM factories, deposition defaults, project wiring helpers

GUI¶

Module	Description
gui_v2	7-tab NiceGUI app — browser + native desktop modes

Optional dependencies¶

Install the extras for the features you need:

Extras group	Install command	Enables
`viz`	`pip install pyaermod[viz]`	`visualization`, `advanced_viz`
`geo`	`pip install pyaermod[geo]`	`geospatial`, `terrain`, `terrain_utils` (DEM + UTM/WGS84)
`gui`	`pip install pyaermod[gui]`	`gui` (Streamlit web app — pulls in viz + geo)
`met`	`pip install pyaermod[met]`	`met_ingest` network fetchers (ISD / IGRA)
`hpc`	`pip install pyaermod[hpc]`	`runner_utils` progress + SLURM
`all`	`pip install pyaermod[all]`	Everything

Stability guarantees¶

Names re-exported from pyaermod.api form the stable public surface. The underlying module layout may change across minor releases (e.g. the v1.5 split of input_generator.py into sources.py / receptors.py / pathways.py), but the facade preserves backwards compatibility.

# Prefer this (stable)
from pyaermod.api import PointSource, AERMODProject, read_aermod_input

# Avoid this in published code (internal layout)
from pyaermod.sources import PointSource  # subject to change

Stable-core subset¶

If you want to stick to the minimum surface possible, check pyaermod.api.CORE_NAMES. That frozenset of ~30 names covers the project/source/receptor/pathway types, the runner and CLI, the input reader and output parser, and the two EPA Appendix W profiles + three NO2 chemistry presets. Any name in CORE_NAMES is guaranteed to keep its signature across every 1.x release — additions to the wider pyaermod.api.__all__ may happen at any minor version before they're promoted into CORE_NAMES.

from pyaermod.api import CORE_NAMES, API_VERSION
assert "AERMODProject" in CORE_NAMES  # always True in 1.x
print(f"pyaermod API v{API_VERSION}")