Metadata-Version: 2.4
Name: openenergyid
Version: 0.1.42
Summary: Open Source Python library for energy analytics and simulations
Author-email: Jan Pecinovsky <jan@energieid.be>, Max Helskens <max@energieid.be>, Oscar Swyns <oscar@energieid.be>
License-Expression: MIT
Keywords: energy,analytics,simulation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.12.15
Requires-Dist: pandera[polars]>=0.22.1
Requires-Dist: pvlib>=0.13.0
Requires-Dist: pydantic>=2.8.2
Requires-Dist: requests>=2.32.3
Requires-Dist: scikit-learn>=1.8.0
Requires-Dist: statsmodels>=0.14.2
Dynamic: license-file

# OpenEnergyID

Open Source Python library for energy data analytics and simulations.

OpenEnergyID is a powerful Python library that provides a wide range of tools for energy data analysis and simulation. Whether you are a data scientist, researcher, or developer working in the energy sector, OpenEnergyID can help you gain valuable insights from your data and build sophisticated models.

[*more info for developers*](DEVELOPERS.md)

## Getting Started

To get started with OpenEnergyID, you can install it using `pip`:

```bash
pip install openenergyid
```

## Analyses

OpenEnergyID provides a variety of analysis modules to help you work with your energy data.

### Baseload Analysis

The baseload analysis module helps you determine the baseload consumption of a building or a portfolio of buildings.

- Use `BaseloadAnalyzer(timezone="Europe/Brussels")`, prepare data with `prepare_power_series(energy_lf)` and then call `analyze(power_lf, "1h")`.
- Accepts either energy (`timestamp`/`total` in kWh per 15 min) or precomputed power (`timestamp`/`power` watts); gapped or zero-valued intervals are kept and handled safely.
- For homes with unmeasured PV, use `nighttime_only=True` to filter to nighttime readings only (uses pvlib for solar position).
- Outputs energy splits (baseload vs total) and baseload ratios per chosen reporting granularity, keeping computations lazy via Polars `LazyFrame`.

### Capacity Analysis

The capacity analysis module helps you identify peaks in your power data.

```python
from openenergyid.capacity import CapacityAnalysis

analyzer = CapacityAnalysis(data=power_series, threshold=2.5)
peaks = analyzer.find_peaks()
```

### Dynamic Tariff Analysis

The dynamic tariff analysis module helps you analyze the impact of dynamic tariffs on your energy costs.

```python
from openenergyid.dyntar import calculate_dyntar_columns

df_with_dyntar = calculate_dyntar_columns(df)
```

### Energy Sharing

The energy sharing module helps you simulate energy sharing scenarios.

```python
from openenergyid.energysharing import calculate

result = calculate(df, method=CalculationMethod.OPTIMAL)
```

### Evening Peak Avoidance

The evening peak avoidance module ("Avondpiek mijden") measures how much of a connection's consumption falls inside a fixed evening window, for peak-shifting campaigns.

```python
from openenergyid.evening_peak import EveningPeakAnalyzer

analyzer = EveningPeakAnalyzer(timezone="Europe/Amsterdam")
net_offtake = analyzer.prepare_net_offtake(gross_offtake_lf, gross_injection_lf)
result = analyzer.analyze(net_offtake)
moments = analyzer.peak_moments(net_offtake, num_peaks=10)
```

- Takes the two gross meter registers in kWh per quarter-hour; injection is clipped to zero **per quarter-hour, before summation**, so the share stays in 0–100% and stays comparable between households with and without PV.
- Reports per day the highest quarter-hour power inside the window (kW) and the share of net daily offtake falling inside it (%), plus Monday-aligned weekly medians as a reference line.
- The window (default 16:00–21:00) and the threshold for counting good days (default 37%) are configurable.
- Day boundaries and coverage are DST-aware: a 25-hour October day is expected to have 100 quarter-hours, not 96. Days that are only partly measured report no share rather than one computed against an incomplete denominator, and unmeasured days stay in the index as nulls so a gap in the data reads as a gap.

See `docs/specs/evening-peak-avoidance.md` and `demo_evening_peak.ipynb`.

### Multivariate Linear Regression (MVLR)

The MVLR module helps you build multivariate linear regression models to predict energy consumption.

```python
from openenergyid.mvlr import find_best_mvlr

model = find_best_mvlr(data)
```

### PV Simulation

The PV simulation module helps you simulate the output of a photovoltaic system.

```python
from openenergyid.pvsim import get_simulator, apply_simulation

simulator = get_simulator(input)
simulation_results = simulator.simulate()
df_with_pv = apply_simulation(df, simulation_results)
```

### Simulation Evaluation

The simulation evaluation module helps you evaluate the results of your energy simulations.

```python
from openenergyid.simeval import evaluate

evaluation = evaluate(df)
```
