GHETOOL: AN OPEN-SOURCE TOOL FOR BOREFIELD SIZING IN PYTHON

GHEtool is a Python package that contains all the functionalities needed to deal with borefield design. It is developed for both researchers and practitioners. The core of this package is the automated sizing of borefield under different conditions. The sizing of a borefield is typically slow due to the high complexity of the mathematical background. Because this tool has a lot of precalculated data, GHEtool can size a borefield in the order of tenths of milliseconds. This sizing typically takes the order of minutes. Therefore, this tool is suited for being implemented in typical workflows where iterations are required.


Graphical user interface
GHEtool also comes with a graphical user interface (GUI).This GUI is prebuilt as an exe-file (only for Windows platforms currently) because this provides access to all the functionalities without coding.A setup to install the GUI at the user-defined place is also implemented and available here.This graphical interface is made by Tobias Blanke from FH Aachen.

Requirements
This code is tested with Python 3.8 and requires the following libraries (the versions mentioned are the ones with which the code is tested) • Numpy (>=1.20.2) • Scipy (>=1.6.When working with Python 3.9 and higher, installing a newer version of pygfunction (>=2.1.0)can lead to problems due to the fact that its dependency CoolProp is not compatible with Python 3.9 and higher (see also https://github.com/CoolProp/CoolProp/issues/1992 and https://github.com/CoolProp/CoolProp/issues/2119).If one wants to work with the newer version of pygfunction and with Python 3.9 or higher, one can install a development version of CoolProp using pip install -i https://test.pypi.org/simple/CoolProp==6.4.2.dev0It is a good practise to use virtual environments (venv) when working on a (new) Python project so different Python and package versions don't conflict with eachother.For GHEtool, Python 3.8 is recommended.General information about Python virtual environments can be found here and in this article.

Check installation
To check whether everything is installed correctly, run the following command

pytest --pyargs GHEtool
This runs some predefined cases to see whether all the internal dependencies work correctly.9 test should pass successfully.

Get started with GHEtool
To get started with GHEtool, one needs to create a Borefield object.This is done in the following steps.
from GHEtool import Borefield, GroundData After importing the necessary classes, one sets all the relevant ground data.data = GroundData(110, # depth of the field (m) 6, # distance between the boreholes (m) 3, # ground thermal conductivity (W/mK) 10, # initial/undisturbed ground temperature (deg C) 0.2, # borehole equivalent resistance (mK/W) 10, # number of boreholes in width direction of the field (/) (continued from previous page) 12, # number of boreholes in the length direction of the field (/) 2.4*10**6) # volumetric heat capacity of the ground (J/m3K) Furthermore, one needs to set the peak and monthly baseload for both heating and cooling.

Functionalities
GHEtool offers functionalities of value to all different disciplines working with borefields.The features are available both in the code environment and in the GUI.These functions are listed in the table below, alongside with a link to an example document where one can find how these functionalities can be used.

Functionality
Example document Sizing the borefield (i.e.calculating the required depth) for a given injection and extraction load for the borefield (three sizing methods are available).

main_functionalities.py
Calculating the temperature evolution of the ground for a given building load and borefield configuration main_functionalities.py Using dynamically calculated borehole thermal resistance (this is directly based on the code of pygfunction) siz-ing_with_Rb_calculation.pyOptimising the load profile for a given heating and cooling load opti-mise_load_profile.py Finding the optimal rectangular borefield configuration for a given heating and cooling load size_borefield_by_length_and_width.py

Precalculated data
This tool comes with precalculated g-functions for all borefields of type nxm (for 0<n,m<21) for which the boreholes are connected in parallel.For these borefield configurations, the g-functions are calculated for different depth-thermal diffusivity-spacing combinations.The ranges are: • Depth: 25 -350m in increments of 25m • Thermal diffusivity of the soil (defined as thermal conductivity / volumetric heat capacity): 0.036 -0.144m 2 /day in increments of 0.018m 2 /day (This is equal to a range of thermal conductivity from 1-4W/mK with a constant volumetric heat capacity of 2.4MJ/m 3 K) • Spacings (equal): 3 -9m in increments of 1m Here a burial depth (D) of 4.0m is assumed even as a borehole radius of 7.5cm for all the precalculated data.
It is possible to calculate your own dataset to your specific project based on the pygfunction tool and use this one in the code.

License
GHEtool is licensed under the terms of the 3-clause BSD-license.See GHEtool license.

Contributing to GHEtool
You can report bugs and propose enhancements on the issue tracker.If you want to add new features and contribute to the code, please contact Wouter Peere (wouter.peere@kuleuven.be).

Citation
Please cite GHEtool using the JOSS paper.

Getting started
In the following, instructions for installing and using the tssm package on Windows are given.The installation instructions for installing and using tssm on Linux/macOS systems are however quite similar and can be, hopefully easily, derived from the instructions below.

GHEtool installation
You can also directly install tssm package from PyPi with the following command: Alternatively, download or clone a local copy of the repository to your computer: git clone https://github.com/wouterpeere/GHEtool And afterwards install (in the folder where the setup.py is located) as editable using: pip install -e .
or install directly via python as python setup.pyinstall

Overview over scaling approaches
The different approaches available are: • The linear approach scaling the original time series to their average using either a given scaling factor or a determined one calculated by the given simultaneity factor.Further explanations can be found here: Linear approach

Linear approach
The linear approach is scaling the original profile (   ) of the current time step () to the mean value for the selected period (  ()  ).It is linearly interpolated using the scaling factor (  () ).Therefore, the scaling factor and average value have to be assigned to the current time step.This is illustrated by  ().For Example if a monthly period is considered the average value array has 12 entries.So one of these 12 entries has to be assigned to the current time step.All time steps in january are referred to the first entry, all time steps in february to the second entry, and so on.
The scaling factor (  ) can either be provided by the user or calculated based on the simultaneity factor ( ).Therefore the maximum of the original values (  ) for all time steps in the current period (, ) and the average value have to be determined.

Graphical Using Interface (GUI)
How to add new options in the GUI?
New options can be added in the .\GHEtool\gui\gui_structure.py script.The added options will be automatically integrated in the Datastorage and the GUI.The following sections will explain the gui structure and the different options which can be added.
The implemented options can then be used in the CalcProblem class in the .\GHEtool\gui\gui_calculation_thread.py script.The value of the option get be get by the get_value() function.

GUI structure
The GUI is based on pages which consists of categories which consists of options.An example for a page is the borehole resistance page.Where the fluid data category can be found.This category has a double spin box option to set the mass flow rate.The order in which the options are created is also the tab order.

Category
To create a category the Category class has to be imported from .\GHEtool\gui\gui_classes.py.Then a default widget parent has to be set.This can be just copied from the previous categories or set to default_parent.As second option the name of the category can be set.In the example below Example category.The last option is the page where the category should be located.In this case page_example.

Float box
To create a float box the FloatBox class has to be imported from .\GHEtool\gui\gui_classes.py.Then a default widget parent has to be set.This can be just copied from the previous options or set to default_parent.As second option the name of the float box can be set.In the example below Float label text.The next option is a default value.In this case 0.5.The next option is the category which should contain the option.In this case category_example.The next option is the decimal position (0=1, 4=1.2345).In this case 2. The next option is a minimal value.In this case 0. The next option is a maximal value.In this case 1.The next option is a step value in which the value is increased if the arrows of the box are used.In this case 0.1.The function add_link_2_show() can be used to couple the float value to other options, hints, function buttons or categories.So in the example option_linked will be shown if the float value is below 0.1 or above 0.9.from GHEtool.gui.gui_classesimport FloatBox option_float = FloatBox( label='Float label text', default_value=0.) option_float.add_link_2_show(option=option_linked,below=0.1,above=0.9)

Integer box
To create a integer box the IntegerBox class has to be imported from .\GHEtool\gui\gui_classes.py.Then a default widget parent has to be set.This can be just copied from the previous options or set to default_parent.As second option the name of the integer box can be set.In the example below Int label text.The next option is a default value.In this case 2. The next option is the category which should contain the option.In this case category_example.The next option is a minimal value.In this case 0. The next option is a maximal value.In this case 12.The next option is a step value in which the value is increased if the arrows of the box are used.In this case 2. The function add_link_2_show() can be used to couple the integer value to other options, hints, function buttons or categories.So in the example option_linked will be shown if the integer value is below 1 or above 10.from GHEtool.gui.gui_classesimport IntBox option_int = IntBox( label='Int label text', default_value=2, category=category_example, minimal_value=0, maximal_value=12, step=2, ) option_int.add_link_2_show(option=option_linked, below=1, above=10)

Button box
To create a button box the ButtonBox class has to be imported from .\GHEtool\gui\gui_classes.py.Then a default widget parent has to be set.This can be just copied from the previous options or set to default_parent.As second option the name of the button box can be set.In the example below Button box label text.The next option is a default index.In this case 0. The next option are the entries.In this case Option 1, Option 2. The next option is the category which should contain the option.In this case category_example.The function add_link_2_show() can be used to couple the selected index to other options, hints, function buttons or categories.So in the example option_linked will be shown if the first (0) option is selected.

List box
To create a list box the ListBox class has to be imported from .\GHEtool\gui\gui_classes.py.Then a default widget parent has to be set.This can be just copied from the previous options or set to default_parent.As second option the name of the list box can be set.In the example below List box label text.The next option is a default index.In this case 0. The next option are the entries.In this case Option 1, Option 2. The next option is the category which should contain the option.In this case category_example.The function add_link_2_show() can be used to couple the selected index to other options, hints, function buttons or categories.So in the example option_linked will be shown if the first (0) option is selected.
One can install GHEtool by running Pip and running the command pip install GHEtool or one can install a newer development version using pip install --extra-index-url https://test.pypi.org/simple/GHEtool Developers can clone this repository.