Nuclear Fallout Simulator

A Lagrangian particle dispersion model for simulating the transport and deposition of nuclear fallout.

This repository contains:

• A local particle-based simulator (advection, turbulence, and wet deposition/scavenging).
• An optional comparison workflow against NOAA HYSPLIT (trajectory mode).
• Quantitative metrics and an ensemble runner to estimate stochastic uncertainty.

Repository structure

• src/ Core implementation (particles, wind/rain models, plotting utilities, HYSPLIT integration).
• main.py Runs the local simulator and generates plots.
• compare_models.py Runs the local simulator + HYSPLIT trajectories and prints a comparison scorecard.

Generated data and plots (meteorological caches, HYSPLIT outputs, ensemble outputs) are excluded from version control.

Requirements

• Python 3.11/3.10+ recommended.
• A scientific Python environment (NumPy, Matplotlib).

Conda environment (recommended)

Two environments are recommended:

1. A minimal environment for running the local simulator.
2. A fuller environment for HYSPLIT comparison and mapping.

Minimal environment (base simulator)

This is the smallest set of packages required to run the core simulation and the wind-data pipeline used by this repository.

conda create -n fallout-sim -c conda-forge python=3.11 \
  numpy scipy pandas matplotlib requests \
  xarray
conda activate fallout-sim
pip install cfgrib eccodes findlibs

Comparison environment (HYSPLIT + mapping)

This adds the geo/mapping stack and the HYSPLIT helper package used by the comparison workflow.

conda create -n fallout-compare -c conda-forge python=3.11 \
  numpy scipy pandas matplotlib requests \
  xarray \
  cartopy basemap basemap-data \
  geopandas shapely fiona pyproj pyshp \
  folium
conda activate fallout-compare
pip install cfgrib eccodes findlibs pysplit

Notes:

• cfgrib relies on ECMWF ecCodes (eccodes). If you run into installation issues, prefer installing eccodes from conda-forge.
• If you want a fully reproducible environment, export it from your machine:

conda env export -n fallout-compare > environment.yml

Optional: HYSPLIT

To run HYSPLIT comparisons you need a local HYSPLIT installation.

compare_models.py currently assumes:

C:\hysplit\HYSPLIT

If yours differs, update hysplit_root inside compare_models.py.

Quick start

Create and activate an environment (example using Conda):

conda create -n fallout-sim python=3.11
conda activate fallout-sim

Run the local simulator

python main.py

Outputs are written under simulation_results/.

Compare against HYSPLIT

Run a multi-start HYSPLIT trajectory ensemble seeded from the initial particle cloud:

python compare_models.py --hysplit-n 50 --seed 0

Common flags:

• --hysplit-n Number of HYSPLIT trajectories (sampled start locations).
• --seed Seed used to select which particles are used as HYSPLIT starts.
• --no-download Use cached meteorological inputs only.

Ensemble uncertainty (stochastic variability)

To quantify uncertainty from stochastic components (initial sampling, turbulence perturbations, scavenging), run an ensemble of independent simulations:

python compare_models.py --ensemble-n 20 --ensemble-base-seed 0

This adds a “TEST F” block to the printed scorecard and writes per-run outputs to ensemble_output/.

Data and outputs

The following directories are created/used at runtime and are ignored by git:

• gfs_data/ GFS GRIB2 files for the local model.
• hysplit_data/ ARL/GDAS files for HYSPLIT.
• hysplit_output/ HYSPLIT run outputs.
• ensemble_output/ Ensemble per-run CSV/JSON summaries.

License

GNU GPL v3.0. See LICENSE.