pycfast.Fires#

class pycfast.Fires(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 temperature (°C) or flux (kW/m²) depending on criterion.

  • 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]], np.ndarray, or pd.DataFrame) – 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. Each row must contain exactly 9 values corresponding to the LABELS columns.

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 = Fires(
...     id="FIRE1",
...     comp_id="ROOM1",
...     fire_id="POLYURETHANE",
...     location=[2.0, 2.0],           # Center of 4x4m room
...     carbon=27, hydrogen=36, oxygen=2, nitrogen=2, chlorine=0,
...     heat_of_combustion=23600,      # kJ/kg for polyurethane
...     radiative_fraction=0.35,      # 35% radiant fraction
...     data_table=fire_data
... )

Create a fire with target-based ignition:

>>> steady_fire = Fires(
...     id="IGNITED_FIRE",
...     comp_id="BEDROOM",
...     fire_id="WOOD",
...     location=[1.5, 2.0],           # Near bed location
...     ignition_criterion="TEMPERATURE",
...     set_point=200,                 # Ignite at 200°C
...     device_id="BED_TARGET",        # Temperature measured at bed
...     carbon=1, hydrogen=4, oxygen=0, nitrogen=0, chlorine=0,
...     heat_of_combustion=50000,      # Default combustion heat
...     radiative_fraction=0.35,      # Default radiant fraction
...     data_table=[[0, 1000, 0, 1.0, 0.01, 0.01, 0, 0, 0]]  # Steady 1 MW
... )
LABELS = ['TIME', 'HRR', 'HEIGHT', 'AREA', 'CO_YIELD', 'SOOT_YIELD', 'HCN_YIELD', 'HCL_YIELD', 'TRACE_YIELD']#
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 = Fires(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['HRR'].max()  # Find peak heat release rate
1000.0
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 = Fires(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 ... /
&TABL ID = 'WOOD' LABELS = 'TIME', 'HRR', ... /
&TABL ID = 'WOOD' DATA = 0, 1000, 0.5, 1.0, 0.01, 0.01, 0, 0, 0 /