PyFDS - Python Interface to Fire Dynamics Simulator¶

[![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) [![License](https://img.shields.io/badge/license-MIT-green.svg)](about/license.md) [![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](development/testing.md) [![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen.svg)](development/testing.md)

A comprehensive Python library for creating, executing, and analyzing NIST Fire Dynamics Simulator (FDS) simulations programmatically.

What is PyFDS?¶

PyFDS transforms the traditional FDS workflow by providing a Pythonic API that allows you to:

Create FDS Input Files

Build simulations using clean, readable Python code instead of manual text editing

Quick Start
Validate Before Running

Catch errors early with comprehensive validation checks before execution

Validation Guide
Automate Parametric Studies

Generate hundreds of simulations programmatically for sensitivity analysis

Parametric Examples
Analyze Results

Access simulation data as Polars DataFrames with built-in plotting

Analysis Guide

Quick Example¶

Create a complete room fire simulation in just a few lines:

Python CodeGenerated FDS FileRun & Analyze

from pyfds import Simulation
from pyfds.core.geometry import Bounds3D, Grid3D, Point3D
from pyfds.core.namelists import Time, Mesh, Surface, Obstruction, Device

# Create simulation
sim = Simulation(chid='room_fire', title='Simple Room Fire')

# Set time parameters
sim.add(Time(t_end=600.0))

# Define computational domain (5m x 5m x 2.5m room)
sim.add(Mesh(ijk=Grid3D.of(50, 50, 25), xb=Bounds3D.of(0, 5, 0, 5, 0, 2.5)))

# Create fire surface (1000 kW/m²)
sim.add(Surface(id='BURNER', hrrpua=1000.0, color='RED'))

# Add fire source (1m x 1m burner at floor)
sim.add(Obstruction(xb=Bounds3D.of(2, 3, 2, 3, 0, 0.1), surf_ids=('BURNER', 'INERT', 'INERT')))

# Add temperature measurement at ceiling
sim.add(Device(id='TEMP_CEILING', quantity='TEMPERATURE',
           xyz=Point3D.of(2.5, 2.5, 2.4)))

# Validate and write FDS input file
sim.write('room_fire.fds')

&HEAD CHID='room_fire', TITLE='Simple Room Fire' /
&TIME T_END=600.0 /
&MESH IJK=50,50,25, XB=0,5,0,5,0,2.5 /
&SURF ID='BURNER', HRRPUA=1000.0, RGB=255,0,0 /
&OBST XB=2,3,2,3,0,0.1, SURF_IDS='BURNER','INERT','INERT' /
&DEVC ID='TEMP_CEILING', QUANTITY='TEMPERATURE', XYZ=2.5,2.5,2.4 /
&TAIL /

# Execute simulation (requires FDS installation)
results = sim.run(n_threads=4)

# Access results as DataFrames
print(f"Peak HRR: {results.hrr['HRR'].max():.1f} kW")
temp_data = results.devices['TEMP_CEILING']

# Generate plots
results.plot_hrr('hrr.png')
results.plot_device('TEMP_CEILING', 'temperature.png')

Key Features¶

Intuitive API Design¶

Fluent Interface: Method chaining for readable simulation building
Type Safety: Full type hints for IDE autocomplete and error prevention
Pydantic Models: Automatic validation with informative error messages

Comprehensive Coverage¶

All Major Namelists: HEAD, TIME, MESH, SURF, OBST, DEVC, VENT, MISC, and more
Complex Features: RAMP, MATL, REAC, PROP, CTRL for advanced scenarios
Special Modes: Wildfire simulation, solid-phase heat transfer, HVAC systems

Execution & Analysis¶

Local Execution: Run FDS directly from Python with progress monitoring
Parallel Processing: OpenMP multi-threading and MPI support
Data Analysis: Results as Polars DataFrames with built-in plotting
Non-blocking Jobs: Background execution with status tracking

Quality & Testing¶

100+ Tests: Comprehensive unit and integration test coverage (>90%)
Type Checked: Full MyPy static type checking
Well Documented: Extensive docstrings and examples

Installation¶

Using uv (Recommended)Using pipFrom Source

uv add pyfds

pip install pyfds

git clone https://github.com/GraysonBellamy/pyfds.git
cd pyfds
uv sync --extra dev

FDS Required for Execution

To actually run simulations (not just create input files), you need FDS installed. See Installation Guide for details.

Documentation Overview¶

Getting Started

New to PyFDS? Start here!
User Guide

Comprehensive guides for all features
Examples

Learn from practical examples
API Reference

Complete API documentation

What Can You Build?¶

PyFDS supports a wide range of fire simulation scenarios:

Building Fire Safety¶

Room fires and compartment modeling
Smoke spread and evacuation analysis
Sprinkler and detector activation
HVAC system interactions

Industrial Applications¶

Warehouse and factory fires
Hazardous material storage
Explosion modeling
Fire suppression systems

Wildfire Simulation¶

Vegetation fire spread
Terrain effects
Wind-driven fires
Fire breaks and barriers

Research & Analysis¶

Parametric sensitivity studies
Model validation
Heat transfer analysis
Custom fire scenarios

Getting Help¶

Support Channels¶

GitHub Issues - Bug reports and feature requests
Discussions - Questions and community help
FAQ - Common questions answered
Troubleshooting - Solutions to common issues

Learning Resources¶

Quick Start - Get up and running in 5 minutes
User Guide - Comprehensive feature documentation
Examples - Real-world code examples
FDS Background - Understanding FDS fundamentals

Project Status¶

Phase 1: Foundation ✅ Complete¶

Core namelist classes (HEAD, TIME, MESH, SURF, OBST, DEVC)
FDS file writer and validation framework
Comprehensive test suite

Phase 2: Execution & Analysis ✅ Complete¶

Local execution with progress monitoring
CSV output parsing (HRR, device data)
Results analysis with Polars DataFrames
OpenMP and MPI parallel support

Phase 3: Advanced Features ✅ Complete¶

Complex namelists (RAMP, MATL, REAC, PROP, CTRL, INIT)
VENT and MISC namelists
Special simulation modes (wildfire, solid-phase, HVAC)

Phase 4: Documentation & Release 🚧 In Progress¶

MkDocs Material documentation
Complete API reference
Video tutorials
PyPI release

License¶

PyFDS is released under the MIT License.

Acknowledgments¶

NIST Fire Research Division for developing FDS
The FDS community for documentation and support
All contributors to the PyFDS project

Citation¶

If you use PyFDS in your research, please cite:

@software{pyfds2025,
  title = {PyFDS: Python Interface to Fire Dynamics Simulator},
  author = {Bellamy, Grayson},
  year = {2025},
  url = {https://github.com/GraysonBellamy/pyfds}
}

Learn more about citing PyFDS

**Ready to get started?** [Install PyFDS](getting-started/installation.md){ .md-button .md-button--primary } [Quick Start Tutorial](getting-started/quickstart.md){ .md-button }