--- name: fds-input-generator description: > Expert assistant for NIST Fire Dynamics Simulator (FDS). Generates, reviews, debugs, and optimizes FDS input files (.fds). Use when the user mentions FDS, fire simulation, fire dynamics, Smokeview, CFD fire modeling, compartment fire, smoke management, sprinkler activation, heat release rate, fire protection engineering, pyrolysis modeling, or asks to create/edit .fds files. license: Apache-2.0 compatibility: Requires FDS 6.x installed (fds executable in PATH) for running simulations. metadata: author: fire-dynamics-skill version: "1.0" fds-version: "6.10.1" source-doc: "NIST Special Publication 1019, Sixth Edition" allowed-tools: Bash(fds:*) Read Write Edit --- # 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](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/(kg*K), 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](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)