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.
| Design heat pump of the project | Co-simulation | |
|---|---|---|
| Building loads | Loads page (monthly or hourly) | a table or constant source, or the FMU itself |
| Heat pump model | data-sheet points; COP as a fraction of the Carnot COP | any FMI 2.0 co-simulation FMU with its own controls |
| Coupling | whole simulation repeated until the seasonal performance factor is stable | signals exchanged at every communication step |
| Sizing | Size borehole length | Size with the co-simulation: one coupled run per trial length |
| Effect on the design | it is the design | none 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 and the mass flow of the field (or, alternatively, the heat rate into the ground); its outputs are the outlet temperature , the heat rate into the fluid , the mean fluid temperature , the mean borehole wall temperature and the pressure drop . A load per metre is positive into the ground, as everywhere in BoreTherm, so that with 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,
with the undisturbed ground temperature, the ground conductivity and the dimensionless step response of the field. The history is held on an internal grid of step (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 of any length is split at the internal grid points. Inside an internal step, at the fraction of it, the incomplete step acts with the running mean of its load. With over its earlier sub-intervals and the yet unknown load of the current sub-interval of length :
The wall temperature at the end of the sub-interval is then linear in :
where is the response to the committed steps. When the internal step is complete, its mean load 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 goes into 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 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,
the load follows in closed form:
When the field is driven by a prescribed heat rate instead, and the inlet and outlet temperatures are .
Low, zero and reverse flow. The effectiveness of the closure,
exceeds 1 for , that is at very low flow: the outlet would overshoot the wall side . The closure is therefore limited to the full exchange, ; the limit is continuous at and never active at design flows. Below of the nominal flow a step is a no-flow step: no heat is exchanged, the outlet shows the stagnant fluid () 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 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
- Steady model. with the effective borehole resistance , so and .
- Short-time model (heat capacity of the borehole). The ground part is that of (24.3); the resistance part adds as in the steady model; a capacity correction , which vanishes after 100 h, is convolved over the last committed steps and the incomplete step. With one sub-interval per internal step this is exactly the short-time convolution of the hourly simulation. For a step of length zero at a step boundary the outlet shows the fluid of the last step: the inertia of the fluid column.
- Dynamic model. The thermal resistance and capacity network of the borehole (Bauer et al. 2011) on depth levels, with plug flow of the fluid down and up the pipes. Each sub-interval of length is one step of the dynamic field with the wall coupled as in (24.3), divided into sub-steps of a fraction of the transit time. The ground aggregation receives the wall heat flux, while is the heat taken up by the fluid; the two differ by the heat stored in the fluid and the grout. The outputs are the means over the last sub-interval of a communication step. An evaluation at the current time (a step of length zero) runs a probe step of s on a copy, so the outlet is the fluid that leaves the field now, independent of the new inlet (the transit delay). With the pump off no heat is exchanged and a prescribed heat rate is not delivered. The internal step is the project's dynamic time step (default 300 s); with it, a stepper driven by the hourly loads of the simulation reproduces its outlet temperatures to rounding.
Flow dependence. 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 and interpolated in , linearly and on log-log axes. The table contains the nominal flow exactly (), 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
- g-function. Computed on the logarithmic time grid of the simulation from the internal step to the pre-conditioning plus the horizon, with a margin. It can also be given as a table (an exported FMU carries one). Computed g-functions are kept in a disk cache keyed by a cryptographic hash of the inputs that can change them, so a repeated run, or a sizing that returns to a length, does not compute them again.
- Pre-conditioning. The ground can start disturbed: a number of years of a constant load, or of the project's own loads (monthly base loads without peaks, or the hourly series), pushed through the aggregation and the borehole model before the start. This represents a field that has already been in operation when the system model starts.
- State. The complete state (time, the incomplete step, the aggregation cells, the borehole model's nodes) can be saved and restored bit for bit, and written to bytes with a fingerprint of the set-up; a state of another set-up is refused. A failed step leaves the stepper unchanged. This is what allows the master to repeat a step (step iteration) and an FMU importer to roll back.
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 , with 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, , 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
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.
| Inputs | Outputs |
|---|---|
| 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
- Advance. Every block advances from to with its inputs held at their values at : 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 for a source. The outputs obtained with the held inputs are recorded at and checked against the limits, as the hourly simulation reports the end of each hour with that hour's load.
- Settle. At 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).
- 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 is first updated by relaxed substitution, , and then by secant steps,
with 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 (default ) 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 ,
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 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
is assumed to be monotone in , 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 lengths inside the bracket are run at once ( 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
in kelvin, with = 0.5, = 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.
| Result | How it is obtained | Example |
|---|---|---|
| Steps | (stop − start) / step | 604 800 s / 3600 s = 168 |
| COP at 1 h | (24.11); source = field outlet held from 0 h | 0.5 · 308.15 / (308.15 − 282.66) = 6.044 |
| Electric power | building load / COP | 43 000 / 6.044 = 7114 W |
| Ground heat rate | −(building load − electric power), negative = extraction | −35886 W |
| Outlet temperature | , the field closure | 8.517 + 35.89 kW / (2 · 8.20 kg/s · 3.877 kJ/(kg K)) = 9.081 °C |
| / | over the values at the ends of the steps | 6.401 °C (168 h) / 8.517 °C (1 h) |
| Limits met | ≥ −3 °C and ≤ 20 °C | yes |
| Ground energy | integral of the ground heat rate from the stepper's energy | −21.35 GJ = −5.93 MWh |
| FMU calls | one step and one exchange per step, plus start and end | 344 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 . A fast loop (a controller, a small buffer tank) needs a shorter step or iteration.
| Step | explicit [°C] | iterate [°C] | Explicit − iterate [mK] | [°C] | FMU calls expl. / iter. |
|---|---|---|---|---|---|
| 10 min | 6.4012 | 6.4012 | −0.02 | 8.87 | 2024 / 11132 |
| 1 h | 6.4011 | 6.4013 | −0.14 | 8.52 | 344 / 1937 |
| 6 h | 6.4006 | 6.4014 | −0.82 | 7.80 | 64 / 460 |
| 24 h | 6.3986 | 6.4019 | −3.39 | 7.20 | 22 / 126 |
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.
| 25 years, step 1 h | Hybrid (automatic) | Full |
|---|---|---|
| Lowest | −2.00 °C (year 24) | −1.43 °C (year 25) |
| Coupled steps | 17 520 | 219 000 |
| Size with the co-simulation | 138.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.
| Variable | Causality | Unit | Meaning |
|---|---|---|---|
| T_in | input | K | inlet temperature; start value: the undisturbed ground temperature |
| m_flow | input | kg/s | mass flow of the field (negative: reverse); start value: the nominal flow |
| Q_ground | input | W | ground heat rate (positive into the ground), used when the heat-rate input is switched on |
| T_out, T_f, T_b | output | K | outlet, mean fluid and mean wall temperature |
| Q_flow, Q_mean | output | W | heat rate into the fluid at the end of and averaged over the last step |
| dp | output | Pa | pressure drop at the current flow |
| T_in_used | output | K | the inlet used (with the heat-rate input: the resulting one) |
| nominal values | calculated parameter | SI | nominal flow, pressure drop, start temperature, total length |
| project inputs | fixed parameter | SI | selected 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 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 (default sample period 3600 s) and, at , advances the stepper over 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 through a first-order filter,
with the time constant by default, so that the outlet enthalpy is continuous for the Modelica solver; the filter delays the outlet by about 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 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 at the nominal flow, so that the library skips its own resistance calculation.
- Refused with the list of reasons: inclined boreholes, coaxial or triple-U pipes, groundwater flow, connections other than all boreholes in parallel, borehole sections, and boreholes of different length, depth or radius.
- Approximated with a note each: ground layers become one ground with the effective conductivity and heat capacity; the pipe contact resistance is left out; the geothermal gradient belongs to the borefield model, not the record, and is given in the record's documentation (the mean undisturbed temperature, or the surface temperature with the gradient).
24.6 Limits of the co-simulation
- Only FMI 2.0 co-simulation FMUs with 64-bit Windows binaries. Inputs are held constant over each step (no input derivatives); check a design with a shorter step, or with iteration, before trusting it.
- Extremes are taken at the ends of the steps. An event shorter than the step is not seen.
- The hybrid mode replays year 1; with a COP that follows the field it overstates the ground load of the middle years. The last year restarts the FMUs from their initial states.
- The loads of the Loads page and the design heat pump are not used, except to pre-condition the ground when the field block is set to the project's loads.
- Results are marked out of date after any change of the project. A coupled sizing changes nothing until Apply length to project; Calculate and Size borehole length must then be run again for the design results.
- BoreTherm checks the coupling, not the physics inside an FMU. A demonstration heat pump without capacity limit, backup heater or part-load behaviour is a teaching model.