gFunctionDatabase Documentation

Introduction

Installation

The source code for this project can be found on github at https://github.com/j-c-cook/gFunctionDatabase.

The gFunctionDatabase package has been uploaded to PyPi. Install the library via pip:

pip install gFunctionDatabase

As long as you are connected to the internet, pip will download and install the package directly from PyPi. If you would like to install a specific version, then you need to specify. For example, if you would like to install version 0.2, then the following command is needed:

pip install gFunctionDatabase==0.2

Background

Thermal response functions, known as g-functions, are commonly used to simulate grount heat exchangers used with ground-source heat pump systems. G-functions were originally developed by Prof. Johan Claesson and his graduate students at the University of Lund in Sweden. (1, 2, 3) G-functions are used by ground heat exchanger design tools (4, 5, 6) and whole building energy simulation tools (7, 8). G-functions are unique to a specific borehole configuration (geometry e.g. 5 rows of 10 boreholes spaced 5m apart) and depth.

Calculation of g-functions can be quite computationally time-consuming, particularly for configurations containing a large number of boreholes. However, once the g-function is computed, the actual simulation time can be quite short, particularly if a hybrid time step (9) approach is used. Because of this, pre-computed g-function libraries are commonly used in design tools and building simulation tools. In practice, the g-functions are pre-calculated for specific configurations; for each configuration multiple depths are pre-computer for interpolation purposes. Then, a design tool, can iteratively adjust the depth to find the correct-sized ground heat exchanger. Furthermore, the g-functions scale with several non-dimensional parameters that allow wider application than the specific horizontal spacing and depths used in the pre-calculation.

Currently, available libraries, implemented in eQuest (7, GLHEPRO 4, EED 5) have less than 1000 possible configurations and are proprietary. This documentation for the g-function database gives a description of a new publicly available library containing g-functions for 34,321 configurations at 5 depths. Some of the configurations are available in existing libraries; others are new. The new configurations are C-shapes, lopsided-U-shapes and zoned rectangles ( 10).

Calculation methodology

This section breifly describes the procedure used to calculate the g-functions. The g-functions are calculated with a tool that we call “cpgfunction” [10]. It is based on the semi-anlytical finite line source methodology developed by Cimmino [11, 12] for an open-source tool written in Python, called pygfunction. Cpgfunction is written in C++. Cpgfunction was developed with an eye towards reducing memory consumption, which can be quite high for large numbers of boreholes, exceeding 96 GB in many cases. For calculating large numbers of g-functions, as was done here, the memory requirements can become critical when running on a cluster. Keeping the memory requirements below 96 GB allowed us to fully use the most common compute nodes on the Oklahoma State High Performance Computing Cluster [13]. The time requirement also improved for most cases, but large number of regularly spaced boreholes the computation times are similar. For further information on cpgfunction, see Cook and Spitler (2021).

The g-functions are calculated using the uniform borehole wall temperature (UBHWT) boundary condition. That is, the heat input at each segment is adjusted to give uniform (but changiing with time) temperature at the borehole walls. This is the method commonly used to develop other g-function libraries and has been used to size ground heat exchangers for commercial systems for the last 30 years.

Database contents

The database contains configurations and methods to access and use g-functions.

Modules and examples

• Modules
  • Statistics Module
  • Handle Contents Module
  • Coordinate Generator Module
  • Access Libraries Module
• Examples
  • Dimensioning Rules Example
  • 1D Interpolation for B/H, D/H, rb/H
  • 2D Interpolation in Bi-Uniform

Libraries and examples

• Libraries
  • Zoned Rectangles
  • Uniform Configurations
• Examples
  • Generate Zoned Rectangle
  • Access Libraries

Bibliography

1

Johan Claesson and Per Eskilson. Conductive heat extraction to a deep borehole: thermal analyses and dimensioning rules. Energy, 13(6):509–527, 1988. URL: https://www.sciencedirect.com/science/article/pii/0360544288900059, doi:https://doi.org/10.1016/0360-5442(88)90005-9.

2

Johan Claesson and Per Eskilson. Conductive heat extraction to a deep borehole: thermal analyses and dimensioning rules. Energy (Oxford), 13(6):509–527, 1988.

3

Göran Hellström. Ground heat storage : thermal analyses of duct storage systems. 1991.

4

J D Spitler. Glhepro : a design tool for commercial building ground loop heat exchangers. Dec 2000.

5

BLOCON. Earth Energy Designer (EED) Version 3.2 Manual. 2015. URL: https://buildingphysics.com/eed-2/.

6

BLOCON. Earth Energy Designer (EED) Version 4 Update Manual. 2017. URL: https://buildingphysics.com/eed-2/.

7

Xiaobing Liu A and Göran Hellstrom B. Enhancements of an integrated simulation tool for ground-source heat pump system design and energy analysis. 2006.

8

Matt S Mitchell and Jeffrey D Spitler. An enhanced vertical ground heat exchanger model for whole-building energy simulation. Energies (Basel), 13(16):4058–, 2020.

9

James R Cullin and Jeffrey D Spitler. A computationally efficient hybrid time step methodology for simulation of ground heat exchangers. Geothermics, 40(2):144–156, 2011.

10

Jack C. Cook and Jeffrey D. Spitler. Faster computation of g-functions used for modeling of ground heat exchangers with reduced memory consumption. In Proceedings of Building Simulation 2021 Conference. International Building Performance Simulation Association, September 1-3, 2021.

11

Massimo Cimmino. Fast calculation of the g-functions of geothermal borehole fields using similarities in the evaluation of the finite line source solution. Journal of building performance simulation, 11(6):655–668, 2018.

12

Massimo Cimmino. pygfunction: an open-source toolbox for the evaluation of thermal response factors for geothermal borehole fields. In Proceedings of eSim 2018, the 10th conference of IBPSA-Canada, 492–501. IBPSA Canada, May 2018.

13

OSUHPCC. OSU's newest supercomputer "Pete" is available for all OSU researchers. Retrieved 29 January, 2021. URL: https://hpcc.okstate.edu/pete-supercomputer.html.

14

Massimo Cimmino and Michel Bernier. A semi-analytical method to generate g-functions for geothermal bore fields. International journal of heat and mass transfer, 70:641–650, 2014.