The one idea: a report is a snapshot
A report does not calculate the design. It writes down three things as they are at that moment: the inputs of the project, the results that are in memory (from Calculation › Calculate, Calculation › Size borehole length and the other runs) and a profile that says which sections to write and how. Change an input afterwards and the report no longer matches the project.
wanted ∧ appliesticked in the profile, or client sectionits results exist (e.g. a sized length)Sections are numbered after this test, so “section 13” in one report can be another section in the next. Refer to sections by title.
The workflow
Reports are made on the Report page, the last item of the page tree, or without a window from the command line.
Templates are report profiles: a JSON file with the title block (company, author, project number, logo, page header and footer), the units (energy MWh or kWh, Darcy velocity), the chart size, the page format (A4 or Letter), the report language (independent of the program language) and the section choice. Save profile… writes it; the same file works in the dialog and in batch mode. The title block of the Project page wins over the profile.
How a report is built
Out-of-date results. Every change of an input raises the project’s input revision. Calculate, Size borehole length and Calculation › Optimize record the revision they were computed for; if any of them differs from the current one, the report opens with the banner OUT OF DATE – the inputs were changed after these results were computed; the input sections show the current inputs. The parametric study, Monte Carlo and the heat pump selection carry their own banners; the co-simulation and the 3D analysis (Calculation › Run 3D analysis) get a note in their own section. A new Calculate or Size borehole length run drops the design results of older inputs: one flag covers them all.
Which simulation. The Results summary, the temperature chart, the annual table and the g-function (the dimensionless temperature response of the field to a constant heat load) show the last simulation: after Calculate the field at the project’s lengths, after Size borehole length the field at the sized length (source “Sizing (H = …)”). The thermal plume needs Calculate (or a 3D analysis), so it disappears after Size borehole length.
Where the numbers come from
Input sections echo the project. Result sections read one result each: the two most read numbers, the minimum mean fluid temperature Tf,min (Tf: the mean of the inlet and outlet temperature of the fluid in the boreholes) and the required length, come from these two calculations.
The matrix shows the source of every section; the shaded rows are the 16 sections of the full report of the example.
Each reported number and how it is derived
The example’s values, from the same calculations as the report (boretherm-cli simulate, size and cost). Section numbers are those of the full report of the example.
--run simulate,size the Results summary shows the field at the project’s 150 m (Tf,min −2.41 °C) and the Required borehole length section the sized 143.7 m (Tf,min −3.00 °C); in the program, Size borehole length after Calculate replaces the summary with the field at the sized length. The cost estimate uses the lengths of the project: 2400 m, not 2299.5 m. To report the sized design consistently, Apply length on the sizing page, run Calculate, then write the report.| Sect. | Number | How BoreTherm derives it | Example |
|---|---|---|---|
| 2 | Undisturbed ground temperature Tm | Ts + qgeo H / (2λ) (classic mid-depth rule; the buried depth is not used); Ts surface temperature, qgeo geothermal heat flux, λ ground thermal conductivity | 9 + 0.06 · 150 / (2 · 2.6) = 10.73 °C |
| 2, 11 | Diffusivity α; time scale ts | α = λ / C (C volumetric heat capacity); ts = H² / (9α) | 1.1818 mm²/s; 67.1 years |
| 4, 8 | Rb* effective resistance | Rb*: thermal resistance from the mean fluid temperature to the borehole wall (Rb: of the cross-section alone; Ra: between the down- and up-going pipe). Multipole (order 3) cross-section + convection at the flow; uniform heat flux along the depth | 0.1194 m·K/W (Rb 0.1151, Ra 0.4397) |
| 5, 8 | Reynolds number, pressure drop | pipe flow at the flow per borehole and the fluid at the property temperature | 4958; 189.6 kPa per loop |
| 5, 8 | Pump power | total flow · Δp / pump efficiency | 8.0 l/s · 189.6 kPa / 0.5 = 3033 W |
| 6 → 8 | Ground load (Loads page → field) | heat · (1 − 1/SPF) + DHW · (1 − 1/SPFDHW) − cooling · (1 + 1/SPFc), per month; peaks the same way. SPF: seasonal performance factor of the heat pump (heat delivered / electricity); DHW: domestic hot water | heating peak 100 kW · (1 − 1/3.8) = 73.7 kW |
| 8, 9, 10 | Minimum mean fluid temperature | Tm + Σ Δq g / (2πλ) + q Rb*, month-end base load with the peak pulse added; Δq: load steps per metre, g: the g-function | −2.41 °C (heating peak, year 25, January); limit −3 °C |
| 8 | Lowest inlet temperature, freezing margin | Tf − Q / (2 ṁ cp); margin to the freezing point of the fluid | −2.41 − 73.7 / (2 · 31.8) = −3.57 °C; margin 6.22 K to −9.8 °C |
| 13 | Required length per borehole H | all lengths scaled until Tf,min or Tf,max is at its limit (tolerance 0.1 m) | 143.7 m, 12 simulations; total 16 · H = 2299.5 m |
| 14 | Cost estimate (net) | quantities of the design × unit prices; computed when the report is written | 5000 + 16 · 800 + 2400 m · 45 + 90 m · 60 = 131,200 € |
| 14 | Cost per kW of peak extraction | net total / peak ground extraction | 131,200 / 73.7 = 1781 €/kW |
| 16 | SHA-256 of the project file | of the saved file; of the project JSON when unsaved or modified | 45f33c3bd7dae1ac… |
The example in numbers
Three reports of the example project, written headless with BoreTherm (BoreTherm.exe --report … --profile … --run … --format …):
| Report | Sections | PDF pages | Figures | Results summary from |
|---|---|---|---|---|
| Full report, Calculate + Size borehole length, warnings and appendix ticked | 16 | 16 | 8 | Calculation |
| Client summary, Calculate + Size borehole length | 4 | 3 | 2 | Calculation |
| Full report, Size borehole length only (--run size) | 15 | 14 | 7 | Sizing (H = 143.7 m) |
Full report sections: Project information, Site and ground, Borehole field, Borehole design, Heat carrier fluid and flow, Loads, Simulation settings and assumptions, Results summary, Mean fluid temperature, Annual minimum and maximum, g-function, Thermal plume, Required borehole length, Cost estimate, Warnings and limitations, Appendix: input data and reproducibility. The client summary: Project information, Results summary, Mean fluid temperature, Required borehole length. Without Calculate (the third row) the report loses Thermal plume and its Results summary shows the field at the sized length.
Every HTML report starts with a comment that holds the version, the time, the project file, its SHA-256 (45f33c3bd7da…), the sections written and the profile; the Markdown file has the same in its first line; the PDF footer shows version, date and the first 12 characters of the SHA-256.
A reproducible report, and limits
- Save the project first. Only a saved, unmodified project is hashed from its file; otherwise the report says “not saved” and hashes the project data.
- Make the results current: Calculate, and Size borehole length if you report a length. No OUT OF DATE banner may remain.
- Tick Warnings and Appendix. They are off in a new profile; the appendix holds the input echo (every input as stored, SI units), the version, the SHA-256, the runs and the profile.
- Save the profile next to the project, set the report language explicitly, and keep the BoreTherm version.
- Write it again without a window:
BoreTherm.exe --report project.boretherm --profile profile.json --run simulate,size --format pdf,html. Batch mode runs the calculations it is told to (simulate, size, optimize, study, montecarlo); the co-simulation, the heat pump check and the 3D analysis are not run there.
- The cost estimate and the input sections are written from the current inputs; results sections from the last runs.
- The client summary is a fixed set: project information, results summary, fluid temperature, required length, and, when they exist, the system comparison, Monte Carlo and the TRT design result.
- The report adds no checks of its own: Warnings and limitations repeats the warnings of the calculations, the limit check and the geometry check of the cross-section.
Numbers calculated with BoreTherm. Reports written with BoreTherm in batch mode.