Metadata-Version: 2.4
Name: ehubx
Version: 2.3.0
Summary: A Python framework for modeling and optimizing energy systems based on the energy hub concept
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: energy systems,energy hub,optimization,mathematical optimization
Author: Dennis Beermann
Maintainer: Urban Energy Systems Laboratory, Empa
Requires-Python: >=3.11,<3.14
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: Pyomo (>=6.8,<7.0)
Requires-Dist: gurobipy (>=11,<12) ; python_version < "3.13"
Requires-Dist: gurobipy (>=12,<13) ; python_version >= "3.13"
Requires-Dist: matplotlib (>=3.9,<4.0)
Requires-Dist: numpy (>=2.3.1,<3.0.0)
Requires-Dist: pandas (>=2.2,<3.0)
Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
Requires-Dist: scipy (>=1.16.0,<2.0.0)
Requires-Dist: tsam (>=2.0,<3.0)
Project-URL: Repository, https://github.com/uesl-empa/ehubx
Description-Content-Type: text/markdown

# ehubX

[![CI](https://github.com/uesl-empa/ehubx/actions/workflows/ci.yml/badge.svg)](https://github.com/uesl-empa/ehubx/actions/workflows/ci.yml)
[![Documentation Status](https://readthedocs.org/projects/ehubx/badge/?version=latest)](https://ehubx.readthedocs.io/)
![License](https://img.shields.io/badge/license-GPLv3-blue.svg)
![Python](https://img.shields.io/badge/python-3.11%2B-blue)

ehubX is a Python framework for optimization-based energy system modeling developed by the [Urban Energy Systems Laboratory at Empa](https://www.empa.ch/web/s313). It has been applied in numerous large-scale energy system analyses for both scientific research and municipal planning projects.

Energy system models are defined through a combination of YAML configuration files and CSV input data. ehubX translates these inputs into Mixed-Integer Linear Programming (MILP) models that can be solved using a variety of external optimization solvers.

Its modular architecture supports a wide range of modeling capabilities, including:

- Energy imports, exports, demands, load shedding, and load shifting
- Storage, conversion, solar, wind, and electromobility technologies
- Energy network modeling and transfer
- Multi-stage, multi-hub, and multi-objective optimization
- Single- and multi-objective optimization with objectives such as costs, emissions, and self-sufficiency

## Installation

We recommend setting up **ehubX** in a dedicated Python virtual environment to avoid conflicts with other packages. The step-by-step guide below is formulated using [conda](https://docs.conda.io/en/latest/) but can be adapted for other package managers or a manual setup. Similarly, we use [poetry](https://python-poetry.org/) for dependency management, which can be replaced with [pip](https://pip.pypa.io/en/stable/) if preferred.

Since ehubX relies on external MILP solvers, additionally ensure that you have a compatible solver installed and properly configured in your environment (see *Specify solver* in the documentation).

### Steps

1. **Clone the ehubX repository.**

2. **Create a new virtual environment:**

   ```
   conda create -n ehubx python=PYTHON_VERSION
   ```

Make sure that the ``PYTHON_VERSION`` you choose is a compatible with the current version of ehubX (see *pyproject.toml* in the root directory).

3. **Activate the environment:**

    ```
    conda activate ehubx
    ```

4. **Install [poetry](https://python-poetry.org/) for dependency management**:

    ```
    conda install -c conda-forge poetry
    ```

5. Navigate to the cloned ehubX directory and install using poetry:

    ```
    cd PATH_TO_EHUBX_REPO
    poetry install
    ```

6. Run any of the main scripts in the examples folder to verify the installation.

## Documentation

The complete documentation is available at:

**https://ehubx.readthedocs.io/**

## Examples

The ``examples`` directory contains demo projects that give an impression on how to work with ehubX models. The most academic example and a good place to start is the *small_demo*.

## How to cite

TODO

## License 

Copyright (C) 2026 Urban Energy Systems Laboratory, Empa.

This project is licensed under the GNU General Public License v3.0 or later.
See the ``LICENSE`` file for details.
