Welcome to thermal-comforts’s documentation!

The thermal-comfort package wraps a few common thermal-comfort functions from official sources such as ISO-norms or VDI-Guidelines in python. The underlying functions are implemented in fortran to achieve blazingly fast performance on large arrays. If possible, the original code was reused and slightly modified to create a standardized interface for all function.

Tests are implemented for all functions using offical data often provided alongside a paper or the implementation itself.

Installation

via https

pip install git+https://github.com/RUBclim/thermal-comfort

via ssh

pip install git+ssh://git@github.com/RUBclim/thermal-comfort

Quick start

The thermal-comfort package provides a limited set of commonly used functions. Which work for scalar values, but are mainly optimized for large array calculation of hundreds of thousands of values.

scalars

from thermal_comfort import utci_approx

utci_approx(ta=20.3, tmrt=50.9, v=2.7, rh=50.5)

arrays

1-dimensional arrays

import numpy as np
from thermal_comfort import utci_approx

utci_approx(
    ta=np.array([20.3, 28.5]),
    tmrt=np.array([50.9, 70.3]),
    v=np.array([2.7, 1.9]),
    rh=np.array([50.5, 70.3]),
)

n-dimensional arrays

The functions only accept 1-dimensional arrays, multi dimensional arrays must be reshaped before and after.

import numpy as np
from thermal_comfort import utci_approx

# 2D arrays e.g. a raster
ta = np.array([[20.3, 28.5], [20.3, 28.5]])
tmrt = np.array([[50.9, 70.3], [50.9, 70.3]])
v = np.array([[2.7, 1.9], [2.7, 1.9]])
rh = np.array([[50.5, 70.3], [50.5, 70.3]])
# retrieve the initial shape
orig_shape = ta.shape

# reshape the array to be 1-dimensional
ta = np.ravel(ta)
tmrt = np.ravel(tmrt)
v = np.ravel(v)
rh = np.ravel(rh)

# calculate the UTCI along the 1-dimensional array
utci = utci_approx( ta=ta, tmrt=tmrt, v=v, rh=rh)

# restore the original shape
utci = utci.reshape(orig_shape)

API documentation

Thermal comfort indices

thermal_comfort.utci_approx(ta, tmrt, v, rh) → ndarray[tuple[Any, ...], dtype[T]] | float[source]

Calculate the Universal Thermal Climate Index (UTCI).

The UTCI is implemented as described in VDI 3787 Part 2. The fortran code was vendored from here: https://utci.org/resources/UTCI%20Program%20Code.zip. A few changes were implemented to the original fortran-code.

  • Instead of taking the vapor pressure as an argument, it now takes the relative humidity. The vapor pressure is calculated from the relative humidity using the formula by Wexler (1976) which is described by Hardy (1998).

  • Arguments were renamed for a consistent interface within this package.

This functions is optimized on 1D-array operations, however also scalars may be provided.

Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(T, bound= floating | integer)]] | float

Returns:

Universal Thermal Climate Index (UTCI) in °C

References

  • Hardy, R.; ITS-90 Formulations for Vapor Pressure, Frostpoint Temperature, Dewpoint Temperature and Enhancement Factors in the Range -100 to 100 °C; Proceedings of Third International Symposium on Humidity and Moisture; edited by National Physical Laboratory (NPL), London, 1998, pp. 214-221 https://www.decatur.de/javascript/dew/resources/its90formulas.pdf

  • Wexler, A., Vapor Pressure Formulation for Water in Range 0 to 100°C. A Revision, Journal of Research of the National Bureau of Standards - A. Physics and Chemistry, September - December 1976, Vol. 80A, Nos. 5 and 6, 775-78

thermal_comfort.pet_static(ta, tmrt, v, rh, p) → ndarray[tuple[Any, ...], dtype[T]] | float[source]

Calculate the Physiological Equivalent Temperature (PET).

The PET is implemented as described in VDI 3787 Part 2. The fortran code was vendored from here:

This functions is optimized on 1D-array operations, however also scalars may be provided.

The procedure has some limitations compared to a full implementation of the PET. Many variables are set to static values, such as:

  • age = 35

  • mbody = 75

  • ht = 1.75

  • work = 80

  • eta = 0

  • icl = 0.9

  • fcl = 1.15

  • pos = 1

  • sex = 1

Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(T, bound= floating | integer)]] | float

Returns:

Physiological Equivalent Temperature (PET) in °C

References

  • Hardy, R.; ITS-90 Formulations for Vapor Pressure, Frostpoint Temperature, Dewpoint Temperature and Enhancement Factors in the Range -100 to 100 °C; Proceedings of Third International Symposium on Humidity and Moisture; edited by National Physical Laboratory (NPL), London, 1998, pp. 214-221 https://www.decatur.de/javascript/dew/resources/its90formulas.pdf

  • Wexler, A., Vapor Pressure Formulation for Water in Range 0 to 100°C. A Revision, Journal of Research of the National Bureau of Standards - A. Physics and Chemistry, September - December 1976, Vol. 80A, Nos. 5 and 6, 775-78

thermal_comfort.heat_index(ta, rh) → ndarray[tuple[Any, ...], dtype[T]] | float[source]

Calculate the heat index follwing Steadman R.G (1979) & Rothfusz L.P (1990).

This calculates the heat index in the range of \(\ge\) 80 °F (26.666 °C) and \(\ge\) 40 % relative humidity. If values outside of this range are provided, they are returned as NaN. This version natively works with °C as shown by Blazejczyk et al. 2011.

This functions is optimized on 1D-array operations, however also scalars may be provided.

Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(T, bound= floating | integer)]] | float

Returns:

Heat Index in °C

References

  • Steadman R.G. The assessment of sultriness. Part I: A temperature-humidity index based on human physiology and clothing. J. Appl. Meteorol. 1979;18:861-873. https://doi.org/10.1175/1520-0450(1979)018%3C0861:TAOSPI%3E2.0.CO;2

  • Rothfusz LP (1990) The heat index equation. NWS Southern Region Technical Attachment, SR/SSD 90-23, Fort Worth, Texas

  • Blazejczyk, K., Epstein, Y., Jendritzky, G. Staiger, H., Tinz, B. (2011) Comparison of UTCI to selected thermal indices. Int J Biometeorol 56, 515-535 (2012). https://doi.org/10.1007/s00484-011-0453-2

thermal_comfort.heat_index_extended(ta, rh) → ndarray[tuple[Any, ...], dtype[T]] | float[source]

Calculate the heat index following Steadman R.G (1979) & Rothfusz L.P (1990), but extends the range following The National Weather Service Weather Prediction Center.

This function works for the entire range of air temperatures and relative humidity. It uses °F under the hood, since corrections are provided in °F only.

This functions is optimized on 1D-array operations, however also scalars may be provided.

Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(T, bound= floating | integer)]] | float

Returns:

Heat Index in °C

References

Temperature

thermal_comfort.mean_radiant_temp(ta, tg, v, d=0.15, e=0.95) → ndarray[tuple[Any, ...], dtype[T]] | float[source]

Calculate the mean radiant temperature based on DIN EN ISO 7726.

Based on the air velocity, this function will decide whether to use the natural or forced convection.

Calculate hcg (the coefficient of heat transfer) for both natural and forced convection. Check which one is higher and use that (defined in Section B.2.3)

This function performs better for larger arrays. For smaller arrays, the numpy-based function outperforms this function.

Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(T, bound= floating | integer)]] | float

Returns:

returns the mean radiant temperature in °C

thermal_comfort.wet_bulb_temp(ta, rh) → ndarray[tuple[Any, ...], dtype[T]] | float[source]

Calculate the wet bulb temperature following the Stull (2011) equation

Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(T, bound= floating | integer)]] | float

Returns:

returns the wet bulb temperature in °C

References

thermal_comfort.dew_point(ta, rh) → ndarray[tuple[Any, ...], dtype[T]] | float[source]

Calculate the dew point following the equation in VDI 3786 sheet 04.

For temperatures values grate or equal to 0 °C, the dew point is calculated using the saturation vapor pressure over water. For temperatures below 0 °C, the dew point is calculated using the saturation vapor pressure over ice.

This functions is optimized on 1D-array operations, however also scalars may be provided.

Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(T, bound= floating | integer)]] | float

Returns:

returns the dew point temperature in °C

References

  • Sonntag, D. (1990). Important new values of the physical con- stants of 1986, vapour pressure formulations based on the ITC-90, and psychrometer formulae. Z. Meteorol., 40, 340–344.

  • Sonntag, D. (1994). Advancements in the field of hygrometry. Meteorologische Zeitschrift, 51–66. https://doi.org/10.1127/metz/3/1994/51

thermal_comfort.sat_vap_press_water(ta) → ndarray[tuple[Any, ...], dtype[T]] | float[source]

Calculate the saturation vapor pressure over water following the equation in VDI 3786 sheet 04.

This functions is optimized on 1D-array operations, however also scalars may be provided.

Parameters:

ta (ndarray[tuple[Any, ...], dtype[TypeVar(T, bound= floating | integer)]] | float | Iterable[float]) – air temperature in °C

Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(T, bound= floating | integer)]] | float

Returns:

returns the saturation vapor pressure in hPa

References

  • Sonntag, D. (1990). Important new values of the physical con- stants of 1986, vapour pressure formulations based on the ITC-90, and psychrometer formulae. Z. Meteorol., 40, 340–344.

thermal_comfort.sat_vap_press_ice(ta) → ndarray[tuple[Any, ...], dtype[T]] | float[source]

Calculate the saturation vapor pressure over ice following the equation in VDI 3786 sheet 04.

This functions is optimized on 1D-array operations, however also scalars may be provided.

Parameters:

ta (ndarray[tuple[Any, ...], dtype[TypeVar(T, bound= floating | integer)]] | float | Iterable[float]) – air temperature in °C

Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(T, bound= floating | integer)]] | float

Returns:

returns the saturation vapor pressure in hPa

References

  • Sonntag, D. (1990). Important new values of the physical con- stants of 1986, vapour pressure formulations based on the ITC-90, and psychrometer formulae. Z. Meteorol., 40, 340–344.

Humidity

thermal_comfort.absolute_humidity(ta, rh) → ndarray[tuple[Any, ...], dtype[T]] | float[source]

Calculate the absolute humidity above water following the equation in VDI 3786 sheet 04.

This functions is optimized on 1D-array operations, however also scalars may be provided.

Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(T, bound= floating | integer)]] | float

Returns:

returns the absolute humidity in g/m³

thermal_comfort.specific_humidity(ta, rh, p=1013.25) → ndarray[tuple[Any, ...], dtype[T]] | float[source]

Calculate the specific humidity above water following the equation in VDI 3786 sheet 04.

This functions is optimized on 1D-array operations, however also scalars may be provided.

Parameters:
Return type:

ndarray[tuple[Any, ...], dtype[TypeVar(T, bound= floating | integer)]] | float

Returns:

returns the absolute humidity in g/kg

Indices and tables