energy.degree-days

HDD = sum over days of max(0, base - mean)
CDD = sum over days of max(0, mean - base)

def degree_days(daily_mean_temperatures: Sequence[int], base_temperature: int) -> DegreeDays

@dataclass(frozen=True)
class DegreeDays:
    """Heating and cooling degree days over the same run of days."""

    #: sum of how far each day's mean fell below the base, in tenths of a degree day
    heating: int
    #: sum of how far each day's mean rose above the base, in tenths of a degree day
    cooling: int
    #: how many daily means were counted
    days: int

from fune.energy.degree_days import degree_days  # energy.degree-days@^1

from typing import Sequence

from .energy_degree_days_types import DegreeDays

LIMIT = 1000  # 100.0 C in tenths


def _check_temperature(what: str, value: object) -> None:
    if not isinstance(value, int) or isinstance(value, bool) or value < -LIMIT or value > LIMIT:
        raise ValueError("%s must be whole tenths of a degree from -1000 to 1000, received %s" % (what, value))


def degree_days(daily_mean_temperatures: Sequence[int], base_temperature: int) -> DegreeDays:
    """Heating and cooling degree days in tenths: each day adds how far its
    mean fell below (heating) or rose above (cooling) the base.
    """
    _check_temperature("base temperature", base_temperature)
    heating = 0
    cooling = 0
    for mean in daily_mean_temperatures:
        _check_temperature("daily mean temperature", mean)
        if mean < base_temperature:
            heating += base_temperature - mean
        elif mean > base_temperature:
            cooling += mean - base_temperature
    return DegreeDays(heating=heating, cooling=cooling, days=len(daily_mean_temperatures))

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add energy.degree-days

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./energy.degree-days-1.0.0-python.fune, or fetch it from a terminal with fune pull energy.degree-days@1.0.0:python.

The whole function, every language, is one file too: energy.degree-days-1.0.0.fune, 10,167 bytes, sha256 dadb9334811da41846ae4e0017ec98006bd554a04830a1c1dd1ed49719b483e0. It installs into a project of any language.

# fune: before energy.degree-days

# fune: after energy.degree-days

# fune: step energy.degree-days after <n|label>

More from the author

They are the standard way to normalise heating (or cooling) energy for the weather: kWh per degree day is comparable between a mild and a cold winter where raw kWh is not.

## Units

Temperatures and results are integers in **tenths of a degree**: 12.3 °C is `123`, and 45 degree days is `450`. Temperatures are recorded to a tenth of a degree, and with integer tenths every sum is exact, so the answer is exact to 0.1 of a degree day in all three languages rather than approximately so.

## Decisions

- **The base is an argument.** 15.5 °C (`155`) is the long-standing UK convention for heating degree days (CIBSE TM41, and the base of the published UK regional series); buildings with better insulation or higher internal gains are often analysed at a lower base, and cooling is often counted above 15.5 °C or 18 °C. The same base is used for both sums. - **Mean-temperature method only.** Each day contributes `base - mean` when positive. The Met Office / UKMO method that estimates degree days from a day's maximum and minimum (for days where the base falls between them) is a different formula and is not what this does; pass the true daily mean. - **A day at exactly the base counts for neither.** - An empty list gives zeros. A mean outside -100.0 to 100.0 °C is refused as a unit mistake (Fahrenheit, or whole degrees times 100).

## Source

CIBSE TM41, "Degree-days: theory and application" (Chartered Institution of Building Services Engineers), for the definition and the 15.5 °C UK base.

Files