GHEtool: An open-source tool for borefield sizing

What is GHEtool?

<img src="https://raw.githubusercontent.com/wouterpeere/GHEtool/main/docs/Icon.png" width="110" align="left">

GHEtool is a Python package that contains all the functionalities needed to deal with borefield design. GHEtool has been developed as a joint effort of KU Leuven (The SySi Team), boydens engineering (part of Sweco) and FH Aachen and is currently being maintained by Enead BV. The core of this package is the automated sizing of borefield under different conditions. By making use of combination of just-in-time calculations of thermal ground responses (using pygfunction) with intelligent interpolation, this automated sizing can be done in the order of milliseconds. Please visit our website https://GHEtool.eu for more information.

Read The Docs

GHEtool has an elaborate documentation where all the functionalities of the tool are explained, with examples, literature and validation. This can be found on https://ghetool.readthedocs.io/en/latest/.

Graphical user interface

There are two graphical user interfaces available which are built using GHEtool: GHEtool Cloud and GHEtool Community

GHEtool Cloud

GHEtool Cloud is the official and supported version of GHEtool which supports drilling companies, engineering firms, architects, government organizations in their geothermal design process. With GHEtool Cloud they can minimize the environmental and societal impact while maximizing the cost-effective utilization of geothermal projects. Visit our website at https://ghetool.eu to learn more about GHEtool Cloud and what it can do for you.

<p align="center"> <img src="https://ghetool.eu/wp-content/uploads/2024/08/GHEtool-Cloud-squarish.png" width="600"> </p>

GHEtool Community

Besides GHEtool Cloud, an open-source alternative for the graphical user interface is available in the form of GHEtool Community. This version is built and maintained by the community, and has no official support like GHEtool Cloud. You can read all about this GHEtool Community on their GitHub repo.

Development

GHEtool is in constant development with new methods, enhancements and features added to every new version. Please visit our project board to check our progress.

Requirements

This code is tested with Python 3.10, 3.11, 3.12, 3.13 and 3.14 and requires the following libraries (the versions mentioned are the ones with which the code is tested)

• matplotlib >= 3.9.2
• numpy >= 1.26.4
• pandas >= 1.4.3
• pygfunction >= 2.3.1
• scipy >= 1.8.1
• secondarycoolantprops >= 1.1
• optuna >= 3.6.1

For the tests

• pytest >= 7.1.2

Quick start

Installation

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

GHEtool is also available as a conda package. Therefore, you can install GHEtool with the command:

conda install GHEtool

Developers can clone this repository.

It 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 or higher 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. All test should pass successfully.

Get started with GHEtool

Building blocks of GHEtool

GHEtool is a flexible package that can be extend with methods from pygfunction. To work efficiently with GHEtool, it is important to understand the main structure of the package.

Borefield

The Borefield object is the central object within GHEtool. It is within this object that all the calculations and optimizations take place. All attributes (ground properties, load data ...) are set inside the borefield object.

Ground properties

Within GHEtool, there are multiple ways of setting the ground data. Currently, your options are:

• GroundConstantTemperature: if you want to model your borefield with a constant, known ground temperature.
• GroundFluxTemperature: if you want to model your ground with a varying ground temperature due to a constant geothermal heat flux.
• GroundTemperatureGradient: if you want to model your ground with a varying ground temperature due to a geothermal gradient.
• You can also use multiple ground layers to define your ground model. Please take a look at our example.

Please note that it is possible to add your own ground types by inheriting the attributes from the abstract _GroundData class.

Pipe data

Within GHEtool, you can use different structures for the borehole internals: U-tubes or coaxial pipes. Concretely, the classes you can use are:

• Multiple U-tubes
• Single U-tubes (special case of multiple U-tubes)
• Double U-tubes (special case of multiple U-tubes)
• Coaxial pipe
• Conical pipe (like the GEROtherm VARIO and FLUX probes from HakaGerodur (learn more))
• Separatus tube: The Separatus geothermal heat exchanger is an innovation in the geothermal domain. It consists of a single, DN50 pipe with a unique 'splitpipe'-technology that separates the cold and the hot side of the fluid. For design purposes, it is advised to use this with rather small borehole diameters of DN90. For more information, visit the separatus website. An example in GHEtool can be found here.
• Turbocollector: The Turbocollector from Muovitech has internal fins which enhances the turbulent flow character at lower flow rates. Visit their website for more information turbocollector website. An example in GHEtool can be found here.

Please note that it is possible to add your own pipe types by inheriting the attributes from the abstract _PipeData class.

Fluid data

You can set the fluid data by using the FluidData class.

• ConstantFluidData: Temperature independent fluid properties
• TemperatureDependentFluidData: Temperature dependent fluid data (Water, MPG, MEG, MMA, MEA, Thermox DTX, Coolflow NTP, Kilfrost GEO or Kilfrost GEO Plus)

Flow rate data

• ConstantFlowRate: A single, unique constant flow rate for the system.
• VariableHourlyFlowRate: An hourly varying flow rate for the system.
• VariableHourlyMultiyearFlowRate: An multiyear hourly varying flow rate for the system.
• ConstantDeltaTFlowRate: Calculate the flow rate based on a fixed delta T for extraction and injection.

Efficiency data

Within GHEtool, you can work with both seasonal efficiencies (SCOP and SEER) and temperature dependent efficiencies (COP and SEER). These efficiencies can be used in the Building load classes (cf. infra). The different available efficiency classes are:

• SCOP: Constant seasonal performance for heating
• SEER: Constant seasonal performance for cooling
• COP: Instant efficiency for heating, with inlet temperature, outlet temperature and part load dependency
• EER: Instant efficiency for cooling, with inlet temperature, outlet temperature and part load dependency
• EERCombined: EER for combined active and passive cooling

Load data

One last element which you will need in your calculations, is the load data. Within GHEtool, there are three important aspects when it comes to choosing the right load data class.

1. Load type: Do you want to work with building (i.e. secondary) or geothermal (i.e. primary) load?
2. Resolution type: Do you want to work with monthly or hourly data?
3. Multiyear: Do you want to assume a building/geothermal demand that is constant over the simulation period or do you want to enter the load for multiple years?

Depending on your answer on these three questions, you can opt for one of eight different load class