res-asset-kpi

Key performance indicators for operating PV plants, wind turbines and battery storage, and the contract logic around them: guaranteed values, exclusions and liquidated damages.

Asset managers, O&M contractors and lenders' engineers compute the same indicators for every portfolio: the performance ratio, availability as the contract defines it, the bridge from budget to actual production, power curves, failure rates, round-trip efficiency, cycles. This library writes them once, with explicit units, explicit time handling (UTC grids, local reporting periods, the DST hours) and a test against a hand-worked example for every formula. Its code comes from six open analysis projects and reproduces their results exactly (validation).

Documentation: https://kwwaleszczynski-del.github.io/res-asset-kpi/

What it covers

Install

pip install res-asset-kpi

Python 3.11+; depends on numpy, pandas, scipy and PyYAML.

Examples

Performance ratio, plain and corrected to 25 °C cell temperature:

from res_asset_kpi import pv

t = pv.pr_terms(p_ac_kw=[48.0, 66.0], poa_wm2=[600.0, 900.0], p_stc_kw=100.0, interval_h=0.25,
                t_cell_c=[40.0, 55.0], gamma_per_k=-0.004)
t.pr, t.pr_temperature_corrected            # (0.76, 0.8407...)

\mathrm{PR} = \frac{\sum_i E_i}{\sum_i P_\mathrm{STC}\, G_i / G_\mathrm{STC}\, \Delta t}
\qquad
\mathrm{PR}_{25} = \frac{\sum_i E_i}{\sum_i P_\mathrm{STC}\, G_i / G_\mathrm{STC}\,\left[1 + \gamma\,(T_{c,i} - 25)\right] \Delta t}

A logger export in local time, with the autumn hour logged twice, onto a regular UTC grid:

import pandas as pd
from res_asset_kpi import schema

long = schema.read(pd.read_csv("export.csv"), "mapping.yaml")   # units converted, DST resolved
wide = schema.to_wide(long)                                      # index: interval start, UTC

Wind availability as an illustrative turbine warranty counts it, and the cost of calling grid stops faults:

from res_asset_kpi import wind

totals = wind.category_totals(categories, interval_h=1 / 6, lost_kwh=lost, actual_kwh=actual)
wind.availability(totals, "oem_warranty", allowance_h=60).time

Round-trip efficiency of a battery per month, corrected for the change of stored energy $\Delta E$ with the one-way efficiency $\eta$:

\mathrm{RTE} = \frac{E_\mathrm{out} + \eta\,\Delta E}{E_\mathrm{in}} \quad (\Delta E \ge 0),
\qquad
\mathrm{RTE} = \frac{E_\mathrm{out}}{E_\mathrm{in} + |\Delta E| / \eta} \quad (\Delta E < 0)

from res_asset_kpi import bess

monthly = bess.window_rte(site, "M", reference_energy=100.0, aux_metering="behind_meter")
monthly[["rte", "rte_excl_aux", "efc", "valid"]]

Two worked examples run on public data: NREL PVDAQ system 34 (examples/pvdaq_system34.py) and the Kelmarsh wind farm (examples/kelmarsh.py). The repository holds no data; the scripts read the files that the companion projects download.

Quality

• Typed API (mypy strict), numpydoc docstrings whose examples run as doctests.
• Hand-worked tests for every formula; property tests with Hypothesis (the energy bridge closes, availabilities stay in $[0, 1]$, rainflow preserves the path length, interval operations count every moment once).
• Coverage above 90 %, CI on Python 3.11-3.13 and on the oldest supported dependencies.
• validation/parity.py reproduces the source projects' results: 41 checks over about one million values, largest relative difference $1.3 \cdot 10^{-13}$.

Source projects

Citing

See CITATION.cff; releases are archived on Zenodo with a DOI.

License

MIT, see LICENSE.