Metadata-Version: 2.4
Name: heatpumpmodel
Version: 0.1.0
Summary: Heat-pump seasonal-performance model (Rogeau et al. 2024) shared by buildingmodel and building_eload
Author-email: Yassine Abdelouadoud <yassine.abdelouadoud@gmail.com>
Maintainer-email: Yassine Abdelouadoud <yassine.abdelouadoud@gmail.com>
License: The MIT License (MIT)
        =====================
        
        - Copyright © `2025` `Yoann Chiche`
        - Copyright © `2025` `Seddik Yassine Abdelouadoud`
        - Copyright © `2025` `Anna Cocchi`
        
        Permission is hereby granted, free of charge, to any person
        obtaining a copy of this software and associated documentation
        files (the “Software”), to deal in the Software without
        restriction, including without limitation the rights to use,
        copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the
        Software is furnished to do so, subject to the following
        conditions:
        
        The above copyright notice and this permission notice shall be
        included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
        OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
        NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
        HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
        WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
        OTHER DEALINGS IN THE SOFTWARE.
        
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <4.0.0,>=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff>=0.16; extra == "dev"
Dynamic: license-file

# 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`](https://gitlab.com/energytransition/buildingmodel)
and `building_eload` share one copy of the physics instead of two that drift apart
(buildingmodel issue #47).

## Install

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

## Use

```python
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

| Axis | Values |
|---|---|
| `System` | `A_A` (air/air), `A_W` (air/water), `G_W` (ground/water) |
| `Mode` | `M`, `M_SB`, `BA` (bivalent alternative), `BP` (bivalent parallel) |
| `Emitter` | `FH` 35 °C, `LT` 45 °C, `MT` 55 °C, `HT` 65 °C, `FAN_COIL` |
| `Technology` | `ON_OFF`, `BI_COMPRESSOR`, `INVERTER` |

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

## 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

```bash
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`.
