ETHOS.FINE - Framework for Integrated Energy System Assessment

The ETHOS.FINE python package provides a framework for modeling, optimizing and assessing energy systems. With the provided framework, systems with multiple regions, commodities, time steps and investment periods can be modeled. Target of the optimization is the minimization of the systems net present value (NPV) while considering technical and environmental constraints. If only one investment period is considered, the net present value is equal to the total annual costs (TAC). Besides using the full temporal resolution, an interconnected typical period storage formulation can be applied, that reduces the complexity and computational time of the model.

This Readme provides information on the installation of the package. For further information have a look at the documentation.

ETHOS.FINE is used for the modelling of a diverse group of optimization problems within the Energy Transformation PatHway Optimization Suite (ETHOS) at ICE-2.

If you want to use ETHOS.FINE in a published work, please kindly cite following publication. The python package which provides the time series aggregation module and its corresponding literature can be found here.

Installation

There are several options for the installation of ETHOS.FINE. You can install it via PyPI or from conda-forge. In all of the following variants it is recommended to install your dependencies from conda-forge as the ecosystem is better tested and maintained. For more information on installation specifics and comparison between the different options, have a look at the installation documentation. In the following first the preqrequisites for the installation are presented. Then the recommended [installation](#Installation from conda-forge (Recomended)) is shown. If you want to work on the source code of FINE, see Editable install from conda-forge.

Preqrequisites

You either need a mamba or conda installation (recommended), but any Python installation will do. However, if you are unfamiliar with using environment manager (like mamba), you should consider using one. Fine has many dependencies and will likely interfere with other software projects on your machine in case you dont isolate them with an environment

You need conda or mamba installer on your machine, which are mostly interchangeable. The code is tested for Linux, Windows and Macos. We recommend to use mamba and install it using the miniforge installer. Please be aware that having multiple conda and mamba installation (for example from the miniforge installer and the anaconda installer) can cause serious problems during the installation. Please remove the other installer and any old environment on your machine if you decide to switch.

Installation from conda-forge (Recomended)

mamba create --name fine_env --channel conda-forge fine

Installation from PyPI

Create venv environment

python -m venv .venv

Activate venv environment on Linux

source .venv/bin/activate

Activate venv environment on Windows

.venv\Scripts\activate

Find more information on creating virtual environments with venv here.

python -m pip install fine

Solver

At its core, ETHOS.FINE creates an optimisation problem via the Pyomo interface. A Mixed Integer Linear Programming (MILP) solver is required, and theoretically any solver supported by Pyomo can be used with ETHOS.FINE. ETHOS.FINE is tested with GUROBI and with GLPK preinstalled. If you want to solve large problems, it is highly recommended that you use GUROBI due to its superior performance. However, a proprietary licence is required to use GUROBI for larger optimisation problems, but this is available free of charge to academics. See the installation documentation for full details. If you do not want or cannot use a GUROBI licence, you can use the GLPK solver, which does not require an additional licence.

Conda Solver Installation

The Conda installation of ETHOS.FINE comes with GUROBI and with GLPK preinstalled.

PyPi Solver Installation

If you use the PyPi installation, it comes with a reduced version of Pyomo called 'GurobiPy'. However, if you require the full Gurobi software or another solver, please check the solver provider's homepage. Alternatively, consider using Conda/Mamba.

Examples

A number of examples shows the capabilities of ETHOS.FINE.

• 00_Tutorial
  • In this application, an energy supply system, consisting of two regions, is modeled and optimized. Recommended as starting point to get to know to ETHOS.FINE.
• 01_1node_Energy_System_Workflow
  • In this application, a single region energy system is modeled and optimized. The system includes only a few technologies.
• 02_EnergyLand
  • In this application, a single region energy system is modeled and optimized. Compared to the previous examples, this example includes a lot more technologies considered in the system.
• 03_Multi-regional_Energy_System_Workflow
  • In this application, an energy supply system, consisting of eight regions, is modeled and optimized. The example shows how to model multi-regional energy systems. The example also includes a notebook to get to know the optional performance summary. The summary shows how the optimization performed.
• 04_Model_Run_from_Excel
  • ETHOS.FINE can also be run by excel. This example shows how to read and run a model using excel files.
• 05_District_Optimization
  • In this application, a small district is modeled and optimized. This example also includes binary decision variables.
• 06_Water_Supply_System
  • The application cases of ETHOS.FINE are not limited. This application shows how to model the water supply system.
• 07_NetCDF_to_save_and_set_up_model_instance
  • This example shows how to save the input and optimized results of an energy system Model instance to netCDF files to allow reproducibility.
• 08_Spatial_and_technology_aggregation
  • These two examples show how to reduce the model complexity. Model regions can be aggregated to reduce the number of regions (spatial aggregation). Input parameters are automatically adapted. Furthermore, technologies can be aggregated to reduce complexity, e.g. reducing the number of different PV components (technology aggregation). Input parameters are automatically adapted.
• 09_Stochastic_Optimization
  • In this application, a stochastic optimization is performed. It is possible to perform the optimization of an energy system model with different input parameter sets to receive a more robust solution.
• 10_PerfectForesight
  • In this application, a transformation pathway of an energy system is modeled and optimized showing how to handle several investment periods with time-dependent assumptions for costs and operation.
• 11_Partload
  • In this application, a hydrogen system is modeled and optimized considering partload behavior of the electrolyzer.

Notes for developers

Editable install from conda-forge

It is recommended to create a clean environment with conda to use ETHOS.FINE because it requires many dependencies.

mamba env create --name fine_env --file requirements_dev.yml
mamba activate fine_env

Install ETHOS.FINE as editable install and without checking the dependencies from pypi with

python -m pip install --no-deps --editable .

Editable install from pypi

If you do not want to use conda-forge consider the steps in section Installation from PyPI and install ETHOS.FINE as editable install and with developer dependencies with

python -m venv .venv

Activate venv environment on Linux

source .venv/bin/activate

Activate venv environment on Windows

.venv\Scripts\activate

python -m pip install --editable .[develop]

Good coding style

We use ruff to ensure good coding style. Make sure to use it before contributing to the code base with

ruff check --config=pyproject.toml
ruff format --diff --config=pyproject.toml

License

MIT License

Copyright (C) 2016-2025 FZJ-ICE-2

Active Developers: Johannes Behrens, Theresa Klütz, Noah Pflugradt, Julian Belina, Arne Burdack, Toni Busch, Philipp Dunkel, David Franzmann, Maike Gnirß, Thomas Grube, Lars Hadidi, Heidi Heinrichs, Shitab Ishmam, Sebastian Kebrich, Jochen Linßen, Nils Ludwig, Lilly Madeisky, Drin Marmullaku, Gian Müller, Kenneth Okosun, Olalekan Omoyele, Shruthi Patil, Kai Schulze, Julian Schönau, Maximilian Stargardt, Lana Söltzer, Henrik Wenzel, Bernhard Wortmann, Lovindu Wijesinghe, Christoph Winkler, Detlef Stolten

Alumni: Robin Beer, Henrik Büsing, Dilara Caglayan, Patrick Freitag, Maximilian Hoffmann, Jason Hu, Timo Kannengießer, Kevin Knosala, Leander Kotzur, Felix Kullmann, Stefan Kraus, Rachel Maier, Peter Markewitz, Lars Nolting, Jan Priesmann, Stanley Risch, Martin Robinius, Bismark Singh, Andreas Smolenko, Peter Stenzel, Chloi Syranidou, Johannes Thürauf, Lara Welder, Michael Zier

You should have received a copy of the MIT License along with this program. If not, see https://opensource.org/licenses/MIT

Contributions and Support

Every contributions are welcome:

• If you have a question, you can start a Discussion. You will get a response as soon as possible.
• If you want to report a bug, please open an Issue. We will then take care of the issue as soon as possible.
• If you want to contribute with additional features or code improvements, open a Pull request.

About Us

We are the Institute of Climate and Energy Systems – Jülich Systems Analysis (ICE-2) at the Forschungszentrum Jülich. Our work focuses on independent, interdisciplinary research in energy, the bioeconomy, infrastructure, and sustainability. We support a just, greenhouse gas–neutral transformation through open models and policy-relevant science.

Code of Conduct

Please respect our code of conduct.

Acknowledgement

This work was initially supported by the Helmholtz Association under the Joint Initiative "Energy System 2050 A Contribution of the Research Field Energy".

The authors also gratefully acknowledge financial support by the Federal Ministry for Economic Affairs and Energy of Germany as part of the project METIS (project number 03ET4064, 2018-2022).

This work was supported by the Helmholtz Association under the program "Energy System Design".