pycfast.FireDefinition

class pycfast.FireDefinition(fire_id, carbon=1, chlorine=0, hydrogen=4, nitrogen=0, oxygen=0, heat_of_combustion=50000, radiative_fraction=0.35, data_table=None)

A reusable CFAST fire definition for the chemistry (&CHEM) and table (&TABL) sections.

Fires in CFAST are defined in two parts: a “Fire Definition” that specifies the fuel composition, heat release rate, and species yields for the fire, and a “Fire Instance” (Fire) that specifies the placement of a defined fire within a compartment in the simulation.

Most of the time, you don’t need to build a FireDefinition by yourself. Passing the chemistry arguments directly to Fire creates one behind the scenes. Create one explicitly when several fires share the same definition.

Parameters:

• fire_id (str) – The selected name must be unique (i.e., not the same as another fire definition in the same simulation). IDs for fire definitions can be the same as ones for fire instances.

• carbon (float) – The number of carbon atoms in the fuel molecule. Burning fuels in CFAST are assumed to be hydrocarbon fuels that contain at least carbon and hydrogen. Default value: 1.

• chlorine (float) – The number of chlorine atoms in the fuel molecule. All of the specified chlorine is assumed to completely react to form HCl. Default value: 0.

• hydrogen (float) – The number of hydrogen atoms in the fuel molecule. Burning fuels in CFAST are assumed to be hydrocarbon fuels that contain at least carbon and hydrogen. Default value: 4.

• nitrogen (float) – The number of nitrogen atoms in the fuel molecule. All of the specified nitrogen is assumed to completely react to form HCN. Default value: 0.

• oxygen (float) – The number of oxygen atoms in the fuel molecule. Default value: 0.

• heat_of_combustion (float) – The energy released per unit mass of fuel consumed. Default units: kJ/kg, default value: 50000 kJ/kg.

• radiative_fraction (float) – The fraction of the combustion energy that is emitted in the form of thermal radiation. Default units: none, default value: 0.35.

• data_table (list[list[float]], dict, np.ndarray, or pd.DataFrame, optional) –

  Time-dependent fire properties with columns for TIME, HRR, HEIGHT, AREA, CO_YIELD, SOOT_YIELD, HCN_YIELD, HCL_YIELD, TRACE_YIELD. Properties are linearly interpolated between specified points. Defaults to DEFAULT_DATA_TABLE (a single all-zero row) when not provided.

  Index	Name	Unit	Description
  0	TIME	s	Simulation time
  1	HRR	kW	Heat release rate
  2	HEIGHT	m	Flame height
  3	AREA	m²	Fire base area
  4	CO_YIELD	kg/kg	Carbon monoxide yield
  5	SOOT_YIELD	kg/kg	Soot yield
  6	HCN_YIELD	kg/kg	Hydrogen cyanide yield
  7	HCL_YIELD	kg/kg	Hydrogen chloride yield
  8	TRACE_YIELD	kg/kg	Trace species yield

  If a dict is used, keys must match column names from LABELS and values can be either a list of floats (one per timestep) or a scalar float (repeated for all timesteps). All list-valued columns must have the same length.

Examples

Define a fire once and place it twice in a compartment:

>>> defn = FireDefinition(
...     fire_id="100kW",
...     heat_of_combustion=50000,
...     data_table=[[0, 100, 0.5, 0.36, 0, 0.001, 0, 0, 0]],
... )
>>> burner1 = Fire(id="burner1", comp_id="ROOM1", location=[5.45, 2.15],
...                definition=defn)
>>> burner2 = Fire(id="burner2", comp_id="ROOM1", location=[4.25, 2.15],
...                definition=defn)

DEFAULT_DATA_TABLE: list[list[float]] = [[0, 0, 0, 0, 0, 0, 0, 0, 0]]

LABELS = ['TIME', 'HRR', 'HEIGHT', 'AREA', 'CO_YIELD', 'SOOT_YIELD', 'HCN_YIELD', 'HCL_YIELD', 'TRACE_YIELD']

property data_table: list[list[float]]

Fire time-dependent data table as list of lists.

to_dataframe()

Convert the fire data table to a pandas DataFrame with proper column labels.

Returns:

DataFrame with columns matching LABELS.

Return type:

pd.DataFrame

Examples

>>> defn = FireDefinition(
...     fire_id="WOOD",
...     data_table=[[0, 1000, 0.5, 1.0, 0.01, 0.01, 0, 0, 0]],
... )
>>> defn.to_dataframe()
TIME     HRR  HEIGHT  AREA  ...
0   0.0  1000.0     0.5   1.0  ...
[1 rows x 9 columns]

to_input_string()

Generate the &CHEM + &TABL CFAST input file string for this definition.

Returns:

Formatted &CHEM record followed by the &TABL labels record and one &TABL data record per row of the HRR table.

Return type:

str

Examples

>>> defn = FireDefinition(
...     fire_id="WOOD",
...     data_table=[[0, 1000, 0.5, 1.0, 0.01, 0.01, 0, 0, 0]],
... )
>>> print(defn.to_input_string())
&CHEM ID = 'WOOD' CARBON = 1 CHLORINE = 0 HYDROGEN = 4 NITROGEN = 0 OXYGEN = 0 HEAT_OF_COMBUSTION = 50000 RADIATIVE_FRACTION = 0.35 /
&TABL ID = 'WOOD' LABELS = 'TIME', 'HRR', 'HEIGHT', 'AREA', 'CO_YIELD', 'SOOT_YIELD', 'HCN_YIELD', 'HCL_YIELD', 'TRACE_YIELD' /
&TABL ID = 'WOOD' DATA = 0.0, 1000.0, 0.5, 1.0, 0.01, 0.01, 0.0, 0.0, 0.0 /