Public API

initialize(options::SimulationOptions)

Precompute the objects of each TimeSuperpositionMethod that can be computed ahead of time and return the SimulationContainers of the required size.

simulate!(;options::SimulationOptions, operator, containers::SimulationContainers)

Run the simulation defined by options. At the end of simulation, containers.X will contain the results. containers should be the output of initialize.

operator should be a function that returns a BoreholeOperation and with signature operator(i, Tin, Tout, Tb, q, configurations):

• i::Int is the time step
• Tin is a vector containing the inlet temperature of each borehole
• Tout is a vector containing the outlet temperature of each borehole
• Tb is a vector containing the borehole wall temperature of each borehole
• q is a vector containing the heat exchanged by each borehole
• configurations: is the list of possible hydraulic configurations of the borefield.

BoreholeNetwork(branches::Vector{Vector{Int}})

Representation of the hydraulic connections of the boreholes in the network. Each element in branches should be a vector representing a branch of boreholes connected in series, specified by their identifiers. The first borehole of each branch is assumed to be connected in parallel.

BoreholeOperation{Arr <: AbstractArray}(
    network::BoreholeNetwork         
    mass_flows::Arr
)

Represents a operation state of the network, with network representing the hydraulic configuration and mass_flows a Vector containing the mass flow rate of each branch.

abstract type Operator

Interface for operation strategies.

Required functions:

• operate(::Operator, i, options, Tfin, Tfout, Tb, q): Return a BoreholeOperation.

SimpleOperator{T <: Number} <: Operator (
    mass_flows::Vector{T}
)

Constant operation strategy, always returning BoreholeOperation(options.configurations[1], operator.mass_flows).

struct SimulationOptions{
                TSM <: TimeSuperpositionMethod,
                C <: Constraint,
                B <: Borefield, 
                M <: Medium, 
                BC <: BoundaryCondition,
                N <: Number
            }(
    method::TSM
    constraint::C
    borefield::B
    medium::M
    boundary_condition::BoundaryCondition = DirichletBoundaryCondition()
    fluid::Fluid{N} = Fluid(cpf=4182., name="INCOMP::MEA-20%")
    configurations::Vector{BoreholeNetwork}
    Δt
    Nt::Int
)

Specifies all the options for the simulation.

• method: time superposition method used to compute the response. Available options: ConvolutionMethod, NonHistoryMethod.
• constraint: constraint that the system must satisfy. Can be variable with time. Available options: HeatLoadConstraint, InletTempConstraint.
• borefield: describes the geometrical properties and the boreholes of the borefield on which the simulation will be performed. Available options: EqualBoreholesBorefield.
• medium: properties of the ground where the borefield is places. Available options: GroundMedium, FlowInPorousMedium.
• boundary_condition: boundary condition of the domain where the simulation is performed. Available options: NoBoundary, DirichletBoundaryCondition.
• fluid: properties of the fluid flowing through the hydraulic system.
• configurations: possible hydraulic topologies possible in the system, including reverse flow.
• Δt: time step used in the simulation.
• Nt: total amount of time steps of the simulation.

abstract type Fluid end

Interface for fluids.

Required functions:

• cpf(::Fluid): Return the scpecific heat capacity of the fluid.
• thermophysical_properties(::Fluid, T): Return the μ, ρ, cp, and k of the fluid at temperature T.

Water <: Fluid (
    stored_properties::ThermophysicalProperties{Float64}
)

Models water.

To initialize, use the convenience method: function Water() that will automatically compute stored_properties.

EthanolMix <: Fluid (
    stored_properties::ThermophysicalProperties{Float64}
)

Models a 20% ethanol and water mix.

To initialize, use the convenience method: function EthanolMix() that will automatically compute stored_properties.

abstract type Medium

Interface for mediums.

Required functions:

• get_λ(::Medium): Return the thermal conductivity of the medium.
• get_α(::Medium): Return the thermal diffusivity of the medium.
• get_T0(::Medium): Return the initial temperature of the medium.
• compute_response!(g, ::Medium, borefield::Borefield, boundary_condition::BoundaryCondition, t): Compute inplace in g the thermal responses between boreholes in borefield, imposing the boundary condition boundary_condition, for all times in t.

GroundMedium{T <: Real} <: Medium @deftype T

Model pure conduction in the ground.

Arguments

• λ = 3.: ground conductivity
• α = 1e-6: ground thermal diffusivity
• C = λ/α: ground medium capacity
• T0 = 0.: initial ground temperature

FlowInPorousMedium{T <: Real} <: Medium @deftype T

Model a porous ground with a water flow.

Arguments

• λw = 0.6: water thermal conductivity
• λs = 2.: ground thermal conductivity
• Cw = 4.18*1e6:water thermal capacity
• Cs = 1.7*1e6: ground thermal capacity
• θ = 0.: angle of Darcy velocity
• Φ = 0.2: porosity
• λ = λs * (1-Φ) + λw*Φ: porous medium conductivity
• C = Cs * (1-Φ) + Cw*Φ: porous medium capacity
• α = λ/C: porous medium thermal diffusivity
• ux_in_meterperday = 1e-2: groundwater speed along the flow coordinate
• ux = ux_in_meterperday/(3600*24): groundwater speed in m/s
• vt = ux * Cw/C: porous medium darcy velocity
• T0 = 0.: initial ground temperature

abstract type Borefield

Interface for borefields.

Required functions

• n_boreholes(::Borefield): Return the amount of boreholes present in the borefield.
• get_H(::Borefield, i): Return the length of borehole i.
• get_rb(::Borefield, i): Return the radius of borehole i.
• segment_coordinates(::Borefield): Return a vector with the coordinates of each segment.
• internal_model_coeffs!(M, ::Borefield, medium, operation, fluid): Compute inplace in M the coefficients corresponding to the internal model equations, given the medium, fluid and operation in use in the system. Note that M is only a slice of Nb (number of boreholes) rows, provided as a view.
• internal_model_b!(b, ::Borefield): Compute inplace in b the independent terms corresponding to the internal model equations. Note that b is only a vector of length Nb (number of boreholes) rows, provided as a view.

EqualBoreholesBorefield{T <: Borehole, R <: Medium, S <: Real} <: Borefield
EqualBoreholesBorefield(borehole_prototype::T, positions::Vector{Point2{S}}), medium::R)

Model a borefield with boreholes all identical to the prototype borehole_prototype, placed at positions. Note that the length of positions determines the amount of boreholes in the field. medium contains the properties of the ground.

abstract type Borehole

Interface for boreholes.

Required functions:

• get_H(::Borehole): Return the length of the borehole.
• get_D(::Borehole): Return the burial depth of the borehole.
• get_rb(::Borehole): Return the radius of the borehole.
• uniform_Tb_coeffs(::Borehole, λ, mass_flow, Tref, fluid): Return the internal model coefficients for the resistance network between the pipes and the wall.

SingleUPipeBorehole{T <: Real} <: Borehole @deftype T
SingleUPipeBorehole(H, D)

Model a borehole with a single U-pipe with burial depth D and length H.

Arguments

• λg = 2.5: grout conductivity
• Cg = 2000. * 1550.: grout capacity
• αg = λg/Cg: grout thermal diffusivity
• rp = 0.02: pipe radius
• λp = 0.42: pipe material conductivity
• dpw = 0.0023: pipe thickness
• rpo = rp + dpw: equivalent pipe radius
• hp = 725.: heat transfer coefficient fluid to pipe
• pipe_position::NTuple{2, Tuple{T, T}} = [(0.03, 0.0), (-0.03, 0.0)]: positions of the downward and upward branches of the pipe. (0, 0) represents the center of the borehole.
• rb = 0.115/2: borehole radius

abstract type Constraint

Interface for constraints.

Required functions:

• constraints_coeffs!(M, ::Constraint, operation::BoreholeOperation): Compute inplace in M the coefficients corresponding to the constraints equations, given the current operation.network. Note that M is only a slice of Nbr (number of branches) rows, provided as a view.
• constraints_b!(b, ::Constraint, ::BoreholeOperation, step): Compute inplace in b the independent term corresponding to the constraints equations, given the current operation.network, at the time step step. Note that b is only a vector of length Nbr (number of branches), provided as a view.

HeatLoadConstraint(Q_tot::Matrix{T}){T <: Number} <: Constraint

Constrain the heat extracted per branch.

The heat constraint Q_tot must be a Matrix, whose column i are the loads per branch at the time step i. The amount of rows of Q_tot must equal to the amount of branches specified in BoreholeNetwork.

constant_HeatLoadConstraint(Q_tot::Vector{T}, Nt) where {T <: Number}

Convenience initializer for HeatLoadConstraint. It creates a constant heat load constraint through all the Nt time steps, where Q_tot are the heat load for each branch.

uniform_HeatLoadConstraint(Q_tot::Vector{T}, Nbr) where {T <: Number}

Convenience initializer for HeatLoadConstraint. It creates a uniform heat load constraint along all branches, where T_in are the heat load for each time step.

InletTempConstraint(T_in::Matrix{T}){T <: Number} <: Constraint

Constrain the inlet temperature of the first borehole in each branch.

The inlet temperature T_in must be a Matrix, whose column i are the inlet temperatures per branch at the time step i. The amount of rows of T_in must equal to the amount of branches specified in BoreholeNetwork.

constant_InletTempConstraint(T_in::Vector{N}, Nt) where {N <: Number}

Convenience initializer for InletTempConstraint. It creates a constant inlet temperature constraint through all the Nt time steps, where T_in are the inlet temperatures for each branch.

uniform_InletTempConstraint(T_in::Vector{N}, Nbr) where {N <: Number}

Convenience initializer for InletTempConstraint. It creates a uniform inlet temperature constraint along all branches, where T_in are the inlet temperatures for each time step.

abstract type TimeSuperpositionMethod

Interface for time superposition methods.

Required functions:

• method_coeffs!(M, ::TimeSuperpositionMethod, borefield, medium, boundary_condition): Compute inplace in M the coefficients corresponding to the heat transfer equations, given the medium, and boundary_condition in use in the system. Note that M is only a slice of Nbr (number of branches) rows, provided as a view.
• method_b!(b, ::TimeSuperpositionMethod, borefield, medium, step): Compute inplace in b the independent terms corresponding to the heat transfer equations, given the medium, at the given time step step. Note that b is only a vector of length Nbr (number of branches) rows, provided as a view.
• precompute_auxiliaries!(method::TimeSuperpositionMethod; options): Compute inplace in method the auxiliary quantities used in the simulation that can be performed ahead of time.
• update_auxiliaries!(::TimeSuperpositionMethod, X, borefield, step): Update inplace in method the auxiliaries after each time step step.

ConvolutionMethod{T} <: TimeSuperpositionMethod 
ConvolutionMethod()

Use the naïve convolution to compute the thermal response between boreholes. It should be initialized without arguments, but it contains the variables:

• g stores the unit response between each pair of boreholes evaluated at each time of the simulation.

It should be precomputed with initialize.

• q stores the heat extraction in each borehole at each time step. It is filled as the simulation runs.

NonHistoryMethod{T} <: TimeSuperpositionMethod 
NonHistoryMethod()

Use the non-history method to compute the thermal response between boreholes. See A non-history dependent temporal superposition algorithm for the finite line source solution. It should be initialized without arguments, but it contains the variables:

• F::Matrix{T}: each column contains the F function (encoding the load history) for each borehole. It is initially 0.
• ζ::Vector{T}: discretization nodes of the integration interval. Shared for all boreholes. Precomputed in initialize.
• w::Matrix{T}: weights of the ζ integration for each pair of boreholes. Precomputed in initialize.
• expΔt::Vector{T}: exp(-ζ^2*Δt). Precomputed in initialize.

This feature is experimental and might not work as expected in some cases.

abstract type BoundaryCondition

Interface for boundary conditions.

NoBoundary <: BoundaryCondition

Option to solve the problem in an infinite domain

DirichletBoundaryCondition <: BoundaryCondition

Option to enforce that the surface plane z=0 remains at temperature T=0