The one idea: the field and the model talk at every step
In a normal calculation the ground load is fixed before the simulation starts. In a co-simulation it is not: an external model computes it from what the field returns. The heat pump sees the brine (the antifreeze fluid in the boreholes) coming out of the field; its COP (coefficient of performance: heat delivered per unit of electricity) follows that temperature; the heat it takes from the ground follows the COP. BoreTherm and the model exchange these values at fixed communication points tk = t0 + k·h and integrate on their own in between.
COP = η Tsink / (Tsink − Tsource)Qground = −Qbuilding (1 − 1/COP)Tf = (Tin + Tout) / 2Tout = Tf − Qground / (2 ṁ cp)The FMU of the example uses η = 0.5 and Tsink = 35 °C (kelvin inside the FMU; COP at least 1.5). The field is BoreTherm’s own: the g-function (the dimensionless temperature response of the field to a constant heat rate) with load aggregation (older load steps lumped into longer blocks), stepped by the co-simulation stepper (BoreTherm theory manual); the energy balance of the fluid gives the outlet temperature.
The workflow
BoreTherm has two places for a heat pump. They answer different questions; the co-simulation does not replace the design. The design is checked with Calculation › Calculate (the fluid temperatures over the years) and sized with Calculation › Size borehole length (the borehole length that meets the fluid limits).
- System: add the borehole field (at most one), the FMUs, tables and constants. Drag from an output to an input to connect. Each wire shows its unit conversion; red wires and badges are errors.
- FMU page: check the identity (model, tool and the SHA-256, a fingerprint of the file content) and set parameters (empty = the FMU’s own start value).
- Settings: communication step, period, coupling, long-term mode, host. Press One-day test run first: it checks the wiring, the units and the FMUs in seconds.
- Run co-simulation, or Size with the co-simulation. Then read Results and, if wanted, apply the length.
| Design › Heat pump | Co-simulation | |
|---|---|---|
| Where | Design › Heat pump: Setup, Equipment selection, Selection results | Advanced analysis › Co-simulation: System, FMU pages, Settings, Results |
| Building loads | Loads page (monthly or hourly) | a Table or Constant block, or the FMU itself; the Loads page is not used |
| Heat pump model | datasheet points: COP = η · COPCarnot, capacity, backup heater, EER | any FMI 2.0 Co-Simulation FMU (64-bit Windows): your model with its controls |
| Coupling | whole simulation repeated until the SPF (seasonal performance factor) is stable (≤ 5 passes, change < 0.01) | signals exchanged at every communication step |
| Sizing | Size borehole length | Size with the co-simulation: a coupled run at every length tried |
| Results | Results pages and the whole report | Co-simulation › Results; report section “Co-simulation” |
| Effect on the design | it is the project’s design | none, until you press Apply length to project |
FMU trust and the exchanged signals
An FMU is a zip file with a Windows DLL inside. Running it means running someone else’s program code, so BoreTherm asks first.
Isolated host (default): each FMU instance runs in its own boretherm-fmuhost.exe process. A crash or a hang (watchdog, default 60 s per call) stops the run with a message, not BoreTherm. In-process is about ten times faster, for trusted, well-behaved FMUs. Values pass as exact bit patterns, so both give the same numbers.
Signals. Every port has a unit. A wire converts between the declared units (°C ↔ K, kW ↔ W, mass ↔ volume flow with the fluid density) or uses your own factor and offset. A temperature difference must be declared in K, or the °C offset is applied wrongly.
| Block | Inputs | Outputs |
|---|---|---|
| Borehole field | T_in [°C] or Q_ground [W] (connect one: it drives the field); m_flow [kg/s] (not connected: the project’s flow) | T_out, T_f, T_b [°C]; Q_ground, Q_flow = −Q_ground [W]; T_in used; m_flow; dp [Pa] |
| Heat pump FMU (demo) | Q_building [W], T_source [K], m_flow [kg/s] | Q_ground [W], T_return [K], P_el [W], COP_actual |
| Table / Constant | — | one output per column / the value “y”, with the unit you give |
How one step is calculated
- Analyse. Ports and units, conversions, the evaluation order (a topological order of the blocks) and the algebraic loops. A loop through the field is cut at the wire leaving the field, because the field’s temperatures are the slowest signals.
- Advance. Every block steps from tk to tk+1 with its inputs held at their values of tk:
fmi2DoStepfor an FMU, the stepper for the field (driven by Q_ground here). - Settle. At tk+1 the blocks are visited in order (Gauss–Seidel: each block uses the newest outputs of the blocks before it) and recompute the outputs that depend directly on their inputs. The cut wire carries the value of the end of the step just taken, y⁻ (Explicit), or is iterated to a fixed point (Iterate: substitution, then secant steps, until the relative change ≤ tolerance; with Repeat each step with rollback, the step itself is repeated until the loop is consistent).
The theory in two pictures
Explicit coupling: the heat pump sees the field one step late
The COP recorded at 1 h is computed from the outlet temperature of 0 h, held over the first step. The error of this lag is first order in h, and it is small when the loop is slow, as here: the field changes little in one hour. The table in section 7 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 Iterate.
The hybrid mode is conservative when the COP depends on the field
How each result is derived
Co-simulation › Results shows the summary, the recorded time series, the years and the warnings. Worked example: the end of the first step of the example.
| Result | How BoreTherm derives it | Example |
|---|---|---|
| Steps | (stop − start) / h | 604800 s / 3600 s = 168 |
| COP at t = 1 h | η Tsink / (Tsink − Tsource), kelvin; Tsource = field Tout held from t = 0 | 0.5 · 308.15 / (308.15 − 282.66) = 6.044 |
| Electricity Pel | Qbuilding / COP | 43000 / 6.044 = 7114 W |
| Ground heat rate | Qground = −(Qbuilding − Pel), < 0 = extraction | −35886 W |
| Outlet temperature | Tout = Tf − Qground / (2 ṁ cp), the field’s closure | 8.517 + 35.88 kW / (2 · 8.20 · 3.877) = 9.081 °C |
| Tf min / max | over the values at the ends of the steps (and when) | 6.401 °C (168 h) / 8.517 °C (1 h) |
| Limits met | Tf,min ≥ −3 °C and Tf,max ≤ 20 °C | yes |
| Ground energy of year 1 | ∫ Qground dt from the stepper’s energy, J → MWh | −21.35 GJ = −5.93 MWh |
| FMU calls | per step one doStep and one exchange in the settle sweep, plus start and end | 344 for 168 steps |
Recorded by default: the field’s T_in, T_out, T_f, T_b, Q_ground, m_flow and every connected output; the example adds hp.P_el and hp.COP_actual (Settings › recorded outputs). The ground energy is negative: heat taken from the ground.
The example in numbers
Settings of the example: step 3600 s, stop time 7 days (604800 s, which overrides the period in years), explicit coupling, isolated host. Result (expected file): Tf 6.401 … 8.517 °C, limits −3 / 20 °C met, 168 steps, 344 FMU calls.
| Step h | Tf,min explicit | Tf,min iterate | Explicit − iterate [mK] | Tf,max explicit | 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 |
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.
| 25 years, step 1 h | Hybrid (default) | Full |
|---|---|---|
| Lowest Tf | −2.00 °C (year 24) | −1.43 °C (year 25) |
| Coupled steps | 17520 | 219000 |
| Size with the co-simulation | 138.4 m (22 coupled runs) | 130.7 m (22 coupled runs) |
The example project’s note mentions 25 years in the hybrid mode, but its settings stop after 7 days; the 25-year rows were run with the stop time cleared. The table block repeats yearly (12 rows of 730 h, 184 MWh of heat a year), which is not the Loads page of the project.
Limits to keep in mind
- FMI 2.0 Co-Simulation FMUs with 64-bit Windows binaries only. Model Exchange, FMI 1.0 and 3.0 are refused.
- Inputs are held constant over each step (no input derivatives). Check a design with a shorter step, or with Iterate, 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 over-states the ground load of the middle years (section 5); use Full for the final check. The last year restarts the FMUs from their initial states.
- The Loads page and 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. Sizing changes nothing until Apply length to project; then run Calculate and Size borehole length again for the design results.
- The demonstration FMU is a teaching model: no capacity limit, no backup heater, no part load. Your own FMU is only as good as its model; BoreTherm checks the coupling, not the physics inside the FMU.
Numbers calculated with BoreTherm. The heat pump of the example is an FMU (SHA-256 a2b19286354ec6c4…).