Knowledge Base: Generating CIBSE TM59:2017 Compliance Reports with the TM59 Report Plugin

Applies to: DesignBuilder v7.3 and v2025.1.1.011 • Plugin: DesignBuilder TM59 Report Plugin

Overview

The TM59:2017 Report generates a CIBSE TM59:2017 overheating compliance report directly from DesignBuilder, as a PDF or an editable Word document (.docx). It combines the currently loaded model with the TM59:2017 simulation outputs (eplusout.eso, produced by a run with the CIBSE TM59 outputs selected) and evaluates each dwelling zone against the TM59:2017 criteria:

• Criterion (a): for living rooms, kitchens and bedrooms in predominantly naturally ventilated zones, the number of occupied hours over May to September during which ΔT (the operative temperature minus the adaptive comfort threshold Tmax) is greater than or equal to 1K shall not exceed 3% of occupied hours.
• Criterion (b): for bedrooms, the number of hours between 22:00 and 07:00 during which the operative temperature exceeds 26°C while the room is occupied shall not exceed 32 hours (1% of the annual hours in that period); 33 hours or more is recorded as a fail.
• Criterion (c): for predominantly mechanically ventilated zones, the operative temperature shall not exceed 26°C for more than 3% of occupied hours.
• Communal areas (corridors): for corridors and other circulation spaces, the proportion of hours during which the operative temperature exceeds 28°C should not exceed 3%. This is an advisory check only: a communal area that exceeds it is reported as a "Significant risk", but it never affects the overall PASS/FAIL verdict.

The report includes a cover page with the overall PASS/FAIL verdict, building details, the settings used by the run, an optional project team, the software versions used, a per-zone summary matrix, one detail table per criterion, the modelled-zones inventory and any warnings.

The same plugin also produces TM59:2026 reports, from its TM59:2026 Report menu item (see TM59:2026 Report). Use the item for the edition your simulation was run for. DesignBuilder v7.3 does not produce TM59:2026 results, so on v7.3 use TM59:2017 Report; on v2025.1.1.011, use whichever edition you simulated.

See also: TM59:2017 help for v7.3 and v2025.1

Installation

The TM59:2017 Report is part of the TM59 Report plugin, the same plugin as the TM59:2026 Report. If that is already installed, there is nothing more to install: skip to Requirements.

The plugin is loaded from the per-user plugins folder when DesignBuilder starts.

1. Download the plugin package from the DesignBuilder Scripts and Plugins webpage: you'll need to be logged in to your DesignBuilder account to see the download.

2. Locate your User Plugins folder. With DesignBuilder open, choose File > Folders > Library data folder: this opens the folder in File Explorer; go up one level, and you'll see the User Plugins folder listed. (Or paste %LOCALAPPDATA%\DesignBuilder\User Plugins\ into the File Explorer address bar: %LOCALAPPDATA% expands automatically, so you don't need to know your Windows username.)

3. Close DesignBuilder.

4. Unzip the downloaded file DbTm59Report.zip and copy the Tm59Report folder it contains into the User Plugins folder. The zip already bundles everything the plugin needs: DbTm59ReportPlugin.dll, System.Data.SQLite.dll with its x86\ and x64\ interop sub-folders, EpNet.dll, and DocumentFormat.OpenXml.dll with DocumentFormat.OpenXml.Framework.dll (for Word output), so there's no need to copy files one by one.

If the plugin fails to load after a restart, additionally copy DB.Api.dll and DB.Extensibility.Contracts.dll from your DesignBuilder installation (in v2025.1.1.011, from <install>\Lib\) alongside the plugin DLL.

5. Start DesignBuilder. The first time you start it after installing a new plugin, you may be asked to confirm it's from a trusted source: click Yes to allow it. A TM59 menu appears under Plugins, with the items TM59:2026 Report, TM59:2017 Report and About (which shows the plugin and DesignBuilder versions). The two report items are greyed out until a model is loaded.

To uninstall or temporarily disable the plugin, close DesignBuilder and delete (or move) the plugin folder, then restart.

See also: How to install DesignBuilder plugins

Requirements

Before generating the report, check the following:

1. A model using the TM59 activity templates. The plugin identifies TM59 zones purely by their activity template. Recognised templates:

Zones with any other activity template are ignored. Zones with Include zone in thermal calculations switched off are also left out, as they are not simulated.

Note that the 4-bed and 5-bed activity templates (TM59_4-BedKitchen, TM59_5-BedKitchen, TM59_4-BedLiving, TM59_5-BedLiving, TM59_4-BedLivingKitchen, TM59_5-BedLivingKitchen) and TM59_HomeOffice cannot be reported under TM59:2017.

2. A completed TM59:2017 simulation, run with the TM59 outputs selected under Simulation Calculation options > Output tab > Graphable Outputs:

• CIBSE TM59: always;
• Mechanical ventilation: when any zones are predominantly mechanically ventilated (set on the HVAC tab);
• Vulnerable occupants: when the occupants are vulnerable (Category I);
• Corridors: to include communal areas in the report.

These options are the same in v7.3 and v2025.1.1.011. Run a full annual simulation (1 January – 31 December), as DesignBuilder's TM59:2017 modelling guide requires; the plugin refuses a run period that does not cover at least 1 May – 30 September.

3. A results folder containing both of:

• eplusout.eso, with the run-period EMS output variables produced by those options (CIBSE TM59 Criterion A …, CIBSE TM59 Criterion B …, CIBSE TM59 Mechanically Ventilated …, CIBSE TM59 Corridors …), and
• the EnergyPlus input file (in.idf) that produced it. The plugin reads this companion file as the ground truth for the simulated settings and will not generate a report without it (see How the plugin verifies the run below).

4. Results simulated from the model that is open: the in.idf next to the results must name this model file, in this folder, as its source.

Using the plugin

Step 1: Run the TM59:2017 simulation

Run your TM59:2017 simulation with the CIBSE TM59 outputs selected (see Requirements), so that the results folder contains eplusout.eso and in.idf. Either the current EnergyPlus folder or a Simulation Manager job can be used as the source.

Step 2: Open the report dialog

With the model loaded, select the building you want to report on in the navigator (the report is scoped to the currently selected building), then choose Plugins > TM59 > TM59:2017 Report.

If no TM59 activity templates are found in the selected building, the plugin tells you so and lists the recognised template names.

Step 3: Complete the dialog

- Project: the project title shown on the report cover and running header (pre-filled from the building/site Title attribute). TM59:2017 reports have no project phase.

- Project team: optional Modeller and Reviewed by details (name and role), a Company name and an optional company Logo (PNG or JPEG), printed in the report's Project team section. The company name also appears in the footer ("Prepared by …"), and the logo replaces the DesignBuilder logo on the cover page and page headers. Leave them blank to omit them. They are remembered on this computer for your next report.

- Results file: pick one of:

- EnergyPlus folder: path to an eplusout.eso (defaults to the current EnergyPlus folder), or

- Simulation Manager results: a list of FINISHED jobs from the Simulation Manager database that were run on the currently open model. Each job's results are read from that job's own results folder. Jobs whose folder has no results file show "Not found" in red; for those, switch to "EnergyPlus folder" and browse to the file manually. Select several jobs (Ctrl/Shift + click, or Ctrl+A) to generate one report per job, each named after the output file with the job's start time added. The job's description is printed in the report's Building details section, unless it is empty or the same as the building name.

- Output: the format (PDF or Word document (.docx)) and where to save the report (defaults to TM59_2017_Report.pdf in your Documents folder, or in the folder you last saved a report to). Close the file first if you are overwriting a previous report, as the plugin checks and will ask you to close it.

- Zone evaluation: one row per standard (non-circulation) zone showing its activity template and detected mechanical-ventilation / cooling status, with the evaluation branch:

- Natural (Criteria A + B), or

- Mechanical / cooled (Criteria B + C).

The branch is preset automatically (see below) but can be overridden per zone. To change several zones at once, select their rows and use the Set selected zones to buttons below the table, or right-click the selection; Reset returns the selected zones to the detected branch. Circulation areas are not listed: they are always assessed under the advisory corridors check.

Under TM59:2017, the Mechanical branch is assessed against Criterion (c), whose results DesignBuilder only produces for occupied, non-cooled zones that are mechanically ventilated, with the Mechanical ventilation output selected. Zones that are cooled are preset to Mechanical too: if their results have no Criterion (c) output, the report is refused (see Troubleshooting).

Step 4: Generate

Click Generate report. The plugin evaluates every zone, writes the report and (with "Open when done" ticked) opens it. With several Simulation Manager jobs selected, the button changes to Cancel while the reports are generated, a summary of every job's outcome is shown at the end, and "Open when done" opens the output folder instead.

How the plugin verifies the run (important)

To prevent reports that silently disagree with the simulation they claim to describe, the plugin treats the EnergyPlus input file next to the results (in.idf) as the ground truth for what was actually simulated:

• Source model: the in.idf records the model file it was generated from. If that is not the model that is open (including a copy of it saved in another folder), report generation is refused.
• Occupant category (Category I vulnerable / Category II standard) is detected from the TM59 reporting objects in the in.idf, overriding the model's Vulnerable occupants output setting if they differ. The report's Settings section shows it, together with the natural ventilation rules read from the in.idf.
• Per-zone mechanical ventilation and cooling are detected from the simulation and preset the Natural/Mechanical evaluation branch in the dialog.
• The simulation period is read from the in.idf. If it does not cover 1 May – 30 September, report generation is refused: re-run the simulation for the full year.
• The weather file shown in the report is the one named in the in.idf, so it is the weather file the simulation was actually run with.

The plugin also won't generate a report when any zone's expected results are missing from the .eso (typically caused by selecting the wrong results file, results from a different building, or a stale run), so no partial report is ever written. The one exception is communal areas: TM59:2017 does not require them to be reported, so when the run had no Corridors output they are shown as N/A, with a note under Warnings, and the report is still generated.

A non-blocking note under the zone grid reminds you that model-sourced supporting information (zone areas, activity templates) always reflects the model as currently open, which may have been edited since the run.

Troubleshooting

Notes

• Criteria thresholds are fixed at the TM59:2017 values and are not user-editable: 3% of occupied hours for Criteria (a) and (c), 32 hours for Criterion (b) (33 hours or more is recorded as a fail), and 3% of hours for the communal-areas check. Each criterion is judged directly on the percentage or hours simulated for the zone.
• Threshold temperatures reflect the detected occupant category: Category I (vulnerable / sensitive occupants) reduces the Criterion (a) adaptive threshold by 1K relative to Category II. The Criterion (b) and (c) thresholds (26°C) and the communal-areas threshold (28°C) are the same for both categories.
• The overall verdict is PASS only when every applicable Criterion (a), (b) and (c) check passes. Communal areas never affect it; when any is flagged as a significant risk, the cover page notes it alongside the verdict.
• The report footer records the company name ("Prepared by …", when entered), the DesignBuilder version, the generation date/time and "Report Page X of Y" on every content page. The plugin version is shown in the report's Software section.
• In the PDF, the cover page is not numbered: page numbering starts at 1 on the first content page.
• The TM59:2017 report has no project phase and no ceiling-fan active-hours table: both are part of the TM59:2026 report only.