PyCFAST

PyCFAST is a Python interface for the Consolidated Fire and Smoke Transport (CFAST) fire simulation software. Its primary goal is to automate CFAST calculations, run parametric studies, sensitivity analyses, data generation, or optimization loops that would be impractical through the graphical interface (CEdit). It also provides a convenient way to create CFAST input files, execute simulations, and analyze results using the versatility and extensive ecosystem of Python.

From CEdit GUI to Python

PyCFAST can be seen as an alternative to the CFAST graphical interface, CEdit. It exposes Python objects that integrate naturally into your Python workflow. Instead of relying on modifying input files through the GUI, you define and manipulate CFAST models programmatically.

CEdit (GUI)	PyCFAST (Python)
	from pycfast import Compartment room = Compartment( id="Comp 1", width=10.0, depth=10.0, height=10.0, ceiling_mat_id="Gypboard", wall_mat_id="Gypboard", floor_mat_id="Gypboard", )

Example Usage

This minimal model runs with just a title and one compartment with default values:

from pycfast import CFASTModel, Compartment, SimulationEnvironment

model = CFASTModel(
    simulation_environment=SimulationEnvironment(title="My Simulation"),
    compartments=[Compartment()],
    # you can also add: fires, wall_vents, ceiling_floor_vents, mechanical_vents, ...
    file_name="my_simulation.in",
)
model.summary()
model.save()

For a full model with all components:

from pycfast import (
    CeilingFloorVent,
    CFASTModel,
    Compartment,
    Fire,
    Material,
    MechanicalVent,
    SimulationEnvironment,
    WallVent,
)

model = CFASTModel(
    simulation_environment=SimulationEnvironment(...),
    material_properties=[Material(...)],
    compartments=[Compartment(...)],
    wall_vents=[WallVent(...)],
    ceiling_floor_vents=[CeilingFloorVent(...)],
    mechanical_vents=[MechanicalVent(...)],
    fires=[Fire(...)],
    file_name="test_simulation.in",
)

Or you can import your existing model from a CFAST input file:

from pycfast.parsers import parse_cfast_file

model = parse_cfast_file("existing_model.in")

Then you can run the model and obtain results as pandas DataFrames:

results = model.run()
# results is a dict of pandas DataFrames
# Available keys: compartments, devices, masses, vents, walls, zone

results["compartments"].head()
#   Time    ULT_1   LLT_1   HGT_1  VOL_1  PRS_1  ...
# 0  0.0    20.00   20.00    5.00   0.01    0.0   ...
# 1  1.0    20.83   20.00    5.00   0.10    0.0   ...

results["devices"].head()
#   Time  TRGGAST_1  TRGSURT_1  TRGINT_1  TRGFLXI_1  ...
# 0  0.0      20.0       20.0      20.0       0.0    ...
# 1  1.0      20.0       20.0      20.0       0.38   ...

Note: When importing an existing model, ensure that all component names (such as TITLE, MATERIAL, ID, etc.) use only alphanumeric characters. Avoid special characters like quotes and slashes, as these may cause parsing issues and will be automatically sanitized where possible.

You can also inspect the model using text-based methods:

print(model.summary())   # text summary to stdout
model.save()      # writes the CFAST input file to disk
model.view_cfast_input_file()  # view the generated input file

Check out the examples for more usage scenarios.

Installation

PyCFAST requires Python 3.10 or later and a working installation of CFAST itself. It is fully tested on verification input files and validation input files from CFAST version 7.7.0 to version 7.7.7. Versions below 7.7.0 might work but are not guaranteed to be fully compatible.

CFAST Installation

CFAST is developed and distributed by NIST, independently of PyCFAST. Download and install it from the NIST CFAST website or the CFAST GitHub repository, then ensure cfast is available in your PATH.

• Windows: download and run the official installer for the version you want from the CFAST releases page (look for the .exe asset, e.g. CFAST-X.Y.Z_SMV-A.B.C.exe), which installs the cfast executable for you.

• Linux / macOS: NIST does not publish pre-built binaries for these platforms, so CFAST must be compiled from source with a Fortran compiler (gfortran). See the Compiling CFAST wiki page for full details:

  # 1. Install a Fortran compiler
  sudo apt-get install gfortran        # Debian/Ubuntu
  # sudo dnf install gcc-gfortran      # Fedora/RHEL
  # brew install gcc                   # macOS
  
  # 2. Clone the CFAST source, pinned to the release tag you want (see the releases page above)
  git clone --depth 1 --branch <CFAST_TAG> https://github.com/firemodels/cfast.git
  cd cfast/Build/CFAST/gnu_linux       # macOS: cd cfast/Build/CFAST/gnu_osx
  
  # 3. Build the executable
  chmod +x make_cfast.sh
  ./make_cfast.sh
  
  # 4. Install it on your PATH
  sudo cp cfast7_linux /usr/local/bin/cfast   # macOS: cfast7_osx instead of cfast7_linux
  sudo chmod +x /usr/local/bin/cfast
  

  Notes:

  • CFAST versions below 7.7.5 do not reliably build on Linux with modern gfortran (see #32).
  • The macOS build was manually verified to work but is not covered by PyCFAST's CI.
  • If the build fails, the compiler and flags for each platform target are defined in Build/CFAST/makefile. Adjust them there to match your machine.

Pip or Conda

PyCFAST can be installed from PyPI or conda-forge:

pip install pycfast

conda install -c conda-forge pycfast

Source

To install PyCFAST from source, clone the repository and install the required dependencies:

git clone https://github.com/bewygs/pycfast.git
cd pycfast
python -m pip install .

Configuring the CFAST Executable

If CFAST is installed in a non-standard location, you can manually specify the path with these methods:

• From an environment variable CFAST:

  export CFAST="/path/to/your/cfast/executable"  # Linux/MacOS
  set CFAST="C:\path\to\your\cfast\executable"  # Windows (cmd)
  $env:CFAST="C:\path\to\your\cfast\executable"  # Windows (PowerShell)
  

• From Python code when defining the CFASTModel:

  from pycfast import CFASTModel
  
  # set custom CFAST executable path via environment variable
  import os
  os.environ['CFAST'] = "/path/to/your/cfast/executable"
  
  # Or directly when defining CFASTModel
  model = CFASTModel(
          ...,
          cfast_exe="/path/to/your/cfast/executable"
      )
  

Documentation

Full documentation, including the API reference and examples, is available online: PyCFAST Documentation

Contributing

We welcome contributions! Please see our Contributing Guide for more information.

References

If you use PyCFAST in your projects, please consider citing the following:

@software{wygas_2026_pycfast,
  author    = {Wygas, Benoît},
  title     = {PyCFAST},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.18703351},
  url       = {https://doi.org/10.5281/zenodo.18703351}
}

Acknowledgments

This Python package was developed with the support of Orano.

PyCFAST is built on top of the work of the CFAST development team at the National Institute of Standards and Technology (NIST). We acknowledge their ongoing efforts in maintaining and improving the CFAST fire modeling software.