Version 3

[MassimoCimmino]

Some context

The repository has been idle for a while. I have made some progress towards some of the open issues. However, the current structure of the package and limitations of the finite line source solution make their implementation exponentially more complex as the project grows. In the meantime, we published a journal article (Cimmino, Basquens and Lazzarotto, 2026) introducing a higher order finite line source approach to model borefields. This method is implemented in the package geothermsim. geothermsim is not meant to replace pygfunction. Even though they share similar approaches, geothermsim aims for detailed simulations of borefields while pygfunction aims for rapid evaluation of g-functions.

Development of pygfunction started in 2016 using Python 2.7. Since then, the Python ecosystem progressed massively and, more importantly, our capabilities in the calculation and use of g-functions progressed in ways I could not foresee at the time. The package was simply not structured to accomodate the current and planned features.

To facilitate the development of pygfunction on the long term, I find it valuable to refactor (or rather rewrite) the entire package using the new high order method. A repository for the implementation of the high order method is available here: pygfunction-HigherOrder.

Advantages of the new high order method

The high order method assumes polynomial variations of borehole wall temperatures and heat extraction rates from values at nodes, and therefore relies on the evaluation of finite line sources at these nodes (instead of the average along segments). This makes the extension from vertical to inclined borehole very simple (and is somewhere where the current implementation struggles in pygfunction).

Status of the new repository

Currently implemented features

• Evaluation of g-functions using the uniform heat transfer rate ('UHTR') and uniform borehole wall temperature ('UBWT') boundary conditions.
• 'Similarities' method for vertical and inclined boreholes. This already gives some performance upgrades in comparison to pygfunction v2. For example, the g-function of a field of 100 inclined boreholes is evaluated in 5.12 seconds, compared to 482 seconds in v2. This is showcased in the following notebook.
• A rewrite of the multipole method. It is much faster than the implementation in v2, in parts due to caching of reusable results and also due to a direct solver for the evaluation of multipole strengths (instead of the iterative solver). The plan is to have borefield objects all call the same multipole object to accelerate the (now slow) pre-processing step that precedes the evaluation of g-functions with the 'MIFT' boundary condition. The multipole method is validated in the following notebook.

Features to be implemented to catch up with v2

• Extension of the borehole and borefield classes to include the evaluation of fluid temperature and heat extraction rate profiles.
• 'MIFT' boundary condition for the evaluation of g-functions, and variable mass flow rate g-functions.
• 'Equivalent' solver for the evaluation of g-functions (which relies on the steady-state finite line source solution for the clustering of boreholes).
• Simulation using load aggregation and other temporal superposition methods.

Other steps before release

• Docstrings, documentation and examples
• Tests
• Formatting (pep8, etc.)

Open issues

• A rewrite of pygfunction makes some of the open issues obsolete (e.g. Refactor pipes module #120, Optimal discretization of segments along boreholes #153, New Borefield class #210, Refactor heat_transfer module #211, Approximation of erfint #239, Refactor Similarities #323, Refactor Equivalent #324).
• If done correctly, it can solve issues with the code base (e.g. Type annotations and mypy #178, Overhaul tests and increase coverage #181, Create API to compute g-function from Network class #318).
• Some of the other open issues should be kept in mind while working on the new interfaces (e.g. Short-term correction using the cylindrical heat source #44, NewFeature Analytical Short-term g-function #149, Thermal interference between two borefields #264, Ground temperature at locations (x, y, z) #265, Simulation module #305).

Backward-incompatible version

The calculation method is new, which by itself breaks backward compatibility and justifies an increment of the major version up to 3.x. It is then also an opportunity to review the pygfunction workflow (borefield declaration -> g-function evaluation -> simulation). As development progresses, I would appreciate anyone's feedback on the various interfaces and how to simplify the workflow. I will open issues on the new repository on critical aspects but anyone is welcome to comment at any time.

[metab0t]

Thanks for your great work on pygfunction and continuing development on the high-order methods.

We recently propose some higher-order methods to calculate g-functions as well (under UBWT BC), where we discretize the temperature integral directly without the polynomial assumption. The final formulation does not include explicit integrals and is easier to assemble the linear system to solve, so it might be useful as another algorithm to be implemented in the next generation of pygfunction.

Links:
Vertical boreholes
Inclined boreholes

[MassimoCimmino]

Thank you @metab0t for posting the links to your papers. I had seen them recently and find them very interesting.

I agree it is very relevant to pygfunction. From my first read-through, I think it should be straightforward to include as an option. I need to make a few small changes to how the 'thermal_response_factors' module calls the 'finite_line_source' but it is surely worth it for this method and for future-proofing if other methods are to be developed.

Right now I will be working on the fluid temperature profile models since they may lead to modifications to the other modules. I will make sure to keep you in the loop.

[j-c-cook]

Thanks for the pointer, @MassimoCimmino -- I've made a first pass through the paper and really appreciate both the dialogue and the contribution. Integrating the point source along polynomial borehole trajectories, combined with polynomial variations of q' and T_b within each segment, is very elegant - and the result that increasing polynomial order beats increasing segment count is a nice practical takeaway. The natural extension to curved trajectories is also a real capability jump of the FLS-based formulations.

I'm looking forward to pygfunction 3.0, and will likely lean on pygfunction-HigherOrder / geothermsim for any near-term work I take on before the refactor here lands.

On the broader question of third-party g-function calculations: I do think giving users options is valuable, but I don't think it's sustainable to ask you to implement every model that comes along. One pattern worth considering is a plugin-style system - an abstract base class in pygfunction defining the g-function-producer interface with third-party implementations published as separate optional-install packages. That way alternative models can be developed in parallel by independent contributors without expanding pygfunction's maintenance surface, and pygfunction becomes the foundation/standard interface for that ecosystem rather than need to own every variant directly.