carbonfly.utils module

General utilities shared across the carbonfly library.

This module contains small helper functions used by multiple writers and case-building utilities

carbonfly.utils.air_exchange_rate_maas1995(A_eff: float, u: float, H: float, delta_theta: float) → float[source]

Air exchange rate in m3/h using Maas’ formula: Qdot = 3600 * 1/2 * A_eff * sqrt(C1 * u^2 + C2 * H * delta_theta + C3)

Source:: Anton Maas. Experimental quantification of air exchange during window ventilation. PhD thesis, University of Kassel, Kassel, 1995. URL https://www.uni-kassel.de/fb6/bpy/de/forschung/abgeschlprojekte/pdfs/maas_diss.pdf

Parameters:

A_eff (float) – effective opening area in m^2
u (float) – outdoor wind speed (10 m) in m/s
H – (float) height of the window sash in m
delta_theta (float) – temperature difference between the inside and outside in K

Returns:

air exchange rate through the opening in m3/h

Return type:

Qdot (float)

carbonfly.utils.co2_generation_rate(age: float, met: float, gender: str | None = None)[source]

Get CO2 generation rate (L/s) based on mean body mass in each age group.

Parameters:

age (float) – Age in years.
met (float) – Metabolic rate (met). Must be one of [1.0, 1.2, 1.4, 1.6, 2.0, 3.0, 4.0].
gender (str | None) – "male", "female", or None (average of both, default).

Returns:

A dict with:

mass: Mean body mass (kg)
BMR: Basal metabolic rate (MJ/day)
CO2: CO2 generation rate (L/s)

Return type:

dict[str, float]

Source:: Persily and De Jonge, Carbon dioxide generation rates for building occupants, Indoor Air 27 (5) (2017) 868–879. doi:10.1111/ina.12383

carbonfly.utils.foam_header(object_name: str, of_class: str = 'dictionary', location: str | None = None, *, of_version: str = '10', project_name: str = 'carbonfly', author: str = 'Qirui Huang', project_url: str = 'https://github.com/RWTH-E3D/carbonfly') → str[source]

Return an OpenFOAM-style header with Carbonfly attribution.

Parameters:

object_name (str) – OpenFOAM object name (e.g., snappyHexMeshDict, U).
of_class (str) – OpenFOAM class (e.g., dictionary, volScalarField).
location (str | None) – OpenFOAM location entry (e.g., "system"). If None, omitted.
of_version (str) – OpenFOAM version label shown in the banner.
project_name (str) – Project name for attribution.
author (str) – Attribution author name.
project_url (str) – Project URL for attribution.

Examples

lines = [foam_header(“snappyHexMeshDict”)]

carbonfly.utils.unit_scale_to_m(unit: str) → float[source]

Convert a unit label to a meters scale factor.

Parameters:: unit (str) – Unit label. Supported: mm, cm, m.
Returns:: Scale factor to meters (mm->1e-3, cm->1e-2, m->1).
Return type:: float

carbonfly.utils.wind_pressure_en1991(vb0: float, z: float, h: float, d: float, window_size: float, zone: str, terrain: int = 4, c_dir: float = 1.0, c_season: float = 1.0, c0: float = 1.0, rho: float = 1.25, k_i: float = 1.0) → dict[source]

Computes peak and surface wind pressure for vertical walls of rectangular plan buildings (h/d <=5 and height <= 200m), based on DIN EN 1991-1-4:2010-12.

Parameters:

vb0 – fundamental value of the basic wind velocity v_b,0 [m/s] (from National Annex map, 10 m, terrain II, 50 yr)
z – height above ground level of the measured/evaluated point [m]
h – height of the building [m]
d – length of the building [m]
window_size – window size in [m^2]
zone – External pressure zones, A/B/C on side/roof edges along the flow, D windward face, and E leeward face. Schematic (Fig. 7.5) see Notes.
terrain –
terrain type, 0/1/2/3/4, default: 4, corresponding to Type 0/I/II/III/IV:

0: Sea, coastal area exposed to the open sea.

1: Lakes or area with negligible vegetation and without obstacles.

2: Area with low vegetation such as grass and isolated obstacles (trees, buildings) with separations of
at least 20 obstacle heights.

3: Area with regular cover of vegetation or buildings or with isolated obstacles with separations of
maximum 20 obstacle heights (such as villages, suburban terrain, permanent forest).

4: Area in which at least 15 % of the surface is covered with buildings and their average height
exceeds 15 m.
c_dir – directional factor, for various wind directions may be found in the National Annex. The recommended value is 1.0.
c_season – season factor, may be given in the National Annex. The recommended value is 1.0.
c0 – orography factor, taken as 1.0 unless otherwise specified. Note: Information on c0 may be given in the National Annex. If the orography is accounted for in the basic wind velocity, the recommended value is 1.0.
rho – air density in kg/m3. The default value is 1.25 kg/m3.
k_i – turbulence factor. The value of k_i may be given in the National Annex. The recommended value for k_i is 1.0.

Notes

For other building types, please see DIN EN 1991-1-4:2010-12.

Zone definition schematic (EN 1991-1-4, e.g., Fig. 7.5):

Top view:
               <- - - d (length)  - ->
               -----------------------     ^
               |                     |     |
    wind --> D |                     | E   b (width)
               |                     |     |
               -----------------------     -
    D = windward face (positive pressure / stagnation)
    E = leeward face (negative pressure / wake suction)

Side view:
               <- - - d (length)  - ->
               -----------------------     ^
               |   |         |       |     |
    wind -->   | A |    B    |   C   |     | h (height)
               |___|_________|_______|     _
               <- - - e - - ->
                   <- 4/5 e ->
               Where: e = b or 2h, whichever is smaller
    A: leading corner band (strongest suction)
    B: intermediate edge band
    C: outer side/roof band

Returns:

Results dictionary with keys:

we: external surface wind pressure (Pa)
cpe: external pressure coefficient (-)
qp: peak velocity pressure (Pa)
vm: mean wind speed (m/s)
Iv: turbulence intensity (-)
cr: roughness factor (-)
vb: basic wind velocity (m/s)

Return type:

dict[str, float]