heatpumpmodel

Single-source implementation of the steady-state (bin-style) heat-pump performance model of

A. Rogeau, R. Vieubled, M. de la Ruche, G. Girard, "A generic methodology for mapping the performance of various heat pump configurations considering part-load behavior", Energy and Buildings 2024, https://doi.org/10.1016/j.enbuild.2024.114471

numpy is the only dependency. The package holds physics only: it knows nothing about a building stock, a weather reader or a simulation pipeline. Callers pass hourly arrays in and keep their own integration layer.

It exists so that buildingmodel and building_eload share one copy of the physics instead of two that drift apart (buildingmodel issue #47).

Install

pip install heatpumpmodel
# or, from a checkout:
pip install -e ".[dev]"

Use

import numpy as np
from heatpumpmodel import (
    Emitter, HeatPumpConfig, Mode, System, Technology,
    compute_T_base, hourly_power_split, scop, size_heat_pump,
)

# hourly series over a year: outdoor temperature (°C), relative humidity (%),
# and heat demand in any single consistent unit (it cancels in every ratio).
t_out = ...
rh = ...
demand = np.clip(20.0 - t_out, 0.0, None)

cfg = HeatPumpConfig(System.A_W, Mode.M, Emitter.MT, Technology.ON_OFF)
sizing = size_heat_pump(cfg, demand, t_out, compute_T_base(t_out))
p_h, p_e, p_h_backup = hourly_power_split(cfg, sizing, demand, t_out, rh=rh)

print(scop(p_h, p_e))            # seasonal COP

seasonal_performance(cfg, sizing, demand, t_out, rh=rh) bundles {"scop", "ecr", "peak_share"} in one call.

Configuration axes

Sub-models (COPCurve, DefrostModel, PartLoadModel, WeatherCompensation) are dataclasses on HeatPumpConfig and can be replaced with manufacturer-specific fits.

From French DPE data

heatpumpmodel.dpe maps buildingdata's heat_pump_type / heating_emitter_type / heat_pump_installation_period DPE columns onto a HeatPumpConfig, so buildingmodel and building_eload resolve the same building to the same machine in both the static and dynamic stages instead of each guessing independently:

from heatpumpmodel import HeatPumpConfig, System, Mode, Emitter, Technology, config_from_dpe

default = HeatPumpConfig(System.A_W, Mode.M, Emitter.MT, Technology.ON_OFF)
cfg = config_from_dpe("air/air", "air", "[2015, 2100]", default=default)

Any DPE column that is None falls back to the matching axis of default; a present value outside the module's vocabulary raises ValueError rather than drifting silently. See heatpumpmodel/dpe.py for the vocabulary vintage and the full mapping tables.

Conventions

• Temperatures in °C, ΔT gaps in K.
• Powers/demand in one arbitrary, self-cancelling unit.
• Relative humidity in percent [0, 100] — the EPW convention.
• Air-source configs (A/A, A/W) require an rh series: a missing, all-NaN or all-zero rh raises ValueError rather than silently skipping the defrost derate (which would leave SCOP ~5 % optimistic).
• Every effective COP is floored at 1.0 — a heat pump never draws more electricity than the resistance backup would for the same heat.

Documentation

doc/heat_pump_model_spec.md is the implementation contract: equation-by-equation mapping to the paper, coefficient provenance (including the values resolved from the authors' Zenodo code rather than the PDF), and the documented deviations.

Tests

pytest                          # hermetic suite, synthetic climate
HEATPUMPMODEL_PARIS_EPW=/path/to/paris.epw pytest -m integration

The integration test reproduces the paper's Fig. 4 SCOP values and needs the authors' Paris-Montsouris TMY EPW; it skips when that file is not supplied. See its docstring for why an ERA5 Paris record does not substitute.

Licence

MIT — see LICENSE.