pycfast.Devices#

class pycfast.Devices(id, comp_id, location, type, material_id, surface_orientation=None, normal=None, thickness=None, temperature_depth=0.5, depth_units='M', setpoint=None, rti=None, obscuration=23.93, spray_density=None, adiabatic=False, convection_coefficients=None)[source]#

Represents measurement and fire protection devices in a CFAST simulation.

This class encompasses both targets and detection/suppression devices. Targets are any objects in the simulation that can heat up via radiative and convective heat transfer. The heat conduction into the target is performed via a one-dimensional calculation in either cartesian or cylindrical coordinates.

Sprinklers and detectors are both considered detection devices by the CFAST model and are handled using the same inputs. Detection is based upon heat transfer to the detector. Fire suppression by a user-specified water spray begins once the associated detection device is activated.

For targets, if the target is only needed to report the local gas temperature, which may include the plume or ceiling jet, then you may specify arbitrary properties and normal vector. The output spreadsheet file includes the local gas temperature in addition to the target temperature.

Care should be taken when specifying detectors to activate based on smoke obscuration since the only calculation included in CFAST is a simple two-zone calculation of soot concentration that does not include the impact of an initial ceiling layer as is done for temperature-based calculations.

Parameters:

  • id (str) – The selected name must be unique (i.e., not the same as another target or detector in the same simulation).

  • comp_id (str) – The compartment in which the target or detector is located.

  • location (list[float]) – Position of the device as distances from the compartment walls and floor. Format: [x, y, z] where x is distance from left wall, y is distance from front wall, z is height above floor. Default units: m.

  • type (str) – Type of device. Options: “PLATE”, “CYLINDER” (targets), “HEAT_DETECTOR”, “SMOKE_DETECTOR”, “SPRINKLER” (detectors).

  • material_id (str) – What the target is made of. Any existing material in the list of thermal properties may be used here. There can be only one material per target. Required for target types only.

  • surface_orientation (str, optional) – Predefined surface orientation for targets. Alternative to specifying normal vector directly.

  • normal (list[float], optional) – Specifies a vector of unit length perpendicular to the exposed surface of the target. Format: [nx, ny, nz]. For example, the vector (-1,0,0) indicates that the target is facing the left wall. The vector (0,0,1) is facing the ceiling. Required for targets when surface_orientation is not specified.

  • thickness (float, optional) – Thickness of the target material. If not specified, will use value from the material definition.

  • temperature_depth (float) – For each target, CFAST calculates the internal temperature at a number of node points within the target. By default, the reported internal temperature is the temperature at the center of the target. This input allows the user to override this default position. The input represents the position as a fraction of the thickness from the front surface to the back surface of the material. Default units: none, default value: 0.5.

  • depth_units (str) – Units for depth measurement. Default: “M” for meters.

  • setpoint (float, optional) – For heat detectors and sprinklers: the temperature at or above which the detector link activates. Default units: °C, default value: dependent on type. For smoke detectors: the obscuration at or above which the detector activates. Default units: %/m, default value: 23.93 %/m (8 %/ft).

  • rti (float, optional) – The Response Time Index (RTI) for the sprinkler or detection device. Default units: (m·s)^(1/2).

  • obscuration (float) – The obscuration at or above which the smoke detector activates. Default units: %/m, default value: 23.93 %/m (8 %/ft).

  • spray_density (float, optional) – The amount of water dispersed by a sprinkler. The units for spray density are length/time, derived by dividing the volumetric flow rate by the spray area. The suppression calculation is based upon an experimental correlation by Evans. Default units: m/s.

  • adiabatic (bool) – Usually should never be used, only when DIAG. Default: False.

  • convection_coefficients (list[float], optional) – Usually should never be used, only when DIAG.

Raises:

ValueError – If location is not a list of 3 numbers. If target type is specified but required target parameters are missing. If detector type is specified but required detector parameters are missing. If both normal and surface_orientation are specified or both are None. If normal vector is not a list of 3 numbers. If unknown device type is specified.

Examples

Create a plate target:

>>> target = Devices(
...     id="WALL_TARGET",
...     comp_id="ROOM1",
...     location=[2.0, 3.0, 1.5],     # 2m from left, 3m from front, 1.5m high
...     type="PLATE",
...     material_id="GYPSUM",
...     normal=[-1, 0, 0],            # Facing left wall
...     temperature_depth=0.5         # Center of target
... )

Create a heat detector:

>>> detector = Devices(
...     id="HEAT_DET_1",
...     comp_id="KITCHEN",
...     location=[2.5, 2.5, 2.4],     # Ceiling mounted
...     type="HEAT_DETECTOR",
...     material_id="STEEL",          # Detector material
...     setpoint=68,                  # Activate at 68°C
...     rti=50,                       # RTI of 50 (m·s)^(1/2)
...     temperature_depth=0.5
... )

Create a sprinkler:

>>> sprinkler = Devices(
...     id="SPRINKLER_1",
...     comp_id="OFFICE",
...     location=[3.0, 3.0, 2.4],     # Ceiling mounted
...     type="SPRINKLER",
...     material_id="STEEL",
...     setpoint=74,                  # Activate at 74°C
...     rti=100,                      # RTI of 100 (m·s)^(1/2)
...     spray_density=0.002,          # 2 mm/s spray density
...     temperature_depth=0.5
... )

Create a smoke detector:

>>> smoke_det = Devices(
...     id="SMOKE_DET_1",
...     comp_id="CORRIDOR",
...     location=[5.0, 1.0, 2.4],     # Ceiling mounted
...     type="SMOKE_DETECTOR",
...     material_id="PLASTIC",
...     obscuration=23.93,            # Default obscuration threshold
...     temperature_depth=0.5
... )

Notes

For sprinkler suppression, several cautions should be observed:

  1. The first sprinkler activated controls the effect on the fire heat release rate. Subsequent sprinklers have no additional effect.

  2. The fire suppression algorithm assumes the effect is solely to reduce the heat release rate. Effects on gas temperatures or mixing are ignored.

  3. The sprinkler always reduces the heat release rate. The ability of a fire to overwhelm an under-designed sprinkler is not modeled.

  4. Since sprinkler dynamics and spray effects on gas temperatures are not modeled, calculated activation times of secondary devices after the first sprinkler should not be relied upon.

Often, smoke alarm activation is simulated with a temperature-based criterion (as a heat alarm), typically 5°C to 10°C above ambient, rather than using obscuration due to limitations in the two-zone soot calculation.

classmethod create_heat_detector(id, comp_id, location, setpoint, rti)[source]#

Create a heat detector.

Parameters:

  • id (str) – Unique identifier

  • comp_id (str) – Compartment ID

  • location (list[float | int]) – [x, y, z] position

  • setpoint (float) – Activation temperature

  • rti (float) – Response Time Index

Returns:

Device instance configured as a heat detector

Return type:

Devices

classmethod create_smoke_detector(id, comp_id, location, setpoint, obscuration=23.93)[source]#

Create a smoke detector.

Parameters:

  • id (str) – Unique identifier

  • comp_id (str) – Compartment ID

  • location (list[float | int]) – [x, y, z] position

  • setpoint (float) – Activation threshold (e.g., obscuration)

  • obscuration (float) – Obscuration value, default: 23.93 %/m

Returns:

Device instance configured as a smoke detector

Return type:

Devices

classmethod create_sprinkler(id, comp_id, location, setpoint, rti, spray_density)[source]#

Create a sprinkler.

Parameters:

  • id (str) – Unique identifier

  • comp_id (str) – Compartment ID

  • location (list[float | int]) – [x, y, z] position

  • setpoint (float) – Activation temperature

  • rti (float) – Response Time Index

  • spray_density (float) – Spray density in m/s

Returns:

Device instance configured as a sprinkler

Return type:

Devices

classmethod create_target(id, comp_id, location, type, material_id, temperature_depth=0.5, thickness=None, surface_orientation=None, normal=None, depth_units='M', adiabatic=False, convection_coefficients=None)[source]#

Create a target device.

Parameters:

  • id (str) – Unique identifier

  • comp_id (str) – Compartment ID

  • location (list[float | int]) – [x, y, z] position

  • target_type (str) – “PLATE” or “CYLINDER”

  • material_id (str) – Material identifier

  • surface_orientation (str | None) – Surface orientation string (mutually exclusive with normal)

  • normal (list[float | int] | None) – [nx, ny, nz] normal vector (mutually exclusive with surface_orientation)

  • thickness (float | None) – Target thickness in meters

  • temperature_depth (float) – Temperature measurement depth in meters

  • depth_units (str) – Depth units, defaults to “M”

Returns:

Device instance configured as a target

Return type:

Devices

Raises:

ValueError – If both surface_orientation and normal are provided, or if neither is provided

to_input_string()[source]#

Generate CFAST input file string for this device.

Return type:

str

Returns:

Formatted string ready for inclusion in CFAST input file.

Examples

>>> target = Devices.create_target(
...     id="WALL_TARGET",
...     comp_id="ROOM1",
...     location=[2.0, 3.0, 1.5],
...     type="PLATE",
...     material_id="GYPSUM",
...     normal=[-1, 0, 0],
...     temperature_depth=0.5
... )
>>> print(target.to_input_string())
&DEVC ID = 'WALL_TARGET' COMP_ID = 'ROOM1' LOCATION = 2.0, 3.0, 1.5 ...