Models

Calculates the Heat Index (HI). It combines air temperature and relative humidity to determine an apparent temperature. The HI equation [12] is derived by multiple regression analysis in temperature and relative humidity from the first version of Steadman’s (1979) apparent temperature (AT) [13].

const hi = heat_index(25, 50); // returns {hi: 25.9}

Calculates the Predicted Heat Strain (PHS) index based in compliance with the ISO 7933:2004 Standard [8] or the ISO 7933:2023 Standard. The ISO 7933 provides a method for the analytical evaluation and interpretation of the thermal stress experienced by a subject in a hot environment. It describes a method for predicting the sweat rate and the internal core temperature that the human body will develop in response to the working conditions.

The PHS model can be used to predict the: heat by respiratory convection, heat flow by respiratory evaporation, steady state mean skin temperature, instantaneous value of skin temperature, heat accumulation associated with the metabolic rate, maximum evaporative heat flow at the skin surface, predicted sweat rate, predicted evaporative heat flow, and rectal temperature.

import { phs } from "jsthermalcomfort";
const results = phs(40, 40, 0.3, 33.85, 2.5, 0.5, "standing");
console.log(results); // {t_re: 37.5, d_lim_loss_50: 480, d_lim_loss_95: 480, d_lim_t_re: 480, sweat_loss_g: 5847.0, sweat_rate_watt: 252.1, ...}

Calculates the humidex (short for "humidity index"). It has been developed by the Canadian Meteorological service. It was introduced in 1965 and then it was revised by Masterson and Richardson (1979) [14]. It aims to describe how hot, humid weather is felt by the average person. The Humidex differs from the heat index in being related to the dew point rather than relative humidity [15].

const result = humidex(25, 50);
console.log(result); // -> { humidex: 28.2, discomfort: "Little or no discomfort" }

Calculates the Normal Effective Temperature (NET). Missenard (1933) devised a formula for calculating effective temperature. The index establishes a link between the same condition of the organism's thermoregulatory capability (warm and cold perception) and the surrounding environment's temperature and humidity. The index is calculated as a function of three meteorological factors: air temperature, relative humidity of air, and wind speed. This index allows to calculate the effective temperature felt by a person. Missenard original equation was then used to calculate the Normal Effective Temperature (NET), by considering normal atmospheric pressure and a normal human body temperature (37°C). The NET is still in use in Germany, where medical check-ups for subjects working in the heat are decided on by prevailing levels of ET, depending on metabolic rates. The NET is also constantly monitored by the Hong Kong Observatory [16]. In central Europe the following thresholds are in use: <1°C = very cold; 1–9 = cold; 9–17 = cool; 17–21 = fresh; 21–23 = comfortable; 23–27 = warm; >27°C = hot [1].

const result = net(37, 100, 0.1);
console.log(result); // -> {net: 37}

Calculates the Wet Bulb Globe Temperature (WBGT) index calculated in compliance with the ISO 7243 [11]. The WBGT is a heat stress index that measures the thermal environment to which a person is exposed. In most situations, this index is simple to calculate. It should be used as a screening tool to determine whether heat stress is present. The PHS model allows a more accurate estimation of stress. PHS can be calculated using the function jsthermalcomfort.models.phs.

The WBGT determines the impact of heat on a person throughout the course of a working day (up to 8 h). It does not apply to very brief heat exposures. It pertains to the evaluation of male and female people who are fit for work in both indoor and outdoor occupational environments, as well as other sorts of surroundings [11].

The WBGT is defined as a function of only twb and tg if the person is not exposed to direct radiant heat from the sun. When a person is exposed to direct radiant heat, tdb must also be specified.

const result = wbgt(25, 32);
console.log(result); // -> {"wbgt": 27.1}

const result = wbgt(25, 32, { tdb: 20, with_solar_radiation: true });
console.log(result); // -> {"wbgt": 25.9}

Calculates the Discomfort Index (DI). The index is essentially an effective temperature based on air temperature and humidity. The discomfort index is usuallly divided in 6 dicomfort categories and it only applies to warm environments. [24]

• class 1 - DI < 21 °C - No discomfort
• class 2 - 21 <= DI < 24 °C - Less than 50% feels discomfort
• class 3 - 24 <= DI < 27 °C - More than 50% feels discomfort
• class 4 - 27 <= DI < 29 °C - Most of the population feels discomfort
• class 5 - 29 <= DI < 32 °C - Everyone feels severe stress
• class 6 - DI >= 32 °C - State of medical emergency

const DI = discomfort_index(25, 50); // returns { di: 22.1, discomfort_condition: 'Less than 50% feels discomfort' }

Two-node model of human temperature regulation Gagge et al. (1986).

[10] This model can be used to calculate a variety of indices, including:

• Gagge’s version of Fanger’s Predicted Mean Vote (PMV). This function uses the Fanger’s PMV equations but it replaces the heat loss and gain terms with those calculated by the two node model developed by Gagge et al. (1986) [10].
• PMV SET and the predicted thermal sensation based on SET [10]. This function is similar in all aspects to the pythermalcomfort.models.pmv_gagge(). However, it uses the pythermalcomfort.models.set() equation to calculate the dry heat loss by convection.
• Thermal discomfort (DISC) as the relative thermoregulatory strain necessary to restore a state of comfort and thermal equilibrium by sweating [10]. DISC is described numerically as: comfortable and pleasant (0), slightly uncomfortable but acceptable (1), uncomfortable and unpleasant (2), very uncomfortable (3), limited tolerance (4), and intolerable (S). The range of each category is ± 0.5 numerically. In the cold, the classical negative category descriptions used for Fanger’s PMV apply [10].
• Heat gains and losses via convection, radiation and conduction.
• The Standard Effective Temperature (SET)
• The New Effective Temperature (ET)
• The Predicted Thermal Sensation (TSENS)
• The Predicted Percent Dissatisfied Due to Draft (PD)
• Predicted Percent Satisfied With the Level of Air Movement” (PS)

Warning: Some tests are currently failing for this function. Please refer to the test suite or the project's issue tracker for more details.

const results = two_nodes(25, 25, 0.3, 50, 1.2, 0.5);
console.log(results); // {
e_skin: 16.2,
e_rsw: 7,
e_max: 159.9,
q_sensible: 47.6,
q_skin: 63.8,
q_res: 5.2,
t_core: 36.9,
t_skin: 33.7,
m_bl: 12.9,
m_rsw: 10.3,
w: 0.1,
w_max: 0.6,
set: 23.6,
et: 25,
pmv_gagge: 0.1,
pmv_set: -0,
disc: 0.1,
t_sens: 0.1
}

Calculates the Standard Effective Temperature (SET). The SET is the temperature of a hypothetical isothermal environment at 50% (rh), <0.1 m/s (20 fpm) average air speed (v), and tr = tdb, in which the total heat loss from the skin of an imaginary occupant wearing clothing, standardized for the activity concerned is the same as that from a person in the actual environment with actual clothing and activity level [10].

const set = set_tmp(25, 25, 0.1, 50, 1.2, 0.5); // returns {set: 24.3}

Calculates the Wind Chill Index (WCI) in accordance with the ASHRAE 2017 Handbook Fundamentals - Chapter 9 [18].

The wind chill index (WCI) is an empirical index based on cooling measurements taken on a cylindrical flask partially filled with water in Antarctica (Siple and Passel 1945). For a surface temperature of 33°C, the index describes the rate of heat loss from the cylinder via radiation and convection as a function of ambient temperature and wind velocity.

This formulation has been met with some valid criticism. WCI is unlikely to be an accurate measure of heat loss from exposed flesh, which differs from plastic in terms of curvature, roughness, and radiation exchange qualities, and is always below 33°C in a cold environment. Furthermore, the equation’s values peak at 90 km/h and then decline as velocity increases. Nonetheless, this score reliably represents the combined effects of temperature and wind on subjective discomfort for velocities below 80 km/h [18].

Determines the adaptive thermal comfort based on EN 16798-1 2019 [3]

Note: You can use this function to calculate if your conditions are within the EN adaptive thermal comfort region. Calculations with comply with the EN 16798-1 2019 [3].

const results = adaptive_en(25, 25, 20, 0.1);
console.log(results); // {tmp_cmf: 25.4, acceptability_cat_i: true, acceptability_cat_ii: true, ... }
console.log(results.acceptability_cat_i); // true
// The conditions you entered are considered to comply with Category I

// for users who wants to use the IP system
const results = adaptive_en(77, 77, 68, 0.3, 'IP');
console.log(results); // {tmp_cmf: 77.7, acceptability_cat_i: true, acceptability_cat_ii: true, ... }

const results = adaptive_en(25, 25, 9, 0.1);
console.log(results); // {tmp_cmf: NaN, acceptability_cat_i: true, acceptability_cat_ii: true, ... }
// The adaptive thermal comfort model can only be used
// if the running mean temperature is between 10 °C and 30 °C

Calculates the Apparent Temperature (AT). The AT is defined as the temperature at the reference humidity level producing the same amount of discomfort as that experienced under the current ambient temperature, humidity, and solar radiation [17]. In other words, the AT is an adjustment to the dry bulb temperature based on the relative humidity value. Absolute humidity with a dew point of 14°C is chosen as a reference.

[16]. It includes the chilling effect of the wind at lower temperatures.

Two formulas for AT are in use by the Australian Bureau of Meteorology: one includes solar radiation and the other one does not ({@link http://www.bom.gov.au/info/thermal_stress/}, 29 Sep 2021). Please specify q if you want to estimate AT with solar load.

const result = at(25, 30, 0.1);
console.log(result); // {at: 24.1}

Returns Predicted Mean Vote ( PMV ) and Predicted Percentage of Dissatisfied ( PPD ) calculated in accordance with main thermal comfort Standards. The PMV is an index that predicts the mean value of the thermal sensation votes (self-reported perceptions) of a large group of people on a sensation scale expressed from –3 to +3 corresponding to the categories: cold, cool, slightly cool, neutral, slightly warm, warm, and hot. [1]

While the PMV equation is the same for both the ISO and ASHRAE standards, in the ASHRAE 55 PMV equation, the SET is used to calculate the cooling effect first, this is then subtracted from both the air and mean radiant temperatures, and the differences are used as input to the PMV model, while the airspeed is set to 0.1m/s. Please read more in the Note below.

Notes:

You can use this function to calculate the PMV and PPD in accordance with either the ASHRAE 55 2020 Standard [1] or the ISO 7730 Standard [2].

This is a version that supports scalar arguments.

const tdb = 25;
const tr = 25;
const rh = 50;
const v = 0.1;
const met = 1.4;
const clo = 0.5;
// Calculate relative air speed
const v_r = v_relative(v, met);
// Calculate dynamic clothing
const clo_d = clo_dynamic(clo, met);
const results = pmv_ppd(tdb, tr, v_r, rh, met, clo_d);
console.log(results); // Output: { pmv: 0.06, ppd: 5.1 }
console.log(results.pmv); // Output: -0.06

Calculate PMV and PPD in accordance with ASHRAE 55.

Delegates to pmv_ppd with the standard fixed to 'ASHRAE'. The ASHRAE equation applies a cooling effect (via SET) before computing PMV — this lowers the result compared to the raw ISO equation when elevated air speed is present.

Valid ASHRAE 55 input ranges (when limit_inputs is true):

• 10 < tdb [°C] < 40
• 10 < tr [°C] < 40
• 0 < vr [m/s] < 2
• 1 < met [met] < 4
• 0 < clo [clo] < 1.5

const r = pmv_ppd_ashrae(25, 25, 0.1, 50, 1.2, 0.5);
console.log(r.pmv); // 0.08
console.log(r.ppd); // 5.1

Calculate PMV and PPD in accordance with ISO 7730.

Delegates to pmv_ppd with the standard fixed to 'ISO'. The ISO equation uses Fanger's original PMV formulation without the ASHRAE cooling-effect adjustment.

ISO 7730 applies stricter input limits than ASHRAE 55. When limit_inputs is true (the default), inputs outside the following ranges cause the function to return NaN:

• 10 < tdb [°C] < 30
• 10 < tr [°C] < 40
• 0 < vr [m/s] < 1
• 0.8 < met [met] < 4
• 0 < clo [clo] < 2
• -2 < PMV < 2 (result is clamped to NaN outside this range)

const r = pmv_ppd_iso(25, 25, 0.1, 50, 1.2, 0.5);
console.log(r.pmv); // 0.08
console.log(r.ppd); // 5.1

Determines the adaptive thermal comfort based on ASHRAE 55. The adaptive model relates indoor design temperatures or acceptable temperature ranges to outdoor meteorological or climatological parameters. The adaptive model can only be used in occupant-controlled naturally conditioned spaces that meet all the following criteria:

• There is no mechianical cooling or heating system in operation
• Occupants have a metabolic rate between 1.0 and 1.5 met
• Occupants are free to adapt their clothing within a range as wide as 0.5 and 1.0 clo
• The prevailing mean (runnin mean) outdoor temperature is between 10 and 33.5 °C

The ASHRAE 55 2020 limits are 10 < tdb [°C] < 40, 10 < tr [°C] < 40, 0 < vr [m/s] < 2, 10 < t running mean [°C] < 33.5

You can use this function to calculate if your conditions are within the adaptive thermal comfort region. Calculations with comply with the ASHRAE 55 2020 Standard [1].

import { adaptive_ashrae } from "jsthermalcomfort/models";
const results = adaptive_ashrae(25, 25, 20, 0.1);
console.log(results);
// {tmp_cmf: 24.0, tmp_cmf_80_low: 20.5, tmp_cmf_80_up: 27.5,
//   tmp_cmf_90_low: 21.5, tmp_cmf_90_up: 26.5, acceptability_80: true,
//   acceptability_90: true}
console.log(results.acceptability_80);
// true

import { adaptive_ashrae } from "jsthermalcomfort/models";
// For users who want to use the IP system
const results = adaptive_ashrae(77, 77, 68, 0.3, 'IP');
console.log(results);
// {tmp_cmf: 75.2, tmp_cmf_80_low: 68.9, tmp_cmf_80_up: 81.5,
//  tmp_cmf_90_low: 70.7, tmp_cmf_90_up: 79.7, acceptability_80: true,
//  acceptability_90: true}

import { adaptive_ashrae } from "jsthermalcomfort/models";
const results = adaptive_ashrae(25, 25, 9, 0.1);
console.log(results);
// {tmp_cmf: NaN, tmp_cmf_80_low: NaN, ...}
// The adaptive thermal comfort model can only be used
// if the running mean temperature is higher than 10°C

Calculates the solar gain to the human body using the Effective Radiant Field ( ERF) [1]. The ERF is a measure of the net energy flux to or from the human body. ERF is expressed in W over human body surface area [w/m2].

In addition, it calculates the delta mean radiant temperature. Which is the amount by which the mean radiant temperature of the space should be increased if no solar radiation is present.

More information on the calculation procedure can be found in Appendix C of [1].

import {solar_gain} from "jsthermalcomfort/models";
const results = solar_gain(0, 120, 800, 0.5, 0.7, "sitting");
console.log(results); // {erf: 42.9, delta_mrt: 10.3}

Returns the value of the Cooling Effect ( CE ) calculated in compliance with the ASHRAE 55 2020 Standard [1]. The CE of the elevated air speed is the value that, when subtracted equally from both the average air temperature and the mean radiant temperature, the same SET under still air as in the first SET calculation under elevated air speed. The cooling effect is calculated only for air speed higher than 0.1 m/s.

const CE = cooling_effect(25, 25, 0.3, 50, 1.2, 0.5);
console.log(CE); // Output: {ce: 1.64}

// For users who want to use the IP system
const CE_IP = cooling_effect(77, 77, 1.64, 50, 1, 0.6, "IP");
console.log(CE_IP); // Output: {ce: 3.74}

Return the PMV value calculated with the Adaptive Thermal Heat Balance Framework [27]. The adaptive thermal heat balance (ATHB) framework introduced a method to account for the three adaptive principals, namely physiological, behavioral, and psychological adaptation, individually within existing heat balance models. The objective is a predictive model of thermal sensation applicable during the design stage or in international standards without knowing characteristics of future occupants.

This is a version that supports scalar arguments.

const tdb = 25;
const tr = 25;
const vr = 0.1;
const rh = 50;
const met = 1.1;
const t_running_mean = 20;

const athb_result = athb(tdb, tr, vr, rh, met, t_running_mean);
console.log(athb_result); // Output: {athb_pmv: 0.2}

Returns Predicted Mean Vote ( PMV ) calculated in accordance with main thermal comfort Standards.

The PMV is an index that predicts the mean value of the thermal sensation votes (self-reported perceptions) of a large group of people on a sensation scale expressed from –3 to +3 corresponding to the categories: cold, cool, slightly cool, neutral, slightly warm, warm, and hot. [1]

While the PMV equation is the same for both the ISO and ASHRAE standards, in the ASHRAE 55 PMV equation, the SET is used to calculate the cooling effect first, this is then subtracted from both the air and mean radiant temperatures, and the differences are used as input to the PMV model, while the airspeed is set to 0.1m/s. Please read more in the Note below.

Notes:

You can use this function to calculate the PMV [1] [2]

This is a version that supports scalar arguments.

const tdb = 25;
const tr = 25;
const rh = 50;
const v = 0.1;
const met = 1.4;
const clo = 0.5;

// calculate relative air speed
const v_r = v_relative(v, met);
// calculate dynamic clothing
const clo_d = clo_dynamic(clo, met);

const results = pmv(tdb, tr, v_r, rh, met, clo_d);
console.log(results); // 0.06

Returns Adaptive Predicted Mean Vote (aPMV) [25]. This index was developed by Yao, R. et al. (2009). The model takes into account factors such as culture, climate, social, psychological and behavioral adaptations, which have an impact on the senses used to detect thermal comfort. This model uses an adaptive coefficient (λ) representing the adaptive factors that affect the sense of thermal comfort.

This is a version that supports scalar arguments.

const tdb = 24,
const tr = 30,
const vr = 0.22,
const rh = 50,
const met = 1.4,
const clo = 0.5,
const a_coefficient = 0.293,
const wme = undefined,

const result = a_pmv(tdb, tr, vr, rh, met, clo, a_coefficient, wme);
console.log(result) //output { a_pmv: 0.48 }

Calculates the percentage of thermally dissatisfied people with the ankle draft (0.1 m) above floor level [23]. This equation is only applicable for vr < 0.2 m/s (40 fps).

results = ankle_draft(25, 25, 0.2, 50, 1.2, 0.5, 0.3, "SI")
console.log(results) // expected result is {PPD_ad: 18.5, Acceptability: true}

Returns Adjusted Predicted Mean Votes with Expectancy Factor (ePMV). This index was developed by Fanger, P. O. et al. (2002). In non-air-conditioned buildings in warm climates, occupants may sense the warmth as being less severe than the PMV predicts. The main reason is low expectations, but a metabolic rate that is estimated too high can also contribute to explaining the difference. An extension of the PMV model that includes an expectancy factor is introduced for use in non-air-conditioned buildings in warm climates [26].

This is a version that supports scalar arguments.

const tdb = 28;
const tr = 28;
const v = 0.1;
const met = 1.4;
const clo = 0.5;
// Calculate relative air speed
const v_r = v_relative(v, met);
// Calculate dynamic clothing
const clo_d = clo_dynamic(clo, met);
const e_coefficient = 0.6;

const result = e_pmv(tdb, tr, v_r, rh, met, clo_d, e_coefficient);
console.log(result) // output {e_pmv: 0.51}

Calculates the percentage of thermally dissatisfied people with a vertical temperature gradient between feet and head [1] . This equation is only applicable for vr < 0.2 m/s (40 fps).

const result = vertical_tmp_grad_ppd(25, 25, 0.1, 50, 1.2, 0.5, 7); // returns {'ppd_vg': 12.6, 'acceptability': false}

It helps you to estimate if the conditions you have selected would cause heat strain. This occurs when either the following variables reaches its maximum value:

• m_rsw Rate at which regulatory sweat is generated, [mL/h/m2].
• w : Skin wettedness, adimensional. Ranges from 0 and 1.
• m_bl : Skin blood flow [kg/h/m2].

const results = use_fans_heatwaves(25, 25, 0.1, 50, 1.2, 0.5);
console.log(results); // 
{
e_skin: 18.1,
e_rsw: 10.0,
e_max: 145.0,
q_sensible: 45.7, 
q_skin: 63.8, 
q_res: 5.2, 
t_core: 36.9, 
t_skin: 33.8, 
m_bl: 13.6, 
m_rsw: 14.6, 
w: 0.1, 
w_max: 0.7, 
heat_strain_blood_flow: 0.0, 
heat_strain_w: 0.0, 
heat_strain_sweating: 0.0, 
heat_strain: 0.0
}

Representative clothing insulation Icl as a function of outdoor air temperature at 06:00 a.m [4].

Note: The ASHRAE 55 2020 states that it is acceptable to determine the clothing insulation Icl using this equation in mechanically conditioned buildings [1].

Determines the Universal Thermal Climate Index (UTCI). The UTCI is the equivalent temperature for the environment derived from a reference environment. It is defined as the air temperature of the reference environment which produces the same strain index value in comparison with the reference individual's response to the real environment. It is regarded as one of the most comprehensive indices for calculating heat stress in outdoor spaces. The parameters that are taken into account for calculating UTCI involve dry bulb temperature, mean radiation temperature, the pressure of water vapor or relative humidity, and wind speed (at the elevation of 10 m above the ground). [7]

• Note: You can use this function to calculate the Universal Thermal Climate Index (UTCI) The applicability wind speed value must be between 0.5 and 17 m/s.

console.log(utci(25, 25, 1.0, 50)) // will print 24.6
console.log(utci(77, 77, 3.28, 50, 'ip')) // will print 76.4
console.log(utci(25, 25, 1.0, 50, 'si', true))
// will print {utci: 24.6, stress_category: "no thermal stress"}

The steady physiological equivalent temperature (PET) is calculated using the Munich Energy-balance Model for Individuals (MEMI), which simulates the human body's thermal circumstances in a medically realistic manner. PET is defined as the air temperature at which, in a typical indoor setting the heat budget of the human body is balanced with the same core and skin temperature as under the complex outdoor conditions to be assessed [20].

The following assumptions are made for the indoor reference climate: tdb = tr, v = 0.1 m/s, water vapour pressure = 12 hPa, clo = 0.9 clo, and met = 1.37 met + basic metabolism.

PET allows a layperson to compare the total effects of complex thermal circumstances outside with his or her own personal experience indoors in this way. This function solves the heat balances without accounting for heat storage in the human body.

The PET was originally proposed by Hoppe [20]. In 2018, Walther and Goestchel [21] proposed a correction of the original model, purging the errors in the PET calculation routine, and implementing a state-of-the-art vapour diffusion model. Walther and Goestchel (2018) model is therefore used to calculate the PET.

Warning: Some tests are currently failing for this function. Please refer to the test suite or the project's issue tracker for more details.

const result = pet_steady(20, 20, 50, 0.15, 1.37, 0.5);
console.log(result); // {pet: 18.85}

JOS-3 model simulates human thermal physiology including skin temperature, core temperature, sweating rate, etc. for the whole body and 17 local body parts.

This model was developed at Shin-ichi Tanabe Laboratory, Waseda University and was derived from 65 Multi-Node model (https://doi.org/10.1016/S0378-7788(02)00014-2) and JOS-2 model (https://doi.org/10.1016/j.buildenv.2013.04.013).

To use this model, create an instance of the JOS3 class with optional body parameters such as body height, weight, age, sex, etc.

Environmental conditions such as air temperature, mean radiant temperature, air velocity, etc. can be set using the setter methods. (ex. X.tdb, X.tr X.v) If you want to set the different conditions in each body part, set them as a 17 lengths of list, dictionary, or numpy array format.

List or numpy array format input must be 17 lengths and means the order of "head", "neck", "chest", "back", "pelvis", "left_shoulder", "left_arm", "left_hand", "right_shoulder", "right_arm", "right_hand", "left_thigh", "left_leg", "left_foot", "right_thigh", "right_leg" and "right_foot".

The model output includes local and mean skin temperature, local core temperature, local and mean skin wettedness, and heat loss from the skin etc. The model output can be accessed using "dict_results()" method and be converted to a csv file using "to_csv" method. Each output parameter also can be accessed using getter methods. (ex. X.t_skin, X.t_skin_mean, X.t_core)

If you use this package, please cite us as follows and mention the version of pythermalcomfort used: Y. Takahashi, A. Nomoto, S. Yoda, R. Hisayama, M. Ogata, Y. Ozeki, S. Tanabe, Thermoregulation Model JOS-3 with New Open Source Code, Energy & Buildings (2020), doi: https://doi.org/10.1016/j.enbuild.2020.110575

Note: To maintain consistency in variable names for jsthermalcomfort and pythermalcomfort, some variable names differ from those used in the original paper.