SingleRunConfig API Reference

geoloop.configuration.SingleRunConfig

Bases: BaseModel

Configuration object for a single geothermal borehole simulation run.

This model merges sub-configurations, validates borehole-type-dependent parameters, numerical model requirements, and resolves base directories.

Attributes:

Name	Type	Description
`config_file_path`	`Path`	Path to the main configuration file.
`base_dir`	`str or Path`	Path to the output folder.
`run_name`	`(str, optional)`	Name of the simulation run.
`type`	`{UTUBE, COAXIAL}`	Borehole heat-exchanger type.
`H`	`float or int`	Borehole length [m]
`D`	`float or int`	Buried depth [m].
`r_b`	`float`	Borehole radius [m].
`r_out`	`list of float`	Outer pipe radius [m].
`k_p`	`float or int`	Pipe thermal conductivity [W/mK].
`k_g`	`float or int or list of float or int`	Grout thermal conductivity (layered or uniform) [W/mK].
`nsegments`	`int`	Number of model segments along the borehole.
`fluid_str`	`str`	Fluid type. Must be included in the pygfunction.media.Fluid module.
`fluid_percent`	`float or int`	Mixture percentage for the fluid dissolved in water.
`m_flow`	`float`	Mass flow rate [kg/s].
`epsilon`	`float`	Pipe roughness [m].
`r_in`	`list of float, optional`	Inner pipe radius [m]. Used if SDR is None.
`pos`	`list of list of float, optional`	Pipe positions, x,y-coordinates in the borehole. Default `[[0,0][0,0]]` for type COAXIAL.
`nInlets`	`(int, optional)`	Number of inlet pipes. Default 1 for type COAXIAL.
`SDR`	`(float, optional)`	SDR index for pipe thickness. If None, then r_in is used.
`insu_z`	`(float, optional)`	Maximum depth of insulating pipe material [m].
`insu_dr`	`float`	Fraction of pipe wall thickness that is insulated.
`insu_k`	`float`	Thermal conductivity of insulation material [W/mK].
`z_k_g`	`list of float, optional`	Depth breakpoints corresponding to grout thermal conductivities. Used if k_g is list.
`Tin`	`float or int`	Inlet temperature [°C].
`Q`	`float or int`	Heat extraction/injection rate [W].
`Tg`	`int or list of int`	Surface temperature if int, or subsurface temperature values over depth if list.
`Tgrad`	`int`	Geothermal gradient in °C/m.
`z_Tg`	`int or list of int, optional`	Depths at which Tg values apply if list. If int or float then it is not used.
`k_s`	`list of float`	Subsurface bulk thermal conductivity layers [W/mK]. Used if litho_k_param is None.
`z_k_s`	`list of float`	Maximum depths for soil conductivity layers [m]. Used if litho_k_param is None.
`alfa`	`float`	Subsurface thermal diffusivity [m2/s].
`k_s_scale`	`float`	Scaling factor for k_s, uniform over depth.
`model_type`	`{FINVOL, ANALYTICAL, PYG, PYGFIELD}`	Type of model used in simulation.
`run_type`	`{TIN, POWER}`	Starting point for performance calculation (inlet temperature or heat load).
`nyear`	`float or int`	Nr. of simulated years [years].
`nled`	`float or int`	Number of hours per simulated timestep [hours].
`nr`	`(int, optional)`	Number of radial model nodes (if model_type FINVOL).
`r_sim`	`(float, optional)`	Simulation radial distance [m] (if model_type FINVOL).
`save_Tfield_res`	`bool`	Flag to save full 3D temperature field for every timestep, if model_type FINVOL.
`dooptimize`	`bool`	Flag to do optimization simulation.
`optimize_keys`	`list of str, optional`	Parameter names to optimize for.
`optimize_keys_bounds`	`list of tuple, optional`	Bounds for optimization variables.
`copcrit`	`(float or int, optinal)`	Minimum COP of the fluid circulation pump. Used if dooptimize = true.
`dploopcrit`	`(float, optional)`	Pumping power. Adjusts flow rate accordingly.
`borefield`	`(dict, optional)`	Borefield sub-configuration. Required for borehole field simulation.
`variables_config`	`(dict, optional)`	Stochastic or optimization sub-configuration. Required for stochastic simulation.
`litho_k_param`	`(dict, optional)`	Lithology module sub-configuration.
`loadprofile`	`(dict, optional)`	Loadprofile module configuration.
`flow_data`	`(dict, optional)`	FlowData module configuration.

merge_borefield_and_cast_subdicts

merge_borefield_and_cast_subdicts(data)

Merge sub-configuration dictionaries into the root configuration.

This merges the borefield dictionary directly into the root namespace and overwrites or adds parameters from litho_k_param.

Parameters:

Name	Type	Description	Default
`data`	`dict`	Raw configuration dictionary input.	required

Returns:

Type	Description
`dict`	Updated configuration dictionary containing merged fields.

apply_type_logic

apply_type_logic()

Validate and apply logic depending on the borehole heat-exchanger type.

Raises:

Type	Description
`ValueError`	If required fields for UTUBE configurations are missing.

Returns:

Type	Description
`SingleRunConfig`	Updated model with defaults or validated fields.

validate_finvol_fields

validate_finvol_fields()

Validate parameters required for FINVOL numerical model.

Raises:

Type	Description
`ValueError`	If `nr` or `r_sim` are missing when model_type='FINVOL'.

Returns:

Type	Description
`SingleRunConfig`

process_config_paths

process_config_paths()

Resolve the base directory path for the simulation run.

Ensures that relative paths are resolved using the config file location and that the directory exists or is created.

Returns:

Type	Description
`SingleRunConfig`