BREOS - Building Renewable Energy Optimization Software

BREOS is a Python library for simulating and optimizing PV + battery energy systems (weather, PV production, battery aging, economics, emissions, and multi-objective sizing) behind one stable breos.App facade, with lower-level modules for building custom study pipelines. The PV modeling is powered by pvlib python, which supplies the solar position, irradiance, cell-temperature, and single-diode physics BREOS builds its production pipeline on.

📖 Full documentation: breos.readthedocs.io

Features

• Weather: TMY from PVGIS, local weather files, and historical data from Open-Meteo at hourly or 15-minute resolution.
• PV production — pvlib CEC single-diode model, with a small example module catalog to get started.
• Multi-array systems — combine multiple faces/orientations (e.g. an east-west roof) at the DC stage instead of one representative tilt.
• Battery — energy balance with calendar + cycle aging (Naumann 2020, Lam 2025) and field-calibrated LFP parameters, or one of 14 vendored BLAST-Lite aging models.
• Battery control — greedy self-consumption by default; opt-in fixed-target grid charging and discharge-only windows under time-of-use prices.
• Economics — NPV, LCOE, breakeven, and cost projections with flat or time-of-use tariffs, a separate tariff for the no-system baseline, and separate price escalators.
• Monte Carlo — weather-year and demand resampling for NPV, payback, grid-independence, LCOE, and SoH distributions.
• Optimization — multi-objective PV/battery sizing and orientation (pymoo NSGA-II), and parameter-grid sweeps.
• Emissions — CO₂ savings and projections.
• Visualization — plots for energy balances, degradation, breakeven, Monte Carlo distributions, sweep heatmaps, orientation landscapes and Pareto fronts.
• Bring your own data — every layer accepts custom inputs: PV module parameters, battery degradation coefficients, weather CSVs, load profiles, and cost/tariff/emissions assumptions. The packaged presets are starting points, not fixed defaults.

Installation

pip install breos

Or with uv:

uv add breos          # as a project dependency
uvx breos --version   # run the CLI without installing

Verify the installation and inspect a complete resolved configuration without creating a file, fetching weather, or running a simulation:

breos run --location porto --n-modules 10 \
  --annual-consumption-kwh 4000 --dry-run

The default install is a lean core. Some workflows need optional extras (e.g. optimization, historical weather, plots):

pip install "breos[optimization,weather,plots]"

See the installation guide for the full list of extras and a source/uv setup.

Quick Start

import breos

app = breos.App({
    "location": "porto",              # preset or {"latitude": ..., "longitude": ..., "timezone": ...}
    "n_modules": 10,
    "annual_consumption_kwh": 4000,
    "battery_kwh": 5.0,               # 0 for no battery
    "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']:,.0f} EUR")

result() returns a plain JSON-serializable dict. Money fields are in the currency recorded in result["provenance"]["currency"] (EUR for the bundled cost presets). The configuration reference lists every option, and interpreting results documents every output field.

For real studies, bring your own weather and API access where required, licensed load profiles, and your own cost/tariff assumptions. The packaged defaults make the tool runnable, not project-grade.

Command Line

Run a simulation without writing Python:

breos run --location porto --n-modules 10 --annual-consumption-kwh 4000 \
  --battery-kwh 5.0 --cost-preset residential-pt --emissions-country pt \
  --output result.json

The CLI also drives config files, parameter sweeps, and Monte Carlo studies, and breos list <category> shows bundled presets (locations, modules, cost presets, …). See the how-to guides and the case examples.

Citation

If you use BREOS in your research, please cite the software and the version you used. GitHub's "Cite this repository" button reads the metadata in CITATION.cff, or use:

@software{rodrigues_breos,
  author = {Rodrigues, Leonardo},
  title  = {{BREOS}: Building Renewable Energy Optimization Software},
  url    = {https://github.com/Str4vinci/breos},
  note   = {Version X.Y.Z}
}

BREOS results that depend on PV production also depend on pvlib. Please cite it alongside BREOS:

@article{anderson2023pvlib,
  author  = {Anderson, K. and Hansen, C. and Holmgren, W. and Jensen, A. and Mikofski, M. and Driesse, A.},
  title   = {pvlib python: 2023 project update},
  journal = {Journal of Open Source Software},
  volume  = {8},
  number  = {92},
  pages   = {5994},
  year    = {2023},
  doi     = {10.21105/joss.05994}
}

pvlib additionally asks that you cite the Zenodo DOI for the specific pvlib version you used.

Acknowledgements

BREOS stands on work done by others:

• pvlib python — the PV modeling foundation: solar position, irradiance transposition, IAM, cell temperature, CEC single-diode evaluation, PVWatts losses, tracking, and inverter helpers. BREOS composes these into a production pipeline with staged losses, degradation, and multi-array handling; the underlying physics is pvlib's.
• BLAST-Lite (NREL) — vendored battery life models.
• demandlib — basis for the bundled example H0 load profiles.
• pymoo — NSGA-II multi-objective optimization.
• PVGIS (EU JRC) and Open-Meteo: weather and solar resource data.

Model choices, defaults, and any errors in how these are combined are BREOS's own, not those of the upstream projects. See ATTRIBUTIONS.md for the full list with licenses and terms.

Contributing

See CONTRIBUTING.md. Feature work happens on branches off develop and merges via pull request; main tracks stable releases only.

Contact

Usage questions and feature ideas: GitHub Discussions. Bugs: issues. Research collaboration or private enquiries: lrodrigues@fe.up.pt.

License

BSD 3-Clause. See LICENSE.