pyESDL

pyESDL is a library for using ESDL in python programs. ESDL stands for Energy System Description Language and is created to support developers creating, parsing, generating ESDL-files with the goal to create interoperable energy system transition tooling.

This package contains all the ESDL classes of the ESDL language and an EnergySystemHandler that helps the developer to read and write ESDL-files.

The PyESDL documentation can be found here: https://pyesdl.readthedocs.io/

More information about ESDL can be found at:

1. ESDL gitbook documentation with a general introduction, example applications and some code samples.
2. ESDL Model Reference documentation that describes all the classes and definitions in detail using a clickable UML diagram.

Support functions:

PyESDL now comes with a lot of support functions for:

• handling profiles:
  • ProfileManager: reading profiles from a CSV, converting to and from esdl.DateTimeProfile or esdl.TimeSeriesProfile.
  • ExcelProfileManager: reading from and writing profiles to Excel files
  • InfluxDBProfileManager: reading from and writong profiles to InfluxDB (version 1.7)
• handling geometries: conversion to and from esdl geometries, WKT, WKB, GeoJSON, ...
• qunatity and units: unit conversion, converting a QuantityAndUnit to a string, building a QuantityAndUnit from a string

Installing

PyESDL now comes with a lot of support functions for handling profiles, geometries and qunatity and units. This requires additional dependencies. As not all users might need all functionalities, there are several ways to install pyESDL.

Use the following command to install the pyESDL python module including all dependencies from the PyPi registry:

pip install pyESDL[all]

To install the minimal version of pyESDL:

pip install pyESDL

To install the dependencies for additional profile functionalities (only required for support for Excel and InfluxDB):

pip install pyESDL[profiles]

To install the dependencies for handling geometries:

pip install pyESDL[geometry]

Documentation

We will start soon with generating more documentation on readthedocs.

Usage

Example 1 - Creating an ESDL-file and saving it to disk

from esdl.esdl_handler import EnergySystemHandler
from esdl import esdl

esh = EnergySystemHandler()
es = esh.create_empty_energy_system(
    name="ES1", es_description="Nice Energy System", inst_title="instance 1", area_title="Area 51"
)
print(es)
esh.save(filename="test.esdl")

Example 2 - Loading an ESDL file and adding a WindTurbine to an area

from esdl.esdl_handler import EnergySystemHandler
from esdl import esdl
from pprint import pprint

esh = EnergySystemHandler()
# load an ESDL file and use type hinting to help the IDE to do auto completion
es: esdl.EnergySystem = esh.load_file("test.esdl")
print(es)
# Create a WindTurbine
wind_turbine = esdl.WindTurbine(
    name="WindTurbine at coast", rotorDiameter=50.0, height=100.0, type=esdl.WindTurbineTypeEnum.WIND_ON_COAST
)

# print the wind turbines properties in ESDL as a dict
pprint(esh.attr_to_dict(wind_turbine))

# Get the area where this windturbine should be added
area51: esdl.Area = es.instance[0].area
# add the WindTurbine to the area
area51.asset.append(wind_turbine)
# save the file
esh.save()

# Give the WindTurbine a location on the map
location = esdl.Point(lat=52.6030475337285, lon=4.729614257812501)
wind_turbine.geometry = location

esh.save()
# Convert the Energy System to an XML string and print it
xml_string = esh.to_string()
print(xml_string)

Example 3 - Creating a project with inherited variants

Add a pipe as a tracked change, create a child variant that inherits it, then save and reload the project.

from esdl import esdl
from esdl.project.ProjectManager import ProjectManager
from esdl.project.variant_api import create_new_variant

# Create a project with an empty energy system
pm = ProjectManager()
stack = pm.get_undo_redo_stack()
# Add a pipe as a tracked change
with stack.track_changes("Add pipe"):
    pipe = esdl.Pipe(id="pipe", name="Pipe")
    pm.get_active_energy_system().instance[0].area.asset.append(pipe)

change = pm.get_active_variant().change[0]
print(change.label)  # Add pipe

# Create and activate a child variant that inherits the pipe
child = create_new_variant(pm.active_variant, "Child variant")
pm.set_active_variant(child)
print(pm.get_active_energy_system().instance[0].area.asset[0].name)  # Pipe

# Save and reload the project, then activate the child variant
loaded_pm = ProjectManager()
loaded_pm.load_from_string(pm.save())
loaded_pm.set_active_variant(loaded_pm.get_variant_by_id(child.id))
print(loaded_pm.get_active_variant().name)  # Child variant

Converting ESDL units

Example:

from esdl.units.conversion import convert_to_unit, ENERGY_IN_J, ENERGY_IN_MWh

converted = convert_to_unit(5, ENERGY_IN_MWh, ENERGY_IN_J)
18E9 == converted
>> True

Creating QuantityAndUnitTypes from strings is also possible using build_qau_from_unit_string(). E.g. build_qau_from_unit_string("TWh", 'Energy') will give you "Energy in TWh" as unit.

Changes

Version 26.10.2

• Fix PyProj dependency compatibility for geometry and all installations on Python 3.10
• Declare Requests, lxml and ordered-set as core dependencies
• Allow dependency patch updates while keeping PyEcore, Shapely and GeoJSON pinned
• Remove the redundant Psycopg binary dependency
• Test core, profiles, geometry and all installations from built wheels on Python 3.10 through 3.14
• Replace live EDR requests in tests with mocked responses
• Remove GitLab CI configuration

Version 26.10.1

• Improved datetime parsing
• Improved copy functionality and range attribute fixes
• Add project management with variants and undo/redo tracking
• Require Python 3.10 or newer
• Update PyEcore to 0.15.2
• Bundle the ESDL metamodel for offline documentation generation
• Add configurable request timeouts to the EDR client
• Fix shared default properties in GeoJSON features
• Fix quoting of PostgreSQL column names
• Fix sample counts when loading PostgreSQL profiles
• Fix PostgreSQL profile loading when quantity and unit metadata is missing
• Fix PostgreSQL metadata error logging and propagate write failures
• Add GitHub Actions testing for Python 3.10 through 3.14 and PyPI Trusted Publishing

Version 26.10

• Updated EnergyDataDescription (EDD) schema

Version 26.9

• Add support for ESDL release 26.9
• Implement support for MultiPolygons

Version 26.7.1

• Fix bug in the profile util function

Version 26.7

• Fix bug in writing postgres profile data

Version 26.6.1

• Fix missing files for automatic ESDL version migration

Version 26.6

• Add support for ESDL release 26.6
• Implement automatic ESDL version migration mappings on loading ESDL files with older ESDL formats

Version 26.5

• Add support for ESDL release 26.5
• Add general profile parsing and adding/writing to database functions, including profile data caching
• Add automated testing with postgres/influxdb databases

Version 26.4.1

• Fix bug of table index creation error in postgresql configuration
• Add initial support for loading DataTableProfile data with profiles stored in InfluxDB database using DataTableProfileManager
• Extend coding examples of DataTableProfile in the readthedocs documentation

Version 26.4

• Updated python dependencies for geometry and profiles functionalities (Python 3.10, 3.11, 3.12, 3.13, 3.14)

Version 26.3.1

• Update readthedocs documentation related to DataTableProfileManager API and a coding example of assigning and querying a profile with DataTableProfile

Version 26.3

• Add support for ESDL release 26.3
• Add initial support for new DataTableProfiles using the DataTableProfileManager with a postgres backend. Allows to easily store CSV/Excel files in postgres and add these profiles to an ESDL

Version 26.2

• Add support for ESDL release 26.2

Version 25.12

• Add functions to create QuantityAndUnit objects
• Add unit conversion from gram to tonne and vice versa (e.g. kg to Mt)
• Support setting PhysicalQuantity when using build_qau_from_unit_string(), e.g. build_qau_from_unit_string("TWh", 'Energy')

Version 25.7

• Add support for ESDL release 25.7
• Small bugfix in generating a QuantityAndUnitType instance from a string
• Fix bug in unit conversion when physical quantities are not the same

Version 25.5.2

• Fix bug in unit conversion when physical quantities are not the same

Version 25.5.1

• Add support for ESDL release 25.5.1

Version 25.5

• Add support for ESDL release 25.5

Version 25.2

• Add support for ESDL release 25.2

Version 24.11.2

• Add link to documentation of pyESDL on readthedocs
• Fix geojson dependency

Version 24.11.1

• Downgrade pyEcore to 0.13.2 again, due to error with rows in tables

Version 24.11

• Update build system and dependencies
• Fix wrong import in support_functions on Python > 3.12
• Update pyEcore to 0.15.1

Version 24.9

• Add support for ESDL release 24.09
• Upgrade shapely and geojson versions

Version 24.2

• Fix bug when no tags are given for an InfluxDBProfile
• Fix issue with multi-valued attribute values (such as values in TableRow)
• Start with the ReadTheDocs documentation

Version 24.1

• Add support for ESDL release 24.01

Version 23.12.1

• Fix bug in ProfileManager
• InfluxDBProfileManager.load_influxdb now returns an esdl.InfluxDBProfile
• InfluxDBProfileManager: improved handling of situations where no data is returned

Version 23.12

• Bug fixes in InfluxDBProfileManager

Version 23.11.2

• Add support for ESDL release 23.11 (with powerCurveTable for WindTurbine)

Version 23.11.1

• Fix bug in determining the end_datetime of profiles

Version 23.11

• Implement EDR client
• Added more predefined QaUs
• Support for tags in InfluxDBProfileManager

Version 23.10.1

• Implement set_profile function
• Corrected some bugs (datetime_utils missing, support for fields with '-')

Version 23.10

• Add support functions for handling profiles, geometries and qunatity and units.

Version 23.03

• Add support for ESDL release 23.03 (added 2 PowerPlant types, referenceYear for CostInformation, added fullLoadHours and operationalHours attributes to Consumer and Transport classes)

Version 22.11.1

• Add support for ESDL release 22.11 (with KPI-KPI and Sector-Sector relation, ElectricBoiler, PowerPlant types, ...)

Version 22.11

• Add support for Energy Data Repository files (*.edd)
• Add supoprt for linking to external files (e.g. stored in the EDR) using get_external_reference(url, object_id)
• Add function to instantiate a class by its class name (instantiate_esdltype(className))

Version 22.10.0

• Add support for ESDL release 22.10 (with Port-Constraint relation, support for modelling material flows, added powerFactor attribute for electricity related assets, DataSourceList)

Version 22.7.0

• Add support for ESDL release 22.07 (with ConnectableAsset, ExposedPortsAsset, PumpedHydroPower and CAES assets, restructured some LabelJump information, asset Constraints)

Version 21.12.0

• Add support for ESDL release 21.12 (with quantity and unit information for InputOutputRelation, renaming of some distribution information classes of AggregatedBuildings)

Version 21.11.0

• Add support for ESDL release 21.11 (with HybridHeatpump, developmentCosts, Commodity emission attribute)

Version 21.10.0

• Add support for ESDL release 21.10 (with storage volumes)

Version 21.9.1

• Add support for ESDL release 21.9 (with pipe and cable relations)

Version 21.9.0

• Fix pyecore 0.12.1 dependency issue

Version 21.7.1

• Add support for ESDL release 21.7 (with BufferDistance, ATES)

Version 21.6.2

• Fix issue with version definition, making the EnergySystemHandler unusable.

• Add get_all_instances_of_type() to EnergySystemHandler to retrieve all the instances of a certain type in an EnergySystem.

  E.g. esh.get_all_instances_of_type(esdl.GenericProfile) will give you all the profiles defined in the EnergySystem.

Version 21.6.1

• Add support for InputOutputRelation

Releasing

The release process is as follows:

1. Do a git tag with the new version number
2. Do python setup.py sdist bdist_wheel to create the tarball and wheel in the dist folder
3. upload to PyPi: python3 -m twine upload --repository pyESDL dist/*