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=None, 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[Material]) – List of material property definitions
compartments (List[Compartment]) – List of compartment/room definitions
wall_vents (List[WallVent]) – List of wall vent connections between compartments
ceiling_floor_vents (List[CeilingFloorVent]) – List of ceiling/floor vent connections
mechanical_vents (List[MechanicalVent]) – List of mechanical ventilation systems
fires (List[Fire]) – List of fire definitions
targets (List[Device]) – 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()  

Create a minimal simulation with just compartments:

>>> model = CFASTModel(
...     simulation_environment=simulation_env,
...     compartments=[room1]
... )
>>> results = model.run()  

add(component)[source]#

Add a component to the model and return a new model instance with it included.

Parameters:

component (CFASTComponent) – One of: Fire, Compartment, Material, WallVent, CeilingFloorVent, MechanicalVent, Device, SurfaceConnection.

Returns:

New model instance with component appended to its list.

Return type:

CFASTModel

Raises:

TypeError – If component is not a supported component type.
ValueError – If the resulting model fails dependency validation (e.g. a fire references a compartment that does not exist).

Examples

Add a fire:

>>> new_fire = Fire(id="FIRE2", comp_id="ROOM1", fire_id="POLYURETHANE", location=[2.0, 2.0])
>>> updated_model = model.add(new_fire)

Add a compartment:

>>> new_room = Compartment(id="ROOM3", width=5.0, depth=4.0, height=3.0)
>>> updated_model = model.add(new_room)

run(file_name=None, timeout=None, verbose=False)[source]#

Execute the CFAST simulation and return results.

Writes the input file, runs CFAST, and reads the output CSV files into pandas.DataFrame objects.

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, logs CFAST stdout and stderr at DEBUG level.

Returns:

Dictionary mapping output type to simulation results.

Key	Description
`'compartments'`	Conditions in each compartment over time.
`'devices'`	Measurements from devices/targets over time.
`'masses'`	Mass flow data for each compartment.
`'vents'`	Flow data for each vent over time.
`'walls'`	Heat transfer data for each wall over time.
`'zone'`	Zone-specific data.
`'diagnostics'`	Diagnostic information (only present if the input file contains `&DIAG`).

Returns None if the simulation fails.

Return type:

dict[str, pandas.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

Warns:

RuntimeWarning – If CFAST execution exceeds the timeout, or if an expected output CSV file is missing, empty, or cannot be read.

Examples

Run a model with a custom filename :

>>> results = model.run(file_name="custom_file_name.in")  

Run a model and access compartment results:

>>> results = model.run()  
>>> comp_data = results['compartments'] 
>>> temp_data['ULT_1'].max() 
np.float64(345.3)

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]#

Return a clear summary of the CFAST model configuration as a string.

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

Returns:: Formatted summary of the model configuration.
Return type:: str

Examples

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

Material Properties (2):: Material(material=’GYPSUM’, conductivity=0.17, density=800…)
Compartment (2):: Compartment(id=’ROOM1’, width=4.0, depth=3.0, height=2.5…)

update_ceiling_floor_vent_params(vent=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)
**kwargs (Any) – Ceiling/floor vent attributes to update. See CeilingFloorVent 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, **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)
**kwargs (Any) – Compartment attributes to update. See Compartment 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="ROOM1",
...     width=6.0
... )

update_device_params(device=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)
**kwargs (Any) – Device attributes to update. See Device 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, **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)
**kwargs (Any) – Fire object attributes to update. See Fire class documentation for available parameters. data_table accepts list, dict, numpy ndarray, or pandas DataFrame — coercion is handled by Fire.

Returns:

New model instance with updated fire parameters

Return type:

CFASTModel

Examples

Update model with fire id (string):

>>> new_model = model.update_fire_params(
...     fire="FIRE1",
...     heat_of_combustion=20000,
...     radiative_fraction=0.1
... )

Update model with fire index (integer):

>>> new_model = model.update_fire_params(
...     fire=0,
...     heat_of_combustion=20000,
...     radiative_fraction=0.1
... )

update_material_params(material=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)
**kwargs (Any) – Material properties attributes to update. See Material class documentation for available parameters.

Returns:

New model instance with updated material parameters

Return type:

CFASTModel

Examples

>>> new_model = model.update_material_params(
...     material="GYPSUM",
...     conductivity=0.20,
...     density=900
... )

update_mechanical_vent_params(vent=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)
**kwargs (Any) – Mechanical vent attributes to update. See MechanicalVent 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=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=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)
**kwargs (Any) – Surface connection attributes to update. See SurfaceConnection 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, **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)
**kwargs (Any) – Wall vent attributes to update. See WallVent 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())  
>>> content = model.view_cfast_input_file(pretty_print=False)  
>>> print(content)  