HomeFeaturesExamplesTutorialsHelpTheoryVerificationPricingContact
BoreTherm / TutorialsTutorial 19 / 19
Workflow and theory · Reporting

The report

What goes into a report, which result feeds which section, the templates and formats, the short client report, out-of-date results, and how to write a report that someone else can reproduce. The example project is a small office building (about 3000 m²) with monthly loads of 200 MWh/year space heating, 8 MWh/year hot water and 45 MWh/year cooling, on a 4 × 4 field of 16 boreholes of 150 m at 6 m spacing, simulated over 25 years.

01 / The one idea

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.

Project inputsthe project file andits SHA-256Results in memoryCalculate, Size boreholelength, Optimize, studies …each with source and timeReport profilesections, title block, units,language, chart sizeReport buildersections in a fixed order;a section is written whenit is wanted and applies;numbered 1, 2, 3 …PDFA4 or Letter; header,footer with SHA-256HTMLone file, charts inside,version + profile in a commentMarkdown + PNGreport.md anda figures folderone HTML body per report, converted to every format
All formats come from the same HTML body, so a PDF and an HTML file of the same run contain the same numbers.
A section is written whenwanted ∧ applies
wantedticked in the profile, or client section
appliesits 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.

02 / The workflow

The workflow

Reports are made on the Report page, the last item of the page tree, or without a window from the command line.

Report pagethe last item of thepage treeReport… (Ctrl+Shift+P)choose, preview, then GenerateExport PDF report (Ctrl+P)PDF with the saved profileReport files‹stem›_report.pdf / .html‹stem›_report_md\report.mdProject pagecompany, prepared by, projectno.: win over the profileAutomatic reportafter every Calculate, Sizeborehole length, Optimize,study, Monte Carlo runBatch, no windowBoreTherm.exe --report--profile --run --formatsame profiletitle block
Report… opens the dialog: preset, section checklist (sections without results are greyed), title block, units, language, formats, folder, automatic reports, preview. Export PDF report writes at once with the saved profile.
Inputs complete; Calculate, Size borehole lengthInputs changed sincethe last calculation?yesRun them againCalculate, Size boreholelength; else every pagesays OUT OF DATEnoWho reads it?clientcheckerTRTClient summaryproject information, resultssummary, fluid temperature,required length (+ comparison,Monte Carlo, TRT result)Full reportevery section with results;tick Warnings and Appendix(off in a new profile): inputecho, SHA-256, profileTRT evaluationVDI 4640-5 contents of athermal response test(project with a test,or a .trt.json file)Custom: tick the sections yourself. Save the choice as a profile (JSON) to use it again.
First make the results current, then choose the report for its reader.

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.

03 / How a report is built

How a report is built

1 Freeze the inputspending edits committed;SHA-256 of file or of JSON2 Title and bannerproject info › profile;OUT OF DATE, DEMO DATA3 Next section in order29 sections, cover first,appendix lastwanted andapplies?4 Render and numberHTML + charts (16 × 8.5 cm,200 dpi); an error → a note5 Write the formatsPDF, HTML, Markdown + PNGfrom the same bodyyesno: skipnext sectionallwanted: ticked in the profile, or part of the client summary when that is on.applies: the section has its results (e.g. Required borehole length needs a Size borehole length run).
app/report/ReportBuilder.cpp. A section that fails to render does not stop the report: it shows a note instead.

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.

04 / Where the numbers come from

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.

Annual extremes at H = 150 m (sections 8, 10)1510152025−30369121518maximum, with cooling peakminimum, with heating peaklimit −3 °Cyear°CSize borehole length: Tf,min against H120150180210240270300−4−20246H = 143.7 m12 trial lengths,the last 2 with the exact gH [m]°C
Left: the annual extremes of the 25-year simulation at 150 m; the minimum −2.41 °C in year 25 is the value of the Results summary. Right (section 13): the trial lengths of Size borehole length (one more at 20 m is off the scale); the sized length is where Tf,min meets the limit.

The matrix shows the source of every section; the shaded rows are the 16 sections of the full report of the example.

Section (report order)Other source, or when it appearsClientSize boreholeInputsCalculatelengthProject informationtimes of the runsSite and groundBorehole fieldSite planonly with a site planBorehole designRb, Ra, Rb* of the last runHeat carrier fluid and flowBorehole connectionsnot all in parallelLoadsSimulation settingsResults summarythe last simulationMean fluid temperaturethe last simulationAnnual minimum and maximumthe last simulationg-functionHourly temperatureshourly loads onlyDynamic borehole modeldynamic model / verificationThermal energy storagestorage (BTES) operationThermal plumeor the 3D analysisRequired borehole lengthLayout optimizationOptimizeCost estimatecomputed when writtenSystem comparisoncomparison set upHeat pump selectionCheck candidatesParametric studystudy runMonte Carlo simulationMonte Carlo runCo-simulationsystem or co-simulation runTRT, 9 sectionsstored test; design part3D analysis (FEM)3D analysis runWarnings and limitationsoff in a new profileAppendix: input echooff in a new profilein the full report of the examplesourcewhen present (else computed from the inputs)
Client: the sections of the client summary, whatever the checklist says (a section still needs its results). Inputs: written from the project at report time. Calculate, Size borehole length: the result of that command.
05 / Each reported number and how it is derived

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.

Two numbers, two lengths. In batch mode with --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.NumberHow BoreTherm derives itExample
2Undisturbed ground temperature TmTs + qgeo H / (2λ) (classic mid-depth rule; the buried depth is not used); Ts surface temperature, qgeo geothermal heat flux, λ ground thermal conductivity9 + 0.06 · 150 / (2 · 2.6) = 10.73 °C
2, 11Diffusivity α; time scale tsα = λ / C (C volumetric heat capacity); ts = H² / (9α)1.1818 mm²/s; 67.1 years
4, 8Rb* effective resistanceRb*: 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 depth0.1194 m·K/W (Rb 0.1151, Ra 0.4397)
5, 8Reynolds number, pressure droppipe flow at the flow per borehole and the fluid at the property temperature4958; 189.6 kPa per loop
5, 8Pump powertotal flow · Δp / pump efficiency8.0 l/s · 189.6 kPa / 0.5 = 3033 W
6 → 8Ground 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 waterheating peak 100 kW · (1 − 1/3.8) = 73.7 kW
8, 9, 10Minimum mean fluid temperatureTm + Σ Δ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
8Lowest inlet temperature, freezing marginTf − 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
13Required length per borehole Hall 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
14Cost estimate (net)quantities of the design × unit prices; computed when the report is written5000 + 16 · 800 + 2400 m · 45 + 90 m · 60 = 131,200 €
14Cost per kW of peak extractionnet total / peak ground extraction131,200 / 73.7 = 1781 €/kW
16SHA-256 of the project fileof the saved file; of the project JSON when unsaved or modified45f33c3bd7dae1ac…
06 / The example in numbers

The example in numbers

Three reports of the example project, written headless with BoreTherm (BoreTherm.exe --report … --profile … --run … --format …):

ReportSectionsPDF pagesFiguresResults summary from
Full report, Calculate + Size borehole length, warnings and appendix ticked16168Calculation
Client summary, Calculate + Size borehole length432Calculation
Full report, Size borehole length only (--run size)15147Sizing (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.

07 / A reproducible report, and limits

A reproducible report, and limits

  1. 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.
  2. Make the results current: Calculate, and Size borehole length if you report a length. No OUT OF DATE banner may remain.
  3. 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.
  4. Save the profile next to the project, set the report language explicitly, and keep the BoreTherm version.
  5. 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.