carm.simulation package

Submodules

carm.simulation.solver module

Time-stepping orchestrator for the BHE simulation.

Assembles all physical inputs, initializes the FLS model and boundary conditions, and runs the simulation via run(). Supports parallel (independent boreholes) and series (fluid outlet of one borehole feeds the next) configurations.

class carm.simulation.solver.Simulation[source]

Bases: object

Time-stepping orchestrator for the BHE simulation.

Assembles all physical inputs, initializes the FLS model and boundary conditions, and runs the simulation via run(). Supports parallel (independent boreholes) and series (fluid outlet of one borehole feeds the next) configurations.

model

Full physical model of the BHE system.

Type:

PhysicalModel

envprops

Static radiative and thermal properties of the external environment.

Type:

EnvironmentalProperties

envinput

Time series of external air temperature and solar irradiance.

Type:

EnvironmentalTimeSeries

timesteps

Duration of each time step [s].

Type:

float

n_steps

Total number of simulation time steps.

Type:

int

mw_tot

Mass flow rate time series, shape (n_bhes, n_steps) or (n_groups, n_steps) in series mode [kg/s].

Type:

NDArray[np.float64]

Tf1

Inlet fluid temperature time series, shape (n_bhes, n_steps) or (n_groups, n_steps) [°C]. When mw is 0 this value must be set as NaN.

Example

>>> Tf1_5 = np.full((1, 100), 4, dtype = np.float64)
>>> Tf1_null = np.full((1, 200), np.nan, dtype = np.float64)
>>> Tf1 = np.concatenate((Tf1_5, Tf1_null), axis = 1)
Type:

NDArray[np.float64]

fls_mode

FLS simulation mode. Accepts 'sqrt' or 'continuous'. The first is less expensive; the latter is more accurate.

Type:

str

groups

Series groups mapping group index to ordered list of borehole indices. Required for series mode, None in parallel mode.

Type:

dict or None

env

Assembled external environment, built at construction time.

Type:

ExternalEnvironment

T_sup_kusuda

Kusuda-Achenbach temperature profile for upper ground layers, shape (n_steps, m_mesh_sup + 1) [°C].

Type:

NDArray[np.float64]

T_middle_kusuda

Kusuda-Achenbach temperature profile for middle ground and borehole layers, shape (n_steps, m_mesh * (n_mesh + n_equations)) [°C].

Type:

NDArray[np.float64]

T_inf_kusuda

Kusuda-Achenbach temperature profile for lower ground layers, shape (n_steps, m_mesh_inf) [°C].

Type:

NDArray[np.float64]

T_bc

Far-field boundary condition array, shape (n_steps, n_bhes, m_mesh) [°C].

Type:

NDArray[np.float64]

T_history

Output temperature history, shape (n_steps + 1, n_bhes, n_dof) [°C].

Type:

NDArray[np.float64]

fls

FLS thermal interference model. None in single-borehole mode.

Type:

FiniteLineSolution or None

gr_p_varprops

Soil moisture module for ground thermophysical properties. Instantiated only if envinput.water_input is not None.

Type:

SoilMoisture or None

bh_p_varprops

Soil moisture module for borehole thermophysical properties. Instantiated only if envinput.water_input is not None.

Type:

SoilMoisture or None

k_ground_history

Thermal conductivity history for the ground, shape (n_steps, n_bhes) [W/(m K)]. Available only if envinput.water_input is not None.

Type:

NDArray[np.float64]

cp_ground_history

Volumetric heat capacity history for the ground, shape (n_steps, n_bhes) [J/(m³ K)]. Available only if envinput.water_input is not None.

Type:

NDArray[np.float64]

rho_ground_history

Density history for the ground, shape (n_steps, n_bhes) [kg/m³]. Available only if envinput.water_input is not None.

Type:

NDArray[np.float64]

k_borehole_history

Thermal conductivity history for the borehole, shape (n_steps, n_bhes) [W/(m K)]. Available only if envinput.water_input is not None.

Type:

NDArray[np.float64]

cp_borehole_history

Volumetric heat capacity history for the borehole, shape (n_steps, n_bhes) [J/(m³ K)]. Available only if envinput.water_input is not None.

Type:

NDArray[np.float64]

rho_borehole_history

Density history for the borehole, shape (n_steps, n_bhes) [kg/m³]. Available only if envinput.water_input is not None.

Type:

NDArray[np.float64]

wc_history_ground

Residual water volume history for the ground, shape (n_steps, n_bhes) [m³]. Available only if envinput.water_input is not None.

Type:

NDArray[np.float64]

wc_history_borehole

Residual water volume history for the borehole, shape (n_steps, n_bhes) [m³]. Available only if envinput.water_input is not None.

Type:

NDArray[np.float64]

model: PhysicalModel
envprops: EnvironmentalProperties
envinput: EnvironmentalTimeSeries
timesteps: float
n_steps: int
mw_tot: ndarray[tuple[Any, ...], dtype[float64]]
Tf1: ndarray[tuple[Any, ...], dtype[float64]] | None = None
heat_flux: bool = False
Q_buildings: ndarray[tuple[Any, ...], dtype[float64]] | None = None
T_supply: ndarray[tuple[Any, ...], dtype[float64]] | None = None
fls_mode: str = 'sqrt'
groups: Dict | None = None
T_sup_kusuda: ndarray[tuple[Any, ...], dtype[float64]]
T_middle_kusuda: ndarray[tuple[Any, ...], dtype[float64]]
T_inf_kusuda: ndarray[tuple[Any, ...], dtype[float64]]
env: ExternalEnvironment
T_bc: ndarray[tuple[Any, ...], dtype[float64]]
T_history: ndarray[tuple[Any, ...], dtype[float64]]
fls: FiniteLineSolution | None = None
run(parallel=None, series=None)[source]

Run the simulation in parallel or series mode.

Dispatches to _run_parallel() or _run_series() based on the provided flags. For single-borehole configurations, parallel and series must both be None.

Parameters:

  • parallel (bool or None) – Set to True to run in parallel mode (independent boreholes).

  • series (bool or None) – Set to True to run in series mode (fluid outlet chaining).

Returns:

Temperature history array of shape (n_steps + 1, n_bhes, n_dof).

Return type:

NDArray[np.float64]

Raises:

ValueError – If both or neither flags are set, or if series groups are not defined.

Examples

>>> T_hist = sim.run(parallel=True)
>>> T_hist.shape
(n_steps + 1, n_bhes, n_dof)

Module contents

class carm.simulation.Simulation[source]

Bases: object

Time-stepping orchestrator for the BHE simulation.

Assembles all physical inputs, initializes the FLS model and boundary conditions, and runs the simulation via run(). Supports parallel (independent boreholes) and series (fluid outlet of one borehole feeds the next) configurations.

model

Full physical model of the BHE system.

Type:

PhysicalModel

envprops

Static radiative and thermal properties of the external environment.

Type:

EnvironmentalProperties

envinput

Time series of external air temperature and solar irradiance.

Type:

EnvironmentalTimeSeries

timesteps

Duration of each time step [s].

Type:

float

n_steps

Total number of simulation time steps.

Type:

int

mw_tot

Mass flow rate time series, shape (n_bhes, n_steps) or (n_groups, n_steps) in series mode [kg/s].

Type:

NDArray[np.float64]

Tf1

Inlet fluid temperature time series, shape (n_bhes, n_steps) or (n_groups, n_steps) [°C]. When mw is 0 this value must be set as NaN.

Example

>>> Tf1_5 = np.full((1, 100), 4, dtype = np.float64)
>>> Tf1_null = np.full((1, 200), np.nan, dtype = np.float64)
>>> Tf1 = np.concatenate((Tf1_5, Tf1_null), axis = 1)
Type:

NDArray[np.float64]

fls_mode

FLS simulation mode. Accepts 'sqrt' or 'continuous'. The first is less expensive; the latter is more accurate.

Type:

str

groups

Series groups mapping group index to ordered list of borehole indices. Required for series mode, None in parallel mode.

Type:

dict or None

env

Assembled external environment, built at construction time.

Type:

ExternalEnvironment

T_sup_kusuda

Kusuda-Achenbach temperature profile for upper ground layers, shape (n_steps, m_mesh_sup + 1) [°C].

Type:

NDArray[np.float64]

T_middle_kusuda

Kusuda-Achenbach temperature profile for middle ground and borehole layers, shape (n_steps, m_mesh * (n_mesh + n_equations)) [°C].

Type:

NDArray[np.float64]

T_inf_kusuda

Kusuda-Achenbach temperature profile for lower ground layers, shape (n_steps, m_mesh_inf) [°C].

Type:

NDArray[np.float64]

T_bc

Far-field boundary condition array, shape (n_steps, n_bhes, m_mesh) [°C].

Type:

NDArray[np.float64]

T_history

Output temperature history, shape (n_steps + 1, n_bhes, n_dof) [°C].

Type:

NDArray[np.float64]

fls

FLS thermal interference model. None in single-borehole mode.

Type:

FiniteLineSolution or None

gr_p_varprops

Soil moisture module for ground thermophysical properties. Instantiated only if envinput.water_input is not None.

Type:

SoilMoisture or None

bh_p_varprops

Soil moisture module for borehole thermophysical properties. Instantiated only if envinput.water_input is not None.

Type:

SoilMoisture or None

k_ground_history

Thermal conductivity history for the ground, shape (n_steps, n_bhes) [W/(m K)]. Available only if envinput.water_input is not None.

Type:

NDArray[np.float64]

cp_ground_history

Volumetric heat capacity history for the ground, shape (n_steps, n_bhes) [J/(m³ K)]. Available only if envinput.water_input is not None.

Type:

NDArray[np.float64]

rho_ground_history

Density history for the ground, shape (n_steps, n_bhes) [kg/m³]. Available only if envinput.water_input is not None.

Type:

NDArray[np.float64]

k_borehole_history

Thermal conductivity history for the borehole, shape (n_steps, n_bhes) [W/(m K)]. Available only if envinput.water_input is not None.

Type:

NDArray[np.float64]

cp_borehole_history

Volumetric heat capacity history for the borehole, shape (n_steps, n_bhes) [J/(m³ K)]. Available only if envinput.water_input is not None.

Type:

NDArray[np.float64]

rho_borehole_history

Density history for the borehole, shape (n_steps, n_bhes) [kg/m³]. Available only if envinput.water_input is not None.

Type:

NDArray[np.float64]

wc_history_ground

Residual water volume history for the ground, shape (n_steps, n_bhes) [m³]. Available only if envinput.water_input is not None.

Type:

NDArray[np.float64]

wc_history_borehole

Residual water volume history for the borehole, shape (n_steps, n_bhes) [m³]. Available only if envinput.water_input is not None.

Type:

NDArray[np.float64]

model: PhysicalModel
envprops: EnvironmentalProperties
envinput: EnvironmentalTimeSeries
timesteps: float
n_steps: int
mw_tot: ndarray[tuple[Any, ...], dtype[float64]]
Tf1: ndarray[tuple[Any, ...], dtype[float64]] | None = None
heat_flux: bool = False
Q_buildings: ndarray[tuple[Any, ...], dtype[float64]] | None = None
T_supply: ndarray[tuple[Any, ...], dtype[float64]] | None = None
fls_mode: str = 'sqrt'
groups: Dict | None = None
T_sup_kusuda: ndarray[tuple[Any, ...], dtype[float64]]
T_middle_kusuda: ndarray[tuple[Any, ...], dtype[float64]]
T_inf_kusuda: ndarray[tuple[Any, ...], dtype[float64]]
env: ExternalEnvironment
T_bc: ndarray[tuple[Any, ...], dtype[float64]]
T_history: ndarray[tuple[Any, ...], dtype[float64]]
fls: FiniteLineSolution | None = None
run(parallel=None, series=None)[source]

Run the simulation in parallel or series mode.

Dispatches to _run_parallel() or _run_series() based on the provided flags. For single-borehole configurations, parallel and series must both be None.

Parameters:

  • parallel (bool or None) – Set to True to run in parallel mode (independent boreholes).

  • series (bool or None) – Set to True to run in series mode (fluid outlet chaining).

Returns:

Temperature history array of shape (n_steps + 1, n_bhes, n_dof).

Return type:

NDArray[np.float64]

Raises:

ValueError – If both or neither flags are set, or if series groups are not defined.

Examples

>>> T_hist = sim.run(parallel=True)
>>> T_hist.shape
(n_steps + 1, n_bhes, n_dof)