B2G API Reference

geoloop.geoloopcore.b2g.B2G

Class for depth dependent variation in pipe temperatures and borehole wall temperatures as well as soil properties, using a 2D axisymmetric finite volume model

The model is based on a modified approach from the work of Cazorla-Marin [1, 2, 3].

The modification is that the thermal resistance and Tb node of pygfunction is used for the borehole wall, and 3 additional nodes are included.

The Tb node is subject to heat flow determined from the thermal resistance network :Rbinv @ (Tf - Tb np.ones)

• q = sum ( qi = Rbinv @ (Tf - Tb np.ones)).

Currently, the model is with finite volume formulation without Lax-Wendroff explicit finite volume scheme (LW scheme not implemented yet). This is a 2nd order explicit scheme, with the thermal resistance network of the borehole wall and the fluid nodes. it practically limits the number of vertical nodes to ca. 10.

Attributes

custom_pipe : CustomPipe Pipe configuration object with geometric and thermal properties. is_coaxial : bool True if the pipe is a coaxial configuration. ag : AxiGrid Axisymmetric finite volume grid (initialized later).

References

[1] Cazorla Marín, A.: Modelling and experimental validation of an innovative coaxial helical borehole heat exchanger for a dual source heat pump system, PhD, Universitat Politècnica de València, Valencia (Spain), https://doi.org/10.4995/Thesis/10251/125696, 2019. [2] Cazorla-Marín, A., Montagud-Montalvá, C., Tinti, F., and Corberán, J. M.: A novel TRNSYS type of a coaxial borehole heat exchanger for both short and mid term simulations: B2G model, Applied Thermal Engineering, 164, 114500, https://doi.org/10.1016/j.applthermaleng.2019.114500, 2020. [3] 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.

__init__

__init__(custom_pipe: CustomPipe) -> None

Initialize the B2G model with a given custom pipe configuration.

Parameters:

Name	Type	Description	Default
custom_pipe	CustomPipe	Object containing borehole geometry, pipe arrangement, and thermal properties.	required

runsimulation

runsimulation(
    bh_design: BoreholeDesign,
    soil_props: SoilProperties,
    sim_params: SimulationParameters,
) -> tuple

Run the borehole-to-ground simulation using finite difference axisymmetric grid.

Parameters:

Name	Type	Description	Default
bh_design	BoreholeDesign	Borehole geometry and thermal resistances.	required
soil_props	SoilProperties	Soil properties and ground temperature profile.	required
sim_params	SimulationParameters	Simulation settings: time array, inlet temperatures, flow rates, etc.	required

Returns:

Name	Type	Description
hours	ndarray	Time array in hours.
Q_b	ndarray	Borehole thermal power [W].
flowrate	ndarray	Mass flow rate [kg/s].
qsign	ndarray	Sign of heat extraction (-1 for extraction, +1 for injection).
T_fi	ndarray	Fluid inlet temperatures [°C].
T_fo	ndarray	Fluid outlet temperatures [°C].
T_bave	ndarray	Average borehole wall temperature [°C].
z	ndarray	Depth coordinates [m].
T_b	ndarray	Borehole wall temperature field [°C].
T_f	ndarray	Pipe fluid temperature field [°C].
qzb	ndarray	Vertical heat flux along borehole [W].
h_fpipes	ndarray	Convective film coefficients for each pipe.
result	ndarray	Raw solution array from the finite difference solver.
zstart	ndarray	Lower boundary of each vertical cell [m].
zend	ndarray	Upper boundary of each vertical cell [m].

modify_par_ag

modify_par_ag(ny_add: int, param: ndarray) -> np.ndarray

Modify the dimension of the AxiGrid object parameter, by adding ny_add nodes in the y direction to represent the pipes.

This member function is used internally to modify the original grid parameters of the AxiGrid object.

Parameters:

Name	Type	Description	Default
ny_add	int	Number of additional nodes to insert in the y-direction for pipes.	required
param	ndarray	Original parameter array (e.g., k, vol, overcp, rcf, rcbulk, axyz).	required

Returns:

Type	Description
ndarray	Modified parameter array with added pipe nodes.

modify_trans_ag

modify_trans_ag(
    ny_add: int, transmission: ndarray
) -> np.ndarray

Modify the dimension of the AxiGrid object transmission or flux (at faces), by adding ny_add nodes in the y direction to represent the pipes.

This member function is used internally to modify the original grid parameters of the AxiGrid object.

Parameters:

Name	Type	Description	Default
ny_add	int	Number of additional nodes to insert in the y-direction.	required
transmission	ndarray	Original transmission/flux array.	required

Returns:

Type	Description
ndarray	Modified transmission array with added pipe nodes.

modify_ag

modify_ag() -> None

Modify the axisymmetric grid to include the pipes and the borehole heat capacity.

This member function is used internally by initAG to modify the original grid parameters of the AxiGrid object.

Replace the heat capacity of the second node in the axisymmetric grid to take into account the borehole heat capacity, corrected for the pipes (which are treated by the pipe nodes).

In addition, insert additional nodes, starting from node 0 to include the pipes and roll the properties of the original axisymmetric grid to include the pipes.

init_ag

init_ag(
    soil_props: SoilProperties,
    nr: int = 35,
    rmax: float = 10,
    T_f_instart: float = 0,
    nsegments: int = 10,
    k: float | ndarray = 2,
    rcf: float | ndarray = 4000000.0,
    rcr: float | ndarray = 3000000.0,
    por: float | ndarray = 0.4,
) -> None

Initialize the axisymmetric grid (AxiGrid) for the borehole-to-ground model.

Sets up the radial and vertical grid, adds pipe nodes, and initializes ground and fluid temperatures.

Parameters:

Name	Type	Description	Default
soil_props	SoilProperties	Soil properties object to obtain ground temperatures.	required
nr	int	Maximum number of radial nodes (should be odd), by default 35	35
rmax	float	Radius of the midpoint of the last cell, by default 10, is a constant	10
T_f_instart	float	Initial fluid temperature used as default to set up the grid initial temperatures, and fluid conductivity and heat capacities	0
nsegments	int	Number of nodes (nx) in the vertical direction, by default 10	10
k	float or ndarray	Bulk thermal conductivity in the radial direction, by default 2.0	2
rcf	float or ndarray	Volumetric heat capacity of fluid [J/m³·K], by default 4e6	4000000.0
rcr	float or ndarray	Volumetric heat capacity of rock [J/m³·K], by default 3e6	3000000.0
por	float or ndarray	Porosity of the cells, by default 0.4	0.4

Returns:

Type	Description
None

get_temperature_depthvar

get_temperature_depthvar(
    hours: ndarray,
    qscale: ndarray,
    T_f_in: ndarray,
    soil_props: SoilProperties,
    nr: int = 35,
    rmax: float = 10,
    nsegments: int = 10,
    k: float | ndarray = 2.0,
    alfa: float = 1e-06,
) -> tuple

Compute the time-dependent temperature profiles for fluid and borehole wall.

Solves the 2D axisymmetric finite difference heat transfer for a borehole including the thermal interaction between fluid, pipes, grout, and ground.

Parameters:

Name	Type	Description	Default
hours	ndarray	Array of time points in hours.	required
qscale	ndarray	Scaling factor for mass flow / heat rate.	required
T_f_in	ndarray	Array of inlet fluid temperatures [°C] (takes first component as inlet temperature).	required
soil_props	SoilProperties	Soil properties object for ground temperatures.	required
nr	int	Maximum number of radial nodes (should be odd), by default 35.	35
rmax	float	Radius of the midpoint of the last cell, by default 10.	10
nsegments	int	Number of nodes in the vertical direction, by default 10.	10
k	float or ndarray	Thermal conductivity (radial), by default 2.0.	2.0
alfa	float	Thermal diffusivity of soil [m²/s], by default 1e-6.	1e-06

Returns:

Name	Type	Description
T_f	ndarray	Fluid temperature [hours, vertical nodes, pipes].
T_b	ndarray	Borehole wall temperature [hours, vertical nodes].
dtf	ndarray	Temperature difference between outlet and inlet [hours, vertical nodes].
qzb	ndarray	Heat flux to borehole [hours, vertical nodes].
result	ndarray	Full 4D result array from the solver [hours, vertical nodes, radial nodes, axial nodes].