pyaermod 1.0.0__tar.gz

pyaermod-1.0.0/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+All notable changes to PyAERMOD will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-02-14
+
+### Added
+
+#### Source Types
+- **AreaSource** — rectangular area sources with rotation angle
+- **AreaCircSource** — circular area sources with configurable vertex count
+- **AreaPolySource** — irregular polygonal area sources
+- **VolumeSource** — 3D emission volumes with initial dispersion
+- **LineSource** — general linear sources (conveyors, pipelines)
+- **RLineSource** — roadway-specific sources with mobile source physics
+- **RLineExtSource** — extended roadway with per-endpoint elevations, optional barriers and road depression
+- **BuoyLineSource** / **BuoyLineSegment** — buoyant line source groups with BLPINPUT/BLPGROUP
+- **OpenPitSource** — open pit mine/quarry sources
+
+#### Modules
+- **Validator** (`pyaermod.validator`) — configuration validation for all 5 AERMOD pathways with cross-field checks
+- **BPIP** (`pyaermod.bpip`) — building downwash / BPIP integration with 36-direction building parameters
+- **AERMET** (`pyaermod.aermet`) — meteorological preprocessor input generation (Stages 1-3)
+- **AERMAP** (`pyaermod.aermap`) — terrain preprocessor input generation with `from_aermod_project()` bridge
+- **POSTFILE** (`pyaermod.postfile`) — POSTFILE output parser with timestep/receptor queries, auto-detection of text (PLOT) and binary (UNFORM) formats
+- **Geospatial** (`pyaermod.geospatial`) — coordinate transforms (UTM/WGS84), GeoDataFrame creation, contour generation, GeoTIFF/GeoPackage/Shapefile/GeoJSON export
+- **Terrain** (`pyaermod.terrain`) — DEM tile download from USGS TNM, AERMAP runner, output parser, elevation update pipeline
+- **GUI** (`pyaermod.gui`) — 7-page Streamlit web application for interactive AERMOD workflow
+
+#### Background Concentrations
+- `BackgroundConcentration` and `BackgroundSector` dataclasses for ambient background levels
+- Three modes: uniform value, period-specific values, or sector-dependent concentrations
+- `SourcePathway.background` field generating `BACKGRND` and `BGSECTOR` keywords
+
+#### Deposition Modeling
+- `DepositionMethod` enum (`DRYDPLT`, `WETDPLT`, `GASDEPVD`, `GASDEPDF`)
+- `GasDepositionParams` and `ParticleDepositionParams` for gas and particle deposition settings
+- Deposition fields added to all 10 source types with shared `_deposition_to_aermod_lines()` helper
+- `OutputPathway.output_type` for selecting concentration vs. deposition output
+
+#### EVENT Processing
+- `EventPeriod` and `EventPathway` dataclasses for event-based analysis
+- `ControlPathway.eventfil` for linking event file
+- `AERMODProject.write(event_filename=...)` generates EV pathway with `EVENTPER` records
+
+#### NO2 / SO2 Chemistry Options
+- `ChemistryMethod` enum: OLM, PVMRM, ARM2, GRSM
+- `ChemistryOptions` dataclass with method, default NO2/NOx ratio, and ozone data
+- `OzoneData` dataclass supporting ozone file, uniform value, or sector-specific values
+- `ControlPathway.chemistry` field generating `MODELOPT`, `O3VALUES`, `OZONEFIL`, `NOXFIL` keywords
+- Per-source `no2_ratio` field on `PointSource`
+
+#### Source Group Management
+- `SourceGroupDefinition` dataclass with group name, member source IDs, and description
+- `SourcePathway.group_definitions` generating `SRCGROUP` keywords
+- Per-group PLOTFILE output via `OutputPathway.plot_file_groups`
+
+#### Building Downwash Expansion
+- Building downwash (PRIME) fields extended from `PointSource` to also support `AreaSource` and `VolumeSource`
+- `_building_downwash_lines()` and `_set_building_from_bpip()` module-level helpers shared across source types
+- Terrain grid elevations via `CartesianGrid.terrain_elevations` and `PolarGrid.terrain_elevations`
+
+#### Binary POSTFILE Deposition
+- `UnformattedPostfileParser` now handles deposition records with `has_deposition` parameter (auto-detect or explicit)
+- Parses 3N floats into concentration, dry deposition, and wet deposition columns
+
+#### GUI Enhancements
+- **ProjectSerializer**: JSON save/load for complete session state with round-trip fidelity
+- **AreaCirc/AreaPoly forms** in SourceFormFactory
+- **BPIP integration**: building forms, BPIP calculator wired to point, area, and volume sources
+- **AERMAP elevation import**: 5th tab in receptor editor for terrain elevation upload
+- **AERMET configuration**: dual-mode meteorology page (existing files vs. 3-stage AERMET config)
+- **POSTFILE viewer**: 4th tab in Results Viewer with timestep slider, receptor time-series, animation GIF
+- **Chemistry Options UI**: NO2 chemistry configuration with method, ozone data, and NOx file inputs
+- **Source Groups UI**: create/delete source groups, per-group PLOTFILE checkboxes
+- **Statistics helpers**: cross-period summary table, ranked receptor table, model complexity indicator
+- **Export format detection**: dynamic format list based on installed optional dependencies
+
+#### Testing & Quality
+- 1166 tests across 18 test files, 95% code coverage
+- 315 EPA v24142 integration tests parsing official test case outputs
+- End-to-end mock pipeline tests (input generation → output parsing → visualization → postfile)
+- `conftest.py` with shared fixtures for all test files
+- Property-based testing with Hypothesis strategies for source types
+- `ruff` linting (replaced flake8) with comprehensive rule set
+- `.pre-commit-config.yaml` for automated lint on commit
+- Performance benchmarks in `benchmarks/` directory
+
+#### Documentation
+- 7 Jupyter tutorial notebooks (Getting Started through Advanced Features)
+- 7 example scripts (area sources, volume sources, line sources, BPIP, chemistry, deposition, end-to-end)
+- MkDocs documentation site with Material theme and mkdocstrings API reference
+
+### Changed
+- **Package layout**: moved from flat root modules to `src/pyaermod/` package structure
+- **Imports**: `from pyaermod.input_generator import ...` (was `from pyaermod_input_generator import ...`)
+- **Python**: minimum version raised to 3.11 (was 3.8) — required by NumPy 2.1+, SciPy 1.14+, Pandas 2.3+
+- Updated `setup.py` extras: added `[geo]`, `[gui]`, `[terrain]`, `[all]` dependency groups
+- CI matrix runs Python 3.11, 3.12, 3.13 with GDAL system dependencies
+
+## [0.1.0] - 2026-02-04
+
+### Added
+- **PointSource** with full stack parameters and building downwash (PRIME) support
+- **Receptor grids**: Cartesian, polar, and discrete receptors
+- **AERMOD input generation** for all 5 pathways (CO, SO, RE, ME, OU)
+- **Output parser**: parse `.out` files to pandas DataFrames, extract metadata, find max concentrations
+- **Visualization**: contour plots (matplotlib), interactive maps (folium)
+- **Runner**: `AERMODRunner` with subprocess execution, `BatchRunner` for parallel processing
+- Project setup: `setup.py`, MIT license, `.gitignore`
+
+---
+
+[Unreleased]: https://github.com/atmmod/pyaermod/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/atmmod/pyaermod/compare/v0.1.0...v1.0.0
+[0.1.0]: https://github.com/atmmod/pyaermod/releases/tag/v0.1.0

pyaermod-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,139 @@
+# Contributing to PyAERMOD
+
+Thank you for your interest in contributing to PyAERMOD! This guide covers
+the development workflow, coding standards, and submission process.
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/atmmod/pyaermod.git
+cd pyaermod
+
+# Install in editable mode with all dev dependencies
+pip install -e ".[dev,all]"
+
+# Install pre-commit hooks
+pre-commit install
+```
+
+### System Dependencies
+
+For geospatial features (GeoTIFF export, coordinate transforms), you need
+GDAL:
+
+```bash
+# Ubuntu / Debian
+sudo apt-get install libgdal-dev gdal-bin
+
+# macOS (Homebrew)
+brew install gdal
+```
+
+## Running Tests
+
+```bash
+# Run full test suite with coverage
+pytest
+
+# Run a specific test file
+pytest tests/test_input_generator.py
+
+# Run tests matching a keyword
+pytest -k "test_point_source"
+
+# Skip slow property-based tests
+pytest -m "not slow"
+```
+
+The project targets **89%+ code coverage**. New features should include
+tests that maintain or improve this threshold.
+
+## Code Style
+
+PyAERMOD uses [ruff](https://docs.astral.sh/ruff/) for linting and import
+sorting. Configuration is in `pyproject.toml`.
+
+```bash
+# Check for lint errors
+ruff check src/ tests/
+
+# Auto-fix where possible
+ruff check --fix src/ tests/
+```
+
+Key style rules:
+
+- **Line length**: 120 characters
+- **Python**: 3.11+ (type hints use `typing` module style, not `X | Y`)
+- **Imports**: sorted by ruff/isort with `pyaermod` as first-party
+- **Docstrings**: NumPy style
+- **Dataclasses**: used throughout for configuration objects
+
+## Project Layout
+
+```
+src/pyaermod/          # Package source (src layout)
+tests/                 # Test files (test_*.py)
+docs/                  # MkDocs documentation
+examples/              # Example scripts and notebooks
+benchmarks/            # Performance benchmarks
+```
+
+### Key Patterns
+
+- **Source types** are dataclasses with a `to_aermod_input() -> str` method
+- **Validation** uses `isinstance` dispatch in `validator.py`
+- **Optional dependencies** use `try/except ImportError` with `HAS_*` flags
+  and `_require_*()` guard functions
+- **GUI** uses Streamlit with `st.session_state` for state management
+
+## Adding a New Source Type
+
+1. Define the dataclass in `src/pyaermod/input_generator.py` following
+   existing patterns (e.g., `PointSource`)
+2. Implement `to_aermod_input()` to generate valid AERMOD keywords
+3. Add validation rules in `src/pyaermod/validator.py`
+4. Add the type to `SourceFormFactory.SOURCE_TYPES` in `gui.py`
+5. Update `__init__.py` exports and `__all__`
+6. Add tests in `tests/test_input_generator.py` and `tests/test_gui.py`
+7. Update documentation in `docs/quickstart.md`
+
+## Submitting Changes
+
+1. **Fork** the repository and create a feature branch
+2. **Write tests** for any new functionality
+3. **Run the full test suite**: `pytest`
+4. **Run the linter**: `ruff check src/ tests/`
+5. **Update documentation** if you changed user-facing behavior
+6. **Open a pull request** against `main` with a clear description
+
+### Commit Messages
+
+Use clear, descriptive commit messages:
+
+- `Add RLINEXT source type with barrier support`
+- `Fix POSTFILE binary parser for big-endian systems`
+- `Update quickstart guide with deposition examples`
+
+### Pull Request Checklist
+
+- [ ] Tests pass (`pytest`)
+- [ ] Linter passes (`ruff check src/ tests/`)
+- [ ] New features have tests
+- [ ] Documentation updated (if applicable)
+- [ ] CHANGELOG.md updated under `[Unreleased]`
+
+## Reporting Issues
+
+Please include:
+
+- Python version and OS
+- PyAERMOD version (`python -c "import pyaermod; print(pyaermod.__version__)"`)
+- Minimal reproducible example
+- Full error traceback
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
+MIT License.

pyaermod-1.0.0/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 Shannon Capps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+AERMOD Disclaimer:
+This software is a wrapper around the EPA's AERMOD atmospheric dispersion model.
+AERMOD is public domain software developed by the U.S. Environmental Protection Agency.
+This wrapper does not modify AERMOD's calculations and maintains regulatory compliance.
+Users must obtain the AERMOD executable separately from EPA's SCRAM website.

pyaermod-1.0.0/MANIFEST.in

@@ -0,0 +1,16 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include pyproject.toml
+
+recursive-include src/pyaermod *.py
+recursive-include tests *.py
+recursive-include docs *.md *.yml
+recursive-include examples *.py *.ipynb
+
+prune aermod
+prune aermap
+prune .github
+prune benchmarks
+prune .claude

pyaermod-1.0.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: pyaermod
+Version: 1.0.0
+Summary: Python wrapper for EPA's AERMOD air dispersion model
+Author-email: Shannon Capps <shannon.capps@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/atmmod/pyaermod
+Project-URL: Documentation, https://atmmod.github.io/pyaermod/
+Project-URL: Repository, https://github.com/atmmod/pyaermod
+Project-URL: Issues, https://github.com/atmmod/pyaermod/issues
+Project-URL: Changelog, https://github.com/atmmod/pyaermod/blob/main/CHANGELOG.md
+Keywords: aermod,air quality,dispersion,modeling,atmospheric
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: pandas>=1.3.0
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.3.0; extra == "viz"
+Requires-Dist: scipy>=1.7.0; extra == "viz"
+Requires-Dist: folium>=0.12.0; extra == "viz"
+Provides-Extra: geo
+Requires-Dist: pyproj>=3.0.0; extra == "geo"
+Requires-Dist: geopandas>=0.10.0; extra == "geo"
+Requires-Dist: rasterio>=1.2.0; extra == "geo"
+Requires-Dist: shapely>=1.8.0; extra == "geo"
+Requires-Dist: scipy>=1.7.0; extra == "geo"
+Provides-Extra: gui
+Requires-Dist: streamlit>=1.28.0; extra == "gui"
+Requires-Dist: streamlit-folium>=0.15.0; extra == "gui"
+Requires-Dist: folium>=0.14.0; extra == "gui"
+Requires-Dist: pyproj>=3.0.0; extra == "gui"
+Requires-Dist: geopandas>=0.10.0; extra == "gui"
+Requires-Dist: rasterio>=1.2.0; extra == "gui"
+Requires-Dist: shapely>=1.8.0; extra == "gui"
+Requires-Dist: scipy>=1.7.0; extra == "gui"
+Requires-Dist: matplotlib>=3.3.0; extra == "gui"
+Provides-Extra: terrain
+Requires-Dist: requests>=2.25.0; extra == "terrain"
+Provides-Extra: all
+Requires-Dist: matplotlib>=3.3.0; extra == "all"
+Requires-Dist: scipy>=1.7.0; extra == "all"
+Requires-Dist: folium>=0.14.0; extra == "all"
+Requires-Dist: pyproj>=3.0.0; extra == "all"
+Requires-Dist: geopandas>=0.10.0; extra == "all"
+Requires-Dist: rasterio>=1.2.0; extra == "all"
+Requires-Dist: shapely>=1.8.0; extra == "all"
+Requires-Dist: streamlit>=1.28.0; extra == "all"
+Requires-Dist: streamlit-folium>=0.15.0; extra == "all"
+Requires-Dist: requests>=2.25.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: hypothesis>=6.82.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# PyAERMOD
+
+Python wrapper for EPA's AERMOD atmospheric dispersion model.
+
+PyAERMOD automates input file generation, model execution, output parsing, and result visualization — replacing manual text-file editing with a type-safe Python API.
+
+## Installation
+
+```bash
+pip install pyaermod             # core (input generation + output parsing)
+pip install pyaermod[viz]        # + matplotlib/folium visualization
+pip install pyaermod[geo]        # + geospatial export (GeoTIFF, Shapefile)
+pip install pyaermod[gui]        # + Streamlit interactive GUI
+pip install pyaermod[all]        # everything
+```
+
+For development:
+```bash
+git clone https://github.com/atmmod/pyaermod.git
+cd pyaermod
+pip install -e ".[dev,all]"
+```
+
+## Quick Start
+
+### Generate AERMOD Input
+
+```python
+from pyaermod.input_generator import (
+    AERMODProject, ControlPathway, SourcePathway, ReceptorPathway,
+    MeteorologyPathway, OutputPathway, PointSource, CartesianGrid,
+    PollutantType, TerrainType,
+)
+
+control = ControlPathway(
+    title_one="My Facility",
+    pollutant_id=PollutantType.PM25,
+    averaging_periods=["ANNUAL", "24"],
+    terrain_type=TerrainType.FLAT,
+)
+
+sources = SourcePathway()
+sources.add_source(PointSource(
+    source_id="STACK1", x_coord=500.0, y_coord=500.0,
+    base_elevation=10.0, stack_height=50.0, stack_temp=400.0,
+    exit_velocity=15.0, stack_diameter=2.0, emission_rate=1.5,
+))
+
+receptors = ReceptorPathway()
+receptors.add_cartesian_grid(CartesianGrid.from_bounds(
+    x_min=0, x_max=2000, y_min=0, y_max=2000, spacing=100,
+))
+
+meteorology = MeteorologyPathway(
+    surface_file="met_data.sfc", profile_file="met_data.pfl",
+)
+output = OutputPathway(receptor_table=True, max_table=True)
+
+project = AERMODProject(control, sources, receptors, meteorology, output)
+project.write("facility.inp")
+```
+
+### Run AERMOD & Parse Results
+
+```python
+from pyaermod.runner import run_aermod
+from pyaermod.output_parser import parse_aermod_output
+
+result = run_aermod("facility.inp")
+results = parse_aermod_output(result.output_file)
+
+df = results.get_concentrations("ANNUAL")
+print(results.summary())
+```
+
+### Parse POSTFILE Output
+
+```python
+from pyaermod.postfile import read_postfile
+
+# Auto-detects text vs binary format
+post = read_postfile("postfile.out")
+df = post.to_dataframe()
+
+# Binary postfile with deposition data
+dep = read_postfile("depo_post.out", has_deposition=True)
+print(dep.to_dataframe()[["concentration", "dry_depo", "wet_depo"]])
+```
+
+## Features
+
+### Source Types (10)
+POINT, AREA, AREACIRC, AREAPOLY, VOLUME, LINE, RLINE, RLINEXT, BUOYLINE, OPENPIT
+
+### Advanced Modeling
+- **Background concentrations** — uniform, period-specific, or sector-dependent
+- **Deposition** — dry, wet, or combined for gas and particle emissions
+- **NO2/SO2 chemistry** — OLM, PVMRM, ARM2, GRSM with ozone data
+- **Source groups** — custom groupings with per-group PLOTFILE output
+- **EVENT processing** — date/receptor-specific analysis
+
+### Preprocessors
+- **AERMET** — meteorological data preprocessing (Stages 1-3)
+- **AERMAP** — terrain elevation extraction with DEM download pipeline
+
+### Analysis & Visualization
+- Output parsing to pandas DataFrames
+- POSTFILE parser for timestep-level results (text and binary formats)
+- Contour plots, interactive Folium maps, 3D surfaces, wind roses
+- Geospatial export: GeoTIFF, GeoPackage, Shapefile, GeoJSON
+
+### Validation & Automation
+- Input validation across all AERMOD pathways
+- Building downwash / BPIP integration (point, area, and volume sources)
+- Batch processing with parallel execution
+- Interactive Streamlit GUI (`pyaermod-gui`)
+
+## Project Structure
+
+```
+src/pyaermod/
+    __init__.py          # Public API
+    input_generator.py   # AERMOD input file generation (all source types)
+    validator.py         # Configuration validation
+    runner.py            # AERMOD subprocess execution
+    output_parser.py     # Output file parsing
+    postfile.py          # POSTFILE output parser
+    visualization.py     # Matplotlib/Folium plots
+    advanced_viz.py      # 3D surfaces, wind roses, animations
+    aermet.py            # AERMET preprocessor wrapper
+    aermap.py            # AERMAP input generation
+    terrain.py           # DEM download + AERMAP pipeline
+    geospatial.py        # Coordinate transforms, GIS export
+    bpip.py              # Building downwash calculations
+    gui.py               # Streamlit web GUI
+tests/                   # 1166 tests, 95% coverage
+examples/                # Example scripts and Jupyter notebooks
+docs/                    # Architecture and quickstart guides
+```
+
+## Requirements
+
+- Python >= 3.11
+- numpy, pandas (core)
+- AERMOD executable (free from [EPA SCRAM](https://www.epa.gov/scram))
+
+## Documentation
+
+- [Quick Start Guide](docs/quickstart.md)
+- [GUI User Guide](docs/gui-guide.md)
+- [Architecture](docs/architecture.md)
+- [API Reference](https://atmmod.github.io/pyaermod/api/)
+- [Examples](examples/)
+
+## License
+
+MIT
+
+## Disclaimer
+
+PyAERMOD is a wrapper around AERMOD, not a reimplementation. It uses official EPA binaries for all calculations and maintains regulatory acceptance. Always validate results against EPA test cases for your specific use case.

pyaermod-1.0.0/README.md

@@ -0,0 +1,161 @@
+# PyAERMOD
+
+Python wrapper for EPA's AERMOD atmospheric dispersion model.
+
+PyAERMOD automates input file generation, model execution, output parsing, and result visualization — replacing manual text-file editing with a type-safe Python API.
+
+## Installation
+
+```bash
+pip install pyaermod             # core (input generation + output parsing)
+pip install pyaermod[viz]        # + matplotlib/folium visualization
+pip install pyaermod[geo]        # + geospatial export (GeoTIFF, Shapefile)
+pip install pyaermod[gui]        # + Streamlit interactive GUI
+pip install pyaermod[all]        # everything
+```
+
+For development:
+```bash
+git clone https://github.com/atmmod/pyaermod.git
+cd pyaermod
+pip install -e ".[dev,all]"
+```
+
+## Quick Start
+
+### Generate AERMOD Input
+
+```python
+from pyaermod.input_generator import (
+    AERMODProject, ControlPathway, SourcePathway, ReceptorPathway,
+    MeteorologyPathway, OutputPathway, PointSource, CartesianGrid,
+    PollutantType, TerrainType,
+)
+
+control = ControlPathway(
+    title_one="My Facility",
+    pollutant_id=PollutantType.PM25,
+    averaging_periods=["ANNUAL", "24"],
+    terrain_type=TerrainType.FLAT,
+)
+
+sources = SourcePathway()
+sources.add_source(PointSource(
+    source_id="STACK1", x_coord=500.0, y_coord=500.0,
+    base_elevation=10.0, stack_height=50.0, stack_temp=400.0,
+    exit_velocity=15.0, stack_diameter=2.0, emission_rate=1.5,
+))
+
+receptors = ReceptorPathway()
+receptors.add_cartesian_grid(CartesianGrid.from_bounds(
+    x_min=0, x_max=2000, y_min=0, y_max=2000, spacing=100,
+))
+
+meteorology = MeteorologyPathway(
+    surface_file="met_data.sfc", profile_file="met_data.pfl",
+)
+output = OutputPathway(receptor_table=True, max_table=True)
+
+project = AERMODProject(control, sources, receptors, meteorology, output)
+project.write("facility.inp")
+```
+
+### Run AERMOD & Parse Results
+
+```python
+from pyaermod.runner import run_aermod
+from pyaermod.output_parser import parse_aermod_output
+
+result = run_aermod("facility.inp")
+results = parse_aermod_output(result.output_file)
+
+df = results.get_concentrations("ANNUAL")
+print(results.summary())
+```
+
+### Parse POSTFILE Output
+
+```python
+from pyaermod.postfile import read_postfile
+
+# Auto-detects text vs binary format
+post = read_postfile("postfile.out")
+df = post.to_dataframe()
+
+# Binary postfile with deposition data
+dep = read_postfile("depo_post.out", has_deposition=True)
+print(dep.to_dataframe()[["concentration", "dry_depo", "wet_depo"]])
+```
+
+## Features
+
+### Source Types (10)
+POINT, AREA, AREACIRC, AREAPOLY, VOLUME, LINE, RLINE, RLINEXT, BUOYLINE, OPENPIT
+
+### Advanced Modeling
+- **Background concentrations** — uniform, period-specific, or sector-dependent
+- **Deposition** — dry, wet, or combined for gas and particle emissions
+- **NO2/SO2 chemistry** — OLM, PVMRM, ARM2, GRSM with ozone data
+- **Source groups** — custom groupings with per-group PLOTFILE output
+- **EVENT processing** — date/receptor-specific analysis
+
+### Preprocessors
+- **AERMET** — meteorological data preprocessing (Stages 1-3)
+- **AERMAP** — terrain elevation extraction with DEM download pipeline
+
+### Analysis & Visualization
+- Output parsing to pandas DataFrames
+- POSTFILE parser for timestep-level results (text and binary formats)
+- Contour plots, interactive Folium maps, 3D surfaces, wind roses
+- Geospatial export: GeoTIFF, GeoPackage, Shapefile, GeoJSON
+
+### Validation & Automation
+- Input validation across all AERMOD pathways
+- Building downwash / BPIP integration (point, area, and volume sources)
+- Batch processing with parallel execution
+- Interactive Streamlit GUI (`pyaermod-gui`)
+
+## Project Structure
+
+```
+src/pyaermod/
+    __init__.py          # Public API
+    input_generator.py   # AERMOD input file generation (all source types)
+    validator.py         # Configuration validation
+    runner.py            # AERMOD subprocess execution
+    output_parser.py     # Output file parsing
+    postfile.py          # POSTFILE output parser
+    visualization.py     # Matplotlib/Folium plots
+    advanced_viz.py      # 3D surfaces, wind roses, animations
+    aermet.py            # AERMET preprocessor wrapper
+    aermap.py            # AERMAP input generation
+    terrain.py           # DEM download + AERMAP pipeline
+    geospatial.py        # Coordinate transforms, GIS export
+    bpip.py              # Building downwash calculations
+    gui.py               # Streamlit web GUI
+tests/                   # 1166 tests, 95% coverage
+examples/                # Example scripts and Jupyter notebooks
+docs/                    # Architecture and quickstart guides
+```
+
+## Requirements
+
+- Python >= 3.11
+- numpy, pandas (core)
+- AERMOD executable (free from [EPA SCRAM](https://www.epa.gov/scram))
+
+## Documentation
+
+- [Quick Start Guide](docs/quickstart.md)
+- [GUI User Guide](docs/gui-guide.md)
+- [Architecture](docs/architecture.md)
+- [API Reference](https://atmmod.github.io/pyaermod/api/)
+- [Examples](examples/)
+
+## License
+
+MIT
+
+## Disclaimer
+
+PyAERMOD is a wrapper around AERMOD, not a reimplementation. It uses official EPA binaries for all calculations and maintains regulatory acceptance. Always validate results against EPA test cases for your specific use case.