Package: hisim
HiSim - Household Infrastructure and Building SimulatorHiSim 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 strategies of smart strategies of modern components, such as
heat pump, battery, electric vehicle or thermal energy storage. HiSim is a package under development by
Forschungszentrum Jülich und Hochschule Emden/Leer. For detailed documentation, please
accessReadTheDocsof this repository.Install GraphvizIf 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 repositoryTo clone this repository, enter the following command to your terminal:gitclonehttps://github.com/FZJ-IEK3-VSA/HiSim.gitVirtual EnvironmentBefore installingHisim, it is recommended to set up a Python virtual environment. Lethisimvenvbe the name of
virtual environment to be created. For Windows users, setting the virtual environment in the path\Hisimis done with
the command line:python-mvenvhisimvenvAfter its creation, the virtual environment can be activated in the same directory:hisimvenv\Scripts\activateFor Linux/Mac users, the virtual environment is set up and activated as follows:virtualhisimvenvsourcehisimvenv/bin/activateAlternatively, Anaconda can be used to set up and activate the virtual environment:condacreate-nhisimvenvpython=3.9condaactivatehisimvenvWith the successful activation,HiSimis ready to be locally installed.Install packageAfter setting up the virtual environment, install the package to your local libraries:pipinstall-e.Optional: Set environment variablesCertain 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.envfile wihtin the HiSim root folder or with system tools. The environment variables are:UTSP_URL
UTSP_API_KEYRun Simple System SetupsRun the python interpreter in theHiSim/system_setupsdirectory with the following command:python../hisim/hisim_main.pysimple_system_setup_one.pyorpython../hisim/hisim_main.pysimple_system_setup_two.pyThis command executeshisim_main.pyon the setup functionsetup_functionimplemented in the filessimple_system_setup_one.pyandsimple_system_setup_two.pythat are stored inHiSim/system_setups.
The results can be visualized under directoryresultscreated under the same directory where the script with the setup
function is located.Run Basic Household System setupThe directoryHiSim/system_setupsalso contains a basic household configuration in the scriptbasic_household.py.
It can be executed with the following command:python../hisim/hisim_main.pybasic_household.pyThe system is set up with the following elements:Occupancy (Residents' Demands)WeatherPhotovoltaic SystemBuildingHeat PumpHence, photovoltaic modules and the heat pump are responsible to cover the electricity the thermal energy demands as
best as possible. As the name of the setup function says, the components are explicitly connected to each other, binding
inputs correspondingly to its output sequentially. This is difference then automatically connecting inputs and outputs
based its similarity. For a better understanding of explicit connection, proceed to sessionIO Connecting Functions.Generic Setup Function WalkthroughThe basic structure of a setup function follows:Set the simulation parameters (SeeSimulationParametersclass inhisim/hisim/component.py)Create aComponentobject and add it toSimulatorobjectCreate aComponentobject from one of the child classes implemented inhisim/hisim/componentsCheck ifComponentclass has been correctly importedIf necessary, connect your object's inputs with previous createdComponentobjects' outputs.Finally, add yourComponentobject toSimulatorobjectRepeat step 2 while all the necessary components have been created, connected and added to theSimulatorobject.Once you are done, you can run the setup function according to the description in the simple system setup run.Package StructureThe main program is executed fromhisim/hisim/hisim_main.py. TheSimulator(simulator.py) object groupsComponents declared and added from the setups functions. TheComponentWrapper(simulator.py) gathers together theComponents
inside anSimulatorObject. TheSimulatorobject performs the entire simulation under the
functionrun_all_timestepsand stores the results in a Python pickledata.pklin a subdirectory
ofhisim/hisim/resultsnamed after the executed setup function. Plots and the report are automatically generated from
the pickle by the classPostProcessor(hisim/hisim/postprocessing/postprocessing.py).Component ClassA child class inherits from theComponentclass inhisim/hisim/component.pyand has to have the following methods
implemented:i_save_state: updates previous state variable with the current state variablei_restore_state: updates current state variable with the previous state variablei_simulate: performs a timestep iteration for theComponenti_doublecheck: checks if the values are expected throughout the iterationThese methods are used bySimulatorto execute the simulation and generate the results.List ofComponentchildrenTheses classes inherent fromComponent(component.py) class and can be used in your setup function to customize
different configurations. AllComponentclass children are stored inhisim/hisim/componentsdirectory. Some of these
classes are:RandomNumbers(random_numbers.py)SimpleController(simple_controller.py)SimpleSotrage(simple_storage.py)Transformer(transformer.py)PVSystem(pvs.py)CHPSystem(chp_system.py)Csvload(csvload.py)SumBuilderForTwoInputs(sumbuilder.py)SumBuilderForThreeInputs(sumbuilder.py)ToDo: more components to be addedConnecting Input/OutputsLetmy_home_electricity_gridandmy_appliancebe Component objects used in the setup function. The
objectmy_apppliancehas an outputElectricityOutputthat has to be connected to an objectElectricityGrid. The
objectmy_home_electricity_gridhas an inputElectricityInput, where this connection takes place. In the setup
function, the connection is performed with the methodconnect_inputfrom theSimulatorclass:my_home_electricity_grid.connect_input(input_fieldname=my_home_electricity_grid.ELECTRICITY_INPUT,src_object_name=my_appliance.component_name,src_field_name=my_appliance.ELECTRICITY_OUTPUT)Configuration AutomatorA configuration automator is under development and has the goal to reduce connections calls among similar components.Post ProcessingAfter the simulator runs all time steps, the post processing (postprocessing.py) reads the persistent saved results,
plots the data and
generates a report.LicenseMIT LicenseCopyright (C) 2020-2021 Noah Pflugradt, Vitor Zago, Frank Burkard, Tjarko Tjaden, Leander Kotzur, Detlef StoltenYou should have received a copy of the MIT License along with this program.
If not, seehttps://opensource.org/licenses/MITAbout UsWe are
theInstitute of Energy and Climate Research - Techno-economic Systems Analysis (IEK-3)belonging to theForschungszentrum 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 UsersDevelopment Partners:Hochschule Emden/Leerinside the project "Piegstrom".4ward Energyinside the EU project "WHY"AcknowledgementThis 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)"and"NREL National Solar Radiation Database"(License: Creative Commons Attribution 3.0 United States License); 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.