Forest Fire Simulation 🔥🌲

A Rust-based forest fire spread simulator that models fire propagation in a procedurally generated forest grid. After a lightning strike ignites a random tree, fire spreads according to a configurable neighborhood strategy, and the simulation reports statistics on burned area across multiple runs.

Example simulation with Moore neighborhood	Example simulation with Von Neumann neighborhood

Features

• Grid-based forest model with customizable dimensions
• Procedural generation with adjustable tree density
• Fire spread algorithms:
  • Moore neighborhood (8-directional)
  • Von Neumann neighborhood (4-directional)
• Multi-simulation analysis with min/max/avg burn statistics
• Fast CLI benchmark mode for batch processing and data collection
• Native GUI visualization using egui/eframe, with reset, stepping, playback speed, density, size, and neighborhood controls
• Statistical output of burned area percentages
• Modular architecture easy extensibility following SOLID principles

Project Overview

This project implements a forest fire model on a two-dimensional grid, where each cell may be empty, contain a tree, be burning, or be burned. Trees are randomly placed based on a user-defined density, and a random tree is ignited to simulate a lightning strike. Fire spreads each timestep according to the selected neighborhood (Moore for 8-directional or Von Neumann for 4-directional). Statistics such as minimum, maximum, and average burned percentages are computed over multiple runs.

File Structure

src/
├── config.rs        # Command-line parsing plus simulation/run configuration structs
├── forest.rs        # Forest grid, cell states, ignition and spread core logic
├── fire_spread.rs   # FireSpreadStrategy trait and neighborhood implementations
├── simulation.rs    # Pure simulation runner and statistics aggregation
├── app.rs           # Native egui/eframe visual simulator
├── main.rs          # Entrypoint: dispatch benchmark, sweep, or GUI mode
└── lib.rs           # Re-exports modules and test harness

• config.rs: Defines Config for run mode/CLI options and SimulationConfig for reusable simulation parameters.
• forest.rs: Implements the Forest struct holding the grid (Vec<Vec<CellState>>), methods to randomly populate trees, ignite a cell, spread fire per timestep, and compute burn statistics.
• fire_spread.rs: Declares the FireSpreadStrategy trait with implementations for MooreNeighborhood (8-directional spread) and VonNeumannNeighborhood (4-directional spread), plus boundary helpers.
• simulation.rs: Contains pure simulation helpers and run_simulations(config: &Config) -> SimulationResults, iterating over the configured number of runs and aggregating min/max/average burned percentages.
• app.rs: Provides the native GUI using egui/eframe, keeping rendering and controls separate from the benchmark path.
• main.rs: Loads Config, launches the GUI, runs a benchmark, or runs a density sweep.
• tests: Unit tests in each module verifying config parsing, neighborhood correctness, forest initialization, and simulation outputs.

Installation

1. Clone the repository

   git clone https://github.com/radoslawwolnik/project-forest-fire.git
   cd project-forest-fire

2. Build the project

   cargo build --release

3. Run executable

   ./target/release/forest_fire_sim [OPTIONS]

Usage

USAGE:
    forest_fire_sim [MODE] [OPTIONS]

MODES:
    benchmark                       Fast command-line statistics (default)
    sweep                           Run density sweep for plotting
    gui                             Open native visual simulator

OPTIONS:
    -s, --size <size>              Grid dimensions (width=height). Default: 20
    -d, --density <density>        Tree density [0.0–1.0]. Default: 0.6
    -c, --simulations <count>      Number of runs. Default: 1
    -b, --burn-pattern <pattern>   'moore' (8-dir) or 'vonneumann' (4-dir). Default: moore
    -a, --auto-sweep               Compatibility alias for sweep mode
    -ss --sweep-step <step>        Sweep density step (between 0.01 and 0.2)
    -q, --quiet                    Print only average burned (raw float)
    -h, --help                     Show this help message

Examples

• Single run with default settings

  cargo run --release -- benchmark

• 100×100 grid at 70% density, 50 fast benchmark runs

  cargo run --release -- benchmark --size 100 --density 0.7 --simulations 50

• Open the visual simulator

  cargo run --release -- gui

• Run a density sweep for plotting

  cargo run --release -- sweep --simulations 100 --burn-pattern vonneumann --sweep-step 0.05

Simulation Diagrams

Below are sample outputs from multiple simulations, plotting tree density versus burned percentage.

Moore:

• Above 60% density all trees will get burned
• Biggest change between 35% to 55%
• Critical threshold at ~40% density where burn percentage sharply increases

Density vs Burn Percentage Moore

Von Neumann:

• Above 80% density all trees will get burned
• Biggest change between 50% to 70%
• Critical threshold at ~55% density where burn percentage sharply increases

Density vs Burn Percentage Von Neumann

Technical Implementation

Grid Representation

enum CellState { Empty, Tree, Burning, Burned }

• 2D grid stored as nested Vec<CellState>
• Initialized using Fisher-Yates shuffling for precise tree counts

Fire Propagation

1. Random tree ignition via lightning strike
2. Iterative spread to adjacent cells:
   • Moore: All 8 surrounding cells
   • Von Neumann: Cardinal directions only
3. Simulation terminates when firefront extinguishes

Optimization Highlights

• O(1) tree counting: Maintains exact tree count during generation
• Firefront queue: Processes only burning cells each iteration
• Reservoir sampling: Efficient random tree selection for ignition
• Separated presentation paths: benchmark mode does no rendering work; GUI drawing lives in app.rs

Testing

Run cargo test to verify:

• Config parsing and validation
• Neighborhood algorithms (Moore & VonNeumann)
• Forest initialization and burn spread logic
• Simulation aggregate behavior

License

MIT

MIT License

Copyright (c) 2025 Radoslaw

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.