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.
2. Set up the header and domain - &HEAD, &MESH, &TIME
3. Define materials and surfaces - &MATL, &SURF
4. Build geometry - &OBST, &HOLE, &VENT
5. Configure the fire - &REAC, &SURF with HRRPUA or pyrolysis
6. Add devices and controls - &DEVC, &CTRL, &PROP
7. Set outputs - &DUMP, &SLCF, &BNDF, &DEVC, &ISOF
8. Add &TAIL / at the end
9. 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

Group	Purpose	Key Parameters
HEAD	Job ID and title	CHID, TITLE
MESH	Computational domain	IJK, XB, MPI_PROCESS
TIME	Simulation duration	T_END, T_BEGIN
MISC	Global settings	TMPA, RESTART, SIMULATION_MODE
DUMP	Output frequency	NFRAMES, DT_HRR, DT_DEVC, DT_SLCF
REAC	Combustion reaction	FUEL, C, H, O, N, SOOT_YIELD, CO_YIELD
MATL	Material properties	CONDUCTIVITY, SPECIFIC_HEAT, DENSITY, EMISSIVITY
SURF	Surface properties	ID, MATL_ID, THICKNESS, HRRPUA, COLOR
OBST	Solid obstructions	XB, SURF_ID, SURF_ID6, COLOR
HOLE	Cutouts in obstructions	XB, CTRL_ID, DEVC_ID
VENT	Boundary vents/openings	XB, MB, SURF_ID
DEVC	Measurement devices	XYZ, QUANTITY, ID, PROP_ID
CTRL	Control logic	FUNCTION_TYPE, INPUT_ID, SETPOINT
PROP	Device properties	QUANTITY, ACTIVATION_TEMPERATURE, RTI
SLCF	Slice file output	PBX/PBY/PBZ, QUANTITY, VECTOR
BNDF	Boundary file output	QUANTITY
ISOF	Isosurface output	QUANTITY, VALUE
RAMP	Time/temp profiles	ID, T, F
SPEC	Chemical species	ID, MW, LUMPED_COMPONENT_ONLY
PART	Lagrangian particles	ID, DIAMETER, QUANTITIES_PER_SECOND
MULT	Multiplier/arrays	ID, DX, DY, DZ, I_UPPER
RADI	Radiation solver	RADIATION, NUMBER_RADIATION_ANGLES
WIND	Wind conditions	SPEED, DIRECTION, Z_0
ZONE	Pressure zones	XB, ID
INIT	Initial conditions	XB, TEMPERATURE, MASS_FRACTION
PRES	Pressure solver	SOLVER, MAX_PRESSURE_ITERATIONS
HVAC	HVAC ducts/fans	ID, TYPE_ID, DUCT_ID, NODE_ID

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 Q_dot = HRR (kW), rho_inf = 1.2 kg/m3, c_p = 1.0 kJ/(kgK), T_inf = 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

Extension	Content	Generated By
.out	Diagnostic log, error messages	Always
_hrr.csv	HRR, MLR, radiation	Always
_devc.csv	Device measurements	&DEVC lines
.sf	Slice file (2D planes)	&SLCF lines
.bf	Boundary file (surface data)	&BNDF lines
.iso	Isosurface data	&ISOF lines
.prt5	Particle/droplet data	&PART lines
.s3d	3D smoke data	&DUMP SMOKE3D=T
.restart	Restart checkpoint	DT_RESTART on &DUMP
_cfl.csv	CFL/VN stability data	CFL_FILE=T on &DUMP
_ctrl.csv	Control function states	&CTRL lines
_mass.csv	Gas species mass data	MASS_FILE=T on &DUMP

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