SingleRun API Reference

geoloop.bin.SingleRunSim.SingleRun

Class for parameters for running BHE model which consists of various compartments which can be adapted, and facilitates in creating and updating related objects.

These include:

A. BoreholeDesign - the borehole dimensions, and pipe configuration and dimensions - the material properties and roughness of pipes - the grout properties - the working fluid properties - pump efficiency - borehole field parameters (only for madrid/curved borehole field) - N number of boreholes (used to scale flow over each borehole) - R radius of circular arranged boreholes(only for ilted borehole field)

B. SoilProperties - surface temperature and gradient - thermal properties of soil

C. OperationalParameters - inlet temperature of power timeseries - mass rate

__init__

__init__(
    borehole_design: BoreholeDesign,
    soil_properties: SoilProperties,
    simulation_parameters: SimulationParameters,
) -> None

Construct a SingleRun object.

Parameters:

Name	Type	Description	Default
borehole_design	BoreholeDesign	Borehole, pipe, grout, and geometry configuration.	required
soil_properties	SoilProperties	Ground temperature and thermal properties.	required
simulation_parameters	SimulationParameters	Time-dependent operational parameters and solver configuration.	required

from_config classmethod

from_config(config: SingleRunConfig) -> SingleRun

Create a SingleRun instance from a configuration dictionary.

If dploopcrit is present in the configuration, the mass flow rate is automatically scaled to match the allowed pumping pressure.

Parameters:

Name	Type	Description	Default
config	SingleRunConfig	Configuration object (typically loaded from a JSON file).	required

Returns:

Type	Description
SingleRun	Configured instance of SingleRun.

run

run(isample: int) -> SingleRunResult | None

Run a single borehole heat exchanger (BHE) simulation for one sample.

Parameters:

Name	Type	Description	Default
isample	int	Index of the sample to run. Use -1 for the base case.	required

Returns:

Type

Description

SingleRunResult

Object containing the simulation results, including: Time-dependent outputs - hours : ndarray of shape (nt,) Simulation time in hours. - Q_b : ndarray of shape (nt,) Extracted/injected borehole power [W]. - flowrate : ndarray of shape (nt,) Mass flow rate [kg/s]. - qsign : ndarray of shape (nt,) Sign of heat extraction/injection. - T_fi : ndarray of shape (nt,) Inlet fluid temperature [°C]. - T_fo : ndarray of shape (nt,) Outlet fluid temperature [°C]. - T_bave : ndarray of shape (nt,) Average borehole wall temperature [°C]. - dploop : ndarray of shape (nt,) Pressure drop across the loop [bar]. - qloop : ndarray of shape (nt,) Pumping power [W]. - Re_in, Re_out : ndarray of shape (nt,) Reynolds numbers in inlet/outlet pipes. Depth-dependent outputs - z : ndarray of shape (nz,) Depth coordinates for fluid temperatures. - zseg : ndarray of shape (nseg,) Depth segment coordinates for wall/grout quantities. - T_b : ndarray of shape (nt, nseg) Borehole wall temperature [°C]. - T_f : ndarray of shape (nt, npipes, nz) Fluid temperature in pipes [°C]. - qzb : ndarray of shape (nt, nseg) Heat flux along the borehole wall [W]. - k_s : ndarray of shape (nseg,) Soil conductivity interpolated over segments. - k_g : ndarray of shape (nseg,) Grout conductivity over segments. - Tg : ndarray of shape (nseg,) Undisturbed ground temperature [°C].

Notes

The executed simulation model is determined by operPar.model_type. Supported models include: FINVOL, ANALYTICAL, PYG, and PYGFIELD.

visualize_pipes

visualize_pipes(filename: str | Path) -> None

Visualize a cross-section of the borehole with the pipe configuration.

Parameters:

Name	Type	Description	Default
filename	str or Path	Full file path (including .png extension) for saving the figure.	required

Returns:

Type	Description
None	The function saves the visualization to disk.

plot_borefield_and_gfunc

plot_borefield_and_gfunc(filepath: str | Path) -> None

Plot a 3D visualization of the borefield layout and its associated g-function, if the pygfield model is used in the simulation.

Parameters:

Name	Type	Description	Default
filepath	str or Path	Base output path. The function appends suffixes such as '_borefield.png' and '_gfunction.png'.	required

Returns:

Type	Description
None	The function saves the borefield and g-function visualizations.