EnergyDataModel

<div align="center"> <img height="80" src="https://github.com/rebase-energy/EnergyDataModel/blob/main/assets/logo-energydatamodel.png?raw=true" alt="EnergyDataModel"/> <h2 style="margin-top: 0px;"> 🔋 Represent energy systems as Python data classes for improved modularity and readability </h2> </div> <p align="center"> <a href="https://opensource.org/licenses/MIT"> <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green.svg"> </a> <a href="https://pypi.org/project/energydatamodel/"> <img alt="PyPI version" src="https://img.shields.io/pypi/v/energydatamodel.svg?color=blue"> </a> <a href="https://dub.sh/yTqMriJ"> <img alt="Join us on Slack" src="https://img.shields.io/badge/Join%20us%20on%20Slack-%234A154B?style=flat&logo=slack&logoColor=white"> </a> <a href="#contributors"> <img alt="All Contributors" src="https://img.shields.io/github/all-contributors/rebase-energy/EnergyDataModel?color=2b2292&style=flat-square"> </a> <a href="https://github.com/rebase-energy/EnergyDataModel"> <img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/rebase-energy/EnergyDataModel?style=social"> </a> </p>

EnergyDataModel provides an open-source, Python-based data model that enables energy data scientists and modellers to write more modular and readable code. EnergyDataModel lets you:

• 🧱 Modularity - Represent energy assets, energy systems and other relevant concepts as object-oriented building blocks;
• 🏗️ Relationships - Structure your energy assets in graphs and hierarchies representing energy systems that can be serialized to files (e.g. .csv, .json, and .geojson files);
• 👀 Visualization - Visualise energy systems maps, graphs, flows and structure using built-in plotting functions;
• 🤓 Readability - Write more explicit Python code through human-readable expressions and built-in convenience methods;
• 🧩 Interoperability - Convert data format to other energy-relevant data models and ontologies; and
• 💬 Communicate - Communicate effectively in teams with a common energy system data vocabulary.

⬇️ Installation  |  📖 Documentation  |  🚀 Try out now in Colab  |  👋 Join Slack Community

Modules and Data Classes

EnergyDataModel leverages Python's Data Classes to represent energy assets as Python objects. The table below gives a summary of the available modules and data classes.

| Module | Data Classes | | :---- | :---- | | 🗺️ geospatial | GeoLocation, GeoLine, GeoPolygon, GeoMultiPolygon, GeoGraph | | 📈 timeseries | ElectricityDemand, ElectricitySupply, HeatingDemand, HeatingSupply, ElectricityPrice, CarbonIntensity, | | ☀️ solar | FixedMount, SingleAxisTrackerMount, PVArray, PVSystem, SolarPowerArea | | 🌬️ wind | WindTurbine, WindFarm, WindPowerArea | | 🔋 battery | Battery | | 💦 hydro | Reservoir, HydroTurbine, HydroPowerPlant | | ♻️ heatpump | HeatPump | | ⚡ powergrid | Carrier, Bus, Line, Transformer, Link, SubNetwork, Network, |

Explore the data model visually here.
Read the full documentation here.

Purpose and Philosphy

The aim of EnergyDataModel is to provide the energy data and modelling community with a Python-based open-source tool to enable improvement of software engineering aspects like code quality, maintainability, modularity, reusability and interoperability. We believe that bringing more rigorous software engineering practices to the energy data community has the potential to radically improve productivity, collaboration and usefulness of software tools, utimately leading to better energy decisions.

Our philosophy is aligned on usefulness and practicality over maximizing execution performance or some kind of esoteric theoretical rigor. A well-know quote by Abelson & Sussman comes to mind:

"Programs [software] are meant to be read by humans and only incidentally for computers to execute"

Making code explicit, readable and intuitive counts.

If you are interested in joining our mission to build open-source tools that improve productiveness and workflow of energy modellers worldwide - then join our Slack!

Basic usage

Create an energy system made up of two sites with co-located solar, wind and batteries and save as a JSON-file.

import energydatamodel as edm

pvsystem_1 = edm.PVSystem(capacity=2400, surface_azimuth=180, surface_tilt=25)
windturbine_1 = edm.WindTurbine(capacity=3200, hub_height=120, rotor_diameter=100)
battery_1 = edm.Battery(storage_capacity=1000, min_soc=150, max_charge=500, max_discharge=500)

site_1 = edm.Site(assets=[pvsystem_1, windturbine_1, battery_1],
                  latitude=46, 
                  longitude=64)

pvsystem_2 = edm.PVSystem(capacity=2400, surface_azimuth=180, surface_tilt=25)
windturbine_2 = edm.WindTurbine(capacity=3200, hub_height=120, rotor_diameter=100)
battery_2 = edm.Battery(storage_capacity=1000, min_soc=150, max_charge=500, max_discharge=500)

site_2 = edm.Site(assets=[pvsystem_2, windturbine_2, battery_2],
                  latitude=51, 
                  longitude=58)

portfolio = edm.Portfolio(sites=[site_1, site_2])

portfolio.to_json()

For more examples on usage and applications of EnergyDataModel see the documentation examples page here.

Installation

We recommend installing using a virtual environment like venv, poetry or uv.

Install the stable release:

pip install energydatamodel

Install the latest release:

pip install git+https://github.com/rebase-energy/EnergyDataModel.git

Install in editable mode for development:

git clone https://github.com/rebase-energy/EnergyDataModel.git
cd EnergyDataModel
pip install -e .[dev] 

Ways to Contribute

We welcome contributions from