pycfast.Fire#

class pycfast.Fire(id, comp_id, fire_id=None, location=None, ignition_criterion=None, set_point=None, device_id=None, carbon=<unset>, chlorine=<unset>, hydrogen=<unset>, nitrogen=<unset>, oxygen=<unset>, heat_of_combustion=<unset>, radiative_fraction=<unset>, data_table=<unset>, definition=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, optional) – 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. Not required when definition is given (the id is taken from the definition).
location (tuple[float, 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.

definition (FireDefinition, optional) – An explicit fire definition to reference. Mutually exclusive with the chemistry arguments (carbon … data_table) and fire_id. Use this to share a single definition across several fire instances.

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 carbon: float#: Number of carbon atoms in the fuel molecule (from the definition).

property chlorine: float#: Number of chlorine atoms in the fuel molecule (from the definition).

property data_table: list[list[float]]#: Fire time-dependent data table as list of lists (from the definition).

property definition: FireDefinition#: The FireDefinition (chemistry + HRR table) this instance uses.

property fire_id: str#: Identifier of the referenced fire definition.

property heat_of_combustion: float#: Energy released per unit mass of fuel consumed (from the definition).

property hydrogen: float#: Number of hydrogen atoms in the fuel molecule (from the definition).

property nitrogen: float#: Number of nitrogen atoms in the fuel molecule (from the definition).

property oxygen: float#: Number of oxygen atoms in the fuel molecule (from the definition).

property radiative_fraction: float#: Fraction of combustion energy emitted as thermal radiation (definition).

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 the full CFAST input file string for this fire.

Emits the &FIRE instance record followed by the referenced definition’s &CHEM + &TABL records. When several instances share one definition, CFASTModel de-duplicates the definition so it is written only once; use to_instance_string and FireDefinition.to_input_string directly for that.

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 /

to_instance_string()[source]#

Generate the &FIRE CFAST input file record for this instance.

Returns:: Formatted &FIRE record (placement and ignition only — chemistry and the HRR table are emitted by the FireDefinition).
Return type:: str

Examples

>>> fire = Fire(id="FIRE1", comp_id="ROOM1", fire_id="WOOD", location=[1.0, 1.0])
>>> print(fire.to_instance_string())
&FIRE ID = 'FIRE1' COMP_ID = 'ROOM1' FIRE_ID = 'WOOD' LOCATION = 1.0, 1.0 /