HomeFeaturesExamplesTutorialsHelpTheoryVerificationPricingContact
BoreTherm / TutorialsTutorial 18 / 19
Workflow and theory · Advanced physics

Co-simulation with FMUs

How an external model, for example a heat pump exported as an FMU (Functional Mock-up Unit: a simulation model packed in one file by the FMI standard), runs coupled to the borehole field step by step: the system, FMU trust, the exchanged signals, the step size and the long-term mode, and how the results come about. The numbers are those of the example project: an office building with a field of 16 single-U boreholes of 150 m (4 × 4 grid, 6 m apart); its heating load (184 MWh a year in monthly steps, 43 kW in January) goes into a heat pump FMU that takes its heat from the field; the run covers 7 days in steps of 1 h.

01 / The one idea

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.

At every communication step h (the example: h = 1 h, 7 days)Building heating loadTable block [kW]held per rowHeat pumpFMU bt_hp_coptCOP from T_sourceBorehole fieldbuilt-in blockg-function stepperQ_heat → Q_buildingkW → W (× 1000)Q_ground [W]> 0 = injectionT_out → T_source, °C → Km_flow → m_flow [kg/s]dashed: the connection wherethe algebraic loop is cut
The example. The heat pump needs the outlet temperature of the field, and the field needs the heat rate of the heat pump: an algebraic loop. BoreTherm cuts it at the wire leaving the field.
Demonstration heat pump (FMU)COP = η Tsink / (Tsink − Tsource)
Its ground heat rate (< 0 = extraction)Qground = −Qbuilding (1 − 1/COP)
Field: mean fluid temperatureTf = (Tin + Tout) / 2
Field: outlet with the heat rate givenTout = 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.

02 / The workflow

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).

What decides the ground load?Is the heat pump described bydatasheet points and the Loads page?yesnoDesign › Heat pump (the project’s)loads from the Loads page, monthly or hourlyCOP from the fluid temperature, ≤ 5 passesCalculate, Size borehole length, reportthis is the design of the projectAdvanced analysis › Co-simulationyour own model as an FMI 2.0 FMU:controls, storage, building, heat pumpexchanged at every step (e.g. 1 h)separate results; Apply length if wantedTypical use: design with Design › Heat pump, then check the field against the dynamic system model of the HVAC engineer.
The project’s heat pump lives in Design › Heat pump. The co-simulation is an advanced check with an external model; it never changes the design by itself.
Advanced analysis › Co-simulationSystemblock diagram: blocks,ports, wires, unitsFMU: ‹name›identity, SHA-256, trust,parametersSettingsstep, period, coupling,host; Run / Test / SizeResultssummary, time series,years, warnings, CSVDesign › Field layoutH of every borehole; ExportFMU: the field for other toolsLoads pagea note: the co-simulationdoes not use these loadsReport › section“Co-simulation”: blocks,FMUs, settings, resultsApply length to project (after sizing): sets H of every borehole
Advanced analysis › Co-simulation: one page per FMU block appears after System. The co-simulation keeps its own results; only Apply length to project writes back.
  1. 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.
  2. 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).
  3. 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.
  4. Run co-simulation, or Size with the co-simulation. Then read Results and, if wanted, apply the length.
Design › Heat pumpCo-simulation
WhereDesign › Heat pump: Setup, Equipment selection, Selection resultsAdvanced analysis › Co-simulation: System, FMU pages, Settings, Results
Building loadsLoads page (monthly or hourly)a Table or Constant block, or the FMU itself; the Loads page is not used
Heat pump modeldatasheet points: COP = η · COPCarnot, capacity, backup heater, EERany FMI 2.0 Co-Simulation FMU (64-bit Windows): your model with its controls
Couplingwhole simulation repeated until the SPF (seasonal performance factor) is stable (≤ 5 passes, change < 0.01)signals exchanged at every communication step
SizingSize borehole lengthSize with the co-simulation: a coupled run at every length tried
ResultsResults pages and the whole reportCo-simulation › Results; report section “Co-simulation”
Effect on the designit is the project’s designnone, until you press Apply length to project
03 / FMU trust and the exchanged signals

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.

Add an FMUdrag a .fmu ontoSystem, or the tool barInspect, no code runsunzip, read the XML,SHA-256 of the fileThis SHA-256trusted before?Runisolated processper FMU, watchdogyesnoTrust this FMU?model, tool, file, SHA-256 shown;“Do not trust” is the defaultTrust: storedper SHA-256Do not trust: the run stops;trust later on the FMU pageA changed file has another SHA-256: a warning (“file changed”) on the block, and the question is asked again. The CLI trusts every FMU.
Trust is remembered per SHA-256 of the file, not per file name. Inspecting an FMU (its identity, variables, units) never runs its code.

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.

BlockInputsOutputs
Borehole fieldT_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
04 / How one step is calculated

How one step is calculated

1 Analyse the systemports, units, loops, the order;no FMU code runs2 Initialiseparameters, start values,one consistent point at t₀3 Advance t_k → t_k+1every block, inputs held:fmi2DoStep / the stepper4 Record at t_k+1outputs of the held inputs;T_f extremes, year sums5 Settle at t_k+1Gauss–Seidel in the order;cut wire: y⁻ or iteratet_k+1 < stop?k = k + 1yes → next stepno → summary: T_f min / max and when, limits met, years, FMU identities, statistics
The master of the co-simulation (core/src/fmi/master.cpp). The recorded values are those at the end of each step with the inputs held over it, as the hourly simulation reports the end of each hour.
  1. 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.
  2. Advance. Every block steps from tk to tk+1 with its inputs held at their values of tk: fmi2DoStep for an FMU, the stepper for the field (driven by Q_ground here).
  3. 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).
Hybrid long-term mode, 25 years (Automatic: hybrid above 2 years)Year 1coupled, FMUs runYears 2 … 24, no FMUsthe ground heat rate and flow of every step of year 1,× growth^(y−1), replayed through the fieldYear 25coupled againThe last year starts fresh FMU instances at its start time, from the ground state the replay left.
Long periods. A coupled run costs one FMU call per step and block (25 years at 1 h: 219,000 steps). The hybrid mode couples only the first and the last year.
05 / The theory in two pictures

The theory in two pictures

Explicit coupling: the heat pump sees the field one step late

Borehole field, 43 kW heating load024487296120144168678910hours°CT_out, to the heat pumpT_f, mean fluidT_in, from the heat pumpCOP of the heat pump FMU0244872961201441685.45.65.86.06.25.49 after 7 days6.04 at the starthoursCOP
The example, step 1 h. The field cools under a constant 43 kW heating load; the outlet temperature falls, and the COP falls with it. Tin − Tout = Q / (ṁ cp).

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

Lowest mean fluid temperature per year1510152025−3−1135hybridfulllimit −3 °Cyear°CHeat taken from the ground per year1510152025140144148152hybrid: year 1 replayedfull: falls as COP fallsyearMWh
The example run for 25 years (stop time cleared, step 1 h). Hybrid: years 2–24 replay the ground load of year 1. Full: all 25 years coupled.
The counter-intuitive part. As the field cools over the years, the COP of the heat pump falls, the compressor supplies more of the heat, and less comes from the ground (150.4 → 142.5 MWh/a in the full run). The hybrid mode replays the 150.4 MWh of year 1 every year and so over-cools the field: its lowest Tf is −2.00 °C (year 24, an extended year) against −1.43 °C in the full run. Sizing in the hybrid mode gives 138.4 m per borehole, the full mode 130.7 m. Without this feedback (a constant COP) the two modes agree to rounding.
06 / How each result is derived

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.

ResultHow BoreTherm derives itExample
Steps(stop − start) / h604800 s / 3600 s = 168
COP at t = 1 hη Tsink / (Tsink − Tsource), kelvin; Tsource = field Tout held from t = 00.5 · 308.15 / (308.15 − 282.66) = 6.044
Electricity PelQbuilding / COP43000 / 6.044 = 7114 W
Ground heat rateQground = −(Qbuilding − Pel), < 0 = extraction−35886 W
Outlet temperatureTout = Tf − Qground / (2 ṁ cp), the field’s closure8.517 + 35.88 kW / (2 · 8.20 · 3.877) = 9.081 °C
Tf min / maxover the values at the ends of the steps (and when)6.401 °C (168 h) / 8.517 °C (1 h)
Limits metTf,min ≥ −3 °C and Tf,max ≤ 20 °Cyes
Ground energy of year 1∫ Qground dt from the stepper’s energy, J → MWh−21.35 GJ = −5.93 MWh
FMU callsper step one doStep and one exchange in the settle sweep, plus start and end344 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.

07 / The example in numbers

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 hTf,min explicitTf,min iterateExplicit − iterate [mK]Tf,max explicitFMU 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.

25 years, step 1 hHybrid (default)Full
Lowest Tf−2.00 °C (year 24)−1.43 °C (year 25)
Coupled steps17520219000
Size with the co-simulation138.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.

08 / Limits to keep in mind

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…).