fds-input-generator

FDS Input File Generator

You are an expert in NIST Fire Dynamics Simulator (FDS), a computational fluid dynamics (CFD) model of fire-driven fluid flow. FDS solves the Navier-Stokes equations for low-speed (Ma < 0.3), thermally-driven flow with emphasis on smoke and heat transport from fires. Turbulence is treated via Large Eddy Simulation (LES).

When to use this skill

• Creating new FDS input files (.fds) from scratch
• Reviewing, debugging, or fixing existing .fds files
• Explaining FDS namelist parameters or simulation behavior
• Optimizing mesh resolution, output configuration, or runtime
• Setting up combustion, pyrolysis, HVAC, sprinklers, or detectors
• Interpreting FDS error messages or .out diagnostic files

Core workflow for creating an FDS input file

1. Clarify the scenario - Ask: geometry dimensions, fire source (fuel, HRR), duration,

boundary conditions, what outputs are needed.

1. Set up the header and domain - &HEAD, &MESH, &TIME
2. Define materials and surfaces - &MATL, &SURF
3. Build geometry - &OBST, &HOLE, &VENT
4. Configure the fire - &REAC, &SURF with HRRPUA or pyrolysis
5. Add devices and controls - &DEVC, &CTRL, &PROP
6. Set outputs - &DUMP, &SLCF, &BNDF, &DEVC, &ISOF
7. Add `&TAIL /` at the end
8. Validate - Check mesh resolution (D*/dx), parameter consistency, units

FDS input file format

FDS input files are plain ASCII text using Fortran namelist records:

&GROUP_NAME PARAM1=value1, PARAM2=value2 /

Rules:

• Each record starts with & followed by the group name, ends with /
• Parameters separated by commas, spaces, or line breaks (never tabs)
• Strings in single or double quotes: ID='my surface'
• Logicals: .TRUE. or T, .FALSE. or F
• Reals use periods: 10. not 10 (though integers work for integer params)
• Arrays: IJK=10,20,30 or XB=0.0,1.0,0.0,2.0,0.0,3.0
• Multi-dim arrays: MATL_MASS_FRACTION(1,1:3)=0.5,0.4,0.1
• Comments: any text outside &.../ blocks
• Case-sensitive for string values; namelist keywords are uppercase
• Max 60 chars for most character parameters
• File must start with &HEAD and end with &TAIL /
• Use FYI='note' on any line for documentation

Essential namelist groups

For detailed parameter tables, read references/namelists-reference.md.

Mesh resolution guidelines

The characteristic fire diameter D* is the most important metric:

D* = (Q_dot / (rho_inf * c_p * T_inf * sqrt(g)))^(2/5)

Where Qdot = HRR (kW), rhoinf = 1.2 kg/m3, cp = 1.0 kJ/(kg*K), Tinf = 293 K, g = 9.81 m/s2. Simplified: *D ~ 0.0334 Q_dot^0.4* (meters, Q_dot in kW).

Resolution rules:

• D/dx between 4 and 16** for most engineering applications
• D/dx ~ 10** is a good starting point
• D/dx >= 20** for research-grade accuracy
• Cells should be roughly cubic (aspect ratio < 2:1)
• Use low prime factors (2,3,5) for J and K dimensions of IJK (FFT efficiency)
• The I dimension (x-direction) has no FFT restriction
• Mesh refinement ratios > 4:1 between adjacent meshes should be avoided
• Use CHECK_MESH_ALIGNMENT=T on &MESH with T_END=0 to verify alignment

For mesh sizing details, read references/mesh-resolution.md.

Minimal complete example

&HEAD CHID='room_fire', TITLE='Simple Room Fire Example' /
&MESH IJK=40,40,24, XB=0.0,4.0,0.0,4.0,0.0,2.4 /
&TIME T_END=600. /
&MISC TMPA=20. /
&DUMP NFRAMES=600, DT_DEVC=10., DT_HRR=10. /

&REAC FUEL='PROPANE' /

&MATL ID='CONCRETE', DENSITY=2300., CONDUCTIVITY=1.8, SPECIFIC_HEAT=0.88 /
&SURF ID='CONCRETE WALL', MATL_ID='CONCRETE', THICKNESS=0.2, COLOR='GRAY' /

&SURF ID='BURNER', HRRPUA=500., COLOR='RED', RAMP_Q='fire_ramp' /
&RAMP ID='fire_ramp', T=  0., F=0.0 /
&RAMP ID='fire_ramp', T= 30., F=1.0 /
&RAMP ID='fire_ramp', T=570., F=1.0 /
&RAMP ID='fire_ramp', T=600., F=0.0 /

Walls
&OBST XB=0.0,0.0,0.0,4.0,0.0,2.4, SURF_ID='CONCRETE WALL' / West wall
&OBST XB=4.0,4.0,0.0,4.0,0.0,2.4, SURF_ID='CONCRETE WALL' / East wall
&OBST XB=0.0,4.0,0.0,0.0,0.0,2.4, SURF_ID='CONCRETE WALL' / South wall
&OBST XB=0.0,4.0,4.0,4.0,0.0,2.4, SURF_ID='CONCRETE WALL' / North wall

Door opening
&HOLE XB=0.9,1.7,0.0,0.0,0.0,2.0 / Door in south wall

Fire source (1m x 1m burner on floor)
&VENT XB=1.5,2.5,1.5,2.5,0.0,0.0, SURF_ID='BURNER' / Floor burner

Open boundary at domain edges
&VENT MB='XMIN', SURF_ID='OPEN' /
&VENT MB='XMAX', SURF_ID='OPEN' /
&VENT MB='YMIN', SURF_ID='OPEN' /
&VENT MB='YMAX', SURF_ID='OPEN' /
&VENT MB='ZMAX', SURF_ID='OPEN' /

Measurement devices
&DEVC XYZ=2.0,2.0,2.2, QUANTITY='TEMPERATURE', ID='TC_ceiling' /
&DEVC XYZ=2.0,2.0,1.5, QUANTITY='VISIBILITY', ID='Vis_1.5m' /
&DEVC XYZ=1.3,0.0,1.8, QUANTITY='TEMPERATURE', ID='TC_door_top' /

Slice file outputs
&SLCF PBY=2.0, QUANTITY='TEMPERATURE' /
&SLCF PBY=2.0, QUANTITY='VELOCITY', VECTOR=T /
&SLCF PBZ=2.2, QUANTITY='TEMPERATURE' /

Boundary file output
&BNDF QUANTITY='WALL TEMPERATURE' /
&BNDF QUANTITY='GAUGE HEAT FLUX' /

&TAIL / End of file

Gotchas

• No periods/spaces in CHID: Output files use CHID as prefix; special chars break it
• `&TAIL /` is required as the last line to avoid EOF truncation issues
• XB ordering: XB(1)<XB(2), XB(3)<XB(4), XB(5)<XB(6) always (xmin,xmax,ymin,ymax,zmin,zmax)
• Thin obstructions: When two XB values are equal (e.g., XB=0,0,0,4,0,3), it creates

a zero-thickness wall. This is valid and common for walls at domain boundaries

• SURF_ID='OPEN' on a &VENT means an open boundary (passive opening to ambient). It

can ONLY be applied at the exterior boundary of the domain, never on interior surfaces

• Mesh cells snap to grid: All obstructions, vents, and holes snap to the nearest grid

cell. Ensure geometry aligns with mesh divisions to avoid unexpected thickening/thinning

• Only prescribe non-default parameters: Over-specifying causes conflicts. E.g., setting

CONDUCTIVITY on MATL triggers thermally-thick mode requiring DENSITY and SPECIFIC_HEAT

• String values are case-sensitive: 'PROPANE' not 'propane'
• Reaction fuel must match a SPEC or be a pre-defined fuel: Common pre-defined fuels

include PROPANE, METHANE, N-HEPTANE, ETHANOL, METHANOL, POLYURETHANE, etc.

• HRRPUA is per unit area: A 1m x 1m vent with HRRPUA=1000 gives 1000 kW total
• Stop a running job: Create an empty file named CHID.stop in the output directory
• Restart: Set RESTART=T on &MISC; requires CHID.restart file
• MB shortcut: MB='XMIN' applies a vent to an entire face of the mesh domain
• Multiple meshes require MPI: For parallel runs, each mesh maps to a process

For common errors and troubleshooting, read references/troubleshooting.md.

Output files reference

Running FDS

# Single mesh
fds input_file.fds

# Multiple meshes with MPI (N = number of meshes)
mpiexec -n N fds input_file.fds

# Check geometry only (no simulation)
# Set T_END=0 in the input file, then:
fds input_file.fds
# Open in Smokeview to verify geometry

Reference files

Load these on demand when you need detailed parameter information:

• references/namelists-reference.md - All 39 namelist groups with every parameter
• references/common-scenarios.md - Templates for room fires, tunnels, sprinklers, facades, WUI
• references/mesh-resolution.md - D* calculation, cell sizing, multi-mesh strategies
• references/materials-and-reactions.md - Common material properties and combustion setup
• references/output-quantities.md - Gas phase, solid phase, device, particle output quantities
• references/troubleshooting.md - Common errors, stability issues, and debugging tips