Python API

pyghe, the Python API of GHE Analysis

pyghe runs the simulation kernel of GHE Analysis from Python: borehole thermal resistance, g-functions, hourly entering fluid temperatures over up to 50 years, and the length a borehole field needs. It is the same code as the desktop application, so a script and the interface give the same answer.

# pip install pyghe
import pyghe as ga

p = ga.Project.load("my_project.ghe")      # a project saved by the application

for length in range(120, 241, 20):          # active length of each borehole, m
    p.ground_heat_exchanger.active_length = length
    result = p.simulate()
    print(length, result.eft.min())         # coldest entering fluid temperature, °C

Each variant is one more turn of the loop. A project can also be built in Python from nothing, without a .ghe file.

What it computes

• Hourly simulation of the entering fluid temperature over 1 to 50 years, with the heat pumps, their temperature limits and the system configurations of the application.
• Sizing of the borehole field by the ASHRAE alternative method, as in the application: the total length each mode requires, with every term of the sizing equation.
• Effective borehole thermal resistance by the multipole method, for single and double U-loops, coaxial pipes and standing column wells.
• g-functions of regular or irregular fields, with vertical or inclined boreholes and groundwater flow.
• Thermal plumes in 2D and 3D, the ones the application draws around the field.
• Fluid properties of water and of antifreeze mixtures.
• Project files: .ghe files are read and written, so a case prepared in Python opens in the application, and the other way around.
• Many cases at once: run_many and sweep spread a parametric study over the cores of the computer.

Results come back as numpy arrays, with the names and the SI units of the application.

Studies a loop makes easy

pyghe was written for the studies that are tedious to do by hand in an interface: parametric sweeps, uncertainty analyses, optimization of the borehole positions. The documentation works through each of them on the same small office building, a field of twelve boreholes. Every figure below comes from a script of a few dozen lines.

How it works

pyghe has no physics in it. It writes the project as a case, passes it to AnalysisSuite-cli, the kernel of the application without its interface, and returns the result as Python objects and numpy arrays. There is only one implementation to check: the verification scenarios of the application test the code a script runs, and a case run from Python gives the same numbers as the executable, bit for bit.

The kernel is the product of research done at Polytechnique Montréal since 2008: spectral convolution of the loads, the quasi-3D borehole response, successive flux estimation for the g-function and the standing column well. The Methods page of the documentation gives the paper behind each computation.

The package installs with pip install pyghe and needs Python 3.10 or later. The executable is downloaded separately, for Windows or macOS, from the download page.

Licence

The package is free and open source, under the MIT licence. The computations are done by Analysis Suite, so they follow its licence.

The tiers of Analysis Suite differ only by capacity, and a script is a way of using all of it: hundreds of cases in a row, on fields of up to 625 boreholes. The API therefore comes with the 625-borehole level, that is the Large and Enterprise licences, and the free Academic licence for research and teaching. The executable checks the licence activated in the application, not Python, so a script follows the same rules as the interface.

Citing

Documentation and source

• DocumentationInstallation, the project nodes, every computation, examples and notebooks.
• Source code on GitHubThe package, its tests and eight notebooks. Issues are welcome.
• Python Package Indexpip install pyghe
• Download Analysis SuiteThe application, a demonstration version and the executable pyghe runs.

Questions