`SIMPLE` - Simulating for People

       [SIM]ulating
for peo[PLE]

Thanks for your interest in SIMPLE, a simulation tool aiming to satisfy the present needs of Building Performance Simulation. Long story short, SIMPLE aims to:

Allow for a holistic building performance simulation using best-practice algorithms for each domain
Make it easier to account for the complex interactions between Humans and Buildings
Make it possible to implement complex algorithms, such as Model Predictive Control.
Be deployable in multiple environments, including Windows, Linux and Mac, the cloud, the browser (i.e., WebAssembly)
Use modern languages, toolset, and aim for clarity of source code (I do my best...)

You can read more about this in the "Do we need SIMPLE? section"

What to expect from this book?

For now this book has two parts:

User guide: This part is written manually, and it is meant to help you learn and understand SIMPLE. This part is mainly focused on users. For example, (in the future) it might help you migrate from other tools—if you wanted to—, to understand best building-modelling practices, and so on. If you are looking for information regarding math and equations, then you'd better be looking at the developer documentation (e.g., this). The developer documentation is meant not only for people who want to code but also for people who want to understand the internals of SIMPLE.
Input/Output Reference guide: This is an automatically generated guide, is updated every time the source code of SIMPLE's input model is updated. This section is meant to be a reference guide, helping

What is `SIMPLE`?

First and foremost, SIMPLE is a building performance simulation tool that aims to satisfy the present needs of this industry.

Digging deeper, SIMPLE can be seen from two perspectives.

Historical perspective, referring to the motivations and drivers that determined its design and motivated me to develop it.
Pragmatic perspective, associated with those cool features and benefits of SIMPLE that I have been finding during it's development.

Arguibly, these pragmatic benefits might be present in any modern simulation tool... but considering the low number of these, I guess they are pretty unique to SIMPLE anyway.

`SIMPLE`'s origins — It's the people, stupid

The development of SIMPLE was motivated by the results of my PhD Research. In these studies, I investigated what is it that people—not building scientists or architects or engineers—mean by and expect from a comfortable home. In a single sentence, my finidings suggest that our understanding of building physics far outpaces our knowledge of how people interact with buildings. This gap is only going to widen unless we invest resources in understanding humans.

Let put it this way:

Materials have been/will be getting better which means that, for instance, closed doors and windows are really good at preventing air leakage and heat transfer. Therefore, building controls and human behaviour—which define whether a window or door is open or closed—greatly impact the building's performance, and the health and comfort of the people in it.
Software have been/will be getting better, meaning that we can—for instance—predict and understand the effects of an open/closed window better than ever before
Our understanding of people is not catching up, meaning that we are not certain of whether windows and doors are open or not.

Note that point 3 is not suggesting that nothing has been done about understanding people. However, I would argue that our current tools to study people are not the best. This should be more clear later in this section.

This is a problem because buildings are built for people. Therefore, not understanding people implies not understanding the performance of buildings. Understanding when and why people choose to open windows requires tools that will let us properly research and evaluate human comfort and behaviour.

Below are the three main elements of SIMPLE that make it better at simulating buildings for real people.

1. It was designed to allow for holistic simulations

The motivation for performing holistic simulations is kind of obvious: when people get into a room, they just feel it. In other words, people do not separate—as software and building scientists do—the Thermal from the Daylight from the Acoustic domains. This means that, if we want to trully incorporate people's behaviour and comfort into our simulations, we need to account for multiple domains at the same time, at run time.

At run time means that it is not enough to run three simulations (one for thermal, one for acoustic, one for lighting) without considering the interaction between these domains.

So far, SIMPLE is actually quite good at Lighting and Thermal simulation, even though this feature has not been fully utilised. For instance, the following figure is evidence of how good it can calculate lighting and how well it compares to Energy Plus in therms of temperature estimations.

Lighting simulation	Thermal simulation

In order to allow for holistic simulations, we developed an architecture where different modules would connect to a single—domain agnostic—api. This API is the SIMPLE Model, and it allows any developer to say "Hey, give me the temperature of this room" without knowing how this value was calculated. In a similar manner, it allows these developers to make available values for other modules to use.

SIMPLE's architecture

2. It was designed to give some room for people's lives

People are not simple. They do not just say "it is cold, I will turn the heater on" in a deterministic manner. They take into account things like budget, bills, whether they are alone, and whether they have kids. Modelling this kind of behaviour calls for a much more flexible way of modelling control algorithms (yes, I am treating human behaviour as a control algorithm).

This is actually addressed in the same way as point 1 (i.e., Holistic simulations), in the sense that a new module could be created to deal with "Budget" or "Safety" and then use the same API to read and write values.

3. It was designed to travel in time

SIMPLE was designed with the purpose of acknowledging that people are constantly aware of their future. This is kind of obvious (e.g., you put a jacket before going out, not after) but our simulation tools tend to make it hard to implement this feature.

Allowing the simulation to travel in time is not trivial, as it means that—at every time step of the simulation—we need to estimate what will happen in the future and then return to the present.

From a simulation perspective, this implies

Gathering a bunch of potential actions to take
Execute each action, simulating some time into the future, record the results, and undo the changes.
From the results of all actions, identify the best decision to take, if any.

Time traveling

SIMPLE deals with this challenge by separating the Simulation State (i.e., the values that describe the physical state of the building and therefore change during the simulation) from the model (i.e., which is constant throughout the simulation). From a software perspective, the structure representing the model is immutable while the state is mutable.

The whole point of this architecture is that the Simulation State happens to be a relatively small and cheap-to-copy structure (it is an array of floating point numbers). This implies that during a simulation, we can create copy, then simulate, and then destroy this copy without much loss of performance.

Beyond people — benefits of a modern tool

Having a modern simulation tool offers several benefits. However, it is important to also acknowledge the general benefits that come built-in from designing a tool that helps design buildings for people:

Holistic simulations let us optimize multi-domain control algorithms that might lead to more optimal performance of buildings.
Traveling in time gives us the chance to implement Model Predictive Control, at runtime, in production, as part of a real EMS system.

And, of course, there are other benefits.

1. It allows easily defining complex control algorithms

SIMPLE can ingest control algorithms as scripts. This allows for a much richer and flexible way of writing algoritghms than through schedules. or other common methods.

let kids_bedroom = space("Kids Bedroom");
let kids_heater = hvac("Kids heater");
let kids_window = fenestration("kids window");

let window_is_open = kids_window.open_fraction > 0.0
let temperature = kids_bedroom.dry_bulb_temperature;
let is_cold = temperature < 19
let is_hot = temperature > 25

let outside_temperature = kids_window.front_temperature

if is_hot && outside_temperature < inside_temperature  {
    if random() < 0.7 {
        // 70% chance of opening windows
        kids_window.open_fraction = 1
    }
} else if is_cold && outside_temperature > inside_temperature {
    if random() < 0.3 {
        // 30% chance of ventilating
        kids_window.open_fraction = 1
    }
} else {
    if random() < 0.5{
        // 50% of opening windows to balance temperatures
        kids_window.open_fraction = 1
    }
}


// Do something else...

2. You can store and reuse the solar calculations

Optical calculations—like those required for estimating the amount of sun or light that reaches each surface—can be computationally expensive. Because of this, it is common to pre-calculate as much as possible before the simulation starts, and then reuse this data when advancing through time.

SIMPLE goes one step ahead and allows you to save this data, and then reuse it in succeding simulations. (This data is valid as long as the geometry and materials of the model remain the same.)

SolarOptions {
    optical_data_path: "./path/to/solar/data.json",
    // ... other options
}

Some applications of this are the following:

We had SIMPLE deployed on the cloud, and used it to run simulations on-demand. Keeping the solar data on a database meant that we did not have to recalculate it, significantly reducing response time and computational expenses.
Optimising non-geometric elements (e.g., insulation thickness, size of heaters, luminaire placements, etc.) does not imply changes in geometry. This means that every step of the optimisation will be shorter.

Note: A very common example of this technique is the Daylight Coefficients, which is the method that SIMPLE utilises to calculate the amount of solar radiation reaching each surface. The figure below shows how SIMPLE's results compare to those of EnergyPlus, which performs this calculation in a very different manner.

3. You can save the current state of the simulation

This is possible, but not yet implemented

Given that the Simulation State is a relatively small, independent object, it can be conveniently stored in a database or text file. This enables the pausing and restarting of simulations, offering flexibility for various applications.

This feature can potentially be particularly beneficial for integrating SIMPLE with Energy Management Systems (EMS). By periodically running simulations, EMS systems can update the building's current state and determine the most o ptimal control strategy, such as Model Predictive Control.

4. Deploy it to modern infrastructure

SIMPLE is a modern tool, written in a modern language, and that can run in multiple environments.

Environment	Example
Run locally	Being a pure `RUST` program, can be compiled to run on Windows, Linux and MacOS (has been tested on Linux and Mac).
Web Assembly	Run it on a browser, without the need for servers. CHECK THIS EXAMPLE
On the cloud	Embed `SIMPLE` into a web server and release it into very small and secure containers
On location	(not tested) Compile `SIMPLE` in a Raspberry PI or similar machine, and put it to work as part of the EMS

Can't we just improve other tools?

I have been working in Building Simulation Tool space for nearly a decade now. During this time, I have tried to combine simulation tools and methods, and also to make simulation more accessible to people. For example, my MSc research focused on the integration of Radiance and EnergyPlus. It was then when I started developing Groundhog, which intended to put Radiance in everyone’s hands. While developing Groundhog I realized that Radiance could use some sort of wrapper to make it a bit friendlier by offering out-of-the-box optimizations and pre- and post-processing. This motivated me to develop Emp, a Radiance orchestrator. Both projects—Radiance and Emp—have already died for various reasons.

During my time developing building performance simulation tools I have learned about an enormous amount of undeniable virtues that currently available tools—e.g., EnergyPlus and Radiance—have: they have been extensively validated, they are open source, they are free (as in freedom), and so on. Unfortunately, I have also seen many drawbacks. For starters, these tools were not really meant to be embedded on other tools. Radiance confesses this quite clearly:

“These routines are designed to aid the programmer who wishes to call Radiance as a library. Unfortunately, the system was not originally intended to be run this way, and there are some awkward limitations to contend with…” (Radiance’s raycalls.c)

Also, these tools were developed decades ago. Radiance was developed before the gaming and animation industry invested millions in improving rendering techniques, and EnergyPlus tends to focus too much on building physics even if we now know that we need to pay more attention to people’s behaviour in buildings (because insulating an open door is pointless). Also, programming was different back then, with different source control systems and way less people who knew how to code.

SIMPLE attempts to fix these issues by being open-source from day zero, by using a modern programming language, by having an architeture designed for enabling collaboration. Don’t be mistaken, though, SIMPLE does not attempt to reinvent the wheel. The real wheel is the knowledge of physics and rendering and computer sciences behind currently existing Building Performance Simulation tools… what it proposes is to build a good-old wheel with new materials and methods, in a more modern factory, and that is designed to travel in modern roads.

Getting Started with `SIMPLE`

SIMPLE requires occasion interactions with the terminal and code, so we have made this guide very simple for beginners. Throughout, you will learn how the tool works, how to prepare input files and analyze outputs.

Running a `SIMPLE` Simulation

SIMPLE is a command-line based tool, therefore, it doesn't have a user interface (UI). Here’s a short crash course on how the terminal works:

The terminal is an interface that allows you to access the command line. The command line is a text-based interface within the operating system to control the software.

To run SIMPLE, you will use the terminal to navigate to the folder where your SIMPLE executable file is located. This can be done by executing a sequence of cd (change directory) commands.

Once you are in the correct directory, you can call SIMPLE and start a simulation. Here's an example:

simple -i model.spl -w weather_file.epw -n 1 -o results.csv

In this command:

-i stands for input, followed by the name of your model file (in this case, model.spl).
-w is used to specify the weather file (here, weather_file.epw).
-n 1 defines the timestep, which is used to report variables and control the building.
-o is used to define the output file (results.csv in this case).

The Building Model

SIMPLE uses a text file as its primary input. This file describes a model, which can contain multiple buildings, although it is most common to simulate just one. (Describing the building in single-building simulations might hel[] estimate some things, like air leakage, based on the number of stories.)

A SIMPLE model contains—among others—the following elements (a more accurate and detailed list is available in the Input/Output reference)

Spaces: Basically, volumes of air that will have a single temperature. Each of them becomes a single Thermal Zone.
Buildings: Can contain Spaces
Surfaces: Physical elements—of a certain Material—that receive sun, transmit heat, and separate spaces.
Substances: A substance with a set of physical properties (e.g., density)
Materials: A layer of a certain thickness made up of a certain Substance
Constructions: A set of Materials
Hvacs: Heaters, Air Conditioners and so on.
Luminaires: Elements made for lighting. They produce light and also heat.
Objects: Mostly decorative at the moment (i.e., they do not interfere in simulation results), this is furniture, toiletes and so on.
Site Details: Describes the site and environment in which the model is located.
Outputs: Describe the outputs we want to be reported.

Describing a model

A SIMPLE model can be written in a .spl or .json file. The .spl format is meant to be more human-readable. (.json files are meant to be read and written by machines, mostly).

A .spl file starts by identifying the object type (e.g., SiteDetails or Substance) followed by a set of corresponding properties of the object being described.

Comments can be added with // for single lines and /*... */ for multi lines.

Here’s a sample basic model written in .spl syntax:

// This is a single line comment
/*
Comments can have multiple lines
So you can explain thigs better:

1. By adding lists
2. And longer comments.

*/

// This describes the environment of the model
SiteDetails {
   altitude : 0.0, // it is at sea level
   terrain : "City", // in a city
   latitude : -41.0, // at this latitude
   longitude : 174.0,  // at this loingitude
   standard_meridian : 180.0,  // this defines the timezone, basically
}

// This describes a building
Building {
    name: "Art Deco Building",
    n_storeys: 2, // it has 2 storeys
    shelter_class: "Urban",  // It is shelter as you would expect in a city
}

Asking for output

You can request specific outputs to be included in the results. This is done with an Output keyword followed by the desired output and an identifier. Here's an example:

Output {
    SpaceDryBulbTemperature : "Kids Bedroom" // Report the Dry Bulb Temperature of the Kids Bedroom.
}

Check out the Output section for a full list of possible output options.

Boundary

Represents the boundary of a Surface

By default (i.e., if no boundary is assigned to a Surface), the boundary will be assumed to be outside.

Note: This object cannot be declared by itself in a SIMPLE model. It is always embedded on a Surface

Examples

A `Space` boundary (in `.json`)

{
    "type": "Space",
    "space": "Some Room"    
}

A `Ground` boundary (in `.json`)

{
    "type": "Ground"
}

Supported Variants

Outdoor

Leads Outdoors. This is also the default (i.e., when no Boundary is set)

Property
`front_temperature`
`back_temperature`
`open_fraction`
`front_convection_coefficient`
`back_convection_coefficient`
`front_convective_heat_flow`
`back_convective_heat_flow`
`front_incident_solar_irradiance`
`back_incident_solar_irradiance`
`front_ir_irradiance`
`back_ir_irradiance`

Q ( $m^{3} / s$ )	$De lt a P$ ( $P a$ )
10	0.222
20	0.338
30	0.433
40	0.513
50	0.586

Property
`dry_bulb_temperature`
`brightness`
`loudness`
`infiltration_volume`
`infiltration_temperature`
`ventilation_volume`
`ventilation_temperature`

Property
`front_temperature`
`back_temperature`
`front_convection_coefficient`
`back_convection_coefficient`
`front_convective_heat_flow`
`back_convective_heat_flow`
`front_incident_solar_irradiance`
`back_incident_solar_irradiance`
`front_ir_irradiance`
`back_ir_irradiance`

SIMPLE Simulation Official Documentation