ETHOS.HiSim - Household Infrastructure and Building Simulator

ETHOS.HiSim is a Python package for simulation and analysis of household scenarios and building systems using modern components as alternative to fossil fuel based ones. This package integrates load profiles generation of electricity consumption, heating demand, electricity generation, and smart strategies of modern components, such as heat pump, battery, electric vehicle or thermal energy storage. ETHOS.HiSim is a package under development by Forschungszentrum Jülich und Hochschule Emden/Leer. For detailed documentation, please access ReadTheDocs of this repository.

Install Graphviz

If you want to use the feature that generates system charts, you need to install GraphViz in your system. If you don't have Graphviz installed, you will experience error messages about a missing dot.exe under Windows.

Follow the installation instructions from here: https://www.graphviz.org/download/

(or simply disable the system charts)

Clone Repository

To clone this repository, enter the following command to your terminal:

git clone https://github.com/FZJ-IEK3-VSA/HiSim.git

Virtual Environment

Before installing ETHOS.Hisim, it is recommended to set up a Python virtual environment. Let hisimvenv be the name of virtual environment to be created. For Windows users, setting the virtual environment in the path \Hisim is done with the command line:

python -m venv hisimvenv

After its creation, the virtual environment can be activated in the same directory:

hisimvenv\Scripts\activate

For Linux/Mac users, the virtual environment is set up and activated as follows:

virtual hisimvenv source hisimvenv/bin/activate

Alternatively, Anaconda can be used to set up and activate the virtual environment:

conda create -n hisimvenv python=3.10
conda activate hisimvenv

With the successful activation, ETHOS.HiSim is ready to be locally installed.

Install Package

After setting up the virtual environment, install the package to your local libraries:

pip install -e .

Optional: Set Environment Variables

Certain components might access APIs to retrieve data. In order to use them, you need to set the url and key as environment variables. This can be done with an .env file wihtin the HiSim root folder or with system tools. The environment variables are:

UTSP_URL
UTSP_API_KEY

Executing a Building Simulation

In ETHOS.HiSim we are calling a specific building configuration a system setup. A system setup encompasses the building itself, all the technical infrastructure and other parameters, such as geographic location, weather, residents, energy prices and many more. You can find the predefined system setups in the directory HiSim/system_setups.

Run Simple System Setups

We provide some simplified examples to show the general principles of the simulation. You can run the simple system setups in the directory HiSim/system_setups with the following command:

python ../hisim/hisim_main.py simple_system_setup_one.scenario.json 2021_minutely_none.simulation.json

or

python ../hisim/hisim_main.py simple_system_setup_two.scenario.json 2021_minutely_none.simulation.json

This command executes hisim_main.py on the scenario configuration given by the first JSON file and the simulation configuration given by the second JSON file. The results can be visualized under directory results created under the same directory where the scenario configuration file is located.

Run Basic Household System Setup

The directory HiSim/system_setups also contains a basic household configuration named basic_household.scenario.json. It can be executed with the following command:

python ../hisim/hisim_main.py basic_household.scenario.json 2021_minutely_plots.simulation.json

The system is set up with the following elements:

• Occupancy (Residents' Demands)
• Weather
• Photovoltaic System
• Building
• Heat Pump

Hence, photovoltaic modules and the heat pump are responsible for covering the electricity and thermal energy demands as best as possible. The components are explicitly connected to each other, binding inputs to their corresponding output sequentially. This is different from automatically connecting inputs and outputs based on similarity. For a better understanding of explicit connection, proceed to section IO Connecting Functions.

Package Structure

The main program is executed from hisim/hisim/hisim_main.py. The Simulator(simulator.py) object groups Components declared and added from the setups functions. The ComponentWrapper (simulator.py) gathers together the Components inside a Simulator object. The Simulator object performs the entire simulation under the function run_all_timesteps and stores the results in a subdirectory of hisim/hisim/results named after the executed setup function.

Plots, KPIs, CSV-files and the PDF-report can be generated by the class PostProcessor (hisim/hisim/postprocessing/postprocessing.py). For this you need to add the respective PostProcessingOptions (hisim/hisim/postprocessingoptions.py) to your SimulationParameters when you are executing your Household System Setup in HiSim/system_setups.

Component Classes

All HiSim component classes are stored in hisim/hisim/components directory and inherent from the parent class Component (hisim/hisim/component.py). They can be used in your setup function to customize different configurations. A Component child class has to have the following methods implemented:

• i_save_state: updates previous state variable with the current state variable
• i_restore_state: updates current state variable with the previous state variable
• i_simulate: performs a timestep iteration for the Component
• i_doublecheck: checks if the values are expected throughout the iteration

These methods are used by Simulator to execute the simulation and generate the results.

List of Component Children

Theses classes inherent from Component (component.py) class and can be used in your setup function to customize different configurations. All Component class children are stored in hisim/hisim/components directory. Some of these classes are:

• RandomNumbers (random_numbers.py)
• SimpleWaterStorage (simple_water_storage.py)
• NightSetbackController (night_setback_controller.py)
• Transformer (transformer_rectifier.py)
• PVSystem (generic_pv_system.py)
• SimpleCHP (generic_chp.py)
• CSVLoader (csvloader.py)
• SumBuilderForTwoInputs (sumbuilder.py)
• SumBuilderForThreeInputs (sumbuilder.py)
• ToDo: more components to be added

Connecting Input/Outputs

In the following the basic principle of the Component connections is explained.

Let my_home_electricity_grid and my_appliance be Component objects used in the scenario. The object my_apppliance has an output ElectricityOutput that has to be connected to an object ElectricityGrid. The object my_home_electricity_grid has an input ElectricityInput, where this connection takes place. In the connections list, the connection would be specified as:

    "source": {
        "component_name": "my_appliance",
        "field_name": "ElectricityOutput"
    },
    "target": {
        "component_name": "my_home_electricity_grid",
        "field_name": "ElectricityInput"
    }
},

Configuration Automator

A configuration automator is under development and has the goal to reduce the amount of connections having to be specified among similar components.

Contributions and Collaborations

ETHOS.HiSim welcomes any kind of feedback, contributions, and collaborations. If you are interested in joining the project, adding new features, or providing valuable insights, feel free to reach out (email to k.rieck@fz-juelich.de) and participate in our bi-weekly HiSim developer meetings. Additionally, we encourage you to utilize our Issue section to share feedback or report any bugs you encounter. We look forward to your contributions and to making meaningful improvements. Happy coding!

License

MIT License

Copyright (C) 2020-2021 Noah Pflugradt, Leander Kotzur, Detlef Stolten, Tjarko Tjaden, Kevin Knosala, Sebastian Dickler, Katharina Rieck, David Neuroth, Johanna Ganglbauer, Vitor Zago, Frank Burkard, Maximilian Hillen, Marwa Alfouly, Franz Oldopp, Markus Blasberg, Kristina Dabrock, Valentin Janser, Nicolai Gölz, Felix Schattmann, Jonas Hoppe

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 - Juelich Systems Analysis belonging to the Forschungszentrum Jülich. Our interdisciplinary institute's research is focusing on energy-related process and systems analyses. Data searches and system simulations are used to determine energy and mass balances, as well as to evaluate performance, emissions and costs of energy systems. The results are used for performing comparative assessment studies between the various systems. Our current priorities include the development of energy strategies, in accordance with the German Federal Government’s greenhouse gas reduction targets, by designing new infrastructures for sustainable and secure energy supply chains and by conducting cost analysis studies for integrating new technologies into future energy market frameworks.

Contributions and Users

Development Partners:

Hochschule Emden/Leer inside the project "Piegstrom".

4ward Energy inside the EU project "WHY" and the FFG project "AI4CarbonFreeHeating"

Acknowledgement

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

For this work weather data is based on data from ["German Weather Service (Deutscher Wetterdienst-DWD)"](https://www.dwd.de/DE/Home/home_node.html/, https://www.dwd.de/DE/service/rechtliche_hinweise/rechtliche_hinweise_node.html) and "NREL National Solar Radiation Database" (License: Creative Commons Attribution 3.0 United States License, Creative Commons BY 4.0); individual values are averaged.

This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No. 891943.

This project has received funding from the FFG under the topic “Digital Technologies”, an initiative of the Federal Ministry for Climate Action, Environment, Energy, Mobility, Innovation and Technology (BMK), through the project "AI4CarbonFreeHeating"

This project has received funding from the Federal Ministry for Economic Affairs and Climate Actions (BMWK.IIB4) under the WAAGE Grant Program (Grant No. 03EI1044/03EE5031D).