# chris-hockey/hysplit-simulations-for-cegb-power-plants architecture

> Architecture diagram of the GitHub repository chris-hockey/hysplit-simulations-for-cegb-power-plants, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chris-hockey/hysplit-simulations-for-cegb-power-plants
- Repository: https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants

## Overview

This repository is research code for generating annual HYSPLIT transport kernels for CEGB power-plant-years, with a calibration exercise used to choose plume-rise heat values. The main workflow prepares plant data and ERA5 meteorology, runs a seven-member calibration ensemble, evaluates its exposures against pollution observations, then runs production simulations. The README documents the broad stages; sampled source confirms key runner, simulation, kernel, and analysis responsibilities. ERA5 conversion and weather-analysis details are represented at their documented directory level because their implementations were not sampled.

Main entry points: [`code/simulation/sim_run.py`](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/simulation/sim_run.py) (Production runner), [`code/simulation/ensemble_run.py`](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/simulation/ensemble_run.py) (Ensemble runner), [`code/simulation/hysplit/kernel.py`](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/simulation/hysplit/kernel.py) (Annual kernel), [`code/analysis/ensemble_runs/1_ensemble_treatment.py`](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/analysis/ensemble_runs/1_ensemble_treatment.py) (Ensemble exposure)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Input preparation"]
  node_clean["Clean plant panel<br/>[1_pp_cleaning.py]"]
  node_stack["Impute stack heights<br/>[2_stack_pred.py]"]
  node_era_api["Download ERA5<br/>[1_api_calls.py]"]
  node_era_convert["ERA5 to ARL"]
end

subgraph group_calibration["Plume calibration"]
  node_ensemble_runner["Ensemble runner<br/>[ensemble_run.py]"]
  node_ensemble_analysis["Ensemble exposure"]
  node_assessment["Calibration assessment"]
  node_weather_check["Weather representativeness"]
end

subgraph group_runtime["Simulation runtime"]
  node_batch["Parallel batch runner<br/>[batch.py]"]
  node_plantyear["Plant-year model<br/>[plant.py]"]
  node_hysplit_run["HYSPLIT run<br/>[run.py]"]
  node_annual_kernel["Annual kernel<br/>[kernel.py]"]
end

subgraph group_production["Production kernels"]
  node_sim_runner["Production runner<br/>[sim_run.py]"]
  node_kernel_store[("Annual kernels")]
end

node_researcher(("Researcher"))
node_cegb["CEGB panel data"]
node_era_service[("Copernicus ERA5")]
node_hysplit["HYSPLIT engine"]
node_pollution["Pollution observations"]

node_researcher -->|"prepares data"| node_clean
node_cegb -->|"cleans panel"| node_clean
node_clean -->|"builds panel"| node_stack
node_researcher -->|"requests weather"| node_era_api
node_era_service -->|"provides fields"| node_era_api
node_era_api -->|"converts fields"| node_era_convert
node_researcher -->|"starts calibration"| node_ensemble_runner
node_ensemble_runner -->|"dispatches jobs"| node_batch
node_ensemble_runner -->|"constructs source"| node_plantyear
node_ensemble_runner -->|"executes members"| node_annual_kernel
node_annual_kernel -->|"wraps simulation"| node_hysplit_run
node_hysplit_run -->|"runs and converts"| node_hysplit
node_annual_kernel -->|"writes kernels"| node_kernel_store
node_ensemble_analysis -->|"reads ensemble output"| node_kernel_store
node_pollution -->|"supplies observations"| node_ensemble_analysis
node_ensemble_analysis -->|"provides station panel"| node_assessment
node_assessment -->|"selects heat values"| node_researcher
node_researcher -->|"checks calibration year"| node_weather_check
node_stack -->|"supplies plant panel"| node_sim_runner
node_researcher -->|"starts production"| node_sim_runner
node_sim_runner -->|"dispatches jobs"| node_batch
node_sim_runner -->|"constructs source"| node_plantyear
node_sim_runner -->|"executes plant-years"| node_annual_kernel
node_sim_runner -->|"produces annual kernels"| node_kernel_store
node_era_convert -->|"supplies ARL meteorology"| node_hysplit_run

click node_clean "https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/data_processing/power_plants/1_pp_cleaning.py"
click node_stack "https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/data_processing/power_plants/2_stack_pred.py"
click node_era_api "https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/data_processing/era5/1_api_calls.py"
click node_era_convert "https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/tree/main/code/data_processing/era5"
click node_ensemble_runner "https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/simulation/ensemble_run.py"
click node_batch "https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/simulation/hysplit/batch.py"
click node_plantyear "https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/simulation/hysplit/plant.py"
click node_hysplit_run "https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/simulation/hysplit/run.py"
click node_annual_kernel "https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/simulation/hysplit/kernel.py"
click node_ensemble_analysis "https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/analysis/ensemble_runs/1_ensemble_treatment.py"
click node_assessment "https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/analysis/ensemble_runs/2_ensemble_assessment.py"
click node_weather_check "https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/tree/main/code/analysis/average_weather"
click node_sim_runner "https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/simulation/sim_run.py"
click node_kernel_store "https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/tree/main/code/simulation/hysplit"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_clean,node_stack,node_era_api,node_era_convert toneBlue
class node_ensemble_runner,node_ensemble_analysis,node_assessment,node_weather_check,node_era_service toneAmber
class node_batch,node_plantyear,node_hysplit_run,node_annual_kernel toneMint
class node_sim_runner,node_kernel_store toneRose
class node_researcher,node_cegb,node_hysplit,node_pollution toneIndigo
```

## Components

### Input preparation

- [Clean plant panel](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/data_processing/power_plants/1_pp_cleaning.py): `code/data_processing/power_plants/1_pp_cleaning.py`
- [Impute stack heights](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/data_processing/power_plants/2_stack_pred.py): `code/data_processing/power_plants/2_stack_pred.py`
- [Download ERA5](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/data_processing/era5/1_api_calls.py): `code/data_processing/era5/1_api_calls.py`
- [ERA5 to ARL](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/tree/main/code/data_processing/era5): `code/data_processing/era5`

### Plume calibration

- [Ensemble runner](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/simulation/ensemble_run.py): `code/simulation/ensemble_run.py`
- [Ensemble exposure](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/analysis/ensemble_runs/1_ensemble_treatment.py): `code/analysis/ensemble_runs/1_ensemble_treatment.py`
- [Calibration assessment](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/analysis/ensemble_runs/2_ensemble_assessment.py): `code/analysis/ensemble_runs/2_ensemble_assessment.py`
- [Weather representativeness](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/tree/main/code/analysis/average_weather): `code/analysis/average_weather`

### Simulation runtime

- [Parallel batch runner](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/simulation/hysplit/batch.py): `code/simulation/hysplit/batch.py`
- [Plant-year model](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/simulation/hysplit/plant.py): `code/simulation/hysplit/plant.py`
- [HYSPLIT run](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/simulation/hysplit/run.py): `code/simulation/hysplit/run.py`
- [Annual kernel](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/simulation/hysplit/kernel.py): `code/simulation/hysplit/kernel.py`

### Production kernels

- [Production runner](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/blob/main/code/simulation/sim_run.py): `code/simulation/sim_run.py`
- [Annual kernels](https://github.com/chris-hockey/hysplit-simulations-for-cegb-power-plants/tree/main/code/simulation/hysplit): `code/simulation/hysplit`

### Other components

- **Researcher**
- **CEGB panel data**
- **Copernicus ERA5**
- **HYSPLIT engine**
- **Pollution observations**

## Connections

- Researcher → Clean plant panel: prepares data (evidence: `README.md`)
- CEGB panel data → Clean plant panel: cleans panel (evidence: `README.md`)
- Clean plant panel → Impute stack heights: builds panel (evidence: `README.md`)
- Researcher → Download ERA5: requests weather (evidence: `README.md`)
- Copernicus ERA5 → Download ERA5: provides fields (evidence: `README.md`)
- Download ERA5 → ERA5 to ARL: converts fields (evidence: `README.md`)
- Researcher → Ensemble runner: starts calibration (evidence: `README.md`)
- Ensemble runner → Parallel batch runner: dispatches jobs (evidence: `code/simulation/ensemble_run.py`)
- Ensemble runner → Plant-year model: constructs source (evidence: `code/simulation/ensemble_run.py`)
- Ensemble runner → Annual kernel: executes members (evidence: `code/simulation/ensemble_run.py`)
- Annual kernel → HYSPLIT run: wraps simulation (evidence: `code/simulation/hysplit/kernel.py`)
- HYSPLIT run → HYSPLIT engine: runs and converts (evidence: `code/simulation/hysplit/run.py`)
- Annual kernel → Annual kernels: writes kernels (evidence: `code/simulation/hysplit/kernel.py`)
- Ensemble exposure → Annual kernels: reads ensemble output (evidence: `code/analysis/ensemble_runs/1_ensemble_treatment.py`)
- Pollution observations → Ensemble exposure: supplies observations (evidence: `README.md`)
- Ensemble exposure → Calibration assessment: provides station panel (evidence: `README.md`)
- Calibration assessment → Researcher: selects heat values (evidence: `README.md`)
- Researcher → Weather representativeness: checks calibration year (evidence: `README.md`)
- Impute stack heights → Production runner: supplies plant panel (evidence: `README.md`)
- Researcher → Production runner: starts production (evidence: `README.md`)
- Production runner → Parallel batch runner: dispatches jobs (evidence: `code/simulation/sim_run.py`)
- Production runner → Plant-year model: constructs source (evidence: `code/simulation/sim_run.py`)
- Production runner → Annual kernel: executes plant-years (evidence: `code/simulation/sim_run.py`)
- Production runner → Annual kernels: produces annual kernels (evidence: `README.md`)
- ERA5 to ARL → HYSPLIT run: supplies ARL meteorology (evidence: `README.md`)
