Python Tools

The tools/ directory contains Python utilities for converting geospatial data into the file formats consumed by the wildfire level-set solver, as well as post-processing tools for exporting simulation results to GIS formats.

Overview

Script	Purpose
`wrf_wind_reader.py`	Extract U/V wind from a WRF netCDF file → solver wind CSV
`srtm_terrain_reader.py`	Download SRTM1 elevation data → UTM terrain XYZ file
`landscape_writer.py`	Download LANDFIRE rasters → FARSITE landscape file (`.lcp`)
`farsite_weather_reader.py`	Parse FARSITE `.wtr` RAWS weather files → time-stamped wind CSVs
`fuel_moisture_from_weather.py`	Estimate equilibrium dead-fuel moisture from temperature and RH
`farsite_fms_reader.py`	Parse FARSITE `.fms` fuel moisture scenario files → solver inputs
`farsite_adj_reader.py`	Inspect, generate, and apply FARSITE `.adj` fuel adjustment files
`farsite_fmd_reader.py`	Parse, query, convert, and generate FARSITE `.fmd` fuel moisture schedules
`plotfile_to_geotiff.py`	Convert AMReX plotfiles → GeoTIFF rasters and GeoJSON fire-perimeter contours
`perimeter_to_shapefile.py`	Convert fire perimeter files (`.geojson`, `.csv`, `.dat`) to Esri Shapefile
`utm_convert.py`	Bidirectional lat/lon ↔ UTM coordinate conversion (pure-Python or pyproj)
`ensemble_burn_probability.py`	FSPro-style ensemble burn probability driver (Latin hypercube sampling, MPI)
`plot_burn_probability.py`	Visualise ensemble burn probability maps (heatmaps, contours, difference maps)
`fire_size_summary.py`	Tabulate and plot fire size statistics over time from `fire_stats.csv`
`surface_fire_worksheet.py`	BehavePlus-style comprehensive single-point surface fire behavior worksheet (Rothermel 1972): reaction intensity, ROS, flame length, fire size, spotting, probability of ignition, crown fire assessment; batch CSV mode supported.
`values_at_risk.py`	FSPro-style values-at-risk (VAR) overlay: match asset inventory to burn probability map, compute expected loss per asset and category, produce prioritised at-risk list and optional Monte-Carlo exceedance curve.
`topographic_horizon_analysis.py`	Compute and visualise FARSITE topographic horizon angles from an XYZ terrain CSV or a built-in synthetic canyon profile. Identifies which cells are in ridge shadow for a given solar elevation / azimuth. Also serves as executable documentation of the C++ horizon-scan algorithm.
`behavior_matrix.py`	Generate Rothermel fire behavior matrices across moisture / wind ranges
`crown_fire_worksheet.py`	Van Wagner (1977) crown fire initiation and active-crown ROS worksheet
`ignition_probability_table.py`	Anderson (1970) probability of ignition lookup tables
`satellite_goes_to_csv.py` / Satellite Fire Detection Assimilation	Convert GOES NetCDF fire-detection granules to CSV; ingest GOES / VIIRS / CSV active-fire detections into the level-set initial condition or mid-simulation
`ember_cascade_analysis.py`	Post-process `ember_cascade_flux` / `ember_cascade_ignition` fields from AMReX plotfiles: summary statistics table, CSV export, and landing-flux density map visualisation (requires `numpy`; `matplotlib` for plots)

A unified legacy tool (terrain_wind_preprocess.py) is retained in tools/deprecated/ and superseded by the split tools above.

Dependencies

Install with pip before using any tool:

pip install numpy netCDF4 pyproj rasterio elevation requests scipy matplotlib shapely pyshp

Not all packages are required by every tool; see each section below.

`wrf_wind_reader.py` — WRF Wind Extraction

Reads U and V 10-m (or lowest-level) wind components from a WRF-style netCDF file and writes one or more CSV wind files for use as velocity_file in the solver.

Key workflow

Opens the WRF netCDF and reads the simulation domain extent.
Reprojects each grid point from WRF geographic coordinates to UTM using pyproj.
Writes utm_x utm_y u v CSV rows (one per grid point per requested time step).
Optionally generates an inputs.i stub with velocity_file pre-configured.

Typical usage

# Single time step, auto bounding box from WRF file
python3 tools/wrf_wind_reader.py --wrf-file wrfout_d01 --wind wind.csv

# Multiple time steps
python3 tools/wrf_wind_reader.py --wrf-file wrfout_d01 --wind wind.csv --time-range 0:4

# Interpolate wind onto an existing terrain XYZ grid
python3 tools/wrf_wind_reader.py --wrf-file wrfout_d01 --wind wind.csv \
    --terrain-file terrain.xyz

Key options

--wrf-file FILE — WRF netCDF input (required)
--wind FILE — output wind CSV (default: wind.csv)
--time-range T1:TN — inclusive range of WRF time indices to extract
--time-index N — single time index (default: 0)
--terrain-file PATH — existing terrain XYZ; wind is IDW-interpolated onto its grid
--grid-resolution M — target grid spacing in metres for regular-grid interpolation
--subsample N — keep every N-th grid point (default: 1)

Dependencies: netCDF4, numpy, pyproj; scipy for --terrain-file or --grid-resolution.

`srtm_terrain_reader.py` — SRTM Terrain Download

Downloads SRTM1 (30 m) elevation data for a lat/lon bounding box and writes a UTM terrain XYZ file for rothermel.terrain_file.

Key workflow

Downloads the SRTM tile(s) covering the bounding box via the elevation package.
Reprojects the raster to UTM using rasterio and pyproj.
Writes X Y Z rows in UTM metres.

Typical usage

python3 tools/srtm_terrain_reader.py \
    --lat-min 40 --lat-max 40.5 --lon-min -105 --lon-max -104.5

# With intermediate GeoTIFF and subsampling
python3 tools/srtm_terrain_reader.py \
    --lat-min 40 --lat-max 40.5 --lon-min -105 --lon-max -104.5 \
    --tif srtm_raw.tif --subsample 2

Key options

--lat-min/max, --lon-min/max — bounding box (required)
--terrain FILE — output terrain XYZ (default: terrain.xyz)
--tif FILE — keep intermediate GeoTIFF at this path
--subsample N — keep every N-th point (default: 1)

Dependencies: elevation, rasterio, numpy, pyproj, scipy.

`landscape_writer.py` — LANDFIRE Landscape File Writer

Downloads LANDFIRE elevation, slope, aspect, and fuel model rasters for a lat/lon bounding box and writes a FARSITE landscape file (.lcp) for rothermel.landscape_file. Three remote sources are supported (AWS S3 COGs, Microsoft Planetary Computer, USGS REST API). Local GeoTIFFs can be used to skip downloads entirely.

Key workflow

Downloads or reads LANDFIRE rasters for the specified bounding box.
Optionally derives terrain slope and aspect from SRTM data.
Writes an ASCII landscape file: X Y ELEVATION SLOPE ASPECT FUEL_MODEL.

Typical usage

# Download LANDFIRE via API
python3 tools/landscape_writer.py \
    --lat-min 40 --lat-max 40.5 --lon-min -105 --lon-max -104.5

# Use local rasters (no download)
python3 tools/landscape_writer.py \
    --lat-min 40 --lat-max 40.5 --lon-min -105 --lon-max -104.5 \
    --elev-file elev.tif --slope-file slope.tif \
    --aspect-file aspect.tif --fuel-file fbfm13.tif

# Scott & Burgan 40 fuel model system
python3 tools/landscape_writer.py \
    --lat-min 40 --lat-max 40.5 --lon-min -105 --lon-max -104.5 \
    --fuel-model-type 40

Key options

--lat-min/max, --lon-min/max — bounding box (required)
--landscape FILE — output .lcp file (default: landscape.lcp)
--fuel-model-type {13,40} — Anderson 13 or Scott & Burgan 40
--vintage YEAR — LANDFIRE vintage year (default: 2020)
--elev-file, --slope-file, --aspect-file, --fuel-file — local rasters
--srtm-slope-aspect — derive terrain from SRTM when only --fuel-file is given
--subsample N — keep every N-th point (default: 1)

Dependencies: rasterio, numpy, pyproj, requests.

`farsite_weather_reader.py` — FARSITE Weather File Parser

Parses FARSITE .wtr RAWS weather-station files and writes time-stamped wind CSV files for the solver. Optionally generates inputs.i stubs and estimated fuel moisture files.

Typical usage

# Single wind file from the first weather record
python3 tools/farsite_weather_reader.py --wtr fire.wtr --wind wind.csv

# Time-dependent wind snapshots for a 2 km × 2 km domain at 100 m resolution
python3 tools/farsite_weather_reader.py \
    --wtr fire.wtr --wind wind.csv \
    --time-dependent --domain 2000 2000 --resolution 100

# Generate solver input stub and estimated fuel moisture
python3 tools/farsite_weather_reader.py \
    --wtr fire.wtr --wind wind.csv \
    --inputs-stub inputs.i --write-moisture

Dependencies: none (pure Python).

`fuel_moisture_from_weather.py` — Equilibrium Fuel Moisture Calculator

Estimates 1-hr, 10-hr, and 100-hr dead fuel moisture content from temperature and relative humidity using the Nelson (2000) / Simard (1968) Equilibrium Moisture Content (EMC) model, as implemented in FARSITE, BehavePlus, and FLAMMAP.

Typical usage

# Single observation
python3 tools/fuel_moisture_from_weather.py --temp 30 --rh 20

# Output in solver input format
python3 tools/fuel_moisture_from_weather.py --temp 28 --rh 25 --solver-format

# Batch from a weather CSV
python3 tools/fuel_moisture_from_weather.py --csv weather.csv --solver-format

Dependencies: none (pure Python).

`plotfile_to_geotiff.py` — GIS Export

Converts AMReX 2-D plotfiles to GeoTIFF rasters and GeoJSON fire-perimeter contours for import into QGIS, ArcGIS, or other GIS tools. Multi-level AMR plotfiles (finest_level > 0) are supported; finer-level data is composited onto the Level 0 base grid.

Default fire-behaviour variables exported when no -v filter is given:

phi, R, fireline_intensity, flame_length, elevation, slope, aspect, fuel_model, fuel_consumption, residual_fuel (post-frontal burnout fraction), crown_fraction, arrival_time, reaction_intensity, wind_speed, wind_direction.

Typical usage

# Export all fire-behaviour variables
python3 tools/plotfile_to_geotiff.py plt0100 --outdir gis_out

# Export specific variables with UTM georeference
python3 tools/plotfile_to_geotiff.py plt0100 \
    -v phi R fireline_intensity flame_length \
    --utm-origin 450000 4200000 --epsg 32613 --outdir gis_out

# Post-frontal fuel state rasters
python3 tools/plotfile_to_geotiff.py plt0100 \
    -v residual_fuel fuel_consumption arrival_time \
    --utm-origin 450000 4200000 --epsg 32613 --outdir gis_out

# Batch-convert all plt#### directories
python3 tools/plotfile_to_geotiff.py --all --outdir gis_out

Key options

-v VAR [VAR …] — export only named variables (default: fire-behaviour subset)
--all-vars — export every variable in the plotfile
--all — process all plt#### directories in the current working directory
--utm-origin EASTING NORTHING — UTM origin to add to simulation coordinates
--epsg CODE — EPSG CRS code (e.g. 32613 for UTM zone 13N)

Output per plotfile:

plt####_<variable>.tif — single-band float32 GeoTIFF (deflate-compressed)
plt####_fire_perimeter.geojson — \(\phi = 0\) contour as GeoJSON LineString

Dependencies: rasterio, numpy; matplotlib for GeoJSON perimeters.

Combining the Tools: Typical Workflow

A typical field-scale simulation setup proceeds as follows:

Download terrain and landscape data:

python3 tools/srtm_terrain_reader.py \
    --lat-min 40 --lat-max 40.5 --lon-min -105 --lon-max -104.5

python3 tools/landscape_writer.py \
    --lat-min 40 --lat-max 40.5 --lon-min -105 --lon-max -104.5

Extract wind from a WRF forecast:

python3 tools/wrf_wind_reader.py \
    --wrf-file wrfout_d01 --wind wind.csv --terrain-file terrain.xyz

Run the solver using the generated files:

rothermel.terrain_file   = terrain.xyz
rothermel.landscape_file = landscape.lcp
velocity_file            = wind.csv

Export results for GIS:

python3 tools/plotfile_to_geotiff.py --all --outdir gis_out \
    --utm-origin 450000 4200000 --epsg 32613

`farsite_fms_reader.py` — FARSITE Fuel Moisture Scenario Parser

Reads a FARSITE .fms file that specifies per-fuel-model dead and live fuel moisture contents and writes solver-compatible moisture inputs.

FMS file format:

<num_fuel_models>
<fuel_model_num>  <1hr%>  <10hr%>  <100hr%>  <live_herb%>  <live_wood%>

Moisture values are integer percentages (e.g. 8 → 8 %, which is 0.08 as a fraction). Non-burnable models (91–99) are silently skipped.

Output modes

Print (default): human-readable table and a ready-to-paste block of solver inputs.i parameters for every fuel model.
--write-inputs FILE: write a solver inputs.i moisture stub for one model.
--write-csv FILE: export all fuel models as a CSV (fractions and percentages).
--query NUM: print the solver block for a single fuel model.

Typical usage

# Print moisture summary
python3 tools/farsite_fms_reader.py fire.fms

# Write solver input stub using fuel model 4
python3 tools/farsite_fms_reader.py fire.fms --fuel-model 4 \
    --write-inputs inputs_moisture.i

# Export all moisture values as CSV
python3 tools/farsite_fms_reader.py fire.fms --write-csv moisture.csv

# Query a single fuel model
python3 tools/farsite_fms_reader.py fire.fms --query 8

Key options

FILE — input .fms file (positional, required)
--fuel-model NUM — model to use for --write-inputs (default: first in file)
--write-inputs FILE — write a solver inputs.i moisture stub
--write-csv FILE — write all moisture values as a CSV table
--query NUM — print only the entry for a specific fuel model

Dependencies: none (pure Python).

`farsite_adj_reader.py` — FARSITE Fuel Adjustment File Parser

Reads per-fuel-model rate-of-spread (ROS) multipliers from a FARSITE .adj file, generates template files, and can apply adjustments to a Rothermel parameter CSV.

ADJ file format:

# Comments start with # or !
[optional: <num_fuel_models>]
<fuel_model_number>  <adj_factor>

The adj_factor is a multiplicative scale applied to Rothermel R₀.

Typical usage

# Inspect an existing .adj file
python3 tools/farsite_adj_reader.py --adj fire.adj

# Generate a template for all FBFM13 models with adj_factor = 1.0
python3 tools/farsite_adj_reader.py --generate --fuel-system 13 \
    --output template_13.adj

# Generate a template for specific models
python3 tools/farsite_adj_reader.py --generate --models 4 9 10 \
    --output my_adj.adj

# Apply adjustments to a Rothermel CSV for calibration inspection
python3 tools/farsite_adj_reader.py --adj fire.adj \
    --apply-csv rothermel_params.csv \
    --output rothermel_adjusted.csv

Key options

--adj FILE — path to .adj file to inspect or apply
--generate — generate a template .adj file (requires --output)
--fuel-system {13|40} — fuel model system for template generation (default: 13)
--models MODEL [MODEL …] — specific fuel model numbers to include in template
--apply-csv FILE — Rothermel CSV to apply adjustments to
--output / -o FILE — output file path

Integrate with the solver via inputs.i:

fuel_adj_file  = fire.adj
fuel_adj_model = 4

Dependencies: none (pure Python).

`farsite_fmd_reader.py` — FARSITE Fuel Moisture Schedule Parser

Reads, converts, queries, and generates FARSITE-compatible .fmd fuel moisture schedule files. The solver reads these via fmd_file and updates moisture at every time step.

FMD file format:

MONTH  DAY  HOUR  PRECIP  NUM_MODELS
MODEL  1HR%  10HR%  100HR%  LHERB%  LWOOD%

Output modes

Inspect (default): print the full schedule as a table.
--output FILE (with --fmd): convert the schedule to a flat CSV.
--query-time SECONDS --fuel-model N: interpolated moisture at a simulation time.
--generate --output FILE: write a constant-moisture .fmd template.

Typical usage

# Inspect a .fmd file
python3 tools/farsite_fmd_reader.py --fmd fire.fmd

# Convert to a flat CSV for analysis
python3 tools/farsite_fmd_reader.py --fmd fire.fmd --output moisture.csv

# Query interpolated moisture at t = 3600 s for FM4
python3 tools/farsite_fmd_reader.py --fmd fire.fmd \
    --query-time 3600 --fuel-model 4

# Generate a 24-hour constant-moisture template
python3 tools/farsite_fmd_reader.py --generate \
    --models 4 9 10 \
    --start-month 7 --start-day 15 --hours 24 \
    --M-d1 8 --M-d10 10 --M-d100 15 \
    --M-lh 90 --M-lw 120 \
    --output summer_moisture.fmd

Key options

--fmd FILE — .fmd file to parse / inspect / convert
--output / -o FILE — output CSV or .fmd template path
--query-time SECONDS — query interpolated moisture at this simulation time
--fuel-model N — fuel model code for --query-time (default: 0 = global)
--generate — generate a constant-moisture .fmd template
--models N [N …] — fuel model codes (default: FBFM13 1–13)
--start-month M, --start-day D — reference start date
--hours N — number of hourly snapshots (default: 24)
--M-d1, --M-d10, --M-d100, --M-lh, --M-lw — moisture [%]

Integrate with the solver via inputs.i:

fmd_file        = summer_moisture.fmd
fmd_start_month = 7
fmd_start_day   = 15
fmd_fuel_model  = 0

Dependencies: none (pure Python).

`perimeter_to_shapefile.py` — Fire Perimeter to Shapefile Converter

Converts wildfire_levelset fire perimeter output files to Esri Shapefile format for import into QGIS, ArcGIS, and other GIS tools.

Supported input formats

perimeter_NNNN.geojson — GeoJSON FeatureCollection with a Polygon
perimeter_NNNN.csv — two-column CSV with X, Y coordinates
phi_negative_NNNN.dat — whitespace-delimited X Y point cloud (φ < 0)
phi_envelope_NNNN.dat — whitespace-delimited X Y convex hull vertices

Typical usage

# Convert a single GeoJSON perimeter to shapefile
python3 tools/perimeter_to_shapefile.py perimeter_0100.geojson

# Convert all GeoJSON perimeters and assign UTM zone 13N (EPSG:32613)
python3 tools/perimeter_to_shapefile.py perimeter_*.geojson --epsg 32613

# Convert CSV perimeters, write to a different directory
python3 tools/perimeter_to_shapefile.py perimeter_*.csv --outdir shapefiles/

# Convert all phi_negative point clouds to Multipoint shapefiles
python3 tools/perimeter_to_shapefile.py phi_negative_*.dat --point-cloud

# Batch convert everything in the current directory
python3 tools/perimeter_to_shapefile.py --all

Key options

INPUT [INPUT …] — input perimeter file(s); glob patterns are supported
--outdir DIR — output directory (default: same as input file)
--epsg N — EPSG code for the .prj file (e.g. 32613 for UTM zone 13N)
--point-cloud — write phi_negative .dat files as Multipoint shapefile
--all — convert all supported perimeter files in the current directory
--overwrite — overwrite existing .shp files

Output per input file: .shp, .dbf, .shx, and (when --epsg is given) .prj.

Dependencies: pyshp (required); shapely for convex hull; pyproj for rich CRS WKT.

pip install pyshp shapely pyproj

`utm_convert.py` — Lat/Lon ↔ UTM Coordinate Conversion

Bidirectional WGS-84 lat/lon ↔ UTM conversion. Works as a standalone CLI tool or as an importable Python module. Uses a pure-Python WGS-84 Transverse Mercator implementation by default and automatically switches to the more accurate pyproj backend when available.

Module API

from tools.utm_convert import latlon_to_utm, utm_to_latlon

easting, northing, zone_number, zone_letter = latlon_to_utm(34.10, -118.85)
lat, lon = utm_to_latlon(330000, 3775000, zone_number=11, northern=True)

Typical CLI usage

# Convert lat/lon → UTM (zone auto-detected)
python3 tools/utm_convert.py --to-utm 34.10 -118.85

# Convert lat/lon → UTM (force specific zone)
python3 tools/utm_convert.py --to-utm 34.10 -118.85 --zone 11

# Convert UTM → lat/lon
python3 tools/utm_convert.py --to-latlon 330000 3775000 --zone 11

# Southern hemisphere
python3 tools/utm_convert.py --to-latlon 330000 3775000 --zone 11 --south

Key options

--to-utm LAT LON — convert lat/lon (decimal degrees) to UTM
--to-latlon EASTING NORTHING — convert UTM metres to lat/lon
--zone N — UTM zone number (1–60); auto-detected for --to-utm, required for --to-latlon
--south — southern hemisphere (applies to --to-latlon only)

Dependencies: none (pure Python); pyproj optional for higher accuracy.

`ensemble_burn_probability.py` — Ensemble Burn Probability Driver

FSPro-style ensemble burn probability driver. Runs the solver N times with perturbed wind speed, wind direction, and dead fuel moisture (Latin hypercube or random sampling), accumulates per-cell burn counts, and writes a probability map.

Perturbation model

Three independent parameters are perturbed:

wind speed factor (multiplicative, lognormal)
wind direction offset (additive, normal, degrees)
1-hr dead fuel moisture offset (additive, normal, fraction)

Typical usage

# Basic serial: 50 runs, ±20% wind speed, ±15° direction, ±2% moisture
python3 tools/ensemble_burn_probability.py \
    --exe ./wildfire_levelset \
    --inputs inputs.i \
    --n-runs 50 \
    --wind-speed-sigma 0.20 \
    --wind-dir-sigma 15.0 \
    --moisture-sigma 0.02

# MPI: each ensemble member uses 4 MPI ranks
python3 tools/ensemble_burn_probability.py \
    --exe ./wildfire_levelset \
    --inputs inputs.i \
    --n-runs 50 \
    --mpi-ranks 4

# Georeferenced probability map, parallel members
python3 tools/ensemble_burn_probability.py \
    --exe ./wildfire_levelset \
    --inputs inputs.i \
    --n-runs 200 \
    --resolution 30 \
    --out burn_probability.csv \
    --geojson burn_probability.geojson \
    --jobs 2

# Reproducible run with fixed seed
python3 tools/ensemble_burn_probability.py \
    --exe ./wildfire_levelset \
    --inputs inputs.i \
    --n-runs 50 \
    --seed 42

Key options

--exe FILE — solver executable path (default: ./wildfire_levelset)
--inputs FILE — template inputs.i file (default: inputs.i)
--n-runs N — number of ensemble members (default: 50)
--mpi-ranks N — MPI ranks per member; 0 = serial (default: 0)
--mpirun CMD — MPI launcher command (default: mpirun)
--wind-speed-sigma S — std dev of multiplicative wind-speed factor (default: 0.20)
--wind-dir-sigma D — std dev of wind-direction offset [deg] (default: 15.0)
--moisture-sigma M — std dev of M_d1 offset [fraction] (default: 0.02)
--resolution R — grid spacing for probability accumulation [m] (default: auto)
--out FILE — output burn probability CSV (default: burn_probability.csv)
--geojson FILE — optional GeoJSON probability raster output
--work-dir DIR — base working directory for scratch dirs (default: /tmp/ensemble)
--seed N — random seed (default: system clock)
--sampler {lhs|random} — sampling method (default: lhs)
--jobs J — parallel solver runs (default: 1)
--keep-runs — keep individual run directories after aggregation

Output files

burn_probability.csv — X, Y, P_burn columns; one row per grid cell
burn_probability.geojson — optional GeoJSON probability field (when --geojson is given)

Dependencies: none required; scipy for Latin hypercube sampling (falls back to pure-Python LHS otherwise).

`satellite_goes_to_csv.py` / Satellite Fire Detection Assimilation

C++ module: src/satellite_assimilation.H Python helper: tools/satellite_goes_to_csv.py (GOES NetCDF → CSV converter)

The satellite assimilation module ingests real-time active-fire detections from GOES, VIIRS, or a pre-prepared CSV file, and merges them into the fire level-set field phi as new ignition disks at the detected locations. Detections can be applied as the initial condition at t = 0, re-applied during the simulation at a configurable interval, or both.

Data Sources

Three source modes are supported:

“file” (recommended for HPC / offline) — reads a pre-downloaded lon/lat/confidence CSV. Format:
```
# longitude_deg, latitude_deg, confidence_pct
-119.42, 37.85, 75
-119.40, 37.86, 80
```
Generate this file from NASA FIRMS with any of the workflows below.
“viirs” — fetches the most-recent VIIRS-SNPP NRT active-fire CSV from the NASA FIRMS REST API. Requires a free map key (register at https://firms.modaps.eosdis.nasa.gov/api/map_key/) and internet connectivity from the compute node.
“goes” — downloads the latest NOAA GOES-16/17/18 ABI fire-detection granule from the public AWS S3 bucket and converts it to CSV using the optional satellite_goes_to_csv.py helper (requires netCDF4). Falls back to the local cache if the helper is unavailable or the download fails. Network errors are non-fatal.

Preparing a Detection CSV with Python (FIRMS)

A minimal Python snippet to download VIIRS NRT detections for a bounding box and write the expected three-column CSV:

import csv, urllib.request

MAP_KEY   = "YOUR_FIRMS_MAP_KEY"     # register at firms.modaps.eosdis.nasa.gov
BBOX      = "-120,33,-114,42"        # lon_min,lat_min,lon_max,lat_max
DAYS      = 1
URL       = (f"https://firms.modaps.eosdis.nasa.gov/api/area/csv"
             f"/{MAP_KEY}/VIIRS_SNPP_NRT/{BBOX}/{DAYS}")

with urllib.request.urlopen(URL) as resp:
    reader = csv.DictReader(resp.read().decode().splitlines())
    with open("fire_detections.csv", "w", newline="") as fh:
        fh.write("# longitude_deg,latitude_deg,confidence_pct\n")
        for row in reader:
            fh.write(f"{row['longitude']},{row['latitude']},{row['confidence']}\n")

Save the script and run it before the solver:

python3 prepare_detections.py
./wildfire_levelset inputs.i

Coordinate Alignment

Detections arrive in WGS-84 lon/lat degrees. The module converts them to UTM easting and northing [m] using a compact Karney (2011) Transverse Mercator projection. The simulation domain origin (prob_lo_x, prob_lo_y) must be aligned with the UTM origin so that:

sim_x = UTM_easting  - prob_lo_easting_m
sim_y = UTM_northing - prob_lo_northing_m

Example for a domain spanning UTM zone 11N easting [500 000, 560 000] m and northing [3 700 000, 3 760 000] m:

geometry.prob_lo = 500000  3700000
geometry.prob_hi = 560000  3760000

satellite.utm_zone           = 11
satellite.utm_northern       = 1
satellite.prob_lo_easting_m  = 500000
satellite.prob_lo_northing_m = 3700000

Input Parameters (prefix `satellite.`)

Parameter	Default	Description
`enable`	0	1 to activate the module
`source`	`"file"`	Detection source: `"file"`, `"viirs"`, or `"goes"`
`local_file`	`""`	Path to pre-downloaded CSV (required for `source="file"`)
`api_key`	`""`	NASA FIRMS map key (required for `source="viirs"`)
`viirs_url_base`	`"https://firms.modaps.eosdis.nasa.gov/api/area/csv"`	Base URL for the NASA FIRMS REST API (override for proxies or mirrors)
`goes_product`	`"ABI-L2-FDCF"`	GOES ABI fire product name
`goes_bucket`	`"noaa-goes18"`	AWS S3 bucket (`noaa-goes16`, `noaa-goes17`, or `noaa-goes18`)
`bbox_lon_min`	-180.0	Bounding box minimum longitude [deg]
`bbox_lon_max`	180.0	Bounding box maximum longitude [deg]
`bbox_lat_min`	-90.0	Bounding box minimum latitude [deg]
`bbox_lat_max`	90.0	Bounding box maximum latitude [deg]
`utm_zone`	10	UTM zone number 1–60
`utm_northern`	1	1 = northern hemisphere; 0 = southern
`prob_lo_easting_m`	0.0	UTM easting of `prob_lo_x` [m]
`prob_lo_northing_m`	0.0	UTM northing of `prob_lo_y` [m]
`fetch_interval_s`	600.0	Re-fetch interval during simulation [s]
`use_as_ic`	1	1 to apply detections as initial condition at `t = 0`
`use_mid_sim`	1	1 to re-apply new detections during the simulation run
`confidence_threshold`	50	Minimum detection confidence [%]
`detection_radius_m`	375.0	Radius of the ignition disk placed at each detection [m]
`local_cache_file`	`""`	Path for caching fetched data; used as fallback on network failure
`suppress_if_burning`	1	1 = skip cells already burning (prevent extinguishing front)

Example — offline file-based assimilation:

satellite.enable              = 1
satellite.source              = file
satellite.local_file          = fire_detections.csv
satellite.utm_zone            = 11
satellite.utm_northern        = 1
satellite.prob_lo_easting_m   = 500000
satellite.prob_lo_northing_m  = 3700000
satellite.confidence_threshold = 60
satellite.detection_radius_m  = 375.0
satellite.use_as_ic           = 1
satellite.use_mid_sim         = 0

Example — live VIIRS re-assimilation every 10 minutes:

satellite.enable              = 1
satellite.source              = viirs
satellite.api_key             = ABCDEF123456
satellite.bbox_lon_min        = -120.0
satellite.bbox_lon_max        = -114.0
satellite.bbox_lat_min        = 33.0
satellite.bbox_lat_max        = 42.0
satellite.utm_zone            = 11
satellite.utm_northern        = 1
satellite.prob_lo_easting_m   = 500000
satellite.prob_lo_northing_m  = 3700000
satellite.fetch_interval_s    = 600.0
satellite.use_as_ic           = 1
satellite.use_mid_sim         = 1
satellite.local_cache_file    = satellite_cache.csv

Test: regtest/ignition/satellite_assimilation/ (uses create_detections.py to generate a synthetic detection CSV).

Dependencies: curl system command (for VIIRS / GOES live modes); netCDF4 Python package plus satellite_goes_to_csv.py helper script (for GOES NetCDF conversion only; not required for "file" or "viirs" modes).

`ember_cascade_analysis.py` — Ember Cascade Post-Processing

Post-processing tool for the flux-based ember cascade model (ember_cascade.enable = 1). Reads the ember_cascade_flux and ember_cascade_ignition fields from AMReX plotfiles and produces:

A per-step summary table (max / mean landing flux, number of active cells, number of spot-fire ignitions).
An optional CSV export for further analysis.
Optional visualisation of the Gaussian landing-flux map alongside the fire perimeter contour.

The reader is dependency-free for plain AMReX plotfiles — it parses the ASCII Header and binary Cell_D_* FAB files directly without requiring the AMReX Python bindings.

# Summarise all steps
python3 tools/ember_cascade_analysis.py --plt-dir .

# Export statistics to CSV
python3 tools/ember_cascade_analysis.py --plt-dir . --csv ember.csv

# Visualise landing flux map at step 50
python3 tools/ember_cascade_analysis.py --plt-dir . --plot 0050 \
    --output flux_step50.png

Dependencies: numpy (required); matplotlib (optional, for --plot).

Python Tools

Overview

Dependencies

wrf_wind_reader.py — WRF Wind Extraction

srtm_terrain_reader.py — SRTM Terrain Download

landscape_writer.py — LANDFIRE Landscape File Writer

farsite_weather_reader.py — FARSITE Weather File Parser

fuel_moisture_from_weather.py — Equilibrium Fuel Moisture Calculator

plotfile_to_geotiff.py — GIS Export

Combining the Tools: Typical Workflow

farsite_fms_reader.py — FARSITE Fuel Moisture Scenario Parser

farsite_adj_reader.py — FARSITE Fuel Adjustment File Parser

farsite_fmd_reader.py — FARSITE Fuel Moisture Schedule Parser

perimeter_to_shapefile.py — Fire Perimeter to Shapefile Converter

utm_convert.py — Lat/Lon ↔ UTM Coordinate Conversion

ensemble_burn_probability.py — Ensemble Burn Probability Driver

satellite_goes_to_csv.py / Satellite Fire Detection Assimilation

Data Sources

Preparing a Detection CSV with Python (FIRMS)

Coordinate Alignment

Input Parameters (prefix satellite.)

ember_cascade_analysis.py — Ember Cascade Post-Processing

`wrf_wind_reader.py` — WRF Wind Extraction

`srtm_terrain_reader.py` — SRTM Terrain Download

`landscape_writer.py` — LANDFIRE Landscape File Writer

`farsite_weather_reader.py` — FARSITE Weather File Parser

`fuel_moisture_from_weather.py` — Equilibrium Fuel Moisture Calculator

`plotfile_to_geotiff.py` — GIS Export

`farsite_fms_reader.py` — FARSITE Fuel Moisture Scenario Parser

`farsite_adj_reader.py` — FARSITE Fuel Adjustment File Parser

`farsite_fmd_reader.py` — FARSITE Fuel Moisture Schedule Parser

`perimeter_to_shapefile.py` — Fire Perimeter to Shapefile Converter

`utm_convert.py` — Lat/Lon ↔ UTM Coordinate Conversion

`ensemble_burn_probability.py` — Ensemble Burn Probability Driver

`satellite_goes_to_csv.py` / Satellite Fire Detection Assimilation

Input Parameters (prefix `satellite.`)

`ember_cascade_analysis.py` — Ember Cascade Post-Processing