The one idea: one project, many copies, one answer each
A parametric study asks “what if?” for inputs of one project. It makes a copy of the project for every case, sets the case’s values in it, and sizes the borehole length (or simulates) as Size borehole length (menu Calculation › Size borehole length) or Calculate (menu Calculation › Calculate) would. Everything that is not varied stays at the project value. The study adds no physics: each case is an ordinary design calculation.
Each run reports the borehole length H, the total length, the lowest and highest mean fluid temperature Tf,min / Tf,max over the period (Tf is the average of the fluid temperatures entering and leaving the boreholes), the undisturbed mean ground temperature Tm, the borehole thermal resistance Rb between fluid and borehole wall, the effective resistance Rb* (Rb plus the heat exchange between the pipes inside the borehole), the pump power, the effective ground conductivity λ eff and, when sized, which limit was limiting.
vk = min + k · step, k = 0 … ⌊(max − min)/step⌋, or a listN = n1 · n2 · n3N = 1 + n1 + n2 + …smallest H with Tf,min ≥ Tmin and Tf,max ≤ TmaxThe maximum is part of the range when it lies on the grid (within 10−9). An explicit list replaces min, max and step. The study can vary 29 inputs of this project; boretherm-cli params lists them with their units and bounds.
The workflow
Choose the tool by the question, then choose what each case reports.
- Parametric study…, menu Tools › Parametric study. Kind: full grid (every combination of 1–3 parameters) or one at a time (each parameter alone, the others at their project values). Result: size the borehole length, or simulate at the current length. The table has one row per parameter: project value, values (list), minimum, maximum, step and the number of runs. The dialog shows the total runs and, after a first study, an estimated time; above 2000 runs it warns.
- Parametric study (Advanced analysis › Studies & uncertainty). Chart: one result against the first parameter, one line per value of the second (or a heat map); with a third parameter, one slice at a time. One at a time: a tornado chart. Table: every run with its values, results, limiting temperature and status; Export CSV gives the same columns as
boretherm-cli study --csv.
How the calculation works
Size runs the full sizing of Size borehole length in every case, with the project’s sizing options. Simulate runs the simulation of Calculate at the current length. Most inputs (loads, SPF, limits, fluid, pipes, grout, flow) do not change the g-function, the dimensionless temperature response of the field to a constant heat rate, so cases of one geometry share one g-function instead of computing it again. For homogeneous ground a conductivity sweep shares one too, rescaled through the time scale ts = H²/(9α) (α = λ/C, the thermal diffusivity); the difference is a few mK. The studies of the program use the analytic g-function.
What is varied and what is held
Each parameter has a setter. Most set one number; some do more:
| Parameter | What the setter changes |
|---|---|
| ground.conductivity | λ of the ground; the volumetric heat capacity C stays, so the diffusivity changes too. Tm follows Ts + qgeo · H / (2 λ), with Ts the surface temperature and qgeo the geothermal heat flux. |
| layout.spacing | B1 = B2 = B; the field is regenerated, each borehole keeps H, D and rb. Circle: B is the chord. Custom: scaled about the centroid. |
| borehole.H | the mean length; equal lengths all get it, unequal ones are scaled in proportion. |
| loads.heatingScale, coolingScale, dhwScale | multiply that energy (monthly MWh, hourly kW); project value 1. |
| loads.peakScale | multiplies every monthly peak power (monthly loads only). |
| spf.*, limits.*, settings.years | set the value (SPF: seasonal performance factor of the heat pump); years are rounded to whole years. |
| all others (ground, design, fluid, flow, …) | set the one value; nothing else changes. |
A value outside the parameter’s sanity bounds (for λ 0.1–10 W/(m K)) makes that case fail with a message; the other cases complete. The project value itself leaves the copy unchanged bit for bit, so the base run of a one-at-a-time study is the project.
Reading the results: two modes, one physics
The same grid, once simulated at the current 150 m and once sized:
A one-at-a-time study ranks inputs by their swing. The tornado below varies six inputs of this project, each over a range an engineer might check, with the others at their project values (Size mode):
How each result is derived
The columns of the table, with run 1 of the example (λ = 2.0 W/(m K), B = 5 m, Size):
| Result | How BoreTherm derives it | Run 1 |
|---|---|---|
| H | Size: the smallest length in H min … H max that keeps Tf within both limits (as Size borehole length). Simulate: the current mean length. | 168.47 m, limiting: Tf,min |
| Total length | N · H (Σ Hi) | 16 × 168.47 = 2695.5 m |
| Tf,min / Tf,max | extremes of the mean fluid temperature over the period (or the last year) | −3.00 °C / 16.69 °C |
| Tm | Ts + qgeo · H / (2 λ) | 9 + 0.06 × 168.47 / (2 × 2.0) = 11.53 °C |
| Rb | multipole method: pipes, grout, shank spacing and the ground λ | 0.1155 m K/W |
| Rb* | Rb + (H / ṁcp)² / (3 Ra), Ra the internal resistance between the pipes: grows with H | 0.1208 m K/W |
| Pump power | ΔP · V̇ / ηpump (pressure drop × volume flow / pump efficiency): grows with H | 3407 W |
| λ eff | conductivity over the active length (layered ground: the effective value) | 2.0 W/(m K) |
| Status | OK; not converged (Size: limits not met within the range, H = H max); failed (message) | OK |
Rb changes a little with λ because the multipole method includes the ground around the borehole; Rb* and the pump power follow the sized length.
The example in numbers
| λ [W/(m K)] | H at B = 5 m (total) | H at B = 7 m (total) | 5 → 7 m saves | Tm at 5 / 7 m [°C] |
|---|---|---|---|---|
| 2.0 | 168.5 m (2695 m) | 154.3 m (2469 m) | 14.2 m (8.4 %) | 11.53 / 11.31 |
| 2.6 | 150.8 m (2414 m) | 138.3 m (2212 m) | 12.6 m (8.3 %) | 10.74 / 10.60 |
| 3.2 | 137.1 m (2193 m) | 125.7 m (2012 m) | 11.4 m (8.3 %) | 10.29 / 10.18 |
- All 6 cases converged and none failed. Every case is sized to Tf,min = −3 °C: heating decides; Tf,max stays below 17.4 °C.
- Wider spacing saves 8.3–8.4 % of the length at every conductivity: the lines of the chart are nearly parallel. The two inputs hardly interact, so a one-at-a-time study would have told almost the same story with fewer runs.
- The project itself (λ = 2.6, B = 6 m) is not one of the six cases. The mean of the 5 m and 7 m results is 144.6 m; sized directly it needs 143.7 m (the base run of the one-at-a-time study). The response is curved: add the project value to a range when you need it.
- Apply run to project on run 6 sets λ = 3.2 W/(m K) and B = 7 m. The length stays 150 m until Size borehole length sizes it to 125.7 m.
Limits to keep in mind
- A study answers “what if” for the values you enter. It gives no probability; for a length at a confidence level use Monte Carlo.
- One at a time misses interactions. A full grid shows them but takes at most three parameters, and the runs multiply: three parameters with ten values each are 1000 sizings.
- In Size mode a case that cannot meet the limits within H min … H max is marked not converged; its H is the longest length of the range, not a required length. Widen the sizing range.
- A varied spacing regenerates a generated layout; it does not move a custom field’s boreholes one by one (it scales the field about its centroid).
- The program’s studies use the analytic g-function. With the FEM (finite-element) engine, check the chosen case with Size borehole length again.
- Each case is as good as the design model: monthly or hourly loads, the borehole model and the ground model of the project apply unchanged.
Numbers calculated with BoreTherm. The one-at-a-time ranges are an illustration, not recommendations.