HomeFeaturesExamplesTutorialsHelpTheoryVerificationPricingContact
Theory manual

24. Co-simulation of the borehole field with system models

A normal design calculation fixes the ground load before it starts: the building loads, converted with seasonal performance factors, give the heat rate into or out of the ground for every month or hour. In a real plant the ground load and the field interact. The heat pump sees the brine that comes out of the field, its coefficient of performance (COP) follows that temperature, and the heat it takes from the ground follows the COP. Controllers, buffer tanks and free cooling add further feedback. BoreTherm handles these systems by co-simulation: the borehole field and one or more external models are advanced side by side and exchange signals at fixed communication points. External models are Functional Mock-up Units (FMUs) of the FMI 2.0 standard for co-simulation (Modelica Association 2014), for example a heat pump or a building model exported from a Modelica tool.

This chapter describes the three parts involved: the time stepper, which turns the borehole field into a component that can be advanced by any step (Section 24.2); the co-simulation master, which couples the stepper with FMUs and simple signal sources (Section 24.3); and the export of the field, so that other simulation tools can use BoreTherm's ground model (Section 24.5). A worked example and the limits close the chapter.

24.1 Purpose and place in the design workflow

The co-simulation is an advanced check, not a replacement for the design. The design of a project is checked with Calculate (the fluid temperatures over the design period) and sized with Size borehole length, using the loads of the Loads page and, when it is set up, the heat pump of the project. The co-simulation uses its own system and keeps its own results: it never changes the project unless the user applies a length found by a coupled sizing (Apply length to project). A typical use is to design the field with the classic tools and then check it against the dynamic system model of the HVAC engineer.

Table 43. The two ways a heat pump enters a BoreTherm project.
Design heat pump of the projectCo-simulation
Building loadsLoads page (monthly or hourly)a table or constant source, or the FMU itself
Heat pump modeldata-sheet points; COP as a fraction of the Carnot COPany FMI 2.0 co-simulation FMU with its own controls
Couplingwhole simulation repeated until the seasonal performance factor is stablesignals exchanged at every communication step
SizingSize borehole lengthSize with the co-simulation: one coupled run per trial length
Effect on the designit is the designnone until Apply length to project

The pages of the co-simulation are grouped under Advanced analysis › Co-simulation: the System page (a block diagram of the borehole field, the FMUs, the sources and the connections), one page per FMU (identity, trust, variables and parameters), the Settings page (period, communication step, coupling, long-term mode, host) with the commands Run co-simulation, One-day test run and Size with the co-simulation, and the Results page (summary, time series of any recorded signal, annual extremes, warnings and the FMU log). The one-day test run checks the wiring, the units and the FMUs in seconds and should be run first.

24.2 The time stepper of the borehole field

The stepper is the hourly simulation of the field rewritten as a component that a system simulation advances step by step, with steps of any length. Its inputs are the inlet temperature Tin and the mass flow ṁ of the field (or, alternatively, the heat rate into the ground); its outputs are the outlet temperature Tout, the heat rate into the fluid Qflow=ṁcp(Tout−Tin), the mean fluid temperature Tf, the mean borehole wall temperature Tb and the pressure drop Δp. A load q per metre is positive into the ground, as everywhere in BoreTherm, so that Qflow=−qL with L the total active length of the field.

24.2.1 Ground history on a fixed internal grid

The ground responds as in the hourly simulation: the borehole wall temperature is the temporal superposition of the field's g-function over the history of load steps,

Tb(tn)=Tm+12πλ∑i=1n(qi−qi−1)g(tn−ti−1)
(24.1)

with Tm the undisturbed ground temperature, λ the ground conductivity and g the dimensionless step response of the field. The history is held on an internal grid of step h (default 1 h) by the load aggregation of Claesson and Javed (2012): older steps are lumped into longer cells, so the cost of a step does not grow with the length of the run. The cells cover the pre-conditioning and the whole horizon of the run, and the last cell absorbs everything older, so the wall temperature does not depend on the horizon chosen. Loads older than the g-function table (1.65 times the horizon) stop acting; the horizon must therefore cover the run.

A communication step [t,t+Δt] of any length is split at the internal grid points. Inside an internal step, at the fraction τ∈(0,1] of it, the incomplete step acts with the running mean of its load. With E=∫qdt over its earlier sub-intervals and the yet unknown load q of the current sub-interval of length δt:

q¯=E+qδtτh
(24.2)

The wall temperature at the end of the sub-interval is then linear in q:

Tw=Tw0+Rgq,Tw0=Tm+Φ(τ)+Eg(τh)/(τh)2πλ,Rg=δtg(τh)2πλτh
(24.3)

where Φ(τ) is the response to the committed steps. When the internal step is complete, its mean load E/h is committed to the aggregation. With one communication step per internal step this is exactly the step of the hourly simulation: a stepper fed with the inlet temperatures of the hourly simulation returns its outlet temperatures to rounding. Energy is conserved by construction, because every sub-interval's ∫qdt goes into E and from there into the cells. Within one internal step the loads of the sub-intervals are represented by their mean; this redistributes load inside one internal step only, and is exact at its end for a load that is constant over it. In the verification, internal steps of 600 s and 3600 s differ by less than 0.01 K at hourly communication.

24.2.2 Fluid closure

For a sub-interval every borehole model of BoreTherm gives a linear relation Tf=A+Bq between the mean fluid temperature and the load (Section 24.2.3). With the arithmetic mean fluid temperature and the energy balance of the fluid,

Tf=Tin+Tout2,qL=ṁcp(Tin−Tout)
(24.4)

the load follows in closed form:

q=Tin−AB+L/(2ṁcp),Tout=Tin−qLṁcp,Tf=A+Bq
(24.5)

When the field is driven by a prescribed heat rate instead, q=Q/L and the inlet and outlet temperatures are Tf±qL/(2ṁcp).

Low, zero and reverse flow. The effectiveness of the closure,

ε=L/(ṁcp)B+L/(2ṁcp)=2NTU2+NTU,NTU=LṁcpB
(24.6)

exceeds 1 for NTU>2, that is at very low flow: the outlet would overshoot the wall side A. The closure is therefore limited to the full exchange, Tout=A; the limit is continuous at NTU=2 and never active at design flows. Below 10−6 of the nominal flow a step is a no-flow step: no heat is exchanged, the outlet shows the stagnant fluid (Tout=Tf=A) and the pressure drop is zero. A negative mass flow is by default treated as the same flow entering at the other port (the borehole is symmetric); it can also be treated as no flow or refused, and the dynamic model can run its node network backwards. The ground state is the same in every case. Because A does not depend on the flow, the outlet always lies between the inlet and the stagnant fluid.

24.2.3 Borehole models in the stepper

Flow dependence. Rb* and the pressure drop depend on the flow (convection, laminar flow at low Reynolds numbers, the internal short-circuit between the pipes). They are tabulated for the project's pipe network at relative flows 2k/16 and interpolated in lnṁ, Rb* linearly and Δp on log-log axes. The table contains the nominal flow exactly (k=0), so at the nominal flow both values are identical to those of the design calculation. The fluid properties are evaluated at the project's fluid property temperature.

24.2.4 Set-up, pre-conditioning and state

24.3 The co-simulation master

The master couples the borehole field with FMI 2.0 co-simulation FMUs and signal sources. Each FMU integrates itself between communication points; BoreTherm exchanges signals only at the points tk=t0+khc, with hc the communication step (default 600 s; the last step ends at the stop time).

24.3.1 System, ports and units

A system is a directed graph of blocks with ports. Blocks are the borehole field of the project (at most one), any number of FMUs, constants and time tables (from a file or entered in the table; hold or linear interpolation, optionally repeating). A connection leads from an output to an input, uj=acyi+bc, where the factor and offset come from the units of the two ports or are given explicitly. A unit is resolved from the FMU's unit definitions (exponents of the SI base units with factor and offset) or from BoreTherm's own table; two units with equal exponents convert as

vto=ffromvfrom+ofrom−otofto
(24.7)

Mass and volume flow convert with the fluid density. Temperature differences are not distinguished from temperatures: a port that carries a difference must declare a unit without offset (K), or the connection needs an explicit factor and offset. A connection whose units do not convert is an error; a port without unit passes the value unchanged with a warning.

Table 44. Ports of the borehole field in the co-simulation system (heat rates positive into the ground).
InputsOutputs
inlet temperature T_in [°C], or the heat rate into the ground Q_ground [W] (one of the two drives the field)outlet temperature T_out, mean fluid temperature T_f, wall temperature T_b [°C]
mass flow m_flow [kg/s] (not connected: the project's circulation flow)Q_ground and Q_flow = −Q_ground [W]; the inlet temperature used; m_flow; pressure drop dp [Pa]

24.3.2 Direct feedthrough, algebraic loops and the order of evaluation

An output depends directly on an input when a change of the input at a communication point changes the output at the same point. For an FMU this is read from the model structure of its model description (no dependency list means all inputs); every output of the borehole field depends directly on its inputs (the closure (24.5)); sources have no inputs. A port graph with one node per connected output and an edge wherever a connection feeds an input on which another output depends directly reveals the algebraic loops: its strongly connected components (Tarjan 1972). A depth-first search that reaches the outputs of the borehole field last marks the connections to be cut, so that the remaining graph is free of loops. Cutting where the loop leaves the field means that the values carried over are the field's outlet and mean fluid temperatures, the slowest signals in the loop. The blocks are evaluated in a topological order of the remaining graph (Kahn 1962).

24.3.3 One communication step

  1. Advance. Every block advances from tk to tk+1 with its inputs held at their values at tk: one FMI step for an FMU, one stepper step for the field (driven by the inlet temperature or by the ground heat rate), the value of tk for a source. The outputs obtained with the held inputs are recorded at tk+1 and checked against the limits, as the hourly simulation reports the end of each hour with that hour's load.
  2. Settle. At tk+1 the blocks are visited in the evaluation order (Gauss–Seidel: each block uses the newest outputs of the blocks before it) and recompute the outputs that depend directly on their inputs. FMI 2.0 permits setting inputs and reading outputs between steps for this; an FMU without direct feedthrough is not called. For the field the closure is evaluated for a step of length zero, nothing being committed. A cut connection carries either the value at the end of the step just taken (explicit coupling, the default; the coupling error is of first order in the step) or the fixed point of the loop (iterate).
  3. Hold. The inputs held over the next step are the settled outputs of their sources.

Iteration. With iterate, the sweep of step 2 is repeated. A cut input x is first updated by relaxed substitution, xn+1=xn+ωfn, and then by secant steps,

xn+1=xn−fnxn−xn−1fn−fn−1,f=G(x)−x
(24.8)

with G(x) the value of the source after a sweep; a secant step more than 100 times the substitution step falls back to substitution (for kinks such as a switching controller). The iteration has converged when every input changes by no more than tol·max(1,|u|) (default 10−6) within the allowed number of sweeps; otherwise the step is counted and reported as not converged.

Step iteration (implicit coupling). When every FMU in an algebraic loop can save and restore its state (the stepper always can), the blocks of the loop can repeat the whole step with rollback: save the states, advance with the loop inputs held at a trial value, settle, compare, restore and update the trial value by the same substitution and secant rule. At convergence the loop inputs held over the step equal their values at its end, which is a backward (implicit) treatment of the loop. For a heat pump that prescribes its source heat rate through its return temperature, the field then extracts exactly the prescribed heat over the step, and the coupled result equals the load-driven result to rounding.

24.3.4 Long periods: the hybrid mode

A coupled run costs one FMU step per block and communication step: 25 years at 1 h are 219 000 steps. In the hybrid mode (the automatic choice for periods above 2 years) the first year is coupled, and the ground heat rate and field flow of every step of that year are kept. The middle years replay them through the same stepper as a prescribed load, scaled per year with a growth factor r,

Qk,y=ry−1Qk,1,y=2,…,N−1
(24.9)

and the last year is coupled again with fresh FMU instances started at its beginning, from the ground state that the replay left. Without feedback from the field to the ground load (a heat pump with constant COP driven by its heat rate) the hybrid mode equals the full run to rounding. With a COP that follows the field temperature it is conservative: as the field cools over the years the COP falls, the compressor supplies a larger share of the heat and less is taken from the ground, which the replay of year 1 does not see (Section 24.4). The full mode couples every year and should be used for the final check.

24.3.5 Sizing with the co-simulation

Size with the co-simulation finds the shortest mean borehole length H in the sizing range for which the coupled run keeps the mean fluid temperature within the design limits (over the whole period, or the last year only). The criterion

F(H)=[Tf,min(H)≥Tf,min,limandTf,max(H)≤Tf,max,lim]
(24.10)

is assumed to be monotone in H, all boreholes being scaled in proportion. Both ends of the range are run first (a failing upper end: not converged; a passing lower end: the lower end is the result). Then k lengths inside the bracket are run at once (k parallel jobs) and the bracket shrinks to the first passing length and the last failing one below it, until it is narrower than the tolerance. Every length is a full coupled run with its own g-function (from the disk cache when it exists). Several FMU instances run in parallel when they are isolated in separate processes, or in one process when the FMU allows several instances per process; an FMU is not necessarily safe to run in several threads.

24.3.6 Supported FMUs, trust and isolation

BoreTherm imports FMI 2.0 co-simulation FMUs with binaries for 64-bit Windows. FMUs for model exchange only (BoreTherm has no ODE solver for them), FMI 1.0 and 3.0, FMUs with sources only and FMUs for other platforms only are refused with a message that names the reason; an FMU that needs its generating tool installed is accepted with a warning. Reading an FMU (unpacking, its model description, a SHA-256 hash of the file) never runs its code.

An FMU contains native program code, so BoreTherm asks before it runs one: the FMU trust dialog shows the model name, the generating tool, the file and its SHA-256, and "Do not trust" is the default. The decision is stored per hash, not per file name; a changed file has another hash, is marked on its block and is asked about again. By default every FMU instance runs in its own host process with a watchdog (60 s per call): a crash or a hang ends the run with a message, not BoreTherm. Running in-process is about ten times faster per step and meant for trusted, well-behaved FMUs. Values pass between the processes as exact bit patterns, so both modes give identical numbers.

24.4 Worked example: an office heat pump coupled to the field

The example is an office building with a field of 16 single-U boreholes of 150 m (4 × 4 grid, 6 m apart; 2400 m in total). The heating load (184 MWh a year in monthly steps, 43 kW in January) is a table source that feeds a heat pump FMU, which takes its heat from the field. The FMU is a small demonstration model with

COP=ηTsinkTsink−Tsource,Qground=−Qbuilding(1−1COP)
(24.11)

in kelvin, with η = 0.5, Tsink = 35 °C and a COP of at least 1.5. Its source temperature is the field outlet, and its ground heat rate drives the field: an algebraic loop, which the master cuts at the connection from the field outlet to the heat pump. The run covers 7 days with a communication step of 1 h and explicit coupling. Table 45 derives the results of the first step.

Table 45. The first step and the summary of the 7-day example run (step 1 h, explicit coupling, isolated host).
ResultHow it is obtainedExample
Steps(stop − start) / step604 800 s / 3600 s = 168
COP at 1 h(24.11); source = field outlet held from 0 h0.5 · 308.15 / (308.15 − 282.66) = 6.044
Electric powerbuilding load / COP43 000 / 6.044 = 7114 W
Ground heat rate−(building load − electric power), negative = extraction−35886 W
Outlet temperatureTf−Qground/(2ṁcp), the field closure8.517 + 35.89 kW / (2 · 8.20 kg/s · 3.877 kJ/(kg K)) = 9.081 °C
Tf,min / Tf,maxover the values at the ends of the steps6.401 °C (168 h) / 8.517 °C (1 h)
Limits metTf,min ≥ −3 °C and Tf,max ≤ 20 °Cyes
Ground energyintegral of the ground heat rate from the stepper's energy−21.35 GJ = −5.93 MWh
FMU callsone step and one exchange per step, plus start and end344 for 168 steps

The field cools under the constant January load; the outlet temperature falls and the COP falls with it, from 6.044 at the start to 5.49 after 7 days. The COP recorded at 1 h is computed from the outlet temperature of 0 h held over the first step. This lag is the error of the explicit coupling; it is of first order in the step and small when the loop is slow, as here. Table 46 shows it: from 10 min to 1 day, explicit and iterated coupling differ by a few thousandths of a kelvin in Tf,min. A fast loop (a controller, a small buffer tank) needs a shorter step or iteration.

Table 46. Influence of the communication step and the coupling in the 7-day example.
StepTf,min explicit [°C]Tf,min iterate [°C]Explicit − iterate [mK]Tf,max [°C]FMU calls expl. / iter.
10 min6.40126.4012−0.028.872024 / 11132
1 h6.40116.4013−0.148.52344 / 1937
6 h6.40066.4014−0.827.8064 / 460
24 h6.39866.4019−3.397.2022 / 126

Tf,max depends on the step for another reason: it is the value at the end of the first step, while the field cools from the undisturbed ground. A longer step records it later, and lower.

Run over 25 years with a step of 1 h (with the table source repeating every year), the hybrid and the full mode give the results of Table 47. In the full run the heat taken from the ground falls from 150.4 MWh in year 1 to 142.5 MWh in year 25, because the COP falls as the field cools. The hybrid mode replays the 150.4 MWh of year 1 every year and over-cools the field; the length it sizes is longer.

Table 47. Hybrid and full long-term mode of the example over 25 years.
25 years, step 1 hHybrid (automatic)Full
Lowest Tf−2.00 °C (year 24)−1.43 °C (year 25)
Coupled steps17 520219 000
Size with the co-simulation138.4 m (22 coupled runs)130.7 m (22 coupled runs)

24.5 Export of the borehole field

The reverse direction brings BoreTherm's field into other simulation tools. Three forms are available: an FMI 2.0 co-simulation FMU, a Modelica model with fluid ports that runs BoreTherm's stepper, and a Modelica data record for the borefield models of the common Modelica building-simulation libraries.

24.5.1 The field as an FMU

Export FMU on the Field layout page writes the field of the current project, with its own borehole model and settings, as an FMI 2.0 co-simulation FMU for 64-bit Windows. The FMU runs the stepper of Section 24.2: the ground history of the whole field and the steady, short-time or dynamic borehole model. It contains the project (without its co-simulation system and thermal response test data), the stepper settings, a pre-computed g-function and its documentation; its identifier is a hash of everything that defines it, so the same export gives the same FMU.

Table 48. Variables of the exported borehole-field FMU.
VariableCausalityUnitMeaning
T_ininputKinlet temperature; start value: the undisturbed ground temperature
m_flowinputkg/smass flow of the field (negative: reverse); start value: the nominal flow
Q_groundinputWground heat rate (positive into the ground), used when the heat-rate input is switched on
T_out, T_f, T_boutputKoutlet, mean fluid and mean wall temperature
Q_flow, Q_meanoutputWheat rate into the fluid at the end of and averaged over the last step
dpoutputPapressure drop at the current flow
T_in_usedoutputKthe inlet used (with the heat-rate input: the resulting one)
nominal valuescalculated parameterSInominal flow, pressure drop, start temperature, total length
project inputsfixed parameterSIselected inputs, e.g. the ground conductivity, set before the initialisation

Outputs change only in a step. The FMU declares no direct feedthrough: after a step its outputs are the values at the end of the step with the inputs held over it. An importer therefore never sees an algebraic loop through the field. The FMU handles variable communication steps, can save, restore and serialise its state (a state of another FMU or project is refused), and can be instantiated several times in one process; each instance has its own stepper. At the initialisation it uses the embedded g-function when no parameter has changed and the stop time lies within the embedded horizon (no computation); otherwise it computes the g-function through the disk cache.

Built-in field and exported FMU. In BoreTherm's own master the built-in field answers the settled inputs at every communication point (Section 24.3.3), and the inputs held over the next step are its settled outputs. The exported FMU cannot do that, because its outputs do not depend on its inputs at a communication point. A system with the built-in field and the same system with the exported FMU therefore differ by a first-order coupling term: 0.11 K at a step of 1 h in the verification case with the field driven by its inlet temperature. When the field is driven by its heat rate the fluid temperatures agree, and only the components that read the field outlet differ. Fed with the same inputs, the exported FMU reproduces the outlet of the built-in field to 4·10−14 K.

24.5.2 The Modelica borefield model

BoreTherm ships a Modelica package with a borefield model between two fluid ports, based on version 4 of the Modelica Standard Library. The model runs BoreTherm's stepper itself: any project, any input changed by parameter (as on the command line), the steady, short-time or dynamic borehole model and the pre-conditioning of the ground. It samples the inlet temperature (in the flow direction) and the mass flow at tk=t0+kτs (default sample period 3600 s) and, at tk+1, advances the stepper over [tk,tk+1] with them held: a zero-order hold. Event iterations at a sample get the cached result; other inputs at the same time roll the last step back first. The fluid leaving the model follows the sampled outlet Ts through a first-order filter,

dTdt=Ts−Tτf
(24.12)

with the time constant τf=τs/2 by default, so that the outlet enthalpy is continuous for the Modelica solver; the filter delays the outlet by about τf compared with the stepper. The hydraulics are a regularised quadratic resistance through the nominal pressure drop at the nominal flow, without mass storage. BoreTherm computes with the project's fluid, while the enthalpy of the Modelica medium follows the outlet temperature: a medium with another specific heat changes the energy by the ratio of the specific heats, so the medium should be close to the project's fluid. Compared with the stepper on a prescribed ten-day series of inlet temperatures with hourly samples, the sampled outlet of the model agrees to 5·10−10 K.

An exported FMU can also be used in Modelica through an adapter of the same package that provides the fluid ports.

24.5.3 The field as a Modelica data record

The design can be written as a data record for the borefield models of the common open-source Modelica building-simulation libraries: ground (conductivity and volumetric heat capacity as specific heat and density), filling (grout), and configuration (single-U, or double-U in parallel; nominal flow per borehole, nominal pressure drop of the field, borehole length, radius and depth, the coordinates of every borehole, pipe radius, conductivity and wall thickness, half the shank spacing). Optionally the record fixes the borehole resistance to BoreTherm's Rb* at the nominal flow, so that the library skips its own resistance calculation.

24.6 Limits of the co-simulation