heatindex 0.0.2
Tools for Calculating Heat Stress
License: MIT
Requires Python: >=3.8

# Heatindex
Tools for Calculating Heat Stress

This package currently provides three functions. The first is `heatindex`, which is an implementation of the simpler and faster heat index introduced by [Lu et al. (2025)](#lu2025). This simpler and faster implementation matches the values of the heat index from [Steadman (1979)](#steadman1979) and [Lu and Romps (2022)](#lu2022) for air temperatures above 300 K (27 C, 80 F) and with only minor differences at lower temperatures. The second is `wetbulb`, which calculates the wet-bulb temperature from pressure, temperature, and relative humidity using the algorithm introduced by [Romps (2025)](#romps2025) using the Rankine-Kirchhoff equations. The third is `rh_from_wetbulb`, which calculates the relative humidity from the pressure, temperature, and wet-bulb temperature.

## Installation

The recommended way to install `heatindex` is by using `pip`, the Python package installer.

### Recommended

Open your terminal or command prompt and run the following command:

```bash
pip install heatindex
```

This will download and install the latest stable version of `heatindex` from the Python Package Index (PyPI).

### Manual

Alternatively, clone the repository and install it locally:

```bash
git clone https://github.com/davidromps/heatindex
cd heatindex/python
./prepare_package.sh
pip install .
```

The source code for this package is located in `heatindex/cpp`. Running `prepare_package.sh` creates hard links in `heatindex/python/src` to the source files.

## Usage and examples

### `heatindex`

The `heatindex` function takes two arguments: air temperature (`T`) in Kelvin and relative humidity (`rh`) on a scale from 0 to 1, and returns the heat index in Kelvin. Note that the relative humidity is defined with respect to saturation over liquid water for air temperatures over 273.16 K and with respect to saturation over ice for air temperatures lower than 273.16 K.

For example:

```python
>>> import heatindex as hi
>>> hi.heatindex(310,0.5)
318.62255317071686
```

Note: The precision of the underlying root solver is set to `1e-8`, so the output is reliable up to the seventh decimal place.

The `heatindex` function is vectorized using NumPy, enabling efficient element-wise computations. For example, when `T` and `rh` are lists of three elements, the result is a Numpy array of length 3:

```python
>>> T  = [310,311,312]
>>> rh = [0,0.5,1]
>>> hi.heatindex(T,rh)
array([305.55495303, 324.54442932, 368.60533913])
```

If one argument is an array and the other a scalar, NumPy broadcasting applies:

```python
>>> T  = [310,311,312]
>>> rh = 1
>>> hi.heatindex(T,rh)
array([359.90632483, 364.20412564, 368.60533913])
```

When both `T` and `rh` are arrays (or matrices), they must have identical shapes:

```python
>>> T  = [[310,311],[312,313]]
>>> rh = [[0,1],[0,1]]
>>> hi.heatindex(T,rh)
array([[305.55495303, 364.20412564],
       [307.05336139, 373.11024873]])
```

### `wetbulb`

The `wetbulb` function has three required arguments: air pressure (`p`), air temperature (`T`) in Kelvin, and relative humidity (`rh`) on a scale from 0 to 1, and returns the wet-bulb temperature in Kelvin. Note that the relative humidity is defined with respect to saturation over liquid water for air temperatures over 273.16 K and with respect to saturation over ice for air temperatures lower than 273.16 K.

For example:

```python
>>> import heatindex as hi
>>> hi.wetbulb(1e5,310,0.5)
[1] 300.79698256455345
```

By default, `wetbulb` returns the thermodynamic wet-bulb temperature. If the psychrometric (a.k.a., sling or aspirated) wet-bulb temperature is desired instead, then:

```python
> hi.wetbulb(1e5,310,.5,psychrometric=True)
[1] 300.5813688610734
```

The `wetbulb` function can also calculate the thermodynamic or psychrometric ice-bulb temperature.


## Authors

* **Yi-Chuan Lu** - *Creator* - [yclu@berkeley.edu](mailto:yclu@berkeley.edu) - [ORCID: 0000-0003-3659-1474](https://orcid.org/0000-0003-3659-1474)
* **David M. Romps** - *Creator, Maintainer* - [romps@berkeley.edu](mailto:romps@berkeley.edu) - [ORCID: 0000-0001-7649-5175](https://orcid.org/0000-0001-7649-5175)

## Citation

To cite package `heatindex` in publications use:

 Lu, Y.-C. and Romps, D.M., 2025. heatindex: Tools for Calculating Heat Stress.
 <https://heatindex.org>.

A BibTeX entry for LaTeX users is
```bibtex
 @Manual{heatindex2025,
  title = {heatindex: Tools for Calculating Heat Stress},
  author = {Yi-Chuan Lu and David M. Romps},
  year = {2025},
  note = {Python package version 0.0.2},
  url = {https://heatindex.org},
 }
```

## References

<a id="lu2025"></a>
1. Lu et al., "Simpler and faster: an improved heat index," in review (2025).
<a id="romps2025"></a>
2. Romps, "Wet-bulb temperature from pressure, relative humidity, and air temperature," in review (2025).
<a id="steadman1979"></a>
3. Steadman, R.G., 1979. The assessment of sultriness. Part I: A temperature-humidity index based on human physiology and clothing science. Journal of Applied Meteorology and Climatology, 18(7), pp.861-873.
<a id="lu2022"></a>
4. Lu, Y.-C. and Romps, D.M., 2022. Extending the heat index. Journal of Applied Meteorology and Climatology, 61(10), pp.1367-1383.