<!-- markdownlint-disable line-length no-inline-html -->

ETHOS.FINE - Framework for Integrated Energy System Assessment

<table style="border:0; border-collapse:collapse;"> <tr> <td style="border:0;"> <img src="./docs/fine_logo_v19_no_overlap.svg" alt="ETHOS.FINE logo" width="180px"> </td> <td style="border:0;"> <a href="https://www.fz-juelich.de/en/ice/ice-2"><img src="https://github.com/FZJ-IEK3-VSA/README_assets/blob/main/JSA-Header.svg?raw=True" alt="Logo für Forschungszentrum Juelich - Juelich System Analysis" width="300px"></a> </td> </tr> </table>

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 po