Troubleshooting¶

Solutions to common problems with PyFDS.

Installation Issues¶

ImportError: No module named 'pyfds'¶

Cause: PyFDS not installed or wrong Python environment

Solution:

# Check installation
pip list | grep pyfds

# Install if missing
pip install pyfds

# Or with uv
uv add pyfds

Version conflicts¶

Cause: Incompatible dependency versions

Solution: Use fresh virtual environment

python -m venv clean-env
source clean-env/bin/activate
pip install pyfds

Simulation Creation¶

"Obstruction outside mesh bounds"¶

Cause: Geometry coordinates exceed mesh limits

Solution: Check coordinates

from pyfds import Mesh, Obstruction
from pyfds.core.geometry import Bounds3D

# Mesh: (0, 5) in X
sim.add(Mesh(xb=Bounds3D.of(0, 5, 0, 5, 0, 2.5)))

# Bad: X goes to 6
sim.add(Obstruction(xb=Bounds3D.of(4, 6, 0, 5, 0, 2.5))  # ERROR

# Good: X within bounds
sim.add(Obstruction(xb=Bounds3D.of(4, 5, 0, 5, 0, 2.5))  # OK

"Surface ID 'FIRE' not found"¶

Cause: Using surface before defining it

Solution: Define surfaces first

# Correct order
sim.add(Surface(id='FIRE', hrrpua=1000.0))
sim.add(Obstruction(xb=Bounds3D.of(2, 3, 2, 3, 0, 0.1), surf_id='FIRE'))

Validation warnings¶

Cause: Potential issues with simulation

Solution: Review and fix warnings

warnings = sim.validate()
for w in warnings:
    print(f"Warning: {w}")

Execution Problems¶

"FDS not found"¶

Cause: FDS not installed or not in PATH

Solution: Install FDS from https://pages.nist.gov/fds-smv/

Verify installation:

fds -v

Simulation crashes immediately¶

Causes and solutions:

Fire too intense

# Too intense
sim.add(Surface(id='FIRE', hrrpua=5000.0))

# More reasonable
sim.add(Surface(id='FIRE', hrrpua=1500.0))

Cells too small

# Too fine (very slow)
sim.add(Mesh(ijk=Grid3D.of(200, 200, 100), xb=Bounds3D.of(0, 5, 0, 5, 0, 2.5)))

# More reasonable
sim.add(Mesh(ijk=Grid3D.of(50, 50, 25), xb=Bounds3D.of(0, 5, 0, 5, 0, 2.5)))

Physical inconsistencies
Check material properties
Verify boundary conditions
Review FDS output (.out) file for errors

NaN or Inf values in results¶

Cause: Numerical instability

Solutions: - Reduce fire intensity - Increase cell size - Check for unrealistic inputs - Review FDS warnings in .out file

Performance Issues¶

Simulation too slow¶

Solutions:

Reduce cell count

# Before: 500,000 cells
sim.add(Mesh(ijk=Grid3D.of(100, 100, 50), xb=Bounds3D.of(0, 5, 0, 5, 0, 2.5)))

# After: 62,500 cells (8x faster)
sim.add(Mesh(ijk=Grid3D.of(50, 50, 25), xb=Bounds3D.of(0, 5, 0, 5, 0, 2.5)))

Use parallelization

# Single thread (slow)
results = sim.run()

# Multi-threaded (faster)
results = sim.run(n_threads=8)

Reduce simulation time

# Test run
sim.add(Time(t_end=30.0))

# Production run
sim.add(Time(t_end=600.0))

Out of memory¶

Cause: Too many cells

Solution: Reduce mesh resolution or use multiple meshes

Results Analysis¶

Cause: Wrong path or simulation didn't complete

Solution: Check file location

# Specify correct directory
results = Results(chid='simulation', output_dir='./outputs')

# Check files exist
import os
print(os.path.exists('simulation_hrr.csv'))

Empty or missing device data¶

Cause: Device output not written

Solution: Ensure simulation completed and devices defined

# Check devices were added
print(f"Number of devices: {len(sim.instrumentation.devices)}")

Development Issues¶

Type checking errors with MyPy¶

Cause: Missing type hints or imports

Solution: Check imports and types

from typing import Optional
from pyfds import Simulation

def create_sim() -> Simulation:
    return Simulation(chid='test')

Tests failing¶

Cause: Environment or dependency issues

Solution: Clean install

# Remove existing installation
pip uninstall pyfds

# Reinstall with dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

Getting More Help¶

Check FDS Output¶

Always check the FDS output file ({chid}.out) for detailed error messages:

# After execution failure
with open('simulation.out', 'r') as f:
    print(f.read())

Enable Logging¶

import logging
logging.basicConfig(level=logging.DEBUG)

# Now run your code

Ask for Help¶

If you're still stuck:

Check FAQ
Search GitHub Issues
Ask in Discussions
Open a new issue

When asking for help, include: - Python version (python --version) - PyFDS version (pip show pyfds) - Minimal code that reproduces the issue - Full error message - FDS version (if execution issue)

Back to Reference →