What your FDS case must provide

Read this before pointing --fds-dir at a case for the first time. To check a deck for these slices before FDS runs, and to build the scenario from it, see Start from your own FDS case.

pyFDS-Evac never runs FDS. It reads the output of a finished FDS run. A deck written for some other purpose usually will not work as-is: it has to be told to dump the specific slices this tool samples.

The slices

&SLCF PBZ=1.6, QUANTITY='EXTINCTION COEFFICIENT' /
&SLCF PBZ=1.6, QUANTITY='VOLUME FRACTION', SPEC_ID='CARBON MONOXIDE' /
&SLCF PBZ=1.6, QUANTITY='VOLUME FRACTION', SPEC_ID='CARBON DIOXIDE' /
&SLCF PBZ=1.6, QUANTITY='VOLUME FRACTION', SPEC_ID='OXYGEN' /
&SLCF PBZ=1.6, QUANTITY='TEMPERATURE' /
&DUMP DT_SLCF=1.0 /

Nothing here is dumped by default. FDS writes only what the deck asks for.

For the default species (soot), FDS records the extinction-coefficient slice internally as SOOT EXTINCTION COEFFICIENT, and that is the exact quantity name load_slice_sampler looks up (fds-sampling.md).

It is all three gases or none of them; there is no partial FED. TEMPERATURE is independent of that gate — it needs neither CO/CO2/O2 nor any &REAC yield to work (see below), so a case can have heat FED without toxic FED or vice versa.

EXTINCTION and EXTINCTION COEFFICIENT are two unrelated gas-phase output quantities (FDS User Guide Table 22.4) — don’t confuse them. EXTINCTION (Sec. 22.10.29) is a combustion-suppression flag with no units: 0 if the extinction routine did not prevent combustion, 1 if it did, -1 if there was no fuel or oxidizer. EXTINCTION COEFFICIENT (Sec. 22.10.5) is the light extinction coefficient K [1/m] that the smoke-speed model actually needs. If your deck has QUANTITY='EXTINCTION' where you meant the extinction coefficient, fix it to QUANTITY='EXTINCTION COEFFICIENT' and rerun FDS.

pyFDS-Evac reads &SLCF output only. &DEVC device output is listed by --inspect-fds but not read by the run.

Check the deck before you run FDS

pyfds-evac init DECK.fds --check reads the deck, before FDS runs, and writes nothing. It applies the run’s rule for choosing a slice and reports each slice of the table above, &TIME T_END, DT_SLCF and the &REAC yields, with the &SLCF line to add for each missing one. It exits with 0 when the deck has the extinction coefficient, CO, CO2, O2 and T_END, with 3 when one is missing, and with 1 when the deck cannot be read, the floor cannot be chosen or an argument is wrong. The full list is in Usage › init –check, and Start from your own FDS case shows it on a ready deck and on one that fails.

Declaring a slice is not enough

The species also has to exist in the run. Under simple chemistry, OXYGEN, NITROGEN, WATER VAPOR and CARBON DIOXIDE are always present, but CARBON MONOXIDE only exists if CO_YIELD is set on &REAC, and SOOT only if SOOT_YIELD is set. A plain &REAC FUEL='PROPANE' / cannot produce FED no matter what &SLCF lines you add. Fix it at the source:

&REAC FUEL='CABLE_FUEL', C=3, H=5, O=0, N=1,
      SOOT_YIELD=0.172, CO_YIELD=0.063, HCN_YIELD=0.006,
      HEAT_OF_COMBUSTION=16400 /

Yields are fuel properties: take them from your material’s data rather than copying these, together with a heat of combustion that fits them. FDS takes the fuel mass flux as HRRPUA divided by HEAT_OF_COMBUSTION (FDS User Guide §9.1) and, with the default IDEAL=F, treats that value as an effective heat of combustion (§13.1.2). The soot released per unit of heat is therefore SOOT_YIELD divided by it. The PVC example of the User Guide (§13.2.2) uses the same 16,400 kJ/kg with these soot and CO yields, taken from the SFPE Handbook. In SFPE Handbook Table A.39 (5th ed., 2016, Appendix 3, doi:10.1007/978-1-4939-2565-0), 16,400 kJ/kg is the net heat of complete combustion of PVC; the chemical heat of combustion listed there is 5,700 kJ/kg. With 16,400 kJ/kg the fire releases about 10 g of soot per MJ, with 5,700 kJ/kg about 30 g (our arithmetic). FDS also takes the oxygen consumed from the reaction and ignores EPUMO2 once HEAT_OF_COMBUSTION is given (§13.1.1–13.1.2), so a value that does not fit the reaction changes the energy released per unit mass of oxygen from the default 13,100 kJ/kg: for the reaction above, 16,400 kJ/kg means about 8,300 kJ/kg (our arithmetic).

TEMPERATURE is the one exception: it is a core solved gas-phase variable in every FDS run, not a species yield, so it needs no &REAC setup at all — the &SLCF line above is sufficient on its own.

Silent failure modes

FED disabled. If CO, CO2 or O2 is missing, pyFDS-Evac carries on with smoke speed only. If the heat FED is off too, the result has no FED at all: fed_history is None, metrics has no fed_max, and --output-fed-history writes no file. If the heat FED runs but the gas FED does not, the FED history exists and its fed_cumulative column is all zero, which looks exactly like a survivable fire. Check metrics["fed_max"], or the warning, which is logged every time (#137):

FED is disabled for <dir>: it has no CO slice, and all three of CO, CO2 and
O2 are needed. ...

Heat FED disabled. The heat FED track is off unless --enable-heat-fed is given. With it, the same applies as for the gases: if there is no TEMPERATURE slice, heat FED is off, metrics has no heat_fed_max, and any heat FED column in the history reads zero:

Heat FED is disabled for <dir>: it has no TEMPERATURE slice. ...

Wrong slice height. --smoke-slice-height (default 1.6 m, FDS+Evac’s HUMAN_SMOKE_HEIGHT) is a preference, not a filter: a case with one slice of a quantity uses it whatever its height, and a mismatch never fails the run. A case you inherit often carries a single slice at whatever height its author chose, so you can end up sampling floor-level CO for standing agents. A warning fires only past 0.5 m. The common case, a request of 1.6 m on a deck with a single slice at 2.0 m, is 0.4 m away and gives no warning (#165). Beyond 0.5 m you see:

Requested a 'SOOT EXTINCTION COEFFICIENT' slice at z=0.50 m but the nearest
available in <dir> is at z=2.00 m ...

Do not ignore these warnings. Nothing else will tell you.

Failure modes

Errors from the command line itself (wrong --fds-dir, conflicting flags) are listed on Troubleshooting.