Assembly

U-value and R-value calculations for building envelope assemblies.

Assembly module — layered building envelope elements.

An Assembly represents a wall, roof, floor, or ceiling made of stacked material layers. It calculates total thermal resistance (R-value) and thermal transmittance (U-value) using the series resistance method from ISO 6946:2017.

Example

>>> from hvacpy import Q_, db, Assembly
>>> wall = Assembly('My Wall')
>>> wall.add_layer('brick_common', Q_(110, 'mm'))
>>> wall.add_layer('mineral_wool_batt', Q_(100, 'mm'))
>>> wall.add_layer('plasterboard_std', Q_(12.5, 'mm'))
>>> print(wall.u_value)
0.298... W / K / m²

class hvacpy.assembly.Assembly(name: str, orientation: str = 'wall')

Bases: object

A layered building envelope element.

Layers are ordered outside-to-inside. Surface resistances are added automatically based on orientation.

Parameters:

• name – Human-readable description e.g. ‘Brick Cavity Wall’.

• orientation – ‘wall’ | ‘roof’ | ‘floor’. Defaults to ‘wall’.

Raises:

ValueError – If orientation is not ‘wall’, ‘roof’, or ‘floor’.

add_layer(material: str | Material, thickness: Quantity) → Assembly

Add a material layer to this assembly.

Layers are ordered as added, outside to inside.

Parameters:

• material – Material key string (e.g. ‘brick_common’) or a Material instance. String keys are case-insensitive.

• thickness – Layer thickness as a pint Quantity with length units. E.g. Q_(110, ‘mm’) or Q_(0.11, ‘m’).

Returns:

self, enabling method chaining.

Raises:

• TypeError – If thickness is not a pint Quantity.

• UnitError – If thickness does not have length dimensions.

• ValueError – If thickness is not positive.

• MaterialNotFoundError – If material is a string key not in DB.

breakdown() → str

Human-readable breakdown of the assembly.

Returns:

Formatted string showing all layers, their resistances, surface resistances, and total R/U values.

property layers: list[dict]

Layer information as list of dicts.

Each dict contains:

• name (str): Material name.

• key (str | None): DB key if looked up, None if passed as Material instance.

• thickness_m (float): Thickness in metres.

• conductivity (float): W/(m·K).

• r_layer (float): Layer resistance in m²K/W.

• r_fraction (float): Layer R as fraction of total layer R (excludes surface resistances), 0.0–1.0.

Returns:

List of layer dicts ordered outside-to-inside.

property r_value: Quantity

Total thermal resistance including surface resistances.

Returns:

R-value as a pint Quantity in m²·K/W.

property u_value: Quantity

Thermal transmittance (reciprocal of R-value).

Returns:

U-value as a pint Quantity in W/(m²·K).

class hvacpy.materials.MaterialsDB

Bases: object

Registry of building materials.

The database contains built-in materials from ASHRAE and ISO standards, and supports adding custom materials at runtime.

This class should not be instantiated directly by users. Use the module-level _DB singleton instead, exposed as db in the top-level hvacpy package.

add_custom(key: str, material: Material) → None

Add a custom material to the in-memory database.

Custom materials persist only for the lifetime of the process.

Parameters:

• key – Unique identifier for the material. Must be a non-empty string.

• material – A Material instance to register.

Raises:

• TypeError – If material is not a Material instance.

• ValueError – If key is empty or already exists as a built-in material.

get(key: str) → Material

Return the Material for the given key.

Parameters:

key – Material identifier, case-insensitive. E.g. ‘brick_common’ or ‘BRICK_COMMON’.

Returns:

The matching Material instance.

Raises:

MaterialNotFoundError – If no material matches the key. The error message includes the key and a hint to use list_keys().

list_by_category(category: str) → list[Material]

Return materials filtered by category, sorted by name.

Parameters:

category – Category to filter by. Must be one of the allowed categories (masonry, insulation, wood, etc.).

Returns:

List of Material instances sorted by name.

Raises:

ValueError – If category is not in the allowed list.

list_keys() → list[str]

Return a sorted list of all available material keys.

Returns:

Sorted list of material key strings.