pycfast.Fire#

class pycfast.Fire(id, comp_id, fire_id, location, ignition_criterion=None, set_point=None, device_id=None, carbon=1, chlorine=0, hydrogen=4, nitrogen=0, oxygen=0, heat_of_combustion=50000, radiative_fraction=0.35, data_table=None)[source]#

Represents a fire source in a CFAST simulation.

A fire in CFAST is specified via a time-dependent heat release rate (HRR). The specified heat of combustion is used to calculate the mass loss rate of fuel, from which the production rate of combustion products can be calculated using specified product yields. The heat release and the corresponding product generation rates go to zero when the lower oxygen limit is reached, and are replaced by the appropriate production rate of unburned fuel gas which is transported from zone to zone until there is sufficient oxygen and a high enough temperature to support combustion. The model can simulate multiple fires in one or more compartments. These fires are treated as totally separate entities, with no interaction of the plumes. These fires can be ignited at a prescribed time, or when a corresponding target reaches a specified temperature or heat flux. 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” that specifies the placement of a defined fire within a compartment in the simulation. A single fire definition may be associated with more than one fire instance in a simulation if desired. The combustion model is defined by a one-step reaction where burning fuels in CFAST are assumed to be hydrocarbon fuels that contain at least carbon and hydrogen and optionally oxygen, nitrogen, and chlorine. All of the specified nitrogen and chlorine is assumed to completely react to form HCN and HCl. Fire properties are linearly interpolated between specified time points. If the simulation time is longer than the total duration of the fire, the final values specified for the fire are continued until the end of the simulation.

Parameters:

id (str) – The selected name must be unique (i.e., not the same as another fire instance in the same simulation).
comp_id (str) – Name of the compartment where the fire occurs.
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.
location (list[float]) – Position of the center of the base of the fire relative to the front left corner of the compartment. Format: [x, y]. Default units: m, default value: compartment center.
ignition_criterion (str, optional) – The time of ignition can be controlled by a user-specified time, or by a user-specified target’s surface temperature or incident heat flux. Options: “TIME”, “TEMPERATURE”, “FLUX”.
set_point (float, optional) – The critical value at which ignition will occur. If it is less than or equal to zero, the default value of zero is taken. Can be a time (s), temperature (°C), or flux (kW/m²) depending on criterion. Required when ignition_criterion is set.
device_id (str, optional) – User-specified target used to calculate surface temperature or incident heat flux to ignite fire. Target is typically placed at the base of the fire to be ignited.
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

Create a simple growing fire:

>>> fire_data = [
...     [0, 0, 0.5, 0.1, 0.01, 0.01, 0, 0, 0],      # t=0s, no heat release
...     [60, 100, 0.5, 0.5, 0.01, 0.01, 0, 0, 0],   # t=60s, 100 kW
...     [300, 500, 1.0, 1.0, 0.01, 0.01, 0, 0, 0]   # t=300s, 500 kW peak
... ]
>>> fire = Fire(
...     id="FIRE1",
...     comp_id="ROOM1",
...     fire_id="POLYURETHANE",
...     location=[2.0, 2.0],
...     carbon=27, hydrogen=36, oxygen=2, nitrogen=2, chlorine=0,
...     heat_of_combustion=23600,
...     radiative_fraction=0.35,
...     data_table=fire_data
... )

Create a fire with a dict-format data table:

>>> fire_data_dict = {
...     "TIME": [0, 60, 300],
...     "HRR": [0, 100, 500],
...     "HEIGHT": [0.5, 0.5, 1.0],
...     "AREA": [0.1, 0.5, 1.0],
...     "CO_YIELD": 0.01,
...     "SOOT_YIELD": 0.01,
...     "HCN_YIELD": 0,
...     "HCL_YIELD": 0,
...     "TRACE_YIELD": 0,
... }
>>> fire = Fire(
...     id="FIRE2",
...     comp_id="ROOM1",
...     fire_id="POLYURETHANE",
...     location=[2.0, 2.0],
...     carbon=27, hydrogen=36, oxygen=2, nitrogen=2, chlorine=0,
...     heat_of_combustion=23600,
...     radiative_fraction=0.35,
...     data_table=fire_data_dict
... )

Create a fire with a pandas DataFrame:

>>> import pandas as pd
>>> fire_data_df = pd.DataFrame({
...     "TIME": [0, 60, 300],
...     "HRR": [0, 100, 500],
...     "HEIGHT": [0.5, 0.5, 1.0],
...     "AREA": [0.1, 0.5, 1.0],
...     "CO_YIELD": [0.01, 0.01, 0.01],
...     "SOOT_YIELD": [0.01, 0.01, 0.01],
...     "HCN_YIELD": [0, 0, 0],
...     "HCL_YIELD": [0, 0, 0],
...     "TRACE_YIELD": [0, 0, 0],
... })
>>> fire = Fire(
...     id="FIRE3",
...     comp_id="ROOM1",
...     fire_id="POLYURETHANE",
...     location=[2.0, 2.0],
...     carbon=27, hydrogen=36, oxygen=2, nitrogen=2, chlorine=0,
...     heat_of_combustion=23600,
...     radiative_fraction=0.35,
...     data_table=fire_data_df
... )

The LABELS for the data table are fixed and must be in the following order below:

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()[source]#

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

Returns:: DataFrame with columns matching LABELS for easy analysis and plotting.
Return type:: pd.DataFrame

Examples

>>> fire = Fire(
...     id="FIRE1",
...     comp_id="ROOM1",
...     fire_id="WOOD",
...     location=[1.0, 1.0],
...     data_table=[[0, 1000, 0.5, 1.0, 0.01, 0.01, 0, 0, 0]]
... )
>>> df = fire.to_dataframe()
>>> df
TIME     HRR  HEIGHT  AREA  ...
0   0.0  1000.0     0.5   1.0  ...
[1 rows x 9 columns]

to_input_string()[source]#

Generate CFAST input file string for this fire.

Returns:: Formatted string ready for inclusion in CFAST input file.
Return type:: str

Examples

>>> fire = Fire(
...     id="FIRE1",
...     comp_id="ROOM1",
...     fire_id="WOOD",
...     location=[1.0, 1.0],
...     data_table=[[0, 1000, 0.5, 1.0, 0.01, 0.01, 0, 0, 0]]
... )
>>> print(fire.to_input_string())
&FIRE ID = 'FIRE1' COMP_ID = 'ROOM1' FIRE_ID = 'WOOD' LOCATION = 1.0, 1.0 /
&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 /