pycfast.MechanicalVents#

class pycfast.MechanicalVents(id, comps_ids, area=None, heights=None, orientations=None, flow=0, cutoffs=None, offsets=None, filter_time=0, filter_efficiency=0, open_close_criterion=None, time=None, fraction=None, set_point=None, device_id=None, pre_fraction=1, post_fraction=1)[source]#

Represents a mechanical ventilation system in a CFAST simulation.

Fan-duct systems are commonly used in buildings for heating, ventilation, air conditioning, pressurization, and exhaust. CFAST models mechanical ventilation in terms of user-specified volume flows at various points in the compartment. The model does not include duct work or fan curves, and thus mechanical ventilation connections are simply described by the connections to the two compartments and a fan whose throughput is a constant volumetric flow up to a user-specified pressure drop across the fan, dropping to zero at high backwards pressure on the fan.

CFAST does not include provisions for reverse flow through a fan, or a fan curve. Rather, you may specify a pressure above which the flow linearly decreases to zero. A hyperbolic tangent function is used to ensure a smooth transition from full flow at the “Begin Drop Off Pressure” to zero flow at the “Zero Flow Pressure”.

For mechanical vents, there are two species that can be filtered out of the gas flow: soot and the user-defined trace species. Filters are applied only to fan openings. By default, there is no filtering applied; that is, all of the soot and trace species mass in the vent flow is passed through the vent.

Vents in CFAST can be opened or closed at user-specified times or by a user-specified target’s surface temperature or incident heat flux. CFAST assumes a linear transition between time points for time-based opening changes. For condition-based opening changes, the transition from the pre-activation fraction to the post-activation fraction is assumed to occur over one second beginning when the specified set point value is reached.

Parameters:

  • id (str) – The selected name must be unique (i.e., not the same as another mechanical ventilation system in the same simulation).

  • comps_ids (list[str]) – List containing the compartment from which the fan flow originates (first) and the compartment to which the fan flow terminates (second).

  • area (list[float]) – Cross-sectional area of the opening for each compartment connection. Default units: m², default value: [0, 0] m².

  • heights (list[float]) – Height of the midpoint of the duct opening above the floor for each compartment connection. Default units: m, default value: [0, 0] m.

  • orientations (list[str]) – Flow orientation for each connection. A horizontal diffuser implies vertical flow through the ceiling or floor of the compartment. A vertical diffuser implies horizontal flow through a wall of the compartment. Default value: [“VERTICAL”, “VERTICAL”].

  • flow (float) – Constant flow rate of the fan. Default units: m³/s, default value: 0 m³/s.

  • cutoffs (list[float]) – Pressure control values: [Begin Drop Off Pressure, Zero Flow Pressure]. Above Begin Drop Off Pressure, the flow begins a drop-off to zero. The pressure above which the flow is zero is the Zero Flow Pressure. Default units: Pa, default values: [200, 300] Pa.

  • offsets (list[float]) – For visualization only, the horizontal distances between the center of the vent and the origin of the X and Y axes in the first compartment. Format: [x_offset, y_offset]. Default units: m, default value: [0, 0] m.

  • filter_time (float) – Time during the simulation at which the mechanical vent filtering begins. Default units: s, default value: 0 s.

  • filter_efficiency (float) – Flow through mechanical vents may include filtering that removes a user-specified portion of soot and trace species mass from the flow through the vent. Specified as a fraction (0-1). Default value: 0 (no filtering).

  • open_close_criterion (str, optional) – The opening/closing 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”.

  • time (list[float], optional) – Time during the simulation at which to begin or end a change in the open fraction. For time-based opening changes, this is a series of time points associated with opening fractions. Default units: s, default value: 0 s.

  • fraction (list[float], optional) – Fraction between 0 and 1 of the vent width to indicate the vent is closed, partially-open, or fully-open at the associated time point. Default value: 1 (fully open).

  • set_point (float, optional) – The critical value at which the vent opening change 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 trigger a vent opening change. Target placement is specified by the user as part of the associated target definition.

  • pre_fraction (float, optional) – Fraction between 0 and 1 of the vent width to indicate the vent is partially open at the start of the simulation. Default value: 1 (fully open).

  • post_fraction (float, optional) – Opening fraction at the end of the simulation. The transition from the pre-activation fraction to the post-activation fraction is assumed to occur over one second beginning when the specified set point value is reached. Default value: 1 (fully open).

Examples

Create a supply air system:

>>> supply_fan = MechanicalVents(
...     id="SUPPLY_1",
...     comps_ids=["OUTSIDE", "ROOM1"],
...     area=[0.1, 0.1],              # 0.1 m² grilles
...     heights=[3.0, 2.8],           # Near ceiling
...     orientations=["HORIZONTAL", "HORIZONTAL"],
...     flow=0.5,                     # 0.5 m³/s supply
...     cutoffs=[200, 300],           # Standard pressure cutoffs
...     offsets=[0, 1.0],             # Positions along walls
...     filter_time=0,                # Start filtering immediately
...     filter_efficiency=0.0         # No filtration
... )

Create an exhaust fan with time-based control:

>>> exhaust_fan = MechanicalVents(
...     id="EXHAUST_1",
...     comps_ids=["KITCHEN", "OUTSIDE"],
...     area=[0.05, 0.05],            # Smaller exhaust grilles
...     heights=[2.5, 0],             # Kitchen ceiling to outside
...     flow=-0.3,                    # Negative for exhaust
...     time=[0, 300, 600],           # Control times
...     fraction=[0, 1, 0]            # Off, on, off sequence
... )
to_input_string()[source]#

Generate CFAST input file string for this mechanical vent.

Returns:

Formatted string ready for inclusion in CFAST input file.

Return type:

str

Examples

>>> vent = MechanicalVents("FAN1", ["OUT", "RM1"], [0.1, 0.1],
...                       [3, 2.8], ["HORIZ", "HORIZ"], 0.5,
...                       [100, 100], [0, 1], 0, 0)
>>> print(vent.to_input_string())
&VENT TYPE = 'MECHANICAL' ID = 'FAN1' COMP_IDS = 'OUT', 'RM1' ...