Merge branch '9-update-doc-curved-wells' into 'main'

## What is **Geoloop**?

**Geoloop** is a Python package for simulating borehole heat exchanger (BHE) systems,

with a focus on optimal implementation of subsurface thermal properties and their impact on system performance.

**Geoloop** is a Python package for simulating vertical borehole heat exchanger (BHE) systems,

with a focus on the impact of depth-dependent thermal properties and geothermal gradient and their impact on system performance.

**Geoloop** incorporates (uncertainty in) depth-variations in subsurface thermal conductivity, subsurface temperature, 

BHE design and diverse operational boundary conditions such as seasonal load variations or 

minimum fluid temperatures, in a tool for deterministic or stochastic performance analyses with the opportunity

for optimization of the system design and operation. This makes Geoloop ideal for scenario analyses and sensitivity 

minimum fluid temperatures. It allows for deterministic or stochastic performance analyses with the opportunity

for optimization of the system design and operation. This makes Geoloop well suited for scenario analyses and sensitivity 

studies in both research and practical applications.

**Geoloop** uses thermal response factors (*g*-functions) calculated using the analytical Finite Line Source model from 

the *pygfunction* package. This setup is extended into a stacked approach for depth-dependent thermal response calculations. 

A detailed description and benchmark of this depth-dependent semi-analytical method is provided in Korevaar & Van Wees (in prep.).

**Geoloop's** generic framework allows for easy switching between simulation methods, including the innovative depth-dependent

semi-analytical approach, the depth-uniform implementation of g-functions as implemented in *pygfunction* and a numerical 

**Geoloop**  provides a novel depth-dependent approach for thermal response calculations. 

A detailed description and benchmark of this depth-dependent semi-analytical method is provided in Korevaar et al. (2026).

**Geoloop** uses the *pygfunction* package, developed by Cimmino & Cook (2022), including its implementation

of *g*-functions, time aggregation schemes for varying loads, borehole and fluid thermal properties, and various visualization capabilities

**Geoloop's** generic framework allows for easy switching between simulation methods, including the 

depth-dependent model, the depth-uniform implementation of g-functions as implemented in *pygfunction* and a numerical 

finite volume approach.

---

---

## References

- Cimmino, M. and Cook, J.: pygfunction 2.2: New features and improvements in accuracy and computational efficiency, 

        in: Proceedings of the IGSHPA Research Track 2022, International Ground Source Heat Pump Association, 

        https://doi.org/10.22488/okstate.22.000015, 2022. 

- Korevaar, Z., Brett, H., Van Wees, J.D.: Geoloop (v1.0) – a stochastic, depth-dependent borehole heat exchanger model, Geoscientific Model Development (in prep), 2026

    The example is located in the following

    working directory: `geoloop/examples/bore_field/madrid`

This example demonstrates how to simulate BHEs with a curved trajectory. The concept of the bore field is similar as described

This example demonstrates how to simulate BHEs with a curved trajectory, in agreement with the case presented in Wawoe et al. (2025).

The concept of the bore field is similar as described

in the example about a [BHE field in the middle east](../bhe_field_me/bore_field_me.md), but incorporates a depth-variable

tilt in a circular borehole field. This is defined in the BHE field configuration JSON (as explained in the [Manual](../../manual/cli.md)),

of the main simulation module.

The bore field is simulated for a period of 25 years with a time step of 24 hours.

---

## Running the example

///

## References

- Wawoe, D., XX,YY, Van Wees, J.D.: A Semi-Analytical Model of the Energy Output of Curved Borehole Heat Exchangers,

  in: proceedings European Geothermal Congress. Zurich, 2025

- Wawoe, D.,  Badenes, B., Blangé, J.J.,Creyghton, M., Godschalk,B.,  Ibanez, S.E., Goitia, Y., Rus, B,  Martinez Zuazo, I., Van Wees, J.D.: A Semi-Analytical Model of the Energy Output of Curved Borehole Heat 

Exchangers, in: proceedings of European Geothermal Congress, Zurich, https://europeangeothermalcongress.eu/wp-content/uploads/2025/11/Wawoe-et-al.pdf, 2025  

IDE or use the CLI by:

```bash

geoloop batch-run `path/to/batch_FINVOL_benchmark.json` 

```

cd examples/benchmark/FINVOL_benchmark

geoloop batch-run `batch_FINVOL_benchmark.json` 

```455

---

# Introduction

Geoloop is a Python package that provides API access to different models and tools for performance calculations of borehole heat 

exchanger (BHE) systems. It includes two models that consider depth-dependency in subsurface thermal properties, in 

a semi-analytical model (Korevaar & Van Wees, in prep.) and a numerical finite volume method based on the model from 

Cazorla-Marín et al. (2019; 2020; 2021). In addition, use of

the *pygfunction* Python package, developed by Cimmino & Cook (2022), is integrated in the geoloop interface, including 

simulation of borehole fields.

exchanger (BHE) systems. It includes two models that consider depth-dependency in subsurface thermal properties and geothermal gradient, in 

a semi-analytical model (Korevaar et al., 2026) and a numerical finite volume method based on the model from 

Cazorla-Marín et al. (2019; 2020; 2021), complementary to a depth-uniform solution.

Geoloop uses

the *pygfunction* Python package, developed by Cimmino & Cook (2022), including its implementation

of *g*-functions, time aggregation schemes for varying loads, borehole and fluid thermal properties, and visualization capabilities.

This theory section concisely explains the difference between the different models and the background theory for the

tools that offer support for optimization of the BHE system design and the implementation of heterogeneous subsurface

location-dependent optimization of the BHE design and investigating the influence of 

variable subsurface thermal properties on the system performance.

For a detailed explanation of the semi-analytical depth-dependent modelling principle, please refer to Korevaar & Van Wees (in prep.).

For a detailed explanation of the semi-analytical depth-dependent modelling principle, please refer to Korevaar et al. (2026).

### The numerical finite volume method

*pygfunction* offers a tool for simulation of borehole fields with vertical or inclined BHE systems, in different field orientations. 

Geoloop builds upon this functionality, in a model for simulating fields of BHE systems with a curved trajectory. 

The implementation and an example for a case study for curved boreholes is described in Wawoe et al. (2025)

**add explanation on how the curved boreholes are incorporated**

## The optimization algorithm

to obtain the maximum power yield from the system with respect to a user-defined boundary condition in the pumping

pressure or coefficient of performance (COP) of the fluid circulation pump.

The flowchart in Fig. 1 represents the optimization process and the algorithm is explained in more detail in 

Korevaar & Van Wees (in prep.).

Korevaar et al. (2026).

![Fig. 1](images/optimization_scheme.png)

- Cazorla-Marín, A., Montagud-Montalvá, C., Corberán, J. M., Montero, Á., and Magraner, T.: A TRNSYS assisting tool

        for the estimation of ground thermal properties applied to TRT (thermal response test) data: B2G model, Applied

        Thermal Engineering, 185, 116370, https://doi.org/10.1016/j.applthermaleng.2020.116370, 2021.

- Korevaar, Z., Brett, H., Van Wees, J.D.: Geoloop (v1.0) – a stochastic, depth-dependent borehole heat exchanger model, Geoscientific Model Development (in prep), 2026

- Limberger, J., Bonte, D., De Vicente, G., Beekman, F., Cloetingh, S., and Van Wees, J. D.: 

  A public domain model for 1D temperature and rheology construction in basement-sedimentary geothermal exploration: 

  an application to the Spanish Central System and adjacent basins, Acta Geod Geophys, 52, 269–282, 

  https://doi.org/10.1007/s40328-017-0197-5, 2017.

- Wawoe, D.,  Badenes, B., Blangé, J.J.,Creyghton, M., Godschalk,B.,  Ibanez, S.E., Goitia, Y., Rus, B,  Martinez Zuazo, I., Van Wees, J.D.: A Semi-Analytical Model of the Energy Output of Curved Borehole Heat 

Exchangers, in: proceedings of European Geothermal Congress, Zurich, https://europeangeothermalcongress.eu/wp-content/uploads/2025/11/Wawoe-et-al.pdf, 2025