Merge branch '6-update-docs' into 'main'

after one year of operation. In all plots, the results of both simulations are plotted together, by setting the `newplot` flag

in the plotting configuration to `false` (see [Manual](../../manual/cli.md)).

The curves from the semi-analytical depth-dependent model in Geoloop and the standard implementation of g-functions directly 

overlap in the plots.

The curves from the semi-analytical depth-dependent model in Geoloop and the standard implementation of g-functions are in perfect

agreement in the plots.

![Fig. 3](images/PYG_SU_P_P_SR_ANALYTICAL_SU_A_P_SRtimeplot_T_bave_T_fi_T_fo.png)

2. Install the environment:

   ```bash

   uv sync --extra dev

   uv sync --group dev

   ```

    uv will install all dependencies defined in `pyproject.toml` in a clean, isolated environment.

### Stochastic (Monte Carlo) Simulation

```bash

geloop stochastic-run CONFIG.json

geoloop stochastic-run CONFIG.json

```

### Process Lithology

```bash

geloop process-lithology LITHOLOGY_CONFIG.json

geoloop process-lithology LITHOLOGY_CONFIG.json

```

Computes and plots depth-dependent thermal subsurface properties.

### Compute Heat Load Profile

```bash

geloop calculate-loadprofile LOADPROFILE_CONFIG.json

geoloop calculate-loadprofile LOADPROFILE_CONFIG.json

```

Generates and plots a time-profile of heat extraction and/or injection rates.

### Compute Flow Rate Profile

```bash

geloop calculate-flowdata FLOWDATA_CONFIG.json

geoloop calculate-flowdata FLOWDATA_CONFIG.json

```

Generates and plots a time-profile of flow rates.

### Plot Simulation Results

```bash

geloop stochastic-run CONFIG.json

geoloop stochastic-run CONFIG.json

```

Creates plots of simulation results (e.g. temperature-depth profiles, time-plots of system variables)

Creates plots of simulation results (e.g. temperature-depth profiles, time-plots of system variables).

---

Geoloop batch provides commands to build batch configuration JSON files and to execute the batch script. Note: all

batch commands come with their own --help method.

The batch commands should be executed from the directory where the batch configuration JSON and linked configuration commands

are stored. For an example, see [Simple Simulation](../examples/simple_simulation/simple_simulation.md). 

## Creating batch Configuration Files

### A. Using `batch create`

```bash

geoloop batch create batch.json \

    --process-lithology path/to/lithology.json \

    --calculate-loadprofile path/to/loadprofile.json \

    --single-run path/to/simulation.json \

    --plot path/to/plot.json

    --process-lithology lithology.json \

    --calculate-loadprofile loadprofile.json \

    --single-run simulation.json \

    --plot plot.json

```

Each flag adds a new step.

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 (**insert ref to journal paper**) and a numerical finite volume method based on the model from 

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.

Geoloop includes a semi-analytical model that uses the thermal response factors - or

*g*-functions - from *pygfunction* to calculate system performance of

a single BHE, in a stacked approach, to include

depth-variation in the soil temperature, the borehole design and the

thermal conductivities of the soil. In addition, the model uses the

a single BHE, in a stacked approach. This approach facilitates

depth-variation in the subsurface temperature, borehole design and

subsurface thermal conductivity. In addition, the model uses the

multipole-method in calculation of the thermal resistivity network for

the borehole interior from *pygfunction*, based on dimensions and

materials used for the tubing and grout. Nodes in the thermal resistance

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

the accessory journal paper **insert reference to paper**.

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

### The numerical finite volume method

The geoloop interface also supports the use of the standard functionality of the *pygfunction* Python package by Cimmino & Cook (2022).

The model in this package uses a similar configuration interface as the analytical

model in Geoloop, but does thus not include depth-dependent subsurface

or system design properties.

model in Geoloop, but with depth-uniform subsurface

and system design properties.

This model is well suited for doing fast calculations of first order

indications of system performance or for locations with homogeneous

indications of system performance, for BHE performance estimations at locations with homogeneous

geology or for shallow BHE systems.

## Simulating (curved) borehole fields

## The optimization algorithm

A simple optimization algorithm can be deployed for optimization of the simulated BHE system design and/or operation,

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

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 

**insert reference to geoloop paper**.

Korevaar & Van Wees (in prep.).

**insert flowchart**

conductivity is calculated conform the method described in Limberger et

al. (2018). For a mix of lithologies (max. 2), properties are combined in the geometric mean,

based on relative lithological fractions. These fractions, as a function

of depth, are provided in the table with lithological information from

the borehole. 

of depth, are provided in a table with lithological borehole information. 

To account for uncertainty in the relative lithology fractions and

porosity over depth, an error can be applied to the porosity and

[project]

name = "geoloop"

version = "1.0.0"

version = "1.0.0b1"

description = "This is a Python package for simulation of (deep) Borehole Heat Exchanger (BHE) systems"

authors = [

    { name = "Zanne Korevaar", email = "zanne.korevaar@tno.nl" },

    { name = "Jan-Diederik van Wees", email = "jan_diederik.vanwees@tno.nl" }

]

readme = "README.md"

license = { file = "Apache 2.0" }

license = { text = "Apache 2.0" }

requires-python = ">=3.12,<3.14"

keywords = [

    "borehole heat exchanger", "BHE", "geothermal", "ground-source heat pump",