BREOS

BREOS

Building Renewable Energy Optimization Software

A Python library for PV and battery energy-system simulation and optimization, designed for research and engineering applications.

Quick example

import breos

app = breos.App({
    "location": "porto",
    "n_modules": 10,
    "annual_consumption_kwh": 4000,
    "battery_kwh": 5.0,
    "cost_preset": "residential_pt",
    "emissions_country": "PT",
})
app.simulate()
result = app.result()

print(f"Grid independence: {result['grid_independence_pct']:.1f}%")
print(f"Payback: {result['payback_year']} years")
print(f"NPV savings: {result['npv_savings_eur']:,.0f} EUR")

result is a plain JSON-serializable dict — no pandas types leak out.

Where to start

Getting started

Install BREOS, run a first simulation, and learn what every key in the result dict means.

Getting started

API reference

Stable facade guidance and lower-level module reference, organized by what each piece does — weather, PV, battery, costs, and so on.

API reference

Architecture

Design decisions and refactoring plans for BREOS’s internal structure.

Third-Party Module Wrapping

Status

BREOS is pre-1.0 (current release 0.3.3, beta). The public API may change between minor releases. The roadmap tracks larger refactoring work — notably, the planned adapter layer for third-party libraries will change the signatures of calculate_pv_production_dc and similar functions that currently expose pvlib.Location directly. The breos.App facade is the most stable surface to build on.