Heat Loads

Cooling loads (ASHRAE CLTD/CLF, HOF 2021 Ch.28) and heating loads (ASHRAE steady-state, HOF 2021 Ch.18).

hvacpy.loads — Heat Load Calculations (v0.3).

ASHRAE CLTD/CLF cooling load method (1997 HOF Ch.28) and ASHRAE steady-state heating load method (2021 HOF Ch.18).

Public API:: CoolingLoad — peak cooling load using CLTD/CLF method HeatingLoad — steady-state heating load Room — single thermally-zoned space Zone — collection of rooms served by one HVAC system WallComponent, WindowComponent, InternalGain — envelope/gain data Orientation — cardinal direction enum

Bases: object

Calculates peak cooling load for a room or zone using CLTD/CLF method.

Parameters:

space – Room or Zone to analyse.
city – City name string for design conditions lookup. OR provide t_outdoor_db and t_outdoor_wb directly.
t_outdoor_db – Outdoor design dry bulb temp as Quantity. Overrides city.
t_outdoor_wb – Outdoor design wet bulb temp as Quantity. Overrides city.
design_hour – Hour (1–24) at which to calculate load. Default: None (calculates all 24 hours and returns peak).
diurnal_range – Daily temp swing in K. Default Q_(10, ‘delta_degC’).

breakdown() → str[source]

Formatted table of all components, their W value, and % of peak_total.

Same style as Assembly.breakdown().

property equipment_latent: Quantity: Equipment latent at peak hour.

property equipment_sensible: Quantity: Equipment sensible at peak hour.

hourly_profile() → dict[int, float][source]

Returns dict of {hour: total_load_W} for all 24 hours.

Useful for understanding load shape over the day.

property infiltration_latent: Quantity: Infiltration latent at peak hour.

property infiltration_sensible: Quantity: Infiltration sensible at peak hour.

property lighting_gain: Quantity: Lighting gain (all sensible) at peak hour.

property peak_hour: int: Hour (1–24) at which peak_total occurs.

property peak_latent: Quantity: Latent component at peak hour = infiltration_latent + people_latent + equipment_latent.

property peak_sensible: Quantity: Sensible component at peak hour.

property peak_total: Quantity: Sum of all sensible + latent at the peak hour.

property people_latent: Quantity: People latent at peak hour.

property people_sensible: Quantity: People sensible at peak hour.

property sensible_heat_ratio: float: SHR = peak_sensible / peak_total.

property solar_gain: Quantity: Total solar heat gain at peak hour.

to_dict() → dict[source]

All properties as plain floats in SI.

Includes ‘peak_hour’, all component loads in W, ‘shr’.

property wall_conduction: Quantity: Total wall+roof conduction at peak hour.

property window_conduction: Quantity: Total window conduction at peak hour.

class hvacpy.loads.HeatingLoad(space: Room | Zone, city: str | None = None, *, t_winter_db: Quantity | None = None, wind_speed: Quantity | None = None)[source]

Bases: object

Steady-state heating load using ASHRAE simple heat loss method.

Conservative: no credit for solar gain or internal gains. This is correct practice for heating equipment sizing.

Parameters:

space – Room or Zone.
city – City name for design conditions, OR provide t_winter_db.
t_winter_db – Outdoor winter design temperature as Quantity.
wind_speed – Design wind speed in m/s. Default Q_(6.7, ‘m/s’). Affects infiltration rate via ACH adjustment.

breakdown() → str[source]

Formatted table of all components, their W value, and % of total.

Same style as CoolingLoad.breakdown().

property delta_t: Quantity: T_indoor - T_outdoor_winter.

property envelope_loss: Quantity: Sum of all opaque and glazed envelope losses.

property infiltration_loss: Quantity: Infiltration heat loss.

property total: Quantity: Total heating load = envelope + infiltration.

class hvacpy.loads.InternalGain(gain_type: str, count: int = 0, activity: str = 'office_work', watts_per_m2: float = 0.0, total_watts: float = 0.0, diversity: float = 1.0, clf: float = 1.0)[source]

Bases: object

A heat source inside the space.

For people: specify count and activity. For lighting: specify watts_per_m2 or total_watts. For equipment: specify watts_per_m2 or total_watts.

activity: str = 'office_work'

clf: float = 1.0

count: int = 0

diversity: float = 1.0

gain_type: str

total_watts: float = 0.0

watts_per_m2: float = 0.0

class hvacpy.loads.Orientation(*values)[source]

Bases: str, Enum

Cardinal / inter-cardinal directions for building surfaces.

E = 'E'

HORIZONTAL = 'H'

N = 'N'

NE = 'NE'

NW = 'NW'

S = 'S'

SE = 'SE'

SW = 'SW'

W = 'W'

class hvacpy.loads.Room(name: str, floor_area: Quantity, ceiling_height: Quantity, walls: list[WallComponent] = <factory>, windows: list[WindowComponent] = <factory>, internal_gains: list[InternalGain] = <factory>, ach_infiltration: float = 0.5, t_indoor: Quantity = <factory>)[source]

Bases: object

A single thermally-zoned space.

Parameters:

name – Human label.
floor_area – Floor area as Quantity (m² or ft²).
ceiling_height – Floor-to-ceiling height as Quantity (m or ft).
walls – List of WallComponent (opaque walls only).
windows – List of WindowComponent.
internal_gains – List of InternalGain.
ach_infiltration – Air changes per hour for infiltration. Default 0.5.
t_indoor – Indoor design temperature as Quantity. Default Q_(24,’degC’).

ach_infiltration: float = 0.5

ceiling_height: Quantity

floor_area: Quantity

property floor_area_m2: float: Floor area in m².

internal_gains: list[InternalGain]

name: str

t_indoor: Quantity

property volume_m3: float: Room volume in m³ = floor_area * ceiling_height.

walls: list[WallComponent]

windows: list[WindowComponent]

class hvacpy.loads.WallComponent(name: str, assembly: Assembly, area: Quantity, orientation: Orientation, wall_group: str = 'D', is_roof: bool = False)[source]

Bases: object

An opaque wall or roof surface contributing to cooling/heating load.

Parameters:

name – Human label e.g. ‘South facade’.
assembly – hvacpy Assembly — provides U-value.
area – Net wall area (excluding windows/doors) as Quantity (m² or ft²).
orientation – Orientation enum value.
wall_group – ASHRAE CLTD wall group ‘A’ through ‘G’. Default ‘D’. See _cltd_tables.py for group descriptions.
is_roof – True if this is a roof/ceiling surface. Default False.

area: Quantity

assembly: Assembly

is_roof: bool = False

name: str

orientation: Orientation

wall_group: str = 'D'

class hvacpy.loads.WindowComponent(name: str, area: Quantity, orientation: Orientation, u_factor: Quantity, shgc: float, has_interior_shading: bool = False, frame_fraction: float = 0.15)[source]

Bases: object

A glazed opening contributing solar and conductive cooling load.

Parameters:

name – Human label e.g. ‘South glazing’.
area – Gross glazed area as Quantity (m² or ft²).
orientation – Orientation enum.
u_factor – Overall window U-factor as Quantity W/(m²K). Typical double-glazed = 2.8, triple = 1.8.
shgc – Solar Heat Gain Coefficient 0.0–1.0. Clear single = 0.87, Low-e double = 0.25–0.40.
has_interior_shading – True if blinds/curtains present. Default False. Affects CLF table selection.
frame_fraction – Fraction of area that is frame (0.0–1.0). Default 0.15.

area: Quantity

frame_fraction: float = 0.15

has_interior_shading: bool = False

name: str

orientation: Orientation

shgc: float

u_factor: Quantity

class hvacpy.loads.Zone(name: str, rooms: list[Room] = <factory>)[source]

Bases: object

A collection of rooms served by a single HVAC system.

The zone peak load is NOT the sum of room peaks — it is the peak of the sum of simultaneous room loads. This distinction is critical for equipment sizing.

add_room(room: Room) → Zone[source]: Add a room to the zone. Returns self for chaining.

name: str

rooms: list[Room]

hvacpy.loads.get_design_conditions(city: str) → dict[source]

Get ASHRAE design conditions for a city.

Parameters:: city – City name (case-insensitive).
Returns:: ‘city’, ‘t_outdoor_db’, ‘t_outdoor_wb’, ‘t_winter_db’, ‘lat’.
Return type:: Dict with keys
Raises:: DesignConditionsNotFoundError – If city not found.

hvacpy.loads.list_design_cities() → list[str][source]: Return list of available city names in the design conditions database.