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

pip install breos

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.

Start with a task

Run your first simulation

Verify the install, run a small PV + battery study, and inspect its headline results.

Quickstart

Configure a study

Choose the location, PV layout, battery, economics, emissions, and model options.

Configuration

Bring your own data

Use project weather, load profiles, component data, and financial assumptions.

Required Inputs

Understand the result

Read the energy, financial, emissions, degradation, and provenance fields.

Interpreting results

Browse the documentation

Guides and recipes

Task-oriented guides for common systems, inputs, configuration, and troubleshooting.

Guides and recipes

Models and assumptions

Physical boundaries, model choices, data sources, and degradation methods.

Models, assumptions, and data

Python API

The stable breos.App facade and lower-level functions organized by domain.

API reference

Status

BREOS is pre-1.0 (beta), so the public API may change between minor releases. The breos.App facade is the most stable surface to build on. Use the version selector to read the docs matching your installation: stable follows the latest published release, while latest follows active development. The documentation describes implemented behavior rather than proposed designs.

Project direction

The public roadmap shows release intent and larger capabilities under consideration. Detailed implementation plans, ADRs, and maintainer procedures live in the repository rather than on this user-documentation site.