pycfast.SurfaceConnections#

class pycfast.SurfaceConnections(conn_type, comp_id, comp_ids, fraction=None)[source]#

Represents surface connections for heat transfer between compartments in CFAST.

The Surface Connections functionality allows the user to define heat transfer between compartments in a simulation. Energy can be transferred from compartment to compartment through solid boundaries (walls, ceilings and floors) by means of conduction. The heat transfer between connected compartments is modeled by setting the boundary condition for the outside surface of a compartment to the temperature of the outside surface of the connected compartment. Temperatures are determined by the solver so that the heat flux striking the wall surface (both interior and exterior) is consistent with the temperature gradient at that surface.

There are two types of surface connections:

  • Horizontal Heat Transfer (Wall Connections): Heat transfer through vertical surfaces (walls) between adjacent compartments. The fraction parameter specifies what portion of the vertical surface area connects the two compartments.

  • Vertical Heat Transfer (Floor/Ceiling Connections): Heat transfer through horizontal surfaces between compartments stacked vertically. The connection is through the floor of the top compartment and the ceiling of the bottom compartment.

Important considerations:

  • For horizontal heat transfer, you must include a connection for each compartment (bidirectional: compartment 1→2 AND compartment 2→1)

  • For consistency, the fraction for each compartment needs to specify equal areas in the two compartments

  • Fractions for connections should add to unity

  • An error is generated if fractions for a compartment add to >1

  • If fractions add to <1, remaining surface area connects to outdoors

Parameters:

  • conn_type (str) – Type of surface connection. Options: “WALL” for horizontal heat transfer through vertical surfaces, “FLOOR” for vertical heat transfer through horizontal surfaces.

  • comp_id (str) – First compartment ID. For wall connections, this is the first of the compartments whose walls are connected for horizontal heat transfer. For floor connections, this is the top compartment (connection through its floor).

  • comp_ids (str) – Second compartment ID. For wall connections, this is the second of the compartments whose walls are connected for horizontal heat transfer. For floor connections, this is the bottom compartment (connection through its ceiling).

  • fraction (float | None) – Fraction of vertical surface areas connected (0-1). Only used for wall connections. Specifies the fraction of the vertical surface area of the first compartment that connects the first and second compartment pair. Must be None for floor/ceiling connections.

Raises:

ValueError – If conn_type is not “WALL” or “FLOOR”, if fraction is specified for floor connections, or if fraction is outside valid range for wall connections.

Notes

For wall connections between compartments of different sizes, the fraction values must be calculated to ensure equal contact areas: - Connection 1→2: fraction = contact_area / total_wall_area_comp1 - Connection 2→1: fraction = contact_area / total_wall_area_comp2

For floor/ceiling connections, the entire horizontal interface is assumed to participate in heat transfer, so no fraction is needed.

Examples

Create a wall connection between two rooms:

>>> # For 1mx1mx1m compartments sharing 1m² wall out of 4m² total wall area
>>> wall_conn_1to2 = SurfaceConnections.wall_connection(
...     comp_id="ROOM1",
...     comp_ids="ROOM2",
...     fraction=0.25  # 1m²/4m² = 0.25
... )
>>> wall_conn_2to1 = SurfaceConnections.wall_connection(
...     comp_id="ROOM2",
...     comp_ids="ROOM1",
...     fraction=0.25  # Bidirectional connection required
... )

Create a floor/ceiling connection between stacked compartments:

>>> floor_conn = SurfaceConnections.ceiling_floor_connection(
...     comp_id="UPPER_ROOM",    # Top compartment
...     comp_ids="LOWER_ROOM"    # Bottom compartment
... )

Different sized compartments example:

>>> # Compartment 1: 1x1x1m, Compartment 2: 2x2x2m
>>> # Connection 1→2: 1m²/4m² = 0.25
>>> # Connection 2→1: 1m²/16m² = 0.125 (same 1m² area, different base)
>>> conn_1to2 = SurfaceConnections.wall_connection("COMP1", "COMP2", 0.25)
>>> conn_2to1 = SurfaceConnections.wall_connection("COMP2", "COMP1", 0.125)
classmethod ceiling_floor_connection(comp_id, comp_ids)[source]#

Create a surface connection for vertical heat transfer through floors/ceilings.

This class method creates a floor/ceiling connection between two compartments for vertical heat transfer through horizontal surfaces. The connection is established between the floor of the top compartment and the ceiling of the bottom compartment. Unlike wall connections, only one connection definition is needed (not bidirectional).

Parameters:

  • comp_id (str) – Top compartment identifier. Heat transfer occurs through the floor of this compartment.

  • comp_ids (str) – Bottom compartment identifier. Heat transfer occurs through the ceiling of this compartment.

Returns:

Configured surface connection instance for floor/ceiling heat transfer.

Return type:

SurfaceConnections

to_input_string()[source]#

Convert the surface connection to a formatted string for CFAST input file.

Returns:

Formatted string ready for inclusion in CFAST input file.

Return type:

str

Examples

>>> wall_conn = SurfaceConnections.wall_connection("ROOM1", "ROOM2", 0.25)
>>> print(wall_conn.to_input_string())
&CONN TYPE = 'WALL' COMP_ID = 'ROOM1' COMP_IDS = 'ROOM2' F = 0.25 /

>>> floor_conn = SurfaceConnections.ceiling_floor_connection("UPPER", "LOWER")
>>> print(floor_conn.to_input_string())
&CONN TYPE = 'FLOOR' COMP_ID = 'UPPER' COMP_IDS = 'LOWER' /
classmethod wall_connection(comp_id, comp_ids, fraction)[source]#

Create a surface connection for horizontal heat transfer through walls.

Parameters:

  • comp_id (str) – First compartment identifier (source compartment for this connection).

  • comp_ids (str) – Second compartment identifier (target compartment for this connection).

  • fraction (float) – Fraction of the vertical surface area of the first compartment that connects to the second compartment. Valid range: 0.0 to 1.0. This represents the contact area divided by the total wall area of the source compartment.

Returns:

Configured surface connection instance for wall heat transfer.

Return type:

SurfaceConnections