ETHOS.FINE - Framework for Integrated Energy System Assessment¶

Multi-region, multi-commodity energy system optimization — from a single node to a whole transformation pathway.

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.

ETHOS.FINE is part of the Energy Transformation PatHway Optimization Suite (ETHOS) at ICE-2, where it is used for the modelling of a diverse group of optimization problems. It uses ETHOS.TSAM to reduce the temporal complexity of its models.

ETHOS.FINE was the JuRSE Code of the Month for February 2026.

Features¶

Multiple regions, commodities, time steps and investment periods in one model
Component library covering sources and sinks, conversion, storage and transmission
Cost-optimal design and operation against technical and environmental constraints
Temporal complexity reduction via typical periods, including an interconnected storage formulation
Spatial and technology aggregation to cut model size
Transformation pathways with perfect foresight, stochastic optimization and partload behaviour
Model setup from Excel and reproducible storage of inputs and results as netCDF

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 prerequisites for the installation are presented. Then the recommended installation is shown. If you want to work on the source code of ETHOS.FINE, see Development installation.

Prerequisites¶

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 don't 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 (Recommended)¶

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, HiGHS and 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 HiGHS (which is slower than GUROBI but faster than GLPK) or GLPK, which do not require paid licences.

Conda Solver Installation¶

The Conda installation of ETHOS.FINE comes with GUROBI, HiGHS and 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.

Development installation¶

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]

Getting Started¶

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_District_Optimization
In this application, a small district is modeled and optimized. This example also includes binary decision variables.
05_Water_Supply_System
The application cases of ETHOS.FINE are not limited. This application shows how to model the water supply system.
06_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.
07_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.
08_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.
09_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.
10_Partload
In this application, a hydrogen system is modeled and optimized considering partload behavior of the electrolyzer.

Citation¶

If you want to use ETHOS.FINE in a published work, please kindly cite:

Klütz, T., Knosala, K., Behrens, J., Maier, R., Hoffmann, M., Pflugradt, N., & Stolten, D. (2025). ETHOS.FINE: A Framework for Integrated Energy System Assessment. Journal of Open Source Software, 10(105), 6274. https://doi.org/10.21105/joss.06274

@article{Kluetz2025,
  title   = {{ETHOS.FINE}: A Framework for Integrated Energy System Assessment},
  author  = {Kl{\"u}tz, Theresa and Knosala, Kevin and Behrens, Johannes and Maier, Rachel and Hoffmann, Maximilian and Pflugradt, Noah and Stolten, Detlef},
  journal = {Journal of Open Source Software},
  volume  = {10},
  number  = {105},
  pages   = {6274},
  year    = {2025},
  doi     = {10.21105/joss.06274}
}

Contributions and Support¶

All 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.

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

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

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, 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.

Acknowledgments¶

This work received primary support from the Helmholtz Association through the Joint Initiative "Energy System 2050: A Contribution of the Research Field Energy" and the program "Energy System Design".

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).