openenergy 4.2.0

OpenEnergy

Backtest battery storage against real power-market prices.

Documentation · Issues

What it does

Describe a battery and a forecasting approach in a short YAML file. OpenEnergy plans each day on the forecast, settles the plan at the prices that actually cleared, and reports what the battery earned, how hard it worked, and how close it came to perfect foresight.

• Battery physics: power and energy ratings, charge/discharge efficiencies, SOC window, cycle and calendar ageing.
• Dispatch: a daily mixed-integer optimisation solved with HiGHS, optionally planning the following days too (dispatch.lookahead_days; one day adds 5–15% revenue).
• Backtesting without lookahead: forecasts see only data available at the decision time; plans settle at actual prices.
• Revenue stacking: GB Dynamic Containment, Moderation and Regulation co-optimised with day-ahead trading (response in a scenario). Adding Dynamic Containment raised a 2-hour battery's revenue by 58–155% a year in 2022–2025 (examples/gb-2025-stacked.yaml).
• Forecasters: perfect foresight, last week's prices, noisy foresight and a gradient-boosting model.
• Renewables: solar and wind plants from capacity-factor profiles, captured price and capture rate by year (openenergy capture).
• Co-located sites: a plant and a battery behind one grid connection with export and import limits and optional support payments, compared with separate connections.
• System analysis: net load, ramps and renewable surplus as wind and solar scale, storage sizing for the system (openenergy storage) and for a site (openenergy sweep).
• Emissions: net emissions from GB carbon intensity and an optional carbon price that steers dispatch, planned without lookahead.
• GB system model: CCGT, coal and peaking plant dispatched in merit order (optionally with unit commitment) from fleet, fuel and carbon data, checked against 2015–2025 prices and fuel use (openenergy system validate), with scenarios for renewables, storage, fleet and carbon policy (openenergy system run); storage uses the optional PyPSA backend.
• Forward scenarios: NESO's Future Energy Scenarios pathways (2025–2035) applied to a historic weather year, with GB's ten interconnectors trading at neighbouring markets' actual prices up to each link's availability fitted from its flows, and unit commitment (system.fes, system.interconnectors: links, system.commitment).
• Web app: value a battery on any GB year from 2017 or on a FES pathway's modelled prices in the browser at open-energy-eight.vercel.app (openenergy.app, FastAPI on Vercel).
• Data: hourly GB day-ahead prices, demand and wind and solar output for 2015–2020 and capacity factors for 2015–2019 from Open Power System Data; GB hourly day-ahead prices for mid-2016 to October 2026 from Ember; half-hourly GB carbon intensity for 2018 to October 2026 and generation by fuel for 2015–2025 from NESO; GB frequency-response auction prices from September 2021 and monthly response utilisation from NESO; GB imbalance prices for 2016 to October 2026 from Elexon; and GB fleet, fuel and carbon prices from DESNZ, HMRC, the World Bank and the ECB, are bundled. So are NESO's Future Energy Scenarios tables, its interconnector register, daily interconnector flows from Elexon and hourly day-ahead prices in the six neighbouring markets from Ember. openenergy data update downloads the latest prices.
• Reports: openenergy report turns saved runs, system scenarios, backcasts and sweeps into one interactive HTML file of charts and tables (optional report extra, plotly).

Quick start

Requires Python 3.14 and uv. The bundled data come with the repository, so clone it:

git clone https://github.com/koulakhilesh/OpenEnergy.git
cd OpenEnergy
uv sync --extra forecast
uv run openenergy compare examples/gb-2019-{naive,ml,perfect}.yaml

The library and command line are also on PyPI (pip install openenergy, with extras forecast, system, report and app); the package carries no data, and openenergy data update downloads the latest GB prices.

scenario         forecast             days       revenue   per MW-yr   capture   cycles
gb-2019-perfect  perfect_foresight     363        19,075      19,180    100.0%      464
gb-2019-ml       gradient_boosting     363        14,086      14,164     73.8%      400
gb-2019-naive    naive_last_week       363        13,918      13,995     73.0%      465

A 1 MW / 2 MWh battery trading GB day-ahead prices in 2019 would have earned about £14k per MW-year planning on last week's prices: 73% of what perfect foresight allows. In the 2022 gas crisis the same battery would have earned about £77k (examples/gb-2022-naive.yaml, on Ember prices).

Run one scenario and write its results to outputs/<name>/, then chart them:

uv run openenergy run examples/gb-2019-naive.yaml
uv sync --extra report
uv run openenergy report outputs/gb-2019-naive -o outputs/report.html

Rebuild GB prices from the plants behind them and compare with what happened:

uv run openenergy system validate
uv sync --extra system   # PyPSA, needed for scenarios with storage
uv run openenergy system run examples/gb-2019-wind3-storage.yaml
uv run openenergy system run examples/gb-2035-holistic.yaml   # a FES pathway in 2035

Run the web app locally (or use it at open-energy-eight.vercel.app):

uv run uvicorn openenergy.app:app

See the documentation for the equations, every scenario setting and the Python API.

Development

uv sync --all-extras --group docs
uv run ruff check && uv run ruff format --check && uv run mypy && uv run pytest
uv run mkdocs serve

Roadmap

Released

Planned

Alongside releases: a Zenodo DOI and versioned docs; refresh and re-check the bundled data every release; keep CI and its actions current; revisit stochastic planning if an open, forecastable market price appears.

Ideas and bug reports are welcome in issues.

Data

Prices, load and renewable generation come from Open Power System Data:

Open Power System Data. 2020. Data Package Time series. Version 2020-10-06. https://doi.org/10.25832/time_series/2020-10-06. (Primary data from various sources, for a complete list see URL).

GB day-ahead prices after September 2020 come from Ember, European Wholesale Electricity Price Data (primary sources ENTSO-E and EMR Settlement), licensed under CC BY 4.0, and are converted from EUR with European Central Bank reference rates (source: ECB).

GB carbon intensity comes from the National Energy System Operator (NESO) Carbon Intensity API, https://carbonintensity.org.uk/, licensed under CC BY 4.0.

GB generation by fuel comes from NESO's historic generation mix, licensed under the NESO Open Data Licence v1.0. Supported by National Energy SO Open Data.

GB frequency-response clearing prices come from NESO's Dynamic Containment, Regulation and Moderation auction results and EAC auction results, and the energy each service moves is derived from NESO's system frequency data with the delivery envelopes in NESO's Response Services Service Terms; all under the NESO Open Data Licence v1.0, accessed 13 October 2026. Supported by National Energy SO Open Data.

GB imbalance (system) prices come from Elexon's BMRS, reused under the BMRS data licence. Contains BMRS data © Elexon Limited copyright and database right 2026.

Forward scenarios use NESO's Future Energy Scenarios 2025 and 2026 Ten Year Outlook (ES1 and ED1 tables) and its Interconnector Register, under the NESO Open Data Licence v1.0, accessed 13 October 2026; supported by National Energy SO Open Data. Interconnector flows come from Elexon's BMRS (FUELHH), under the same BMRS data licence. Day-ahead prices in France, the Netherlands, Belgium, Norway, Denmark and Ireland come from Ember's European Wholesale Electricity Price Data (primary sources ENTSO-E and SEMOpx), CC BY 4.0, converted with ECB rates.

Fleet capacity and efficiency (DUKES 5.8 and 5.10) and fuel prices (Quarterly Energy Prices 3.2.1) come from the Department for Energy Security and Net Zero, the 2021 UK ETS price from the UK ETS Authority's carbon price determination, and carbon price support rates from HM Revenue & Customs; they contain public sector information licensed under the Open Government Licence v3.0. EU ETS (to 2020) and UK ETS (from 2022) prices come from the World Bank Carbon Pricing Dashboard (CC BY 4.0), converted to GBP with a cross rate OpenEnergy derives from euro reference rates (source: European Central Bank). Unit sizes and minimum loads for unit commitment come from the Danish Energy Agency's Technology Data catalogue (CC BY 4.0), and start-up costs from Kumar et al., Power Plant Cycling Costs, NREL/SR-5500-55433, 2012, Table 1-1 (https://www.osti.gov/biblio/1046269), converted with 2011 ECB rates. All accessed 10 October 2026.

The optional storage backend uses PyPSA (Brown, Hörsch and Schlachtberger, PyPSA: Python for Power System Analysis, Journal of Open Research Software 6(1), 2018, https://doi.org/10.5334/jors.188).

See data/time_series, data/prices, data/carbon_intensity, data/system, data/fes, data/scenarios, data/app, data/response and data/balancing for sources, changes and known issues. OpenEnergy is not affiliated with or endorsed by any data provider.

License

The code is MIT licensed; see LICENSE.txt. The written documentation in docs/ (text, tables and findings) is licensed under CC BY 4.0. Bundled data is not covered by either and keeps its own licence:

Reuse of any of these requires the attribution given in the folder's README.md.

Citing

If you use OpenEnergy, please cite it with the details in CITATION.cff (GitHub's "Cite this repository" button reads it), and credit the data sources each result lists.

Contact

Akhilesh Koul · koulakhilesh@gmail.com · LinkedIn