Introduction to ESP-r

John Allison, Ian Beausoleil-Morrison, Valentina

Bonetti, Gian Luca Brunetti, Parag Cameron-Rastogi,
Stephane Citherlet, Joe Clarke, Jeremy Cockroft,
Daniel Cóstola, Jordan A. Denev, Ery Djunaedy, Eli
Mathias Duggan, Alex Ferguson, Graeme Flett, Achim
Geissler, Jon Hand, Alaa Liaq Hashem, Dariusz Heim,
Jan L.M. Hensen, Deeksha Hota, Milan Janak, Karel
Kabele, Nick Kelly, Georgios Kokogiannakis, Gavin
Lavery, Bartosz Lomanowski, Toby Mackintosh, Lori
McElroy, Raheal McGhee, Filippo Monari, Cezar O. R.
Negrao, Luciana Oliveira, Luis Prazeres, Mohamad
Rida, Neil Saldanha, Aizaz Samuel, Paul Strachan, Paul
Tuohy, Anna Wieprzkowicz, Adam Wills

2024
University of Strathclyde Publishing
ISBN: 978-1-914241-71-0

Editor: Daniel Cóstola

This document is distributed under the Creative Commons License CC BY-SA 4.0.
For updates, visit http://www..esru.strath.ac.uk/
Contents
About this document 1
PART 1 Introduction to ESP-r 5
Introduction 7
1 Overview of ESP-r capabilities 8
2 ESP-r exemplars 18
Installing ESP-r 31
3 Before installing ESP-r 32
4 Windows: Run Ubuntu using WSL 33
5 Linux: Install compiling from source code 36
6 macOS: Compile from source on Apple Silicon processors 44
7 Install supporting software 48
Thermal Domain 49
8 Exploring a thermal model 50
9 Exploring results of a thermal model 85
10 Changing climate data and HVAC controls 110
11 Changing model geometry and materials 128
12 Creating a new thermal model 148
13 Thermal model with a PV panel 165
14 Exploring exemplars variants 173
Bulk Fluid Flow Domain 175
15 Exploring an airflow network 176
16 Analysing the results of an airflow network 181
17 Creating a new airflow network 187
Contaminant Domain 205
18 Exploring a contamination network 206
19 Contaminant concentration in airflow networks 210
20 Creating a new contaminant network 214
Electrical Domain 225
21 Exploring an electrical model 226
22 Exploring results of an electrical network 237
23 Create electrical network with a PV panel 241
Explicit Plant & Systems Domain 273
24 Opening, inspecting and running a HVAC model 274
25 Analysing the results of a HVAC model 285
26 Editing a HVAC model 290
Idealised Plant & Systems Domain 297
27 Opening, inspecting and running a model with idealised HVAC 298
28 Exploring results of a model with idealised HVAC 305
29 Implementing an idealised HVAC system in a model 308
Moisture Domain 321
30 Exploring a model with moisture transfer 322
31 Exploring results with moisture transfer 329
CFD domain 335
32 Exploring a model with CFD 336
33 Exploring CFD results 344
Lighting Domain 357
34 Lighting domain 358
Productivity tools 361
35 Automating tasks in ESP-r 362
36 Uncertainty analysis 376
37 Variants 391
Source Code 397
38 Exploring the source code 398
39 Editing the source code 406
40 Debugging 415
41 Validation 422
PART 2 res - the result analysis application for ESP-r 425
Starting res 427
42 ESP-r result files 428
43 Starting res using the command line 433
44 Starting res using ESP-r Project Manager prj 441
45 Main elements of res graphic interface 446
46 Module Options 454
Graph: Parameter plot 463
47 Graph types 464
48 Parameter plot menu 465
49 Assessment period and display period 480
50 Parameter plot: a weather 482
51 Parameter plot: b temperature 488
52 Parameter plot: c comfort metrics 509
53 Parameter plot: d solar processes 519
54 Parameter plot: f zone flux 523
55 Parameter plot: g surface flux 532
56 Parameter plot: h heat/cool/humidity 549
57 Parameter plot: i zone RH 560
58 Parameter plot: j casual gains 562
59 Parameter plot: m renewable/adv. comp. 567
Other types of graphs 569
60 Graph: Intra-construction temperature 570
61 Graph: 3D profile 577
62 Graph: frequency histogram 581
63 Graph: variable v. variable 586
64 Graph: network flows 588
Time-series export and post-processing 607
65 Tabular Output 608
66 Enquire about 616
PART 3 Tutorials 629
67 Create MRT sensors 630
68 Save temperature of nodes inside constructions 639
69 Import weather data to ESP-r 641
70 Use a fan curve in a fluid network 646
71 Understanding fluid flow network control files 660
72 Define solar obstructions 678
73 Disable time-step averaging of results 688
74 Create operation file from scratch 689
75 Understanding the impact of latent casual gains in the RH of the zone 695
76 Change the emissivity or absorptivity of a component 699
77 Link controls loops to thermal zones 703
78 Use custom fixed convective transfer coefficients 706
79 Create a weather file based on custom data 714
80 Modelling blinds activated as a function of temperature 721
81 Modelling adjacent zones 739
82 Calculate reverberation time 751
83 Life-cycle analysis 755
84 Computing the thermal effect of reflections from obstructions via Radiance 758
Appendix 1 Additional resources 763
85 Tips for new Linux users 764
86 WSL tips and troubleshooting 774
Appendix 2 Alternative approaches to compile ESP-r 785
87 Run Ubuntu on a VM (alternative approach for Windows) 786
88 Install using the pre-compiled installer (alternative approach for Linux) 792
89 macOS: Compile from source on Intel processor 795
About this document
An introduction to ESP-r
ESP-r is a modular, open-source, freeware, comprehensive energy simulation program
developed and validated over decades by researchers around the globe1. ESP-r is a research
code, and as such, the efforts put into software development were mainly focused on
adding new calculation functionalities rather than improving documentation and user
experience (which are often the focuses of commercial software). This explains the historical
challenge of learning ESP-r, characterised by its sparse and incomplete documentation and
its temperamental user interface. This document aims to contribute to addressing these
issues by bringing a straightforward overview of ESP-r capabilities so new users can
understand the sort of things that can simulate with this program. By addressing the main
ESP-r functionalities, this document is meant to help the reader on using building physics
knowledge and understanding regarding modelling to develop a model in ESP-r, run
simulations and analyse results.

This document was conceived as a self-contained introduction to ESP-r, and as such, it does
not assume previous knowledge of Linux (the operational system where it runs). For new
users, it provides a chance to familiarise themselves with some Linux commands and
functionalities. However, it is strongly recommended that ESP-r users invest some time
learning Linux, as this document only addresses the minimum necessary Linux features to
run ESP-r.

A collaborative documentation platform

This document was created for educational purposes and is not meant to be a
comprehensive source of documentation for ESP-r. It is a work-in-progress based on
contributions from members of the ESP-r community, moderated by ESRU. This may explain
eventual differences in writing style throughout the document.

If you want to contribute (or access the latest version of this document), visit
https://appdocs.esru.strath.ac.uk/ (where videos covering parts of this book are also
available).

Theory behind ESP-r

This document does not intend to discuss the physics or numerical methods behind ESP-r.
The source code of ESP-r is the best source of information in this regard, and this document
describes how to navigate the source code to find relevant information (even for users with
no experience in software development). The source code not only shows the calculations
done, but it often has comments pointing to PhD theses and scientific articles published by
those who developed that particular part of the code (where more information about the
physics behind it can be found). The book “Energy Simulation in Building Design” by Joe

1
See a completely list of developers at: https://www.esru.strath.ac.uk/applications/ESP-r/About.html
Clarke brings a comprehensive description of the theory behind ESP-r, and many papers
and theses are listed on the ESRU website describing specific parts of ESP-r calculations.

Learning simulation strategies

This document also does not address simulation strategies and challenges, i.e. how to
translate real design and operation questions into a simulation model and how to manage
the simulation workflow itself. In this direction, the so-called “ESP-r cookbook”, by Jon
Hand, provides a great combination of ESP-r skills and knowledge of best practices in
simulation (http://contrasting.onebuilding.org/Strategies/Index.html).

Not directly related to ESP-r, "Fundamentals of building performance simulation", by Ian

Beausoleil-Morrison, provides a series of exercises to guide new users into exploring
different energy flow paths in the model.

Many books provide broad discussions about simulation which may be useful for
experienced simulators as well as for newcomers learning ESP-r. Here are a few of them:

• "Building performance simulation for design and operation" edited by Roberto

Lamberts and Jan Hensen;

• "Building performance analysis", by Pieter De Wilde, and

• "Applied Building Performance Simulation" by Joe Clarke, Jeremy Cockroft, Jon

Hand and Raheal McGhee.

Structure of this document

ESP-r is a comprehensive application capable of solving several different sets of equations.
In this introduction, each set of equations, its dedicated assumptions, inputs, and outputs
is referred to as a domain. For each domain, the document aims at providing guidance on:

• exploring an exemplar model featuring the representative elements of that domain,

• running and exploring key results of this exemplar, and
• adding this domain to a simple model, including discussing key settings in the
model definition.

Model complexity
This book often uses models of low complexity (such as the one on the image below the
left) to describe ESP-r functionalities. However, this should not be taken as a statement of
ESP-r capabilities, which are probably better represented by the image below on the right.
The differences go beyond the fidelity of spatial representation, and also include the
modules invoked during the simulation to account for air and water movement, 3d ground
heat transfer effects, detailed HVAC systems and control representation, electrical network
with renewables, etc. The usage of low-complexity models in this book is meant to facilitate

2
the learning process, and enable users to develop fit-for-purpose models (which often
require high-fidelity complex representation of energy systems).

ESP-r learning curve

As a final remark, it is important to stress that ESP-r is certainly not the most user-friendly
simulation tool (particularly for beginners), so for users who are looking for a state-of-the-
art graphic user interface and streamlined workflow, it may not be the right tool for your
application. Having said that, ESP-r provides state-of-the-art simulation functionalities and
a range of means for automation and customisation that lead to excellent workflow for
experienced users. The learning curve is steep, and sometimes using ESP-r can be
frustrating. Still, the frustration is not an exclusive experience of using this program (user
experience can be frustrating in most applications, either because of bugs or due to their
assumptions and limitations). The key advantage of using ESP-r compared to other
simulation programs is that once users hit a wall, they have access to all the means to
circumvent the problem and/or solve the problem. Moreover, any additional functionality
developed in ESP-r can be easily included in the main source code distribution and shared
with the rest of the community. ESP-r inclusiveness is one of the key differences between
this and other open-source simulation projects. Hopefully, this document assists new users
in mastering ESP-r and benefit from its extensive capabilities.

Troubleshoot problems in ESP-r

Users facing problems installing or using ESP-r may post questions to the ESP-r community
using the mailing list (http://lists.strath.ac.uk/mailman/listinfo/esp-r) or Discord
(https://www.esru.strath.ac.uk/applications/ESP-r/Learn.html).

3
4
PART 1
Introduction to ESP-r
This guide provides information on installing and running ESP-r on multiple
platforms. It also describes application features relating to the creation and
simulation of models.

5
6
Introduction

7
1 Overview of ESP-r capabilities
1.1 A research-oriented tool for integrated energy simulation

ESP-r is a comprehensive, state-of-the-art integrated building performance simulation

suite. It comprises several applications encapsulating decades of developments and
provides tools suitable for models of different levels of complexity. In undertaking its
assessments, the system is equipped to model heat, air, moisture, light, and electrical power
flow at user-specified spatial and temporal resolution.

These are some examples of ESP-r models, showcasing its versatility to handle arbitrary
building geometries.

China Central Television (CCTV) building - Beijing . China.

Walt Disney Concert Hall - Los Angeles . USA.

8
 The Gherkin - London . UK.

1.2 Validation

ESP-r has been extensively validated:

• Strachan P A. 2000. 'ESP-r: Summary of Validation Studies.

(https://www.esru.strath.ac.uk/Documents/validation.pdf)
• Strachan, P. A.; Kokogiannakis, G.; Macdonald, I. A. (2008-04-01). "History and
development of validation with the ESP-r simulation program". Building and
Environment. Part Special: Building Performance Simulation. 43 (4): 601–609.
doi:10.1016/j.buildenv.2006.06.025.

Among other projects, ESP-r was part of BESTEST, an IEA initiative that created a benchmark
for quality assessment of energy simulation software:

• Judkoff, R.; Neymark, J. (1995). International Energy Agency building energy

simulation test (BESTEST) and diagnostic method (Report). National Renewable
Energy Lab. (NREL), Golden, CO (United States). doi:10.2172/90674. OSTI 90674.

This benchmark was later incorporated into ASHRAE Standard 140 - Method of Test for
Evaluating Building Performance Simulation Software:

9
 • Judkoff, R.; Neymark, J. (2013). Twenty Years On!: Updating the IEA BESTEST
Building Thermal Fabric Test Cases for ASHRAE Standard 140 (Report). NREL/ J.
Neymark & Associates, Golden, CO (United States). doi:10.2172/1220110. OSTI
1220110.
• "ASHRAE Standard 140 Resource Files".
(https://data.ashrae.org/standard140/AccompanyingSec5-2A.html)

Validation models are available to any user through the ESP-r interface.

1.3 Features
ESP-r is research-oriented, so the usability of the features listed below may show wide
variations. Some features are accessible to beginner users, while others require expert
knowledge of ESP-r input files and/or source code.

Dynamic multi-domain Systemic analysis Stochastic input

Thermal zonal model, air Calculations from one Capabilities to handle non-
flow, water flow, electrical domain are interlinked deterministic input for user
flow, HVAC, CFD, and with others, allowing behaviour and casual
many others fully coupled assessment of unexpected gains. Coupling with
calculation domains. interactions between obFMU, for occupant
different parts of the behaviour.
system.

10
 Time-dependent Arbitrary geometry Import CAD and BIM
material properties Capability to handle Capabilities to import DXF
Finite difference method complex, non-conventional and gbXML models.
capable of handling shapes.
variation in properties on
time-step basis, such as
changes in thermal
conductivity as a function
of moisture content.

Draw zones over Explicit thermal mass Plant module

scanned floorplans Furniture can be modelled HVAC modelling using a
Complex buildings can be considering its materials simultaneous solver,
easily modelled based on and geometry. Effects avoiding problems of poor
existing drawings. account for thermal inertia, convergence in complex
moisture buffer, shading, systems.
longwave radiation, and
convection.

11
 Coupled thermal and Electrical module Electrical-thermal
pressure calculations in Detailed calculation of coupling
plants power flows based on Detailed calculation of
Performance of pumps and equipment power factor, electrical performance of
fans calculated in cable length and PV panels in relation to
combination with thermal impedance, efficiency of their temperature.
effects of fluid flow. inverters, etc.

Fluid flow module Air or water filled zones Air quality

Flow networks coupled Multiple fluid flow Streamlined workflow with
with the other ESP-r networks can be used to Paraview to facilitate
modules. model wet systems and air visualisation of
movement. CFD. Detailed assessment
of CO2 concentration

12
 HVAC components as Lighting simulation Glare risk
zones Radiance simulations Automated calculation
Capability to explicitly integrated in ESP-r. Results using Radiance, with
model ducts, AHU and can be linked to internal results post-
other fluid flow gains due to natural and processed using EN-ISO
components as thermal artificial lighting. standards.
zones.

Moisture transfer module Mould growth risk Phase change materials

Vapour transfer to porous Results of temperature and PCM models available, as
materials, coupled with moisture contents post- well as other dynamic
airflow network and HVAC processed to indicate material properties.
performance. mould growth risk per
surface.

13
 Detailed solar Multiple convection View factor calculations
calculations empirical models Longwave radiation
Solar radiation gains per Dozens of empirical exchange based on
surface in the indoor equations implemented calculated view factor
environment using covering many convection between surfaces, instead
raytracing. regimes. of area-weighted factors.

Local thermal discomfort Temporal files Automatic calibration

PMV, radiant asymmetry, Time series can be Integration with Calibro for
thermal stratification, imposed in any node, automatic model
floor/ceiling gradient, and providing greater control calibration against
draught risk can be over the model to simulate experimental data.
assessed by covering all unusual systems or for
indicators described on validation.
ISO-7730.

14
 Sensitivity/Uncertainty 3D ground modelling CFD for every time-step
analysis Heat flux from/to buildings Fully coupled CFD solver
Integrated routines for calculated based on a 3D interacting with the
Factorial analysis or Monte ground model. thermal domain.
Carlo simulations.

CFD-AFN coupling Complex fenestration Fast simulations

Capability to model parts Window properties can be The code is written in
of the building using CFD changed on time-step Fortran, prioritising
and use air flow network basis to emulate controls simulation speed.
results as boundary and/or dynamic properties. Calculation engines are
conditions. optimised to reduce
computation time.

15
 Fully scriptable Single source code for X interface
ESP-r can be run in text calculations and GUI ESP-r uses a low-level
mode and has a The same executables library for its interface, so
straightforward scripting handle user interface and developers can implement
language that facilitates calculations, facilitating the any required feature with
automating repetitive development of the GUI by minimal constraints.
tasks. researchers.

Modularity Research-oriented Knowledge repository

ESP-r is a suite of 20 ESP-r is done for ESP-r source code has
applications, ranging from researchers, and to millions of lines and
pre-processing tools, researchers. Advances first documents many of the
calculation engines, seen in ESP-r were often advances in the field in the
visualisation, and post- ported to commercial last decades.
processing tools. software.

16
 Portability Tester QA report
ESP-r was compiled on ESP-r releases are ESP-r provides
various Unix and Linux compared to results of comprehensive reporting
distributions and previous models to ensure tools to document the
computational calculations are as reliable model for quality
infrastructures, from Solaris in new versions as in assurance and/or convey
workstations to Raspberry previous ones. information to other
Pi. stakeholders.

Coupling to TRNSYS HVAC graphic Pre-defined entities

ESP-r can exchange representation ESP-r has a library of
information during runtime Graphic network topology components and furniture
with TRNSYS to model creation tool, which is for high-resolution
complex HVAC typically used to create air modelling.
systems (http://dx.doi.org/ flow networks
10.1016/j.egypro.2012.11.0
60).

17
2 ESP-r exemplars
2.1 Overview of categories
ESP-r has several exemplar models available to users and distributed with the source code.
These exemplars provide a broad coverage of ESP-r capabilities, so exploring them provides
an easy way to understand what ESP-r features. This introduction also uses several
exemplars to explore ESP-r features; therefore, it is helpful to have an overview of available
models before starting to use ESP-r. Exemplars are structured in the following categories,
discussed below in more detail.

2.2 Models per category

2.2.1 a simple
The simple exemplar comprises several variants of a model with a single thermal zone, listed
in items a to e in the image below.

18
The first model in this category (opened in ESP-r) is shown in the image below. The title
indicates that it has a convective heater delivering energy to the air inside the thermal zone.
This model demonstrates essential features of ESP-r thermal zone modelling, covering the
geometry of the problem, boundary conditions, construction materials, imposed air
infiltration and casual gains, and ideal controls for heating.

In ESP-r, variants of a model are often adopted in exemplars to demonstrate how a new
feature can be implemented in existing models. On the list of models in this category
(shown above), option b ... with underfloor heating shows the same single zone model,
19
but with floor heating instead of a convective heater. Option c shows the same base model,
but evaluates the impact of shading elements placed outside the building (blocks in the
image below representing surrounding buildings).

On the list of models in this category (shown above), option f multizone with convective
heating and basic controller shows a version of the previous model with an attached
office and the roof void represented as a thermal zone. This model demonstrates how
thermal zones interact regarding heat conduction, boundary conditions, and air flow.

Options g to o on the list show variants of the multizone model covering several features
available in ESP-r.

20
2.2.2 b technical features
This category is dedicated to several variants of a model with three thermal zones.

The model has two adjacent small offices (manager_a and manager_b) and a zone
representing the corridor. This model represents two rooms on a typical floor of a large
building. The walls, floor, and ceiling have boundary conditions that emulate the presence
of similar offices. This model makes it possible to study energy-saving features in one of
the rooms and use the other as a reference for comparison. As only two offices are included
in the model, applying changes and analysing their impact is straightforward.

21
The available variants cover a wide range of features (and many variants have several
offices to demonstrate these features). Some features are easy to configure, such as
option b ...with shading, but most variants are aimed at experienced users.

2.2.3 c realistic scale

Different from the previous two categories, these models are not meant to showcase
particular features of ESP-r implemented in a base case model. This category comprises six
models created to reproduce realistically rooms in a hospital, a house, and flats in a high-
rise building.

The hospital exemplar (shown below) is dedicated to thermal comfort assessment of

occupants.

22
The model below, of a high-resolution house with network flow wet central heating system
representation, is one of the most detailed ones in ESP-r. It has radiators, solar collectors,
and water storage modelled as thermal zones filled with water, providing a detailed
representation of this complex heating system.

2.2.4 d real projects

This category shows models representing actual buildings, with various climates and
functions.

23
The image below, for example, shows the model for an office section in Ottawa, Canada.

24
2.2.5 e training workshop
These exemplars are similar to the first two categories, as they show simple applications
of ESP-r, with variations in features for demonstration/teaching purposes.

The image below shows the model for a medical centre with user-imposed flows.

2.2.6 f network ventilation

This category has a few exemplars dedicated to air flow modelling using networks.

25
The image below shows a model with a Trombe wall and controls.

2.2.7 g systems & control

This category comprises various exemplars dedicated to explicitly modelling heating,
ventilation, and air conditioning systems.

26
Some models, such as exemplar a rudimentary mechanical system, do not have thermal
zones, nor control files, and only represent the system on its own. The screenshot below
shows that this model has 0 zones defined (in the section Buildings on the right menu), but
it has a network representing plant & systems (marked as defined). In ESP-r, it is possible
to simulate only the relevant part of the problem for a given analysis, as exemplified by this
model with no thermal zones.

2.2.8 h plant systems with network fluids

This option is not available in version V13.3.17.

27
2.2.9 i construction-related issues
This category is dedicated to a variety of advanced features related to heat and moisture
transfer in solids.

The image below shows a model with 3D ground conduction, in which the interaction
between the building and the ground is calculated (rather than imposed, as in other
models in ESP-r).

2.2.10 j windows and daylighting

Options b to d are not available in version V13.3.17.

28
2.2.11 k fluid movement
This category shows exemplars related to CFD simulations in ESP-r, either stand-alone or
coupled with the thermal zone and/or air flow network calculations.

The image below shows a model dedicated to decoupled CFD simulation in ESP-r.

29
2.2.12 l combined heat and power
This category comprises three models dedicated to energy generation using PVs and CHP
systems.

In the following sections, some exemplars are explored in detail to illustrate ESP-r
capabilities and instruct users on the settings required to implement features in their
models.

However, readers should keep in mind that some of the exemplars listed above are meant
for experienced ESP-r users, and the fact that they are available does not indicate that
running or reproducing their features is straightforward.

30
Installing ESP-r

31
3 Before installing ESP-r
3.1 ESP-r runs on Linux
ESP-r was developed for Unix and later ported to Linux. Currently, ESRU recommends using
ESP-r in machines running Ubuntu desktop 20.04. If you already use Linux, you may skip
the next section and go directly to the following one to install ESP-r and compile it from
the source code. If you run another OS (likely Windows or OS X), you can use Linux as a
client on your computer and then use this client to install ESP-r (instructions provided in
the following sections).

3.2 Getting Linux on a computer with another OS

If you are using Windows, OS X or another OS, this is the place to start ESP-r installation.
While using an application that should run on Linux may be initially seen as a burden for
Windows and Mac users, it often proves to be a valuable experience to users as it allows
for acquiring important skills such as virtualisation and using Linux. Linux remains an
important OS for scientific computation and servers (both for web services and high-
performance computing). The following sections address two ways of getting Linux inside
a computer with another OS:

• Windows Subsystem Linux (WSL), a functionality available on Windows 10 (and

later), and
• Virtual machines (which can be used in any OS) and provide a complete Linux
experience with the user interface.

These instructions do not address the use of dual-boot systems. Although it is possible and,
in some cases, straightforward, dual-booting has a key limitation: it is impossible to use the
two OSs at the same time. In the multitasking environment, most people work in nowadays,
the idea of shutting up your Windows system every time you need to run a simulation is
not very feasible. Some ESP-r users opt for having a separate computer dedicated to
running Linux. As Linux and ESP-r do not require powerful computers, this option may be
cost-effective in many cases. Its key advantage is the simplicity of having a computer for
each OS, not facing the problems related to virtualisation or subsystems needed otherwise.

3.3 Other programs used in combination with ESP-r

The installation of other software used with ESP-r (such as Radiance and Gtool) is briefly
covered in this introduction guide in the section Install supporting software. Beginners may
skip this step initially as most ESP-r functionalities do not require any additional software.

3.4 Decimal separator

ESP-r requires computers to be configured with a period as a decimal separator. The OS
often manages this setting depending on the country and language used in the computer.
Changing this setting on computers that do not use English as the primary language may
be necessary.

32
4 Windows: Run Ubuntu using WSL
This tutorial is recommended for most Windows users.

⚠ Make sure Windows is up-to-date before proceeding.

4.1 Windows Subsystem for Linux

This document details the installation and configuration process for using ESP-r within a
Windows Subsystem for Linux (WSL). WSL can run Linux programs on a Windows computer
without the need for a virtual machine. It provides a terminal window for Linux commands
that can be used to run ESP-r.

4.2 WSL
4.2.1 Enable Windows Subsystem for Linux (WSL)
If you are running a recent version of Windows (Windows 11 or Windows 10 Build 19044+
or superior), open PowerShell as Administrator:

Install Ubuntu 20.04 LTS by running the command:

wsl --install -d Ubuntu-20.04

33
Restart your computer.

4.2.2 Starting Ubuntu

From the Start menu, select Ubuntu.

Set up a new Linux user account with a username and password. This is completely
separate from the login to Windows system, and does not have to be the same. Most
users adopt a simple password for Ubuntu, as this password is often used to run
commands as superuser.

Some computers come with the support for virtualisation disabled. In these cases, an
error related to Intel VT-X or AMD-V appears during the VM installation/setup/usage. See
the appendix for WSL tips and troubleshooting.
34
Once Ubuntu is ready, the prompt shows:

4.2.3 Update Ubuntu

Before proceeding, update Ubuntu using the following command on the Ubuntu terminal:

sudo apt update

WSL setup is concluded. At this point, users may proceed to the next section to install
ESP-r.

4.3 Learning more about WSL

Check the appendix for additional WSL features that may be useful for ESP-r users.

35
5 Linux: Install compiling from source code
Install dependencies, download and compile the code, and create links to ESP-r
executables

5.1 All-in-one install command for Ubuntu 20.04 LTS

The following command is a fully automated combined version of the instructions in the
step-by-step section below. Copy and paste it on the Ubuntu terminal.

sudo apt update ; sudo apt -y install build-essential gfortran libtool ; sudo apt -y install
libx11-dev ; sudo apt -y install libxft-dev ; sudo apt -y install libxml2-dev libxslt-dev ;
sudo apt -y install libsqlite3-dev ; sudo apt -y install imagemagick xfig transfig ; sudo apt
-y install csh xterm curl ; sudo apt -y install pandoc ; cd ~ ; sudo rm -r ESP-
r_V13.3.17_Src.tar.gz ; sudo wget --no-check-certificate
"https://www.esru.strath.ac.uk//Downloads/esp-r/ESP-r_V13.3.17_Src.tar.gz" ; echo
"Extracting ESP-r compressed files. This may take a few minutes..." ; sudo rm -r ESP-
r_V13.3.17_Src ; sudo tar -xzf ESP-r_V13.3.17_Src.tar.gz ; sudo rm ESP-r_V13.3.17_Src.tar.gz
; cd ESP-r_V13.3.17_Src ; sudo mv /opt/esp-r /opt/esp-r_previousinstall; echo "if there was
a previous install in the /opt/esp-r folder it will be moved to /opt/esp-r_previousinstall";
sudo ./Install --silent ; cd /usr/local/bin; for FILE in /opt/esp-r/bin/*; do sudo ln -sf $FILE
"$(basename -- $FILE)"; done ; cd ~ ; ls ; esp-r

⚠ This command will install several packages and may take up to one hour to complete.

The command above should work for most users and install all dependencies, download
the source code, extract compressed files, and run ESP-r Install script. It may take up to one
hour to execute. Copy the whole command above, paste it into the Linux terminal, and
execute it. If successful, ESP-r will open at the end of the installation. In case it does not
work, execute the commands one by one, as listed in the step-by-step instructions below,
to identify where the problem occurs.

5.2 Step-by-step instructions

This instructions were tested on Ubuntu 20.04, but they should work on Ubuntu 23.04 as
well.

5.2.1 Installing dependencies for Ubuntu 20.04

Before downloading, compiling and installing ESP-r, several packages need to be
installed.

Update Ubuntu before proceeding:

sudo apt update

Compilers and library support tools:

36
sudo apt -y install build-essential gfortran libtool

X Window System GUI environment:

sudo apt -y install libx11-dev

Fonts:

sudo apt -y install libxft-dev

XML support:

sudo apt -y install libxml2-dev libxslt1-dev

SQLite support:

sudo apt -y install libsqlite3-dev

Visualisation support:

sudo apt -y install imagemagick xfig transfig

Additional applications:

sudo apt -y install csh xterm curl nedit pandoc

5.2.2 Downloading the source code

Move to the home folder before proceeding:

cd ~

Download the file directly from the Ubuntu terminal (either on native Ubuntu or WSL):

sudo wget --no-check-certificate "https://www.esru.strath.ac.uk/Downloads/ESP-r/ESP-

r_V13.3.17_Src.tar.gz"

⚠ If the command above does not work, you can also manually download the source
code from https://www.esru.strath.ac.uk/applications/
If you download the file manually using an internet browser, the file and folder locations
provided below may need to be adapted depending on your system.

Check if you have a file named ESP-r_V13.3.17_Src.tar.gz (or similar, depending on the
version number)

37
ls

Extract the source code from the compressed tar.gz file (adapt the command below
depending on the version you downloaded):

sudo tar -xzf ESP-r_V13.3.17_Src.tar.gz --verbose

This creates a folder ESP-r_V13.3.17_Src.

⚠ Linux is case-sensitive, so pay attention to upper and lower case when typing
commands such as the one above.

5.2.3 Compiling
Move to the folder with installation files (replace the version number with the one you
downloaded):

cd ESP-r_V13.3.17Src

Inside this folder is a Readme file with information about several optional flags that can be
used when installing ESP-r. However, new users can skip the Readme file and compile ESP-
r by calling the Install script using:

sudo ./Install

You will be prompted with several questions. You can accept the default option for all
questions, as they suit most ESP-r users.

38
The installation takes several minutes.

5.3 Check the installation

After the installation, you can check if ESP-r was installed in the computer by looking at
the contents of the opt folder:

cd /opt

ls

List the contents of this folder, and you should see a folder named ESP-r. You can check
the content of this folder where all ESP-r files are located.

39
⚠ On Windows WSL, this folder can also be see on Windows File Manager at:
wsl.localhost\Ubuntu-20.04\opt
or
\\wsl$\Ubuntu-20.04\home\user\basic\doc

Windows File Manager showing ESP-r folder on WSL

Windows File Manager showing ESP-r folder on WSL

5.3.1 ESP-r in Text Mode

If you enter the folder bin, and issue the command below, the application will open in
text mode.

40
cd bin

./esp-r -mode text

⚠ In practice, users will rarely call ESP-r itself and will rather use one of the many
programs in the ESP-r suite, such as prj, bps, or res.

5.3.2 Create Links to Executables

In order to make ESP-r executables accessible from any folder in the system, create
symbolic links for the files in the default application folder for Ubuntu:

cd /usr/local/bin

for FILE in /opt/esp-r/bin/*; do sudo ln -s $FILE "$(basename -- $FILE)"; done

cd ~

You can check if the link was created correctly by issuing the following command:

which esp-r

You should see that the systems points to the usr/local/bin

41
5.3.3 Update the PATH (an alternative approach that may be used instead of creating
links as described above)
Some users prefer to modify the system PATH instead of creating symbolic links in
the /usr/local/bin folder.

Once the installation is complete, update the PATH.

Here we use the text editor gedit to change this file

sudo gedit .~/.profile

This will open the file. Include the following new line in the end of the document:

PATH="$PATH:/opt/esp-r/bin"

Save the file, close it and restart the computer.

⚠ WSL users should use the command below to update the PATH:

sudo echo export PATH="$PATH:/opt/esp-r/bin" >> ~/.bashrc ; source ~/.bashrc

5.3.4 Run ESP-r

After the system restarts, start Ubuntu and on the terminal and type esp-r to start the
application.

42
⚠ If you are using WSL on Windows 10 (prior to Build 19044), remember that XLaunch
should run before starting ESP-r.
Some WSL users may encounter errors in text mode. Updating the system (sudo apt
update) and rebooting Ubuntu may solve the problem.

The message "cannot find" in the text feedback area can be ignored and does not impact
ESP-r functionality.

5.4 Linux for beginners

It is highly recommended to have basic skill on Linux to work with ESP-r. The appendix
chapter describes a number of tips and it is essential reading for new users of Linux
interested in using ESP-r.

43
6 macOS: Compile from source on Apple Silicon
processors
There are two sets of instructions on this session. The first addresses Apple Silicon chips,
and the second is describe in the appendix and is dedicated to computers with and intel
processors.

6.1 Installing ESP-r on a M1 Mac (Apple Silicon)

6.1.1 Acknowledgments
The following instructions are taken from the following video tutorial:
https://www.youtube.com/watch?v=U0GSwp-T07g&t=5s

6.1.2 System setup

ESP-r requires some dependencies and useful tools that are not available from the Apple
App Store. These are required to install ESP-r on MacOS. Open the Terminal application
and a command window will open up. Run the following command to install command
line developer tools

xcode-select --install

xcode-select --install

Select install when prompted and wait for the tools to install. This may take a few
minutes.

6.1.3 XQuartz
A X11 environment is required. Apple no longer internal support this so download the
package from this link: https://www.xquartz.org Click on the pkg in your downloads folder
and follow the instructions. You will then have to log out and back in to complete the
install.

6.1.4 Homebrew
A package manager is required to install all the dependencies and utilities required.
Homebrew is a good one and will be used in this install. Go to https://brew.sh and copy
and paste the script into the terminal window to install. After installing homebrew there
are a couple next steps suggested, run those commands.

The next step is to enhance this by setting up our own definitions of what the paths
should be. We’re going to use a little text editor that works within the OSX terminal
window. Use the commands:

cd

44
nano .profile

in the .profile file type in

PATH=$HOME/bin:/opt/esp-r/bin:/opt/homebrew/bin:$PATH

export PATH

save the text by pressing "Control + O" and exit with "Control + X"

Then run those directives:

source .profile

And to see if it works:

which brew

You should see: /opt/homebrew/bin/brew. Next make sure homebrew is all up to date.

brew update

brew upgrade

6.1.5 Other dependencies and applications

ESP-r has some dependencies and helpful applications.

We can use brew to install those. Here are some suggestions:

• nedit - a simple graphical text editor for tweaking models or source.

• xfig - a utility that can create/use vector drawing directives from ESP-r.
• meld - the best thing since sliced bread in terms of seeing visually differences
between text files and folders.
• imagemagick - a suite of tools to convert image files.

They can be installed with:

brew install nedit xfig meld imagemagick

ESP-r will expect to find the following library:

brew install libxft

45
ESP-r will also expect to find gcc g++ and gfortran. Several versions may be available but
Version 11 works best for M1.

brew install gcc@11

When it finishes, give the following commands to see if done okay:

which gcc-11

which gfortran-11

To ensure that the pre-compiled executable find the libraries we need to create a link:

cd /opt/homebrew/opt

in -s /opt/homebrew/opt/gcc@11 /opt/homebrew/opt/gcc

6.1.6 Folder Creation

For simulation files:

cd

mkdir Models

If you want to compile ESP-r from source at some point:

cd

mkdir Src

cd Src

mkdir ESP-r

ESP-r is 'traditionally' located in /opt/esp-r . This folder needs to be created, but you
need to use sudo to create it and then make yourself owner of that new folder.

cd /opt

sudo mkdir esp-r

sudo chown [your user name] /opt/esp-r

46
6.1.7 Installing precompiled M1 Version of ESP-r
Get the precompiled M1 version of ESP-r: http://contrasting.onebuilding.org/esp-
r_13.3.17_precompiled_M1.tar.xz

If not found substitute a 18 or 19 for the 17 to get an updated version. Go to the folder
where the file has been downloaded to. The default is usually:

cd

cd Downloads

Issue the following command:

tar xfJ esp-r_13.3.17_precompiled_M1.tar.xz -C /opt

Now to check everything has worked force start an application.

cd /opt/esp-r/bin

./clm

If an application starts, then you are almost there. Return to home folder and check that
the new software is found.

cd

source .profile

which prj

Should return: /opt/esp-r/bin Last go to model folder and start ESP-r and select and
exemplar model:

cd

cd Models

prj

ESP-r should now be fully installed and you can begin simulating.

47
7 Install supporting software
There are several programs that can be used with ESP-r to improve its calculation or work
flow capabilities. These instructions are for reference only. Check the documentation of
these applications for detailed instructions.

⚠ The software listed below is not required for most simulations, so you may install it at a
later stage when you are more familiar with ESP-r.

7.1 Radiance
Radiance is an open-source application for lighting simulation. It can be used to simulate
artificial and/or natural lighting in ESP-r.

Download the latest version of Radiance from

https://www.radiance-online.org/download-install/radiance-source-code/un-
officialhead-version

Decompress both the source tree and auxiliary files into a single directory, then issue the
following command to install Radiance:

sudo ./makeall install

7.2 Modish
Modish is an open-source application for the calculation of the reflection of solar
radiation by external obstruction impacting thermal analysis in ESP-r, using Radiance as a
calculation engine.

sudo cpan

At the cspan prompt, issue the following commands.

upgrade
install List::AllUtils
install Vector::Object3D::Polygon
install Math::Polygon::Tree
install Statistics::Basic
install Data::Dump
install Regexp::Common
Then press ‘q’ to return to the shell.
Some components of the above packages will not activate until next log in.

48
Thermal Domain

49
8 Exploring a thermal model
This tutorial explores an ESP-r model focused on the thermal domain and describes the
steps to run a simulation.

ESP-r can solve several different energy and mass transfer processes. The thermal domain,
for example, solves the thermal energy balance of fluid bodies enclosed by solid surfaces.
It does not include, among others, the calculation of air/water flow volumes (fluid network
domain), the concentration of contaminants (also in the fluid domain), the detailed energy
balance of fluids (CFD domain), the energy balance considering HVAC components (plant
domain), the energy balance of components consuming/storing/generating electricity
(electrical domain). Each energy and mass transfer process requires solving a particular set
of equations, which may (or may not) be enabled in a given model and are referred to in
this document as a domain.

Key features covered in this Tutorial are:

• model geometry
• constructions and boundary conditions
• operation regarding imposed air flow rates and internal heat gains
• controls for HVAC systems
• climatic conditions imposed around this model

8.1 Copying an exemplar model

Move to the home folder (directory) before starting:

cd ~

Start by opening the terminal and see if ESP-r is working.

Select open existing. ESP-r contains a number of Exemplars. These are found in "other" or
"exemplar". Select Exemplar. ESP-r then offers a list of Exemplars. Open a simple, then
select a zone with convective heating & basic control.

Options in the menu can be selected using the mouse or by typing the first letter of the
option in the menu. For example, for the option simple, either click on it using the mouse
or type a.

50
Once a selection is made, the item is marked with an asterisk (*), as shown below. The user
can click on the same option to deselect it if necessary. This selection mode is used in many
ESP-r menus.

Click on -the exit menu to accept this selection. Click on Proceed.

51
As default, ESP-r copies the model from the installation folder into the home folder
(home\<username>\simple). In the example below, the user is called Ubuntu. Note that the
home folder might be different for different users. To save the file to a different location,
type the link to the desired location in the text box.

Select OK, and the model is copied to the home folder. ESP-r shows the model wireframe
in the interface's graphic window.

It asks to restart ESP-r; accept to restart. The copied model should now be available in the
specified link. Alternatively, ESP-r may automatically restart and show the copied model
without prompting the user.

8.2 ESP-r model: folder and file structure

Note that folder and file locations may be different depending on your system.

At this point, reviewing ESP-r's file structure might be handy. On the application Files
(equivalent to File Explorer on Windows), select "other locations" and then "computer." ESP-
r is installed at "opt" and "esp-r."

ESP-r executables are located in "bin". "Training" models (including the models available
through prj interface under exemplar are in "training"). Open the folder "training" and then

52
"simple". ESP-r models, such as the "simple" model, are made by the combination of the
files in all those folders. The folder "simple" holds the original model, which is being copied
now to home/user/simple.

The main file in ESP-r is the file extension .cfg in the cfg folder. The .cfg file gives general
information about the model and points to other files in this folder structure.

8.3 Opening an ESP-r model via terminal

Open a terminal by pressing ctrl+t keys simultaneously (only for Linux OS).

53
Move to the home folder, typing:

cd ~

Move to the folder simple and cfg.

cd simple

cd cfg

Open the model in ESP-r by invoking the application prj using the file parameter to point
to the .cfg of interest.

prj -file bld_simple.cfg &

Add the symbol & at the end of any command to start the process in the background and
keep the terminal usable (otherwise, the terminal remains locked until ESP-r is closed).

8.4 Adjusting font sizes

Before starting, it may be necessary to adjust font sizes to facilitate reading menus and
other text fields. The option "fonts" in the lower right corner allows changing font sizes in
the interface.

54
8.5 Project manager application
ESP-r shows a model with a room and a few doors and windows. The thermal domain of
ESP-r adopts the concept of the thermal zone (in this case, this room), where surfaces
enclose a fluid body (air or water), and the goal is to calculate thermal energy flow from/to
the fluid body through the surface.

55
This screen contains several options and information, so it is valuable to spend time
exploring them. Sometimes, users may get stuck on a screen. ESP-r can be closed in this
case, and the model is rarely damaged. Open the model again using the terminal.

Select m browse/edit/simulate. This menu opens a number of options to run the

simulation, assign HVAC and ventilation controls, and assign fluid and/or electrical
networks to the model. This tutorial explores the thermal zone properties, i.e., the materials,
geometry, boundary conditions, and heat sources/sinks affecting the thermal performance
of the building.

Select composition.

56
8.6 Building composition
Under composition, the three first options cover the main attributes of a thermal zone:
geometry, a set of construction materials and an operation file. While the term Building
appears in several places in the ESP-r interface, the program can be used to model a variety
of systems and not only buildings.

57
Select a geometry & attribution and a reception.

This menu offers several functionalities for defining and editing the position of vertices and
the list of vertices that describe each surface.
58
8.7 Zone geometry
8.7.1 Surface topology
Select e Surface list & edges. prj shows a list with surface names (such as North, South,
glazing, ceiling, floor), the number of vertices used to describe each surface and the id of
these vertices. The floor, for example, is defined by points number 1, 28, 27, 7 and 6.

Select - exit menu.

8.7.2 Vertex coordinates

Select d vertex coordinates. The Project Manager shows all nodes listed by id and their
coordinates. Using the functionalities available on prj, all geometric features (vertices and
surfaces) can be created, edited, and deleted.

59
Select - exit menu

8.7.3 Surface attributes

Select f surface attributes. Surface attributes provide information about the name of the
surface, its composition (indicated by the name of the construction assembly composed of
layers of materials) and its boundary conditions.

60
Regarding boundary conditions, most surfaces face the exterior environment, i.e., they are
exposed to sun, wind, and external air temperature, and they exchange longwave radiation
with the surroundings, etc. The exceptions are Floor and Passage. The Floor faces a
"constant temperature" environment representing the temperature of the ground. The
Passage faces a "similar" environment, indicating other parts of the building that are not
included in the model, such as a corridor or other rooms, and the surface Passage faces
one of such parts. Assuming a "similar" environment emulates the heat transfer between
the two rooms, or room and corridor through the wall between the two zones. Heat transfer
is negligible due to small the temperature difference. Regarding heat transfer, the other
side of the surface Passage is assumed to have the same temperature as the Reception in
the previous time step.

The ceiling (roof_1) and floor (floor_1) are made of different materials when compared to
the walls (extern_wall), and the windows are double-glazed (dbl_glz).

Information regarding each thermal zone geometry is stored in files extension .geo, located
in the folder zones.

61
Open the file reception.geo. The contents below show the same information seen on the
Project Manager interface. The primary purpose of prj is to support the creation and edition
of model files. Users can also edit files directly; changes are reflected in the prj interface.

62
8.8 Zone constructions
Return to the Building Composition menu by selecting - exit menu a few times.

Select b construction materials. Then, select a reception to access the construction

material details for the reception.

Select use it (this indicates that prj found a file in the model related to constructions for
this zone and recommends its use).

⚠ Buttons can be selected using the mouse or by typing the letter a for first button, b for
the second, c for the third as so on. In the example above, typing the letter a selects the
option "use it"

63
Select continue (TMC holds data related to transparent constructions, and some additional
options are available on how these properties can be described in model files - in most
cases these options are not applicable and can be ignored).

A list of surfaces and components is shown. Select, for example, a south.

The properties of this construction are shown, such as emissivity, absorptivity (for solar
radiation), the number of layers in this construction, and the respective thickness and
material properties.

64
Detailed information about the composition of construction materials is stored in model
files with extension .con located in the zone folder. Open the file reception.con. The
sample below shows the same information accessible through the prj interface.

The properties of constructions are also stored in ESP-r databases (described later in this
document).

8.9 Zone operations

Return to the Building composition menu by selecting - exit menu a few times.

65
Select c operation details. Then, select a reception to access the operation data about
internal heat gains by people, equipment and artificial lighting for the reception. Select ok
(or press the Enter key).

In the thermal domain of ESP-r, Zone Operations holds information about imposed or
estimated air changes (as air carries energy from/to the zone) and about internal heat gains
by people, equipment and artificial lighting (casual gains).

66
8.10 Scheduled air flows
Select c edit scheduled air flows. The graph air flow volumes are expected in this thermal
zone (this is input data in the calculation). This is a simplistic way to impose an air flow rate,
as the mass flow is not calculated based on window positions, size, wind speed, fan capacity,
duct diameters, or other relevant parameters. Air change schedule, for instance, indicates
that 24 hours a day, seven days a week, there is a constant infiltration rate of 0.3 air changes
per hour (ACH). So, 30% of the volume of this thermal zone is renewed with air from the
outside per hour.

Select - exit menu

8.11 Casual gains

Select d edit casual gains

This is a deterministic way to impose casual gains from computers, people, or anything
releasing heat in this thermal zone. The casual gains in this model show a more complex
pattern than the one seen in the airflow. During Saturdays, Sundays, and night time on
weekdays, there is a fixed value of 800W, while during the weekdays in working hours from
9:00 to 5:00, there is an increase in the gains. Occupant behaviour, Lights, Equipment, etc.,
cause such gains. The factors and their respective gains are tabulated on the right-hand
side of the screen.

67
As in the geometry and constructions, the information regarding operations is stored in a
file in the Zones folder with the extension .opr.

This concludes the exploration of key aspects of the model Composition.

8.12 Control loops

Return to the Browse/edit/simulate menu by selecting - exit menu a few times.

The menu section dedicated to Controls indicates that one loop was defined. Thermal
domain control is responsible for injecting or extracting thermal energy from the thermal
zone to model heating and cooling systems.

Select i zones.

Select ok. The main Controls menu is displayed. It shows three control loops: one for
weekdays, one for Saturdays, and one for Sundays.

68
Select the option for weekday.

The figure shows a bug in the interface, where two letters "e" are used in the menus. Use
the mouse to select the correct option instead of the keyboard.

The image below shows important information in the feedback text window (lower left
corner). The control for weekdays starts at 0.00 hours in free-floating mode. Free-floating
is used when heating and cooling systems are unavailable or inactive. At 7.00 hours, another
control becomes active, with a heating capacity of 3000W and a heating setpoint of 15°C,
pre-warming the zone to the arrival of occupants later in the day. At 9.00 hours, the heating
system's temperature is raised to 20°C. Then, at 18.00 hours, the control is again in free-
floating mode, indicating that the heating and cooling systems have been turned off. This
information is compatible with a heated building located in a cold area.

69
Select d period data. The information shown in the previous image in the feedback text
window is now available on menus for editing.

As with information on geometry, constructions and operations, control data is written in

the file, as shown in the image below. The extension .ctl is used for controls, and files are
located in the ctl folder in the model folder.

70
8.13 Databases
Return to the Building composition menu by selecting - exit menu a few times.

Select b databases.

The Database management menu provides the names of several databases. Some of them
are used in every model (such as the annual weather), while others are available to users in
case new features are included in the model. This menu shows the standard ESP-r
71
installation path <std>, where the original database files are located. All options in this
menu have the <std> tag, indicating this model relies on the original databases. The field
<mod> indicates where customised databases used only in this model are placed (in this
case, they are in the dbs folder of the model).

8.14 Climate
The image above shows that the model uses the standard ESP-r climate "clm67".

Select a annual weather. The Weather menu provides options to analyse the currently
selected weather file or to select another one.

Select a analysis tool. The Weather Module is opened. This is another program called clm,
which is part of the ESP-r suite. Note that the Program Manager (prj) is still open. ESP-r is
a collection of programs; none of them are called ESP-r.

72
Select ok to accept the name of the climate file linked to the Simple model. Then, select d
graphical (to access the data plotting tools) and select a dry bulb temperature. Select !
draw graph.

The image below shows an example of the temperature plot for the clm67 climate file.

73
 Dry Bulb Temperature Graph

The graph shows temperature variation throughout the year. The temperature is very low
in the early and late weeks (January and December) of the year, with a peak of 25°C in the
summer months. It can determine that the modelled location is in the northern
hemisphere, in a cold location.

Close the Weather Module of ESP-r.

8.15 Material database

Select d material properties

Select a browse/edit

A set of material classes are shown.

74
Materials are not directly applied in thermal domain models but instead grouped in
construction components. The image below shows the material properties available in the
database.

The list of materials and the respective properties of a Brick is shown below.

The properties of the Brick sub-category, a Breeze Block, are shown in the image below.

75
8.16 Construction database
From the Database Management menu, select e construction

Select a browse/edit

76
A set of Construction Classes are shown.

Select j legacy construction & models (this is where most constructions used in the
Simple model are defined)

Select a extern_wall

77
Properties of each layer of this construction are shown, and options for editing them are
provided.

78
At this point, the following key features of the Simple exemplar model have been covered:

• geometry
• constructions and boundary conditions
• operations regarding imposed air flow rates and internal heat gains
• controls for HVAC systems
• climatic conditions imposed around this model

8.17 Exporting a model description (QA report)

ESP-r has facilities to create reports comprising the model's main features described
above for Quality Assurance (QA) purposes.

Select m browse/edit/simulate.

79
Select u content report.

Select no for markdown format.

The Model reports menu becomes available. This menu shows options to increase or reduce
the amount of information included in the report.

80
Select > contents >> text feedback

Change the file name as indicated below and press ok.

Select ! generate contents

The file is created in the doc folder of the model.

81
In this example, a 13-page report describing the model is generated (a sample of this
report is reproduced in the image below).

8.18 Running a simulation

82
Go to the Browse/edit/simulate menu.

Select s simulation

The Simulation Controller menu shows, among other things, the starting and ending date
for the simulation (option g).

Select q integrated simulation

Select automated

The ESP-r suite's Integrated Simulator program (bps) is briefly open while the simulation is
running and then closes automatically once it is finished.

83
The next section covers the result analysis tool.

84
9 Exploring results of a thermal model
This tutorial explores basic functions for the result analysis of a simple model in ESP-r. Some
users might get an error message - "Error opening session log". Select the result file name
as needed and select ok. The first window from the t results analysis module is shown
below. Select a graphs.

9.1 Basic plotting

9.1.1 Dry bulb temperature
Select a parameter plot, then select b temperatures, as shown below. Then select the a
dry bulb (db) temp option in the next window.

85
Select -exit menu, then select ! draw graph. The result is shown in the image below.

86
 Zone Dry Bulb Temperature Graph

This simulation computes temperature variation over a 168-hour period - from January 9th
to 15th. This is defined in the settings in s simulation window (shown below), as discussed
in the previous tutorial. These settings can be changed as per requirement.

87
In the dry bulb graph, the pattern is as expected on weekdays. The average temperature is
20°C from 9 AM to 5 PM (work hours). During the night, this temperature drops. At 7:00 am
the next day, the heating is switched on at 15 °C to preheat the building, and at 9 o'clock,
the building heats up again. For Saturday and Sunday, when the heating is off, the
temperature decreases with time. There is a noticeable increase in temperature on Saturday,
likely because of solar radiation entering the zone during this day, so it can be assumed
that Saturday was sunny. Whereas, Sunday could have been an overcast day since there is
no significant increase in temperature.

9.1.2 Solar radiation

Select the a weather option in the parameter plot window. Select the b diffuse horizontal
solar and c direct normal solar to plot the direct and diffused solar radiation.

88
 Dry Bulb Temperature Compared to Available Solar Radiation (Direct and Diffused)

The solar radiation graph shows that Monday has some solar radiation. Tuesday was
overcast and thus had negligible direct radiation. Wednesday had some solar radiation.
Thursday had more diffused solar radiation (accounting for the slight increase in
temperature) but not much direct solar radiation. Saturday had the highest solar radiation
during the day, and the sky was clear. The temperature increases due to solar radiation
entering the zone through the windows and heating it to a certain extent. Sunday has
relatively lesser solar radiation (accounting for the minor increase in temperature during
the day) and has no noticeable direct solar radiation. The unit of solar radiation intensity is
W/m².

89
Selecting options without clearing the selections creates plots where the new data is shown
together with previous selections, which is useful for comparison, as seen above. To start
afresh, select /clear selections.

9.2 Results quantities and metrics

9.2.1 Weather
The wind speed and direction are used to calculate the convection around this building.
The respective graph can be drawn as directed below.

Selecting e wind speed plots the wind speed (in m/s) measured at the meteorological
station and included in the weather file used by ESP-r, as shown below.

Wind Speed Graph

The wind direction (where the wind comes from) can also be plotted using the option f
wind direction (0 equals north, values in degrees clockwise). The graph is given below.

90
 Wind Direction Graph

It is also possible to plot the relative humidity, sky illuminance, cloud cover, and
atmospheric pressure variation.

Select / clear selections.

9.2.2 Temperature

91
This menu is dedicated to temperature values in the thermal zone, such as the dry bulb air
temperature inside the zone (a dry buld (db) temp.). The second option (b (db -ambient)
temp) refers to the ambient temperature - in ESP-r jargon, it is the outdoor dry bulb air
temperature, so this graph plots the ΔT, or temperature difference between the inside and
outside temperature. It is possible to use the ΔT between the present and other zones,
using the option c (db -other zone) temp.

Ambient and Other Zone Temperature Graph

d Control Point temperature is used in cases where the system is undersized. This means
that the temperature inside the room or the zone (if it's a boiler or any other sort of
equipment) might not be the same one defined in the control setpoint.

e Resultant Temperature is the operative or resultant temperature, which is a combination

of air temperature and surface temperature around this zone. Thermal comfort combines
both convective and radiant heat exchange, so this option gives a better understanding of
the temperature in the zone as perceived by a person. To plot the data, select e resultant
temperature.

92
 Resultant Temperature Graph

The resultant temperature in the graph above is lower than 20 ºC. This is because the walls
in this building are likely to be much colder than 20 ºC. Heating the air, in turn, heats the
walls, but the walls never reach 20 ºC due to the temperature gradient between either side
of the wall ( ΔT between the inside and outside temperature - heat lost due to conduction).

It is possible to plot the mean radiant temperature (MRT) by selecting f zone mean
radiant temperature.

93
 Zone MRT Graph

The following graph shows a dew point plot used to check for possible moisture
condensation in this zone. Select h dew point temperature. The graph indicates that the
dew point is low compared to the indoor temperature, which means there is little risk of
condensation in this case.

94
 Dew Point Graph

To draw the surface graphs, select i inside surface temperature option, then exit menu,
then select the required surfaces (in this case, h ceiling and i floor). Select these surfaces
since they have different boundary conditions.

95
 Temperature Comparison between Ceiling and Floor

The graph shows that the floor is much warmer because it faces the ground, which is at a
constant temperature (as prescribed in the file). The ceiling has much lower temperatures
since it faces the outdoor air and the sky. Due to the high convective heat exchange and
high radiative heat exchange, the temperature is reduced.

Similar patterns can be seen in the comparison between the passage facing another room
(as seen in the previous tutorial) and the south wall. Select a south and c passage. The
passage has a higher temperature than the wall because it faces the other room. In this
case, the temperature difference is not significant.

96
 Temperature Comparison between South Wall and Passage

Select / clear selection. Plot the south wall and ceiling temperature. The plot shows that
the ceiling is the surface bringing the temperature down. This is because the ceiling shows
lower temperatures, leading to higher levels of heat exchange, and thus, it requires better
insulation for a cold climate like this one.

97
 Temperature Comparison between South Wall and Ceiling

9.2.3 Comfort metrics

The comfort metrics allow plotting several indicators for temperature such as the Predicted
Mean Vote (PMV).

98
PMV is supposed to be used only in places with steady-state conditions so that it can be
used during the days in this zone.

Clothing level 0.7 CLO, which is an indicator of how well-insulated clothing is: 0 is naked,
and 1 is a full suit. Select METs. It then asks us for the metabolic level since comfort is felt
differently when sitting down or doing heavy work. For this case, specify 1 MET (one person
resting). For the air velocity, as this model in ESP-r does not calculate the air velocity in this
model, a very low air velocity of 0.1 m/s can be adopted. Air velocity must be specified
because it affects how humans perceive the environment. For the casual gains that
represent occupancy, select occupied and then draw the graph.

Predicted Mean Vote Graph

The predicted mean vote is actually between +3 and -3. Values in the plot range from -6 to
-2, meaning the room is quite cold. During the day, this room is not acceptable because
the mean radiant temperature is very low, which means that the operative temperature is
also low.

Now, clear all selections.

Other comfort metrics can describe this zone. The percentage of dissatisfaction (PPD)
measures the percentage of people dissatisfied with the conditions in the zone. To draw
this graph, select c PPD.

99
 PPD graph

It shows that 100% of the people are classified as dissatisfied on nights and weekends.
However, this data is not applicable because the zone is not in steady-state. For the working
hours, the percentage of dissatisfaction is between 80 - 90% of the people. This is certainly
not something desirable in an environment.

9.2.4 Solar processes

Several solar process graphs can be plotted to gauge the amount of solar energy that enters
from the outside and adjacent rooms and the energy absorbed in the zone.

The graph indicates a lot of solar radiation on Saturday—close to 1600 Watts at the peak.

100
Solar Energy Entering from Outside

101
 Solar Energy Entering from Adjacent Rooms

Solar Energy Absorbed in the Zone

9.2.5 Energy balance fluxes

Zone fluxes measure how much heat the volume of air contained by the zone surfaces is
losing due to infiltration, ventilation, gains by occupancy, convection, casual power, etc.
Surface convection can be plotted for different surfaces. These options can be used to check
which elements are the most important regarding heat gain or loss.

102
Select l total surf conv to plot the surface convection.

Total Surface Convection Graph

The graph indicates heat is lost by convection to the outside environment. The heat loss is
in the order of 3000 Watts during the weekdays when the zone is heated up and much
lower during the weekend when the zone is not being heated. When the room is not being

103
heated, the heat gradient between the interior and exterior of the zone is smaller, which
means that less energy is lost due to convection.

Select c occupant casual gain. The graph shows some gains during the five days of the
week, but it is pretty small compared to the heat loss. Thus, a heating system is required.

Clear all the selections now.

Select g surface flux. In the same way graphs can show heat balance in the zone, it is also
possible to plot energy balance parts for each surface.

104
So, for each of the surfaces, plot the convection and conduction for the interior and exterior
walls (which would be the other face). Plating casual gains from lighting, occupants, and so
on is also possible. Three types of radiation - LW (long wave) plots are available (i.e.,
radiation exchanged between people, buildings, ground and sky). Solar radiation (i.e. SW,
short wave) plots are available in two categories.

9.2.6 Heat/cool/humidify loads

Select h heat/cool/humidify. Here, the sensible heating load of this building (since there
is no phase change) is visible.

105
Draw the graph for the sensible heating load. This is in the order of 3 kW (3000 W), which
is not surprising because the previous graph showed that this zone is losing ~3000 W by
convection. This energy needs to be added back to the zone to maintain the room
temperature at 20 ºC.

Sensible Heating Load Graph

The graph shows that sensible heat changes during the day. As the simulation starts, the
zone accumulates heat every day. This means that the heating required is reduced every
day due to the residual heat from the previous days stored in the walls and floors. This
could be an initialisation error or a result of the conditions outside. If the error is due to
initialisation, running the simulation for a prolonged period might negate this error.

106
 Heat load and Ambient Temperature

It is possible to check the source of this error by checking the temperature outside. Plot the
a dry bulb temperature in the a climate menu in the same graph. The graph shows the
error is not due to initialisation. The weekends are much warmer than the weekdays, thus
reducing the heating load required on the weekdays due to higher solar radiation.

Clear all selections.

9.2.7 Additional options

Other options related to relative humidity, casual gains, and electrical demand exist but are
not explored in this tutorial. Renewable energy options are also available but were not
implemented in this model; some of these features are addressed in other sections.

This model does not implement the option to model airflow. With this option, ventilation
rates could be assessed instead of imposed. Imposing 0.3 ACH is a gross simplification.

It is also possible to model water flow, in case components such as radiators and boilers
are modelled using thermal zones.

There are CFD metrics for computational fluid dynamics if this feature is included in the
model.

Other options are dedicated to imported measured data (observed data to this
environment) used to facilitate comparison against simulation results.

9.3 Exporting results to a text file

107
ESP-r results are stored in a binary file, so it is not possible to use the data in other
applications in its native format. For this reason, res has functionalities to export selected
results to a text file. From the first menu on res, select:

• c reports
• g performance metrics
• > display to to toggle between the options screen and file, and select "file",
o Set the file name. This file is created in the model cfg folder. ESP-r shows a
warning in the feedback window that the file was opened.
• Select the metrics to be exported, such as temperatures, weather data, and comfort
metrics.
• ! list data to write the performance metrics to file.
• > display to to toggle back to the screen option. ESP-r shows a warning in the
feedback window that the file was closed.

selecting display to the option

choosing file name

file opened

file closed

The image below shows an example of exported data from ESP-r. It uses "Space" as a field
separator and shows dry bulb temperature at one thermal zone and also the heating
injected in the zone during hours with occupancy. This fie can be imported in spreadsheet
applications, such as Excel.

108
109
10 Changing climate data and HVAC controls
This tutorial explores options to reduce the demand for a building. Select d open existing,
then exemplar. Select a simple. Then, select the option f multi-zone with convective
heating and basic control, instead of one zone model used in the previous tutorial. The
default number of zones for the multi-zone is 3. Select proceed. Then specify the name of
the folder to copy the model to by typing the location link. This command copies the
exemplar model from the ESP-r tutorials to the home folder. Note, the home folder name
is vary for different users.

Now that this model is copied to the home folder, it can be used instead of using the model
directly from the ESP-r training folder. This prevents damage to the original model. In case
there is an issue with the new model, it is possible to delete the file and restart the process
described above.

The software needs to restart so that the path for the model is set correctly. In the home
folder, a new folder named "basic" becomes available. Note, restarting the software may
not be required for all users. This model includes daylight simulation and control (not
addressed in this tutorial).

To open the model at a later time, go to the copy folder using the same steps as described
in a previous tutorial and use the command:

prj -file bld_basic.cfg &

110
This model has three zones: a reception in L-shape, an office and the roof space.

10.1 Changing climate data

Select the option b databases, then a annual weather, then b select another.

In this weather list, there are weather files of several locations listed across five pages. For
this tutorial, select u Chicago, which has a severe winter and a very clear summer.

111
Weather analysis window should open. Then select the weather file name, click ok, and
close the window. Change the weather file year. Now, Chicago weather has been selected
for this analysis. Select ok to update the name.

It is good practice to run a simulation every time a change is made in the model to check
if it is still working correctly. New users should avoid making several changes in the model
at the same time.

It is possible to import new data into ESP-r if necessary (see instructions here).

10.2 Changing HVAC controls

Select m browse/edit/simulate. Then select the option i zones in the controls sub-section.
Now, change the scope from HEATONLY to HEATCOOL. This option enables the display
of results related to the heating, cooling, and humidification systems.
112
Exit the controls window. Now, click on s simulation. Let us explore some of the simulation
presents. Option c start-up days is the number of days to be simulated before the specified
simulation period starts. Option d zone timesteps/h is the number of time steps per hour
that in this case is specified as one time step per hour. For a higher resolution analysis, it is
possible to increase the number of timesteps. Option f result save level is the level of
results that are saved, and this can prevent result files from becoming very large. Level 4
stores key results such as energy demand per building or per zone, while level 5 stores
temperatures for each of the layers in each wall of each zone, making the file size much
larger. Option g from: specifies the date range for the simulation.

Change the simulation time from the 1st of January to the 31st of December to simulate an
entire year.

Option h zone results contains the name of the file in which the results are going to be
stored. Run an integrated simulation, called as such because it brings together the thermal
domain, the airflow domain, the lighting domain, and any other domains that are defined
in the model and simulates the domains in an integrated manner.

Select the option q integrated simulation. There are two options for the integrated
simulation: interactive and automated. Interactive asks several questions to the user,
many of which were defined in the pre-settings in the previous window. Automated is a

113
simpler version that runs silently, assuming the setting defined in the pre-settings or
defaults. In this tutorial, use the automated version.

The simulator window opens and the simulator runs for a few seconds.

Select the option t result analysis. followed by option a graphs. Option 3 output period,
shows the the simulation period which is set from January 1st to December 31st. It is
possible to retrieve results for one specific date or period, but keep these settings are they
are for now.

It is possible to focus the analysis for a specific zone using the option 4 zones, which shows
the three zones available in this model - the reception, office, and roof space. For now,
select all three zones.

114
Back to the main menu, select option d enquire about. In this Enquire about menu, select
option a summary statistics, which gives access to highlights in terms of climate,
temperature, fluxes, etc. for a specific zone. Option b frequency table shows how often
certain values achieve certain thresholds. It can count c hours above a value and d hours
below a value. Of particular interest for this tutorial is the option f energy delivered. In
order to calculate the energy demand of a building on an annual basis, it might be easier
to have a single value than creating a graph, exporting the graph and then adding the
values hour by hour. The energy delivered option presents a single value that is much more
convenient than a graph.

Select f energy delivered and then a reception. For the reception, the sensible heating
energy delivery is in the order of 4 kWh/m2. This is required for 450 hours of the year.
Considering that a year has 8760 hours, this is a relatively small value. Humidification is not
applicable to this model.

Repeat this process, but now select all the zones.

115
The energy delivered for the office is much larger than the energy delivered for the
reception. For the roof space, there is no energy required for heating (there are no controls
for heating in this particular zone).

Plot a graph of temperatures just to check if there is any cooling system in this particular
model. Select a graph, then 4 zones. Select *All. Then a parameter plot, then select b
temperature, then a dry bulb (db) temperature. These settings create a graph as shown
below for all the zones for the duration of the year 2001 (as selected earlier).

Annual Temperature Variation in all zones

In the graph, the temperature in the roof space plummets to approximately -20 ºC in the
winter. The reception and office space also get very cold, probably at night. The
temperature in all the zones is above 40 ºC in the summer, so it is really uncomfortable in
this place due to the fluctuating temperatures.

116
Now change the display period to a week in the winter. Select 3 display period then select
the start date as 1/1 and the end date as 7/1. Leave the output time-step increment as 1.
Plot the graph again.

Winter Week (1/1 - 7/1) Zone Temperatures

The temperature during the day in this office is in the order of 20 ºC, but during the night
there is a significant drop in the temperature probably because the level of insulation in the
space is inadequate. During the weekend, there are minor gains during the day probably
due to solar radiation. To check this, let us plot the solar radiation. Select the option d solar
processes, then select the option a entering from outside. Plot the graph now.

Zone Temperature and Solar Radiation Graph

117
The graph shows how solar radiation entering the room increases the zone temperature
during the weekend. Most likely, there is no heating here during the weekend. On the fifth
day of the week, there is a significant amount of solar radiation, which increases the
temperature of the reception above the 20 ºC setpoint defined in the simulation. The roof
space is much colder because there is no heating there, and the level of insulation is likely
to be lower than in the other zones.

The following part of this tutorial explores how changes in simulation settings may affect
temperatures and the energy demand for this building.

Quit the module. As the model has been copied, the model can modify and it is always
possible to return to copy if needed.

Select the option m browse/edit/simulate. Even without any cooling in this building, the
temperatures are very low. One approach to tackle this issue is by changing the controls of
this building by using the option i zones in the control sub-section. Select ok to choose the
file name. In the control window, there are three different patterns: one for the weekdays,
one for Saturdays and one for Sundays.

Click on the e weekdays option. The Editing Options menu is shown below. Option b
sensor details is used to specify the sensor details such as what details the sensor senses
(the air temperature of a current/mixed zone), the dry bulb temperature and the position
of the sensor on a surface of a component or embedded inside a building component).
Option c actuator details is used to specify where the heat is injected/extracted from/to
the zone, such as an air-based heater delivering energy purely by convection to the air
node, a radiant floor delivering energy inside a floor layer, or a radiator where part of the
energy is delivered to the air and part is delivered to the surrounding surfaces. This tutorial
does not address changes in these details.

118
Change the heating setpoint and capacity data by selecting option d period data.

There are four periods for the weekday. For Period 1 (from 0 to 7 am), there is no heating.
For period 2 (from 7 to 9 am), there is some heating. Since the main energy consumption
is in Period 3 (from 9 am to 6 pm), change the set points for this period.

119
The heating is activated at 20 ºC, i.e., the heating setpoint. This means that if the
temperature of this zone drops below 20 ºC, heating will be activated. The maximum
heating capacity available is 1000 W. The capacity could be reduced to simulate the use of
a smaller heating system and understand the impact of this decision when demand is too
high. Keep this value unchanged.

As temperatures in the summer months are very high, change the maximum cooling
capacity to 1000 W. The current settings indicate that cooling is only activated if the
temperature is above 100 ºC, i.e. cooling is never activated based on this value. Change the
cooling setpoint to 25 ºC. The new settings indicate that, from 9 AM to 6 PM, the cooling
system is active if the temperatures go above 25 ºC and if the temperature goes below 20
ºC, the heating system is activated.

Exit and save the changes. Warnings about linking zones can be ignored (it is possible to
return to this menu and re-link the zones if needed). Make sure to save control data in the
controls menu.

10.3 Simulation and results with new climate and HVAC controls
Return to the browse/edit/simulate menu and run an integrated simulation
(automated). Let us see the results.

Go to results, then enquire about and energy delivered. Now, the energy required for
heating in the three zones can be calculated.

120
Window Navigation Buttons

This button can be used to change the size of the feedback window in
comparison to the graph window.

This is the Scroll bar, on the left side.

The energy used for heating in the reception is lower than that used for the office. The
heating in the reception is 4.52 kWh/m², whereas that for the office is 30.51 kWh/m², while
the sensible energy for cooling is 29 kWh/m² for the reception and 46 kWh/m² for the
office. This means that the cooling system consumes considerable energy to solve the
problem of high temperatures.

Bear in mind that those values are sensible heating and cooling. Normal air conditioning
would also have a high humidification load that is not addressed in this particular
simulation. To see if this cooling is actually adding some comfort, let's check the
temperatures.

Plot the dry bulb temperatures as before. Change the display period to 1/7 till 7/7, ie, a
week in July. It is expected to see much lower temperatures during the summer, particularly
during the day.

121
 Temperatures in a week in July

During the day, the temperatures at the office are much lower but still not as low as
expected. For the office (orange line), the temperature is 25 ºC during the day, and as soon
as the air-conditioning is turned off, the temperature increases. The pattern is easier to
identify if the simulation is carried out for two days. Change the display period from the
2nd to the 4th of July.

Temperatures of two days in July

122
At 9 am, as expected from the controls, the air-conditioner is on. It tries to keep the
temperature below 25 ºC and when it's off at 6 pm, the temperatures go up. During
operating hours, the temperature was expected to be steady at 25 ºC. Go to h
heat/cool/humidify and then select option b sensible cooling load.

Sensible Cooling Load

The sensible cooling load for the reception is fixed at 1000 W. However, it can still not bring
the temperature down to 25 ºC, probably due to the high gains in this particular zone. It
would be possible to increase the cooling system's capacity to lower the temperature and
provide optimum comfort.

The gains for the office space are much lower, which means that 1000 W is adequate to
bring temperatures close to 25 ºC. At the start of the day, the cooling loading is less than
1000 W; probably, solar radiation entering at this point is low. So, a relationship exists
between the cooling capacity, the temperature setpoint, and the energy and comfort in the
zone.

Now, go to enquire about and energy delivered. Change the output period from 1/1 to
31/12 ie, 1 year.

123
 Updated Energy Delivered

Take note of the energy delivered. Exit the window.

Let's change the setpoint and increase the energy available for this cooling system. Go to
the browse/edit/simulate menu and select zones in the control sub-section. Go to the e
weekday option, d period data. For the third period, change the cooling capacity to 5000
W and the heating setpoint to 21 ºC.

These heating and cooling set points can be defined with a certain degree of freedom to
provide different levels of comfort and they have a significant impact on the energy
consumption, as shown when the cooling setpoint was changed it from 100 to 25.

Run an automated integrated simulation. Go to results, then enquire about and then
energy delivered.

124
The energy delivered, in this case, is now much higher. This means that increasing the
cooling capacity and heating setpoint increases the energy required and can imagine that
the temperatures are now lower in the office. Changing the heating setpoint by one degree
increased the energy required for heating from 4 to 5.3.

So, changing the heating and cooling set points has a direct effect on the energy demand
of the zones. Temperatures and comfort metrics can also be manipulated to provide
optimum comfort and save energy. Many places, particularly in cold countries, leave
buildings extremely cold when they are not occupied.

Plot the temperatures for two days in summer: 2/7 to 4/7.

Temperatures of two days in July

The graph shows that the reception temperatures are higher than the ones in the office,
but a clear pattern from 9:00 to 6:00, when the temperature is ~ 25 ºC. That is the expected
pattern, so by using the system's maximum capacity and the setpoint for the system, it is
possible to manipulate how temperatures evolve in the model.

125
Temperatures have an impact in comfort metrics, such as the PMV. Go to a graphs,
parameter plots, c comfort metrics, then, a PMV. I'm assuming a clothing level of 0.7, a
MET level of 1.2, and an air velocity of 0.1. This gives me an error because this zone has no
radiant temperature sensor (see create MRT sensors).

Clear all selections using the option /.

To plot the operative temperatures or resultant temperatures, go to b temperatures, and

then plot the e resultant temperature. The graph shows that even though the air
temperature is 25 ºC, the resultant temperature is going to be different from that value.
Additionally, these values can be exported in text files for further analysis. The resultant
temperatures are a better indication of the thermal comfort in the zone than the air
temperature.

Resultant Temperatures for all zones

Now, clear all selections. In the building zones option, change the zones to only the
reception, then go to b temperatures, and then plot the a dry bulb temperature and the
e resultant temperature.

126
 Dry Bulb v/s Resultant Temperature for Reception

The graph above shows the dry bulb temperature (air temp) is 25 ºC, as expected. Still, the
resultant temperature, ie, the temperature that people perceive in this environment, is in
the order of appx. 28 ºC. This means that providing the desirable environment requires
lower setpoints or changes other features in this zone.

This tutorial addressed controls: setpoints, maximum capacities, and operating times of the
heating and cooling systems. Only the time period of 9 am-6 pm was covered, but similar
changes can be applied to other periods and days of the week.

Edit Selection
The q edit selection option can be used to remove or retain some information in the
graphs. In the example below, the option marked by the asterisk can be selected to
remove them from the graph. Clicking on the option deselects it (removing the asterisk).
Exit to save the changes.

Thermal Domain

127
11 Changing model geometry and materials
This tutorial describes how to alter the reception constructions, geometry, and operation
to improve comfort. Some of the things that can be done are change the geometry,
construction materials, and zone operations.

11.1 Changing surface properties

Go to m browse/edit/simulate and in the building sub-section, go to c composition.

Here, three things can be changed: the geometry, the construction materials, and the
operations. This section discusses the construction materials, particularly for the reception.

Click on the option b construction materials, then a reception. Select use it, then continue.

128
Here is a list of all the materials in the reception. Click on any option to access further details
on the materials and their relevant properties.

Now, click on a south wall. The emissivity and absorptivity values are defined for both
sides of the wall. Emissivity is related to the capacity of the material to release energy by
longwave radiation, and here, the emissivity value is 0.9, which is a normal value.
Absorptivity is related to the ability of the material to absorb solar radiation (short-wave
radiation).

129
Change the absorptivity value for the south wall to a lower level, which would occur with
the use of special paint. This approach reduces solar gains on the wall, thereby decreasing
the cooling needs in the zone.

Click on d absorptivity, then change the values for both walls to 0.3.

This tutorial does not run the simulations after each change, otherwise, it would get quite
long. However, it is recommended that new users run the simulation after making every
change. The changes made above, in particular, have a very small effect on the results since
it is a change in only one wall.

This tutorial does not change the absorptivity of all the walls in the reception since it is
unlikely that the major gain is through the walls. Most likely, the major gains are through
the windows or through the roof, which is poorly insulated.

Change in emissivity values, on the other hand, may have a significant impact (in spite of
the challenges on implementing them in real buildings). Suppose a very low emissivity
material, like polished aluminum, is used. Click on c emissivity, then change the values for
both walls to 0.1.

Now, the wall is made of polished aluminum with very low absorptivity. The simulation can
be run to observe the effect of these changes on the results. Properties of the different
walls can also be adjusted to examine their impact as well.

11.2 Construction definition

Another potential adjustment is the material of this wall itself, which currently consists of
four different layers, as specified in options k-n.

130
Layer 2, with a very low conductivity value of 0.04, serves as the thermal insulation layer. It
has a thickness of 75 millimeters, providing substantial insulation. Additionally, an air gap
exists—layer m—with a conductivity of 0.00 (negligible) and a resistance value of 0.17.

The U-value indicates the performance of this wall. The U-value, or thermal transmittance,
represents the rate of heat transfer through a surface divided by the temperature difference
across it. For further details about the U-value, refer to the following link: U-Value
Explanation.

Click on b construction, then select j legacy constructions & models, then select a
extern_wall.

External Wall Properties

As shown in the image above, the U-value of all layers in this wall is approximately 0.39.
This indicates that the thermal transmittance of this wall (excluding solar radiation under
steady-state or idealized lab conditions) is around 0.4 Watts/m² per degree Kelvin
difference between the indoor and outdoor temperatures—a relatively low value.

Now, adjust the wall selection to compare the U-values of the two walls.

Click again on b construction, then k construction for UK compliance, and select d

exWall_typic.

External Wall Typical Properties

In this case, the U-value is higher, indicating that the transmittance value is also greater.
This wall permits more heat to enter from outside during the cooling system’s operating
hours. Previous tutorials showed that at night, this zone remained very hot due to the
accumulation of daytime heat that couldn’t escape the building.

131
A higher U-value is not always advantageous, especially in summer, as it may prevent the
building from cooling down effectively. Testing different U-value levels could help
determine if adjustments provide any benefits. Note that this value doesn’t account for wall
weight, so additional analysis may be required to consider whether the wall is constructed
from lighter or denser materials like concrete or brick.

Save the construction changes.

Let's investigate how to implement a new construction in the model since, in many cases,
that is a better option. Go to b material databases in the model management window
(the first ESP-r window). Here, option c material properties and e construction are useful
for changing the model properties. Click on the option e construction.

Using the standard ESP-r database means the path for this database is set to the standard
ESP-r installation. To avoid modifying the ESP-r default file, create a copy of the
construction and materials in a local file. To do this, click on d copy default file to model.
Select the file name and save it.

132
Once the file is copied file, it is possible to change properties.

Go to j legacy constructions & models, then the option a extern_wall.

The External Wall consists of four layers comprising of brick, glass wool, insulation and
breeze block. Here the type of material or the thickness of the layer can be changed. Reduce
the level of insulation in this wall. The current U-value is approximately 0.39, and a change
is desired. Click on m glasswool and select yes.

133
The type of insulation material or its thickness can be changed here. Click on the option u
glasswool, the material which are already being used.

Insulation Material Entries

Select "yes," then change the layer thickness to 35 mm. Reducing the insulation level
decreases the resistance to energy flow, thereby reducing the amount of energy transferred
through the wall.

Change the bricklayer by click on the option l lt brown brick. Use the same material, but
change the thickness of the layer to 300 mm.

134
The U values have changed. Changing the properties of the different layers affects the
overall transmittance and thermal conductivity. In layer 1, the wall is a massive wall, and
requires significant amounts of energy to cool down and heat up. So, even though the
resistance might be similar between the walls with thicknesses of 100 and 300 mm of brick
the U-values changed significantly.

Material Properties Feedback

When changing the construction materials, consider the transmittance and thermal
capacitance of the surface. Various properties of the brick wall are displayed in the feedback
window, including a conductivity of 0.96 and a density of 2000. The thermal capacity of this
wall can be calculated using the specific heat.

So far, all tutorials have utilized predefined materials, such as brick and glass wool. If a new
material is required, exit the construction database and navigate to the materials database.

Click on c material properties in the Database Management Window. Again, copy this
material file to the model file.

135
Here, new materials such as new bricks, insulation, or concrete can be created. Take, for
example, light brick. Go to a Brick, then g light brown brick. Clicking on this option lists
all the properties of this material.

Change the density of this brick to 2200 kg/m3, the updated information from the
manufacturer. Save the changes. Now, this value is be used in all the simulations. Exit the
menu.

It is good practice to save the material database and then update the construction
database. Go to the construction database, click on browse/edit, go to the material light
brown brick and see if the changes made in the material database show up on the
construction database. Save the changes and exit.

After this process is completed, make sure that you update the changes for all the zones.
To do that, go to m browse/edit/simulate, then c composition, then b construction
materials and click on update all zones. Then exit.

With this, the first part of this tutorial is concluded - demand adaptation using zone
properties in construction materials.

136
Now, materials and construction properties can be adjusted to reduce or increase thermal
gains in appropriate areas. In this case, the roof may be the primary issue; however, it is
essential to investigate all zones and the energy requirements thoroughly. Given that the
roof is significantly hotter than the other zones, it is likely that the roof contributes to the
heating in those areas.

11.3 Glazed surfaces

Now, let's move on to another option of demand reduction: changing the glazing type.
Windows tend to respond to solar radiation very clearly. Go to b construction materials,
then a reception and select use it. The option j glz_s, can be seen, ie, south glazing for the
reception.

Construction properties for the glazing can be changed in the same manner as done for
the external wall earlier in the tutorial.

Glazing sets have different construction types, listed in b construction, which are a
particular sequence of layers. The optical property files are stored in the optical property
option.

The optical properties determines how energy passes through the glass, defined in terms
of solar radiation - transmission, absorption, and reflection. Click on b construction then d
glazing, then h tripglz 089. Selecting the different options substantially changes the
amount of energy that passes through this window, ie, the solar gains entering this zone.

137
Changing the glazing type also updates the optical properties to reflect the corresponding
optical data for the selected glazing type. Exit and save the changes, then update all zones.

Error Message
Returning to the reception, an error message may appear due to a mismatch between the
number of layers and the transparent optical properties of the selected material. To fix this
issue, update all zones.

11.4 Size of glazing

A simple way to reduce solar radiation in his case is by reducing the size of this window.
This requires a change in the zone geometry of the zone. Let's see how it can be done for
the reception. Go to a geometry and attribution, then a reception.

Initial Geometry
138
Every vertex in the model corresponds to a set of x, y, and z coordinates. Clicking on d
vertex coordinates lists all the vertexes and the corresponding list of coordinates. By
changing these coordinates, the position of any point in the model can be adjusted,
allowing the model to be rebuilt for specific purposes. In this case, the size of the window
can be altered by modifying the vertex coordinates.

Option e surface list and edges lists all the surfaces and the corresponding edges and
vertex number. The south window has the following set of vertexes: [15, 16, 17, 18], as
seen in the option j glz_s.

139
Changing the position of this point should allow for the adjustment of the window size. Go
back to the vertex coordinate list and note the coordinate sets for the vertexes of the south
window.

Points 15 and 18 have an x-coordinate of 2, while points 16 and 17 have an x-coordinate

of 8. Change the second x-coordinate from 8 to 5, which will move these two points to the
middle of the wall. This adjustment results in a smaller window, reducing the amount of
solar radiation entering the zone. This change directly impacts solar gains and the cooling
load for the building, particularly in winter, since the thermal transmittance of the window
is higher than that of the wall, meaning more energy escapes through the window during
colder months.

There is no need to change the y-coordinates, as they define the location of the points in
the horizontal direction. Change the values of the z-coordinates from 1 to 1.5 for points 15
and 16.

Reduced Southern Window

140
This method is a straightforward demand reduction approach since changing the size of
the surfaces relative to each other reduces the energy demand.

A useful option is the i rotation and transformation feature, which allows for the rotation
of zones within the model. By changing the direction, the model can be oriented to face
East, West, or North. While it is not possible to change the orientation of an existing
building, rotating a building under design can sometimes enhance its thermal performance.
This option is not explored in this tutorial.

11.5 Operational changes: imposed airflow

This section addresses changes in imposed air flow rates to the thermal zones using
operation files.

⚠ Airflow may be due to natural and/or mechanical ventilation. Natural ventilation

depends on several factors, such as wind speed, direction, surroundings, building shape
and the positions, sizes, and characteristics of the openings. The same applies to mechanical
ventilation, which depends on fan pressure x flow characteristic curves, duct
length/diameter/material/path, wind speed/direction, etc. The imposed air flow rates in this
section do not take any of these factors into account and can be used only to explore the
impact of imposed airflow on the thermal energy balance of zones.

Click on c operational details. Start from the roof since the reception and the office are
expected to have a certain amount of fresh air coming into the space to supply air for the
occupants. This adds a certain amount of casual gains in these two zones, but that is not
the case for the roof. Click on d edit casual gains to see the casual gains in the roof.

141
 Casual Gains in the Roof

As noted, there are some casual gains from lights present in this roof space (which is
uncommon in most buildings). Currently, 800 W of energy enters this roof during weekdays,
which is an unreasonable assumption. Change this value to 0 W. This simple measure
should reduce the temperature of the zone. Since the roof space is connected to the other
zones, this adjustment should also decrease the cooling demand for those zones. However,
it will increase the heating demand because the energy that was entering the roof
previously helped maintain warmth in the building. When adjusting lighting or equipment
gains, it is important to remember that any changes may have opposite effects in summer
and winter.

Click on c edit scheduled airflow. It can be seen that there is no airflow. This scenario is
well-suited for the winter when we would expect to have an airtight roof to prevent cold
air from entering inside the roof. This would prevent the extraction of the heat from the
other zones. This, however, would be unpleasant for the summer, During the summer, there
is a need to have a different infiltration rate, to emulate opening windows in the roof to
cool it down, particularly during the night. So a model is needed that is focused on the
winter or on the summer, with varying cooling and heating needs.

Assuming that this model is for the summer, a flow rate suitable for the summer could be
implemented. To do that, add a new period by clicking on the option +
add/delete/copy/import flows. Select add period, all day types, and specify the time
from 0 (midnight) to 4 am. Select AC/h (Air Chains per hour), with an infiltration rate of 3
ac/h. Infiltration and ventilation in this context have the same meaning - air coming in from
the outside, so leave ventilation as is.

142
 Night-time Purge Ventilation

This strategy is called night ventilation. During the summer, it is a very effective strategy
to reduce the energy consumption of buildings because it uses cool air from outside to
ventilate this space, thus cooling it down. In the morning as the occupants enter, the cooling
load should be reduced due to the already cool air inside. This requires an automated
window that would open at midnight and close at 4:00 am in the morning. If it is simulated
for the entire year, the simulation gives inadequate results in the winter when windows
should not be opened for cooling purposes.

So for this demand reduction strategy, it is required to have two separate models - one to
analyze the winter airflows and one to analyze the summer airflows in such a way that it
can be seen this strategy in a simplistic way.

Save this operation file.

Now, let us see the airflows in the reception.

143
 Reception Airflows

There is an infiltration rate of 0.3 AC/h (air coming from outside) and a ventilation rate of 1
AC/h (air coming from office - see image above), 24 hours a day. Again, it is particularly
suitable for the full year, especially in the winter because the airflow would bring cold air
into the reception. Click on c vent rate to change this value, and then specify the airflow
unit to AC/h, no need to change the ventilation rate, then click on ambient db T, and select
yes. The new vent rate should be seen as 0 and the new infiltration rate as 1.3.

This is a rather simple approach. A better idea would be to add a new period. Go to+
add/delete/copy/import flows. Select add period, one day type, then a weekday, and
specify the time from 0 (midnight) to 9 am. Select AC/h (Air Chains per hour), with the
ventilation and infiltration rate of 0 ac/h. Now there is a new period from 0 to 9 and the
rest of the day from 9 to 24, both with an infiltration rate of 1.3 and a ventilation rate of 0.

144
Change the infiltration of the first period to 0.3, by clicking on b infil rate. During the night,
there is some undesired air entering this building but no ventilation and during the day.

Infiltration accounts for air coming from outside (either by infiltration through cracks or by
openable windows). The field Ventilation is restricted to air movement between zones, or
to air injection into the zone at predefined temperatures. This is why ESP-r adds up the
ventilation flow rate into the infiltration one, and sets ventilation to 0.

The same can be done for the end of the day. Add a new period from 6 pm (18) to midnight
(24). Change the infiltration rate to 0.3 and the ventilation rate to 0.

Amended Airflows

145
Now, during the day, outside air comes to the zone; during the night we don't have air
coming to the zone. Thus, by controlling the amount of air entering the zone, the cooling
can be controlled and heating needs of the zone.

Guidelines and standards provide reference value in liters per second, per meter square of
building, or per person, depending on how to approach this problem. The method shown
above is a very efficient demand reduction strategy because only fresh air is provided when
it is needed and in the amount that is needed.

11.6 Operational changes: casual gains

The casual gains are occupants, lighting, and equipment that add heat to the building.

Casual Gains in Reception

During the winter, the casual gains have a positive effect because the additional energy
helps to keep the building warm. During the summer casual gains have the opposite effect
when there is need to remove this heat by air conditioning or other means. So, it should be
analysed carefully to see if these values are reasonable.

146
Each person is assumed to add energy in the order of 100 Watts and since the gain is 800
Watts, talking about a place with 7-8 people in this reception what needed. This is a
significant number, but the assumption that all people are present in the reception all the
time is not a very sensible assumption. The office space attached to the zones is quite small
so it could be manipulated and this would have an impact on the heating and cooling
demands.

The user could test how the building would react to these different values. Equipment as
well; there is here in the order of 2.5 kW of equipment running in this zone. Particularly
during the night, from 0 to 9, there are still 600 Watts of equipment, and from 5 to midnight,
800 Watts.

In an energy-conscious building, it is preferable to turn off most of the equipment at night

unless essential. A server should not be turned off, but there should not be an expectation
for a server to be running in the reception of this building.

By analyzing this and making fair assumptions, demand can be manipulated to better
reflect reality, not just to reduce the load. That would make absolutely no sense.

With this, this tutorial concludes, covering how to control the energy demand of the
building by changing the construction materials and editing the material and construction
databases for the model. It was also learned how to change the geometry of the building
by adjusting the relative size of surfaces and how to modify operational details, including
imposed air infiltration and ventilation, as well as casual gains related to people, equipment,
and lighting.

Thermal Domain

147
12 Creating a new thermal model
This tutorial will cover the creation of a simple ESP-r model with one zone.

12.1 Creating new model

Click on e create new. Name the new model demo-1zone. The model description can be
adjusted according to preference. The name on the log file can also be edited. In this case,
the log file name will remain unchanged. No associate image will be selected, as no pictures
are available. The latitude is set to the default, the longitude to -4.1, and the altitude
remains at the default setting. These options can be changed later if needed. The
assessment year will be left as is.

The window will close and the new window will open with the new model and the above
settings.

The model should also be saved in the system. This can be checked by either going to the
home folder or by checking using the UBUNTU command prompt.

12.2 Geometry
To start creating the geometry of the zone, click on m browse/edit/simulate. Then click
on c composition in the Building sub-section. Here, the geometry, construction and
operational details can be created to run a simple simulation.

148
Start with creating the geometry. There are multiple methods of creating the geometry, as
seen in the image below.

Here, the input dimensions option will be used, as it is the simplest method. The zone can
be named Reception, and the description can be adjusted according to requirements. This
is important if the file is exported, as this information will be copied.

Next, there are multiple options for the zone shape, as shown in the image below. A
rectangular zone, a polygon-based plan, a general 3D, or a bitmap can be created in case
a building or system design is available. A nice example of this is in the user's guide.

In this case, the rectangular plan will be used. First, define the lower-left corner as (0,0,0),
then set the length, width, and height (i.e., the opposite top right corner) as (1, 0.5, 1.7).
This essentially describes a fridge.

The orientation of the rectangle can also be changed. In this case, it will be kept at 0.0
degrees. The elevation option is useful if the model has several floors or levels. The zone
will be assumed to be on the floor, and the elevation will be left at 0.

Now, the wireframe of the model is visible. The zone name will be changed to Fridge by
clicking on the option to a name it.

149
The menu also has zone statistics such as volume, area, etc.

Option d vertex coordinates lists all the coordinates. Here, the coordinates can be edited
in order to change dimensions or to transport the model to a different location.

150
Option e surface lists and edges lists all the surfaces and the corresponding vertex as well.
The surface name and vertices can be changed according to requirement.

12.3 Surface Attribution

Option f surface attributes is particularly important because here it can be easily defined
the composition of the walls and the surfaces they are facing.

Select attribute many. As seen from the image below, there are multiple ways to define
surface attribution. Select Impose Boundary Conditions.

151
Define the boundary condition as exterior. This means that all the walls are facing the
outside environment. Then exit. Select all items.

Now, since the base cannot face the same environment as the other walls, the boundary
condition for the base will be changed. Click on the base, then on f environment. Assuming
this will be a well-insulated base, click on i adiabatic.

Now, in the construction, Go to attribute many, then select composition. Click on j Legacy
constructions and models.

152
An external wall will be selected, which is a massive insulated panel with 75 mm of glass
wool, and it will be attributed to all items on the list.

Now, all surfaces are fully attributed. By clicking on a surface, properties such as areas,
thickness, thermo-physical properties, and the name can be viewed.

Change the name of the first wall from Wall-1 to door-frame.

12.4 Editing geometry

This part of the tutorial will go over how to include a window in the door frame. Click on e
surface list and edges. Then click on + add/insert/copy/extrude_from. Then click on the
option c inserted into a surface.

Now, click on % of surface area, and specify the percentage as 70%. This means that the
window will occupy 70% of the door-frame surface area. The wireframe should now show
the window within the door frame. Select ok and then name the window as per preference.

153
In the menu, it can be seen that ESP-r has created new vertices to accommodate the
window. Another point to note is that the door frame is no longer a surface, but a
rectangular cut-out, with coordinates detailed in the menu.

154
Now, it has to be specified the surface attribution for the window. It has the exterior
boundary conditions since it inherited this property from the door frame. However, the
composition has not been specified. Go to e construction, then click on d glazing. Then
click on the option for double glazing - a dbl_glz.

Exit and save by clicking on ! save in the Zone 1 Geometry menu. Exit.

12.5 Updating zone construction

Now that the geometry is defined, the construction materials will be addressed next. Click
on b construction materials in the Building Compositions menu. The file was not found,
but since it is defined it all in the previous part of the tutorial, a file using this name can be
created. Click on a Fridge, then create using this name, and finally current format with
optical data.

155
Now, it should display all the properties that has been defined in the surface attributes
earlier. Save the construction data.

12.6 Operational details: casual gains and imposed airflows

Now that the geometry and construction materials have been defined, the operational
details can be specified.

Click on c operational details. Click on a fridge and select the file name based on
requirement and click ok. Click on nothing happens in this zone, ie, there is no pattern of
casual gains and no internal gain. It will not be taken into consideration the gains due to
the lights that are inside this fridge. It is also assumed that there is no airflow. Also, the
cooling required for the repeated opening of the fridge. So it's quite a simplification, but it
is adequate to run a simple simulation.

156
All options in the thermal domain—geometry, construction, and operations—have now
been defined.

ESP-r offers many more possibilities in terms of the electrical domain, CFD - modelling all
the compressors, the heat exchangers and heat pumps, and much more.

12.7 Zone control

Now that the zone has been defined, the controls in the zone need to be specified.

Go to i zones in the control sub-section. Specify the file name as per requirement, then
click ok. Then click on make new file. Click on heating and cooling, then select one day
type since the fridge needs to be in operation regardless of the day. Specify the number
of periods as 1 to have only one time period - of the 24-hour regime. This makes the model
creation much simpler since it is no longer need to define the controls in the different time
periods separately.

157
Now click on e bld_loop_01 and click on b sensor details. Then click on a senses current
zone db temp. There are no nested controls, so click on no.

Click on c actuator details. Here, the position of the actuator will be defined. Click on a
current zone air point, as it is assumed that the heat flow is fully convective and all the
heat delivered to the zones is delivered to the air.

158
Now, click on d period data. At this stage, the control is free-floating, ie, there is no
heating or cooling in this fridge.

If the simulation is closed now, ESP-r would run the simulation. However, this will be
changed to the heating and cooling law, so the law will be adjusted from free floating.

Click on option a, then 2 Law to change the control law. There are a number of laws to suit
the different types of control systems. Click on the option a Basic controller for
heating/cooling.

159
Now define the heating and cooling settings. Specify both the heating and cooling
setpoints to 5 ºC, which means that regardless of the condition outside, the system will try
to maintain the internal temperature at 5 ºC. Save the changes.

160
Now, it can be seen the updated controls in the control period menu.

Exit. In the Controls menu, click on d link loop to zones. Now, save control data.

12.8 Model simulation

The model defined above is by no means an exploration of the full capabilities of ESP-r. It's
just a sample of the rudimentary capabilities that can be used in ESP-r to run the simplest
simulation.

Go to s simulation, then a simulation presets since it is highly recommended to define it.

Click on yes, then change the name according to preference. The start up days will be
changed from 1 to 3. This means that the simulation will run for 3 days before the results
are displayed.
161
Run an automated integrated simulation.

12.9 Results analysis

This section covers the basic analysis of the simulation results.

First, plot the dry bulb temperature graph. As expected, the temperature is exactly at 5 ºC.

162
 Dry Bulb Temperature Graph

To check the heating, cooling and humidification, click on h heat/cool/humidify. First,

select a sensible heating load. Since the fridge is exposed to the outside environment, the
external temperature fluctuations affect the internal temperatures. For this reason, there is
a need for heating at some specific time periods in the day.

Dry Bulb Temperature with Heating Load

Now, click on b sensible cooling load. The cooling load is negative since it extracts energy
from this fridge to keep it at a lower temperature. As the sun rises, it will lead to some solar
gain entering from the window. This energy will need to be extracted to maintain the
temperature in the fridge at 5 ºC.
163
 Zone Temperature with Heating and Cooling Loads

This concludes the tutorial on creating a very simple ESP-r model.

164
13 Thermal model with a PV panel
This tutorial covers the modelling of a renewable energy source, the Photovoltaic Panel, in
an existing ESP-r model using integrated renewables. No electrical network is involved in
this tutorial.

Open ESP-r, then click on d open existing, and select exemplar. Then select a simple and
f multi-zone with convective heating and cooling. Exit the menu. Click on proceed and
select the file location where the file is to be copied. The new model will now open.

13.1.1 Editing the model construction for PV panel inclusion

Before including the PV panel, the construction of the roof needs to be changed to include
the layers related to the PV panel.

To check the material used for the roof, select m browse/edit/simulate, click on c
composition and then b construction materials. Select c roof_space, then select use it.

Now, the composition of the roof is visible, identified as OPAQ roof_1. It is necessary to
search for roof_1 in the database and include the PV layers in roof_1. Click on roof_1.

165
As evident from the picture above, roof_1 does not have glazed layers for the PV. It consists
of material for insulation and the outer and inner layers of the roof.

Press exit several times and return to the model management menu. Press - exit one more
time it will close the model.

Go to b databases and then e constructions. As evident, the model is using the standard
database material in ESP-r. Instead of changing this database, copy it to the model file by
selecting d copy default file to model. This means that now instead of being in the
standard database, the file will be in the model.

Now, if "exit" is pressed, it will be evident that the file being used is the <mod> (model)
file, not the <std> (default) file. This change can be seen in the saved file on the computer
system as well.

166
Now that the file is copied to the model, it can be edited. Go to a browse/edit. Since it is
known that roof_1 is in j legacy construction and models, go to that option and click on
e roof_1. Instead of changing roof_1, make a copy of it. It is good practice to change this
copy, instead of the file itself. Go to 1 add/delete/copy/invert then click on roof_1. Exit the
menu and change the name as per preference.

Now, the layers related to the PV panel on the roof can be added.Click on ! add or delete
a layer and click on insert. Here, the existing layers of the roof can be added. The roofing
felt in the outermost layer where the PV Panel is to be inserted. The other layers are the
inner layers. So, select c roofing felt. Exit the menu and select use it.

First, a gap between the PV panel and the roof will be required. Click on q GAPS and select
an air gap. Click on it and choose the default for all remaining questions. Now, the gap has
been inserted. However, the material cannot be left in this manner; a gap cannot be the
outer layer. Therefore, if an attempt is made to exit the menu now, it will fail.

Now, another layer will be added. This time, after selecting ! add or delete a layer and
then insert, select the gap later since it is the outermost layer now. Go to m glass and
167
ceramics. Three layers of glass are required: two layers of the low iron glass that is used in
PV panels and one layer of the EVA - the electrical layer that actually has the PV cells,
between the two low iron glass layers.

Click on j low-iron glass. Change the thickness to 3 mm. Repeat this process for the
remaining EVA and low-iron glass layer. Each time, be sure to select the outermost layer
and change the thickness to 3 mm for all the layers - first the EVA layer, then the glass layer.

Now, there is a layer of EVA panel with two layers of glass on either side and a gap layer
between the glass and the roof layer, along with the pre-existing internal layers of the roof.

Exit and save the data. Now there is a new roof with a PV panel.

13.1.2 Simulation results

The material can be changed by going to m browse/edit/simulate, then c composition,
then b construction materials, c roof_space, c s_roof, b construction, j legacy
constructions and materials. Material roof_1 can be chosen on page one, and roof_12 (or
whatever the new roof material has been named) can be selected on page two of the
material list.

168
If the automated simulation is run with the previous material (roof_1), the energy delivered
is 42.5 KWh, but if the simulation is run for the new material with the PV panel (roof_12),
the energy is 42.9 kWh. There is a small increase in the energy. This is because adding new
layers requires more energy.

The energy delivered can be accessed by going to t result analysis, d enquire about and
f energy delivered.

13.1.3 Integrating PV panel into the roof

Now turn on the active conversion between radiation and electricity. Go to m
browse/edit/simulate, c composition and m integrated renewables in the special
components sub-section. At this point, a special components file will be created since one
does not currently exist. The file should be named according to preference and will appear
in the cfg folder of the ESP-r file.

To add new renewables, click on + add/delete items and click on new component. Select
1 crystalline PV and a BP_saturn_36cell. The information about this cell is available on
the internet. The data is pre-loaded in ESP-r already, so, there is no need to type in all the
information. Accept all the defaults.

The reference insolation is used for collecting this data and the reference temperature is
used to calculate the temperature of the layer at each time step and correct the efficiency
of the PV panel. The PV Panel should be placed on the EVA layer on the s_roof (south roof).
ESP-r will automatically select the node in the middle of the layer (node 4).

169
The radiation that strikes the south roof will be converted into electricity based on the
properties of the PV Panel that was selected above. Now, update the file.

13.1.4 Simulation with integrated renewables

Go to s simulation. To change the name of the results file, go to h zone results. Change
the name according to preference. This ensures that a different result file is read than the
previous one.

Now, run an automated simulation. After the simulation is completed, open the result
window. Go to energy delivered. The energy delivered is the same as earlier. And with PV a
small increment in the heating demand is present because part of the thermal radiation
that was available before is no longer available - it was converted into electricity.

Now go to t results analysis and select a graphs, a parameter plot, and m

renewables/adv. comp. Plot the heat/power output graphs.

Integrated PV Power Output

170
The output of the PV panel should correlate with the solar radiation. Go to a weather, c
direct normal solar radiation.

The solar radiation is quite high on the two days with significant energy production from
the panel, measuring around 700 W/m², which leads to a production of 80 W. The results
for all the days will need to be integrated to determine the actual output. The other days
are likely overcast; however, if the diffuse solar radiation is plotted, some degree of
radiation will be observed on these days as well. The diffused solar radiation is also being
converted into electricity.

Integrated PV Power Output and Solar Radiation

This is the simplest approach to calculate PV production, electricity production using PVs
in ESPR without using an electrical network. This method neglects the interaction between
the PV and the other parts of the electrical system, so it's a rough initial estimate of
electricity production. Note the maximum power - which is around 80 W.

Now, try to see the effect of changing the number of PV panels on the surface. Go to c
composition, m integrated renewables. The special component file exists already. Select
b BP_saturn_36cell to change/edit the component. Accept all the defaults, but change the
number of panels from 2 to 5. Follow the same process as before.

Change the name of the result file before running the integrated simulation. In the result
analysis, it can be seen that the Power Output has increased to 210 W. So, the increase in
energy can be seen as the number of panels is increased.

171
 Integrated PV Power Output With 5 Cells

172
14 Exploring exemplars variants
14.1 Exemplar text files
One of the most important characteristics of ESP-r is its openness. Therefore, input is
defined in text files that can be easily opened, investigated, and modified in any text editor.
The user interface of ESP-r is meant to support new users. However, users often prefer to
manipulate input files directly for certain tasks once they get familiar with the file structure
and syntax. New users are not required to read or manipulate input text files, but getting
used to these files can improve the ESP-r learning curve.

14.2 Open an exemplar model with variants

Open the exemplar a simple > a zone with convective heating & basic control.

This model has a variant with underfloor heating.

The folder img of the model has two montages, one for the base model and one for the
variant (reproduced below).

The first model opened in ESP-r is shown in the image below (left), and a montage with this
model representing the control hours and setpoints is provided (right).

14.3 Comparing configuration files

Settings for the model with convective heating are stored in file bld_simple.cfg, and the
settings for the underfloor heating variant are in bld_simple_ufh.cfg. If these two files are
compared using an application such as Meld of kdiff3, the results indicate that a single
relevant line is changed between these models.

173
Line 62 (in both files) shows that these models use different HVAC control files. This is
expected as heating is injected on the floor in the second model. Apart from the control
file, the models have no significant differences.

14.4 Comparing control files

Comparing the two control files, again, only one line is modified. Line 9 indicates the
actuator of the controls (i.e. the point where energy is injected or extracted from the model
in case of heating or cooling). In the base model, energy is injected in the air node of the
zone (represented in the file by the values 0 0 0. In the variant with underfloor heating, the
actuator location change from air to component (1), and in this case the following values
indicate the the surface number (9), and the node in that surface (7).

The lack of additional differences indicates that floor heating is modelled using a high-level
abstraction of the system, describing it only by the way the control file interacts with the
model. It also indicates the model is likely the representation of an electric heater, as a
water-based floor heating system would require additional information such as pipe
diameter, pipe material, flow rates, and inlet temperature. Finally, as components are
modelled as 1D heat transfer energy paths, the approach used in this model means energy
is delivered to the whole floor at the same rate, and the circuit of wires, the distance
between them, and any other 3D effects are not accounted for. Investigating changes in
input files can reveal valuable information about the nature of the model.

174
Bulk Fluid Flow Domain

175
15 Exploring an airflow network
This tutorial explores a model with an airflow network and reviews its most common
features.

15.1 Natural ventilation exemplar

Start ESP-r. Click on d open existing, exemplar, then b technical features. Select c with
natural ventilation.

Select the file name and copy the model files to the user folder.

176
The model consists of two offices and a corridor. It can be visualized as a part of a larger
building with rooms on the other side and several other rooms on the top and bottom
floors since these surfaces are all defined as similar in boundary conditions.

In the m browse/edit/simulate menu, the item f network flow in the network sub-
heading is already defined (since the model has an in-built natural convection system). In
the Control sub-heading, several control loops are defined as well.

Click on f network flow. Select existing network (this is the file that stores all the settings
of this air flow network), then select the file name and click ok. Select yes for file summary.

177
15.2 Network nodes
Click on c nodes.

In total, there are eight nodes in the model. Among these, five are boundary conditions,
which are wind-defined at various heights. The orientation of these boundary condition
nodes can be seen in the Data 2 column. Several nodes are at 180 degrees (facing south).
The corridor left is at 270 degrees on the manager_a side of the building. The remaining
nodes are the three internal nodes that are defined for each one of the three zones -
corridor, manager_a and manager_b.

15.3 Network components

Click on d components.

a door_cr is the crack between the doors that links the corridor and the offices, and
window_cr is the crack around the windows, both of which are component type 120. There
are high and low ventilation window cracks (low_win and high_win), and a grill on the
window (grill). These components are of the type 110. Component type 120 is specific for
cracks, while 110 is specific for openings, defined on purpose and tailored for natural
ventilation.

178
Click on e grill and select Edit component grill. Leave the component's name as it is, and
then select no for the type of component to see the list of component types. Exit the menu.

The grill's opening area is specified as 0.2 m2. The pressure drop over this opening does not
need to be specified (ESP-r calculates it automatically).

15.4 Network connections

Click on e connections. The connections show how the boundary condition nodes are
connected to the indoor nodes and how these indoor nodes are connected. Four of the
boundary conditions are connected to the offices, and the two offices are, in turn,
connected to the corridor. The corridor is also connected to the outside through the
corridor left node.

179
180
16 Analysing the results of an airflow network
This tutorial will explore the results of an airflow network in ESP-r.

16.1 Airflow simulation

Go to s simulation. The integrated simulation solves two sets of equations, one for the
thermal domain - for all of the zones (solved using a matrix) - and one for the natural
ventilation that results from the flow network. The results are going to be stored in a
separate file, shown in the zone and flow results options.

Click on q integrated simulation, then select interactive. Go to c initiate simulation.

The name of the file where the results are going to be stored has already been specified
earlier, so select ok.

181
Click on s commence simulation and continue the simulation. Save the results and
complete the simulation.

Exit the window. The options here are all related to the simulation itself such as running the
simulation rather than configuring the simulation and input required.

16.2 Result analysis

Now that the simulation is complete, click on t result analysis.

16.2.1 Thermal domain results

Go to a graphs, a parameter plot, b temperatures, and finally a dry bulb (db) temp. The
temperatures in the two offices are identical. There is a clear day and night pattern- heating
at 19°C during the day and 15°C at night. The weekend patterns are different since there is
no heating or cooling activated on these days.

Temperatures in Thermal Zones

16.2.2 Airflow domain results

Exit the menu and return to the graphing options menu. Go to f network flows.

In the menu, there are several different options related to the airflow network, such as wind
speed, direction, relative humidity, the pressure at each one of these three nodes, calculated
for each time step, pressure difference across connections, the temperature of the nodes,
the mass flow rate, etc.

182
Click on i mass flow rate, one of the most important values relevant for an airflow network.
Select c total entering node, then manager_a.

Mass Flow into Manager_a

183
The mass flow rate is given in kg/s.

Mass flow entering the node is always a positive value. In the case of flow through
connections, the sign of results is related to the order nodes are listed in the connection.
Positive values indicate the flow is from node 1 to node 2, while negative values indicate
the opposite.

Without clearing the selection, click on options b wind speed and c wind direction.

Wind Speed, Direction and Mass Flow Rate

On some days here the wind direction is around 180 degrees ie, the south. When the wind
comes from the North, there is no significant pressure on the windows to drive the airflow,
as seen from the lower mass flow rates.

Clear all selections.

Click on k air changes, then c total entering node, then manager_a. The air change rate
is in the number between 1 and 31 air-changes here. Again, the values are much larger than
what the graphs indicate. Even though 1 may seem like a small number, that is not really
the case and 31 is an incredibly large number.

184
 Air Change Graph

Click on a ambient temperature. In the graphs, the outside temperature is in the order of
5 or 7 degrees, which means that having this amount of airflow might not be necessarily
interesting.

Air Change vs Ambient Temperature

185
The concentration of contaminants cannot be analysed in case, as this data is not available
in this network. There can be a network only for mass flow, or a network for mass flow with
contaminants calculation. To do that, sources and sinks of contaminants need to be set.
There is no data on the contaminants. The third tutorial on this topic covers contaminant
modelling.

Exit the menu and go to c reports, then i network air/wtr flow. Select > display to
>>screen to export to a file. This saves the simulation results. To save a specific result to
another file, select that option, and click on ! list data to export the file.

Exit the module and close the Project Manager.

186
17 Creating a new airflow network
The idea of a flow network is to impose boundary conditions as in an energy problem and
see how the fluid moves around and affects energy transfer processes in the zone. This
tutorial uses the multi-zone model with convective heating and basic control model.

17.1 Editing the zones and boundary conditions

For this tutorial, only the office will be considered since it will make creating an airflow
network and analyzing the effect of the changes much easier.

Go to m browse/edit/simulate. Then click on c composition, then a geometry &

attribution. Go to + add/delete/copy, then delete the zones reception and roof, so that
the only zone is the office.

Since the reception and roof have been deleted, the boundary conditions of the wall
previously facing the two zones have to be changed. Go to a geometry & attribution and
select a office. Then select f surface attributes and click on part_b. Go to f environment
and select a exterior. Repeat this process for part_a and door_a and ceiling.

187
Adjust the controls and impose a fix temperature of 20°C in the zone at all time. This
facilitate visualizing the air flow due to stack effect.

Save the changes and exit.

17.1.1 Explicit network definition

Return to m browse/edit/simulate, then f prescribed fluid flow under the Network sub-
heading. Here, a new airflow network (AFN) can be created.

There are several options to create an AFN - empirical model, scheduled flow, and new
network. Empirical models, as the name suggests are empirical - the fluid flows here have
been measured by researchers and they give a rough idea about the flow in a given

188
situation. However, the model does not take into account the boundary conditions and the
other factors that guide the flow. The schedule model is applicable when the flow is known.

Select New Network. The method described here uses menus & lists rather than the
graphic tool.

Select the file name where all the information is to be stored. Select create new file since
no pre-existing file exists.

For a model such as water storage with radiators or a hot water collector, it would have a
zone full of water that has water flowing to other zones and transferring energy there. For
this model, select air as the working fluid.

17.1.2 Node definition

ESP-r automatically discretizes the wall for thermal flow in a zone, such that each wall is
divided into three nodes. In the case of fluid flow, the number of nodes needs to be
specified. Go to c node and select yes for auto-generate fluid nodes. This creates flows for

189
all the zones. Select the office. This will create a node in the office, that has a type of fluid,
it has a position in space and other relevant data.

Two more nodes need to be added, that will be the two boundary conditions. Click on
+add/delete/copy node, select add, then specify the name of the new node as Window_1.
Select boundary, wind induced since in this case, the pressure will be provided by the
wind. This pressure will guide the fluid flow through my domain.

Select a office. The menu lists all the surfaces in the office. Select h west_glz dbl_glz to
put the node in the window.

Now, a new node named Window_1 has been created. Click on the node to view the details.
The fluid, node type, and node location are shown. The wind pressure set should be left at
1. There are several pressure sets depending on how sheltered or how obstructed the
building is.

190
The third node will be created in the door, to properly visualize the flow. Click on add
another node and name it Door. The working fluid is air. The node type is specified since
the pressure in the office is unknown, boundary, wind induced. Select a office and then g
door_a door to put the node in the door.

Clicking on the node shows its properties. The position, XYZ is important because at
different heights there can be some degree of stack effect - the warm air within the room
will move up, escape through the upper surfaces or the upper openings and enter the zone
by the lower point. The pressure set can be left as 1 for this node as well.

The internal unknown node is the office since its pressure is unknown. The pressure of the
office will be related to the pressure of the other nodes.

191
17.1.3 Component definition
Now that the boundaries are defined, along with the internal nodes, the nodes need to be
connected so that the energy or, in this case, the fluid can flow between them. To do this,
components are used. The procedure is similar to the electrical network.

In the electrical network, there are boundary nodes, which is the grid in most cases. Then
there are other nodes which are the PV panel, the lighting, and so on. Connecting these
nodes using connection devices and wires carries energy between these nodes in the
electrical network. The driver is the potential, so differences in potential will be translated
into fluxes of electricity and current. In this case, the difference in the potential is the
pressure, which will be translated into fluxes of fluid between these nodes through the
components.

In the Fluid Flow Network menu, select d Components, select + add/delete/copy

component, choose add, and then select Edit component New_group. The menu presents
a range of options for this component depending on how it takes energy from the flow.
Depending on the pressure drop in this component, some components will take a lot of
energy, other components will let most of the energy be translated from pressure into
kinetic energy and then into fluid flow. Component 40 common orifice flow component
is the simplest to understand since it consists of only an area and a discharge coefficient,
the amount of pressure drop in the opening, and the friction coefficient.

For a window, the efficiency is close to 0.6, which means that 40% of the energy is dissipated
when the air passes through this window and 60% is converted into the flow. Other types
of components such as ducts (for example, in an air conditioning system) tend to absorb
energy. The longer the duct or the shorter the cross-section, the higher the energy loss.
There are empirical equations to measure energy losses.

192
Select j 40 common orifice flow component and select air. Specify the area of the opening
as 1 m2 and the discharge coefficient as 0.6. The discharge coefficient for different types of
openings such as screens, grills, etc. can be found in the literature. The more barriers on
the flow, the lower this number. This means that for the same pressure drop, the flow is
slower.

For the position in space, select the option via a specific surface and click on a office.
Select g door_a and then select surface upper edge as the position.

Create another component using the same steps as before. Specify the opening area as 0.5
and the discharge coefficient as 0.6.

193
Again, select via a specific surface and click on a office. This time, select the window and
place it on the surface lower edge, to measure the stack effect.

17.1.4 Connection definition

Now that the nodes and components have been defined, the connections need to be
established. In the Fluid Flow Network menu, click on e connections. Click yes to auto-
generate the connections. It usually works well, but it may not work in this case.

Click on + add/ delete/ copy, and select add. Then, click on b Window_1 and a office to
connect the two components. Click on New_comp2. Keep the height as is. Add another
connection with the same process described above. Connect a office to c Door using
New_comp. Again, leave the height as is.

194
Now the nodes, components and connections have been defined. The wind reduction
factors can also be changed depending on the context.

17.1.5 Coupling of airflow and thermal domains

Up to this point, the model is an abstraction that is detached from the thermal domain. It
is only a fluid domain.

Click on g link nodes and zones. Link the office node of the fluid flow network to the office
node of the thermal network. Click on accept.

Save the network.

With this method, fluid flow can be modeled. Having more zones is just a matter of creating
more nodes and more connections between these zones.

17.2 Airflow network results analysis

Exit the menu. Go to s simulation. In order to save the flow results, a separate flow file
needs to be created. To do this, go to i flow results and specify the file name as flow1.mfr.
The flow network is stored in a separate results library since the flow connections are
completely separate calculations that are coupled at a point in time - so they exchange
values. The flow that comes from the fluid flow will affect the thermal, the temperatures
from the thermal will affect the fluid flow, and the calculations are carried out separately
and are stored in separate result files.

195
Run an automated integrated simulation. Then go to result analysis. Click on a graphs, f
network flows.

In the result analyzer, ESP-r may not suggest the new flow network name that was specified
before the simulation. Specify the Flow Library name as the one defined previously,
flow1.mfr.

17.2.1 Mass flow rate and wind

Click on i mass flow rate and a individual connections. Select window_1. Since in this
case, the fluid flow is related to the boundary conditions, plotting the wind speed is useful.
Click on b wind speed.

Mass Flow Rate through Window_1 and Wind Speed

The graph should reveal that higher wind speeds will lead to higher mass flows; lower
windspeeds to lower mass flows. However, the wind direction also affects the manner in
which wind speed affects mass flow.

196
 Mass Flow Rate compared to Windspeed and Wind Direction

The window is oriented at 270°, so when the wind is directed at 270°, the mass flow directly
affects the flow rate. Clear all selections and plot the wind direction and mass flow rate.
Wind coming from 270° will be very useful for this office because it's blowing directly on
the face of the window. Wind coming from any other direction will not have a major impact
since it cannot push air through one of the openings and push it through the other.

Wind Direction and Mass Flow Rate

197
The highest flow rate happens when the wind direction is close to 270°. The combination
of high wind speed and wind direction is the one that led to this particular airflow.

Model Orientation (office window at 270°)

Clear all selections.

17.2.2 Temperature-driven stack effects

The temperature stack effects can be checked by plotting the i mass flow rate, a ambient
temperature and internal temperature in the office. Click on h node temperature, then
select office.

Stack Effect
198
There is a temperature difference between these two nodes since one of the openings is
on the upper surface and the other is located in the lower surface. Thus, ESP-r calculates
the difference in the stack effect between the two nodes. The difference in stack effect is
also translated into a difference in pressure, which is in turn translated into mass flow.

Clear all selections.

17.2.3 Pressure drop between nodes

Click on f press diff @ conn and then a window_1 -> office via New_comp2. This shows
the difference in pressure in each connection, in this case the difference in pressure
between window_1 and office.

Pressure Drop between Window and Office

The points of highest pressure do not correspond with the points of higher temperature
difference and vice versa.

The individual pressures at both nodes can also be plotted by using the option e press @
node.

199
 Comparison of Pressure at Window_1 and Office

Exit the result analysis window.

17.3 Modifying simulation initialisation

This section covers detailed simulation and changing the simulation initialization.

Go to s simulation. Select integrated simulation and then click on interactive. Click on c

initiate simulation and discard the previous result set.

Click on g simulation options. The option f building initial temperature is specified as

15 °C.

At t=0, the temperature of the system is unknown. So, an initial temperature needs to be
imposed. It can be changed according to the requirements. However, the impact of this
change will not be seen very clearly since most energy simulation tools start the calculation
a couple of days before the date specified. This is done to fix the initialization error.

200
Close the module and return to the s simulation menu. Go to g from:, which shows that
the simulation period is defined from the 6th to the 12th of February. The option c start-
up days shows that the simulation actually starts three days earlier than the simulation
period.

For a simulation with a very clear and precise initial temperature, the start-up days need to
be changed to 0, ensuring that the effect of the initial temperature can be seen in the first
time step.

Go to q integrated simulation, c initiate simulation and then g simulation options.

Change the initial temperature to the unrealistic temperature of 7 °C, just to see the impact
of this change. ESP-r will then change the temperature of all the nodes defined earlier and
initialize them at 7 °C and then run the simulation accordingly.

In the Browse/edit/simulate menu of Project Manager, go to f network flow and then select
legacy network. Then dereference it. This will turn off the mass flow so that the effect of
changing the initial temperature can be seen properly. The number of networks will change
to 0.

201
The files are still there in the model. In the model folder location basic/nets, the file that
describes the flow network is still defined there, but it is no longer linked to the model. If
needed it can be used again.

Go again to the interactive simulation window. Click on initiate simulation and discard
the previous result set. Go to g simulation options. Again change the initial temperature
to 7 °C. Exit the menu and commence simulation.

Exit the module and go to t result analysis. If the simulation runs fine, ESP-r will report a
graph with very peculiar temperatures starting at 7 °C.

Go to a graphs, a parameter plot, b temperatures and select a dry bulb temperature.

Zone Temperatures with Imposed Initial Temperatures

For a very well-prescribed problem, the initial conditions and initialization of days, and
changing warm-up days are very useful.

Selecting Options
The options in the menu can be selected by clicking on the corresponding alphabet or
symbol.

202
For dialogs like the ones below, the options can also be selected by clicking on a, b, c, etc.
according to the position of the option.

For instance, a is used to select internal, unknown, b is used to select internal, known
and so on.

203
204
Contaminant Domain

205
18 Exploring a contamination network
This tutorial covers the contamination model in air flow networks.

18.1 Contaminant exemplar

This tutorial requires a new model - one with the contaminant concentration, that can show
contamination results.

Click on d open existing, exemplar, then b technical features. Select g with CO2 tracking
(open windows). Select the file name and then copy the model files to the user folder. In
this model, there is a sketch detailing how the airflow network is defined in the images
folder.

The airflow network in this model is much simpler. There are six nodes - one boundary node
in the south, one in the west and one in the east, one in the corridor, and one in each
ventilation grill on either side of the corridor. Symbol C identifies the cracks and O identifies
the openings.

To get contaminant results, an additional set of equations need to be defined, for which an
additional set of elements should be defined. Go to m browse/edit/simulate and then
click on h contaminant. Click on yes to display the synopsis. The synopsis details the
occupants in these rooms, which release CO2 into the environment, showing a list of the
contaminant sources and sinks in the model.

206
18.2 Simulation
Return to the m browse/edit/simulate menu and go to s simulation. The image here
shows the concentration of CO2, mostly at 500 ppm and it changes during the day since the
CO2 release also varies. The image should show up automatically if the Image Viewer is
installed. If not, the image can still be found in the model folder in the Images file.

CO2 Concentration

Go to q integrated simulation, then click on interactive. It is a better idea to run

interactively for a flow network. If the model has pre-simulation settings, it is rather
straightforward to run it interactively. Click on c initiate simulation and then s commence
simulation. Save the results.

18.3 Result Analysis

Close the simulator and open the t result analysis. Go to a graphs, then f network flows,
m contaminant @ node. Plot the graph for a manager_A for CO2.

207
 Variation of CO2 contamination over the week

The concentration of CO2 is 0.5 g/kg, which would be around 500 ppm. It should be kept
in mind that this unit is the mass ratio, which is not a way to represent ppm. It is an
alternative unit that is still useful to analyze the overall pattern of results.

Now, click on i mass flow rate, c total entering node, manager_a to compare the mass
flow rate entering the node to the CO2 contamination.

CO2 Levels and Mass Flow Rate into Manager A

208
As the mass flow rate decreases, CO2 contamination increases and vice-versa. The variation
pattern of the contaminant reflects the pattern of the flow rate because the discharge of
contaminants continues during the occupied hours by the users and as the wind or as the
mass flow changes, the concentration changes as well, and this is calculated dynamically by
ESP-r.

This tutorial is based on material available at:

https://www.esru.strath.ac.uk//Courseware/ESP-r/iaq.htm

209
19 Contaminant concentration in airflow
networks
This tutorial covers changing the settings in a contaminant network and analyzing the
results. This helps to understand how the different factors are interrelated in such a
network.

19.1 Changing the occupancy levels

This section covers the effect of changing occupancy levels on CO2 contamination levels at
different times.

Return to the m browse/edit/simulate menu and go to c composition under the building

sub-section. Then go to c operational details and select a manager_a. Go to d edit casual
gains.

Increase all occupancy numbers from 9 am to 5 pm by a factor of six. Simply multiply the
Sensible and Latent gains for the options d, e, and f by six. This now emulates six people in
the office during working hours.

Save the changes and exit.

Return to the m browse/edit/simulate menu and go to s simulation. Go to q integrated

simulation and click on interactive. Select c initiate simulation. Discard the previous
result set. Then select s commence simulation. Save the results.

Go to t result analysis. Again, select a graphs, then f network flows, m contaminant @

node. Plot the graph for a manager_a for CO2.

210
 CO2 Levels with Edited Occupancy

The baseline concentration is 0.5 g/kg, at non-working hours, but during working hours,
the CO2 concentration levels spike to ~2 g/kg. This is in stark contrast with the previous
case, where the maximum concentration was ~0.78 g/kg. Thus, increasing the occupancy
increases the CO2 level, lowering the air quality significantly.

Click on i mass flow rate. Then select c total entering node, manager_a to compare the
mass flow rate entering the node manager_a to the CO2 contamination.

Updated CO2 Levels and Mass Flow Rate into Manager A

211
As evident in the graph, the spikes in the contamination correspond with the increase in
mass flow rate. This is the same behavior as the previous case, although with different
contamination levels. Pay attention to the axis on either side of the graphs when comparing
the two cases.

Now, clear all selections. Display the contamination levels in manager_a, along with a wind
speed and b wind direction. The option q edit selection can also be used to remove the
mass flow rate graph. Remember to click on ! draw graph to see the changes. This method
can create some issues with the display in some cases. If that happens, simply clear all
selections and choose the options as usual.

Wind Speed and Direction Compared to CO2 Levels

the graph shows that higher wind speeds lead to higher mass flows; lower windspeeds to
lower mass flows. However, the wind direction also affects the manner in which wind speed
affects mass flow. The office is oriented at 180°, which means that when the wind flows at
180°, the effect of the wind on the mass flow rate and contamination levels should be the
most evident. This is the case in this graph as well.

Now plot the along with a wind speed and b wind direction and the mass flow rate.

212
 Wind Speed and Direction Compared to Mass Flow Rate

In this graph, when the wind direction is 180 deg, the wind speed affects the mass flow rate
directly. Additionally, the highest mass flow rate corresponds to the highest wind speeds.

Note: This tutorial is based on material available at:

https://www.esru.strath.ac.uk//Courseware/ESP-r/iaq.htm

213
20 Creating a new contaminant network
This tutorial describes the creation of a new contaminant network.

20.1 Opening a new model

The tutorial uses a pre-existing model with airflow. The contaminant network is then added
to the airflow network.

Open ESP-r and click on d open existing, then b technical features. Then select c with
natural ventilation.

214
20.2 Editing the model
In the Model Management menu, click on m browse/edit/simulate. In the Network sub-
section, there should be a network flow already defined (since the model has an in-built
natural convection system). In the Control sub-heading, several control loops are also
defined.

Then, click on h contaminant. Select yes to proceed with the model definition.

Select the file name where all the information is to be stored. Select make new file since
no pre-existing file exists.

The Contaminant Description window shows that no contaminants, sources/sinks or filters

have been defined.

215
20.3 Contaminants
20.3.1 Define the contaminant
In this model, CO2 is used as the contaminant.

Click on c contaminants. Go to + add/delelte/copy, and select add. Specify the name of

the contaminant as CO2 . The average hourly contaminant concentration is constant.

Define the concentration as 0.000480 kg/kg.

Specify the concentration at each node as equal to ambient. Select yes.

216
20.3.2 Sources/sink model
Click on d source/sink models, go to +add/delete/copy and select add.

Specify the name of the first source as occup_man_a.

Then select f personal CO2 emmision as the source model.

217
Select yes to take the metabolic rates from the casual gains from the occupancy, ie, the
persons present in the room.

Repeat this process for the second source, with the name occup_man_b.

Now select # link to contaminants. For both sources, select CO2 as the contaminant.

Select ! link to nodes. Link occup_man_a to manager a.

Repeat this process for occup_man_b, linking it to manager b.

218
Exit the menu.

20.4 Simulation timestep

Select b simulation timestep. Change the simulation timestep to 12.

Save the changes.

Select yes.

Select the file name and exit.

Finally, to cross-check, select h contaminant again and display the synopsis. The synopsis
should match the details given below.

219
Exit the menu.

20.5 Simulation
Go to s simulation and run an automated simulation. The simulator window should pop-
up for a short while and close after the simulation is finished.

20.5.1 Results
Go to t result analysis. Click on a graphs, then f network flows, m contaminant @ node.
Plot the graph for a manager_a for CO2.

CO2 Concentration in Manager_a

220
Click on i mass flow rate, c total entering node, manager_a to compare the mass flow
rate entering the node to the CO2 contamination.

CO2 Concentration and Mass Flow Rate in Manager_a

The occupancy levels can now be changed, and the effect on the contaminant levels be
analyzed.

20.6 Changing Occupancy Levels

Go to m browse/edit/simulate menu, then click on c composition under the building sub-
section. Select c operational details and select a manager_a. Go to d edit casual gains.

221
Now, for the time period from 9 am to 5 pm, increase the Sensible and Latent Gains by a
factor of 5, ie, multiply each number by 5. This essentially means that five more persons
have been added to the room during the working hours.

Select d 9 12. Leave the start and finish hours as is. Select ok.

Specify the Gain Unit as Watts.

Change the Sensible and Latent Gain to 500 W and 250 W, respectively. Then select ok.

Leave the Radiant and Convective Fraction as is. Select ok.

Repeat this process for the remaining time periods, ie, options e and f.

222
Exit the Menu and Save the changes.

Return to the m browse/edit/simulate menu and go to s simulation and run an

automated simulation.

Now, go to t result analysis. Again, select a graphs, then f network flows, m

contaminant @ node. Plot the graph for a manager_a for CO2.

Updated CO2 Concentration in Manager_a

The baseline concentration (during the non-working hours) is still 0.5 g/kg, but during the
working hours from 9 am to 5 pm, the concentration of CO2 is much higher, with a peak
value of 1.7 g/kg. Comparing this to the peak value of 0.78 g/kg in the previous CO2 graph,
there is a steep increase in the concentration due to the increased casual gains.

Click on i mass flow rate. Then select c total entering node, manager_a.

223
 Updated CO2 Concentration and Mass Flow Rate in Manager_a

The mass flow rate remains constant, but there is an increase in the concentration levels,
as expected.

224
Electrical Domain

225
21 Exploring an electrical model
This tutorial explores a model with an electrical network in ESP-r.

21.1 Opening a model

21.1.1 Opening an ESP-r model using the graphic interface

Open ESP-r. Now click on open existing, then exemplar. Go to b technical features, then
choose l .... with PV cells embedded in spandrel. Copy the model files to the home folder.

226
A new window should open with the new model.

21.1.2 Opening an ESP-r model via terminal

Open a terminal by pressing ctrl+t keys simultaneously (only for Linus OS).

Move to the home folder typing:

cd ~

Move to the folder simple and cfg.

cd simple

cd cfg

Open the model in esp-r by invoking the application prj using the file parameter to point
to the .cfg of interest.

prj -file cellular_contam_bc.cfg &

Add the symbol & at the end of any command to start the process in the background and
keep the terminal usable (otherwise, the terminal will be locked until ESP-r is closed).

To create a backup of the model files, copy the entire folder and paste it. Any modifications
made to the model, whether accidental or purposeful, will not affect the backup files.

21.2 Exploring the electrical network

227
Go to m browse/edit/simulate. The model has various zones, controls and networks. This
section discusses the networks in the model. Unlike the previous tutorials which had an
airflow network, this model will have an electrical network since a PV Panel is already
present.

Click on g electrical. Click yes to proceed with this network.

228
As seen in the Electrical Network Menu, the network consists of several elements. A
description of the phases, angles and power base value are also given. The network consists
of the following main categories:

1. Nodes
2. Connection components
3. Power only components
4. Connections to other elements
5. Network connections

Exploring each of these elements is important to gain a good understanding of the model.

21.2.1 Nodes
Click on d nodes. The electrical nodes list consists of a PV node, an inverter, corridor lights,
and a construction unit.

The nodes are the elements where energy is injected or extracted from the network. For
example, the lights will extract energy, whereas the PV node will inject energy. It is necessary
to always have one fixed node, which is always present in the network. It describes the
connection of the network with the grid, so it's a fixed voltage. The voltage for the rest of
the model will be calculated on the basis of this voltage and the other boundary conditions.

Exit the menu.

21.2.2 Connections
Click on e Connect HVAC/PV/Lights etc.

The nodes in the network are connected to other nodes. In this case, the PV array and
corridor lights are connected to the network. This means that when lights are turned on
and off according to schedules, it affects the overall energy calculation of the network. The
same applies to PV arrays as well. The variation in energy delivered from the PV Panel
throughout the day will also affect the network energy.

229
Exit the menu.

In this case, there are no power components.

21.2.3 Connecting components

Click on g connecting components.

There are three connecting components - cable for lights and PV array, and inverter losses.
These components connect the different elements and dissipate energy.

Exit the menu.

21.2.4 Network connections

Click on h network connections.

There are the cables for the light and the PV panel and the inverter loss. For each of these
elements, there is a starting node and an end node. These describe how each node is
connected to the network. The nodes are connected using these connections: node 1 goes
to node 2, node 4 to node 3, and node 1 to node 4.

230
Exit the menu.

21.3 Definition of the PV panel

Now that the basic elements of the electrical network have been established, a PV panel
needs to be added to the model.

Return to the m browse/edit/simulate menu. Then select c composition in the building

sub-section. Click on m integrated renewables in the Special Components sub-section.
Choose yes for the special components file.

The definitions for this particular panel are available in BP_Solar_380.pdf in the docs folder
in the model folder. This file is the datasheet from the manufacturer. It describes the
properties of this panel such as maximum power and voltage and the current capacity.

231
 PV Panel Specifications

The performance of the panel is dependent on the temperature. So the relationship

between the voltage and the current at different temperatures is an important
consideration.

PV Performance Temperature Dependence

In this case, using integrated simulation is very useful. Since the PV panel will be integrated
into the components, the temperature at each time step will be calculated. The simulation
will then choose the appropriate voltage-current curve for that particular temperature to
calculate the voltage and current output.

232
The properties of the PV panel are pre-defined, as can be seen in the embedded renewables
menu.

Click on a BP380_poly_36cel and select yes to edit the component. Click on 1 crystalline
PV.

Select this BP_saturn_36cell model. The BP380_poly_36cel PV Panel does not exist in the
ESP-r directory anymore.

Since the properties are predefined, there is no need to change anything. The properties
here are according to the data sheets.

21.4 Placement of PV panel

Now, the location of the PV panel has to be selected. In this case, the panel will be installed
on a surface in manager_a.

233
Select manager_a. The PV panel will be placed in the panel under the window.

Select the surface n PVmod PV_constr.

234
Now that the surface has been selected, the specific layer of the construction where the
panel will be installed needs to be selected, since the different layers will have different
temperatures. This will affect the output of the panel. Select the layer 2 EVA layer.

If these steps are being reproduced, the model needs to have a similar structure of layers
to allow the placement of the panel in the correct position. In this case, the panel is placed
on the fourth node, as suggested by the software.

Update the file to save the changes. Exit the menu.

235
Return to the Model Management menu and go to b databases, to explore the materials
for the PV panel. Click on e constructions. Select a browse/edit, then g PV_constr (on the
second page).

In the list, there are seven-layer made of different materials. The first layer is a layer of glass
that protects the solar cell underneath it. When placing the panel, the protective glass layer
should be placed on either side of the panel. There is also a gap layer that separates the
panel layers from the rest of the building facade.

This concludes this tutorial. The next tutorial will go over the simulation and result analysis.

236
22 Exploring results of an electrical network
This tutorial describes running a simulation and analysing the results of an electrical
network.

22.1 Simulation
Go to m browse/edit/simulate, then click on s simulation and q integrated simulation.
Select interactive.

The integrated simulator window should open. Click on c initiate simulation, then select
s commence simulation. Select the result fine name and run the simulation. The simulation
is quick since the simulation period is only a week.

Quit the module.

22.2 Viewing electrical results

Go to t result analysis. The result analysis window opens. The results are stored in the res
file, which contains the temperatures and heat flow through the building.\

22.2.1 Solar resource

Select a graphs, a parameter plot then a climate. Plot the direct normal sunlight.

Direct and diffuse radiation over the Simulated Week

237
It can be seen the the graph that on the third and seven day, there is a significant amount
of solar radiation. On these days major energy production from the PV panel can be
expected. On the remaining days, there is no directed radiation, but there is some amount
of diffused radiation. On these days, there is lower energy generation.

Clear the selection and exit the menu.

22.2.2 Electrical results

Return to the Module Options menu and select g electrical results.

Click on a graphs. Change the Focus from Nodes to Whole Networks by clicking on the
option repeatedly.

238
 Toggling Focus of Electrical Results

Toggle again and select the focus as nodes. Click on c generation and c pv_node. Plot the
graph.

PV Node: Generation

As expected the highest power generation of 200 W is during the third and seventh days,
which has the highest direct solar radiation. There is minor production on the other days
due to diffused radiation.

Change the focus to the whole network and plot the total loading.
239
 Whole network: generation and loads

The graph shows the energy generation and consumption (hence the negative values) -
those are related to the lighting defined in this simulation.

Electrical Domain

240
23 Create electrical network with a PV panel
This tutorial will go over creating an electrical network with a PV Panel.

23.1 Adding a PV panel and electrical network

The cellular PV model will be used as a reference for this tutorial. All the modifications will
be applied to the 'basic' model - multi-zone with convective heating & basic control. It is
recommended to have a copy of this model in the home folder, in case any damage occurs
to the working model.

First, the celluar_pv model (with PV panel embedded in the spandrel) needs to be opened,
using the following command after entering the cfg folder in the terminal window (or
command prompt):

prj -file cellular_contam_bc.cfg &

The model has a small PV panel installed under the window.

Now, the basic file is to be opened using the same steps as before. The simplest cfg file can
be opened using the following command:

prj -file bld_basic.cfg &

The point of this process is to use the previous model as a reference to include PV panels
in the roof of the current model.
241
23.1.1 PV panel data
The PV Panel data is stored in the manager_pv file in msc folder of the cellular_various
folder. This the spm file, or the special materials file. It contains all the specifications of the
PV used in the model.

It is recommended to maintain a separate file with all the solar panel details for future
reference.

Most of this information is available in the PV Panel datasheet, stored in the doc folder. In
the Electrical Characteristics Table, the maximum current is 4.55A, the same as the figure in
the spm file.

242
 Datasheet for BP_Solar_380

So, if some other PV Panel is being used, these values need to be replaced by those
corresponding to the new PV Panel.

Another important file is the cell_office file stored in the nets folder. It is an ENF file and it
describes the electrical network. The file contains all the nodes, connections, components,
and connecting cables in the electrical network that can be seen through the interface (as
done in the previous tutorial).

Cell_Office ENF File

243
There are two pieces of information that are relevant to this tutorial. First, the properties of
the cable linking the inverter to the PV Panel in the switchboard. The six numbers under the
additional data items for the component cable_pvt are related to the inverter and
determine the performance of the inverter. These numbers can be added to a file to refer
to when making a new PV Panel.

There is another component in the file that accounts for the inverter loss, invert_loss. These
numbers represent a very bad inverter due to the very high losses. These numbers describe
the losses in the inverter itself rather than describing connections.

23.2 Adding PV panel layers to roof construction

The first step of adding the PV layers is to decide where the PV panel is to be placed. In this
case, the panel will be placed on the roof.

In the cellular_various (reference) model, go to b databases, then e constructions, a

browse/edit, then g PV_constr on the second page of the list. This window now contains
the list of materials used in the PV panel. As mentioned in the previous tutorial, there is a
specific construction that describes the PV Panel - the first protective glass layer, the EVA
layer where the solar cells are deployed, the second protective glass layer, a gap, and the
building facade. The same structure of layers must be replicated to correctly install the
panel.

244
The materials in the roofspace also need to be known before the panel can be installed. In
the basic (working) model, in the Model Management Window, click on m
browse/edit/simulate. Then go to c composition in the Building sub-section of the menu.
Click on b construction materials and c roof_space. Select use it.

If the surface names are not displayed, click on image control (option below the model
image) and click on the option i surface names to display the surface names.

Usually, the x-axis points to the East, the Y-axis to the North. This means that the s_roof
points towards the South.

245
The panel will be installed on the s_roof. As can be seen in the Composition menu, the
s_roof surface uses the material roof_1. This is the material that needs to the changed in
the database on the Basic model.

Exit the menu.

Return to the Model Management menu and go to b databases. The option e construction
shows <std>, which signifies that the construction files is stored in ESP-r default files, not
the model files. In order to make changes to the files, the files need to be copied to the
model. In order to do this, go to e constructions, and select d copy default file to model.
Select the file name and then exit a few times to return to the Database Management menu.
Now e construction should show the <mod>, indicating that the files have been copied to
the model and can now be edited.

246
Now, click on e constructions, then a browse/edit. From the list, select j legacy
constructions & models and then click on 1 add/delete/copy/invert, select copy, then e
roof_1. Change the name of the surface to roof_1_pv.

Since this surface is a copy of roof_1, new layers can be introduced here without any
changes made to the original model files. The material assignment for the roof can then
simply be changed to the copied file roof_1_pv which contains all the additions.

When adding the layers, it is important to keep in mind that there is a specific order for the
PV layers. Layer 1 is the current outermost layer and all the new layers of the PV Panel must
be added before this layer. When in doubt, click on ? help for further clarification.

247
Click on ! add or delete a layer, select insert, then click on layer 1 roofing felt since it is
the outermost layer. Select yes to change the material reference.

A gap layer can never be the outermost layer; thus, the gap layer must be inserted after the
other layers have been added since simulation software can sometimes return an error
when adding a layer that is not physically possible.

First, the glass layer will be added. Click on m glass and ceramics and select j low iron
glass, same as the one used in the cellular_various model. Change the thickness to 3 mm.

248
Second, the EVA glass layer is to be added. Again, add a new layer after the first layer. Select
m glass and ceramics, then d EVA layer. Change the thickness to 3 mm. Repeat the
process to add another glass layer after the EVA layer.

Now that all three layers have been added, the gap layer can be inserted. Since the gap
layer is between the PV Panel layers and the roof material layers, select roofing felt when
adding the gap layer.

Click on q GAPS. Select a Air layer with default properties.

249
Accept all the default R values (resistances) of 0.17 m2 K/W for all orientations. Change the
thickness to 20 mm.

250
Exit and save the construction.

23.3 Changing the roof material

Return to the Model Management Menu and go to m browse/edit/simulate. Go to c
composition, b construction materials.

Before editing the composition of the zone, update all materials in the files using # update
all zones. and select via legacy format when prompted.

This is always needed when the material database is modified, to assure ESP-r construction
files are up-to-date.

Select c roof_space and click on use it. Go to c s_roof.

Select b construction, j legacy constructions & models, and select x roof_1_pv on the
second page of the list. Now, the material of the south roof has been changed to the new
material with the added PV Panel layers.

251
Save the changes and exit.

23.4 Model simulation check

It is a good idea to run a simulation after making major changes to the model to ensure
that the model is running properly. In fact, it is also recommended to run a simulation
before modifying things to ensure that there are no flaws in the original model and be
worked on.

Return to the Browse/Edit/Simulate menu and select s simulation. For some models, the
time periods may need to be changed. Select g from: and change the dates to 1 1 (1st
January) and 31 12 (31st December).

Select q integrated simulation and select interactively. To avoid problems with the files,
related to the electrical results, do not preserve the results that are available, instead run a
new simulation each time. Select c initiate simulation and s commence simulation.
Specify the name of the result file and save the results.
252
23.5 Results
Select t result analysis. The result analysis window should open.

Ensure that the output period is the same as specified in the previous section.

Go to a graphs, a parameter plot, b temperatures, a dry bulb (db) temp temperature.

Select ! draw graph to display the graph.

Dry-bulb Temperature

If the results obtained are as expected, then it can be concluded that the model has not
been damaged in any way while making the changes. If the model is damaged in the future,
a copy of the model can be used instead. It is recommended to store the copy of the model
in a different location from the working model to ensure that any damage to the folder
does not affect the back-up file.

23.6 Electrical network definition

Close the result analysis window and return to the browse/edit/simulate menu.

As seen from the Network sub-section, no networks have been defined. Select g
electrical.

253
Select yes to proceed with the network description. From the Electrical Network definition,
it can be seen that no nodes, components or networks have been defined.

Open the cellular_various (reference) model and go to the Electrical Network Definition.

254
In the working model, click on a Network name and specify the name as PV_roof_south.
Select continue and select yes. The name can be changed as per user preference or
requirement. It is a good idea to give a network description as well.

23.6.1 Nodes
In the reference model, there are four nodes. One node should always have a fixed voltage
since it is the one connected to the grid. It balances the whole network such that if there is
an excess or lack of energy, it can draw or return the required amount to the grid.

Since the tutorial is the first attempt at defining the network, only two nodes will be created,
since it is the simplest thing to do.

Select d nodes, + add/delete/copy item and select add node. Select 1-phase(1) node.

Then select Fixed Voltage since it is the first node. Name the node Grid_connect.

Since there is only one phase, select the phase as 1.

255
ESP-r always sets 220V as the base. The simplest way to change this is to change the ENF
file rather than changing it through the interface. Before doing that, the PV Panel node also
needs to be created.

Add another node. It is a one-phase node with a variable voltage. Name the node PV and
specify the phase of the node connected to the grid as 1.

In ESP-r, it is possible to define an electrical network that is physically wrong. A PV Panel

should not be directly connected to the grid, since the PV Panel needs DC, instead of AC in
the grid. The AC from the grid needs to be converted to DC first using an inverter, then it
can be connected to the panel or the rest of the network. However, it is possible to model
this for the sake of understanding the energy flows as if it were directly connected to the
one-phase flow. It must be kept in mind when modelling a real electrical circuit that this is
not possible and will not represent a physical situation.

Now the two nodes have been created.

This tutorial will not cover connections to lights, power components or HVAC systems. The
objective of the tutorial is to calculate the amount of energy generated by the PV Panel. It
is possible to connect the components to the network, thus, supplying the energy to run
the components from the PV Panel.

23.6.2 Connecting components

Go to g Connecting components, + add/delete/copy item and select add. Select 1
Electrical conductors.

256
Select 2 one_phase_cable.

Since it is the only cable in the problem, the name can be simply cable. The cable definition
can be information regarding diameter, materials, manufacturer, etc. For this tutorial, it can
be left as is.

Next, there are six data items that need to be provided by the user.

Cable Parameters (cell_office ENF file and doc)

The six data items are stored in the Cell_office ENF file of the reference model. The data
need to be added as required. It is a good idea to maintain a separate document with all
the parameters and units so that the numbers can simply be added where necessary.

The data in the file has to be reproduced in the same order in ESP-r.
257
The cable length has been increased to 10 meters since the PV Panel is on the roof (instead
of below the window in the reference model) and seven meters may be inadequate.

Select b 1-phase in the phase type menu.

The new cable has been created.

23.6.3 Network connections

Now, the two nodes have to be connected using the connections.

Select h network connections and go to + add/delete/copy item and select add. In the
Electrical Nodes menu, select b PV and then a Grid_connect.

258
Then select a cable.

Now, there is a connection with the cable going from node 2 to node 1 on phase one.

The network definition is now complete. The only thing left to do is to change the voltage
from 240V to 120V.

259
Select >Update network. A file will be created in the model folder of the name
PV_roof_south. Save and exit the electrical network.

Go to the cfg folder in the model folder. Open the file PV_roof_south. For some systems,
the file may be stored in a different location. In the file, change the base voltage of the
nodes from 220V to 120V. Save the file.

Return to g electrical. Select the file and continue. Go to d nodes.

260
Changes made in the file should reflect in the nodes as well. Update network, save and exit.

23.6.4 Integrating the PV panel into the electrical network

Now, the PV Panel has to be deployed on a specific surface of the roof. Select c
composition and go to m integrated renewables in the Special Components sub-
section.

Now special file exists, so, select no. Then create a new file. Name the file bp_pv.spm.
Spm is the abbreviation for special material files.

Select + add/delete item, then select new component.

Select 1 crystalline PV.

261
Select 2 BP_saturn_36cell.

Leave the name of the panel as is. The data entry values are stored in the manager_pv
SPM file.

Manager_pv File

The data in the fields have to be added in the same order as they appear in the file.

The reference temperature is required since ESP-r will calculate the temperature of this
panel for each time step and based on this temperature, it will calculate the efficiency
using a standard curve.

262
It is a type of load, that's the maximum power, the PV panels usually have controllers that
can track the behaviour and ensure that the panel is operating at the maximum power point
with the optimal voltage and the optimal current. And here load versus voltage - a
resistance type of network is used - and the shading treatment is the default one.

Now, select c roof_space, c s_roof then layer 2: EVA layer. The placement of the node
should be in the middle of the EVA layer and ESP-r should suggest it automatically. The first
three nodes are placed in the glass.

The PV Panel has been created. Update the network. Save and exit.

263
23.7 Integrated simulation
Now that the network has been fully defined and the PV panel has been installed, the
integrated simulation can be run.

Return to the browse/edit/simulate menu. In the Miscellaneous menu, select ! Save model
to save the model. Since several changes have been made, it is a good idea to save the
model so as to not lose the data.

Go to the simulation. In the simulation controller, no electrical results file has been defined.
Click on m elect. results.

Name the result file as bld_basic.elr.

264
elr is the proper abbreviation for electrical results so that ESP-r can find the file easily when
required.

Select p save/dereference parameters and select save current sets. This saves the file
names, the simulation presets, the simulation time period, etc.

Select q integrated simulation and select interactive. Select c initiate simulation and
do not preserve the previous result set. Select s commence simulation. Exit the simulation
window.

23.8 Result analysis

Go to t result analysis. There are a couple of warnings here.

Go to g electrical results and remove "win" from the name of the results file. Select ok. It
should now read "File read successfully".

Let's see if a graph can be plotted of the generation and the PV panel. Select a graph, c
generation and b PV. Plot the graph. As shown below, the generation is 0, indicating that
something is probably wrong with this model.

265
This error most likely means that something is wrong with our network; the link between
the panels and the network is a likely culprit. From the Browse/edit/simulate menu, navigate
to g electrical (defined) --> e Connect HVAC/PV/Lights/etc. Here, it should be seen that
there is no defined link between the panels and the network (it should look like the image
below, but with no component as option a).

It was already defined the connection above to remedy the error. Let's define this
connection on others model now. Here, a connection between the PV panel and our
network need to be added. Select + add/delete/copy item and choose add and
then renewable source. Choose a 1 BP_saturn_36cell --> b 1-phase --> b PV. Name the
component pv_node_ccn or another arbitrary name of any choice. Now, it should be seen
that a component similar to the image above.

Specifying this connection tells the model that the energy coming from the integrated
renewable - which was previously defined with the data from the PV panel data sheet -
should come to this point in the electrical network. Now that there are two nodes—one
connection between the PV panels in the network and the PV panels under integrated
renewables, and one cable connecting the two nodes—running a simulation should display
some electrical results.

266
Now, navigate to s simulation. Change the name of the electrical results library to
"bld_basic_win.elr" and select ok. Select q integrated simulation and run interactively.
Select c Initiate simulation and, if prompted, choose not to preserve results. Select s
commence simulation and choose to save the results.

Results can now be analyzed using t results analysis. Ignore any warnings about the library
being incomplete or corrupt; functionality should not be impacted. To display the
generation of the PV panels, navigate to g electrical results --> a graph --> c Generation
--> b PV, then exit and plot the graph. This graph should show the results of the electrical
network.

As shown, this simulation produces an output of approximately 85 Watts, representing the

simplest case of running a simulation with a PV panel in an electrical network. These results
can be exported, post-processed, and further analyzed. To do so, follow the same steps as
for the graph but select b tabular report instead of a graph. Then, select > Display to
>>screen to toggle the display to a file instead. Name the file as preferred. Select ! List
output, and once again, select > Display to >> file to close the file (a critical step, as
forgetting to close the file will prevent results from being exported).

Other tutorials will cover additional features of this electrical network.

23.9 Amending the electrical network

In the second part of this tutorial, the area or number of PV panels will be modified to
observe how it affects energy production.

23.9.1 Changed the number of PV panels

From the first menu, go to browse/edit/simulate, then go to composition and integrated
renewables. This is the PV panel defined. Edit it; it is still crystalline PV 380. Many of the

267
defaults are the same ones to accept, except for the number of panels. One was used in the
first tutorial; now, use 10.

Assuming all the defaults are the same as listed here for the rest of the values: using the
roof space, the South roof, and the EVA layer. Update the file so this new information is
written in the bp_PV.spm file or any other name, as it is arbitrary.

With a new file containing these numbers, an integrated simulation can be run to see the
impact on energy production. No results will be kept, keeping the same name for the
results' library for the electrical. Invoke simulation, then exit this, return here, and review
the output.

Bear in mind that as ESP-r calculates energy flow between the thermal and electrical
domains, extracting more energy from the roof to produce electricity and convert solar
radiation to electricity reduces the energy entering the zone, potentially affecting
temperatures and loads in the zone.

Then plot the graph here focusing on node and generation for the PV panels.

The impact of this new number of panels should now be visible. As expected, there is a
tenfold change in the results, with 700 Watts as the peak for this particular setting.

23.9.2 Including the "lossy" inverter

Another thing that could eventually be done is to try to connect PV panels in a more realistic
way using an inverter that has some high changes, for example. In the second part of this
tutorial, a new node will be added to the network, which will be the inverter, and the losses
of this inverter will be described as they are here.

268
So, proceeding with the definition, yes. The file is already available. Now, a new node will
be included here. A node will be added; it is a one-phase node with a variable voltage. It
will be called "inverter."

The node itself is not going to be the inverter, but a trick will be used to describe these
losses. What will be done is the following: now that this new node is available, changes
need to be made in the text file in a minute. A new connecting component will be created.
Rather than the small loss that was used, this small resistance in the actual cable will be
addressed.

A very high resistance will be assigned, which means that lots of energy produced by the
panel will not be available to the rest of the network because it is dissipated in this
inefficient inverter. A new sort of connection will be added here. That's the electrical
conductor, one phase. Now call it losses_inv.

Again, there are six data types, and these are the data that would be used. A very high
resistance means that a lot of energy will be dissipated there: 0.1, 4 again for the resistance
on the neutral, 0.1, 0, and the length of the cable, 1. A longer cable with a smaller resistance
would probably have the same effect in the first phase. Now, there are two connecting
components.

The network will be rewired to establish new connections. A new connection will be added
between the PV and the inverter using this "loss" cable. Now, there is a connection from
the PV to the inverter, and a change is needed for the connection from the inverter to the
network. In this case, it will link the inverter to the network using the normal cable. The PV
panel—that's node 2—is connected to the inverter using this cable that has a high loss, so
the impact of this on the energy available and generated in the network will be observed.
Another connection from the inverter to the network will also be established.

269
Updating this, the file PV_roof_South is being saved. It will be opened in the
basic/cfg/PV_roof_South to change this value. It is easier to change here than through the
interface.

The simulation will be run to see the results of the integrated simulation. This will be
cancelled, and it will run for just a small period of time: from the 1st of June to the 4th of
June. This allows for clearer results in the integrated simulation, interactively.

The simulation will be initiated, and the name of the results file will be accepted. The
available results will not be kept. The name is correct for the electrical network, and the
simulation will be invoked. Continuing, the simulation's results will be saved, which is very
fast because it is just a couple of days in the simulation.

During the result analysis, it will be observed that the energy generated and the energy
transmitted are not the same due to the losses related to the inverter. For instance, a graph
of the generation in the PV panel will be plotted, showing over 700 watts generated in these
four days.

Now, see what the transmission to the grid is. These values are in the order of 500W and
not 700W. Even though 700W was produced, the actual exported value to the grid is lower
because components, cables, and other elements in the network generate losses in the
electrical network. These losses need to be taken into account to provide a more reliable
270
figure for the energy exported to the grid when using this inverter, which has a very high
loss. The literature includes many references on how these losses change depending on the
inverter's configuration and the nature of the inverter itself.

With this tutorial, the process of changing the number of panels in the PV panel network
was covered, which impacts energy production, and how to include an extra node and
connection to represent losses in the system. Now, lighting and other layers of complexity
could be represented in the model. The same procedure could be used to deploy PV panels
on other surfaces of the model to find the best solution. Data can be explored and analyzed
in relation to solar radiation (direct and diffuse), wind speed, and temperature because
these factors affect panel temperature, performance, efficiency, and more.

271
272
Explicit Plant & Systems Domain

273
24 Opening, inspecting and running a HVAC
model
This tutorial is based on information available at:
https://www.esru.strath.ac.uk//Courseware/ESP-r/hvac.htm

This tutorial describes the steps to open, inspect and run simulations using a model with
explicit HVAC plant modelling.

The plant domain solves heat and mass-energy transfer in a network of HVAC components.
While the thermal domain can provide valuable information about the performance of the
HVAC system, it does not provide facilities to evaluate the performance of each component
of the system and assess the interaction of components for the analysis of the impact of
realistic control algorithms implemented in HVAC systems. Explicit plant networks provide
such capabilities, and can be used to describe systems operating with air and/or with water.
Multiple plant networks can co-exist in a model. The plant domain does not calculate
pressures across the HVAC system, but it can be coupled to a fluid flow network for this
purpose.

24.1 Access and explore the HVAC model

Start ESP-r. Click on d open existing, then exemplar, b technical features, o with detailed
HVAC representation. Select the file name and then click on proceed. Copy the model to
the home folder.

274
The new model opens automatically in a new ESP-r window. To open the model at a later
time, follow the steps below.

cd ~

cd cellular-various

cd cfg

prj -file cellular-hvac.cfg &

24.2 Schematic representation

A schematic representation of the system is available in the images file in the model
folder.

275
 HVAC Systems Model Diagram

The image shows an air handling unit with ducts, mixing boxes, fans, heating and cooling
coils, humidification, and a set of sensor reading temperature and humidity levels in the air
return systems and connected to actuators in the delivery system.

24.3 Components
Select m browse/edit/simulate, e plant & systems under the networks subheading,
then b explicit.

Select the name of the file and select yes. Press yes to modify the file. Press yes to see the
network summary. An extensive summary is provided in the text feedback window, partially
shown in the image below.

276
 Partial Plant Summary

The Network definition: edit menu shows options to define HVAC models. Select d
components. The list of components used in the model is shown, matching the schematic
representation.

277
Select l fan1, then name and component data, then select the component name. Select
ok for the volume flow rate.

Fan Volume Flow Rate

Data regarding thermal losses and thermal inertia of this component is shown in the menu.

Exit the menu. Select l fan1 again, but now select optional flow data.

The component indicates that the working fluid for this plant network is air. The list of
parameters is tailored to this component. The parameters are related to the performance
of the fan as a function of the pressure difference. Exit the menu.

Select j re-heat_coil. Accept the heating capacity of the coil.

The menu shows the parameters related to the component thermal losses and thermal
inertia.

278
Note that parameters regarding the energy delivered by the coil are not set here. They are
described in the control loops for the plant model, as shown later in this document. Exit the
menu.

Note that some components are labelled as supply and return. These components are
important to link the plant network to the thermal zones described in the thermal domain,
as described later in the section about controls in this document.

As in other ESP-r domains, the information shown on prj interface is stored in text files. For
the plant model, the file is located in the nets folder and has extension .pnf. The image
below shows part of the pnf file, with information about the components used in the model.

24.4 Connections
Return to the Network definition: edit menu. Select e Connections. Connections describe
how the working fluid flows through the components described in the previous section.

279
Editing these connections by selecting them is cumbersome, as the software (prj) does not
show the currently selected options once the user starts editing the connection. The
connections can be more clearly seen in the .pnf file, as shown below.

Component Connections

The file indicates components connected directly to another component (those with
connection type 3). It also shows components connected through the air nodes of thermal

280
zones (those with connection type 4). The sixth line from bottom to top is reproduced
below. This line shows that extract duct 1 7 is connected to supply duct 7.

ex_duct_1_7 1 4 supply_duct7 1 1.000 1.00 # 15

Once components and connections are defined, controls need to be set for the plant
network.

24.5 Zones Controls

Return to the browse/edit/simulate menu and select i zones.

The image above shows that three control loops are used in this model, one for each
thermal zone. The corridor uses the first loop, with no heat injection/extraction.

Investigating control settings in the software (prj) can sometimes be cumbersome, as the
current information used in a control loop may not be shown in the interface. In some cases,
it is easier to understand the controls using the .ctl file. Open the file cellular_offices_bc+p
located in the ctl folder of the model.

281
 cellular_offices_bc+p - Control File (Zones)

The image below above shows a sample of this file. The lines related to the zone loops
show that this loop only links the zone conditions to the respective plant components for
the air return. The actual control data (setpoints, capacities, schedules) is defined in the
loops for the plant network, described in the same .ctl file.

24.6 Plant Control

Return to the browse/edit/simulate menu and select j plant & systems.

282
There are six control loops for this plant network covering the key components of the plant
network - heating, cooling, preheating, two fans, and humidification. Details of each control
can be seen in the .ctl file (same file as earlier), as shown below.

cellular_offices_bc+p - Control File (Plant)

24.7 Running a simulation

Return to the browse/edit/simulate menu and select s simulation.

283
The Simulation controller menu shows the names of the result file (for the thermal domain)
and for the the plant domain (extension plr). The controller also defines that the time-step
for the zone (for the thermal domain) is 60 minutes, while the time-step for the plant
network is 1 minute. The plant domain often requires smaller time steps, as HVAC
components can inject/extract significant amounts of energy/mass and the working fluid
may have a small thermal capacity.

Select q integrated simulation and then select automated.

The next tutorial describes the result analysis for plant networks.

284
25 Analysing the results of a HVAC model
This tutorial is based on information available
at: https://www.esru.strath.ac.uk//Courseware/ESP-r/hvac.htm

Run the results analysis and read in cellular_hvac_winter.res.

25.1 Graphs
Select parameter plot

Select weather

Select a dry bulb temperature

The graph below shows the outdoor temperature.

Select / clear selection

Select building zones > a manager_a > - exit menu (to restrict plots only to this one
zone)

Select temperature > a dry bulb (db) temp.

285
The graph shows the evolution of temperature in the zone over time. The temperature
oscillates around the setpoint reproducing the behavior of the HVAC system.

Select / clear selection

Select i zone RH

The image shows an oscillation in the relative humidity around the setpoint of 50%.

286
Once the conditions in the thermal zone are understood, results for the plant network can
be analysed.

Select plant results and read the plant results file cellular_hvac_winter.plr

Select output -> psychrometric chart -> generate chart

ESP-r will display a psychrometric chart for plotting the state of plant components on this.
The x-axis shows the temperature of the air in the HVAC plant and the y-axis shows the
amount of moisture in the air.

Choose select components -> all items. Then choose to display one timestep - look at
timestep 660 (i.e. 11 hours in the graphs above).

287
The chart now shows what is happening inside the HVAC plant. The point on the lower
left corner represents the outdoor air (cold and dry), the point around 16°C and 55% RH
shows the conditions at the mixing box, the point at 14°C and 70% shows the results after
humidification, the point at 25°C shows the conditions after re-heating. The air is then
supplied to the zone, where energy is extracted from the air by the cold surfaces of the
zone, bringing the air to 20°C and 50% RH.

25.2 Time series plots

Return to the Psychrometric menu and select output -> time series plot -> 2nd phase
flow -> humidifier and draw the graph. This shows how the flow of water into the
humidifier is controlled to obtain the 70% RH setpoint. Clear this graph and select output
-> time series plot -> relative humidity% -> ex_duct_1_7 and plot the graph. Component
ex_duct_1_7 draws air from zone manager_a and so this shows the zone humidity. How
successful is the HVAC system at holding RH to 70%? Also look at the space temperature:
select output -> time series plot -> temperature ex_duct_1_7. This shows the temperature
in office manager_a. How successful is the HVAC system at holding temperature to the set
point of 19°C? Select output -> summary statistics -> relative humidity% -> ex_duct_1_7
and for additional output -> re-heat_coil -> heating output again noting the values. This
shows the amount of heat needed to maintain the room at the desired temperature.

25.3 Summer simulation - plant in cooling mode

Return to the project manager Browse/Edit/Simulate menu and select
browse/edit/simulate -> simulation -> simulation presets -> summer. Run an integrated
simulation. Analyse the results from /tmp/cellular_hvac_summer.res and look at plant
results /tmp/cellular_hvac_summer.plr. Select output -> time series plot -> temperature -
> ex_duct_1_7 and temperature -> supply_duct7. Can you explain why the supply duct
temperature profile is as shown (hint: remember that we are cooling the space and think
288
about the level of heat gains during the day!). How successful is the HVAC system at
maintaining temperatures at the set point of 23°C?

Select output -> psychrometric chart -> generate chart and select components -> all
items. Now display the HVAC system state at timestep 780. There are two processes
occurring - mixing and cooling/dehumidification. Can you identify them from the chart?

Finally clear all previous selections and select output -> summary statistics -> additional
output -> cooling coil and look at the load on the cooling coil.

289
26 Editing a HVAC model
This tutorial is based on material available at
https://www.esru.strath.ac.uk//Courseware/ESP-r/hvac.htm

26.1 Editing HVAC control settings for the plant system

Return to the Browse/Edit/Simulate menu and select Controls - plant and systems. Notice
that there are several control loops defined. Each loop controls an individual HVAC
component. Select loop 6, which controls the humidifier and edit the period data. Choose
period 2 PID flow control - select controller type l, which senses relative humidity (RH) and
actuates the flow of water to the humidifier, and control law c (P,PI,PID). Proportional
control will be used in this case.

Enter data as follows:

• Set start time to 7.0.

• Set PID mode to 1 - proportional only.
• Set number of misc data items to 7.
• Change the control values from 0. 0. 50.0 10. to 0.001 0.0 70.0 10.0
• The integral action flag and derivative action flags should be set to 0.
• Save the new control data and run the default winter simulation.

Run the results analysis and read in /tmp/cellular_hvac_winter.res. Select plant results and
read in the plant results file /tmp/cellular_hvac_winter.plr.

Select output -> psychrometric chart -> generate chart

ESP-r displays a psychrometric chart for plotting the state of plant components on this. The
x-axis shows the temperature of the air in the HVAC plant and the y-axis shows the amount
of moisture in the air.

Select components -> all items.

Then choose to display one timestep - look at timestep 660.

The chart now shows what is happening inside the HVAC plant.

Can you identify mixing; humidification and re-heating processes? Looking at the plant
network schematic diagram - can you identify which components perform these processes?
Finally look at the humidification process - can you describe what is happening to
temperature and moisture content?

Return to the Psychrometric menu

Select output -> time series plot -> 2nd phase flow -> humidifier
290
Select draw graph

This shows how the flow of water into the humidifier is controlled to obtain the 70% RH
setpoint.

Clear this graph

Select output -> time series plot -> relative humidity% -> ex_duct_1_7

Select draw graph

Component ex_duct_1_7 draws air from zone manager_a and so this shows the zone
humidity. How successful is the HVAC system at holding RH to 70%?

Also look at the space temperature:

Select output -> time series plot -> temperature ex_duct_1_7

This shows the temperature in office manager_a. How successful is the HVAC system at
holding temperature to the set point of 19°C?

Select output -> summary statistics -> relative humidity% -> ex_duct_1_7

Selects and for additional output -> re-heat_coil -> heating output again noting the
values. This shows the amount of heat needed to maintain the room at the desired
temperature.

26.2 Further editing HVAC control settings for the plant system
Repeat the process of editing the humidifier control loop 6. Keep all the control settings
the same as before, except that when prompted set the control values to 0.0 0.0 70.0 10.0.
This effectively closes down the humidifier by setting the maximum allowable water flow
rate to 0 kg/s. Save the new control settings and re-run the simulation. Select the results
analysis and read in the new results file e.g. /tmp/cellular_hvac_winter.res.

Select plant results and read in the new plant results file e.g. /tmp/cellular_hvac_winter.plr.
Select output -> psychrometric chart -> generate chart and plot the state of all of the plant
components as before for timestep 660. Can you see a difference between this and the last
simulation? Which process (humidification, re-heat or mixing) is now missing? Clear this
graph and return to the Psychrometric menu and select output -> time series plot ->
relative humidity% -> ex_duct_1_7 and plot the graph. What is the difference between this
and the humidity plot from the previous example? Select output -> summary statistics ->
additional output -> re-heat_coil -> heating output and then generate the report. What
has happened to the amount of heating energy supplied by the heating coil? Also look at
the space temperature. Select output -> time series plot -> temperature ex_duct_1_7. How
does this compare to the temperature plot from the previous simulation?
291
What conclusions can you draw from changing the humidifier control settings, looking at
the psychrometric plots and the time-series plots of RH and temperature?

26.3 Alter the amount of re-circulation in the plant system and

examine the impact on the cooling load
Return to the Project Manager and select plant and systems under the networks section.
Using the menu interface select connections. Select b (the second connection) and choose
to edit the connection.

Select the mixing box as the receiving component then select option c - from another
component then select fan2 as the sending component. Set the mass diversion ratio to 0.5.
This has the effect of reducing the amount of cool extract air recirculated and mixed with
the incoming supply air from 80% to 50%.

Can you identify this recirculation on the plant system schematic?

Also edit connection t (the last connection) to change the mass diversion ratio from 0.2 to
0.5. Again choose to edit the connection. In this case the receiving component is
supply_duct1, the connection type is e - from ambient air and the sending component is
fan2. Set the mass diversion ratio to 0.5. This increases the amount of air rejected to outside
from 20% to 50%.

Update the plant configuration file and then return to the main menu and re-run the
simulation, remembering to use the summer simulation pre-sets as before. Analyse the
results from /tmp/cellular_hvac_summer.res and look at plant results
/tmp/cellular_hvac_summer.plr. (If you have changed the results file names for these new
simulations use these new names instead.)

Look at the resulting room temperature by selecting output -> time series plot ->
temperature -> ex_duct_1_7. Is there much difference from the previous simulation? Now
look at the load on the cooling coil. Select output -> summary statistics -> additional
output -> cooling coil -> cooling output and then generate the report. What effect has
reducing the recirculation had?

Select output -> psychrometric chart -> generate chart

after changing the period data for the humidification control

292
Select Timestep change, all components- humidification, re-heat or mixing

Select output -> summary statistics -> relative humidity% -> ex_duct_1_7 and for
additional output -> re-heat_coil -> heating output

Select 5. 0.0 0.0 70.0 10.0 - output -> psychrometric chart -> generate chart -
humidification, re-heat or mixing

293
Select output -> summary statistics -> additional output -> re-heat_coil -> heating
output

Select output -> psychrometric chart -> generate chart and select components -> all
items.

294
Select output -> summary statistics -> additional output -> cooling coil

Select output -> summary statistics -> additional output -> cooling coil -> cooling
output

295
296
Idealised Plant & Systems Domain

297
27 Opening, inspecting and running a model
with idealised HVAC
In the previous section, ESP-r explicit plant module was used to describe systems
comprising several components, interacting in a network to extract/remove thermal energy,
moisture, and/or air from the building. This is the explicit approach to model plant systems
in ESP-r.

There is an alternative approach, where only a few parameters are required to model a
single component heating and/or cooling system: the idealized approach. This is not a
streamlined interface for explicit plant networks, but rather a different way to model HVAC,
with its own assumptions and solver.

Idealised HVAC was primarily developed to support modelling in line with the methodology
in the HOT3000 software, developed by NRcan. Users should exercise caution when
adopting idealised HVAC modelling in other contexts. More information about this
methodology can be found in ESP-r source code, at src\cetc\hvacsim.F

27.1 Opening an exemplar with idealised HVAC

ESP-r has several exemplars that are not listed in the Project Manager "open existing
model" menu option. This is the case with models using idealised control. Copy this models
using Linux terminal:

cd ~

cp -r /opt/esp-r/validation/selftest/idealized_hvac/ ./idealized_hvac

Still using Linux termina, navigate to the cfg folder of this model, and list the files available.

cd idealized_hvac/cfg

ls

There are several cfg files in this folder, representing versions of this model with different
HVAC systems.

298
On the terminal, open the model with an air source heat pump for cooling:

prj -file ashp_cool_auto_conv.cfg

Select m browse/edit/simulate

27.2 Controls
Before exploring the heat pump setting, it is important to check the control applied to the
system.

Select i zones (2 loop)

Accept the control file name

There are two loops in this file.

299
In order to identify the control related to the heat pump, it is necessary to explore them
one by one.

Select the first loop f 1 bld_loop_01 > d period data

The control is reproduced in the image below. It is a free float control covering the first
hours of the day, therefore it is not directly relevant for the HVAC system,

Select - exit and return to the Controls Menu

Select the second control loop g 2 bld_loop_02 > d period data

There are 3 periods, select period b, which operates during daytime (from 8:00 to 20:00
hours).

300
This control defines the setpoints to be used by the air source heat pump defined in the
idealised plant mode.

The value set on item e Maximum cooling capacity (W) is 2000 W, but this value is not used
in the simulation, as the capacity of the heat pump in the idealised model overrides this
setting.

Exit these menus and return to the the browse/edit/simulate menu.

301
27.3 HVAC settings
Select e plant & system to explore the HVAC settings.

The Plant model menu becomes available. It shows the idealised HVAC as defined. Select
a idealised (defined)

The dialog area shows the name of the file with HVAC settings.

Select ok

302
The HVAC Summary menu shows one system defined. Note that this menu does not follow
the convention adopted in other ESP-r menus (each line starting with a letter to facilitate
selection using the keyboard.

Select System 1:ASHP

The menu shows a summary of information for the heat pump. This menu does not allow
editing these settings. It is noticeable that the capacity of the heat pump is 020E+04 (i.e.
2000W). This is substantially lower than the 6000 W set in the ideal control.

Do not select the option edit to investigate the model, as the Project Manager does not
show the information used in the model. This feature is recurrent in ESP-r functionality that
is restricted to advanced users, such as the idealised HVAC system. To investigate model
features for idealised HVAC, use the .hvac file (see the next section).

Select - exit menu twice to leave the idealised control.

Press yes to save the file, and accept the prompt to update the connection file (.cnn) and
the plant file (.hvac).

303
⚠ After saving the file, ESP-r remains in the HVAC Summary. It is necessary to select -exit
menu and select no when prompted about saving the file to leave this menu and return
to the Plant model menu.

27.4 Exploring the .hvac text file

Go the the file manager of your computer and open this file in a text
editor: ashp_cool_auto_conv.hvac, located on the folder hvac of the idealized_hvac
model.

The file looks like the image below. The meaning of some of these fields can be found in
https://www.esru.strath.ac.uk/Documents/ESP-r/modeling_hvac_in_HOT3000.pdf

In the file below, it is noticeable the values for the capacity and COP on line 6.

Close the file, and return to ESP-r Project Manager.

304
28 Exploring results of a model with idealised
HVAC
28.1 Running a simulation
On the browse/edit/simulate menu, select s simulation

⚠ Note that the item d zone timestep/h is set to 1. This is requried when using idealised
HVAC.

Before proceeding, select f result save level

Enter 4 and press ok. This will reduce the amount of information saved by the Integrated
Simulator in the result file and avoid problems with this exemplar.

Select q integrated simulation, followed by automated.

28.2 Results

305
On the Project manager, select t results analisys

The Results Analyser module starts in a new window. Accept the name of the result file.

Select graphs > a parameter plot

On the Parameter plot menu, select 4 building zones

Select only zone b main_second , as these is the zone affected by the heat pump. Select -
exit the menu. This will facilitate data analysis.

Select b temperatures > a dry bulb (db) temp. > -exit menu

Select ! draw graph

The graph below shows that temperature often exceed the cooling setpoint (25°C),
demonstrating that the heat pump does not have adequate capacity for this building.

306
Select / clear selections

Select h heat/cool/humidify > i Aggregated cooling load

In a simulation with ideal control and no idealised HVAC, the cooling load would show a
flat line at maximum capacity in cases where the cooling system is undersized (like the
present one). However, The graph below does not show this behaviour, as the idealised
model calculates for each timestep the capacity of the heat pump as a function of several
parameters.

307
29 Implementing an idealised HVAC system in a
model
⚠ Idealised HVAC was primarily developed to support modelling in line with the
methodology used in the HOT3000 software, developed by NRcan. Users should exercise
caution when adopting idealised HVAC modelling in other contexts. More information
about this methodology can be found in ESP-r source code, at src\cetc\hvacsim.F

This tutorial implements an air-source heat pump to deliver heating to a thermal zone.

29.1 A model with no idealised HVAC

29.1.1 Exploring the model
Open the exemplar a simple > a zone with convective heating and basic control

Select m browse/edit/simulate

Before implementing the idealised HVAC system, let's explore the current control and
system capacity used in the model. It is also useful to run a simulation and analyse results
before implementing the idealised system, in order to have a baseline to evaluate the
impact of the changes implemented in the model.

Select i zones (1 loop)

Press ok to open the control file.

308
Select the loop f, as this model only have heating on weekdays.

In order to access heating capacity and setpoints, select d period data.

Select option c to explore the control used from 9:00 until 18:00.

309
The Zone control period data menu shows a model with no cooling system, and heating
with setpoint of 20 °C and 3000 W of capacity. Take note of the capacity, so the heat pump
implemented in the idealised HVAC system matches it and facilitates comparison.

Select - exit menu (press yes or ok whenever prompted), and run an automated
simulation.

29.1.2 Results
Open the result file, and on the Results Analyser, select a graph > a parameter plot > b
temperatures > a dry bulb (db) temp.

310
The graph below shows that the heating system meets the capacity in all 5 week days,
keeping the temperature at 20°C.

Select / clear selections

Select h heat/cool/humidify > Sensible heating load

Select ! draw graph

The graph shows that the system reached maximum capacity when it is activated on the
first day of simulation, in order to meet the demand from the thermal zone.

311
Select - exit menu twice to return to the Module options menu.

Select d enquire about > f energy delivered

Text feedback window shows the energy delivered to the model: 84.05 kWh. These graphs
and values provide a baseline for comparison once the idealised system is implemented.

Exit all menus on the Results Analyser and return to the Project Manager.

29.2 Idealised HVAC systems

29.2.1 Defining the heating capacity
The idealised system corrects, amongst other things, the heating capacity of the heat
pump function of outdoor temperature. The graph below represents this correlation a
typical heat pump with nominal capacity of 3000 W. The outdoor temperature related to
the nominal capacity is assumed to be 8°C. Using a correlation, this capacity is adjusted for
other outdoor temperature values (as illustrated in the image below).

312
The idealised system also corrects other properties of the heat pump which are not
explored in this tutorial, such as COP and increase in consumption due to part-load
operation (as illustrated in the graphs below).

29.2.2 Implement idealised HVAC

On the Browse/edit/simulate menu, note that no plat & systems network has been
defined (Networks (0 defined)).

Select e plant & systems

Select a idealised
313
Select ok to the suggested file name and location.

As the file does not exist yet, select make a new file

Enter the altitude of the site (for atmospheric pressure correction. Press ok.

The HVAC System Type menu becomes available. Select c Air-Source heat Pump.

Select - exit menu.

Select heating.

Select none for backup heating system.

314
The relation between outdoor temperature and het pump capacity depends on the
quality of the heat pump. ESP-r has curves for 3 representative values, implemented back
in early 2000s. For this tutorial, select ASHP typical.

Press ok to accept the suggested value, and also to accept the suggested number of
zones served by the heat pump.

Select a reception and - exit menu.

Enter 1 to indicate that all heating capacity of the heat pump should be delivered to the
reception zone.

Enter 3000 afor the capacity of the heat pump, in such a way that results from the
idealised HVAC model can be compared with the ideal loads model already available in
the exemplar. Press ok.

For the purpose of this tutorial, enter a COP equal to 2 and press ok.

Enter -1 for the flow rate in the next two dialog boxes, as this forces the idealised HVAC
algorithm to set a suitable flow rate automatically.

315
Select no fan.

This dialog is related to the temperature control for the cutoff temeprature. Enter 1 and
press ok

This is the cutoff temperature for the heat pump. Enter -1 and press ok.

The setup is completed. On the HVAC Summary menu, select s save hvac file.

⚠ do not press s on the keyboard, as it will activate the System 1 option.

Press ok

On the HVAC Summary menu, select -exit menu.

Select no, as the file was already saved.

316
The Plant model menu now shows the idealised option as defined.

Select - exit menu.

Select s simulation on the Browse/edit/simulate menu

Select h zone results and change the name of the result file to be generated during the
simulation, as indicated below:

Select q integrated simulation followed by automated.

Once the simulation is concluded, select t results analysis.

29.2.3 Results
On the Results Analyser, press ok to open the results file.

Plot a graph of dry bulb temperature in the zone, as in the image below. The graph shows
significant differences when compared to the case with no idealised HVAC. In the first
and second days, the temperature inside the reception does not reach the setpoint of
20°C.

317
Plot a graph with the heating load, as in the image below.

In order to facilitate the comparison with the case with no idealised HVAC, change the y-
axis scale. Select = axis scale.

Enter the values as in the image below.

Select default.

318
The graph now has the same scale used in the plot with no idealised HVAC. It is noticible
that the load is smaller in the first tow day when compared to the case with no idealised
HVAC. This is related to the reduction in the heat pump capacity due to lower outdoor
temperatures, captured by the idealised model but ignored when only the ideal load control
is used in the simulation.

Use the enquire about function to obtain the heating energy deliver to the zone (see
image below). The value is significantly lower than the one for the simulation with no
idealised HVAC, showing the importance of modeling heat pump performance in energy
modelling.

319
320
Moisture Domain

321
30 Exploring a model with moisture transfer
30.1 Open an exemplar with moisture transfer
Start prj and select open existing.

Select Exemplar, followed by i construction-related issues > f construction moisture

flow.

This will copy the exemplar folder adapt.

The image below shows the zones of this model. Note the Enhanced fabric highlighted
in the Features area on the upper right corner.

Select m browse/edit/simulate > c composition > k adaptative gridding & moisture

This will show a menu for the selection of the zone where moisture transfer will take
place. Settings must be done zone by zone.

Select the zone number 5: e liv_room

322
The Project manager shows the name of the file holding moisture transfer settings. Press
ok.

Moisture transfer may be combined with adaptive gridding. This exemplar does not this
feature. Select cancel

This option returns to the Building composition menu. This occur because moisture
transfer settings are not supported by menus in ESP-r. Users must manually set a text file
holding the necessary data, as described in the section below.

30.2 Moisture file setting

30.2.1 Header
The header of the moisture transfer settings file indicates the equations to be used in the
calculation of material properties:
Files with the first line equal to # moisture nodes/layer or *Moisture 1.0 will use
equations as in Nakhi, A.E. "Adaptive construction modelling within whole building
dynamic simulation." University of Strathclyde, Glasgow, UK (1995).
Files starting with first line equal to *Moisture 2.0 will use equations as in Otto, F. "The
Influence of Sorption Processes on Indoor Air Humidity" University of Kassel, Germany
(1995).

The file contains the following four sections:

• Moisture nodes/layer
• Vapour permeability data for each layer

323
 • Sorption isotherm data for each layer
• Thermal vapour diffusion coefficient for each layer

30.2.2 Moisture nodes/layer

The section "# moisture nodes/layer" comprises:

• one line per surface in the zone

• n values per line, where n is the number of layers in the construction used in the
surface
• each value indicates the number of nodes for moisture transfer calculation per
layer of construction. it must be a multiple of 3 (as 3 is the number of nodes per
layer used in the thermal domain).

The image below shows this section for the liv_room.mst file.

30.2.3 Vapour permeability data for each layer

The section "# Vapour permeability data for each layer" comprises subsections for each
surface in the zone identified as:
# indx | associated data for surface <surface number>
Each subsection comprises:

• one line per layer

• 4 values per line, where:
• the first is an index indicating the equation to be used in the calculation. Only one
equation for each file type (version 1.0 or 2.0) are implemented in ESP-r, so this
value does not affect the calculation. The file versions should have b
• three coeficients (VPRMa, VPRMb, VPRMc) obtained by curve fitting vapour
permeability data as a function of the relative humidity.

These three coefficients are described in Eq 5.13 Nakhi's thesis, based on results from IEA
Annex 14:
permeability = 1.89923e-10*(VPRMa+VPRMb*EXP(VPRMc*RH))
or in Otto's thesis:

324
 permeability = exp(VPRMa+VPRMb*RH**2+VPRMc*RH**4)
The image below shows part of this section for the liv_room.mst file.

30.2.4 Sorption isotherm data for each layer

The section "# Sorption isotherm data for each layer" follows a similar structure:
# indx | associated data for surface <surface number>

• one line per layer,

• 4 values per line, where the first is an index of the equation (also not affecting the
calculation)

The three coefficients (Uh, CFF, EXPT) are described in Nakhi's thesis:
Moisture content = Uh*(1.0-ALOG(RH)/CFF)**(-1.0/EXPT)
or in Otto's thesis:
Moisture content = 1000.*(exp(Uh*RH+CFF*RH**2+EXPT*RH**3)-1.)
The image below shows part of this section for the liv_room.mst file.

30.2.5 Thermal vapour diffusion coefficient for each layer

325
The section "# Thermal vapour diffusion coefficient for each layer" follows a similar
structure with subsections per surface, and indexes for equations and in this case one
single coefficient for each layer. Nahki states that the thermal vapour diffusion is the
diffusion caused solely by the temperature gradient and through porous materials. This is
a moisture flow drive rarely used in other moisture transfer models and Nahki indicates
the lack of data regarding this coefficient. All examplars listed above set this coefficient to
zero for all layers.
The image below shows part of this section for the liv_room.mst file.

30.3 Run simulation

In order to run this exemplar, adjust the field d zone timestep/h to 1.

The result file name on i moist resuts should be set to ../tmp/moist.mrs

326
Select integrated simulation

Select interactive

The Integrated Simulator module starts in a new window.

Press ok for the suggested cfg file name.

Select c initiate simulation

Press ok for the suggested result file names (for buildings, mass flow network, and
moisture flow).

Select s commence simulation

Select continue

Once the simulation is concluded, select Yes to save results. Select -exit menu > - quit
module.
327
This closes the Integrated Simulator and returns to the project Manager.

328
31 Exploring results with moisture transfer
31.1 Results
On the Project manager, select t result analysis

This will open the Results Analyser module. Press ok to accept the result file name
suggested by ESP-r.

In the Module options, select i Indoor environment.

This menu has various analysis related to topics not necessarily related, such as thermal
comfort, mould growth risk and lighting.

Select b mycotoxin to activate the mould growth tool.

329
The Mould analysis module opens in a new window.

Select c statistics >>OFF

This will enable statistics, as in the image below.

330
Select a mould species

This file contains the temperature and relative humidity conditions for germination of
different mould species. This file is located in the ESP-r installation folder: \opt\esp-
r\databases\mould.db1

Once the file is loaded, 6 mould types become available for selection:

Select a Aspergillus Repens followed by - Exit

On the results menu, select 3 Re-draw Chart. The germination curve is shown in the
graphic window.

331
Now that mould growth conditions are loaded, Select 1 Plot points on chart to loaded
moisture content at the walls of the model calculated during the simulation.

Select Result file

Enter the name of the results file, as in the image below.

Select plot data

The text feedback area shows that information for the zone model 5 is loaded, and 12
surfaces are available. Select the number of the surface for plotting. In this example, enter
1.

332
Results of moisture and temperature for the inner face are plotted, as in the image
below.

The text feedback area shows statistics for these surface, where no point is above the
germination line.

On the menu, select 1 Plot points on chart one more time.

Select surface index 3. Points for this surface are plotted in the graph, combined with the
previous plot for surface 1, as in the image below.

333
334
CFD domain

335
32 Exploring a model with CFD
This tutorial explores a model with a CFD domain ESP-r.

32.1 Opening a model

Opening an ESP-r model using the graphic interface start ESP-r.

Select d open existing > exemplar . Go to k fluid movement, then choose b ...with
thermally coupled CFD. Copy the model files to the home folder.

A new window should open with the new model.

336
32.1.1 Opening an ESP-r model via terminal
Open a terminal by pressing ctrl+t keys simultaneously (only for Linus OS).

Move to the home folder typing:

cd ~

Move to the folder simple and cfg.

cd CFD_room

cd cfg

Open the model in esp-r by invoking the application prj using the file parameter to point
to the .cfg of interest.

prj -file CFD_room1.cfg &

Add the symbol & at the end of any command to start the process in the background and
keep the terminal usable (otherwise, the terminal will be locked until ESP-r is closed).

To create a backup of the model files, copy the entire folder and paste it. Any
modifications made to the model, whether accidental or purposeful, will not affect the
backup files.

32.2 Exploring the CFD model

Go to the model's m browse/edit/simulate section. The model currently has one zone,
along with controls and networks. This section will discuss how to link a CFD domain to
the model.

To run a CFD simulation, you need at least one thermal zone defined within the
model. Ensure the thermal zone includes all relevant geometry and construction files. (For
detailed guidance, refer to the thermal zone tutorial.)

337
To open the CFD domain definition and setup go to c composition and then to j
computational fluid dynamic and select the zone (room). open the existence .dfd file under
/zones/room1.dfd

To open the CFD domain definition and setup: Go to the c composition section. Navigate
to the j computational Fluid Dynamics (CFD) tab. Select the desired zone (e.g., room).
Open the existing .dfd file located in the corresponding zone folder (e.g.,
/zones/room1.dfd).

338
A new window with the domain will open

Zone CFD definition menu

339
Turn CFD coupling to>> ON

32.3 Domain gridding

Check the b geometry and gridding. the model discretize the domain into 12 region on
the x axes 9 region on the y axes and 10 region on the z axes making 1080 cells.

From this menu you can edit the gridding to either increase or decrease the mesh.

32.4 Solution variable

In the CFD definition menu, go to c Solver Parameters. Here you can choose whether
you want the simulation to be:

Isothermal: Temperature is not solved, only conservation of mass flow is considered.

Non-isothermal: Temperature is included and solved for, along with other variables.
To include temperature in the simulation, select the Temperature option and change it to
Solved.

340
Go to # edit solution parameters, From this menu you can edit the relaxation factors, select
the Turbulence Model, enable the Buoyancy calculation, set the Maximum Iteration Count,
and select the Monitored Cell Coordinates.

32.5 Boundary conditions

In the CFD definition menu, go to d Boundary conditions. The Boundary Conditions menu
allows you to add or remove boundaries from the domain. In this example, an inlet and
outlet were defined to simulate a displacement ventilation scenario.

341
When selecting a boundary, you can view the cells defining that boundary, along with their
associated properties.

Boundary condition a) an opening type velocity b) a wall type temperature boundary

If you choose to edit a boundary's type, you can select from the following options:

342
If you choose to edit the location, select c cells. A menu will pop up asking you to select
the boundary face, which must be one of the six faces of the domain. You will then need to
enter the start and end cell numbers along each of the three axes.

Select boundary face and define the cells

Save any changes you made to the file before exiting the CFD menu. When prompted to
include the domain in the calculation, answer "Yes." This will link the domain file to the
model's configuration file, allowing the CFD simulation to start when you initiate a
simulation.

This concludes this tutorial. The next tutorial will go over the simulation and result
analysis.

343
33 Exploring CFD results
33.1 Simulating a model with CFD domain
This tutorial describes the steps needed to run a simulation with a CFD domain being
included. For this purpose the model opened and described in the previous tutorial is used.

From the last step in the previous tutorial the domain file .dfd is being included for CFD
calculation.

From the Browse/edit/simulate menu select s simulation

In the simulation controller menu select n CFD results

344
Add the library name

Define the start simulation date

Determine the appropriate end time.

In simulations using multiple time steps, for a computationally expensive simulation, these
steps should be chosen carefully. add the start and end time it is a decimal number of an
hour example 11.00 is beginning of 11:00 and 11.99 is the end of the hour in case of 1 time-
step per hour CFD will be conducted at one time-step.

345
From simulation controller menu select q integrate simulation

start the simulation in either interactive or automated mode.

Simulation progress can be displayed immediately after CFD solver finished if required for
that select yes.

33.1.1 Simulation
After the simulation starts, a window displaying the CFD iteration with the residuals graph
appears. Once the simulation converges, it stops and displays a message indicating the
number of iterations required for convergence.

346
 CFD solver presenting the residuals graph and the convergence message

Save the results for post-processing.

33.2 Results
After the solver finishes, there is an option to view a 3D visualization of the air
temperature distribution in the domain for each time step. This option is only available if
"yes" is selected for the "Display CFD prediction as the simulation progresses" question
mentioned in the simulation setup earlier.

347
 Instant visualisation of the results

348
 View of a slice within the domain

To process the results similar to any BPS model, go to Browse/edit menu select t results
analysis add the results file name.

349
Select h flow results (CFD) add the library name and path when asked for to load the
CFD results.

From the Flow visualization menu select b Image format to change the output visualization
format.

Check the results with Paraview. Paraview is an open source software it can be downloaded
from the following link www.paraview.org/download follow the instruction on the website
based on the operating system.

350
When Paraview is selected for image format select >create image few files are
automatically created in the model cfg folder. See image below all files with extension .vtk
are the Paraview files.

Start Paraview and select to file>open go to directory and select the .vtk file

351
Once the model is loaded, it is possible to add visualisation and targeted type of results.

The menu ribbon below allows the selection of a glyph or threshold representation.

Once a representation is selected, the user can adjust the setting in the properties menu
adjust the scale and select velocity or temperature results. Figure below show the case of
Glyph properties.

352
Apply any changes to update the results image. on the Pipeline Browser you can view or
hide any representation by selecting the eye.

353
To adjust the legend refer to the ribbon presented in the figure below.

Examples of the outputs

Glyph results

354
Slice from the threshold view

355
356
Lighting Domain

357
34 Lighting domain
This tutorial is based on material available at:

https://www.esru.strath.ac.uk//Courseware/ESP-r/lighting_control.htm

Radiance must be installed prior to this tutorial.

1. Access a simple exemplar and explore the model.

Return to your home folder and start up ESP-r. From the top level menu, choose open
existing and then exemplar options and select the base case cellular model from the
technical features category. Copy the model into your home directory.

Explore the basic features of the model by selecting browse/edit/simulate, then

composition. View the geometry, constructions and operations files for the model.

2. Define a change in lighting loads between the two offices.

Return to the Project manager->browse/edit/simulate->composition menu, and select the

operational details option. At present, a lighting gain of 10W/m2 has been defined for both
offices during weekdays working period and Saturday morning. Select the manager_b zone.
Set the lighting in this office to zero on weekdays and Saturday.

3. Run a winter simulation and determine the impact of lights on the heating requirements.

Return to the Browse/Edit/Simulate menu. Run a simulation for a winter week (the default
period).

Run the results analysis. Look graphically at the dry bulb temperatures and heating load in
the two offices over the simulation period. Then find the total heating requirement and
number of heating hours for the two offices by returning to the results analysis menu and
selecting enquire about. The heating load in the manager_a zone should be lower than that
for manager_b - why is this the case?

4. Undertake a summer simulation and determine cooling requirements.

Repeat the simulation but change the period. In the simulation controller menu, select
simulation presets and choose the summer week and undertake a simulation.

In the results analysis, look graphically at temperatures and cooling loads, and find the total
cooling requirement and number of cooling hours for the two offices by returning to the
results analysis menu and selecting enquire about.

358
Restore the lighting in the manager_b office by editing the file in the operational details
section. Simulate the model again and check that the results are now the same for both
zones. Alternatively, you could reload the original model.

5. Define a lighting control scheme and determine its effect on plant loads

Return to the Project manager->browse/edit/simulate-> composition menu, select the

casual gains control option, and select the manager_a zone, then create.

Define a single lighting zone control where the sensed illuminance is calculated by a user
defined daylight factor as follows:

Set the control period to 0-24.

Set the calculation type to User defined DF.
View the control data.
Define the photocell location (option m) as 1.50 2.25 2.80 0.00 0.00 -1.00 i.e. the centre of
the ceiling, facing down.
Finally, for the outside glazing (labelled glazing in the source surface section) set the
daylight factor to 0.1145. This means that the photocell responds to a daylight factor of
11.45% on the working plane (i.e. 11.45% of the external horizontal illuminance) - the
information has been obtained from a separate detailed lighting study.
IMPORTANT - remember to save your control information as you will not be reminded and
the information will be lost if you exit before you save.

Simulate the model for winter, spring and summer periods and note the effect of lighting
control on the heating and cooling demands in the manager_a compared to the manager_b
office.

6. Define lighting control scheme with multiple lighting zones

Return to the Project manager->browse/edit/simulate->composition menu, select the

casual gains control option, and select the manager_b zone, then edit.

Define two lighting zone controls (a core zone and a perimeter zone) where the sensed
illuminance for each zone is calculated by a user defined daylight factor. For the perimeter
zone:

Set the control period to 0-24.

Set the calculation type to User defined DF.
For the photocell data define the proportion of the gain as 0.5.
Move the photocell to 4.50 1.125 2.80 0.00 0.00 -1.00 i.e. the centre of the office perimeter
area on the ceiling, facing down.
Finally for the outside glazing set the daylight factor to 0.1761.
Now select add/delete lighting zone and define the core lighting zone as follows:
Set the calculation type to User defined DF.
For the photocell data define the proportion of the gain as 0.5.
359
Move the photocell to 4.50 3.375 2.80 0.00 0.00 -1.00 i.e. the centre of the office core area
on the ceiling, facing down.
Finally for the outside glazing set the daylight factor to 0.0449.
IMPORTANT - remember to save your control information!

As in task 5 simulate the model for several periods in the year and compare the
performance (in terms of heating and cooling loads) of the manager_a and manager_b
offices.

360
Productivity tools

361
35 Automating tasks in ESP-r
This tutorial will cover the evaluation of options to automate tasks in ESP-r. It is a
transcription of the video: https://www.youtube.com/watch?v=KUg8SGqwOuo

In this tutorial, the model will be rotated several times and each time this action is
performed, performance metrics will be exported. This process can be done manually using
the ESP-r interface, but it can also be performed using scripts.

Files used in this tutorial: rotate-script.zip.

Download the folder and unzip the files. Save the files in a folder named "Rotate". Open
the folder

Supporting files for Automation Tutorial

Click on the file rotate45. The file contains the sequence of letters that map the commands
needed in ESP-r (in PRJ) to rotate the model.

Open a new examplar model - multi-zone model with convective heating and basic
control or simply open an old unedited model. It should have the name "basic", unless it
was saved using an alternate name.

35.1 Running prj

35.1.1 Performing PRJ tasks using keyboard inputs in graphical mode
ESP-r is mainly a simulation software, so it provides support for scripting. There are letters
in front of each option that correspond to that option.

So, the letter m is for browse/edit/simulate, then c which is composition, * is for global
tasks. Then, b for rotate. 45 specifies the degree of rotation, a represents site origin - the
point about which the rotation happens. * means all items, ie, all the zones will be rotated
362
about the previously defined point. The - option is for exiting the menu. ! is to archive the
model, ie, save the model with the above changes. The empty line represents ok. The next
two dashes are to exit and then quit the model.

In this manner, a set of commands be constructed to emulate tasks to be performed in ESP-

r.

To use the text files in the rotate folder, the files need to be present in the CFG folder in the
model folder. Copy the files to the cfg folder. There are codes stored in the rotate files to
use the text file commands.

In the file rotate45, there are letters that correspond to the options to perform the required
action.

363
35.1.2 Text Mode in prj
It is possible to run any ESP-r module in text mode. In this case, there is no graphical
interface and options must be chose using only letter for each menu option.

Enter the command below in the terminal to run ESP-r in text mode.

prj -file bld_basic.cfg -mode text &

The command is the same command used in previous tutorials, with the addition of -mode
text, which runs the software in text mode.

As can be seen in the terminal, the option and the corresponding letters are the same as in
the graphical interface. This is a way to map these letters if needed since there is no visual
input.

Enter - to exit.

35.1.3 Running a file in the Script mode

Once all options have been written in a txt file, it is possible to run prj (or any other ESP-r
module) by providing this file, and the application will read lines one by one and execute
the chosen options.

The first line- prj -mode script -file bld_basic.cfg < rotate45.txt can be understood by
breaking it into parts.

prj indicates that the project manager is being invoked. -mode script is the code for script
mode or text mode. -file bld_basic.cfg indicates the model file that is being used. <
rotate45.txt indicates the file that is being used.

364
ESP-r can be run in three modes - the graphic mode (used in previous tutorials) and the
text mode (explored in this tutorial).

Copy the command in rotate1 into the terminal:

prj -mode script -file bld_basic.cfg < rotate45.txt

The command carries out all the tasks written in the file and closed the model. Open the
graphical mode as usual. The model should have been rotated by another 45 degrees. This
way, it can be checked whether the command was properly executed.

If there is a need to repeat this process multiple times, the odds of making a mistake
increase. In this tutorial, the model has to be rotated eight times to cover all possible
orientations and the performance metrics have to be measured. This is a rather repetitive
task with multiple steps in each rotation. In such cases, automating certain tasks is a useful
tool.

Now that the model has been rotated, the simulation needs to be run. To do this, another
program in ESP-r called BPS needs to be invoked.

In this some cases after the recent release of the new version of ESP-r, the BSP command
may return a segmentation fault. This issue is being addressed in develepment. For the time
being, the problem can be bypasses by restarting the system.

35.1.4 Running a simulation in text mode using bps

bps -mode text -file bld_basic.cfg

365
35.1.5 Running a Simulation in Script Mode in bps
The first one was rotate45, which has a sequence of steps to be used when PRJ is invoked,
the project manager, now run_simulator.txt which does exactly the same thing. But for the
building performance simulations (bps) - to the integrated simulator.

bps -mode script -file bld_basic.cfg < run_simulator.txt

Open the file run_simulator. The series of commands for the building performance
simulations (bps) to the integrated simulator is stored in this file.

The first line is an empty line to accept the CFG file. "C" initiates the simulation, followed by
the name of the result file, starting date, ending date, and so on.

Invoking this sequence of steps will produce the result file, so calling this line here will
achieve that.

So BPS in script mode with the CFG file and with these commands. It runs the simulation. A
result file should be generated. Here, the bld_simple.res.

35.2 Extracting results

35.2.1 Extracting results in text mode
res -mode text....

35.2.2 Extracting results in script mode

366
Up to this moment, the model has been automated for rotation and simulation. Now, the
last step that needs to be automated is extracting the results. The third line here invokes
the result analysis tool again in script mode using the extract energy text.

res -mode script...

So open extract_energy_0.

Again, a sequence of letters is necessary to export a CSV file with the energy consumption
of this building. In this case, RES is called, which is the result analysis tool, followed by -file.
The file, in this case, is the result file that was generated (not the CFG file), which is what
will be analyzed.

As seen, the first line is an enter. Then, D is used for the inquiry. Next, the output is changed
with the greater than sign (>), followed by giving a name to the CSV file. In this case, a zero
is added, indicating that this is with zero rotation. Enter is pressed to accept the description
and the title of the graph. Then, "F" is used for energy delivered. Finally, the option to close
the file is selected. Now it returns to the screen, closing the export; the file has been closed,
and two times "-" are used to quit.

By this, a CSV file with the extension has been exported. This file should be located here:
basic0.csv. This file will be deleted, and the line will be invoked in script mode to ensure
that it runs properly.

It opens the result file, exports the data for the CSV, and then closes it. Here is basic0.csv. If
this file is opened in a text editor, the command used opens all the CSV files. In this case,
there is only one, but it can be used later to open all the files at the same time.

367
Here is the energy delivered for each of the zones. For the whole model, for this particular
orientation, there is 870 kWh per year for this model in terms of heating, with no cooling,
as already known.

35.3 Combining several scripts to automate complex tasks

Users can combine rotation on prj, running on bps, and extracting results using res.

Write a program to do these tasks

There are several versions of this script, the one in the rotate1 file is the simplest.

So by having these three scripts and invoking these three applications on text mode and
script mode, this process can be done. What this whole script does is to do exactly the
same, but it saves the file with different names.

Extract energy 45 is identical to the previous one, but it builds a different CSV file so that
when each of these lines is called, the CSV will be saved with a different name. This is a
rather inelegant way of doing it, but it was done for clarity, making it very transparent what
is being done. At a later stage, a more elegant version of the same script will be created.

Now that it has been understood how to run ESP-r in text mode and in script mode, and
how to build these sorts of files with the commands while understanding them, let's see
how all these things can be called at the same time.

The ones that were just generated will be deleted. This one is not relevant for the moment,
and this one is also not important.

In the file provided for this lecture, there is one text file called "code-improvements," which
documents the different versions of these Python commands that are present here.

35.4 Install Python

Before doing that, Python needs to be installed on the machine in case it is not already
installed. Issuing this command will prompt for the password.

368
Pressing enter multiple times is necessary if prompted to do so. Once this is done and
Python is installed on the computer, Python is a high-level computer language that allows
for writing reasonably easy-to-understand scripts as well as very powerful ones.

35.4.1 First automation script

The first automation script consists of lines that describe what happens in this file and what
version of Python should be used.

Here, two libraries are imported, and this library allows issuing commands as if typing in
the terminal. The "os.system" function is calling the operating system and issuing this
command.

Before running the simulation, PRJ is called to remove any result files, ensuring that
previous results do not cause issues. Retaining or deleting them makes it easier to manage
the result files, run the simulation, conduct the results analysis, and extract the desired CSV
files.

If this program is run, a number of CSV files should be generated, showing the energy
consumption for heating for each of these orientations. The model was already rotated a
few times, so the results will be slightly different from those of others.

369
To invoke this program, the Python file and the CFG file should be in the same location. The
program is invoked by typing Python3 followed by the name of the file: rotate_1.py.

This will run the Python code line by line—executing PRJ, deleting the file, executing bps,
and generating the result file for each of these orientations. Energy will be extracted for
each orientation, resulting in CSV files with the correct names.

Each time the file is opened again, an image showing something inside the office will
appear. The terminal displays the simulation being run, and the CSV files being created can
also be seen, such as basic0, basic45, basic90, basic135, and so on.

Although it takes time and knowledge to write this type of code, it is very powerful because
it can be used for other models and allows for much more complex automations than those
demonstrated in this lecture. The idea is not to teach how to rotate models but to illustrate
how powerful automation can be when used properly. Other more theoretical aspects of
automation will be covered in the lecture.

All these images are being closed now. All the CSV files will be opened using the command
issued a couple of minutes ago, allowing access to all of them.

The number of interest, representing the heating energy consumption for the entire year,
is changing substantially, ranging from 900 something to 700, depending on the
orientation of the model. Results will again be slightly different due to the original model
already being rotated.

A spreadsheet can be opened to copy these values manually up to this point, which is what
has been done here.

370
 Annual heating demand at different orientations

For each orientation, the energy consumption for the whole year, kWh/a per year, has been
copied, and the orientations and the energy consumption are presented. Some orientations
are significantly worse than others.

This is just a demonstration of how automation can take place. Any other task in ESP-r and
in most simulation tools can be automated. Whatever sort of analysis is being conducted,
if a repeated task is encountered, a way to automate that should be found because it will
be easier to re-run it in case of a change in a feature. It will reduce the odds of error when
clicking and copying, and it particularly opens the door to much more complex analysis.

This is the core element of this lecture, and that will be the focus of the assignment this
afternoon. Another model will be obtained to explore the same workflow.

35.4.2 Second automation script

Before finishing, some more advanced versions of this Python code will be shown, as this
one is far from ideal. All these files should be closed.

This file has a problem with repetition in each task, and there is a need to call this line with
all the elements. A few other versions of this Python code may be more interesting and
elegant specifically. The files rotate_2, rotate_3, rotate_model_loop, and code
improvements will also be opened.

In version 1 of the code, which has been used so far in this lecture, the model is rotated 45
degrees, the simulation is run, and the energy consumption is exported. This is the code
that has been used so far. Now, a much more elegant version of the same code that
performs the same functions will be examined, which is the rotate_model_loop.py.
371
Differences between this code and the previous one include the introduction of functions
for each task. There is now a function to rotate that takes a CFG file as an argument, a
function to simulate that takes the names of the CFG and the result file as arguments, and
a function to extract energy.

35.4.3 Main code loop

These functions are called in the main code. So rotate 45, run simulation, extract simulation.
They're called using a loop 8 times.

Instead of the code being copied eight times, it now runs in a loop eight times, using the
CFG file and the desired result file name as inputs. The run number in the loop is used more
elegantly to build the name of the CSV file. Thus, the name of the CSV file used in extract
energy is now derived from this loop number.

A number of lines are replaced by a much smaller, more concise, and elegant description.
Now, these three functions have to be examined for other differences.

Instead of using the os.system call and a text file with commands, a more flexible approach
is now used, where all commands are written using an array like this. PRJ is called as a
subprocess, allowing all these commands to be given as inputs.

The advantage is that, for instance, the result file or the output file here becomes part of
this process, so they can be replaced by the name of the CSV file, for example. Previously,
each text file had to be modified individually.

That's why there are files named extract0, extract45, and extract90—because they contain
a lot of "hard-coded" information. Inside each file, specific information was embedded. For
example, when one of these files is opened, the name is written directly within it. In the
updated version of the code, however, the name used in the extraction is built using the
loop number and passed as an argument to the extract energy function.

372
The out file is used as part of one of the commands, making it look slightly more
complicated, but it actually allows invoking with numbers, strings, and other elements as
input, as long as they are placed in this array in the command.

For those unfamiliar with Python, this might seem a bit more complicated than the previous
approach, but that is not the case.

35.4.4 Function to rotate in PRJ

The beginning is exactly the same. Functions are defined for each of these tasks.

This is a description of the function, and these are just comments. This array with commands
is the same one that's written in each one of the text files is the M, C, *, B and 45, and so
on. There is a command to join them all in a single element, and this is a way to call PRJ,
just a different syntax and it's in a slightly better way because it allows to handle problems
in a more robust way, so targeting them to files and so on. So this is the end of rotate.

35.4.5 Function to run simulation in BPS

Run follows the same structure.

373
First, the result file is removed if it exists. Then, all commands are compiled into an array,
joined, and BPS is called in script mode with the CFG file.

35.4.6 Function to extract energy in RES

For the extract energy it's the same.

Once these three functions are written, the actual program, when invoked—by running
Python3 with the Python file name—will execute eight times, performing these functions.

374
This approach represents a first attempt at automation.

It provides a more robust way to automate, allowing changes to various parameters:

orientation, material properties, setpoints, system capacities, PV system features, and so on.

With these two files, there is a foundation for automating ESP-r. For this exercise, go
through this process with another model or the same one, rotate it, and check if different
results are obtained and if they make sense.

35.5 Automation libraries

Members of the ESP-r community have developed various scripts to automate a range of
repetitive tasks. While these scripts may require adaptation for other uses, they provide
valuable resources for those interested in improving the workflow in ESP-r.

Some useful scripts are available in the scripts folder of ESP-r's installation (bash scripts),
and also in the tester folder of ESP-r source code (bash and Perl).

A comprehensive library of ESP-r automation tools is available at:

https://github.com/johnallison0/espy (Python).

375
36 Uncertainty analysis
36.1 Exploring a model with uncertainties
36.1.1 Open an exemplar with uncertainties defined
Start prj and select open existing.

Select Exemplar, followed by a simple > o ... with uncertainty definition.

This command copies the exemplar folder uncertain.

36.1.2 Exploring the model

Select m browse/edit/simulate

Under the Uncertainty section, select q define

In this exemplar, uncertainty is defined in the fie uncertain_ctl.ual, located in the msc
folder. Press ok to open the file.

The uncertainty definition menu is presented. Select ! list current uncertainties

376
The text feedback shows that two uncertainties are defined. One is related to the control
start, and the other to the heating SetPoint. Both uncertainties have effect over the whole
year.

On the menu, select b define/edit distributions

The menu shows the two distributions. Select ! list current

The text feedback are shows more details about these uncertainties. The start time used in
each simulation may be up to ± 1 hour, while the heating setpoint may change between
simulations up to 1°C.

377
Exit all menus and close the Project manager.

36.1.3 Uncertainty file

The image below reproduces the uncertainty definition file for this exemplar. Codes used
in the file are not immediately obvious, but the magnitude of the uncertainty can be
identified in lines 10 and 15.

This is only one of the uncertainty cases provided with this exemplar. There are other cfg
and ual files for uncertainty analysis related to climate, materials, and operation, as shown
in the images below.

36.1.4 Running a model with uncertainty

⚠ Do not use the Project manager to invoke simulations with uncertainty
378
Models with uncertainty are simulated several times to give ESP-r the chance to test
different input calue combinations. Therefore, they should be called from the Integrated
simulator. Navigate to the folder ~/uncertain/cfg/ and open the Integrated simulator:

bps -file uncertain_ctl.cfg

Once the Integrator Simulator opens, select ok for the cfg file.

Select c initiate simulation

Accept the name suggested by ESP-r for the result file.

Accept the following default values

Select s commence simulation

Accept the suggested control file.

The Analysis methods menu appears with options for the uncertainty analysis.

Select c Monte-Carlo to run several simulations with combination of input parameters

within the prescribed ranges.

379
Set the number of simulations to 100, and continue with simulations (yes).

The feedback text window indicates the simulation progress.

Once finished, select - exit menu > - quit module

36.1.5 Uncertainty analysis results

on the terminal, navigate to the folder and open the results file:

cd ../tmp

ls

res -file BLDres

The Result Analyser module issues a warning about the need for a configuration file.

380
⚠ As results are in the tmp folder, it is necessary to include manually ../cfg/ before the
file name below.

Once results are opened, the text feedback area shows a summary of the simulations.

On the dialog area, select the uncertainties.

On the menu, select i sensitivity analysis.

The Uncertainty Analysis menu shows the options available. Select option c graph
between sets

381
Once this option is selected, the Sensitivity plot menu shows several options. Select b
temperature > a dry bulb (db) temp. > - exit menu

The Result set activation menu shows all runs available for plotting. All are active, so there
is no need to select * activate all sets.

Select - exit menu

382
The graph below shows the simulation results. The impact of uncertainty in heating
setpoint is noticeable, with temperatures on average around 20°C ± 1°C. The start time
uncertainty also affects temperature increase.

383
Select h heat/cool/humidify > a Sensible heating load. The graph below show the
impact of uncertainties in the power delivered by the heating system.

36.2 Defining uncertainties

36.2.1 Overview
The following text is provided by ESP-r help, and gives an overview of uncertainty settings.

ESP-r includes formal descriptions of uncertainty for the following topics: 1) thermophysical
properties, 2) layer thickness, 3) weather 4) zone operations, 5) convection coefficients, zone
air volume.
Uncertainties are defined in a three stage process analogous to mass flow.

• One or more distributions are defined. For example, a distribution named might
create if thickness of insulation is of interest [wall_thickness] & [roof thickness] and
identify specific materials to perturb (% or +- absolute increments).
• One or more named physical locations in the model are defined e.g. [facades] &
[roof] each of which are linked to specific zones & surfaces. Thermophysical
properties & layer thickness & zone operations need a zone location. Weather
needs a temporal location.
• Distributions and locations are linked to define one or more uncertainties e.g.
[wall_thickness] + [facades]. The validity of the uncertainty is checked at
simulation time.

When the assessment is run, the following choices become available of: differential,
factorial, Monti-Carlo assessments. For each run a random seed is generated (within the
range +-2.0 and applied to the user defined bounds. The results file includes a base case
plus all of
the separate variants (sets) required.
384
36.2.2 Open an exemplar without uncertainties defined
The next sections describe the implementation of uncertainty in control setpoint.

Start prj and select open existing.

Select Exemplar, followed by a simple > a zone with convective heating & basic
control

Select m browse/edit/simulate

Select q define

Press ok to accept the name suggested for the file by ESP-r.

⚠ ESP-r suggests a name (and location) for the uncertainty definition file. The suggested
name above places this file in the cfg folder, not in the ../msc fodler as in the exemplar
explored above. It does not affect the simulation, but this information becomes important
in case the user wish to explore or edit this file manually.

The uncertainty definition menu becomes available. The next sections define the
distribution, location, and link of the uncertainty for control setpoint.

36.2.3 Set uncertainty distribution

Select b define/edit distribution

Select + add definition

385
Select f ideal controls

Press ok

Select a weekday > - exit menu

Press ok

Several sources of uncertainty in controls are available for selection. Select heating SP to
create uncertainty related to the heating setpoint.

Select absolute change

386
Give a meaningful name for this distributions. Select ok.

Once defined, the new distribution should be visible in the menu.

Select -exit menu

36.2.4 Set uncertainty locations

Back to the uncertainty definition menu, select c define/edit locations

Select + add definition

In the dialog area, select temporal (e.g. weather control)

Use the settings below to set the location period.

387
Once defined, the new period should be visible in the menu.

36.2.5 Link distributions to locations

Back to the uncertainty definition menu, select d link distributions to locations

Select + add definition

Select a heat_setpoin-3C

388
Select a wholeyear

Once defined, the new link should be visible in the menu.

Select > update library

Select yes

Select - exit menu several times and quit the Project manager

36.2.6 Adding the uncertainty file name to the cfg file

When uncertainty is defined in the Project manager, the file name is not add
automatically in the "site" area" of the cfg file. Users must add this name manually.

Open the file bld_simple.cfg in a text editor and add the line *ual bld_simple.ual as in the
image below.

36.2.7 Running a model with uncertainty

389
⚠ Do not use the Project manager to invoke simulations with uncertainty

Models with uncertainty are simulated several times to give ESP-r the chance to test
different input calue combinations. Therefore, they should be called from the Integrated
simulator. Navigate to the folder ~/simple/cfg/ and open the Integrated simulator:

bps -file bld_simple.cfg

Follow the same steps used to simulate the exemplar and run a Monte Carlo analysis with
100 simulations.

36.2.8 Analysing uncertainty results

Open the result analyser from the terminal:

cd ../tmp

res -file BLDres

⚠ remember to add ../cfg/ in the prompt about the cfg file on the Results Analyser

The graph below shows the heating sensible load in the 3rd day of the simulated period.
A variation around ±10% is seen in the peak load due to uncertainties in the setpoint. This
result can be used to size the heating system taking this uncertainty into account.

heating sensible load when uncertainty is applied to the heating setpoint

390
37 Variants
37.1 Developing multiple models to explore design and operation
alternatives
Users often need to create several versions of a model to investigate particular changes in
input, such as the impact of a new construction for a wall, or the impact of a different
control strategy. One approach is copying the entire model, renaming it, and applying the
required changes. This approach is simple, but it has some drawbacks:

• the whole model is copied to the new folder, while only one or a few files in the
model requires change, and
• if a problem in the original model is identified, copies of the model must be fixed
one by one, leading to a time consuming and error prone process.

Variants in ESP-r provide a straightforward tool to address this problem. Variants create a
new cfg file for each modified version of the model, but the remaining model files are
kept the same whenever changes are not required on them.

37.2 Variants in exemplars

Most exemplar in ESP-r use variants. For demonstration purposes, take the uncertainty
related exemplars. In the cfg folder there are several versions of cfg files, as shown in the
image below. Variants are identified by the suffix starting with the underscore character.

The next image shows a comparison of the base file uncertain.cfg (left) and variant
uncertain_clt.cfg (right). It shows that the following differences:

• the uncertainty definition file (extension ual) to be used in the simulation, as the
variant explores a different source of uncertainty,
• the the control file (extension clt), as the base file had no controls, and the variant
requires one,
• the name of the result file to be generated by the simulation, to clearly identify
results from different variants, and
• the connection file (extension cnn) which is always created for each variant, even if
it has no change like in this case.

391
Apart from these changes, base file and variant share all other files and related features,
such as climate file, materials, constructions, casual gains, fluid flow network settings, etc.
In the case of the uncertainty exemplar, a number of uncertainty definition files is
available on the msc folder, as shown below.

All variants share the same model constructions, geometry, and operations, as shown
below.

37.3 Creating variants

Start prj and select open existing.

Select Exemplar, followed by a simple > a zone with convective heating & basic
control

392
Note the name of the cfg file of this model (bld_simple.cfg), in the _Current model_ area
of the menu.

Select j variants

Create a suffix to be appended to the model name. The default text is _xyz, and should be
replaced by text that describes the nature of the variant. This example keeps the default
just for simplicity. Select ok.

Add a description for the variant. In this example, the heating setpoint of the variant will
be changed to 22°C, so enter the text below.

The Model variants menu becomes available. Each option creates dedicated files for that
feature in the model folder.

Select w controls
393
Users may select several options, creating variants that address multiple model features.
In this example, only controls are addressed, so select no.

Press ok for the suggested name of the variant connection file.

The variant is created. Note the name of the cfg file in the are _Current model_ of the
menu, indicating the variant created.

394
 On the terminal, list the files in the cfg folder (shown below). The newly created variant
(_xyz) is added to the fodler (where other variants already existed).

Users should open the variant of interest from the terminal, not from the Project Manager
interface, such as:

prj -file bld_simple_xyz.cfg

37.4 Managing variants

Handling variants can become challenging when the number and complexity of variants
increases. It is essential to document variants properly to allow quality assurance of
models and results. Maintaining a log of variants using a text file in the model cfg folder is
a simple, yet effective, measure to document variants. This task is not supported by ESP-r,
and should be performed manually by users. The simple model used above has such file
(readme.txt), reproduced below.

395
396
Source Code

397
38 Exploring the source code
This tutorial explores files available in the ESP-r source code and describes how to find
information within these files.

38.1 Extracting source code files

Download the source code from the ESRU website
(https://www.esru.strath.ac.uk//Downloads/downloads.htm#ESP-r).

Open the terminal and move to the Downloads folder and list its contents. There should
be a file such as "ESP-r_V13.3.15_Src.tar.gz" (version number may be different on your
file). Extract the contents of this compressed file.

tar -xzf ESP-r_V13.3.15_Src.tar.gz

Move to the new ESP-r_V13.3.15_Src and list its contents.

This folder contains a number of subfolders and files, such as

• data: climate files and databases,

• doc: documentation,
• models: ESP-r exemplars,
• tester: set of routines to check the correctness of ESP-r calculations,
• Install: script to compile ESP-r, and
• src: source code files containing the routines for all ESP-r programs.

Move to the src file and list its contents.

Folders are organized based on ESP-r applications. Move to the eprj folder to explore the
files related to ESP-r Project Manager.

398
Open the file prj.F containing the start of the Program Manager application.

gedit prj.F &

ESP-r is written in Fortran, a straightforward programming language known for its fast
performance for numerical applications. In Fortran, lines starting with C followed by space
are used for comments in the source code. The first lines show some of these comments.

The code for this application starts at program prj

399
The first lines in the code are dedicated to #include statements, describing other header
files. These files are located in the src/include folder, and list several parameters that are
shared by different ESP-r applications.

This is an example of the contents of the building.h header file, listing the maximum allowed
number of zones, surfaces and others.

Further in the prj.F file, parameters that are relevant only for this program are listed,
followed by their values. Parameters do not change during the program execution.

Several variables are defined for posterior usage in the code.

Common blocks list variables that are shared by several routines in the code.

The source code documentation is uneven, with some points providing more information
than others. For the beginner, navigating this source code can be quite cumbersome. This
is not a major problem, as with some practice, users can easily infer the meaning of most
parameters, variables and common blocks based on their usage in the code.

After many lines with variables' definitions and checks, around line 1200, the menus that
are seen on the prj application start appearing in the source code.

400
401
38.2 Searching the source code
While it is possible to read the source code, line by line, often users are interested in one
particular element regarding one feature of the program (for example, convection
coefficients). The Unix command grep can be used to browse through a number of files
looking for a specific pattern.

grep -i -n -R "convection coefficient" ./src/*

where the grep flags and parameters are:

• -i, search not case-sensitive,

• -n, include line number where the pattern occurred,

402
 • -R, use all subfolders and files, and
• ./src/*, to restrict the search to the source code folder.

There are many other flags and patterns that can be used with the grep command, which
are not explored here.

grep all files in "src" directory for string

This command lists in the terminal all occurrences of "convection coefficient in the source
code. In many cases, it is useful to store the results of this query into a file (such as convc.txt
in the example below).

grep -i -n -R "convection coefficient" ./src/* > convc.txt

After using this command and opening the file using gedit, the list of files and line numbers
where the term appears (as in the example below) can be scrutinized to identify relevant
points. For example, the first line shows that the file convect2.F has a routine called HTCEXT
that calculates convection coefficients for exterior surfaces.

sample of output from grep

Another way to find relevant parts of the code is by using grep to search for expressions
seen in ESP-r interface, as the interface is directly linked to variables and subroutines related
to the each part of calculations.

For example, grep can be used to identify the file containing the expression "self testing"
seen in the first menu of prj.

grep -i -n -R "self testing" ./src/* > selft.txt

403
The results show that this menu item is handled by the file prj.F, in line with the exploration
done at the beginning of this tutorial. It also indicates where the self testing calculations
may take place and where help information is stored (esruprj.help).

Grep is an important command to navigate millions of lines in ESP-r source code and find
relevant entry points to particular topics.

38.3 Exploring routines in source code files

In the convection coefficient example above, it became clear that the file convect2.F could
be responsible for the calculation of convection coefficients for external surfaces. Let's dig
further in this topic and open this file.

gedit .src/ebld/convect2.F &

The file convect2.F has three routines, including HTCEXT. Use ctrl+F to navigate to the
part of the file where this routine is described.

Model options available in HTCEXT to calculate exterior convection coefficients

This routine calculates convection coefficients for exterior surfaces, and it shows the many
models implemented in ESP-r for external convection. Reading the source code has
significant advantages over having a user manual, as it describes how the calculation is
actually done. In this example, the routine shows indexes pointing to different heat transfer
correlations implemented (15 in total).

404
For each empirical correlation, details of the calculation can be seen in this file. The image
below shows the calculation according to the MoWitt model. In this example, the transfer
coefficient (HC) for windward surfaces is calculated based on the temperature difference
between air and wall (to account for natural convection) and also based on the wind speed
(VF) to account for forced convection.

405
39 Editing the source code
This tutorial shows how to modify and compile the code.

39.1 Preparing to Edit the Source Code

There are a couple of things that are important to do before starting.

The first one is to see from which location ESP-r is currently running (where it is installed),
and it can be done by using the command 'which'.

This is important because when ESP-r is compiled, what is contained in this location will be
overwritten. The next step is to move to this particular location by using the command

cd /opt/esp-r

By having a look inside this folder it can be seen the whole range of folders with the binary
files, executables, databases, climate files, everything that comes together with ESP-r.

Before doing any new compilation of ESP-r, it is essential to move all of this to a new folder
in such a way that if needed it is possible to delete the new compilation and return to the
previous one.

The command ‘move’ needs to be invoked as a super user ('sudo' command) (so it is
possible to move it), followed by ‘esp-r’ and the file name where it should be moved, in this
example ‘esp-r-original,’ and the user password should be inserted.

ESP-r is not in the starting folder anymore: if tried to open it by typing ‘esp-r’ in the
terminal, it shouldn't open because it will look for opt/esp-r and this folder no longer exist.

39.2 Compiling ESP-r

See instructions on https://appdocs.esru.strath.ac.uk/books/introduction-to-esp-
r/page/install-esp-r-on-ubuntu-by-compiling-from-source-code

406
The compilation is going to take a several minutes, as esp-r will install each one of the
training models.

After the compilation is concluded, the screen should look similar to that showed in the
following picture.

If everything goes right once it's done, type ESP-r and the computer will have ESP-r again.
Check by going to /opt/ and show the folder content (ls) that there are two different
versions of ESP-r, the new one and the original.

39.3 Modifying the Source Code: Changing a menu item

At this point, PRJ should open in the terminal properly. To ensure the code can be changed,
one of the tags in the ‘model management’ menu will be rewritten to check if the code
reacts to the text in the source file. For example, try writing something else instead of the
word ‘CAD’ (line n) to confirm the file can actually be modified.

First, move to the Downloads folder, then to the folder where the source code is available.
Using grep, search for the CAD tool (probably not many instances of ‘CAD tool’ are written
in ESP-r) by using the command

grep -i -n -R "cad tool" ./src/*

The interested line is available in the file ‘prj.f’, and to open it type the command
407
gedit ./src/eprj/prj.F &

Use the command ‘ctrl+f’ to look in the file for the word ‘CAD’ and change the line by
adding for example ‘test compilation’.

Attention is needed to be paid because there is a limit on the size of this string.

Since this is an attempt to change the ESP-r source code for the first time, is better not to
change any of the calculations but change something that is cosmetic.

Save the file and in the same folder recompile the code. In this case there is no need to go
through the entire process of compiling all the executables and the libraries and so on. It
can be therefore used the option

sudo ./Install prj

which only re-compiles the application prj (should be faster). There is no need for the
databases, nor the training models, but it is important to answer yes to the question about
proceed with the installation.

It will ask again for the password and the question mentioned previously. This time there is
no need to install databases and training models because are already installed.

If everything went right there is a new PRJ now, that's based on the modified file. Write 'prj'
in the terminal to invoke it. As it can be seen, now in the ‘model management’ menu there
is the option 'n cad tool test compilation' just added.

The new executable that is running now is no longer ESP-r as it's distributed, but it is a
modified version. The text added as example can be removed.

39.4 Modifying the source code: Changing a default option

408
A more challenging example can now be done. In the previous tutorial it was shown that
ESP-r has a number of heat transfer coefficient equations for external facades and one of
them is the default one. The goal is now to change the default equation of ESP-r. The paper
that is provided recommends some other equations as the default ones; it can be
interesting to check how these can eventually be modified in ESP-r.

To make sure everything results as said, it is better to delete the basic folder and then start
ESP-r. In the program, click option d) open existing, choose exemplar and click simple and
then option f) multi-zone, proceed and copy the model to the basic folder.

Run a simulation of the model as it comes (integrated simulation, automated) and check
the results in terms of energy delivered to have a reference of what is the result at this
moment (42.0 kWh). To keep track of this value, write it in a file.

Open the file created in the last tutorial with the information regarding the convection
coefficient: the calculations of the convection coefficient are done in the file convect2.F,
which is worth a further investigation. To do that, use the command

gedit ./src/ebld/convect2.F &

What is interesting in this file is the 'subroutine (HTCEXT)'.

In order to see who calls this function, it can be used again the command ‘grep’:

grep -i -n -R "HTCEXT" ./src/* > HTCEXT.txt

Line 6 shows that the subroutine is called by convect1, which is then analysed.

This can be a time-consuming process, but it's rewarding in the sense that it can actually
interact with the way the calculation is done in the source code.

In the file, browse for ‘call HTCEXT’. As written in the text file, these words are in line 134.

409
The line above it gives a very crucial piece of information: ‘icor’ is the name of the
correlation that will be used. There are 15 options and now the default is being used all the
time. The goal is to change the way ‘icor’ is defined. Apparently ‘icor’ is coming from
another variable which is ‘icorexhct’, so it can be used again the function grep and by an
iterative process it is possible to find information about the way the source code works.

grep -i -n -R "icorexhct" ./src/* > icorexhct.txt

By opening the text file, it can be seen that it is called in many locations.

At the location bps.F there is a line that says that icor is equal to 1 and this is very likely the
place that defines that the correlation 1 (MacAdams) is the default correlation in ESP-r.

There are other places where the default icor could be defined, for example simcon.f. Before
opening the bps, open this file to have a look at its contents. Search for ‘icorexhct’ and go
in the position where it is called.

In this part of the file there is a menu with the name of different things and something
about toggles. In ESP-r there is a place for toggles: to see it run in ESP-r an integrated
simulation in interactive mode. Initiate the simulation without preserving results. One of
the options in the menu is the ‘simulation options’, which is what is being mentioned in the
410
code. When opened, many options are presented, and amongst these there is one about
convection methods for external facades (t). By open its link, it can be found exactly the
menu saw in the code, therefore the information for the menu in the program is coming
from the analysed file.

From here it can actually be selected the correlation that will be used; now this is the icor
= 1, the default method of ESP-r which is MacAdams, but another one of those mentioned
in the paper can be used.

The aim of this exercise is to run a simulation with the second expression, that is suitable
for low-rise buildings. Select the option B (icor = 2, which is MoWiTT), accept the
implicitness degree given, exit the menu and commence the simulation, say yes to continue
the simulation and save the results. Now in the results there should be a different energy
output because of the change in the way convection is taken into account (energy delivered
= 42.5 kWh).

The correlation coefficients can therefore be changed by looking at the source code,
browsing through different parts of it and eventually find something in the interface that
will allow to do that. Browsing the source code is composed of: search where there is
interest, find a new keyword and what is the function that's calling this, analyse this other
piece of code and so on. In the beginning, it will take more time, but after getting familiar
with it, it can be navigated through the code reasonably well and find what is wanted.

To impose to always use equation 2 as the default equation, change in the source code file
simcon.F the line regarding icor = 2 ‘MoWiTT low rise hc (default)’, which is the one for high
rise buildings. For the aim of the exercise it will be supposed to have this one as the
recommended one.

411
It is also necessary to change the other line ‘icorexhct = 1’ which is located in the BPS file,
as it can be seen from the previously created file ‘icorexhct.txt’. BPS is the main integrated
simulator which defines this default.

The value assigned to ‘icorexhct’ is then transferred to ‘icor’ in the file convect1.F (shown in
the following picture), where the function calls the other function ‘HTCEXT’ (defined in the
file convect2.F) using the icor provided in the simcon.F file.

By changing that number to 2, this whole sequence instead of leading to one will lead the
icor to 2.

Now in the bps.F file change the default icorexhct from model 1 to model 2, and in the
convect2.F file rewrite the information line by saying that now is icor = 2 the default. The
first one is the change that will actually make a difference, the second is only for the purpose
of documentation.

Save the two modified files and recompile the integrated simulator. This is no longer a
matter of the interface PRJ, but on the simulator BPS that is actually defining this default.

It is needed to recompile BPS, after closing all the files and application from ESP-r, by typing:

sudo ./Install bps --no-dbs --no-training --silent

The flags used in this command make sure databases and training models are not installed,
and also reuses previous compellation files and adopts all defaults.

412
The command below shows all flags available in the Install script:

sudo ./Install -h

Now BPS is being compiled in such a way that while it runs it will use the variable for the
correlation icor = 2, which is passed in convect1.F and then eventually to the called function
defines which one of the correlations is being used in the file convect2.F.

Another change that can be done is modify the coefficients in the equations presented in
this file, or even replace an entire model or add a new one (would be icor = 16).

Now there is the knowledge and skill to change a small fraction of the code: a very clear
target is needed, and the code will be navigated to find it and define ways to verify if the
change is working properly.

After the BPS installation is completed, the result should always be 42.5 kWh and not
anymore 42.0 (the original one) kWh, for the model taken into account.

Next step will be to go back to the home folder, move to cd basic/cfg, and start PRJ with
the cfg file ‘bld_basic.cfg’.

It might be better to write a note in the text feedback which says that it is a modified version.

As a simulation is run( can be integrated because it uses all the defaults) and check the
results, the energy delivered will be 42.5 kWh. Therefore BPS is running with icor = 2 (The
MoWiTT equation) and the default transfer coefficient equation for external surfaces has
been modified correctly.

If it feels like modifying other elements of the code or understanding in a better way how
this is done in the code, there are the tools to - with proper time, patience and the necessary
understanding - to go through the code and find the places where it is needed to modify
them.

39.4.1 Writing variables to the terminal

It is often useful to design strategies to track changes in variables during execution. This
can be done by writing variables to a file as the code is executed, or directly to the terminal.

413
Add the text below to the code to print the value of ICOR to the terminal during runtime:

C Writing variable to terminal for debugging purposes only

WRITE(*,*) 'The ICOR used in the execution was:',ICOR

39.4.2 Reverting to the original state

The last explanation in this tutorial will be on how to revert ESP-r to the previous version, if
there is the need. It is required to exit all the ESP-r applications (ESP-r, PRJ and BPS) and go
back to the OPT folder, where is the new ESP-r version with the new default heat transfer
coefficient equation for convection and the old one, and move ESP-r to a new folder called
‘ESP-r-hct’.

Now there is no ESP-r available in my system, neither of the two would actually run ESP-r;
there is the original one with the original transfer coefficient and the new one with the new
default. The next step is to move ESP-r-original to ESP-r.

At this point ESP-r is as it was at the beginning, and can be used as usual. Is the original
version that will run, not the modified one with a different transfer coefficient.

There are other ways to do this management, but to keep things reasonably simple it can
be done by just managing the folders.

414
40 Debugging
When ESP-r crashes or shows unexpected behavior, it becomes necessary to find the line(s)
of code responsible for the problem.

This page describes some tools that can help new ESP-r users/developers in this task.

40.1 Errors
40.1.1 Reproduce the error
It is not unusual that problems reported by users are not in fact bugs, but issues in the way
ESP-r is used in a particular problem. Therefore, before trying to solve a bug, make sure it
can be reproduced using one or more exemplars.

40.1.2 Check if the error has been reported

Use the Search function on the top of the page to see if the problem or unexpected
behavior has been addressed in the documentation. In many cases the error is a known
problem and the documentation may provide a solution for it that does not involve
debugging.

Also, check the ESP-r Community Discord page to see if the error has not been reported
before (Join us on Discord).

40.1.3 Document the error

In the example below, ESP-r crashed in the menu Geometry when running on text mode.
The problem did not occur when the graphic interface was being used. The image below
shows the menu in text mode just before the error occur.

The image below shows the error in the Linux terminal.

415
To reproduce this error, use this sequence of commands:

• prj -mode text -file bld_basic.cfg

• m
• c
• a
• a
• h
• a

40.1.4 Report the error

Errors may be reported on Discord, post it in the mailing list, or contact the ESP-r Archivist.
Provide the documentation above so other developers can reproduce the error.

40.2 Debugging
40.2.1 Identify the area of the code where the error occur
The following steps may be used to identify the problem in the code.

One way to locate the part of the code responsible for the error is to use grep and search
the source code for strings in the user-interface close to the occurrence of the error. In the
example below, the last line of the user interface is used in the search:

grep -i -n -R 'Shading obstruction definition via' ./src/*

The image below shows grep results. It is clear that the file edgeo.F in the eprj folder of
the source code is a good starting point to identify the cause of the error.

416
The image below shows the part of the code identified in the grep command (line numbers
are provided in green in the grep result above). It is a large piece of code, and the error
may be in any part of this if statement, of in one of the subroutines called. THe next section
uses the debug option to identify the line where code fails.

40.2.2 Use the debug option on the Install script

In the ESP-r source code folder, recompile prj using the ---extra-debug option:

sudo ./Install prj --no-dbs --no-training --silent --extra-debug

After the compilation, reproduce the error. The terminal should show additional
information about the error, as in the image below.

417
The debug option shows the files of the code involved in the error, as well as the lines of
the code where the error occurred. Notice that the edgeo.F file is in the list, and the error
is listed on line 1499. The image below shows the line, indicating that it calls the subroutine
EDOBS, so the bug is not in edgeo.F itself. The image above also shows that the error in
edgeo is followed by an error in the file edobs.F (line 231).

Open the file edobs.F. The image below shows the part of the code around line 231.

In the image above, the line indicated in the debug message is related to the subroutine
redraw.

Up to this point the procedure for the identification of bugs described above can be
reproduced for any bug. However, each bug is unique and understanding the nature of the

418
bug helps identifying the actual problem in the code. In this particular example, it is very
likely that this is the cause of the bug, as the code is able to redraw when ESP-r is on graphic
mode, but it crashes if there is an attempt to redraw when in text mode.

40.2.3 Testing a hypothesis about the bug in the code

In the file edobs.F. add a few WRITE statements before and after the point where the error
occur. There write statements is printed in the Linux terminal as ESP-r is executed. It is
possible to write static string (such as 'check-point 1') or write the current value of
variables (such as, in this example 'izgfog = ', izgfoc). If this is correct, the execution shows
the message check-point 1 and the value of the variable izgfog, but wiill crash before the
displaying 'check-point 2'.

Save the file, recompile the code, and reproduce the error. the image below shows the
terminal response, indicating that the problem does occur in the line with the call to the
subroutine redraw.

40.2.4 Solving the bug

The solution for each bug is unique and depends on the nature of the bug. In this
particular case, the call to redraw could, for example, be removed. This would solve the
problem in text mode, and users in graphic mode would need to redraw the problem
manually.

A more elegant solution would be placing an if statement before the redraw call, only
executing it if ESP-r is in graphic mode. This would, of course, require further research to
identify which variable in the code holds the graphic-text-mode status. As solving the bug
is a case dependent problem, there is little gain on demonstrating it here. hence these
solutions are not addressed in this tutorial.

The next section of this page describes a way the quick_rebuild flag, which can facilitate
the work during code development.

40.2.5 Carrying our multiple successive compilations

419
When debugging, it is often necessary to recompile the code several times to test
different solutions, and in this conditions the compilation process can become time-
consuming. During compilation, the Install script produces a number of object files, where
compile code for each fortran file is stored. The Install script deletes all these files at the
end of compilation to save space, but it is possible to keep them and reuse them in future
compilations, greatly increasing the compilations speed.

Before recompiling the code, look at the contents of the source code folder eprj (see
image below). There are only Fortran files in this folder.

Now recompile the prj using the --quick_rebuild flag.

sudo ./Install prj --no-dbs --no-training --silent --extra-debug --quick_rebuild

After compilation, the eprj folder should show a number of object files (O File type). From
now on, any recompilation of prj becomes much faster, reducing debugging time when
multiple successive compilations are needed.

⚠ In the debugging process, some fortran files are certainly modified. When using the --
quick_rebuild flag, it is essential to delete the object files for the modified fortran
files. This forces the Install script to recreate the object files using the modified version of
the source code.

420
Once the debugging process is completed, remove the flags:

• --quick_rebuild, and
• --extra-debug.

Rebuild the executable with no debugging instructions and removing all object files after
compilation.

sudo ./Install prj --no-dbs --no-training --silent

421
41 Validation
41.1 Self testing
ESP- has gone through extensive validation (e.g. Strachan et all 2008). Part of the
validation models is available for testing on the first menu of Project Manager.

Select option c self testing.

41.2 BESTEST
This menu shows two options, the first dedicated to simpler tests related to conduction,
and second covering models of the International Energy Agency building energy
simulation test (BESTEST) and diagnostic method.

Select b BESTEST.

422
BESTEST results were incorporated into standards such as ASHRAE 140, and while this
validation exercise took place decades ago it is still considered one of the most relevant
and comprehensible ones in the field.. There are several tests covering different elements
of energy modelling.

Select a high mass basic sensitivity test.

BESTEST cases are identified by numbers (see original report).

Select a 900-600 followed by -exit menu to activate this selection.

Select the screen option in the dialog area.

423
The simulation is then carried out and a summary of the test is shown in the text feedback
window, indicating the results obtained for annual energy demand heating and cooling
(first lines), and for peak power for heating and cooling. Four values are provided for each
metric: the first column shows results obtained by ESP-r , the second and third columns
show the minimum and maximum values accepted by the BESTEST, and the last column
shows results obtained by ESP-r when the BESTEST was developed in 1993.

424
PART 2
res - the result analysis
application for ESP-r
ESP-r is a suite comprising several applications, and res is the one dedicated
to result analysis. It provide several tools to analyse results and export parts
of the data set to analysis by other tools. This document aims at providing a
detailed account of all res functionalities.

425
426
Starting res

427
42 ESP-r result files
42.1 ESP-r result files' names
Understanding how result files are generated and named is essential to use res. ESP-r
models may include one or more calculation domain (e.g. thermal, airflow, electrical),
therefore some capabilities of res are only available if the model used in the simulation
addressed that particular domain. For example, fluid flow network results, such as pressures
and calculated flow rates, will not be shown on res unless the model used in the simulation
includes a flow network.

Each calculation domain generates a separate result set that is stored in a dedicated file.
The name of this result files is shown on prj before the simulation, as part of the Simulation
Controller menu, in the simulation presets area, as shown in the image below.

The example on this image shows that only the thermal domain will be calculated in this
simulation, indicated by the option h zone results: Results for the thermal domain will be
stored in a file named bld_basic_win.res. Other domains are marked as N/A, indicating
they are not available for calculations.

File and folder names are case-sensitive.

428
File extension .res usually is associated with thermal domain results, but users can adopt
any arbitrary extension or even have a file with no extension and res will still work properly.
Other extensions are associated with each domain, and prj automatically suggests
adequate extensions when these domains are available in the model.

42.2 Result file locations

Result files location depends on how simulations were invoked on prj or bps. If simulations
are carried out using prj automated option, results files will be located by default in the
cfg folder of the model. If the interactive option is used on prj or if bps is invoked from
the command line, the result files will be placed in the tmp folder of the model.

42.3 Result files are binary

ESP-r simulation results are usually stored in binary format, which means they cannot be
read with a text editor or spreadsheet. res has functionalities to export results in ASCII
format (see the report section for this functionality).

ESP-r simulator, bps, has functionalities to generate some result files in XML format. These
XML files can be directly opened in a text editor and are not meant for use with res. See
note on result save level 5 in the next section for more information on XML result files.

42.4 Result save levels

ESP-r simulations generate a vast quantity of results and writing results to a file is a time
consuming process in program execution. ESP-r provides options to save results in different
levels of detail. Users can select the adequate level for their needs, avoiding large files and
long simulation times when suitable.

On prj, the result save level is indicated in the Simulation controller on the simulation
presets (as shown in the figure below).

429
The following levels are available:

• Level 0: summary table

• Level 1: air temperatures, and fluxes
o Most concise result file containing results on time step basis.
• Level 2: air and surface temperatures, and fluxes
o This option does not include energy balance figures nor temperature data
for nodes inside construction components.
• Level 3: air, surface and node temperatures, and fluxes
o Largest file size and longest simulation time, as temperatures for all
intra-construction nodes are stored.
• Level 4: air and surface temperatures, and fluxes, and energy balance
o Default option suitable for most cases. Does not include intra-
construction node temperatures.
• Level 5: H3K no res file
o This option generates custom ASCII files with selected ESP-r results. Result
files are created in the cfg folder and can be open in text or spreadsheets
eeditos. Instruction to use his option can be found in the source code, on
the file cetc/h3kreports/ConfigureH3kReports.txt.
• Level 6: csv summary
o Very concise summary with heating and cooling aggregated values. An
ASCII file is generated in the cfg folder.

430
In the following pages/chapters of this guide, each section indicates which exemplar
model and result saving level were used to generate results shown in the figures.

42.5 Multiple result data sets in a single result file

ESP-r can store results for the thermal domain for multiple simulations in a single file. This
is useful in cases where variations of the model are used to generate different result sets,
but the user wants to store them all sets in a single file. This capability becomes evident
when a user starts a simulation and ESP-r finds a result set stored in the file indicated by
the user. This will lead to the simulator to prompt the user (see image below) to either
preserve the existing set (adding a new set to the file) or do not preserve the existing set
(deleting the current set and replacing it by the new results to be generated by the
simulator).

If the users chooses to preserve the results, a second prompt is presented (see image
below). It stresses that multiple results sets can only be stored in a single .res file if they are
based on the same model cfg file (as indicated in the help window).

In res, result files with multiple result sets will have the option 2 in the Module menu
available (see image below). Using this option users can select which result set will be
shown. For most functionalities on res, only one result set can be visualised at a time.

431
Files with multiple datasets will also prompt the user to select one of them when res opens
the file (see image below). In this example the first set (a) has results for the base model,
while the second set (b) has results for a model variant 1 (the name of both variants are
defined by the user when he invokes each simulation.

Example of result file with 2 datasets (note options in the menu as well as summary in the
text feedback area)
432
43 Starting res using the command line
43.1 Different ways to start res
As other application in the ESP-r suite, there are several ways to invoke res. This section
describes the ways to start res using the Ubuntu terminal.

43.2 Graphic mode

43.2.1 Start res with no input file in graphic mode
res can be invoked with the command

res

invoking res on graphic mode with no arguments

Starting res with no arguments is not advisable, as the user will need to type the name of
the result file on the interface as soon as the program starts. ESP-r does not offer
functionalities to browse through folders, so the user needs to know in advance the exact
name (case sensitive) of the result file to be used in the analysis. res assume the file is
located on the same folder from where it was invoked. It is possible to use relative paths
from this folder to indicate files located elsewhere.

All res screens have a help function indicated by ? (as in the image above) or by ? help (in
most menus of res). This help is contextual, offering information concerning the options
available to the user at that particular moment. The help function opens a window over the
feedback area of res, and it may offer valuable information for users. The image below
shows the help for the first res screen, indicating the existence of sample result file. Click
Dismiss to return the dialogue area.

433
 example of res help function

The option d in the images above indicates the default option for a res prompt. Pressing
this button leads to the prompt shown in the image below. The default option in this case
points to a sample file located in the ESP-r installation folder. Users can accept this file if
they wish to explore some typical results for the thermal domain. There are no default
results for other calculation domains.

43.2.2 Start res specifying the input file in graphic mode

The best way to invoke res when simulation results are already available in a file is to:

• identify the folder holding the model (in the example below is the ~/basic folder)
• navigate to the folder where result file(s) are located (usually the cfg folder of the
model),
• list the result files available and choose the adequate file (in the example in the
image below is the bld_basic_win1.res), and
• start res using the option -file as shown in the figure below.

ls *.res

434
res -file <name of the result file>

invoke res on graphic mode with the -file option

Pressing ENTER on the keyboard corresponds to clicking on the button ok on res graphic
interface; however, the key ESC has no effect and does not correspond to the cancel
option.

⚠ The message "Error opening session log!" in the text feedback area of res can be
ignored, as it does not affect res functionalities.

Using the -file option has clear advantages, as it brings the name of the result file to the
first screen of res and the user only needs to press ok to proceed with the result analysis
using that file (as shown in the image above). The -file option is the recommended way to
invoke applications in ESP-r.

Press ok to proceed.

The image below shows the first screen of res with the module options.

435
 res Module option screen

43.2.3 Text feedback when a result file is successively opened

If a model opens correctly, the text feedback area will show various relevant information
about the model, such as:

• the number of data sets in the result file (in the case above there is only one);
• the control file used in the simulation (bld_simple.ctl, where the last two
characters of the file name are omitted by res for brevity);
• The start (day 9 month 1) and end (day 15 month 1) of the simulation;
• The number of time steps per hours (in this case, 2, i.e. each time step has 30
minutes);
• The value for a "average flag", where the default 0 (as in the image above)
indicates results are averaged over the hour;
• The number of the simulation preset used on prj to invoke the simulation (in the
example, preset number 2 was used);
• A flag if solar radiation data in weather file hour-centered (0 as in the example
above: this is the default) or half-hour centered (1);
• And a note provided by the user who performed the simulation (in the example
"Result bld_simple").

The text feedback area will also show if all zones are considered for output. The user can at
any point select particular zones for output on res.

436
The simulation period ( output period: 00:15 on 09/01/67 to 23:45 on 15/01/67). ESP-r
considered time 00:00 of the first day of simulation results as part of the initialization and
data for this time-step is not included in the result file. As the time-step in this example is
30 minutes, and the average flag is ON, ESP-r shows results for the first time-step at 00:15
(i.e. the average of results on 00:00 and 00:30). The next results in this dataset will be for
time 00:45, 01:15, 01:45, successively. Averaging results smooths the results and reduces
the impact of spurious results in the simulation. Averaging results is also useful in some
comparisons with experimental data, as some sensors take readings at high frequency, but
only store an average value at longer intervals. If the average flag were OFF when the
simulation was carried out, the simulator bps would have written a different set of results
in the res file, and the output period in this example would be 00:30 on 09/01/67 to 24:00
on 15/01/67, with results reported for the exact time of each time-step.

The last field in the feedback area when a file is open indicates the number of time-steps
reported in the output shown by res. If this number is greater than 1, res skips some time-
steps when generating graphs and reports (the larger the number, the more time-steps are
skipped by res). Displaying results in simulations with short time-steps (e.g. one minute)
requires considerable computational power, and users may choose on res to display only
one out of each n time-step results available in the file to speed-up res execution.

43.2.4 Feedback when the result file is corrupted

If the result file is, for any reason, corrupted, res will show a message indicating this problem
in the dialog area. While the option "continue" is offered, it is often advisable to discard
this file and run the simulation again to generate an adequate res file.

43.3 Text mode

43.3.1 Start res on text mode
All application in the ESP-r suite can be used in text mode as well. Text mode is particularly
helpful for users interested in automating repetitive tasks in ESP-r or embed ESP-r in other
applications, as scripting actions in text mode are much simpler than in graphic user
interface (GUI). To invoke res with no GUI use:

res -mode text

res prompt the user to provide the result file name (image below), similarly to the
behaviour seen in graphic mode.

437
 invoking res on graphic mode with no arguments

In text mode there are no options to cancel or use a default file when res is invoked. If the
user wants to terminate res at this stage it must do so by killing the process pressing:

ctrl + c

⚠ Do not use ctrl + z as it stops the process but keeps the process paused and using
computer memory.

43.3.2 Start res specifying the input file in text mode

A better approach to start res on text mode is to provide the name of the result file when
invoking the program:

res -file <name of the result file> - mode text

invoking res on text mode with the -file option

In this case the user only needs to press ENTER to proceed using the currently used result
file.

438
Press ENTER to continue.

The image below shows the first text menu of res in text mode, with the same module
options seen in the graphic mode.

res Module option menu on text mode

43.4 res command help

As all applications in the ESP-r suite, res argument options can be seen using:

res -help

The image below shows the options available, where the arguments -mode (text, and the
default mode graphic) and -file were covered above. The other options will be covered in
other sections of this document.

439
 res options in the command line

440
44 Starting res using ESP-r Project Manager prj
44.1 Running a simulation with simulation presets on prj
Before running a simulation, make sure simulation presets are enable in the simulation
controller menu, and make sure the name of the result file is specified (see image below).
This facilitates calling res from prj as the name of the result file will be passed by prj to res.

sequence of prj menus to run a simulation with presets defined

When a simulation is started from prj using option q integrated simulation, the user is
asked to select between interactive or automated simulations (see image below).
Automated simulations adopt default settings for all settings available in ESP-r Simulator
bps, and produce result files for thermal and air flow domains (but not for other domains,
even if they are enabled in the model).

Result files from automated simulations are placed on the cfg folder.

Result files from interactive simulations are placed on the tmp folder.

441
44.2 Start res on graphic mode
From the Browse/edit/simulate menu on prj, use the option t result analysis to start res.

res will open on a separate window, and prj will remain open as well (see image below).
prj and res can still be open independently from this point.

442
res assumes the file is on the cfg folder, so if an automated simulation was carried out
from prj the user can click ok (or press ENTER) to start the result analysis.

44.3 Simulations results from interactive simulations

If an interactive simulation was invoked from prj, the result file will not be on the cfg
folder and res will show the message below when the user attempts to start the result
analysis.

The user can prevent this problem by adding ../tmp/ before the name of the file (as in
the image below).

44.4 Multiple res sessions

It is possible to have multiple res sessions active at the same time. This can be useful to
conduct result analysis side-by-side using different result files, but is good practice to
close all instances of res as soon as the analysis is concluded.

443
 multiple simultaneous res sessions on Ubuntu

multiple simultaneous res sessions on Ubuntu on WSL

44.5 Starting res from prj in text mode

While there is an the option to start res from prj in text mode, this option should not be
used, and it is preferable to start res directly from the command line if text mode is
required.

On Ubuntu, invoking res from prj on text mode opens a new window for res (see image
below).

444
 starting res from prj on text mode on Ubuntu

On Ubuntu running on WSL, the OS has no means to open a new terminal window and an
error message is presented:

starting res from prj on text mode on Ubuntu running on WSL

Starting res

445
45 Main elements of res graphic interface
45.1 ESP-r Result Analyser areas
res has four main areas on its interface (see image below).

buttons on res interface

45.1.1 Menu area

The menu area, on the right, is the main form for user input. Users can click on the
desired option, or type the first letter or number shown in each option. Menus are nested,
so each option of the menu in the image above opens a second level of menus. Users can
always return to the upper level using the last option in each menu.

45.1.2 Dialog area

The dialog area, on the bottom of the interface, shows options available for the user
depending on the item chosen in the menu. The dialog area may show options where no
text input is required (as in the example in the image below). In this case, the user can select
an option by clicking on it or by pressing the keyboard. The buttons on the dialogue area
as mapped to the letters of the alphabet, so in the option below, pressing a will activate
the option yes, pressing b will activate the option no, and pressing c will activate the help
option ?.

446
 example of dialog with no text input

The dialogue area may also show a field for text input, such as a file name or the value for
a parameter (see example below). In this case, any character pressed on the keyboard will
be included in the text field. The option ok is usually mapped to the ENTER key, Copy and
paste functions, as well as keys DEL and ESC do not work on input text box in the dialog
area.

example of dialog with text input

✔ In most text input dialog boxes, blank characters before and/or after the text entry are
ignored by res.

45.1.3 Graphic area

The graphic area will display simulation results requested by the user using the options on
menus and dialogues, as in the example below.

447
 example of output in the graphical area of the interface

It is possible to control the aspect ratio of plots by resizing the main res window, as in the
two examples below.

example resizing res window to plot wide graphs

448
 example resizing res window to plot narrow graphs

45.1.4 Text feedback area

The text area has three purposes:

• show messages related to the program execution, such as warnings, errors,

• show information about the result file, such as simulation period and number of
time-steps per hour, and
• show simulation results as requested by the user using the menu and dialogue
options.

The text feedback area has a scroll bar on its left side (click on the bar or drag and drop
the slider). The mouse scroll button and the Page Up and Page Down keyboard options
do not work in the text feedback area.

449
45.2 res interface buttons
There are 5 buttons always visible on res interface on graphic mode (see image below).

buttons on res interface

45.2.1 Resize graphic/text areas button

The resize button works to move the separation line between the graphic and text feedback
areas, in case the user prefers to have a large space on the interface for one of the areas.
This is the only division of areas on res interface that can be defined by the user. To resize
the division, right-clicking and holding the button and drag it up or down to move the
division line.

45.2.2 Capture screen button

The capture graph buttons allow storing the contents of the whole res interface in an image
file on gif format. The user is prompted to provide a file name (see image below), and the
file is usually stored in the model cfg folder.

Once the user presses ok, the capture button is highlighted (see image below). The user
must click on any point of the interface (the red rectangle in the image below) to

450
conclude the capture process and write the image to the gif file. If a file with the chosen
name already exists, res will overwrite the file, erasing its previous contents (no warning is
given by res).

capture image button activated - click on any point of the interface to complete capture
process

User can also capture parts of res interface using OS print screen capabilities available on
Ubuntu and Windows.

45.2.3 Capture text button

The capture text button allows storing the contents of the text feedback area in to a text
file. All content is stored, including previous lines no longer shown in the feedback area.
The users is prompted to provide a file name (see image below), and the file is usually
stored in the model cfg folder. If the file with the chosen name already exists, res will add
the text at the end of the original contents of the file.

45.2.4 Font button

451
The font button opens a window with functionalities to increase or reduce the text size in
menus, text feedback and dialogues (see image below). Options need to be selected
using the mouse (no keyboard input is allowed for font sizes).

text size window

Once an option is selected, the change in text size is implemented and the window
disappear. It is possible to repeat the operation to further increase text size one more
time (see before and after example in the image below).

452
 menu text size example

Dialogue text size must be modified before a dialogue option is shown. Do not attempt to
resize dialog text when there is text shown in the dialogue area, as the text will disappear.

45.2.5 License button

This button shows the license terms under which the ESP-r suite is licensed
(https://opensource.org/license/gpl-2-0/). This license is very permissive, as (in a nutshell)
users can freely use and distribute the application, and also modify the source code (as
long as any new developments are also published under the same license).

res license window

Starting res

453
46 Module Options
46.1 Main res menu
The two images below show the options in the first menu of res in graphic and text mode.
res menus are usually divided in three sections. In this particular case, they are:

• upper section (with options starting from 1 to 4) dedicated to the selection of

data for post processing by res,
• middle section (with options starting from a to j) dedicated to the core
functionalities,
• lower section (with options starting from r to -) holding options and navigation
for this menu,

This page covers in detail the upper and lower sections. The middle part is addressed in
the following chapters and pages of this document.

Module menu in graphic mode

454
 Module menu in text mode

46.1.1 1 result file

This option allows changing or reloading the result file. This is useful if a new file needs to
be loaded, or if the reporting settings have been changed and the user wants to reload
the file to receive a more detailed feedback about the model used in the simulation (see
the r report >> section further on this page).

46.1.2 2 result set

This option allows choosing from different datasets, in case the result file has more than
one of them. This option is available in several other menus on res, so users can switch
between datasets while plotting graphs, generating reports, etc. See the previous section
about result files for more information about multiple datasets in a single file.

46.1.3 3 output period

This option allows the selection of start and end times for result analysis. This option is
available in several other menus on res, so users can customize the time window while
plotting graphs, generating reports, etc.

When the define output period option is chosen, the users is prompted with a number of
successive dialogs in the dialog area. Firstly, the user should provide the starting time for
plotting (see image below). Hour 1 is defined as the period 0h00 to 1h00, and hour 2 is
defined as the period 1h00 to 2h00, etc.

⚠ This dialog, as many in ESP-r, do not have a cancel option. If the user no longer wants
to set the output period, it is often possible to go through the sequence of dialogs
accepting the suggested values (just pressing ENTER until return to the original menu
option selection). It is also possible to close res and start it again.

Values should be integers and separated by one or more blank characters. Commas can
also be used to separate day, month, hour values.
455
res will check if values are valid and will show an error message for values with decimal
places, or unrealistic values such as the ones in the image below.

error message for invalid input on output period

res will not check in the output period dialog if the chosen start and end periods are
within the time covered in the result file. If the user selects a starting time not covered by
the results, res will only show an error message (like the example in the image below)
when the user tries to plot graphs of generate reports based on that output period.

error when trying to generate a graph for an output period not covered in the results data
set

If the error shown in the image above occurs, res may behave inappropriately as in the
example of the image below, where an endless loop is presented and the user can only
press continue multiple times, generating new errors at each attempt. In this cases, it is
better to close res window and start res again. The result file(s) will not be corrupted by
this operation.

456
 error in user input leads to a loop in res - closing the application is advisable

Once the user defines the start time, res shows a similar dialog for the end time selection
(as in the image below).

In case the user selects an end time falling before the start time, the following error
message is presented:

The default option d for start and end time does not offer reliable suggestions (see image
below) and should not be used.

Once the user defines the start and end time, res shows a dialog for the selection of the
output time-step increment (discussed in a previous session). This value indicates the

457
number of time-steps reported in the output shown by res. If this number is greater than
1, res skips some time-steps when generating graphs and reports (the larger the number,
the more time-steps are skipped by res). Displaying results in simulations with short time-
steps (e.g. one minute) requires considerable computational power, and users may
choose on res to display only one out of each n time-step results available in the file to
speed-up res execution.

⚠ Sometimes, the output period option does not respond correctly. Closing and
restarting res will fix this problem.

46.1.4 4 building zones

Result files may comprise data for several thermal zones, and this option allows the
selection of particular zones for result analysis. This option is available in several other
menus on res, so users can select the adequate number of zones to facilitate the
visualization of results while plotting graphs, generating reports, etc.

In the example below, the result file has data for three thermal zones.

When a zone is selected by the user, this will be indicated by an asterisk after the zone
name, as in the image below.

458
Clicking again (or pressing the corresponding menu letter) in a zone previously selected
will remove the zone from the selection. The text feedback window provides an update on
the addition and removal of zones from the selection (see image below). The dialog area
brings instructions about what the task, indicating that one or more zones may be
selected.

✔ In ESP-r, the option "- exit menu" is often used to accept the selection and return to the
previous menu.

Text feedback and dialog for the building zone selection option

46.1.5 r report >>

This option controls how much information is shown in the feedback text area when a
result file is open on res. Result files do not carry information about model features, but
res can retrieve this information from the model and show it when results are loaded.
Menu options, like this one, followed by the symbols >> indicate that users can toggle
through different options. There are three levels of reporting available:

• Silence (default)
• Summary
• Detailed (very comprehensive, see image below for a partial display of the report
generated)

If the report level is changed, it is possible to reload the result file and force res to show
the requested information in the feedback text area.

459
 Example of detailed report about the model, shown by res when a result file is opened

46.1.6 * preferences
The preference option gives access to 3 distinct functionalities.

460
a Display format for date. The following options are available:

• 10/01/21
• DOY 10 (Day Of Year)
• 10 Jan
• Fri 10 Jan

b Display format for time

• 10h00
• 10.00
• 0.41666 (i.e. 10/24).

d Recording-of-picks. This option opens a dialog to enable the recording of user actions
on res, to facilitate scripting tasks. This option does not seem to be working properly at
the moment, as no file is generated.

46.1.7 ? help
This help is shown here just to show the pagination used in ESP-r help functions. The
buttons with arrows in the lower part of the image below allow users to navigate through
long help messages.

461
 res main menu help - page 1

res main menu help - second and last page

46.1.8 - quit module

This option terminates res.

462
Graph: Parameter plot

463
47 Graph types
The option a graphs in the Module option menu opens the Graphing options menu. The
upper section shows the same functions seen in the Module options menu, apart from the
result file option that is no longer available in this menu level. In ESP-r, menus are nested,
so each option of one menu leads to a deeper new level of menus with new options.. Users
can always return to the previous level using the last option in each menu (- exit menu).

The following pages/chapters cover each one of the graphing tools provided by res
(options a to f in the menu).

Graphing options menu

464
48 Parameter plot menu
The image below shows the Parameter plot menu. The upper section shows the same
functions seen in the previous menu.

The middle section of the menu (from a to p) shows a number of variables and input
parameters that are available for plotting. Note that options will only work if the
corresponding domain was included in the simulation. For example, res will not produce
plots using the option o CFD metrics unless the model has a CFD domain set-up and
enabled in the simulations. In general, options a weather to j casual gains are available in
most ESP-r exemplar models. This page will use these more common options to
demonstrate how res generates graphs, and how the options in the lower section (from >
Display to - exit menu) affect plot generation and the appearance of plots. Each of the
middle section options will be described in detail in the following chapters and pages.

465
48.1 Plot generation method
The graphing tool of res has a particular workflow to generate a plot, where the user:

• selects one or more variables and/or parameters for plotting,

• requests res to produce the plot using the option ! draw graph in the menu.

The process to select variables for plotting is explored below using some variables as
examples. Each variable available for selection is treated in detailed in the next pages of
this chapter.

48.2 Variable/Parameter selection method

When open for the first time, the parameter plot menu has a blank field below the option
p observed:temporal and above >Display to. This blank field indicates that no variable has
been selected so far. Once variables are selected, this field is replaced by option q edit
selection.

Left menu has no variables selected (see blank space above > Display to, while right menu
has variables selected for plotting

466
For demonstrations purposes, select the outdoor temperature for plotting using the
commands below.

a weather (to select climate variables for plotting. a new menu will open and show these
variables, see image below)
a dry bulb temperature (in the clm menu, where clm is the abbreviation used for climate
used in ESP-r. An asterisk appears on the left of the select variable)
- exit menu (to exit the clm menu and return to the parameter plot menu)

Once this variable has been selected, the q edit selection becomes available. Click on this
option (or press q) to open the Metric selection menu (see image below). This menu shows
the currently selected variables. and users can unselect variables by clicking on them (or
pressing the corresponding key on the keyboard). Select - exit and activate changes to
leave this menu and return to the parameter plot menu,

Menu showing selected variables for plotting - click on the variable to unselect it

Once a variable is selected, it is possible to plot the graph using the option ! draw graph.
The figure below is plotted.

467
 Example of parameter plot - outdoor air temperature (°C)

One more time, for demonstration purposes, select the air temperature inside the thermal
zones of this model using the following commands:

b temperatures (a new menu will open and show several options of temperature for
plotting, see image below)
a dry bulb (db) temp. (to select the indoor air temperature for all available thermal zones
. An asterisk appears on the left of the select variable)
- exit menu (to exit the temperature metrics menu and return to the parameter plot
menu)

468
Use the option q edit selection to inspect the updated list of available f selected for
plotting. (see image below with 3 new variables corresponding to the thermal zones in the
result dataset). Select - exit and activate changes to leave this menu and return to the
parameter plot menu.

Menu showing selected variables for plotting after new variable was added to the selection

Use the option ! draw graph redraw the graph and figure below is plotted.

469
 Example of parameter plot - outdoor air temperature and indoor temperature in three
thermal zones (°C)

The vertical axis range is automatically updated by res to handle the new dataset. Line styles
and colours (for lines and labels) are automatically assigned by res and cannot be modified
by the user.

It is possible to plot variables with different units in a single graph. For demonstration
purposes, select the energy demand for heating required by the thermal zones of this
model using the commands below:

h heat/cool/humidity (opens the Load choice menu, see image below)

a Sensible heating load (selects the variable and automatically returns to the previous
menu)

⚠ Upon selection of option a, the Load choice menu closes automatically instead of
showing the selected choice with an asterisk. The option - exit menu is not used in this
menu. The behaviour of menus in ESP-r is not always consistent, but it does not affect the
use of the program.

470
 Energy demand variables available for plotting

Refresh the graphical area to account for the new selected variable using ! draw graph.
The image now shows a secondary axis on the right side dedicated to the power values
related to the heating demand.

Example of parameter plot - various air temperatures (°C) and energy demand for heating
in three thermal zones (kW)

In case the number of variables plotted simultaneously compromises the readability, it is

possible to use the option q edit selection to remove some variables from the selection. In
the example in the image below, only three variables are kept in the selection.

471
 Menu showing selected variables for plotting after some variable were unselected

Use the option ! draw graph to refresh the graph, producing the image below.

Example of parameter plot after some variables were removed from the selection

✔ you can also use the option 4 building zones to only display results to a few particular
zones.

Use the option / clear selection to remove all variables from the selection. The option q
edit selection is no longer available on the menu, indicating that no variable is selected
for plotting. Leaving the parameter plot menu and returning to it has a similar effect.

48.3 Parameter plot controls

48.3.1 > Display to >>

472
Regular res users should not use this option. It is available for developers of res, as it writes
a text file with the instructions used by the graphic library to plot the graph.

The options available for "display to" are:

• screen (default), and

• file.

If > Display to >> is changed to file, the dialog box below is presented.

Dialog of file name for export plot instructions to a file

Once the user inputs a file name (or accepts the suggested one), the text feedback window
will indicate that the file has been open. The file is located in the cfg folder of the model.

Feedback text indicating the file was opened and graphics are now channelled to the file

From this point on, every time the option ! draw graph is used, res will produce the
requested graph in the graphical area of res, but it will also write the instructions for this
graph in the text file indicated by the user (the image below reproduces a sample of part
of this file).

473
 Fragment of a sample text file with plot instructions exported by res

When the option >Display to >> is used again, the file is closed (as indicated in the text
feedback area - see image below).

Feedback text indicating the file was closed

48.3.2 % data as:

When this option is selected, a dialog is presented with the three different modes res can
use when plotting data:

• as values (default, in the dialog below this corresponds to the option

"parameter"),
• integrated (function not working correctly on res), and
• parameter rate of change.

474
The default option indicates data will be plotted as they are in the result file, i.e. as time-
series of temperatures, energy demand, humidity, etc (see example below with heating
energy demand plotted using the option parameter).

Integrated is meant to provide results for energy over time. ESP-r does not calculate energy
(kWh), but instead it calculated the power (kW) required to keep the thermal zone at a
certain set-point. Energy results are calculated by res by multiplying power data available
in the result file by the length of the time step. This option, however, does not produce
clear graphs in res and it will not be exemplified here with an image.

Parameter rate of change plots the difference between values for consecutive time-steps
divided by the length of the time-step. This type of plot is exemplified in the second image
below where the times of maximum increase or decrease in power can be easily identified.
Note that the unit is kW/h, i.e. the variation in power (kW) per unit of time (h).

Plot using the parameter option for % data as

475
 Plot using the rate of change option for % data as

48.3.3 = axis scale

This option allows adjusting the vertical ranges of plots, as well as the resolution in the
horizontal axis, as exemplified in the images below.

Dialog for vertical axis range in temperature plots

Dialog for vertical axis range in power plots

Dialog for time resolution in the graph axis

48.3.4 " units >> normal

This option allows adjusting the unit for power plots and energy, switching from W or Wh
to kW or kWh.

476
⚠ This function does not seem to be working correctly and may freeze res when
activated, so its use is not recommended.

48.3.5 * label
This option allows:

• changing the plot title,

• adding custom text labels in any point of the plot.

When invoked, it will prompt the user to define a title for the plot (see image below).
Blank titles are not allowed.

Dialog with user-defined graph title

Once the title is provided, the dialog below is shown.

477
The user can choose cancel to return to the parameter plot menu; the plot title will be
automatically updated (see image below).

Graph with user-defined title

If the user selects add/edit in the previous dialog (Graph label options), a new dialog is
shown allowing the crating of custom text labels in the plot (see image below). The user
should enter the text, press ok, and then pick the point in the plot where the label should
be introduced. Blank labels are not allowed.

Error message if user-defined label is blank

In the example below, the custom label was placed close to the highest temperature
value.

478
 Graph with user-defined label and dialog for additional labels

It is possible to edit the text and position of previously created labels, and it is also
possible to clear all custom labels. In this case, it is necessary to force res to redraw the
graph (using ! draw graph).

This concludes the general functionalities of the parameter plot menu. The next pages
cover the variables available for plotting.

Graph: Parameter plot

479
49 Assessment period and display period
ESP-r is able to run simulation for multiple years in a single run, but most often it is
configured to run simulations with assessment period up to one calendar year, and in many
examples a much smaller period is used.

The section Module Options described how to control the output period for display on the
results Analyser. It is important to stress that the period covered in the simulation
(assessment period) is defined on the Project Manager or in the Integrated Simulator before
running the simulation. The figure below show the Project Manager Simulation controller
menu for the exemplar model (a simple > e ... multizone with convective heating &
basic control). This model is configured to simulate only one week in February (option g).

Using these settings produces results such as the figure below. This is the setting used in
most of the next sections to present the Results Analyser capabilities, as it makes easier to
observe daily patterns and discuss result analysis alternatives.

480
It is possible, however, to change the assessment period in the Project Manager Simulation
controller menu, to produce graphs for the whole year, as illustrated below. These graphs
are useful to observer seasonal patterns, and while they are not extensively used in the next
sections, all capabilities illustrated for a shorter time frame (a week) are also valid for a
whole year simulation.

481
50 Parameter plot: a weather
This menu shows options for plotting climate data used as boundary condition in the
simulation. The availability of each of these variables depends on the climate file.

Figures in this page were generated using the exemplar model a simple > a zone with
convective... and saving results level 4.

climate data for plotting

50.1 Options in the weather plot menu

50.1.1 a dry bulb temperature

example of outdoor air temperature plot

482
50.1.2 b diffuse horizontal solar (radiation)

example of diffuse solar radiation plot

50.1.3 c direct normal solar (radiation)

Note that res will adjust the y-axis range to the data set. In the previous plot (diffuse solar
radiation) the y-axis maximum value was 100 W.m-2.

example of direct normal solar radiation plot

50.1.4 d global horizontal solar (radiation)

483
✔ This and some other climatic parameters available on the clm metrics menu were
introduced in recent versions of res to handle new climatic files with more information
available than in traditional ESP-r models and climate files. The absence of data for some
climatic parameters does not compromise the quality of results.

message indicating this not available in the climate file

50.1.5 e wind speed

Note that the name and unit of the y-axis are not adjusted to this parameter (this is the
case for many other plots in res). Values for wind speed are shown in m.s-1.

example of wind speed plot

50.1.6 f wind direction

Values in degrees, where 0 is north and values increase clockwise.

484
 example of wind direction plot

When in doubt about ESP-r units, the contextual help may provide valuable information.
The help window show below, for example, is available on prj in the weather menu in
databases.

help window from prj describing weather files

The source code has also comments addressing this topic. The image below shows a
fragment of a file based on a search in the source code for the expression "wind
direction".

485
 fragment of the file data/climate/README available on the source code

50.1.7 g relative humidity

Relative humidity in %.

example of relative humidity plot

50.1.8 h total cloud cover

message indicating this not available in the climate file

50.1.9 i opaque cloud cover

486
 message indicating this not available in the climate file

50.1.10 j atmospheric pressure

message indicating this not available in the climate file

50.1.11 k sky illuminance

Sky illuminance in lux. This value is usually calculated by ESP-r, based on other weather
data.

example of sky illuminance plot

487
51 Parameter plot: b temperature
This menu shows options for plotting various temperature metrics available in ESP-r
results (or post-processed based on available results). The availability of each of these
variables depends on the settings of the model used in the simulation.

Figures in this page were generated using the exemplar model a simple > f ... multizone
with convective heating & basic control and saving results level 4, unless stated
differently for a given entry.

51.1 Temperature metrics

ESP-r thermal domain results can comprise several different types of temperature, as shown
in the menu below.

Temperature metrics menu

51.1.1
51.2 Options in the temperature plot menu
51.2.1 a dry bulb (db) temp.
Dry bulb temperature (often referred as db temperature) is the average air temperature
inside the zone. If the zone is filled with another fluid than as (such as water), the db
temperature will show the fluid temperature.

488
The term dry bulb makes reference to a time where people would a second thermometer
in contact a piece of fabric saturated with water to estimate the air relative humidity, based
on the so called "wet bulb". Wet bulb temperature is rarely used nowadays, but the dry
bulb term remains in use in energy simulation.

example of dry bulb temperature plot

51.2.2 b (db-ambient) temp.

This option shows the difference between the db temperature inside the thermal zones
and the ambient temperature showed in the weather file.

489
 example of temperature difference between zone and outdoor air temperature plot

51.2.3 c (db - other zone) temp.

This option shows the difference between the db temperature inside the thermal zones and
the temperature inside one of the thermal zones. If this option is selected, the user is asked
to select the "other zone" in the following menu.

example of temperature plot showing the difference between air temperature in each zone
and reference zone (in this case, the roof space)
490
51.2.4 d control point temp.
This option plots the temperature of the node defined in the control for each zone.

example of temperature plot for the control node in each zone

51.2.5 e resultant temp.

The result temperature indicates the particular case where the operative temperature has
convective and radiant weights both equal to 0.5. MRT is calculated based on area-
weighting of each surface. Operative temperature is a more adequate measure of thermal
comfort than air temperature. In the plot below, the result temperature is lower than the
air temperature because the indoor surface temperatures are lower than the air. This is
common in cases where heating is injected in the air node.

491
 example of resultant temperature plot (i.e. operative temperature with equal weights for
convection and radiation)

51.2.6 f zone mean radiant temp.

The Mean Radiant Temperature (MRT) is calculated for a generic location in the zone, based
on area-weighting of each surface. Note in the example below that the MRT is lower than
the air temperature, and that the resultant (operative) temperature is the average of both
air and MRT.

492
 example of mean radiant temperature plot

51.2.7 g sensor mean radiant temp.

This option plots MRT values for user-defined positions in the thermal zone. This is useful
to access the impact of colder/hotter surfaces in the MRT of nearby areas in the thermal
zone. User-defined locations must be defined in prj, and are called MRT sensors in ESP-r.
If the result file does not contain this locations and this graphing option is selected, the
following error message will appear:

message in of dry bulb temperature plot

The exemplar model used in the examples in this section was adapted to include a MRT
sensor. MRT sensors can be created prior to or after the simulation, as they are not used in
the simulation itself. res reads the information available about MRT sensors from the model
configuration files when it loads the result file. You can force res to reload the result using
option 1 of the Module menu on res.

The image below shows a MRT sensor representing a person standing close to the south
window.

example of MRT sensor size and position in a thermal zone

Select g sensor mean radiant temp.

493
The following message is displayed in the lower left corner or res:

dialog message for MRT sensor selection

The menu area will show the available MRT sensors in the model. In the case below, the
model has only one sensor.

menu for MRT sensor selection for plotting

The image below shows the MRT for the selected sensor.

example of MRT plot for a user-defined sensor

The graph below shows a comparison of the area-weighted MRT (f zone mean radiant
temp.) and the MRT for the user-defined sensor. The sensor shows a spike in the hour 70

494
due to solar gains heating up the window and heating up the window panel. The last hours
of the simulation show that the sensor readings are lower, due to long-wave radiation
losses to the sky during the night reducing the temperature of the window panel.

comparison of area-weighted and sensor MRT

MRT sensors in ESP-r do not take into account solar radiation reaching the sensor.

51.2.8 h dew point temp.

This option plots the dew point based on air temperature and humidity.

495
 example of dew point temperature plot

The image below shows the dew point temperature in relation to the air temperature and
relative humidity (plotted on the secondary axis). It shows that as the relative humidity
increases at periods of constant temperature, the dew point increases as well.

example of dew point temperature compared to dry bulb temperature and RH plot

51.2.9 i inside surface temp.

496
This option plots the temperature of one or more surfaces, considering the face inside the
zone. In the example below, two surfaces were selected for plotting.

example of surface selection menu

The image below shows the indoor surface temperature for the south wall and for the
south-facing glazing panel. Glass temperature is mostly lower due to the higher thermal
transmission, but it shows a peak in hour 35 due to solar radiation.

497
 example of indoor surface temperature plot

The image below shows the same surface temperatures in comparison to the indoor air
temperature. Air temperature is higher most times, as the zone heat injection is in the air
node. In the night, air temperature drops close to the south wall temperature due to heat
losses.

example of indoor surface temperature and dry bulb temperature plot

The image below shows the same surface temperatures in comparison to the indoor air
temperature and MRT. MRT is similar to the temperature of the south wall.

498
 example of indoor surface temperature plot, MRT and dry bulb temperature plot

51.2.10 j surf - dewpoint temp.

This option shows the difference between indoor temperature for selected surfaces and the
dew point of the zone. In the menu below, the glass panel of the window facing south is
selected.

The image below shows mostly positive values, indicating that the surface temperature is
in general above the dew point.

499
 example of difference between surface temperature and dew point plot

The graph below shows the surface temperature and the calculated dew point, where values
around hour 16 show that the surface temperature is below the dew point (i.e. the negative
values in the plot above). This indicates the likely occurrence of surface condensation at
this hour.

example of dew point and dry bulb temperature plot

500
51.2.11 k outside surface temp.
This option plots the temperature of one or more surfaces, considering the face outside the
zone.

While this option is named "outside", the face may be exposed to the outdoor environment,
it may be facing another zone, or it may have other settings, depending on the boundary
conditions defined in the model. Outside should not be consider equal to outdoor in this
context.

In the example below, two surfaces were selected for plotting. In the model, both surfaces
have EXTERIOR as boundary condition.

In the example below, glazing temperatures are often higher due to the heat escaping easily
from the building through the glass panel and heating it up in the process. When solar
radiation warms both surfaces (around hour 35), the opaque wall absorbs more radiation
than the transparent glazing panel, and consequently the wall temperature reaches higher
values.

501
 example of external surface temperature plot

The plot below compares surface temperatures with outdoor air temperature. It shows how
solar radiation increases outdoor surface temperatures at levels much higher than the
outdoor air.

example of external surface temperature compared to outdoor air temperature plot

502
The graph below shows weather data for this period, where the spike in direct solar
radiation reaching around 700 W.m-2 is noticeable.

example of external air temperature and direct solar radiation weather data plot

51.2.12 l constructions note temp.

This option plots temperature of nodes inside the component. This values are not stored
when simulation is carried out with level 4 result saving (the default option used in all
examples above). The image below shows the text feedback message in case the option l
constructions note temp. is used with results level different from 3.

message if result file is not suitable for intra-construction temperature plot

Results shown in this section are based on results save level 3.

The image below shows the menu for zone selection when l constructions note temp. is
invoked. The reception is selected.

503
 menu for zone selection

The menu below shows surfaces in the thermal zone reception.

menu for surface selection

Select the option a south extern_wall. Once you click/select one of the surface, the menu
disappears, i.e. the option - exit menu is not used in this menu.

A dialog is shown for the selection of the node inside the component to be plotted. The
following paragraphs and images provide information on how to select the node number
for this dialog.

504
 dialog for node selection for plotting

The help function provides valuable information to understand how nodes are numbered
in ESP-r. In a nutshell, each component has 3 nodes, one in the middle and one in the
interface with each surface.

It is useful to check the construction name in the surface attributes on prj, as shown in the
image below. The option b in the image shows that this surface used the construction
extern_wall.

Using this name, it is possible to check on the construction database the composition of
this construction, as shown in the image below. In this example, node 2 is located in the

505
middle of the brick layer, and node 3 in the interface between the brick and the glass
wool insulation.

Enter the number 2 in the dialog to plot temperature values for the node in the middle of
the brick layer. Exit the menu and draw the graph (see image below).

example of temperature plot for a node inside a building component

506
The image below shows the comparison between the outdoor surface temperature (i.e.
node 1) and the node number 2 placed in the middle of the brick. Both values are similar,
as expected. The surface temperature is higher when solar radiation reaches the wall, but it
is lower in most time-steps as the surface looses energy by convection and longwave
radiation.

example of temperature plot for two nodes, one on the surface and one inside a building
component

51.2.13 m sensor operative temp.

This option is similar to g sensor mean radiant temp. and requires MRT sensors. If the
result file does not contain MRT sensors, the following error message will appear:

warning regarding lack of MRT sensors

This option plots operative temperatures and can utilize local values for air temperature
from CFD if available. If not, the following warning is shown and air temperature values
for the zone are used in the calculation of operative temperatures.

507
 warning about lack of CFD data for local air temperature

The image below shows the operative temperature for the available sensor.

example of operative temperature plot for a MRT sensor

508
52 Parameter plot: c comfort metrics
This menu provides options to plot thermal comfort metrics based on post-processing
ESP-r results. Metrics are defined in international standards such as ISO 7730 and EN
15251.

Most options required additional elements in the model, such as mean radiant
temperature (MRT) sensors of CFD for air speed. In case CFD is available in the model, the
local air temperature is used in the analysis of a given point rather than the average air
temperature of the zone.

Figures illustrating most options of this menu were generated using the model created
using the tutorial Create MRT Sensor.

52.1 Options in the comfort metrics plot menu

52.1.1 a PMV
The Predicted Mean Vote for a particular MRT sensor position and radiant field is
calculated and plotted using this option. Once invoked, the user is required to provided
additional data necessary for comfort assessment.

The prompt below is dedicated to clothing level.

Additional information on clothing levels is provided using the help option [?].

Accept the default value of 0.7 clo corresponds to a winter conditions.

509
The following dialog is dedicated to the metabolic rate of occupants to be used in the
analysis of PMV. Select MET in the dialog below.

The Activity level dialog is shown in METs.

Additional information on clothing levels is provided using the help option [?].

Accept the default value of 1.546 MET corresponding to an activity level similar to
standing activity or cooking.

510
The following dialog is dedicated to the air velocity to be used in the analysis of PMV. If
CFD data is available, ESP-r adopts the local air velocity calculated by CFD, otherwise the
user must provide a value manually. Accept the default value of 0.1 corresponding to still
air.

The following dialog allows the selection of periods of the day for analysis. In spite of the
dialog, this option is not used in ESP-r graph plotting for PVM. Select any option.

The user is presented with a list of MRT sensors available in the model to be used in PMV
calculation. Select option a reception :sen_01 and select - exit menu.

The PMV selection is concluded, returning to the main Parameter plot menu with data
ready for plotting.

Select ! draw graph.

The graph shows values from -1.4 to -1.1 in the start of working hours. PMV improves and
reaches -0.5 once the heating system manages, after several hours, to warm-up the room.
The most comfortable weekday is the 3rd day of the simulation, where significant solar
gains raise the air and mean radiant temperature of the zone. As the heating system turns
off, the comfort level inside drops quickly.

511
Select / clear selection to reset the data set for plotting.

52.1.2 a PMV using SET

This option plots PMV using the standard effective temperature (SET), a much less
common approach for thermal comfort assessment.

If the user has already defined the comfort parameters (clothing and metabolic levels, and
air speed) for a previous plot, ESP-r prompts the user to accept the existing values (yes) or
redefine them (no). Select yes.

The plot of PMV using SET, shown in the figure below, is very similar to the previous one.

512
52.1.3 c PPD
The predicted Percentage of People Dissatisfied (PPD) in this option is related to the PVM
values calculated and shown in option a of the menu. the PPD concept is used to assess
other comfort aspects in the following options of the menu, and this one is dedicated to
the overall thermal balance level represented by PMV. The graph shows high PPD in the
start of working hours (between 30 and 50%). Comfort improves during the morning and
reaches the minimum value for PPD (5%) remaining stable until the heating system is turned
off at the end of the working-hours period. PPD increases in the evening/night (as the
heating system is off and the office is not occupied).

513
52.1.4 d heat-foot delta temperature
This option assess the air temperature difference between head and foot heights to
estimate local thermal discomfort due to temperature stratification. It requires CFD results
for the analysis.

52.1.5 e floor temperature

This option assess local thermal discomfort due to floor temperature. Once the option is
invoked, the user is prompt to select the surface representing the floor in the model.
Select the surface floor in the reception.

The figure below shows PPD results for thermal discomfort due to floor temperature. As in
previous graphs, PPD is higher in the beginning of the working-hours period and reduces
gradually during the day. The floor of this thermal zone has significant thermal mass and is
not heavily insolated, so its temperature does not reach quick and PPD never rarely reaches
lower levels (apart from the 3rd day of the simulation).

514
52.1.6 f warm/ cool ceiling (PPD)
This option assess local thermal discomfort related to radiant asymmetry due to ceiling
temperature warmed or colder than the surrounding environment. Once the option is
invoked, the user is prompt to select the MRT sensor to be used in the analysis.

The figure below shows results (only for occupied hours) with low percentage of
dissatisfaction.

The figure below shows the ceiling and floor temperatures, which have often just a few
degrees of difference, hence the absence of discomfort due to the ceiling temperature.
515
52.1.7 g radiant asymmetry (PPD)
This option provides tools to calculate local thermal discomfort due to radiant asymmetry
for each face of the MRT sensor. Once invoked, the user must define the surface of interest
for the analysis.

This nomenclature assumes that the MRT sensor was not rotated, so the South face of the
sensor is the one originally facing south when the sensor was created.

The figure below shows the percentage of dissatisfaction (between 0 and 1) for the south
of the sensor. This side of the sensor faces the window, and the MRT sensor is close to the
window, so higher values of local discomfort were expected.

516
The figure below shows the temperature of the window compared to the mean radiant
temperature of the zone, where it is noticeable that the window is consistently colder
(around 5°C) than the surrounding surfaces.

The figure below shows percentage of dissatisfaction due to radiant asymmetry the east
facing side of the MRT sensor. This side faces a insulated wall, with surface temperature
closer to surrounding temperatures, leading to a lower level of local thermal discomfort
when compared to the south facing side of the sensor.

517
52.1.8 h draught (PPD)
This option assess the thermal discomfort due air movement when particular combinations
of air speed and temperature are present. It requires CFD results for the analysis.

518
53 Parameter plot: d solar processes
The solar metric menu has 3 options:

Solar metric menu

In order to best explore these options, consider a model with 2 adjacent zones divided by
a glass panel, as shown in the image below. All exterior surfaces are opaque, apart from the
surface facing west in Zone1. Interior surfaces in Zone 2 have absorptivity equal to 0.22 (i.e.
they are painted white). Simulation is conducted for a summer week.

Model used to exemplify solar process

519
53.1 Options in the solar processes plot menu
53.1.1 a entering from outside
The first option in the solar processes menu plots the amount of solar radiation that enter
the thermal zone through transparent/translucent elements. The image below shows up to
4000 W entering Zone 1, with a clear pattern of diffuse solar radiation in the morning, and
a sharp increase at noon where direct solar radiation starts reaching the west façade.. No
solar radiation enters Zone 2 from outside (as all exterior surfaces are opaque in Zone 2).

Example of solar radiation entering from outside plot

53.1.2 b entering from adjacent

The image below shows the solar energy entering one zone and coming from an adjacent
one. Zone 2 receives significant amounts of radiation through the glazed partition from
Zone 1. The magnitude (up to 1000 W) is much lower than in the figure above (up to 4000
W), as most radiation is absorbed by opaque surfaces in Zone 1 and only a small portion
passed through the zone and reaches the internal partition.

None that Zone 1 also has a small amount of solar radiation coming from an adjacent zone.
This is due to the fact that white surfaces in Zone 2 reflect part of the incoming solar
radiation and these reflections cross the partition bring radiation back to Zone 1.

520
 Example of solar radiation entering from adjacent zone plot

For demonstration purposes, consider the same model with the indoor surface absorptivity
of opaque surfaces in Zone 2 changed to 0.99 (i.e. a black and almost perfect absorber).
The image below shows the simulation results where there is no solar radiation coming
from adjacent zones into Zone 1.

Example of solar radiation entering from adjacent zone plot

521
53.1.3 c absorbed in the zone
Option c in the solar metric menu shows the amount of solar radiation that is actually
absorbed by transparent and interior surfaces in the zone. The image below shows that the
absorbed radiation in Zone 1 is equal to the energy entering the zone, minus the radiation
transmitted to Zone 2, plus the energy returning from Zone 2. The energy absorbed in Zone
2 is equal to the energy entering from adjacent zone, minus the energy reflected by the
white surfaces that returns to Zone 1.

Example of solar radiation absorbed in the zone plot

522
54 Parameter plot: f zone flux
This menu shows options for plotting various zone fluxes available in ESP-r results (or
post-processed based on available results). Zone fluxes account for heat gains/losses
related to the fluid node inside the zone.

Figures in this page were generated using the exemplar model a simple > f ... multizone
with convective heating & basic control and saving results level 4, unless stated
differently for a given entry.

54.1 Zone flux metrics

ESP-r thermal domain results provide break down values for various heat flow paths, as
shown in the menu below. Some of these values are directly related to input provided by
the user (such as infiltration, ventilation and casual gains due to scheduled air change
rates and gains imposed in the model). Other fluxes are post-processed using ESP-r
results.

54.2 Options in the zone flux plot menu

54.2.1 a infiltration
Infiltration losses are related to air change imposed in the thermal domain model using
schedules. In this example, temperatures inside the building are higher than outdoors, so
Reception and Office show losses over the simulated week (around 200W and 50W
respectively), while there are no losses in the Roof zone.

523
54.2.2 b ventilation
Ventilation fluxes are related to imposed flow rates of air coming from outside or from
another zone. In this model, the Office and Reception zones have ventilation air flow
related to air movement through the door. The Office shows gains (up to 50W) as it is
colder than the Reception during the simulated period, while the Reception shows losses
varying from 0 to 100W during most of the simulation. Losses by ventilation are higher
when the Reception temperature increases during the day due to solar gains. There is no
imposed air flow in the Roof zone.

524
54.2.3 c occupant casual gain
Occupant casual gains are imposed using schedules. In this model, the Reception is
significantly bigger than the Office, and the imposed occupancy is consequently higher
(gains up to 500W in the Reception and 150W in the Office). There are no occupants in
the Roof zone.

525
54.2.4 d lighting casual gain
Lighting gains are substantially higher in the Roof zone (up to 700W), due to the use of
suspended ceiling and lighting fixtures rejecting heat into the attic space. This model has
an old lighting system with high energy consumption (and heat gains) for lighting. A
small portion of gains is imposed in the Reception and Office zones.

526
54.2.5 e small power casual gain
Small power is imposed in the Reception to account for electric devices used in the zone.
Gains from 600 to 1000W are imposed 24h in this zone, even during weekends.

527
54.2.6 f other casual gain
There are no other casual gains in this model.

54.2.7 g controlled casual gain

There are no controlled casual gains in this model.

54.2.8 h opaq surf. conv. @extrn

This option shows losses in all zones through convection between the indoor air and the
opaque surfaces facing the external environment. This is expected, as the air inside the
building is warmer than the outdoor environment, leading to warm air losing energy by
convection to colder surfaces. The losses are higher through the Reception (up to 400W)
due to the large areas and higher temperatures. The unheated Roof zone shows losses as
high as the Office (up to 250W).

Graphs dedicated to convection at internal surfaces will be heavily affected by solar

radiation, as solar energy entering the room is absorbed at the internal surface node,
leading in some cases to convection gains even during the winter.

54.2.9 i opaq surf. conv. @partns

This option shows convection losses/gains between the zone air node and surfaces facing
other zones (internal partitions). The Reception and Office mostly show losses (up to
500W), while the Roof shows gains in part of the time. These results are consistent with

528
the fact the Roof is unheated, so heat will flow from warm zones (Reception and Office) to
the colder Roof through the internal partition (ceiling).

54.2.10 j tran surf. conv. @extrn

This option shows losses in all zones through convection between the indoor air and the
transparent surfaces facing the external environment. The larger windows at the Reception
show losses around 150W, while losses at the Office are much smaller.

Peaks of gains around hours 60 and 160 are related to incoming solar radiation being
absorbed by the glass and released to the indoor environment by convection.

529
54.2.11 k tran surf. conv. @partns
There are no transparent partitions in this model.

54.2.12 l total surf conv

Total convection between the indoor node and inside faces of building components is
shown below. These indicates losses around 1000W at the reception during the day,
consistent with the capacity of the heating system assigned for this model.

530
531
55 Parameter plot: g surface flux
Surface fluxes provide details about energy flow paths for every surface of every zone in
the model.

55.1 Examples on this page

Figures in this page were generated using the exemplar model a simple > f ... multizone
with convective heating & basic control and saving results level 4, unless stated
differently for a given entry.

All images were generated for the zone Reception, using the surface a south.

Graphs in this page are shown in W/m2.

55.2 surface fluxes menu

The surface fluxes menu shows the several heat flow mechanisms calculated by ESP-r for
the surfaces in the model. Data is provided for the node facing the interior part of the
thermal zone (inside) and for the node in the opposite side of the construction (other fc).
The other face may be exposed, for example, to the outdoor environment, or to another
zone. The boundary condition set in the model for each surface defines the sort of heat
fluxes available for the other face.

532
55.3 Options in the surface flux plot menu
55.3.1 a conduction (inside)
The figure below show heat conduction between the surface node facing the indoor
environment and the next node inside the construction. This simulation shows results for
winter conditions, so the inside node loses energy by conduction to the next node (as
energy is flowing from the inside to the outside environment). Losses are higher during the
day when the heating system is in operation. During the night the temperature inside the
zone drops quickly, reducing the temperature of the inside face node in this construction,
reducing losses. In some points in time, the fluxes is positive, indicating that the inside face
node is drawing energy from inside the construction by conduction.

⚠ Results are shown in W/m2 (in spite of the legend in the graph showing W in some
cases, as in the example below).

533
55.3.2 b convection (inside)
This figure shows the convective flux between the inside node of the construction and the
fluid (usually air) inside the zone. The positive flux during the day indicates the node gains
energy by convection (as expected, as the air is warmer than the wall due to the heat
injection in the air node by the heating system). During the night air and surface node
quickly reach equilibrium and the convective losses are much reduced.

534
The figure below shows surface and air temperatures, where it is noticeable that the air is
most times warmer than the surface, hence the positive convection flux shown in the
previous figure. There are two brief windows of time, around hour 72 and at the end of the
simulation, where the air is colder than the surface; these periods are see in the figure below
where the convective flux becomes negative and comes close to -0.5 W.

535
55.3.3 c LW radiation (inside)
The figure below shows the flux by longwave radiation between the inside node of the
construction and the inside nodes of surrounding surfaces in the thermal zone. The flux is
positive most of the time, as internal partitions and the floor will usually have higher surface
temperatures than this external wall. The flux is only negative during the periods indicated
in the convection graph around hour 72 and at the end of the simulation, as higher surface
temperatures will likely increase losses by convection and also by long wave radiation. The
emissivity of the internal surface, as defined in the Project Manager, will affect all longwave
radiation fluxes.

The image below shows the surface temperature of the inside node compared to the Mean
Radiant Temperature (MRT) of the zone. The MRT shows the area-weighted surface
temperature values of all surfaces in the zone (including the south wall used in all plots of
this section). The difference between these lines is proportional to the flux shown above, as
expected, with peaks around hours 60 and 160.

536
55.3.4 d SW radiation (inside)
The figure below shows the Shortwave (SW) radiation, i.e. solar radiation, absorbed by the
inside node of the surface. This is due to solar radiation coming through the windows and
being redistributed to the inside nodes of several surfaces of the zone. There are peaks in
solar radiation gains around hours 60 and 160, which explain the increase in surface
temperature at these points in time, consequently leading to an increase in convection and
longwave radiation losses.

537
The way ESP-r distributes solar radiation entering the zone varies depending on model
settings. In this model, there is no detailed calculation regarding which surface will receive
solar radiation based on solar position and incidence angle, and the incoming radiation is
usually the same per unit of area, as shown in the figure below with identical SW fluxes for
inside nodes of four different walls. The use of insolation calculations can be enabled on
the Project Manager if more detailed calculation is required.

55.3.5 e radiant casual occup

Casual gains, such as occupants, equipment, and others, inject heat in nodes of the thermal
zone. The following graphs are dedicated to the radiant fraction of these gains, which is
injected directly at the inside node of the surface to account for longwave radiation released
by people and equipment and absorbed by surfaces. The image below shows gains in
(W/m2) related to occupant gains at the inside node of the surface. These gains match the
profile of casual gains (with gains during the day and no gains at night nor weekends). The
magnitude is small compared to other fluxes as casual gains in this model are small and are
distributed throughout all surfaces of the zone.

538
55.3.6 f radiant casual light
The figure below shows casual gains due to lighting at the inside node of the surface.

539
55.3.7 g radiant causal other
The figure below shows radiant fluxes due to casual gains described in the model using
the field "other".

55.3.8 i contrld casual gains

There are no controlled casual gains in this model.

55.3.9 j heat storage (inside)

This option does not seem to be working properly, as it does not show any variation in
the stored energy, as seen in the figure below.

540
The previous figure should show variation of stored energy in line with changes in the
node temperature, as shown in the next figure.

55.3.10 k plant inj/ext (inside)

In some models, heating and cooling can be injected or extracted directly to/from the
surface node. This is the case of buildings with floor heating or with thermally activated
building elements. There are no components like this in this model, so there is no plant
injection of extraction at the inside node of the surface.

55.3.11 l conduction (other face)

541
This and the next fields of the surface flux menu are dedicated to the other face of the
surface, which in the case of the South wall of the Reception is facing the outdoor
environment. Some surface may face another zone, or have fixed imposed boundary
conditions. In any of these cases, the "other face" will provide values of surface fluxes for
node placed in the opposite side of the construction when compared to the inside node.

In the figure below the conduction losses/gains between the external node and its adjacent
node towards the inner part of the wall (the grey line at load 0.00 was not plotted by ESP-
r and is provided here for clarity). The flux shows mostly positive fluxes, as the interior part
of the building is being heated and energy is flowing from the node inside the wall to the
node facing the external environment. There are short internals were the flux is negative,
as the wall gains energy sue to solar radiation, leading to an increase in temperature that
is propagated to the inner parts of the wall. In the periods around hours 60 and 160, solar
gains at the external node of the wall will lead to rapid temperature increase, which drives
losses by conduction (negative values) from the outer node to the inner parts of the wall.
In the following hours, as solar radiation drops, the warmer inner node of the wall starts
releasing energy by conduction back to the outer node, leading to the positive spikes in
the flux seen in the figure.

55.3.12 m convection (other face)

The figure below shows convective losses/gains from the external node of the wall to the
outdoor air. During most of the time, this flux is positive and shows small fluctuations
(due to node temperature, outdoor air temperature, and wind speed and direction).

542
Two peaks in losses are seen in the figure above at the points in time where solar radiation
heats up the outer node of the wall, increasing the temperature gradient between wall
surface and air, consequently leading to higher convective losses. The figure below shows
the temperature of the external node of the surface compared to the outdoor (ambient)
air, where the temperature difference (figure below) can be directly correlated to the
increase in convective losses (figure above).

543
55.3.13 n long wave > buildings
The figure below shows longwave radiation fluxes between the external node of the wall
and surrounding buildings. These surrounding buildings are not explicitly described in the
model. Their temperature is inferred by ESP-r, and the view factor between surface and
surrounding buildings is defined in the context menu of the Project Manager. The emissivity
of the external surface, as defined in the Project Manager, will affect all longwave radiation
fluxes. Results below indicate negligible flux, apart from a surge in losses when there is an
increase in the temperature of the external node of the surface.

55.3.14 o long wave >sky

The figure below shows longwave radiation fluxes between the external node of the wall
and sky, Sky temperature is estimated by ESP-r and the view factor and the view factor
between surface and sky is defined in the context menu of the Project Manager. The figure
shows that in most of the time there are constant losses around 20 W/m 2, the most
significant losses of this node.

544
55.3.15 p long wave > ground
The figure below shows longwave radiation fluxes between the external node of the wall
and ground, Ground temperature is estimated by ESP-r and the view factor and the view
factor between surface and the ground is defined in the context menu of the Project
Manager. The figure shows small losses by radiation to the ground during most of the
simulated period, apart from the increase in losses similar to the ones seen in previous
graphs.

545
55.3.16 q SW rad abs (other fc)
The figure below shows the amount of shortwave (solar) radiation absorbed by the
external node of the wall. The peak in solar gains matches the timing seen in previous
graphs.

55.3.17 r SW rad incid (other fc)

The figure below shows the incident shortwave (solar) radiation at the external node of
the wall. Part of the incident solar radiation will be absorbed (previous graph), while part
will be reflected depending on the absorptivity of the material defined in the Project
Manager.

546
55.3.18 s heat storage (other fc)
Heat storage results for the South surface of the Reception are shown below for the
external node. This node shows significant fluctuation in the thermal energy stored in the
layer at the points where solar radiation enters the node. Results, however, show an
unexpected pattern, with a reduction of energy stored in the node when solar radiation
reaches it. The graph below is heavily influenced by a feature of ESP-r called time-step
averaging. This feature is suitable for most calculations and results, but it shows
inadequate behavior when the quantity of interest is the energy stored in a given node at
a particular point in time.

547
In order to assess the energy stored in the outer node of the wall, it is necessary to run a
simulation disabling time-step average (see tutorial).

The image below shows results for the same node without time-step averaging. Results
are in line with expectations, with an increase in energy stored as solar radiation reaches
the node, followed by a decrease when longwave radiation losses reduce the node
temperature.

548
56 Parameter plot: h heat/cool/humidity
The Load choice menu is dedicated to the energy injected or extracted from the thermal
zone, base on controls defined in the Project Manager. It provides several types of plot
related to heating, cooling (sensible and latent), as well as energy demand related to
humidity control in the zone. These options do not consider the efficiency of the heating,
cooling, dehumidification, and humidification systems.

56.1 Examples on this page

Figures on this page were generated using the exemplar model a simple > e ...
multizone with convective heating & basic control and saving results level 4. The
exemplar model in ESP-r does not include, cooling nor humidity control. For the purpose
of this section, the control on weekdays was modified as shown in the image below, with
a cooling setpoint of 22C (with 1000W of cooling capacity), and humidity controlled
between 50 and 60% (with a capacity of 30 g/s). These values are arbitrary and were
adopted only for demonstration purposes.

549
Most images were generated for the zone Reception, and in a few cases the plot also
includes values for the Office zone.

56.2 Options in the heat/cool/humidity plot menu

56.2.1 a Sensible heating load
As the temperature outdoor is low during the simulation period, the figure below shows
heating injection in the air node of the zone over the 5 weekdays of this simulation (the
control is not used during weekends, hence the absence of load on the last two days of the
simulation). When the heating system becomes active in the morning, the heating capacity
goes to the maximum value (1kW) to heat-up the zone, and the heating power is reduced
in the following hours as the room becomes warm and solar gains increase. In all 5 days,
the heating injection is not necessary during the middle of the day (due to solar gains), and
resume in the last working hours of the day. Heating is off during night time. On the third
day, solar gains are significantly higher (up to 3kW, as shown in previous sections) and there
is no need for heat injection in the last working hours of the day.

The figure below shows the heat injection plotted with the air temperature of the zone. The
increase in temperature is seeing over the first working hours of the day, where energy is
injected until the air node reaches 20C. Temperature remains stable around 20C in most
working days apart from the 3rd day where the temperature is constant at 22C (the cooling
setpoint used in this model). This indicates that solar gains pushed the temperature above
the cooling setpoint and this system was activated to extract energy from the node,
therefore there is no heating load at the end of the working day.

550
56.2.2 b Sensible cooling load
The figure below shows energy extracted (negative values) from the air node by the cooling
system. The cooling system is only active during a few hours of the 3rd day of the simulation,
as expected based on the graph above. The cooling system never reaches the maximum
capacity of 1 kW, only reaching a peak of 0.46 kW.

551
The figure below shows the cooling load in combination with the air node temperature and
solar gains in the zone. The graph shows small solar gains in all working days (likely due to
overcast sky). On the day where cooling is needed, there is a significant increase in solar
gains.

56.2.3 c Dehumidification load

This option is not functional on the V13.3.16 of ESP-r, and shows a flat line of zero load, in
spite humidity results showing the humidity control is operational and keeps humidity
between 50% and 60% during working hours.

552
The actual dehumidification load can be plotted using an alternative approach. Select for
plotting only the thermal zone of interest, and use option j Aggregate dehumidification
load, of the load choice menu produces results as shown in the figure below. The graph
shows that as humidity reaches the set-point of 60% (due to latent casual gains for
occupancy - see tutorial) the dehumidification system is activated, extracting moisture from
the air node, i.e. extracting energy from the node, hence the negative values. This occurs in
most days during the afternoon period, as the air starts the working-hours period quite dry,
and only reaches higher values due to moisture release over several hours.

553
56.2.4 d Humidification load
The humidification load option presents the same issues discussed in the previous section
(flat line at 0 kW even if the system is active). The figure below was plotted using the k
Aggregate humidification load option. The air node starts the working-hours period with
low relative humidity (as air infiltration during the night removes the moist air from the
zone replacing it by dry outdoor air). This triggers the humidification system in the first
hours of the day, injecting moisture until the RH set-point is reached. Moisture injection
increases the energy in the air node, hence the positive values.

56.2.5 e Sensible H + C loads

The figure below shows the combined sensible heating and cooling loads for the zone. It is
the superimposition of graphs generated using options a and b of the load menu described
in the beginning of this section.

554
56.2.6 f Latent H + C loads
The figure below shows the combined latent heating and cooling loads for the zone. It is
the superimposition of graphs generated using options c and d of the load menu described
in the beginning of this section.

555
56.2.7 g All Sensible + latent loads
The figure below shows the combined sensible and latent loads for heating and cooling
for the zone. It is the superimposition of graphs generated using options a, b c, and d of
the load menu described in the beginning of this section.

56.2.8 h Aggregated heating load

The figure below shows the combined sensible heating of all zone. It is the superimposition
of graphs generated using options a for each zone of the model. In the figure, loads for the
Office and Reception are included.

556
In the figure below, the heating load for the Office and Reception are plotted to indicate
that in this tutorial how the aggregated load is the combination of the two curves. Each
curve has peak at 1kW, while in the previous graph the peak is 2kW.

557
56.2.9 i Aggregate cooling load
The figure below shows the combined sensible cooling of all zone. It is the superimposition
of graphs generated using options b for each zone of the model. In the figure, loads for the
Office and Reception are included.

56.2.10 j Aggregate dehumidification load

The figure below shows the combined dehumidification load of all zone. It is the
superimposition of graphs generated using options c for each zone of the model. In the
figure, loads for the Office and Reception are included.

558
56.2.11 k Aggregate humidification load
The figure below shows the combined humidification load of all zone. It is the
superimposition of graphs generated using options d for each zone of the model. In the
figure, loads for the Office and Reception are included.

559
57 Parameter plot: i zone RH
This option plots graphs with relative humidity values of the air node of the zone. The
example below was generated using the exemplar model a simple > f ... multizone with
convective heating & basic control and saving results level 4 (the default saving
level). The figure shows the variation on relative humidity for the Reception, with daily
cycles between 30 and 70%.

The increase in relative humidity is due to the latent casual gain due to occupancy defined
in the model and shown in the figure below. During the first working hours of the day, the
relative humidity drops as the air is warmed up by the heating system. As the air reaches a
constant temperature around 20C, moisture gradually builds-up increasing the relative
humidity of the air node.

560
561
58 Parameter plot: j casual gains
The Casual gain metric options menu plots casual gains in similar to plots created using
the zone flux menu.

58.1 Options in the casual gains plot menu

58.1.1 a all gains
The figure below shows the combine gains for each zone.

562
58.1.2 b convective portion
The figure below shows the convective fraction of casual gains added to the air node of
each zone.

58.1.3 c radiant portion

The figure below shows the total radiant fraction of casual gains (added to the inside
surface nodes of surfaces) for each zone.

563
58.1.4 d occupants
The figure below shows occupants gains for each zone.

564
58.1.5 e lighting
The figure below shows lighting gains for each zone.

58.1.6 f small power

The figure below shows small power gains for each zone.

565
58.1.7 g controlled gains
There are no controlled gains in this exemplar model.

58.1.8 h controlled fraction

There are no controlled gains in this exemplar model.

566
59 Parameter plot: m renewable/adv. comp.
This option produces graphs related to embedded renewable energy generation in the
thermal model.

Figures illustrating this section were produced using the exemplar model b technical
features >l ... with PV cells embedded in spandrel, where PV cells placed under the
window of the zone manager_a convert part of the incoming solar radiation into
electricity.

When the option m renewable/adv. comp. is used, the following prompt will be
presented. Select heat/power output.

The figure below shows the energy produced by the PV panel, with peaks on the 3rd and
last days of the simulation. This is consistent with the solar radiation data for this location,
which shows mostly overcast days with no direct solar radiation.

567
568
Other types of graphs

569
60 Graph: Intra-construction temperature
These functionalities are dedicated to plot cross sections with temperature of constructions
used in the surfaces of the ESP-r model. Figures in this page were generated using the
exemplar model a simple > f ... multizone with convective heating & basic control
and saving results level 3,

The image below shows the main menu for intra-construction temperature.

intra-construction temperature menu

60.1 Options in the Intra-construction temperature plot menu

60.1.1 a Xsection temperatures
Upon selection, this option prompts the user to select the zone and surface for plotting, as
shown in the images below.

570
 surface selection menu

As in other menus on res, the surface selection menu closes as soon as one surface is
selected. In the examples below, surface a south extern_wall is used. Note that this menu
also shows the composition of the wall, as this information is relevant to understand the
plots generated.

Once a surface is selected, a dialog presents the two plotting modes: cumulative and
animated.

plotting modes for intra-temperature cross section plots

For either mode, the user should then select the speed for plotting.

plotting speed for intra-temperature cross section plots

The example below shows the cumulative section plot in normal speed. The graph
indicates the indoor side of the plot (reception, on the right) and the conditions on the
other side of the component (outside, on the left). Each grey rectangle represents one layer
in the construction, while the white space between rectangles represents an air gap. Values
571
in the x-axis are in millimeters. In the example below, the layers are: brick (on the left),
insulation, air gap, and concrete block (on the right). The plot shows the temperature across
the component in each time step.

example of cumulative temperature cross plot

res does not capture the animation (examples here were done using a screen recorder
app). res does not show the plot in loop, as shown on this page. Once the plot is concluded,
res will show the image below.

572
 plotting of cumulative temperature cross plot

The example below shows the cumulative plot in normal speed.

The example below shows the animate data display mode in normal speed. These graphs
demonstrate the dynamic nature of heat flow in complex energy systems, and the severe
limitation of steady-state calculations based on U-values.

573
 plotting of animated temperature cross plot

60.1.2 b graph interstitial

This option plots a cross-section of the chosen component in line with ISO 13788 (aka
'Glaser method'). The plot shows moisture variation in the cross section (as vapour pressure,
in mbar) for a single time-step chosen by the user. Calculation is carried out by res in
steady-state and liquid transfer is not taken into account. The plot also includes the
saturation vapour pressure based on the temperature of each node inside the component.

Once the option b graph interstitial is selected, the user is prompted to confirm values of
vapour resistivity for the materials of each layer in the construction. Values are suggested
in mega Newton seconds per gram metre (MNsg-1m-1 ), and res retrieves these values from
the model material database, as in the example below.

dialog for material vapour resistivity

After confirming the suggested material properties, the user should select the time-step for
plotting, as in the image below.

574
 dialog for time selection for plotting

The example below shows resulting plot, indicating that the vapour pressure across the
component is always below the saturation for this time-step, and interstitial condensation
is, according to this assessment method, unlikely at this time.

glaser method plot for a particular time-step

The user can select other conditions for new plots (see dialog options in the image above).
Previous plots of time series temperature indicate more sensitive times for analysis, where
external surface temperature is below the dew point, for example.

dialog for time selection for plotting

The example below shows a significative condensation risk in the brick and insulation layers.

575
 glaser method plot for a particular time-step with severe interstitial condensation risk

576
61 Graph: 3D profile
3D profiles are dedicated to plots of of parameter variation (z-axis) in different days of the
year (y-axis) and in different time-steps (x-axis). The 3D profile menu allows the selection
of variables.

One a variable is selected, use ! draw 3d plot to generate the image.

This tutorial uses the exemplar model a simple > f ... multizone with convective
heating & basic control. The example below shows a 3D profile of the Reception dry
bulb temperature over the simulated period of one week. The duration of the simulation
greatly impact on the size of the y-axis of 3D profiles.

577
The example below shows a 3D profile of the outdoor temperature.

The example below shows the 3D profile of heating fluxes. This profile is not readable on
this form, but this can be adjusted to a extent.

578
Select the option 2 scale data. Enter a scale factor of 0.02 in the dialog.

Select ! draw 3d plot. The image is adjusted to a more readable plot, as exemplified
below.

The image below shows a 3D profile of heat flux due to infiltration. the plot shows
negative values on the z-axis, as infiltration leads to energy losses in this particular
simulation.
579
580
62 Graph: frequency histogram
The Results Analyser is able to plot histograms and cumulative frequency plots of most
variables discussed in previous section, and listed in the Frequency histogram menu.

These capabilities are demonstrated in this tutorial for one particular variable.

This tutorial uses the exemplar model a simple > f ... multizone with convective
heating & basic control.

Select a weather

The sub-menu with weather variables becomes available for variable selection.

Select a dry bulb temperature

581
Select yes when prompted regarding the bin width to be used in plot.

Once the variable is selected, it is necessary to indicated the kind of plot.

62.1.1 Types of frequency plots

The Frequency analysis menu shows the different kinds of plots available. Each one will be
exemplified in the following sections.

62.2 Options in the frequency histogram plot menu

62.2.1 a frequency graph
After selecting a frequency graph, select distribution (hits).

The plot below is generated, with absolute frequencies on the primary y-axis and relative
frequencies on the secondary y-axis.
582
62.2.2 b cumulative graph
Select the variable for plot again, and then select for plotting b cumulative graph. Select
standard order.

Select distribution (hits)

The cumulative plot below is generated.

583
62.2.3 c summary table
This option is generate frequency tables in the text feedback area, as the one below
exemplifying external dry bulb temperature frequencies. No plot is generated.

584
62.2.4 d frequency graph+table and e cumulative frequency graph+table
These options combines frequency table and plots (in the example below, option d was
used to produce a table and histogram).

Other types of graphs

585
63 Graph: variable v. variable
This option generates scatter plots where points represent values of two variables for
each given time step. The variables for selection are available in the Var.vs.Var menu.

The example below shows results for g mean radiant tempr (on the x-axis) versus 5
direct solar (reception floor) (on the y-axis).

586
587
64 Graph: network flows
This section addresses results of fluid flow networks, and contaminant. These results are
available only in models where these features were enabled and configured. The presence
of a fluid network is indicated by the in the Project Manager (see image below) by:

• highlighted text in the Features field, on the upper right corner of the graphic
window, and by
• the word "defined" after option "f network flows", in the Browse/edit/simulate
menu.

Modelling of contaminant concentration is indicated by "defined" on option "h

contaminants". Contaminant modelling is an optional additional feature to fluid flow
results and cannot exist without fluid results.

This tutorial uses results from the model b technical features > g ... with CO2 tracking
(open windows), using the simulation pre-sets included in the exemplar (see image below).
The name and location of the result file for the thermal domain is defined in option "h zone
results" of the Simulation controller of the Project Manager (in the image, the name is not
fully display as it is too long to fit in the menu width). Name and location of the fluid flow
result file is defined in option "i flow results" (also not fully shown in the image below). If
contaminant modelling is defined, its results are stored in the same file used for fluid flow
results.

588
64.1 Opening fluid flow results
On the Result Analyser, under the menu Graphing options, select f network flows.

The dialog area requests the name of the fluid flow result file. If simulation pre-set were
defined in the Project Manager, the name file will be retrieved and filled automatically by
the Results Analyser. Press ok.

589
If the file is successfully opened, the time series plot should become available.

64.2 Time series plot menu

The menu below shows time series available for plotting. The mechanism for plotting and
options are identical to the described in previous sections of this guide.

64.3 Options in the network flows plot menu

64.3.1 a ambient temperature
This option plots the external air dry bulb temperature, as provided by the weather file.

590
64.3.2 b wind speed
This option plots the wind speed, as provided by the weather file.

64.3.3 c wind direction

This option plots the wind direction, as provided by the weather file.

591
64.3.4 d ambient RH
This option plots the external air relative humidity, as provided by the weather file.

64.3.5 e press @ node

This and following sections provide fluid flow results.

592
This option plots the pressure at any node of the network. This is the mean pressure at the
node, and does not include pressure variation at a given component due to stack effect.

Upon selection this option, the Result Analyser shows the Node select menu (see image
below). This network has six nodes. Select nodes a manager_a and corridor for plotting
and press - exit menu.

Select ! draw graph to generate the image below. These are the pressures calculated for
the two nodes, based on the boundary conditions and features of the network defined for
this model. The pressure difference is quite small, so it may be useful to change the scale
of the Pressure axis.

Select = set axis scale. Enter the values as in the image below.

593
For the horizontal axis, select default.

The fluctuation in the graph shows the impact of wind speed and direction variations
resulting in variation in indoor nodes of the network. In many points, pressure is similar in
both nodes, so it is expected that the flow rate will be small at these points in time. Flow
rates are explored in several sections below. The graph shows pressure higher in
magnitude at the corridor around hours 27 to 37, when compared to the manager, hence
the flow rate is likely to be from the manager to the corridor.

Select / clear all selections

Select e press @ node, and select the three boundary nodes, as in the image below.

594
The plot below shows significantly higher suction (negative pressure) at the south
boundary node (in yellow) when compared to the other nodes. This is consistent with the
previous graph which indicated air moving from the corridor (linked to west and east
boundaries) to the manager (linked to the south boundary).

64.3.6 f press diff @ conn

This option plots the pressure difference across connections at the network. Once
invoked, this option shows the Connection selection menu 9see image below). For this
tutorial select options c and e.

595
The plot below shows the pressure difference across the selected components, with nearly
identical curves, indicating both connections are strongly linked and pressures variations
propagate from one to the other. The pressure drop across the large connection between
manager_a and corridor shows a small pressure difference. By conservation of mass the
same amount of air passes through the opening from manager_a to the externa south node
shows (flow through cracks is negligible in this model). The smaller opening to the outside
is counterbalanced by a much higher pressure difference to achieve the same flow rate.

Select / clear all selections

596
Select f press diff @ conn, and select the three main boundary node connections, as in
the image below.

As in the previous section, the south connection shows higher magnitude negative
pressure, likely driving the flow from other connections.

Adjust the graph scale by selecting = set axis scale and entering the values suggested
below.

Select default for the horizontal graph division.

597
The graph is updated using the new scale. The peak in the east boundary from hours 27
to 37 becomes more noticeable.

64.3.7 g stack pres @ conn

This option plots the pressure due to stack effect at selected connections. Select a
south_ext -> manager_a via crack.

598
The graph shows a high pressure difference when compared to previous graphs,
highlighting the importance of stack effects on flow rates for this particular simulation.

64.3.8 h node temperature

This option plots temperature at nodes. These values are boundary conditions for the
fluid flow network, and are imposed every time-step based on results from the thermal
domain or values from the weather file. For this tutorial, select options a and d.

The image below shows the dry bulb air temperature of selected nodes, which mirrors the
outdoor temperature variation, as this model does not have heating controls.

599
64.3.9 i mass flow rate
This option provides facilities to plot mass flow rates at several points of the network.
upon selection, The image below shows the five available options for mass flow rate
plotting.

Select a individual connections. Different from other menus, there is no need to select
"exit menu", and the Result Analyser reacts as soon as an option is selected in the menu
below.

A list of connections is shown. Select option a.

600
The image below shows the rapid fluctuation of mass flow rate through the selected
crack. Values on the y-axis show values of small magnitude.

Select:

i mass flow rate

a individual connections.

Select option c as in the image below.

601
The graph with both lines put into perspective the fluctuations seen in the previous plot.
As flow rate through the window is substantially higher, the flow rate through the crack
appears now as a flat line. As expected, based on previous graphs, most of the flow rate
through the window is negative, i.e. air leaves the manager_a zone through this opening.
This pattern is only modified during brief periods, such as between hours 27 and 37.

Select:

/ clear all selections

i mass flow rate
c total entering node (as in the image below)

602
 .

Select the manager_a zone.

The plot below combines all openings of the manager_a zone.

64.3.10 j volume flow rate

The option shows the same plots described in i mass flow rate, but using volume. The
only difference is the dialog to select the unit for plotting, as in the image below.

64.3.11 k air changes

603
The option shows the same plots described in i mass flow rate and plot results in air changes
per hour (i.e. volume flow rate divided by the zone volume as defined in the model
description in the Project Manager). The name of the y-axis is plotted as Misc.
(miscellaneous, a term used in ESP-r whenever the unit and axis name has not been
specified in the source code).

64.3.12 l velocity @ conn

This option plots the flow average velocity through a connection, based on volume flow
rate results and on the nominal cross-section area of the components defined in the model
(on the Project Manager). The image below shows the plot for the connection c south_ext
-> manager_a via opening.

604
64.3.13 m contaminant @ node
This option is available when one or more contaminants were included in the fluid flow
network. Once invoked, the Node selection menu is displayed. Select a manager_a.

The contaminant menu shows the available contaminants for plotting in the model. This
model has only one contaminant. Select a CO 2.

605
The plot below shows the calculated CO2 concentration based on sources and sinks defined
on the model, and flow rates calculated by the fluid flow network. The pattern shows results
at 0.48 g of CO2 per kg of air during periods with no sources, while there is an increase in
concentration once the indoor sources become active.

64.3.14 n watts assoc w/ flow

This option is not implemented in ESP-r.

606
Time-series export and post-
processing

607
65 Tabular Output
ESP-r results are stored in a binary file, so it is not possible to use the data in other
applications on its native format. For this reason, the Results Analyser has functionalities to
export selected results to a text file. This section is primarily dedicated to this
functionality. The Tabular Output menu provides three main options:

• g performance metrics,
• h special materials data, and
• i network air/wtr flow.

The next section describes, dedicated to performance metric reports, explains the
mechanism to export data and manage export formats. It is followed by a section on i
network air/wtr flow. The option h special materials data is not covered in this page.

65.1 Options in the tabular output menu

65.1.1 g performance metrics
Select g performance metrics. The performance metrics menu shows variables available
for selection.

608
65.1.2 Exporting results to a text file
From the first menu on res, select:

> display to to toggle between the options screen and file, and select "file",

Set the file name. In this example, the file is called bld_basic.csv.

Press ok to select the suggested title for the dataset to be exported.

This file is created by ESP-r in the model cfg folder of the model. You should see a
warning in the text feedback area that the file was opened.

609
The display toggle should indicate file rather than screen.

Select one or more metrics to be exported, such as temperatures, weather data, comfort
metrics. In this tutorial, select:

b temperature
a dry bulb (db) temp.
-exit menu

Once this variables is selected, option p edit selection becomes available, similarly to the
facility available for variables in graphs.

610
Select p edit selection to check the variables selected so far (as in the image
below). Press - exit and activate changes.

65.1.3 ^ delim
Select ^ delim >> normal to display the available options for data delimiter. Select
comma.

611
65.1.4 & labels
Select & labels >> multiline to toggle between available options for the style of text
heading used to identify each column of exported data. The default label option
(multiline) is ideal for text feedback on the Result Analyser, but for data export the label
option on one line is preferable as it can be parsed with the corresponding data when
imported to another program.

65.1.5 * time
Select * time >> 10h30 to toggle between options for the time stamp added in the
beginning of each line in the exported file. The default option adds a time stamp (hours-
minutes) to every entry, repeating the pattern every 24 hours. Days are not indicated.
Results are indicated for the point in time between two time steps. Assuming an one-hour
time-step was used, by default ESP-r calculate values representative for the hour as a
whole, and not for a particular discreet point in time, hence the time-stamp indicating the
middle of the hour.

Two other options of time stamps are available.

The option 0.4375 provides a time stamp where the integer part indicate the day (1, 2,
3,...) and the decimal part indicates the time as fraction of the day, as in the example
below.

612
The option mm-dd 10:30:30 provides a stamp with month, day, hour, minute and
second, as in the example below.

Select the * time >> toggle until you reach mm-dd 10:30:30.

Select no on the dialog question about adding marks between days.

The menu should reflect this change.

613
65.1.6 ! list data
Once all variables of interested were selects use ! list data to write them to the
bld_basic.csv file. The text feedback area informs that the selected variable (Zone db
temperature) was written to the file.

Use the option > display to to toggle back to the screen option. You should see a
warning in the feedback window that the file was closed.

The image below shows an example of exported data from ESP-r. It uses a thorough time-
stamp, and "comma" as a field separator, and shows dry bulb temperature at the three
thermal zones of the model.

⚠ The functionality described above does not overwrite data already written in the file.
Exported data is appended at the end of the document, so if the document is not empty
it becomes necessary to scroll until the end of the document to see the exported data.

614
65.2 Additional options
The option +filter provides means to filter exported values based on casual gains.

The option *unit provides means to change some of the units used when exporting data.

Return to the main Tabular Output menu.

65.3 i network air/wtr flow

On the main Tabular Output and select i network air/wtr flow. The menu below shows
the variables available for selection. The exporting mechanism works as described above.

615
66 Enquire about
The enquire about facility of the Results Analyser provides tools to post-process time-step
results into aggregated values, such as minimums, maximums, averages, hours above or
below user-defined thresholds, and sums. Sums, in particular, are useful to access the
energy delivered to the model, as ESP-r results are in terms of power, and delivered must
be assessed by the integration of power over time. Sums are also useful to evaluate the
energy balance of the model, by integrating gains and losses over the simulation (for
surfaces and zones). The image below shows the Esquire about menu, and its options are
described in the following sections.

This tutorial starts by discussing the last fields of this menu, as their are general and affect
the way other options ot the menu are displayed.

66.1 Options in the enquire about menu

66.1.1 > output
In the Enquire about menu there is no no need to send data for plotting using the "!"
symbol, as in the graphical menu. Once requested, information is plotted directly in the text
feedback area. Results can also be save to files. Use this option to select the file name and
location, similar to the procedure described to save Report data to files.

616
66.1.2 : output
There are two formats available for data display/export in the Enquire about menu: ASCII
or Markdown. ASCII is the default option and it will suit most users, as markdown
documents require specific readers.

66.1.3 ^ delim
Similar to the Report functionality, data can be displayed/exported using several
separators, as listed in the image below.

66.1.4 & labels

Column labels can be presented in three formats.

The option multiline is the default and shows data as in the image below. Note that "Zone
name" is showed in two lines, and words are left-aligned to facilitate reading. This option
is ideal to read data on the Result Analyser interface.

The option on one line shows results as in the image below. The header of each column is
represented by a single word. This is ideal when data is exported and parsed in another
program (such as a spreadsheet application).

617
The following sections address the Enquire about menu post-processing functionalities.

66.1.5 a summary statistics

This option calculates maximum., minimum, average, and standard deviation of selected
variables. Once this option is invoked, the Summary statistics menu is shown (see image
below) and the user should selected the metric of interest. For this tutorial, select b
temperature.

The temperature metrics menu is displayed, and user should select the metric of interest.
For this tutorial, select a dry bulb (db) temp.

618
The image below shows the results produced by the summary statistics option, with values
for the selected metric for the three thermal zones in the model.

66.1.6 b frequency tables

See the histogram tutorial.

66.1.7 c hours above a value

This option calculates the number of hours where selected variables are above a user-
defined threshold. Once this option is invoked, the "hours above" query statistics menu is
shown (see image below) and the user should selected the metric of interest. For this
tutorial, select b temperature, and then

619
The temperature menu is shown. Select a dry bulb (DB) temp.

Enter the threshold to be used in the "hours above" calculation. For this tutorial, enter 20.

The image below shows results for this functionality.

620
In many cases, it is desirable to filter results based on occupancy or other criterion.

Selec + filter >>none

Select Occupants

The image belows show results of hours above 20C, considering only occupied hours.

66.1.8 d hours below a value

This option works exactly like the "hours above" option.

For demonstration purposes, invoke this option, select b temperature, and select e
resultant temp.

The image below shows results for this request. Note that previously selected filters
remain active.

66.1.9 f energy delivered

This option calculates the total amount of energy injected or extracted from thermal
zones during the simulated period.

621
66.1.10 g casual gain distribution
This option shows total casual gains, integrated over the simulated period.

Below, the image shows an example for zone 1.

The next image shows gains for all zones.

66.1.11 h zone energy balance

622
This option provides a break down of energy gains/losses for whole zones, as snapshots
or integrated over time.

Select snapshot.

Enter the date and time for the snapshot. In this example, use 6 2 1.00.

Select gain/loss, as the examplar model does not have a HVAC plant defined.

The text feedback window displays the results. In this example considering the Office
zone, energy losses are mainly due to infiltration and convection on external partitions,
while gains are due to ventilation (warm air coming from the Reception through the
door), and by conduction through internal partitions (as the Reception is warmer and heat
flows through the partition walls).

It is also possible to repeat the process and select integrated values.

In this case, the summary includes integrated values for the whole output period. In this
example considering the Office zone, the main loss is due to convection at opaque
internal partitions (likely the ceiling partition to the Roof zone). Casual gains and
623
ventilation gains have a larger impact while the vast majority of the heat injection is due
to the control defined for this zone keeping the air temperature at 20°C.

66.1.12 i surface energy balance

As in the previous images, it is possible to extract energy balance snapshots or integrated
values for any surface of the model.

Select the option snapshot and enter the same date of the previous example. Then select
surface (Surface a south, at the Reception zone).

The text feedback window shows a massive loss by shortwave radiation to the sky at the
outside face, while the same face is mostly heated up by conduction extracting thermal
energy from nodes inside the wall accumulated during the day (when the heating system

624
was in operation). The inner surface has significantly lower values of energy flux as at 0:30
hours the heating system is off and the indoor air node is close to thermal equilibrium with
the inner face of the wall.

66.1.13 j surface condensation

This option compares surface temperatures with the dew point of the air and indicates
how often condensation is likely to occur. Select current zone RH.

Select summary to get an overview of the whole simulated period.

Glazing panels and an external door with low thermal resistance are listed as surfaces
where condensation is likely to occur.

625
66.1.14 k intrstl condensation
This option is only available if internal wall temperatures are provided, otherwise the
following message is displayed.

In order to use this option, see Save temperature of nodes inside constructions

66.1.15 l monthly gains/losses

This option provides a summary of gains and losses on monthly basis.

Select proceed to accept the default selection of parameters.

Select to nearest kWh.

The text feedback window shows energy breakdown for the whole zone for the month of
February (as this simulation only covers a few days of this month).

626
66.1.16 m monthly temp. stats
This option provides minimum, maximum, and average dry bulb air temperature values
on monthly basis for each zone.

627
628
PART 3
Tutorials
Stand-alone tutorials aims at providing guidance about self-contained tasks
that are not addressed in other parts of the ESP-r documentation. Each
tutorial describes a unique task or data structure in ESP-r. Users are invited
to improve existing tutorials and/or create new ones expanding the
documentation.

629
67 Create MRT sensors
This tutorial describes the main steps to create MRT sensors in ESP-r.

67.1 MRT definition and purpose

A MRT sensor allow the calculation of viewfactors for a box in the zone, with user-defined
size and position. This box is not used in the thermal calculations (i.e., it does not have
materials and do not play a role in the thermal energy balance). A MRT sensor may be use
to represent the position of a real globe temperature probe placed in the zone (for
comparison with monitoring results), or representing a person (to support detailed
thermal comfort calculations).

The calculation of MRT viewfactors is done using the app mrt which is part of the ESP-r
suite.

67.2 Creating an MRT sensor

Open an exemplar on prj, such as a simple > f ... multizone with convective heating &
basic control

On prj, go to the view factor calculation application in the ESP-r suite:

m browse/edit...
c compositions
h view factors & radiant sensors

prj will show the zones available in the model. Zone names may be followed by the word
(defined) indicating that a viewfactor file is already available, or undefined.

Select reception (undefined)

And press ENTER accept suggested name. FIles with viewfactors are stores in the folder
zones, and have extension vwf.

630
Select + Add a MRT sensor

A small sensor is placed in the middle of the zone, and its properties (size, position and
rotation) are listed in the menu in a new entry: j sen_01 5.0 5.0 1.5 0.10 0.10 0.10 0

Select the option to edit sensor properties: j sen_01 5.0 5.0 1.5 0.10 0.10 0.10 0

631
✔ If necessary, return to the model composition and enquire about the coordinates of
vertices of the zone to decide which coordinates should be used for the MRT sensor.

Click on option a Sensor origin Y. The following dialog is presented:

Select the button edit sensor origin or press a on the keyboard to activate the first button
in the dialog. The dialog in the image below is presented. Change this value to 1.5 to bring
the sensor close to the window, in order to, for example, check how lower glass
temperatures may affect thermal comfort.

Change this value to 1.5 to bring the sensor close to the window, in order to, for example,
check how lower glass temperatures may affect thermal comfort.

The position of the sensor is updated in the zone.

632
Edit the properties one by one as showed in the image below.

The position of the sensor is shown in the image below.

633
Press - Exit to MRT menu

Other sensors may be added if necessary.

Save the new MRT sensor data before continuing: > Save MRT sensor & viewfactor

If the sensor data is not saved, ESP-r will show an error message when the user invokes
the calculation of viewfactors. In this case, the user should cancel the calculation, and save
the MRT sensor data.

67.3 Calculate viewfactors using the MRT app

Select b Calculate zone or MRT sensor viewfactors

prj shows the dialog in the image below:

The first option does not take into account the position and orientation of the sensor. The
second option ray-tracing provides more accurate viewfactor values. Select ray-tracing.
The View Factor app opens (see image below).

634
⚠ prj will remain opened in the original window, showing a warning message (see image
below) and waiting for the completion of viewfactor calculations:

Press:

f MRT sensor attrib & calcs.

635
Proceed with the viewfactor calculation:

d calc. sensor viewfactor

Calculation is performed and feedback is provided in the text feedback window., indicating
the view factor for each face of the sensor in relation to each surface of the zone (see image
below). Note that cube face 1 (back) is the one facing the window, and, as expected, the
higher view factors correspond to the surfaces 1 south and 10 glz_s, the south wall and
window respectively.

636
⚠ The calculation percentage in the lower left corner may stop before reaching 100%
even when the calculation is complete. Users may attempt to proceed using the
application even though before.

Save results > update file and overwrite the file when prompted.

The calculation is concluded. Press:

- exit to main menu, and

- exit vwt

The View Factor application closes and the user can resume using prj.

637
Press ENTER on prj to dismiss the warning shown when the viewfactor calculation was
invoked.

Select use new data.

It is not necessary to save the results again.

Select - Exit to model definition

The menu should show that the reception now has view factors (see image below).

Press - exit menu to return to the Building composition menu of prj.

638
68 Save temperature of nodes inside
constructions
ESP-r has different result saving levels so users can find the best compromise between file
size and information needed for a given analysis. By default, ESP-r uses result save level 4,
where intra-construction temperatures are not stored. This is visible in the default
simulation presets on prj for the exemplar model a simple > f ... multizone with
convective heating & basic control.

In the image below, the result save level is shown on option f.

Choose option f and use the dialog to change the result save level to 3, where intra-
construction values are saved.

The menu should reflect this change (see image below).

639
It is also possible to change the result save level on bps when the simulation is run
interactively or if bps is invoked from the terminal.

640
69 Import weather data to ESP-r
This tutorial describes some tools available for importing climate files in ESP-r

69.1 Data sources

Climate files for several locations can be found at Climate.OneBuilding.Org

This database may provide files based on different data sources for a single location. The
image below show 4 data sets available for Ahmedabad, in India. These sources (ISHRAE
and TMYx in this example) may show significant variation, as some are based on weather
station monitoring data, while others may use satellite data (see list of acronyms).

example of data sets on climate.onebuilding.org

69.2 Move files to the adequate folder and extract files in WSL
Depending on the operating system you are using, downloaded files will be located in
different folders. Move them to the adequate folder for importing.

In Windows WSL, for example, move downloaded files to the Ubuntu mapped drive and
extract compressed files.

641
 move zip file to the ubuntu folder on WSL

In the folder with extracted files, identify the file with extension epw.

identify the epw file for importing

Move this file to the dbs folder of your model.

Rename the model using a short name and bear in mind file names are case-sensitive in
ESP-r.

642
 move epw file to dbs model folder and rename it

69.3 Import data to the ESP-r model

Open the model on prj and use the options below to access the weather menu:

b databases
a annual weather

On the Weather menu, select h import EPW file

Type the name of the file you want to import (case sensitive).

Type a name for the new file to be created by ESP-r using the imported data.

643
If the import process occurs as expected, prj will show the name of the imported file on
option a of the in the Database management menu.

69.4 Test the imported file

On prj, select:

b databases
a annual weather
a analysis tool

The Weather module of ESP-r (clm) starts. On this module, press <ENTER> to accept the
suggested file name.
Use the options below to plot a graph and check that data was imported properly:

d graphical
a dry bulb temperature
! draw graph

644
 example of plot for testing imported data

Use other functionalities of this tool to explore the imported data and assess if its is
adequate for your simulation.

Troubleshooting notes

If it does not go as expected when trying to import your own climate data, pay attention
to the dialog box. The longitude and latitude in the project and file might be
mismatched.

It is also possible that the weather file you are trying to import is corrupted. In this case, it
is useful to tests other files for locations nearby.

645
70 Use a fan curve in a fluid network
This tutorial describes how to implement a fan performance curve in a fluid network.

Open the following model: exemplar > b technical feature > i ... with CO2 control of
mechanical ventilation

70.1 Constant flow rate fan

This exemplar uses constant flow rate components to represent fans. The image below
shows part of the summary information about the flow network, with one of the fans
highlighted (30 l/s).

By running this exemplar and opening the fluid flow network results, it is possible to see
the fan in operation to control the CO2 level in the Manager A zone. A sample of CO2
concentration results for the model using the constant flow are shown below.

646
70.2 Fan performance curve - Sample performance data
In reality, the flow provided by a fan or pump is based on the pressure loss in the system
as a whole, based on duct type/diameter/length, connections, pressure loss on openings,
filters, grills, etc. ESP-r calculates this pressure loss, but is a constant flow fan, as in the
exemplar, this information is ignored. The most adequate approach is to provide to ESP-r
the fan performance curve provided by the manufacturer, such as the one exemplified
below.

647
In order to use this curve in ESP-r, the user must extract manually a few data points from
the curve (Volume in m3/s and pressure in Pa). The table below shows approximate data
extracted from the curve above.

Volume Flow Pressure

Volume Flow (m3/s)
(l.s) (Pa)

0 0 43

15 0.015 41

25 0.025 20

29 0.029 0

The data above can be entered directly into ESP-r, but is also possible to derive a 3rd-order
polynomial equation using another software (such as Excel) and provided the curve
coefficients to ESP-r .

The image below shows an example of derived curve using Excel,:

648
The table below shows the curve coefficients with the nomenclature used in ESP-r:

a3 -5000293

a2 117203

a1 -691.07

a0 43.174

70.2.1 Curve limits

In addition to the performance data points or the coefficients, the user must also inform
the limit of validity for the curve, as minimum and maximum flow rates. The minimum value
must be above 0.001 m3/s. It is advisable that the maximum limit is slightly below the actual
limit. The limits below should be used in this tutorial:

lower polynomial validity limit (m3/s) 0.0011

upper polynomial validity limit (m3/s) 0.0289

70.2.2 Excel sample file

The file used in the data analysis is available on the link below: fan-esp-r.xlsx

70.3 Fan curve component type 310 in ESP-r

Once the fan curve data is obtained, the constant flow component (component type 30)
can be replaced by the general flow inducer component (type 310). As in many cases, the
best source of documentation about this component is the source code. The image below
shows an extract from the source code related to this component, where the parameters
required are explained:

649
70.4 Replacing the constant flow component
Open the exemplar and select f network flow

650
Select exisiting network

Press ok to open the file.

Select option d Components

651
Select component d fan_30lps

Select Edit component fan_30lps

Select no to modify the component type.

652
Select u 310: General flow inducer component

Select air as working fluid

The image below shows the help message provided for this component. It is always useful
to check the information available on the help for a given component.

653
Enter the lower flow rate limit of validity for the performance curve equal to 0.0011:

Enter the upper flow rate limit of validity for the performance curve equal to 0.0289:

Select the option coefficients to enter the values obtained by curve fitting in Excel:

Enter the coefficients (note that a0 is the first one, this is the opposite order provided by
Excel). Values are separated by one or more space characters.

The component has been replaced. The image below shows the updated list of
components, with type 310 used for the fan_30lps.

654
Press - Exit to return to the Fluid Flow Network main menu.

Press - Exit to leave the fluid flow network menu.

Press yes to save the modifications.

Press yes to overwrite the previous file.

655
⚠ Do not use the Save option, and if you do so, do not save a 3D network file if you
receive the prompt below.

70.5 Run simulation

Select s simulation and q integrated simulation

Select interactive

Press ok to accept the configuration file name.

Press w warnings >> OFF

Press yes to enable warnings.

Select c initiate simulation and s commence simulation

The simulation should run in a few seconds. The image below shows the new results for the
CO2 concentration in the Manager A zone. Results are particularly different on around hour
109 in the graph, where the CO2 level does not show the spikes seen on the other days
(and during this day in the flow rate results). On most days, the fan turns on and off in
alternating 5 minutes time-steps, as the CO2 lower setpoint concentration of 2 g/kg
reached. On one time step the fan is active and brings the CO2 level below 2 g/kg, while
656
on the next time step the fan is off and the CO2 level reaches around 2.4 g/kg triggering
the fan on the next time step. This does not happen in the forth day of this simulation.

The alternating flow rate pattern is seen in most days in the flow rate graph below. Note
that the flow rate on the fourth day of simulation is constant and it is also slightly lower
than in other days.

The graph below shows the pressure difference across the fan, where hour 109 has the
highest pressure difference to be handled by the fan. As the pressure difference increases,
the flow reduces (following the fan curve). The reduced flow rate never managed to bring
the CO2 concentration below the 2 g/kg setpoint, therefore the fan did not turn off.
657
The increase in pressure around the hour 109 is related to a peak in wind speed, creating
pressure in the building envelope acting against the fan, as seen in the graph below.

This is just an example of how a fan curve can be implemented in fluid flow networks in
ESP-r. The impact of using a fan curve depends on the network setting and boundary
conditions applied to the nodes.

70.6 Alternative input data using the curve performance points

658
In the example above, Excel was used to derive the coefficients for the polynomial equation
describing the fan curve. It is also possible to enter data points from the performance curve
directly in ESP-r, and the program will create the regression equation automatically.

This is done by selecting perf curve instead of coefficients in the dialog below.

The user should then inform the number of data points to be provided to ESP-r.

And then provide the volume flow rate and pressure for each point, in consecutive dialogs
as below:

ESP-r calculates the coefficients and report them in the text feedback area, as below:

Note that this coefficients are only slightly different from the ones obtained using Excel.
Both approaches (coefficients or perf curve) provide equivalent results

659
71 Understanding fluid flow network control
files
This tutorial uses the exemplar b technical features > c ... with natural ventilation

71.1 Fluid flow summary

The model has one fluid network defined, as indicated in the option f network flows
(defined) in the Browse/edit/simulate menu image below. Select this option to open the
fluid network.

660
The summary of this network is reproduced in the image below, indicating that two large
windows are available in each room, one low and another high, Each room also has cracks
around windows, and a door undercut connecting it to the corridor. The corridor has a grill
taking air to/from the outside.

661
Control file for the fluid network
Exit the fluid network menu, returning to the Browse/edit/simulate menu. Select k
network flow (4 loops).

Take note of the name of the control file and do not press ok yet.

Before pressing ok, use a text editor (such as NotePad++) to open this file and see its
contents. It useful to open the control file in a text editor as well as on prj. A sample of this
file, regarding the first control loop is reproduced below. In ESP-r, a single control file is
used for several model domains. The mass flow part starts at line 29 in this file, marked by
*mass flow. During the tutorial, whenever changes are implemented and saved using prj,
it is possible to also see the updates being loaded in the text editor.

Press ok on prj to open the control file in ESP-r.

71.2 Results

662
This is a sample of results for this model, just to illustrate that the model is currently
functional. This tutorial does not explore these results and does not discuss the impact of
control strategies on these results, focusing on presenting the different options available
for control of fluid networks.

663
71.3 Controls menu
The controls of this fluid network show 4 loops, one for which window.

Select option e 1 manager a low.

664
At this point, the text feedback menu describes the control settings for this loop, as
exemplified below. In this loop, the sensor is placed in a node on manager_a, and the
actuators is located in a flow network connection. The period data indicates that

This feedback is very important to understand the control, as the options provided in the
menu use codes instead of a human-readable options, as in the Editing Options menu
reproduced below.

As in the thermal domain, controls are based on the location of sensors (b) and actuators
(c), and period data (d) where control rule and setpoints are defined.

71.4 Sensor details

This section explores a few options for sensor placement in the model.

71.4.1 Place the zone in the fluid node of a zone

Select b sensor details

Select n senses temp in a specific zone

665
Select a manager_a

Select air point

The sensor definition is complete. Select option a for all questions related to the actuator
until you return to the Editing Options menu. The menu should look like the image below
on the left. Positive numbers indicate that a point in a thermal zone was selected for the
sensor. The number indicates the zone. In the images below, the sensors are placed on
zones 1 (on the left, based on the options described above) and 2 (on the right, in case the
zone manager_b was selected - zone number follows the same order they appear on
menus).

666
71.4.2 Placing the sensor in a construction node
It is also possible to place a sensor on the surface of a building component, or inside the
component. Following the example in the previous section, proceed until the dialog
Location, as in the image below. Select surface

Select c door

Select internal node

Select Layer 1 oak

667
Enter 2 to use the node in the middle of this layer.

✔ See section l constructions note temp. on https://appdocs.esru.strath.ac.uk/books/res-

result-analyser-guide-under-development/page/b-temperature for more information
about node number inside building components

Sensor selection is complete. The menu is now dedicated to the actuator selection. Select
option a for all questions related to the actuator until you return to the Editing Options
menu. The menu should look like the image below After selecting the actuator, the menu
reflects on line b the new sensor, as in the image below

In the sensor entry: 1 is a positive number, indicating the

number of the zone where the sensor is located, 3 is the number of the surface (c door
door), and 2 is the number of the node in the surface.

71.4.3 Sense flow at a connection

Select j senses flow at a node or connection

668
Select network node.

Select a dry bulb temperature at node.

When the option j senses flow at a node or connection is selected in the previous menu,
the menu workflow takes a counterintuitive structure, as the actuator must be defined
before the sensed node is selected.

Select any actuator, as for example, a single flow connection and a man_alow in the
next two menus.

669
Once the actuator is selected, the node for the sensor placement can be selected using the
menu below. Select a manager_a.

This will return the same control currently used in the model, as seen in the image below.

670
Where: -4 indicates that the control senses flow at a node or connection, 1 indicates the
fluid network node id (in this case, the manager_a), and 0 control based on the dry bulb
temperature at node. In principle, it will have the same effect of having a sensor with values
1 0 0 (selecting the air node of the first zone).

71.4.4 Sensor using weather data

Selecting any of the options from c to i will place the sensor on the outdoor environment.
In this example, select e wind speed

After selecting the actuator, the control menu reflects the new sensor.

671
Where: -3 indicates a weather variable is used for this sensor, and 2 indicates the variable
(following the same other shown in the menu, i.e. c dry bulb = 1, e wind speed = 2, ...).

71.4.5 Sense casual gains

Select k senses casual gain

Select b manager_b

672
There may be several casual gains defined for this zone. The index field is described in the
help available for this dialog, reproduced below.

Select 1 to use casual gains related to occupancy.

Sensor definition is complete. After selecting the actuator the menu should look like the
image below, where -7 indicates the use of casual gains and 1 indicates the casual gains
index.

71.4.6 Sensor based on temperature difference between nodes

elect j senses flow at a node or connection

673
Select network node.

Select d delta T between nodes

Select the actuator, as in the previous example using sensor on fluid flow network nodes.

Select the first node a manager_a

674
Select the 2nd node d man_alow

The menu below reflects the changes in sensor details.

Where -4 indicates a node of the fluid network is used for sensing, and the next two values
indicate the index of the two zones used for the temperature difference calculation. The
fact that the temperature difference was selected for this sensor is not represented in the
sensor details. The fragment of the control file below shows the value 24 at line 37,
indicating that the type of control is based on the temperature difference between nodes.
This line, related to the period data, is modified when the sensor for delta T is selected,
even if no change in the period data was carried out. Note, however, that the rest of the
675
period data is not adjusted automatically and must be addressed before attempting to run
a simulation with the new sensor position.

Select d period data

Select a

Select a on/off

Enter the values as in the image below, indicating that the connection will be fully
(fraction of 1) open (on above the setpoint) if the setpoint (temperature difference) was
above 0 (i.e., if the temperature of the first sensed node is higher than the second),

676
The image below shows the new period data in the control file.

71.5 Actuators
The most common actuator in fluid flow network controls is a connection in the network.
This option is represented by the values -3 in the control file line for actuators.

The following value indicates the index of the connection where the actuator is placed.

677
72 Define solar obstructions
72.1 Role of solar obstructions
Solar obstructions can be used to represent the reduction in solar radiation due to
neighbors, trees, topographic elements and even parts of the building that shade other
ones.

72.2 Getting baseline results for a model with no obstructions

Open an exemplar on prj, such as a simple > f ... multizone with convective heating &
basic control

Carry out a simulation and plot the solar gains on the Reception zone(see image below).
Solar gains in clear sky days are up to 3000 W.

72.3 Defining a obstruction

To define a solar obstruction select:

m browse/edit/simulate
c composition
a geometry & attribution
Select the zone that will be obstructed (obstructions are defined separately for each zone).
In this example, let's consider the reception of the multizone exemplar.
h solar obstruction

Select dimensional input:

678
The Obstruction menu is now available, as in the images below:

On this menu, select * add/delete/copy obstruction

Select add in the dialog below.

The block menu is now available, as in the image below. In this menu, it is possible to set
its properties.

679
Select a origin X Y Z

Choose edit origin and enter the following values: 3.0 -4.0 0.0

The position of the obstruction is updated as in the image below.

Select b block W D H

Enter the following values: 5.0 2.0 6

The size of the obstruction is updated as in the image below, showing a large obstruction
on the south of the building.

680
Other options in this menu can be used to rotate and tilt the model. It is also possible to
control the opacity of the obstruction.

72.4 Calculating shading factors

After defining obstructions, it is necessary to invoke > shading & insol directives to
enable the detailed calculation of solar gains.

This option opens the menu dedicated to shading (external elements blocking a fraction of
the solar radiation that would reach the thermal zone) and insolation (fraction of solar
radiation absorbed by each internal surface of the zone). These factions are calculated by a
separate ESP-r module.

681
Note that in calculated shading was "not requested for this zone" yet.

Select b calculated shading, and select all applicable surfaces in the following dialog.

In the Zoning shading and insolation menu, select e invoke shade/insol analysis

Select do now

ESP-r asks you for the name of the file where the fractions for shading and insolation will
be stored. Accept the suggested name pressing ok.

The module for shading and insolation calculations is opened in a new window

682
The image below reproduces the main menu of this module. Select g calculate shading.

Select update

Select the start time for the calculations:

683
And the end month:

ESP-r will show warnings indicating that data for shading is already available, however these
data does not consider the obstruction added in this tutorial, so press Yes to overwrite the
existing data whenever prompted.

ESP-r will not show any message when the calculation is concluded. You can check the
results of the calculation by choosing h shading synopsis in the main menu of the module.
The module will ask you for the month of interest (as in the image below), press ok.

Results for the first surface will be displayed in the text feedback area. The user can use
options in the dialog are to see results for other surfaces of interrupt the process. Press no
to return to the main menu.

684
Select - exit Shading/Insolation

Select yes to delete the transitional files.

This closes the shading and insolation module and return to the Project Manager.

685
Exit the menus and run the simulation to see the impact of shading on the results. The
image below shows solar gain results much smaller in the office due to the obstruction

72.5 Self-shading
In this exemplar model, there are overhangs on the south and west facades. These
overhangs will not be considered in the solar calculation of the reception and office unless
it is also represented by a obstruction.

686
687
73 Disable time-step averaging of results
For some applications, it is necessary to disable a feature of ESP-r called time-step
averaging. This feature reduces numerical instability, and will by default average
consecutive time-steps. This averaging is not suitable, for example, in cases where
detailed information about each time-step is essential to an energy assessment, or when
energy stored in the outer node of the walls is investigated.

⚠ This is not the same of the "average hourly results flag" defined in the simulation pre-
sets of prj. The average flag addresses multiple time-steps in a hour, and average their
results in a single hourly value.

73.1 Invoking interactive simulations on the Project Manager

In order to disable time-step averaging, it is necessary to run a simulation using the
interactive option in the Project Manager.

Once ESP-r simulator starts (bps), use options c initiate simulation, and then g
simulation option, followed by a timestep averaging >> ON.

Enter 1 to turn it off.

Use the option s commence simulation. The simulation runs and results are saved
without averaging values for every time-step.

688
74 Create operation file from scratch
74.1 Set internal load
In this section, you can define the internal gains that come from occupants, lighting, and
equipment.

To do this, follow these steps:

• Go to the "Edit/Simulate" menu.

• Choose "c composition"
• Then, select "c operational details" as follows:

689
Afterward, you will be directed to a menu to select the targeted zone. Below is a
screenshot from the "casual_gain_ctl" an example model in ESP-r. These twin chambers
each have a different internal load schedule.

At this stage, you should already know how many people will be in your zone, and you
can define their presence based on an hourly schedule. The activity of people can give
you an indication of the energy emitted from people (remember that people emit
sensible and latent heat load). You can also specify the type of lighting and its heat
emission, as well as the heat emitted from the equipment. Any load that is active for less
than one hour can be modeled as a fraction of the full hour's internal load.

After selecting the zone, give your operation file a name. A file with the .op extension will
be generated, usually in the \zones directory.

When defining the file for the first time, a menu will appear for you to either create a load
schedule from scratch or use pre-defined schedules. select "a define from scratch"

690
In the following section, we will go through the process of defining an internal load from
scratch, using the example of people's heat load. First give you load a name in our
example we refer it to people.

Then, select the type. We will go with the basic occupant, which gives us the possibility to
define the load in either Watts or Watts/m². select "b people basic occupant W & m2/p"

691
The interface will guide you through a loop of four day types: weekdays, Saturdays,
Sundays, and holidays. For each of these, you need to specify how many periods you
require within the day.

For example, if you choose to have three periods on weekdays, you can set the starting
hours as follows:

• The first period starts at 0.

• The second period begins at 8 to represent the start of the working hours.
• The third period starts at 17 and ends at 24.

In this case, you can specify that the period between 8 and 17 hours has internal loads
from people, while the other two periods have no loads.

692
You can change between the day type by clicking on the highlighted "3 loads >>"

Below is an example of three different kind of internal loads.

693
To define the loads for each period, you will need to adjust the following inputs:

• People Heat Load: Specify the amount of heat emitted by people during this
period. You can enter this value in either Watts or Watts per square meter,
depending on your preference.
• Lighting Heat Load: If you want to include the heat generated by lighting during
this period, you can enter the amount in Watts or Watts per square meter.
• Equipment Heat Load: Similarly, you can specify the heat generated by
equipment in Watts or Watts per square meter.

These inputs will allow you to tailor the internal loads for each defined period based on
your specific requirements.

74.2

694
75 Understanding the impact of latent casual
gains in the RH of the zone
This section describes the close relation between latent casual gains and the relative
humidity inside thermal zones.

75.1 Exemplar model results with latent gains

Casual gains are defined in terms of sensible and latent components, as shown in the
figure below for the Reception of the exemplar model a simple > f ... multizone with
convective heating & basic control.

Latent gains, such as the 300W due to occupancy between hours 9 and 17, are considered
as moisture sources, increasing the amount of energy in the model by adding water vapour
to the air node.

695
Relative humidity results for the exemplar model show values as low as 30% in the middle
of the day, as moisture released by occupants is added into the warm air inside the zone
(as the heating systems keeps the temperature at 20C). The graph shows peaks around
70% in the evening, when the warm and moist air inside the zone cools down and is no
longer able to hold the same amount of moisture. The air node temperature reduction
reduces the saturation pressure and leads to a higher relative humidity.

696
75.2 Remove latent gains from the model
The figures below show the modified casual gain menus for the Reception and Office of
the exemplar model, with no latent gains.

Results of relative humidity for the Reception using the updated casual gains are shown in
the figure below. During the middle of the day, RH drops to 20% in some days, and it never
reaches values above 50% in other days. This demonstrates the role of latent casual gains
in the zone RH.

697
698
76 Change the emissivity or absorptivity of a
component
76.1 Material and construction databases
It is possible to change the absorptivity or emissivity of each individual construction using
the composition > construction menus (illustrated below). This change is local and only
affects the selected surface.

It is also possible to change these values on the database and automatically apply
changes to all surfaces that use the modified component.

Absorptivity and emissivity are properties of materials, which are retrieved by ESP-r when
that material is used in the external or internal layer of a component.

76.2 Identify materials of interest

Consider the exemplar model a simple > f ... multizone with convective heating &
basic control. Navigate to the construction menu and select the zone Reception. Select
the south wall and note that the component is called "extern_wall".

Select - exit multiple times to return to the main menu.

Select b databases

Select e constructions

Select a browse/edit

699
Select j legacy constructions & models (it may be necessary to explore other classes to
find the component of interest)

Select a extern_wall

The properties for this construction are displayed in the menu area (reproduced in the
figure below). Note that the outer layer uses the material LT brown brick. This is the
material that needs to be target if changes in absorptivity and emissivity are expected to
impact in all surfaces of the model using this component.

76.3 Change material properties

These are the steps to change materials properties and propagate this change to all
constructions in the model:

Select b databases

Select c material properties

Select d copy default file to model (this step is essential to limit changes only to the
model, and not to all models in ESP-r)

Select a browse/edit

700
Select a Bricks (15)

Select option g, which holds the properties of the Lt brown brick used in the external
walls of the multizone exemplar model

Select f Emissivity out(-)

Enter 0.05

The value above is arbitrary and used only this tutorial to represent the extreme scenario
where all external wall are covered by a low-e coating or foil)

Select - Exit

In the "Accept changes" prompt, press yes (and to the same in all subsequent similar
prompts)

Select ! save materials file

Press yes to "Save materials changes" and too "Overwrite file" prompts.

Select -exit to return to the database management menu

Select -exit to return to the main menu of Project Manager

Press yes to accept subsequent prompts regarding update and save relevant files.

⚠ Note that this change will affect all component using the LT brown brick so there may
be unintended consequences in the model. It is recommended to make a copy of the
material and apply the copy of the material to the construction component.

76.4 Update construction zone files

In order to assure changes are implemented in the zone files, follow the steps below:

Select m browse/edit/simulate

Select c composition

Select b construction materials

Select # update all zones (and accept subsequent prompts to update and save relevant
files)

701
The updated value should now be visible for every external wall which uses the Lt brown
brick at the external layer.

76.5 Impact in results

The change described in this tutorial should reduce the heating energy demand of the
model from 42 kWh (with emissivity 0.9) to 37.4 kWh (with emissivity 0.05).

702
77 Link controls loops to thermal zones
Whenever controls are created of modified in ESP-r, it becomes necessary to link them to
zones (or other applicable entities). If the link is not defined, the user receives the
message below when attempting to exit the Control menu.

77.1 Link loops to zone

Open on prj the exemplar d open existing > exemplar >a simple > f ... multizone with
convective heating & basic control

On prj, go to the control menu by selecting:

m browse/edit...

i zones (1 loop)

This model has 1 control loop (as indicated in the line between options c and d.

The different days types used in this control are listed after the field cntl loop.

Select d link loops to zones

703
On the dialog below, select loop through all zones

The following dialogs will request the loop number to be used in each zone of the model.
The first dialog asks for the control loop to be used for the reception. Press ok to accept
control loop number 1.

The next dialog is dedicated to the office zone. Press ok to accept control loop number 1.

The next dialog is dedicated to the roof zone. The roof in this model has no control, i.e.
there is no injection or extraction of thermal energy and ESP-r will calculate temperature
fluctuations just base on the properties of the model and boundary conditions applied to
the zone. This is indicated using the control loop number zero. Press ok to accept control
loop number 0.

Now used the following options to save these controls and exit the menu:

Select > save current control data

Select - exit

There is warning messages about links controls and zones.

77.2 Example of control file with more than one loop

Open on prj the exemplar d open existing > exemplar > a simple > n ... with
convective heating and PID control

Navigate to the control menu by selecting:

m browse/edit...

704
i zones (2 loops)

The menu shows two loops, named: zn_compling_pc_6 and zn_compling_pc_8. In this
model, it is possible to link zones to one of them, or to enter loop number 0 if the zone
has no controls.

705
78 Use custom fixed convective transfer
coefficients
Convection is an important heat transfer mechanism in most energy systems. When
modelling unusual systems or validation/theoretical cases, users may need to replace
ESP-r default convective heat transfer coefficients (hc) by custom values.

78.1 Plotting reference results for comparison

This tutorial uses the exemplar model a simple > f ... multizone with convective
heating & basic control

Use this model to plot the external temperature of the South surface of the Reception
zone, as in the image below:

Detailed information on how to plot this graph:

On prj, go to the view factor calculation application in the ESP-r suite:

m browse/edit...
c compositions
q integrated simulation
automated

After the simulation is concluded. Invoke the Result Analyser using t result analysis

On the Result Analyser, plot the graph using the following options.

a graph
a parameter plot
a weather
b dry bulb temperature
- exit
b temperature
k outside surface temp.
-exit
a south
-exit
-exit
-exit
! draw

The graph shows surface temperatures up to 28°C, while the air temperature is much lower.
This graph will be used as reference for comparison to the case with custom hc. If
convection increases (higher hc), the surface temperature should come closer to the air

706
temperature, and a reduction in convection (hc) should increase the surface temperature
by reducing convection losses.

78.2 Create a custom hc file

On the Project Manager, select:

m browse/edit/simulate
c composition
g convection coefficients

The menu indicates that none of the zones uses a custom hc file.

Select a reception

The dialog area suggests a name and location for the new file. Press ok to accept it.

707
The dialog provide the option to define hc based on day types (such as weekday and
weekend). Press All days treated the same.

The Heat transfer coefficient/correlation menu is presented. While this tutorial only
covers fixed hc values, this menu offers several options for empirical equations (most of
them focus on the inside surface).

Select o User defined hcn coefficients

This option supports the definition of fixed hc values for the inside and outside surfaces.
These two fizxd value are applied to all surfaces of all zones.

Press ok to accept only one control period, so the same hc value will be applied to the
whole day.

708
Press ok to accept the start and end time of this period.

Select fixed coefficient.

Select user inside and outside.

Enter 0.01 for the hc of internal surfaces.

Enter 0.01 for the hc of external surface.

The User defined or CEN values menu now display the custom set of hc defined by the
user under option b.

Select > Save and - exit.

709
ESP-r asks for the confirmation of file names and warns about overwriting files. Press ok
whenever prompted.

The menu now shows that the hc file for the Reception is defined.

Exit this menu, run a simulation and plot the temperature of the South surface of the
Reception, as in the image below. The reduction of convection losses leads to a significant
increase in the surface temperature, which now reaches more than 37°C.

710
78.3 Edit the fixed hc value
On the Project Manager, select:

m browse/edit/simulate
c composition
g convection coefficients
a reception

Select option b 0.00 24.00 User supplied hc values

Press ok to prompts relared

711
As in the first part of this tutorial, press ok to accept start and end times, select fixed
coefficients, and select user inside and outside.

Enter 100 for both inside and outside values.

When custom hc values are edited, Program Manager shows a menu with all surfaces in
the zone and their respective hc values. Users can edit values per surface using this menu.
Press - exit, and then save the new values and exit the Heat transfer coeff menu.

Exit this menu, run a simulation and plot the temperature of the South surface of the
Reception, as in the image below. The increase of convection losses leads to a significant
reduction in the surface temperature, which now is close to the external air temperature.

712
713
79 Create a weather file based on custom data
This tutorial describes the steps to import weather data to ESP-r when data is in an
unconventional format. For information on regular weather files, please see the tutorial
Import weather data to ESP-r.

79.1 Prepare the weather data to be imported

The weather data must be placed in a text file, with values separated by comma. All values
must be integers.

Columns should hold data in the following order and format:

# Parameter | Column | Unit

dry bulb temperature | 1 | tenths C
diffuse horizontal solar | 2 | W/m^2
direct normal solar | 3 | W/m^2
wind speed | 4 | tenths m/s
wind direction | 5 | deg clockwise from north
relative humidity | 6|%

Note that both dry bulb temperature and wind speed are in tenths of °C and m/s, so
values such as 2.3°C and 4.7 m/s will be expressed as 23 and 47, respectively. This avoids
the use of decimal values, simplifying the import process.

The file name should be as simple as possible, as the user needs to type this name in the
dialog box during the import process. No headers are needed, and the file should look
like the image below.

714
79.2 Custom data example
For this tutorial, the following data file is provided: customdata.csv

This data shows data where the following values are equal to zero throughout the year:
dry bulb temperature, diffuse horizontal solar, wind speed, and wind direction. Direct
normal solar shows a pattern of 12 hours equal to zero, followed by 12 hours with
constant radiation close to 1400W/m2.

715
79.3 Exemplar model and custom data file location
This tutorial uses the exemplar model a simple > f ... multizone with convective
heating & basic control

After opening the exemplar, place the CSV file containing the weather data to be
imported in the dbs folder of the model, as in the image below.

79.4 Copying the current weather file to the model database

Navigate to the Weather menu using:

b databases
a annual weather

Select e copy to model to copy the current weather file from the central ESP-r database
to the model where it can be modified.

716
Press ok to accept the suggested name. The extension is arbitrary and ESP-r will accept
any extension defined by the user.

Select yes to open the Weather module of the ESP-r suite.

The Weather module is initiated in a separate window.

79.5 Import data using the Weather module

In the Weather module, press ok to open the current weather file.

Select k import

717
Select ASCII ESP-r.

Select yes. This will override the whole dataset in the current file by data from the
imported file.

The dialog box requests the name of the file to be imported. It is important to know the
name and path of this file, as the user must type it in the field. Name and path are case-
sensitive, and copy/paste is not enable in these dialogs in ESP-r.

As the file was placed in the dbs folder, and the default location of ESP-r is the cfg folder,
the relative path to the file is: ../dbs/customdata.csv

Press no, as the imported file has no information about site info. This must be done
manually after importing the file.

718
Press no, as the file does not have lines indicating the beginning of each day.

The text feedback area shows a message indicating the new data was save to the file. This
means that the bld_basic.climate file now holds the data imported from the CSV file.

It is useful to plot graphs

d graphical
1 set period
b January
c direct normal radiation
! draw graph

The graph below is plotted by the Weather module, showing the expected pattern and
values for the direct solar radiation.

Select:

- exit
- exit weather analysis

The Weather module is closed and the Project Manager becomes active again.

719
Select - exit menu to leave the database management facility. Whenever asked by ESP-r
to confirm changes in the database, press yes or ok to accept the suggested option.

79.6 Update latitude

Use the following options to update the latitude value to the site location:

m browse/edit/simulate
b context
a latitude

In this tutorial, the latitude was set to 0, to represent a model at the Equator.

It is also possible to adjust the longitude difference between center of the local time
meridian, but this parameter has minor impact in simulation results. The local time is
defined by weather data, as each line indicates one hours in local time.

79.7 Simulation results

The image below shows results for the exemplar model using data from customdata.csv .
As expected, the roof zone shows a cyclical daily pattern driven by solar gains during the
day and followed by nighttime convective losses due to external air at 0°C. Other zones
show similar pattern, with smaller magnitude due to smaller exposure to solar radiation.

720
80 Modelling blinds activated as a function of
temperature
This tutorial describes the steps to model internal blinds controlled by the external air
temperature. Other blind positions and other types of control can be implemented using
a similar approach.

80.1 Modelling blinds by switching optical properties

There are many heat and mass transfer implications of moving blinds and external
shutters to cover a transparent windowpane. In this tutorial, the effect of blinds is
modelled in a significantly simplified way, by assigning an alternative set of optic
properties for a transparent component, and use a weather variable to switch between
this main and alternative optic properties. This means that the thermal mass of the blind
is not taken into account, and the energy absorbed by the blind is injected in the inner
glass panel. Reflection by the blind is also combined with the one for the inner glass
panel.

80.2 Getting reference results for comparison

Open an exemplar on prj, such as a simple > f multizone with convective heating &
basic control

b databases
a annual weather
b select another
f Egypt, Aswan, 1986
- exit menu

The Weather module will start. Close it, as there is no need check the weather data in this
file.

Select yes to update the simulation year:

The Database management menu should indicate the new weather file on option a.

721
Select - exit menu and accept the prompts shown by the Project Manager related to
model updates.

Run a simulation:

m browse/edit/simulate
s simulation

Modify the simulation period to: 5 to 8 Auguts. Select:

g from...

And enter:

5 8
8 8

Run a simulation:

q integrated simulation
automated

Once the simulation is complete, select t results analysis on the Project Manager to
open the Results Analyser module of ESp-r.

Once the result file is open, select 4 building zones on the Module options menu.

722
Select a reception followed by - exit menu to confirm the selection.

a graph
a parameter plot
b temperature
a dry bulb (db) temp.
-exit menu
! draw graph

The graph shows that the indoor temperature reaches values above 45C.

Select:

d solar processes
a entering from outside
! draw graph

The graph indicates significant solar gains in this zone.

723
Select:

a weather
a dry bulb temperature
-exit menu
! draw graph

The graph indicates the external air temperature (bold line marked as Ambient) varies
from 27 to 43 C. Note that the indoor temperature is always higher than the external one.

⚠ For this tutorial, let's assume that the blinds should close when the external air
temperature is above 31C, which would allow users to enjoy the window view in the
morning, and close the blinds as the day gets hotter. This value is not a recommendation
and it is just used here to demonstrate how optics controls wor.

724
Close the Results Analyser and return to the Project Manager.

80.3 Identify relevant surfaces

Use the button image control at the bottom of the graphic window to toggle to i
surface names >> display. The name of the glazed surface to the south where blinds
should be placed is glz_s.

725
80.4 Investigating optical properties used in the model
On prj, select:

m browse/edit/simulate
c composition
b construction material
a reception

Select use it

Select continue

Select j glz_s

The menu shows attributes to the surface. Take note of the name of the optical property:
DCF7671_06nb. This is the set of optical properties that will be modify to account for
blinds.

726
Exit all menus and return to the first menu of the Project Manager. Select b databases.

Select d optical properties.

727
Select d copy default to model ../dbs to create a copy of the database in the model
folder, as we may need to modify it to include optical properties accounting for blinds.

Press ok to accept the suggested file name.

The first page of the Optica Properties db menu is shown, as in the image below. Note
that option q corresponds to the properties used in the model, and at the end of the line
it is described as a set of 6mm glass panels with no blinds. Select q.

728
ESP-r shows a graph with the transmittance, reflectance and absorptance of the assembly
for different angles of incidence of solar radiation. The menu shows the direct
transmittance for the whole assembly option f) for different angles of incidence. The
menu also shows the absorptance of each layer of the assembly (glass_air_glass). These
values are typical of glazing with no blinds. Press - exit menu to return to the Optical
Properties database.

729
In order to model blinds using optical properties, it is necessary to have two sets of
properties, one with and one without blinds. In some particular cases, such as the present
one, ESP-r database already includes an option of the properties with blinds (option r
DCF7671_06ib for this particular assembly), therefore, there is no need to modify the
database. Select option r. to explore the properties with blinds.

The curves in the graph show a dominant role for absorption, and small transmission and
reflection. The first layer of glazing (option h) has very high absorptance, emulating the
effect of blinds.

Now that two sets of optical properties are available (with and without blinds), the tutorial
concentrates on linking this properties (to allow one to be replaced by the other
whenever blinds are activated), and on creating a control that specifies which zones have
blinds and that they should be activated based on the criterion previously defined, i.e.
outdoor temperature above 31C.

Exit this and other database menus, and return to the first menu of the Project Manager.

730
In cases where ESP-r does not provide an option with blinds, it is necessary to create a
copy of the relevant optical properties, by using the item * import/add/delete/copy
element at the end of the menu.

80.5 Modelling blinds and controls in ESP-r

On prj, select:

m browse/edit/simulate
c composition
b construction material
a reception

Select use it

Select continue

Select 2 transparent layer properties

731
Select define alternative optical property

Select optical database

Select r DCF7671_06ib followed by -exit menu to confirm the selection.

732
Select > save construction data and accept the prompts to save files.

Select - exit menu and return to the main menu,

These steps will be saved in the construction file of this zone, located in the folder
zones. The file now has a second set of properties, as shown below.

80.6 Define optics control

733
On the Browse/Edit/Simulate menu, select l optics.

Press ok to open the control file.

The Controls menu opens with the control focus on optics (first line).

Select + add/delete/cop control loop.

Select add control loop on the dialog below.

Select Just one day type.

Press ok to accept the default value of one period for the control

The control loop is created, as in the image below.

Open this control loop.

734
Select b sensor details: 0 0 0 0

Select c dry bulb temperature to use the external air temperature as sensed variable.

Press continue in the following dialog to return to the control menu.

735
In the Editing Options menu, select c actuator details: 0 0 0

Select a reception

Select a optical properties (tcm type)

After defining sensors and actuators, the Editing options menu should loo like in the
image below.

Select d period data.

The Optical control periods menu opens. Select the only period available a 1 0.00
standard optics use standard optic.

736
Select a control tmc optics.

Select c switch tmc optics

Press ok to accept the default start time.

Enter the setpoint for the external temperature where optical properties should be
switched by ESP-r.

The configuration is finished.

737
Exit all control menus and save/overwrite files whenever asked.

The control file, located on the ctl folder, should now have lines related to the optics
control.

80.7 Run simulation with blinds and compare results

Run a new simulation and extract results for comparison with the previous model with no
blinds.

The graph below shows a significant reduction in solar energy entering the zone, with a
clear drop when the external temperature reaches the setpoint of 31C. The impact in the
zone air temperature is noticeable, particularly on the first two days the the indoor
temperature stays below the outdoor during the day.

738
81 Modelling adjacent zones
This tutorial describes the modelling of zones which are side-by-side (sharing a wall) or
are one on the top of the other (sharing a construction for floor of the upper zone and
ceiling of the lower one). In these cases, both zones have to be defined separately, and
the wall (or any other surface) separating the zones must be defined in both zones
following certain rules.

81.1 Adding a new zone

Consider the exemplar d open existing > exemplar > a simple > f multi-zone with
convective heating & basic control.

The image below shows a Storage zone, to be added to the original exemplar. Storage
and Reception share a wall and a door, and the tutorial describes the process to create
this new zone (with matching surfaces).

81.2 Investigating the model before adding the new zone

81.2.1 Understanding surfaces shared by two zones
In this model, the zones reception and Office share a few surfaces. In the image below,
the surface around the door is highlighted in both zones.

739
In cases like this, the best approach is to define the surface in one zone, and then copy it
to the new zone. The procedure is described in this tutorial.

81.2.2 Order of vertices of a surface

While the position of the vertices is the same in both surface, the order is different in each
zone. Consider the part_a surface in the Office zone. Looking from the outside of the
zone, the vertices are listed in anti-clockwise order., as in the images below.

This order is important because is assists ESP-r on understanding which side of the surface
points outwards. It is possible to visualize these normal vectors pointing outwards for each
surface in a zone using the image control button (position between the graphic and the
text windows). Select option n surface normals >> hidden. It will toggle this field to show,
and plot the arrows as in the image below.

740
This indicates that, when a surface is copied between zones, the order of the vertices must
be inverted to make sure the new surface normal points outwards (as expected by ESP-r).

81.2.3 Position of the new zone

Select d vertex coordinates to show the position of all vertices in the reception zone.
Take note of the coordinates for vertex 3, as it will be used as the origin for the new zone.
Vertex 4 is also useful because it can be used to calculate the length of the new zone (in
this case the coordinate y). The new zone will have 4.5 meters in the y direction (i.e. the
difference between the coordinates for vertices V3 and V4).

741
Select - exit menu

81.2.4 Materials of shared surfaces

When two zones share a surface, it is important that the construction assigned to the
surface in one zone matches the material assigned for the corresponding surface in the
other zone.

Select f surface attributes to access the constructions used in the Reception.

742
The surfaces of interest are c passg and k door_p.

The constructions are respectively gyp_blk_ptn and door.

Leave this menu and return to the first menu of the Project Manager. Navigate to the
construction database to check the properties of the constructions of interest. Select b
database > e construction > a browse/edit > b internal partitions > f gyp_blk_ptn.

The menu below shows the layers of the wall construction, indicating a central block with
one gap and one finishing gypsum board on each side. Option g indicates that the layers
in this construction as SYMETRICAL. This information is relevant when a construction is used
in a surface shared by two zones, as a symmetrical composition can be assigned to the
matching surfaces in each zone.

743
Press exit twice to return to the Construction Classes menu, Select c inside and outside
doors > a door. This construction is also SYMETRICAL, so it can be directly used in the
shared surfaces.

Press - exit menu five times to return to the main Model management menu.

744
81.3 Creating the new zone
81.3.1 Adding a zone
Select m browse/edit/simulate > c composition > a geometry & attribution > *
add/delete/copy

Select add zone

Select input dimensions

Enter the name of the new zone:

Enter a description:

Select rectangular plan

Enter the origin for the new zone, matching the position of vertex 3 in the Reception
zone.

Enter the dimensions of the new zone.

Accept the default values for orientation, elevation, and accept to overwrite the ctl file.

745
81.3.2 Deleting the unnecessary surface in the new zone
Select e surface list & edges

In the Surface topology of Storage menu, select * delete surface

Select option d Wall-4 and press - exit menu.

The zone now has only 5 surfaces.

746
81.3.3 Copying surfaces from the Reception into the Storage
Select + add/insert/copy/extrude from

On the new surface option menu, select e copy surface(s) from another zone

Select accept tolerance to use the default ESP-r value for small discrepancies between
vertices positions.

Select a reception

747
Select the two surfaces to be copied from the reception into the new Storage zone. The
selection is indicated by *. Press - exit menu.

When surfaces are copied from another zone, they can be modified (e.g. rotated, moved).
In this case, the surfaces will remain in the same position, so it is only necessary to invert
the surfaces. By selecting this option, the Project Manager changes the order of the nodes,
and this assures that the copied surface will have its normal point outwards (as expected).

Select invert

Select yes to make the connection between the original and the copied door surface.

748
Press ok to update the connection file.

Press yes to repeat the operation to the passg surface, followed by yes to link surfaces
and yes to update the cnn file.

ESP-r identifies that the surfaces in the reception have now the Storage room as
boundary condition. press yes to accept the update of properties in the reception
surfaces.

The Storage zone now has a shared wall with the reception.

The image below shows the normal for the surfaces of the new zone,

749
Remember that before running a simulation, the other surfaces of the new zone must be
configured (constructions and boundary conditions), and new construction and operation
files must be created for the zone.

750
82 Calculate reverberation time
82.1 Calculate reverberation time
ESP-r is primarily used for energy simulation, but there were initiatives to extend its
capabilities to other domains.

This tutorial provides a brief example of the Acoustic Module of ESP-r, called aco.

82.2 Atria exemplar for the calculation of reverberation time

82.2.1 Locate and copy the exemplar
Copy the exemplar folder from ESP-r training models into the home folder.

cp -R /opt/esp-r/training/acoustics/ ~/

Navigate to the cfg folder and list its contents.

cd ~/acoustics/cfg
ls

The model comprises a cfg file, and two other file types dedicated to acoustic properties
(extensions bcf and aco).

82.2.2 Open the exemplar

On the terminal, use the Acoustic Module to open the file.

aco -file acoustics_atrium.cfg

The Acoustic module opens and shows an image of the model geometry and a range of
options on its main menu.

751
82.3 Simulation parameters
Acoustic simulations require material and occupancy properties that are fundamentally
different from the ones available in a typical ESP-r model and databases. These properties
are listed in two separate files, described below.

82.3.1 Open the material properties file

Select b BCF

Enter the name of the file: ./acoustics_lca.bcf

Select with reporting of contents

A summary is provided in the text feedback

82.3.2 Open the occupancy file

Select c ACO

Enter the name of the file: ./acoustics_atrium.aco

Select with reporting of contents

752
These files (BCF and ACO) are ASCII and can be opened/edited using any text editor.

82.3.3 Select zones

On the main menu, select d zones to include

Select b atria and press - exit menu

Select Yes to display the properties of surfaces on the text feedback area.

82.4 Run simulation and analyse results

At this point, the main menu should indicate the problem, BCF and ACO file names, as well
as properties in the Zones, Options, and Calculation sections of the menu.
753
Select k start

The calculation using the selected method (Sabine, in the case of this example) is carried
out. Results are shown as a function of the frequency.

754
83 Life-cycle analysis
ESP-r is primarily used for energy simulation, but there were initiatives to extend its
capabilities to other domains.

This tutorial provides a brief example of the Ecobalance Module of ESP-r, called eco,
dedicated to Life-cycle analysis.

83.1 Atria exemplar

83.1.1 Locate and copy the examplar
Copy the exemplar folder from ESP-r training models into the home folder.

cp -R /opt/esp-r/training/acoustics/ ~/

Navigate to the cfg folder and list its contents.

cd ~/acoustics/cfg

ls

The model comprises a cfg file, and two other file types dedicated to acoustic properties
(extensions bcf and aco).

83.1.2 Open the exemplar

On the terminal, use the Acoustic Module to open the file.

aco -file acoustics_atrium.cfg

The Acoustic module opens and shows an image of the model geometry and a range of
options on its main menu.

755
83.1.3 Open the material properties file
Select b BCF

Enter the name of the file: ./acoustics_lca.bcf

Select done silently

A summary is provided in the text feedback

83.2 Run the analysis

Select Whole life cycle

756
Press ? to obtain a description of each analysis type, as reproduced below. Press dismiss
to close the help windows.

Select Whole life cycle analysis.

Results for each surface are provided in the text feedback area.

757
84 Computing the thermal effect of reflections
from obstructions via Radiance
This tutorial explains using the Modish facility to calculate the thermal effects of reflections
from obstructions using Radiance. This is achieved by modifying files generated by ESP-r’s
ISH (insulation and shading) module. The facility enables high-resolution ray tracing
computations to be integrated with ESP-r’s energy calculations, providing realistic
modelling of reflective obstructions. It allows users to specify the ratios of diffuse versus
direct reflectivities without relying on pre-calculated or empirically determined bidirectional
scattering distribution functions (BSDF).

84.1 Activating the functionalities

The operations are accessible from the context menu by selecting “Update shading for
reflections.” This action opens a menu with the following options:

Each option modifies the configuration file governing the application module, named
modish_defaults.pl. This module currently operates externally to ESP-r and is installed in a
dedicated modish folder within the bin directory of the ESP-r installation. The underlying
rationale for the application is discussed in detail in the paper available here.

Each menu selection modifies the configuration file instantly and silently—no additional
confirmations are needed. Modifications are applied one at a time as you click each option.

If “Compute reflections from obstructions” is selected, the configuration file is automatically

copied into the current cfg model folder. The file can be further customized manually or via
the menu. Manual modifications offer a broader range of options, which are documented
in the file comments.

Here are the menu options available under “Update shading for reflections”:

1- compute reflections from obs 15- suppose 2 diffuse bounces

2- do not compute refl.from obs 16- suppose 3 diffuse bounces
4- shd.f.corr. + diffuse piping 17- use 1 direction vector
5- shd.f.cor+dif.pip.+grnd refl 18- use 5 direction vectors
6- completely recalculate s.f. 19- use 17 direction vectors
7- compl.recalc. + diff. piping 20- resolution:2x2 diffuse & dir
8- put dir. refl. in diff. s.f. 21- resolution:2x2 dif,20x20 dir
11- use Perez sky, from weather 22- resolution:1x1 dif,10x10 dir
12- use CIE sky, generic 24- specify zons&surfs(optional)
13- use Perez sky, generic 25- include all zones &all surfs
14- suppose 1 diffuse bounce 26- if monthly: process now

Let us now examine one group of options separately.

758
1- compute reflections from obstructions'
2- do not compute reflections from obstructions'

These options toggle the activation of the reflections procedure. Selecting option 1
enables the process.

84.1.1 Selecting the Calculation Method

The next set of options determines the computation method, each with unique advantages
and trade-offs. Refer to the cited paper for detailed descriptions.

4- shading factor correction + diffuse piping

This is the default method. It adjusts shading factors calculated by ESP-r using a correction
factor from the ray tracer. It has an intermediate computation time. Diffuse piping means
that both direct and diffuse reflection contributions are integrated into ESP-r’s diffuse
radiation calculations.

5- shd.f.cor+dif.pip.+grnd refl'
Similar to option 4, but includes the shading effect of obstructions concerning ground
reflections. However, this option approximately doubles computation time.

6- completely recalculate the shading factors

This is one of the fastest methods, requiring about half the time of the default procedure.
It computes shading factors from scratch, ignoring ESP-r’s standard calculations.

7- completely recalculate the shading factors. + diffuse piping

This method extends option 6 by piping both direct and diffuse reflection contributions
into ESP-r’s diffuse radiation calculations.

8- put direct radiation reflections in the diffuse shading factors

This option modifies ESP-r’s ISH module-calculated shading factors. It is faster than the
default method and conservative, as it avoids diffuse piping.

84.1.2 Picking the sky model

The following options allow users to select the sky model:

11- use Perez sky, from weather

This option generates a Perez sky based on radiation data from the weather file, using the
specified latitude.

12- use CIE sky, generic

This option uses a generic CIE sky model. It is the default option.

13- use Perez sky, generic

759
This option calculates a generic Perez sky model on the basis of the specified latitude.

84.1.3 Specifying the number of diffuse bounces

Specifying the Number of Diffuse Bounces

This section defines the number of diffuse ray "bounces" considered in Radiance’s
calculation of diffuse reflections. This setting significantly affects computation times.

For simple problems, 1 bounce is sufficient. For moderately complex scenarios with some
interreflections, 2 bounces are usually adequate. For highly complex interreflections, 3
bounces may be necessary.

For even more interreflections, manual modifications to the configuration files are required.
Direct bounces, on the other hand, are much faster to compute. The default is 7 direct
bounces, which can only be adjusted by editing the configuration file directly.

To modify the number of diffuse bounces via the menu, the following options are available:

14- suppose 1 diffuse bounce

15- suppose 2 diffuse bounces
16- suppose 3 diffuse bounces

84.1.4 Specifying the number of direction vectors

Direction vectors define the orientation of rays emitted outward from each sensor on the
surface receiving radiation. The available options are 1, 5, or 17 direction vectors. These are
pre-calculated; to use a different number, the application code must be modified. The
number of direction vectors scales linearly with computation time.

17- use 1 direction vector

This is the fastest option but is usually inadequate unless the majority of reflected
radiation can be approximated as perpendicular to the receiving surface.

18- use 5 direction vectors

This is the default option and provides a good balance between computational speed and
resolution.

19- use 17 direction vectors

This option provides the highest precision but requires significantly longer computation
times. It is recommended for high-accuracy scenarios.

84.1.5 Specifying the sensor resolution

760
This option allows you to define the number of sensors for diffuse and direct radiation on
the receiving surfaces. Since diffuse calculations take significantly longer, the resolution for
diffuse sensors is usually set much lower than that for direct radiation sensors.

20- resolution:2x2 diffuse & dir

This is the default option and is suitable when specular reflections from direct radiation
are not dominant.

21- resolution:2x2 dif,20x20 dir

This option is ideal when specular reflections from direct radiation play a significant role..

22- resolution:1x1 dif,10x10 dir

This option is recommended when specular reflections from direct radiation have some
importance but high resolution for diffuse reflections is not required.

84.1.6 Specifying the zones and surfaces

The surfaces for which reflections from obstructions are calculated are usually glazed
surfaces but can also include fictitious or opaque surfaces. By default, all transparent
surfaces in all thermal zones are included. However, this default may be impractical when
there are many zones or transparent surfaces. In cases where only specific zones or surfaces
need to be analyzed (e.g., opaque surfaces or specific zones), one must edit the
configuration file manually.

24- specify zones and surfaces (optional).

There are two main strategies to specify zones and surfaces.

(1) The first strategy is creating a file named “modish_request.pl” manually to target
specific zones and surfaces.

(2) Calling Modish from the command line with the desired parameters, one zone at a
time.

As regards (1), in the first line of the “modish_request.pl” file one has to write the
following things:

zone_number_a surface_number_b surface_number_c …

and zone_number_d surface_number_e surface_number_f,

terminating the first row with a comma.

For example:
1 1 7 and 3 5,

761
would mean: take into account the reflection from obstruction for zone 1, surfaces 1 and
7, and zone 3, surface 5.

If the file "modish_request.pl" is absent, all the existing transparent surfaces in all the
existing zones of the model, will be taken into account in the calculation of reflections from
obstructions.

In the second row, one should write the name of the model configuration file in the “cfg”
model folder.

As regards (2), calling Modish from the command line one zone at a time, works only
when the shading computations are in monthly mode, not in embedded mode.

To use the command line, Modish refers to the configuration file but processes only the
specified zones and surfaces. Use the following syntax (see
https://metacpan.org/pod/Sim::OPT::Modish):

perl ./Modish.pm
PATH_TO_THE_model_CONFIGURATION_FILE.cfg zone_number surface_1_number surfac
e_2_number surface_n_number

For example:

perl ./Modish.pm/home/x/model/cfg/model.cfg 1 7 9

(which means: calculate for zone 1, surfaces 7 and 9.)

25- include all zones &all surfs

This is the default option and does not require specification in the configuration file. It is
also the only available option when Modish is running in embedded, non-monthly mode.

84.1.7 Adapting the setting to the required ISH mode

This section includes a single option for the monthly calculation mode. It does not toggle
a setting but instead triggers the recalculation of shading factors to incorporate reflections
from obstructions, in the case that the ISH mode that have been chosen when the shading
factors have been calculated is monthly. In monthly mode, ESP-r indeed calculates shading
factors in advance, so these must be modified to include obstruction reflections. After
finalizing all other settings, use this option to launch the necessary Modish recalculations:

If monthly: process now.

Select this option in monthly mode to activate Modish recomputations. This step is
unnecessary both when Modish is launched from the command line and when the shading
calculations are set to be performed in embedded (non-monthly) mode.

762
Appendix 1
Additional resources

763
85 Tips for new Linux users
Most users reading this chapter will have no previous experience using Linux, and this
section intends to provide the basic skills needed to use ESP-r properly. Some tips rely on
Ubuntu GUI and, therefore, are only suitable for some users, while most command line tips
are useful for Ubuntu and WSL users. Many tutorials are available on video on the internet,
so if you prefer, you can rely on them to get familiar with Linux instead of reading this
section.

85.1 Customising Ubuntu

Since your VM is a fresh computer, there are a few settings you may want to change before
you start using it. The settings window can be accessed by the drop-down menu in the
upper right corner (see figure below). Language and keyboard layouts are available on the
“Regions and languages” options. Data and time can be adjusted through the “Details”
option. Avoid the screen being locked all the time, and request you to reinsert your
password by choosing the option “Power” and changing the field “Blank Screen” to “Never”.

Access to Ubuntu Settings window

85.2 Using the terminal
Becoming a proficient user of ESP-r requires putting the graphic user interface aside and
using the command prompt window to invoke the program and other related tasks. On
Linux, the command prompt windows is called a “terminal”. You can open a new terminal
by pressing Crtl+Alt+t.

This command opens a terminal that may occupy the entire desktop (see the next figure,
on the left). You can resize it to better use your desktop space.

764
Ubuntu desktop with a terminal opened (left) and showing the terminal resized (right)

85.3 Navigation and management of files and folders

The terminal brings three pieces of information: the current user (user in the figure
below), the name of the computer (ubuntu) and the current folder (~), which is a way for
Linux systems to indicate you are at the user home folder).

Terminal Information - user@computer:current-folder

To see the full path of your home folder, use the command “pwd,” which stands for
present work directory.

Command indicating the current folder

So the symbol “~” is a shortcut to the folder “/home/user”.

The File Manager allows you to see the content of the Home folder. The figure below shows
a Terminal window and a File Manager window open on the desktop. This configuration is
ideal for practising terminal commands related to file and folder management, as you can
type commands in the Terminal and compare the response with the folders and files you
see in the File Manager.

765
 Terminal and file manager open side by side

You can list the files and subfolders in the current folder using the list command given
below.

ls

This will give you the following response, listing the folders in your home folder.

Output of the “ls” command on the terminal compared to the folders in the File
Manager

The terminal is case-sensitive, so pay attention to upper- and lowercase letters. The
command below will not work because it uses uppercase characters incorrectly.

⚠ LS

All commands have a user manual that can be accessed by typing man before the
command:

766
man ls

This will return the text in the figure below, with all possible flags that can be used when
invoking the “ls” command. Use the key ENTER to move to the next lines of the manual, or
type “q” and press ENTER to quit this manual and return to the prompt.

The first lines of the “ls” command manual

For example, the flag “-a” forces “ls” to list all files, including the hidden ones. Quit the
manual, return to the prompt, and issue the following command:

ls -a

You will see a much longer list when compared to the one you got the first time you
issued the command due to the inclusion of hidden files in the listing (shown in the image
below).

767
The point here is that you should get used to reading and using the Linux commands
manual to improve your skills on this OS and terminal. Numerous examples on internet
forums show how to use flags to perform particular operations with a given command.

Moving on, we will now address how to navigate the folders using commands. This is an
important skill in any OS, and it is essential knowledge for the automation of repetitive
tasks you may encounter by using custom programs. You will learn how to write them in
the section dedicated to Automating ESP-r).

In Ubuntu, you can use the command “cd” to change your current folder in the prompt.
Assuming you are in the home folder, you can use the following command to change to
the sub-folder “Documents” (remember, all commands are case-sensitive):

cd Documents

As a response, you will see that your current folder is indicated below.

Terminal indicating that the current folder is now “Documents”

If you use the command “ls,” you will see that the Document folder is empty. You can return
to the folder one level higher by typing:

cd ..

The expression “..” always indicates a level higher in the folder structure. You can keep
issuing this command to move up in the folder structure.

Using the command cd to move up in the folder structure

After a few times using “cd ..”, the current folder will remain unaltered, indicating that you
are at the highest level, also referred to as root. Listing the folders on root will show:

768
 Sub-folder structure of the root directory
There are a few important sub-folders in the root:

• bin and usr hold many of the programs installed in the system
• etc holds some new programs added to the system, and this is the default
location to place ESP-r executable files and databases
• mnt is the location to find external disks and USB pen drives
• home is the place where you will have your user home folder

To return to your home directory, you can use the following two commands issues one
after another:

cd /home

cd user

This will bring you back to the point where we started, the “~” folder, where we will
preferably place our own files.

You can use the shortcut “/” to point directly to the root folder:

cd /

You can also use the shortcut “~” to point directly to your home folder:

cd ~

You can have complex paths in the command “cd”. Assuming you are in the home folder,
you can use the following command to move to the folder mnt in the root:

cd ../../mnt

The command above moved twice up in the folder structure to reach the root directory
and then moved to mnt.

769
Until this point, we used the command “cd” to move to relative paths (up or down in the
folder structure). We can also use absolute paths. The command below, for example, moves
the prompt to the Documents folder regardless of where it is used:

cd ~/Documents

The same applies to the command below, which moves us to the mnt folder, regardless of
the place it was issued from:

cd /mnt

In the last two commands, the folders “~” and “/” were used to define absolute paths.

You can make new directories by using the command:

mkdir <directory_name>

where <directory_name> should be replaced by the name of the new directory you want
to create. The command below creates a sub-folder named “mymodels” in the user home
folder:

mkdir ~/mymodels

You can use the commands “cd ~” and “ls” to go to the user home folder and list the
directories, showing you the new folder you just created.

Example of folder creation using mkdir

Some useful commands for file management to copy, move and delete files are:

cp <original_file_name> <copy_file_name>

mv <file_name> <destination_folder>

rm <file_name>

The next figure shows the operations to copy a file in the home folder, move this copy to
a folder called “mymodels” and then delete this file.

770
 Example of using the commands to copy, move and delete files
85.4 Productive tips when using the terminal
You can recover previous commands by using the key ↑. This is particularly useful if you
want to reuse a recently typed command.

If you are typing the name of a file or folder within the command line, you can type the first
letters of its name and press the ESC key. This will autocomplete the name, saving you the
effort of typing it all. You can test it by going to your home folder, typing “cd T” and pressing
ESC. You should see the terminal complete the command as “cd Templates”. You should
try this command with other folders and directories in your Ubuntu folder if the above
example is not available in your case.

If you want to copy some text from the terminal (e.g. a name file to include in a command
you are writing), you may copy it as usual and then right-click on the terminal to paste it in
the position you need. You can use this function to copy any text in the terminal, such as
parts of previous commands, paths, files and folder names, to facilitate typing a new
command. You can also use the mouse scroll button to paste into the terminal information
you copied from another Ubuntu application (or copied from Windows if you are running
Ubuntu using VMWare).

85.5 System maintenance

You should regularly update the system, by typing:

sudo apt-get update

“sudo” gives administrative rights when you issue a command, so you are asked to type
your password after using this option. Many commands on Ubuntu will only work if you
place sudo before them. The update will install patches to your system, but it will not
upgrade it to the most recent stable version of Ubuntu. To upgrade the system you should
use the command:

sudo apt-get upgrade

771
85.6 Text editing
Using ESP-r often involves editing plain text files with no formatting. You can invoke a
text editor using the terminal command (not applicable for WSL):

gedit

You may need to install the update necessary to run this command using the command
(you will be prompted):

apt install gedit

Installation may take several minutes.

Using this editor, create a text file named testtext.txt and place it in your user home
folder. Quit the application. Now, move the working directory to the user's home folder
and use the list command, 'ls', to check if your new file is placed there. You can now open
this file by including it as a parameter when you start the editor:

gedit testtext.txt

85.7 Running commands in the background

You will notice that once you start gedit, your terminal gets locked, and you can no
longer use it until you close gedit. This happens because “gedit” was started as a
foreground application, and the terminal will wait until it is finished to proceed to the next
task. You can also start any application in background mode. Close gedit and invoke the
program again, adding the symbol “&” at the end of the command line.

gedit testtext.txt &

This will be able to use the terminal while gedit is still running. You can start ESP-r or any
other application in background mode, and this is very useful in many situations.

85.8 Manage and terminate processes

To check the processes currently running in your Linux computer, issue the command:

ps

This will produce a list like the one in the figure below.

You can terminate any process using the command kill, followed by the process's PID. In
the example below, this command would terminate ESP-r Project Manager, prj running on
process id 6167 (as an example).

772
kill -9 6167

85.9 Interrupt a command during execution

You can stop the execution of any command that is taking too long to run by pressing
ctrl+c.

85.10 Clear the screen

Using the Clear command, you can remove previous commands from the screen and start
afresh. You will still remain in the same folder.

clear

773
86 WSL tips and troubleshooting
86.1 Installing VcXsrv Windows X-server
⚠ VcXsrv is necessary on older Windows versions, prior to Windows 10 Build 19044+.

Download and install VcXsrv from SourceForge (VcXsrv Windows X Server download |
SourceForge.net).

Start ‘XLaunch’ from the Start menu or the Desktop icon.

Choose ‘Multiple windows’ as the display settings and set the display number to 0.

Accept the default options in the following screens:

774
775
⚠ XLaunch needs to be restarted manually every time the computer restarts.

It is possible to check if XLaunch is active on a computer in the area at the bottom right
corner of the screen. ESP-r only works in graphical mode if XLaunch is active.

After ESP-r is installed, configure it to work with VcXsrv.

86.1.1 Configuring VcXsrv X-server on Ubuntu (only for Windows 10 prior to Build
19044+)
Assign the display number to Ubuntu:

sudo echo export DISPLAY=:0 >> ~/.bashrc

source ~/.bashrc

The computer is ready to install ESP-r following the steps described in Compiling from
source code section.

86.2 Additional Information About WSL

86.2.1 WSL File Management
The files created on Ubuntu are usually mapped automatically to a network folder on
Windows.

The Ubuntu home folder, for example, is usually located on \\wsl$\Ubuntu-

20.04\home\user, as shown in the images below on Ubuntu and Windows.

Ubuntu:

776
Windows:

Windows disks are mounted on Ubuntu as /mnt/<disk letter>. For example, the
Download folder on Windows can be accessed from Ubuntu using this command:

cd /mnt/c/Users/<username>/Downloads

For some users, downloading Ubuntu automatically creates a separate folder named
'Linux', as shown below. All the Ubuntu and ESP-r files are stored in this folder.

777
86.2.2 Ubuntu Terminal Colours (Windows 11)
The default text/background colours can be changed by right-clicking at the top of the
window, selecting Settings in the drop-down menu, and selecting Appearance,
Application Theme Light.

86.2.3 Ubuntu Terminal Window Colours and Scroll Up (Windows 10)

The default colours of text/background can be changed by right-clicking on the top of
the window and selecting Properties in the drop-down menu.

778
In the Layout Tab, adjust the field Screen Buffer Size—Height to 1000 so users can scroll
up and see previous commands issued in the terminal.

Even if colours are changed on the terminal, when listing files and folders, a green
background is added to folder names, like in the image below:

To avoid this issue, use the following commands (on the terminal).

sudo echo export LS_COLORS=$LS_COLORS:'ow=1;34:' >> ~/.bashrc

source ~/.bashrc

This is the result:

86.2.4 Linux for Windows Users

It may be useful to check the tips section for new Linux users.

86.2.5 Using WSL from Windows command prompt (advanced users)

779
Advanced users may want to call WSL from Windows applications or scripts using the
Windows command line.

In this case, it is useful to access the Ubuntu file structure from the Windows prompt by
mapping a drive to the Ubuntu folder. In the example below, drive N on Windows is
mapped to the network drive where Ubuntu files are stored (this folder may change
depending on the Ubuntu version and installation).

net use N: \\wsl.localhost\Ubuntu-20.04

Calling WSL Linux from Windows Command Prompt can be done using the wsl.exe
command, followed by the distribution and the commands to be executed on Linux. In
the example below, the distribution is Ubuntu-20.04. Concatenate all necessary
commands using ";" (in this example, the first command moves to the model folder
before invoking ESP-r's Project Manager in script mode as described in the Automation
session on this Introduction to ESP-r.

wsl.exe -d Ubuntu-20.04 cd ~/basic/cfg; prj -mode script -file bld_basic.cfg < rotate45.txt

86.3 Troubleshooting
86.3.1 Segmentation Fault Error (Core Dumped) - Windows 10 with XLaunch
This error is usually due to XLauncher not being installed or active.

Make sure VcXsrv is installed.

Start ‘XLaunch’ from the Start menu, and set Display as described at the beginning of this
page.

Sometimes, bashrc does not set the display, and the following command should be issued
in every new Ubuntu session.

export DISPLAY=:0
780
86.3.2 Segmentation Fault Error (Core Dumped) - Windows 11 or Windows 10 with
recent updates
Windows support for GUI applications should be enabled in the Optional Features tab of
the Windows Subsystems for Linux Settings.

86.3.3 'command not found' Error

Check if ESP-r executables are in the folder /opt/ESP-r/bin

If the files are not there, the installation was unsuccessful and must be repeated.

If the files are in the folder, the problem is on the symbolic link (or in the PATH if the user
used this alternative approach). Check the instructions for creating symbolic links in the
ESP-r installation.

86.3.4 xterm not found error

After installing ESP-r, some users may face various errors when trying to run it in graphic
mode, with error messages related to xterm not found. These errors may be solved by
rebooting Ubuntu one (or more times) and following the update prompts.

86.3.5 Copy & Paste

It is possible to paste commands on the terminal using the mouse right button.

86.3.6 Enable virtualisation error

The error below may be solved by enabling virtualisation features on the BIOS.

781
WslRegisterDistribution failed with error: 0x80370102
Error: 0x80370102 The virtual machine could not be started because a required feature is
not installed.

BIOS settings vary depending on the computer and model, so it is beneficial to look
online for information about enabling virtualisation options for a particular machine.

Use this command (on PowerShell as Administrator) to restart the computer and gain
access to the BIOS

shutdown /r /fw

The computer restarts after a minute, and options related to Virtualization become
available for selection. Enable them, save the new configuration, and exit the BIOS.

86.3.7 CPU does not support virtualisation

Errors such as "The host CPU does not support the necessary hardware requirements"
indicate that the CPU does not support the virtualisation necessary for WSL, XLaunch,
and/or a virtual machine. See the example below for a machine running on Qualcomm
Snapdragon (TM) 8cx Gen 2.

86.3.8 Flickering screen

This issue occurs on computers running Windows 11. VcXsrv (XLaunch) is not needed on
Windows 11, so the operational system and VcXsrv display the same application, resulting
in a conflict that leads to a flickering screen. Uninstall VcXsrv to solve this issue.

782
86.3.9 Error: cannot create /tmp/foundit
The error below can be ignored and does not impact ESP-r functionality.

⚠ sh: 1: cannot create /tmp/foundit: Permission denied

86.4 Enabling WSL in older Windows versions

WSL is available in some older versions of Windows, but enabling it requires different
commands. Using Powershell as admin:

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-

Linux

Restart the system.

Go to the downloads folder and download Ubuntu:

Invoke-WebRequest -Uri https://aka.ms/wslUbuntu2004 -OutFile Ubuntu.appx -

UseBasicParsing

Install Ubuntu:

Add-AppxPackage .\Ubuntu.appx

86.4.1 Windows store

As an alternative to the PowerShell command, it is also possible to install Ubuntu via
Microsoft Store (as shown in the image below). Open the store, search for ‘Ubuntu 20.04
LTS’, and select "Get" on "Install" from the app page.

783
784
Appendix 2
Alternative approaches to
compile ESP-r

785
87 Run Ubuntu on a VM (alternative approach
for Windows)
It is recommended for Windows users who want a complete Linux system with a user
interface.

⚠ This procedure requires at least 20Gb of free disk space

87.1 Creating and Managing a Virtual Machine

A virtual machine VM allows the creation of a computer within another computer. By this,
you can have a full OS (client) running inside another OS (host). Several programs allow the
creation of virtual machines. Two popular options are VMware Workstation Player and
VMbox. VMware is fast, can be installed on Windows machines and is free for non-
commercial users. VMbox is open-source, freeware for all sorts of users, can be used in
Windows and OS X machines, and many relevant tasks for VM can be easily automated.

This section will use VMWare to create a Ubuntu client inside a Windows 10 computer.
Depending on your computer settings, creating a VM may require additional steps not
described here. This will become evident when you try one of the steps described below
and an error message appears. In these cases, read carefully the error message and look
for solutions on the internet. Other VMware users have often faced similar problems and
reported the solution in a forum. A brief list of common issues is available at the end of this
section.

Ubuntu 20.04 (Focal Fossa) is the recommended Linux Operating System (LOS) for use with
ESP-r. Download Ubuntu Desktop 20.04 from: http://releases.ubuntu.com/20.04/

Now, download VMWare player for Windows from:

https://www.vmware.com/uk/products/workstation-player/workstation-player-
evaluation.html

Install VMware Player on your computer and open it. You should see the window shown in
the figure below.

786
 Let’s use the option “Create a New Virtual Machine“. In the “New Virtual Machine
Wizard”, select “Installed disc image file (iso)” and choose the Ubuntu file from the
Download folder. Click “Next”, and provide your details, and choosing your username and
password for the VM. Then, you will be prompted about the VM name and location (see
next figure). The location is very important, as this is where all your virtual machine files will
be placed.

Click “Next”, and you will then be asked to define the hard disk space to be used by your
VM. VMware recommends an adequate size, and you can increase it at any point in the
future if necessary (see Managing your VM). Choose “Store virtual machine as a single file”
to improve your VM's performance (in terms of computational speed).

787
Click “Next” to access the final screen of the VM creation (see next figure). You may
customise some hardware options now, but as with the hard disk space, these settings can
be changed in the future if needed, so accept the default values and click “Finish”.

The creation of the VM may take a while. If you receive error messages, please consult the
dedicated section or look for a solution online (often found in forums or videos). You may
be prompted to install VMWare tools for your host system; please do so. If the creation of
your VM is successful, you will see the login screen of Ubuntu, and after providing your
username and password you will see the Ubuntu desktop (see next figure). You may now
navigate on the internet using Firefox and explore the folders and files in the system using
the File Manager (amongst other applications deployed by default with Ubuntu). If you are
unfamiliar with Linux systems, check the Introduction to Linux section.

788
 We can now close the VM using the menu options “Player > Power” in the VMware
window (see figure below). There are two different ways of doing so. You may “Suspend
guest”, which will freeze the VM on its current state (which is equivalent to the option
“Sleep” on a computer running Windows). This is often the preferred option, as the VM will
be loaded fast and be ready to use the next time you need it. You may also “Shut down
guest”, which will close all files and application in your VM (equivalent to “Shut down” a
computer running Windows). Shutting down is useful when you need to back-up, move,
share or manage your VM, as described in the next two sections.

87.1.1 Managing your VM

If your VM is shut down, you may change several of its settings by selecting this VM in the
VMware window and choosing the main menu of VMWare Player: Player > Manage >
Virtual Machine Settings. This will give you access to facilities to change the allocated run
memory for this VM, hard disk space, number of processors available to the host and others.

87.1.2 Backing up, moving and sharing virtual machines

The whole VM, including the OS, all programs installed, and all files created, are stored
in the folder you defined in the previous section. You can back up the entire VM by copying
this folder. You can also move it to another folder or another computer or share it with
another person if you want to.
87.2 Common error messages related to VMware Player on Windows
87.2.1 Mouse locked in the Virtual Machine
Sometimes, the virtual machine freezes and locks your mouse cursor, making you unable
to interact with the host OS. Press “Ctrl+Alt” to release the cursor.

87.2.2 Credential Guard

Windows may show error messages about the Credential Guard configuration. Please
refer to this solution:

https://www.techcrumble.net/2018/05/vmware-workstation-and-device-credential-
guard-are-not-compatible/

789
Several solutions are reported for the case above, with slightly different approaches. If the
suggested links do not work for your machine, search online and try alternative methods.
It may be a bit frustrating in the beginning, but this is the sort of experience that helps you
build up your skills and gain confidence that you can solve whatever problems you face
regarding setting up and using a less user-friendly system.

87.2.3 Segmentation Fault

When running esp-r, some problems with segmentation faults can be experienced. This is
mainly related to the lack of memory in these virtual machines. Sometimes, this can be fixed
by restarting the virtual machine or increasing its disk size.

87.2.4 VT-X settings

Some computers have virtualisation support disabled. In these cases, an error related to
Intel VT-X or AMD-V will appear during the VM installation/setup/usage.

Check if "Virtualization Enabled in Firmware" is properly configured using the command

below on the Powershell or Command Line prompt (run as Administrator):

systeminfo.exe

If the result shows "no", enabling it in the computer BIOS will be necessary.

Use this command to restart the computer and gain access to the BIOS

shutdown /r /fw

790
The computer will restart after a minute, and options related to Virtualization will be
available for selection. Enable them, save the new configuration, and exit the BIOS.

You may also refer to:

https://www.howtogeek.com/213795/how-to-enable-intel-vt-x-in-your-computers-
bios-or-uefi-firmware/

791
88 Install using the pre-compiled installer
(alternative approach for Linux)
⚠ This procedure works on Ubuntu 20.04, and it is not suitable for
WSL

If you are using another Ubuntu version, you should compile ESP-r from the source code.

88.1 Download
The pre-compiled installer can be downloaded from:

https://www.esru.strath.ac.uk/applications/esp-r/

88.2 Install
Open a terminal and go to the Downloads folder:

cd ~/Downloads

You can list the files in this folder to make sure you have downloaded the installer:

ls

The response should show a file like gzip -d ESP-r_<version>.deb.gz

Extract the installation file from the compressed gz file:

gzip -d ESP-r_<version>.deb.gz

Where <version> must be substituted by the number of the version you downloaded,
such as:

gzip -d ESP-r_13.3.14.deb.gz

If you recheck the folder contents, you should now see a file like gzip -d ESP-
r_<version>.deb

Install using the command (replace the version in the command):

sudo apt install -y ./ESP-r_<version>.deb

Where <version> must be substituted by the number of the version you downloaded,
such as:

792
sudo apt install ./ESP-r_13.3.14.deb

88.3 Check the installation

After the installation, you can check if ESP-r was installed in the computer by looking at
the contents of the opt folder:

cd /opt

ls

List the contents of this folder, and you should see a folder named esp-r. You can check
the content of this folder where all ESP-r files are located.

88.4 Create links to executables

In order to make esp-r executables accessible from any folder in the system, create
symbolic links for the files in the default application folder for Ubuntu:

cd /usr/local/bin

for FILE in /opt/esp-r/bin/*; do sudo ln -s $FILE "$(basename -- $FILE)"; done

cd ~

88.5 Update the PATH

This is an alternative approach that may used instead of creating links as described above.

Some users prefer to modify the system PATH instead of creating symbolic links in
the /usr/local/bin folder.

Once the installation is complete, update the PATH.

Here, we use the text editor gedit to change this file

sudo gedit .~/.profile

This will open the file. Include the following new line in the end of the document:

793
PATH="$PATH:/opt/esp-r/bin"

Save the file, close it and restart the computer.

88.6 Run ESP-r
After the system restart, open a terminal and type esp-r to start the application.

794
89 macOS: Compile from source on Intel
processor
89.1 Installing on Intel machines
This text is based on information available on the docs folder of ESP-r source code. from
2017 and have not been tested in recent ESP-r releases.

An alternative to the instructions below is creating a virtual machine using Virtualbox and
installing Ubuntu on it.

89.2 Introduction
This section is dedicated to installing dependencies and compiling on Apple computers.
Apple computers can run ESP-r and are also great computers for doing development work
on ESP-r. OSX includes the scripting, security and multi-tasking features of Linux/Unix
computers which ESP-r requires. For development work the compiler 'tool-chain' is almost
identical to that on Linux.

There are several tasks that are required before you can embark on creating or using the
virtual physics of ESP-r. If you only want to use ESP-r and have no need for a development
environment see the INSTALL from DMG below. If you want to INSTALL ESP-r from scratch
then jump to that section. section.

89.3 Install from DMG

ESP-r is available as a DMG file with a pre-compiled version of ESP-r which should work on
any recent OS X version. It includes a script to run to carry out the install process. You need
the following installed first XQuartz <https://www.xquartz.org> allows software such as
ESP-r to be displayed on your computer. After this package is installed you need to reboot.

There is a video which shows the steps involved. Inside the DMG file are instructions. Read
them before invoking the script.

89.4 System setup

Use the Apple Store to get the command line utilities (see notes at the end of this
document). Reboot after you have installed the command line utilities. Although this will
install a C compiler you need a matching set of the GNU compilers (gcc g++ gfortran) and
for that we recommend either MacPorts or Homebrew (see notes below). You will also need
XQuartz (see above for details). Again reboot after you have installed the XQuartz package.

89.5 MACPORTS
The MacPorts environment (see useful links below) is designed to assist OSX users in
installing open source software. It supports getting the necessary utilities as well as the GCC
compiler collections (gcc g++ gfortran). MacPorts will place newly installed software in

795
/opt/local (so that they do not clash with other software). MacPorts package manages
dependencies so the hassles of acquiring related software packages and/or libraries are
reduced. With very few commands the dependencies needed for ESP-r development and
use can be installed on your computer.

Go to the folder /opt/local. Check if a port exists use commands in the form:

sudo bin/port search gcc5

And to install a package and its dependencies issue commands in the form:

sudo bin/port install <package_name>

You will want to install the following port packages along with their dependencies:

sudo bin/port install gcc5, ddd gimp2-devel

This combination of ports will result in g++-mp-5, gcc-mp-5 and gfortran-mp-5 in

/opt/local/bin and the X11 and GTK libraries being located in /opt/local/lib in addition to
the X11 libraries generated by the initial X11 install in /usr/X11R6.

The pure-text version needs none of the graphic libraries and will almost always compile.
The GTK version uses a utility called pkg-config to locate libraries and will compile with few
questions being asked.

89.6 Compiling
By default OS X will place user accounts under the folder /Users. The default location for
ESP-r is /opt/esru. To create /opt/esru folder use a sudo command to create the new folder
and to gain ownership of the new folder so that you can install ESP-r there.

cd /opt

sudo mkdir esru

sudo chown your_login_name /opt/esru

sudo chgrp staff /opt/esru

When compiling esp-r use Install script in the ESP-r source code distribution. A typical
command would be:

./Install_o1 -d /opt/esru --gcc4 --debug --compiler_version -mp-5

or if you are using homebrew the compiler name is a bit different so use:

796
./Install_o1 -d /opt/esru --gcc4 --debug --compiler_version -6

You can find out more about the source code compile process by giving the command:

./Install --help

There are a few responses you need to provide during the Install process (refer to the Linux
install instructions for more details).

89.7 Setting up your environment

To use ESP-r it is suggested that in your $HOME folder e.g. /Users/fred you create a bin
folder and a Models folder. In bin place the scripts link_to and link_to_bash from the
distribution scripts folder. After building ESP-r into /opt/esru issue the following
commands:

cd

cd bin

./link_to /opt/esru/esp-r/bin

This will create links to the ESP-r executables. If your .profile or your .cshrc environment
files include $HOME/bin in the PATH definition when you login in the next time you should
be able to issue the command:

which prj

and get back

/Users/fred/bin/prj

If this does not work you may need to issue the following commands first:

cd

source .profile

which prj

When creating new models a good habit is to start from your Models folder:

cd

cd Models
797
prj

This will start up the ESP-r Project Manager and if you ask for a new model it will be located
in a subfolder of Models.

89.8 Fonts
On OSX sometimes the GTK version of ESP-r will crash when attempting to display a pop-
up message or display such as the wire-frame control proforma. This is usually resolved by
re-freshing the font cache via the following command:

sudo fc-cache -f -v

It might take several minutes to do this refresh of the font cache.

89.9 Useful links

Here is a list of useful sites:

• Command line tools for XCode <developer.apple.com/support/development/>

• MacPorts site <http://www.macports.org>
• The MacPorts GCC 4.9 or 5 works well in OSX. GCC 6 compiles but has not been
extensively tested.
• Homebrew site <http://brew.sh>
• XQuartz <http://www.xquartz.org>

89.10 Dependencies
If you are running the X11 version of esp-r there are only a few libraries that the executables
will be looking for (the version numbers may be different on your machine):

otool -L ./clm
./clm:
/usr/X11/lib/libX11.6.dylib (compatibility version 10.0.0, current version 10.0.0)
/opt/local/lib/libgcc/libstdc++.6.dylib (compatibility version 7.0.0, current version
7.18.0)
/usr/lib/libxslt.1.dylib (compatibility version 3.0.0, current version 3.24.0)
/usr/lib/libxml2.2.dylib (compatibility version 10.0.0, current version 10.3.0)
/opt/local/lib/libgcc/libgfortran.3.dylib (compatibility version 4.0.0, current version
4.0.0)
/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 159.1.0)
/opt/local/lib/libgcc/libgcc_s.1.dylib (compatibility version 1.0.0, current version 1.0.0)
/opt/local/lib/libgcc/libquadmath.0.dylib (compatibility version 1.0.0, current version
1.0.0)

These libraries will typically be installed with the X11 environment on Apple computers.

798
89.11 Additional notes
The developer kit XCode is only available via the Apple App Store and comes with GCC. The
command line tools needed for compiling ESP-r are an additional install which is accessed
via the Xcode -> Open developer tool -> More developer tools options. It is likely that you
can do development work by only downloading the command line tools for XCode
<developer.apple.com/support/development/>

799