pycfast.CFASTModel#

class pycfast.CFASTModel(simulation_environment, compartments, material_properties=None, wall_vents=None, ceiling_floor_vents=None, mechanical_vents=None, fires=None, devices=None, surface_connections=None, file_name='cfast_input.in', cfast_exe='cfast', extra_arguments=None)[source]#

Main class for creating and running CFAST fire simulations.

This class handles the creation of CFAST input files from Python objects and executes the CFAST simulation, returning results as pandas DataFrames.

The CFASTModel combines all the necessary components of a fire simulation: scenario configuration, compartments, vents, fires, targets, and material properties into a single model that can be executed.

Parameters:

  • simulation_environment (SimulationEnvironment) – Basic simulation parameters and settings

  • material_properties (List[MaterialProperties]) – List of material property definitions

  • compartments (List[Compartments]) – List of compartment/room definitions

  • wall_vents (List[WallVents]) – List of wall vent connections between compartments

  • ceiling_floor_vents (List[CeilingFloorVents]) – List of ceiling/floor vent connections

  • mechanical_vents (List[MechanicalVents]) – List of mechanical ventilation systems

  • fires (List[Fires]) – List of fire definitions

  • targets (List[Devices]) – List of target/sensor definitions

  • file_name (str) – Name of the CFAST input file to generate

  • cfast_exe (str) – Path to the CFAST executable

  • extra_arguments (List[str]) – Additional command-line arguments for CFAST

Examples

Create and run a simple fire simulation:

>>> model = CFASTModel(
...     simulation_environment=simulation_env,
...     compartments=[room1, room2],
...     material_properties=[concrete, gypsum],
...     wall_vents=[door],
...     fires=[fire1],
...     devices=[temp_sensor],
...     file_name="simulation.in"
... )
>>> results = model.run()
>>> print(results['simulation_compartments.csv'].head())

Create a minimal simulation with just compartments:

>>> minimal_model = CFASTModel(
...     scenario_configuration=scenario_config,
...     compartments=[room1]
... )
>>> results = minimal_model.run()
add_ceiling_floor_vent(vent)[source]#

Add a ceiling/floor vent to the model and return a new model instance.

Parameters:

vent (CeilingFloorVents) – Ceiling/floor vent object to add to the model

Returns:

New model instance with the added ceiling/floor vent

Return type:

CFASTModel

Examples

>>> hatch = CeilingFloorVents(comp_ids=["ROOM1", "ROOM2"], area=0.5)
>>> updated_model = model.add_ceiling_floor_vent(hatch)
add_compartment(compartment)[source]#

Add a compartment to the model and return a new model instance.

Parameters:

compartment (Compartments) – Compartment object to add to the model

Returns:

New model instance with the added compartment

Return type:

CFASTModel

Examples

>>> new_room = Compartments(id="ROOM3", width=5.0, depth=4.0, height=3.0)
>>> updated_model = model.add_compartment(new_room)
add_device(device)[source]#

Add a device/target to the model and return a new model instance.

Parameters:

device (Devices) – Device object to add to the model

Returns:

New model instance with the added device

Return type:

CFASTModel

Examples

>>> sensor = Devices.create_heat_detector(
...     comp_id="ROOM1", location=[2.0, 2.0, 2.4], temperature=68.0
... )
>>> updated_model = model.add_device(sensor)
add_fire(fire)[source]#

Add a fire to the model and return a new model instance.

Parameters:

fire (Fires) – Fire object to add to the model

Returns:

New model instance with the added fire

Return type:

CFASTModel

Examples

>>> new_fire = Fires(id="FIRE2", comp_id="ROOM1", location=[2.0, 2.0])
>>> updated_model = model.add_fire(new_fire)
add_material(material)[source]#

Add a material property to the model and return a new model instance.

Parameters:

material (MaterialProperties) – Material properties object to add to the model

Returns:

New model instance with the added material

Return type:

CFASTModel

Examples

>>> steel = MaterialProperties(id="STEEL", conductivity=45.0, density=7850)
>>> updated_model = model.add_material(steel)
add_mechanical_vent(vent)[source]#

Add a mechanical vent to the model and return a new model instance.

Parameters:

vent (MechanicalVents) – Mechanical vent object to add to the model

Returns:

New model instance with the added mechanical vent

Return type:

CFASTModel

Examples

>>> hvac = MechanicalVents(comp_ids=["ROOM1", "OUTSIDE"], flow_rate=0.5)
>>> updated_model = model.add_mechanical_vent(hvac)
add_surface_connection(connection)[source]#

Add a surface connection to the model and return a new model instance.

Parameters:

connection (SurfaceConnections) – Surface connection object to add to the model

Returns:

New model instance with the added surface connection

Return type:

CFASTModel

Examples

>>> wall_conn = SurfaceConnections.wall_connection(
...     comp_ids=["ROOM1", "ROOM2"], fraction=0.5
... )
>>> updated_model = model.add_surface_connection(wall_conn)
add_wall_vent(vent)[source]#

Add a wall vent to the model and return a new model instance.

Parameters:

vent (WallVents) – Wall vent object to add to the model

Returns:

New model instance with the added wall vent

Return type:

CFASTModel

Examples

>>> door = WallVents(comp_ids=["ROOM1", "ROOM2"], width=1.0, height=2.0)
>>> updated_model = model.add_wall_vent(door)
run(file_name=None, timeout=None, verbose=False)[source]#

Execute the CFAST simulation and return results.

This method writes the input file, runs CFAST, and reads the output CSV files into pandas DataFrames. The simulation creates several output files with different types of data.

Parameters:

  • file_name (str, optional) – Optional filename/path for this specific run. If provided, temporarily overrides the model’s file_name for this execution only. The model’s original file_name remains unchanged. Useful for batch processing, sensitivity analysis, or saving runs with descriptive names.

  • timeout (int | float, optional) – Maximum time in seconds to allow for CFAST execution. If the execution exceeds this time, it will be terminated. If None, no timeout will be applied.

  • verbose (bool, optional) – If True, prints CFAST stdout and stderr to the console.

Returns:

Dictionary mapping CSV filenames to pandas DataFrames containing simulation results. Keys include: - ‘compartments’: Compartment conditions over time - ‘devices’: Device/target measurements - ‘masses’: Mass flow data - ‘vents’: Vent flow data - ‘walls’: Wall heat transfer data - ‘zone’: Zone-specific data - ‘diagnostics’: Diagnostic information (if generated with &DIAG)

Returns None if simulation fails.

Return type:

dict[str, pd.DataFrame]

Raises:

  • subprocess.CalledProcessError: – If CFAST execution fails

  • FileNotFoundError: – If CFAST executable is not found

  • pd.errors.ParserError: – If output CSV files cannot be parsed

Examples

>>> results = model.run()
>>> if results:
...     temp_data = results['simulation_compartments.csv']
...     print(f"Max temperature: {temp_data['CEILT'].max()}")

>>> # Run with custom filename for sensitivity analysis
>>> results = model.run(file_name="sensitivity_case_1.in")
save(file_name=None)[source]#

Save the CFAST input file and return its absolute path.

Parameters:

file_name (str, optional) – filename/path for this specific save operation. If provided, temporarily overrides the model’s file_name for this save only. The model’s original file_name remains unchanged. Useful for creating backups, saving variants, or organizing output files.

Returns:

Absolute path to the saved input file.

Return type:

str

Examples

>>> # Save with default filename
>>> path = model.save()

>>> # Save backup without changing model's file_name
>>> backup_path = model.save(file_name="backup/model_v1.in")
summary()[source]#

Print a clear summary of the CFAST model configuration.

Shows the model info and all components with their current parameter values using each component’s string representation.

Return type:

None

Examples

>>> model.summary()
Model: my_simulation.in
Simulation: 'Building Fire Test' (3600s)
Material Properties (2):

MaterialProperties(material=’GYPSUM’, conductivity=0.17, density=800…)

Compartments (2):

Compartments(id=’ROOM1’, width=4.0, depth=3.0, height=2.5…)

update_ceiling_floor_vent_params(vent=None, vent_index=None, **kwargs)[source]#

Update ceiling/floor vent parameters and return a new model instance.

Parameters:

  • vent (int | str | None, optional) – Ceiling/floor vent identifier. Can be: - int: Vent index (0-based) - str: Vent id - None: Updates first vent (index 0)

  • vent_index (int, optional) – Deprecated. Use ‘vent’ parameter instead.

  • **kwargs (Any) – Ceiling/floor vent attributes to update. See CeilingFloorVents class documentation for available parameters.

Returns:

New model instance with updated ceiling/floor vent parameters

Return type:

CFASTModel

Examples

>>> new_model = model.update_ceiling_floor_vent_params(
...     vent=0,
...     area=0.5
... )
update_compartment_params(compartment=None, compartment_index=None, **kwargs)[source]#

Update compartment parameters and return a new model instance.

Parameters:

  • compartment (int | str | None, optional) – Compartment identifier. Can be: - int: Compartment index (0-based) - str: Compartment id - None: Updates first compartment (index 0)

  • compartment_index (int, optional) – Deprecated. Use ‘compartment’ parameter instead.

  • **kwargs (Any) – Compartment attributes to update. See Compartments class documentation for available parameters.

Returns:

New model instance with updated compartment parameters

Return type:

CFASTModel

Examples

>>> new_model = model.update_compartment_params(
...     width=5.0,
...     height=3.0,
...     compartment=1
... )

>>> new_model = model.update_compartment_params(
...     compartment="living_room",
...     width=6.0
... )
update_device_params(device=None, device_index=None, **kwargs)[source]#

Update device/target parameters and return a new model instance.

Parameters:

  • device (int | str | None, optional) – Device identifier. Can be: - int: Device index (0-based) - str: Device id - None: Updates first device (index 0)

  • device_index (int, optional) – Deprecated. Use ‘device’ parameter instead.

  • **kwargs (Any) – Device attributes to update. See Devices class documentation for available parameters.

Returns:

New model instance with updated device parameters

Return type:

CFASTModel

Examples

>>> new_model = model.update_device_params(
...     device=0,
...     location=[2.0, 2.0, 2.4]
... )
update_fire_params(fire=None, fire_index=None, data_table=None, **kwargs)[source]#

Update fire parameters and return a new model instance.

Parameters:

  • fire (int | str | None, optional) – Fire identifier. Can be: - int: Fire index (0-based) - str: “fire_id” or “id” (yes it’s different) - None: Updates first fire (index 0)

  • fire_index (int, optional) – Deprecated. Use ‘fire’ parameter instead. Fire index (0-based). If both fire and fire_index are provided, ‘fire’ takes precedence.

  • data_table (list[list[float]], np.ndarray, or pd.DataFrame, optional) – New fire data table to replace existing one. Must have 9 columns: TIME, HRR, HEIGHT, AREA, CO_YIELD, SOOT_YIELD, HCN_YIELD, HCL_YIELD, TRACE_YIELD.

  • **kwargs (Any) – Fire object attributes to update. See Fires class documentation for available parameters.

Returns:

New model instance with updated fire parameters

Return type:

CFASTModel

Examples

>>> # Update scalar fire properties
>>> new_model = model.update_fire_params(
...     heat_of_combustion=20000,
...     radiative_fraction=0.35
... )

>>> # Update fire data table with pandas DataFrame
>>> fire_data = pd.DataFrame({
...     'time': [0, 60, 120],
...     'heat_release_rate': [0, 1000, 2000],
...     'height': [0.5, 0.5, 0.5],
...     'area': [1.0, 1.0, 1.0],
...     'co_yield': [0.004, 0.004, 0.004],
...     'soot_yield': [0.01, 0.01, 0.01],
...     'hcn_yield': [0.0, 0.0, 0.0],
...     'hcl_yield': [0.0, 0.0, 0.0],
...     'trace_yield': [0.0, 0.0, 0.0]
... })
>>> new_model = model.update_fire_params(data_table=fire_data)

>>> # Update fire data table with numpy array
>>> import numpy as np
>>> fire_array = np.array([
...     [0, 0, 0.5, 1.0, 0.004, 0.01, 0.0, 0.0, 0.0],
...     [60, 1000, 0.5, 1.0, 0.004, 0.01, 0.0, 0.0, 0.0],
...     [120, 2000, 0.5, 1.0, 0.004, 0.01, 0.0, 0.0, 0.0]
... ])
>>> new_model = model.update_fire_params(data_table=fire_array)

>>> # Update fire data table with list of lists
>>> fire_list = [
...     [0, 0, 0.5, 1.0, 0.004, 0.01, 0.0, 0.0, 0.0],
...     [60, 1000, 0.5, 1.0, 0.004, 0.01, 0.0, 0.0, 0.0],
...     [120, 2000, 0.5, 1.0, 0.004, 0.01, 0.0, 0.0, 0.0]
... ]
>>> new_model = model.update_fire_params(data_table=fire_list)

>>> # Update by fire name
>>> new_model = model.update_fire_params(
...     fire="main_fire",
...     heat_of_combustion=18000
... )
update_material_params(material=None, material_index=None, **kwargs)[source]#

Update material properties parameters and return a new model instance.

Parameters:

  • material (int | str | None, optional) – Material identifier. Can be: - int: Material index (0-based) - str: Material id - None: Updates first material (index 0)

  • material_index (int, optional) – Deprecated. Use ‘material’ parameter instead.

  • **kwargs (Any) – Material properties attributes to update. See MaterialProperties class documentation for available parameters.

Returns:

New model instance with updated material parameters

Return type:

CFASTModel

Examples

>>> new_model = model.update_material_params(
...     material="concrete",
...     conductivity=1.5,
...     density=2300
... )
update_mechanical_vent_params(vent=None, vent_index=None, **kwargs)[source]#

Update mechanical vent parameters and return a new model instance.

Parameters:

  • vent (int | str | None, optional) – Mechanical vent identifier. Can be: - int: Vent index (0-based) - str: Vent id - None: Updates first vent (index 0)

  • vent_index (int, optional) – Deprecated. Use ‘vent’ parameter instead.

  • **kwargs (Any) – Mechanical vent attributes to update. See MechanicalVents class documentation for available parameters.

Returns:

New model instance with updated mechanical vent parameters

Return type:

CFASTModel

Examples

>>> new_model = model.update_mechanical_vent_params(
...     vent=0,
...     flow_rate=0.5
... )
update_simulation_params(**kwargs)[source]#

Update simulation environment parameters and return a new model instance.

Parameters:

**kwargs (Any) – Simulation environment attributes to update. See SimulationEnvironment class documentation for available parameters.

Returns:

New model instance with updated simulation parameters

Return type:

CFASTModel

Examples

>>> new_model = model.update_simulation_params(
...     time_simulation=1800,
...     print=10,
...     interior_temperature=25.0
... )
update_surface_connection_params(connection_index=None, **kwargs)[source]#

Update surface connection parameters and return a new model instance.

Parameters:

  • connection (int | None, optional) – Surface connection identifier. Can be: - int: Connection index (0-based) - None: Updates first connection (index 0)

  • connection_index (int, optional) – Deprecated. Use ‘connection’ parameter instead.

  • **kwargs (Any) – Surface connection attributes to update. See SurfaceConnections class documentation for available parameters.

Returns:

New model instance with updated surface connection parameters

Return type:

CFASTModel

Examples

>>> new_model = model.update_surface_connection_params(
...     connection=0,
...     fraction=0.8
... )
update_wall_vent_params(vent=None, vent_index=None, **kwargs)[source]#

Update wall vent parameters and return a new model instance.

Parameters:

  • vent (int | str | None, optional) – Wall vent identifier. Can be: - int: Vent index (0-based) - str: Vent id - None: Updates first vent (index 0)

  • vent_index (int, optional) – Deprecated. Use ‘vent’ parameter instead.

  • **kwargs (Any) – Wall vent attributes to update. See WallVents class documentation for available parameters.

Returns:

New model instance with updated wall vent parameters

Return type:

CFASTModel

Examples

>>> new_model = model.update_wall_vent_params(
...     vent=0,
...     width=1.2,
...     height=2.0
... )
view_cfast_input_file(pretty_print=True)[source]#

View the contents of the CFAST input file as a string, with optional pretty formatting.

Parameters:

pretty_print (bool, optional) – If True (default), returns a formatted string with line numbers and bold section headers for improved readability in the terminal. If False, returns the raw input file contents as a plain string.

Notes

Use print() to display the formatted content properly: print(model.view_cfast_input_file())

Returns:

Contents of the input file

Return type:

str

Raises:

RuntimeError: – If the input file has not been generated yet (call save() or run() first).

Examples

>>> print(model.view_cfast_input_file())  # Pretty-printed with line numbers
>>> content = model.view_cfast_input_file(pretty_print=False)  # Raw content
>>> print(content)