SIMPLE - Simulating for People

Thanks for your interest in SIMPLE a simulation tool aiming to satisfy the present needs of Building Performance Simulation. In very simple terms, SIMPLE is developed by acknowledging that current Building Science has to see people as its first priority. You can read more about this in the "Do we need SIMPLE? section"

       [SIM]ulating
for peo[PLE]

It is really exciting to have you here. I hope this book—and SIMPLE itself—are of your interest. There is a lot to do but it surely has a lot of potential!

What to expect from this book?

For now this book has two parts:

1. 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.
2. 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?

SIMPLE is a Building Performance Simulation tool developed with the purpose of modernizing Building Performance Simulation. This includes, but it really is not limited to, more appropriately integrating how "people" experience and interact with the buildings they use. There are two main reasons for this.

The first one is that—based on the research that led to the design and development of SIMPLE—Building Performance Simulation tools should be able to, at least (again, there are more requirements) allow us to perform holistic simulations (i.e., integrating heat, moisture, light and acoustics). The reason for this is that, when people get into a room, they just feel it. They do not separate—as Software and Building Scientists do—the Thermal from the Daylight from the Acoustic domains. So, SIMPLE aims to enable holistic Building Performance Simulation.

The second reason to focus on people is more related to the changing challenges of Building Science. One or two decades ago, many of the buildings we lived in were crap not very well insulated, they weren't air-tight, their windows weren't sized to balance solar heat gains, daylight, and insulaton, and so on. Under these conditions, it made a lot of sense to focus just on building physics. We did not really know how to design and build healthy, comfortable and Net-Zero energy buildings... but that has changed. There are many examples of extremely good buildings today and Software has become cheaper, more affordable, fast, and easy to use. Today, we understand and can predict the effects of building physics better than ever before, which means that the main gap in knowledge lies in human factors. Insulating an open door is absurd, so we need to really understand when and why people choose to open doors, so we can plan in advance and design buildings that make their comfort and behaviour compatible with the energy efficiency and health needs we have identified.

I like to think of this as a change of paradigm, where we stop focusing on 'occupants' and finally start focusing on 'humans'. If you want to understand a bit more the difference I make between Occupants and People read this.

Do we need SIMPLE? Can't we just keep using 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.

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)

Full Specification

{
	type: "Outdoor"
}

Ground

The Surface is in contact with the Ground

Full Specification

{
	type: "Ground"
}

Space

The Surface leads to another space whose temperature and other properties are part of the simulation

Border conditions:

• Solar Radiation: As calculated by the Solar module
• Net Shortwave (IR) Radiation: Zero, for now at least (this is a good assumption if the surfaces inside the Space are at similar temperatures)
• Convection Coefficient: Indoor
• Wind: No

Full Specification

Boundary {
	type : "Space", // this should not change
	space : string
}

AmbientTemperature

The surface leads to an environment with no wind or sun, and with a fixed mean-radiant and dry bulb temperature

This object is useful for defining surfaces that lead to spaces that we one is not interested in modelling; for example, a wall that separates an apartment's room with the hall of the building. In that case, we don't need to simulate the temperature of the hall... but we can assume a certain temperature.

Border conditions:

• Solar Radiation: None
• Net Shortwave (IR) Radiation: The set temperature
• Convection Coefficient: Indoor
• Wind: No

Full Specification

Boundary {
	type : "AmbientTemperature", // this should not change
	temperature : number
}

Adiabatic

The temperature of the other side of the wall will be the same as the one measured at the interior of the space

Full Specification

{
	type: "Adiabatic"
}

Building

This object is utilized to group Space objects together for metering and/or shared values. For example, the number of storeys and the ShelterClass will help defining the Infiltrations

Examples

.spl

Building {
    name: "Main Building",
    shelter_class: "Urban"    
}

.json

{
    "name": "Main Building",
    "shelter_class": "Urban"
}

Full Specification

Building {
   name : string,
   n_storeys : int, // optional,
   shelter_class : ShelterClass, // optional,
   stack_coefficient : number, // optional,
   wind_coefficient : number, // optional,
}

name

The name of the Building

n_storeys (optional)

The number of storeys of this building.

This value use used by the AirFlow module when a Space associated to this Building has been assigned an EffectiveAirLeakageArea infiltration. This value is required for calculating the Stack Coefficient ($C_s$) and the Wind Coefficient ($C_w$) of the EffectiveAirLeakageArea infiltration. $C_s$ and $C_w$ can be inputed directly by assigning values to the stack_coefficient and wind_coefficient fields, in which case the n_storeys field will be ignored.

shelter_class (optional)

The ShelterClass of this building.

This value use used by the AirFlow module when a Space associated to this Building has been assigned an EffectiveAirLeakageArea infiltration. This value is required for calculating the Wind Coefficient ($C_s$) of the EffectiveAirLeakageArea infiltration. $C_w$ can be inputed directly by assigning values to the wind_coefficient field, in which case the shelter_class field will be ignored.

stack_coefficient (optional)

The stack coefficient of this building, used for calculating infiltrations in Spaces that utilize the EffectiveAirLeakageArea infiltration option.

If not given, the number of storeys will be used for getting this values (based on EnergyPlus' Engineering Reference).

Note: The EffectiveAirLeakageArea object is appropriate for buildings of 3 storeys or less.

wind_coefficient (optional)

The wind coefficient of this building, used for calculating infiltrations in Spaces that utilize the EffectiveAirLeakageArea infiltration option.

If not given, the number of storeys will be used for getting this values (based on EnergyPlus' Engineering Reference).

Note: The EffectiveAirLeakageArea object is appropriate for buildings of 3 storeys or less.

ChairArmType

Types of armchair

Supported Variants

Existing

Has arms

Full Specification

"Existing"

Missing

Does not have arms

Full Specification

"Missing"

ChairBackType

Types of chair back

Supported Variants

Existing

Has arms

Full Specification

"Existing"

Missing

Does not have arms

Full Specification

"Missing"

ChairLegType

Types of legs in a chair

Supported Variants

Four

Four legs

Full Specification

"Four"

Three

Three legs

Full Specification

"Three"

Star

Star

Full Specification

"Star"

Other

Other

Full Specification

"Other"

ChairType

Type of chair

Supported Variants

Other

Other

Full Specification

"Other"

Dining

Dining

Full Specification

"Dining"

Office

Office

Full Specification

"Office"

Stool

Stool

Full Specification

"Stool"

Construction

An object representing an array of Materials, ordered from front to back

Front and back can be indoor, outdoor, or they can both be indoor (it depends exclusively on the Boundary set to the surface)

Examples

.spl

Construction {
    name: "The Construction",
    materials: [
        "layer 1",
        "layer 2",
    ]
}

.json

{
    "name": "The Construction",
    "materials": [
        "layer 1",
        "layer 2"
    ]
}

Full Specification

Construction {
   name : string,
   materials : [string, ...],
}

name

The name of the Construction object. Must be unique within the model

materials

The indices of the Material objects in the materials property of the Model object

Fenestration

A surface that can potentially be opened and closed. It can be of any Construction and it does not need to be a hole in another surface.

Examples

.spl

Fenestration {
    name: "Window 1",
    construction: "Double Clear Glass",
    back_boundary: {
        type: "Space",
        space: "Space 1",
    },
    operation: {
        type: "Fixed",
    },
    category: "Window",
    vertices: [
        0.548000,0,2.5000,  // X,Y,Z ==> Vertex 1 {m}
        0.548000,0,0.5000,  // X,Y,Z ==> Vertex 2 {m}
        5.548000,0,0.5000,  // X,Y,Z ==> Vertex 3 {m}
        5.548000,0,2.5000   // X,Y,Z ==> Vertex 4 {m}
    ],
    
}

.json

{
    "name": "Window 1",
    "construction": "Double Clear Glass",
    "back_boundary": {
        "type": "Space",
        "space": "Space 1"
    },
    "operation": {
        "type": "Fixed"
    },
    "category": "Window",
    "vertices": [
        0.548000,0,2.5000,  
        0.548000,0,0.5000,  
        5.548000,0,0.5000,  
        5.548000,0,2.5000   
    ]    
}

Full Specification

Fenestration {
   name : string,
   vertices : Polygon3D,
   construction : string,
   category : FenestrationType,
   operation : FenestrationPosition, // optional,
   front_boundary : Boundary,
   back_boundary : Boundary,
   precalculated_front_convection_coef : number, // optional,
   precalculated_back_convection_coef : number, // optional,
   parent_surface : string, // optional,
}

name

The name of the sub surface

vertices

An array of Numbers representing the vertices of the surface. The length of this array must be divisible by 3.

construction

The name of the Construction object in the constructions property of the Model object

category

Defines whether a Fenestration is a Window, Door, or other. If none is given, the assumed behaviour is that it is a Window.

operation (optional)

The opportunity for operating the Fenestration. If none is given, the window is assumed to be Fixed at Closed position.

front_boundary

The front Boundary. No boundary means it leads to the exterior

back_boundary

The back Boundary. No boundary means it leads to the exterior

precalculated_front_convection_coef (optional)

The front convection coefficient, in W/m2K

This value fixes the value, so the automatic calculations in SIMPLE have no effect.

precalculated_back_convection_coef (optional)

The back convection coefficient, in W/m2K

This value fixes the value, so the automatic calculations in SIMPLE have no effect.

parent_surface (optional)

The name of the surface containing this Fenestration, if any. A hole will be made in the parent surface in order to accomodate

Note that a Fenestration can be self contained (i.e., it can have no parent surface), which allows representing situation where the fenestration is very large and therefore there would be no area for wall.

Note: This field will not be serialized. This is beacuse there is no quarantee that the surfaces will be there before the fenestrations and thus there would be errors when deserializing. In any case, it is assumed that JSON models are read/written by machines—e.g., either by serializing a Model or by another kind of machine—and therefore the convenience of not having to write down the vertices around holes is not much needed.

API Access

// by name
let my_fenestration = fenestration(string);
// by index
let my_fenestration = fenestration(int);

API

The following properties are available for simulating control algorithms

FenestrationPosition

Defines whether the Fenestration is fixed or openable.

Example

.json

{
    "type" : "Continuous", 
    "max" : 1.0,
    "min" : 0.0
}

Note: This object cannot be declared by itself in a SIMPLE model, as it is always embeded on a Fenestration object

Supported Variants

Fixed

It is fixed at a certain open fraction

Full Specification

FenestrationPosition {
	type : "Fixed", // this should not change
	fraction : number, // optional
}

Continuous

It can be position at any position, from fully opened to fully closed

Full Specification

FenestrationPosition {
	type : "Continuous", // this should not change
	max : number, // optional
	min : number, // optional,
}

Binary

It can only be opened or closed, no in-between

Full Specification

FenestrationPosition {
	type : "Binary", // this should not change
	open : number, // optional
	closed : number, // optional,
}

FenestrationType

Defines whether the fenestration is a Door or a Window.

At present, this option has no effect whatsoever

Example

.json

"Window"    

Note: This object cannot be declared by itself in a SIMPLE model, as it is always embeded on a Fenestration object

Supported Variants

Window

This is a Window. This is the default.

Full Specification

"Window"

Door

This is a Door

Full Specification

"Door"

Opening

This is an opening, meaning that it lets air through it.

Full Specification

"Opening"

HVAC

A collection of elements heating and cooling systems

Example .spl

HVAC {    
    type: "ElectricHeater",
    name: "Bedrooms heater",
    target_space: "Bedroom",    
}

Example .json

{    
    "type": "ElectricHeater",
    "name": "Bedrooms heater",
    "target_space": "Bedroom"
}

Supported Types

• IdealHeaterCooler: An ideal heating/cooling device. Heats and Cools with an efficiency of 1, and nothing effects its COP or efficiency

• ElectricHeater: An electric heater, it can only heat.

API Access

// by name
let my_hvac = hvac(string);
// by index
let my_hvac = hvac(int);

ElectricHeater

A simple model of an Electric Heater. It can only heat and has a COP of 1. It only has two states: On/Off.

The thermostat that controls it—if any—is assumed to be in the target_space

Examples

.spl

HVAC {    
    type: "ElectricHeater",
    name: "Bedrooms heater",
    target_space: "Bedroom",    
}

.json

{    
    "type": "ElectricHeater",
    "name": "Bedrooms heater",
    "target_space": "Bedroom"
}

Full Specification

ElectricHeater {
   name : string,
   target_space : string, // optional,
   max_heating_power : number, // optional,
   heating_setpoint : number, // optional,
}

name

The name of the system

target_space (optional)

The Space that this [ElectricHeater] heats and/or cools

max_heating_power (optional)

Max heating power

heating_setpoint (optional)

The temperature that triggers the on/off option.

This tempareture is 'measured' in the target_space. If the dry bulb tempreature in the target_space is below this value, the heater starts heating.

Note: This assumes automatic control; that is to say, this condition will be evaluated every timestep of the heat model simulation (as opposed to the occupant/people control timestep, which is the one set by the user witht the simulation options)

API

The following properties are available for simulating control algorithms

IdealHeaterCooler

An ideal Heating and Cooling device, with a COP of 1.

It only has two states: On/Off.

Example

.spl

HVAC {    
    type: "IdealHeaterCooler",
    name: "Bedrooms heater",
    target_space:  "Bedroom"    
}

.json

{    
    "type": "IdealHeaterCooler",
    "name": "Bedrooms heater",
    "target_space": "Bedroom"    
}

Full Specification

IdealHeaterCooler {
   name : string,
   target_space : string, // optional,
   max_heating_power : number, // optional,
   max_cooling_power : number, // optional,
   heating_setpoint : number, // optional,
   cooling_setpoint : number, // optional,
}

name

The name of the system

target_space (optional)

The Spaces that this IdealHeaterCooler heats and/or cools

max_heating_power (optional)

Max heating power

max_cooling_power (optional)

Max cooling power

heating_setpoint (optional)

The temperature that automatically triggers the on/off option.

This tempareture is 'measured' in the thermostat_location. If the dry bulb tempreature in the thermostat_location is below this value, the system starts heating.

Note: This assumes automatic control; that is to say, this condition will be evaluated every timestep of the heat model simulation (as opposed to the occupant/people control timestep, which is the one set by the user witht the simulation options)

cooling_setpoint (optional)

The temperature that triggers the on/off option.

This tempareture is 'measured' in the thermostat_location. If the dry bulb tempreature in the thermostat_location is over this value, the system starts cooling.

Note: This assumes automatic control; that is to say, this condition will be evaluated every timestep of the heat model simulation (as opposed to the occupant/people control timestep, which is the one set by the user witht the simulation options)

API

The following properties are available for simulating control algorithms

Infiltration

Infiltration is the unintended air exchange between an interior space and the exterior. In SIMPLE, infiltrations are added to the intended ventilation.

This group of objects allow defining infiltration on different ways. Which variety is better will depend on the information available and the kind of building.

Examples

.spl

// Note that Infiltration is always attached to a Space
Space {
    name: "Bedroom", 
    volume: 42, // volume in m3. 
    infiltration: { // <- Define the infiltration
        type : "Doe2", 
        flow : 0.24,
    }
}

.json

{
    "type": "DesignFlowRate",
    "a": 1.0,
    "b": 0.0,
    "c": 0.04,
    "d": 0.0,
    "phi": 1.2
}

{
    "type": "Constant",
    "flow": 1.2
}

Note: This object cannot be declared by itself in a SIMPLE model, as it is always embeded on a Space

Supported Variants

Constant

A contant infiltration, specified in m3/s

Full Specification

Infiltration {
	type : "Constant", // this should not change
	flow : number
}

Blast

It is the same as the DesignFlowRate infiltration object, but specifying the default values from BLAST, as described in the EnergyPlus' Input Output reference

Full Specification

Infiltration {
	type : "Blast", // this should not change
	flow : number
}

Doe2

It is the same as the DesignFlowRate infiltration object, but specifying the default values from DOE-2 as described in the EnergyPlus' Input Output reference

Full Specification

Infiltration {
	type : "Doe2", // this should not change
	flow : number
}

DesignFlowRate

Sets the infiltration to the DesignFlowRate values using an arbitrary set of values. This option is based on EnergyPlus' object of the same name.

The flow $phi$ (in $m^3/s$) is calculated from the parameters $A$, $B$, $C$, $D$ and $ph{i}_{design}$ as follows:

$$\begin{gathered} phi= \\ ph{i}_{design}(A+B|T_{space}-T_{outside}|+C \\ times{W}_{speed}+D \\ times{W}_{speed}^2) \end{gathered}$$

The inputs to this object are $A$, $B$, $C$, $D$, $ph{i}_{design}$ .

Full Specification

Infiltration {
	type : "DesignFlowRate", // this should not change
	a : number
	b : number,
	c : number,
	d : number,
	phi : number,
}

EffectiveAirLeakageArea

Sets the infiltration based on EffectiveLeakageArea as described in the EnergyPlus' Input Output reference. This variant of infiltration requires the space to be part of a Building

The infiltration rate—in $m^3/s$—is calculated based on the following equation:

$$\begin{gathered} phi= \\ frac{A}_{L}1000 \\ sqrt{C}_s \\ DeltaT+C_w{W}_{speed}^2 \end{gathered}$$

where:

• $A_L$ is the effective air leakage in $c{m}^2$ @ 4Pa (NOTE THAT THE INPUT IS IN M2)
• $C_s$ is the coefficient for stack induced infiltration
• $C_w$ is the coefficient for wind induced infiltration

The only input to this object is the effecctive air leakage, $A_L$, in $c{m}^2$ @ 4Pa. The other parameters—$C_s$ and $C_w$—are derived based on the required Building object associated with the Space that owns this Infiltration. For this to work, the associated Building needs to have been assigned the fields n_storeys and a shelter_class (which allow calculating $C_s$ and $C_w$) OR the properties of stack_coefficient (i.e., $C_s$) and wind_coefficient (i.e., $C_w$).

Note: The EffectiveAirLeakageArea object is appropriate for buildings of 3 storeys or less.

Example

Building {
    name: "Art Deco Building", 
    n_storeys: 2,
    shelter_class: "Urban",
}

Space {
    name: "Kids Bedroom",
    volume: 19.23, 
    infiltration: {
      type : "EffectiveAirLeakageArea",
      area: 0.0496, // this is roughly 22cm x 22cm
    },
    building: "Art Deco Building"
}

Values for $A_L$

(source of this example: Sherman and Grimsrud (1980) Infiltration-Pressurization correlation: Simplified physical modeling). Conference of American Society of Heating, Refrigeration and Air Conditioning Engineers

Ideally, the value from $A_L$ should come from a blower-door test. When doing one of these, you can get a table like the following:

This data can be fitted in a model with the shape:

$$\begin{gathered} Q=K{ \\ DeltaP}^b \end{gathered}$$

In this case, the values for $K$ and $b$ are $0.0555$ and $0.6032$, respectively.

Evaluating this model at $4Pa$, we get an air flow $Q$ of $0.128m^3/s$.

To calculate $A_L$ we now need to use this data in the following equation, which relates air flows through openings of size $A_L$:

$$\begin{gathered} Q=A_L \\ sqrt \\ frac2 \\ DeltaP \\ rho \end{gathered}$$

Where $rho$ is the air density of $1.2kg/m^3$. So, the estimated $A_L$ would be $0.0496m^2$

Full Specification

Infiltration {
	type : "EffectiveAirLeakageArea", // this should not change
	area : number
}

Luminaire

A Luminaire

Examples

.spl

Luminaire {
    name: "Some Light",
    max_power: 30,
    target_space: "A bright space!"
}

.json

{
    "name": "Some Light",
    "max_power": 30,
    "target_space": "A bright space!"
}

Full Specification

Luminaire {
   name : string,
   max_power : number, // optional,
   target_space : string, // optional,
}

name

The name of the Luminaire

max_power (optional)

The maximum power consumption

target_space (optional)

The name of the space in which the space is located

While this value might not be relevant for e.g., lighting calculations, this is necessary for thermal simulations, in which the heat disipated by a luminaire will be disipated into the air of a thermal zone. So, if this is an exterior luminaire or if no thermal calculation is performed, this can be left empty.

API Access

// by name
let my_luminaire = luminaire(string);
// by index
let my_luminaire = luminaire(int);

API

The following properties are available for simulating control algorithms

Material

The representation of a physical layer-Material. That is to say, a layer of a certain thickness made of a certain Substance

Examples

.spl

Material {
    name:"Fancy Material",
    substance: "Fancy Substance",
    thickness: 0.2
}

.json

{
    "name":"Fancy Material",
    "substance": "Fancy Substance",
    "thickness": 0.2
}

Full Specification

Material {
   name : string,
   substance : string,
   thickness : number,
}

name

The name of the material object

substance

The name of the Substance of which this [Material] is made of

thickness

The thickness of the [Material]

Object

An object

Full Specification

Object {
   name : string,
   dimensions : Point3D,
   location : Point3D,
   up : Vector3D,
   front : Vector3D,
   specifications : ObjectSpecs,
   space : string, // optional,
}

name

The name of the object

dimensions

The size of the object (x, y, z)

location

The location of the center of the object

up

The up

front

Front

specifications

The specification of the object

space (optional)

The space in which the object is located

ObjectSpecs

An object category

Supported Variants

Other

Other category

Full Specification

{
	type: "Other"
}

Bathtub

Bathtub

Full Specification

{
	type: "Bathtub"
}

Bed

Bed

Full Specification

{
	type: "Bed"
}

Chair

Chair

Full Specification

ObjectSpecs {
	type : "Chair", // this should not change
	category : ChairType
	arms : ChairArmType,
	back : ChairBackType,
	legs : ChairLegType,
}

Dishwasher

Dishwasher

Full Specification

{
	type: "Dishwasher"
}

Fireplace

Fireplace

Full Specification

{
	type: "Fireplace"
}

Oven

Oven

Full Specification

{
	type: "Oven"
}

Refrigerator

Refrigerator

Full Specification

{
	type: "Refrigerator"
}

Sink

Sink

Full Specification

{
	type: "Sink"
}

Sofa

Sofa

Full Specification

ObjectSpecs {
	type : "Sofa", // this should not change
	category : SofaType
}

Stairs

Stairs

Full Specification

{
	type: "Stairs"
}

Storage

Storage

Full Specification

ObjectSpecs {
	type : "Storage", // this should not change
	category : StorageType
}

Stove

Stove

Full Specification

{
	type: "Stove"
}

Table

Table

Full Specification

ObjectSpecs {
	type : "Table", // this should not change
	category : TableType
	shape : TableShape,
}

Television

Television

Full Specification

{
	type: "Television"
}

Toilet

Toilet

Full Specification

{
	type: "Toilet"
}

WasherDryer

Washer Dryer

Full Specification

{
	type: "WasherDryer"
}

Output

ossible outputs to request from the simulation

Example

json {#include ../../../model/tests/box.spl:bedroom}} {#include ../../../model/tests/box.spl:bedroom_output}}

Supported Variants

Clothing

he amount of clothing the person is using, n Clo value

Output {
	Clothing : string
}

FenestrationOpenFraction

epresents how open is a fenestration. ontains the Index of fenestration, and its open fraction

Output {
	FenestrationOpenFraction : string
}

HeatingCoolingPowerConsumption

epresents the heating/cooling energy consumption of a Heating/Cooling system, n Watts

ontains the index of the HVAC in the building\'s vector, nd the power.

Output {
	HeatingCoolingPowerConsumption : string
}

LuminairePowerConsumption

epresents the power being consumed by Luminaire object, in Watts (luminaire index, power)

Output {
	LuminairePowerConsumption : string
}

SurfaceFrontConvectionCoefficient

he convective heat transfer coefficient t the front of a surface

Output {
	SurfaceFrontConvectionCoefficient : string
}

SurfaceBackConvectionCoefficient

he convective heat transfer coefficient t the back of a surface

Output {
	SurfaceBackConvectionCoefficient : string
}

SurfaceFrontConvectiveHeatFlow

he convective heat flow t the front of a surface

Output {
	SurfaceFrontConvectiveHeatFlow : string
}

SurfaceBackConvectiveHeatFlow

he convective heat flow t the back of a surface

Output {
	SurfaceBackConvectiveHeatFlow : string
}

SurfaceFrontSolarIrradiance

ncident solar irradiance at the front

Output {
	SurfaceFrontSolarIrradiance : string
}

SurfaceBackSolarIrradiance

ncident solar irradiance at the back

Output {
	SurfaceBackSolarIrradiance : string
}

SurfaceFrontIRIrradiance

ncident Infrared irradiance at the front

Output {
	SurfaceFrontIRIrradiance : string
}

SurfaceBackIRIrradiance

ncident Infrared irradiance at the back

Output {
	SurfaceBackIRIrradiance : string
}

FenestrationFrontConvectionCoefficient

he convective heat transfer coefficient t the front of a surface

Output {
	FenestrationFrontConvectionCoefficient : string
}

FenestrationBackConvectionCoefficient

he convective heat transfer coefficient t the back of a surface

Output {
	FenestrationBackConvectionCoefficient : string
}

FenestrationFrontConvectiveHeatFlow

he convective heat flow t the front of a surface

Output {
	FenestrationFrontConvectiveHeatFlow : string
}

FenestrationBackConvectiveHeatFlow

he convective heat flow t the back of a surface

Output {
	FenestrationBackConvectiveHeatFlow : string
}

FenestrationFrontSolarIrradiance

ncident solar irradiance at the front

Output {
	FenestrationFrontSolarIrradiance : string
}

FenestrationBackSolarIrradiance

ncident solar irradiance at the back

Output {
	FenestrationBackSolarIrradiance : string
}

FenestrationFrontIRIrradiance

ncident Infrared irradiance at the front

Output {
	FenestrationFrontIRIrradiance : string
}

FenestrationBackIRIrradiance

ncident Infrared irradiance at the back

Output {
	FenestrationBackIRIrradiance : string
}

SpaceDryBulbTemperature

pace Air Temperature in C... The elements re the index of the Space in the Building mode nd the temperature

Output {
	SpaceDryBulbTemperature : string
}

SpaceInfiltrationVolume

he volume of air that is entering the space in n uncontrolled way. In m3/s

Output {
	SpaceInfiltrationVolume : string
}

SpaceInfiltrationTemperature

he temperature of air that is entering the space in n uncontrolled way. In C

Output {
	SpaceInfiltrationTemperature : string
}

SpaceVentilationVolume

he volume of air that is entering the space in controlled way. In m3/s

Output {
	SpaceVentilationVolume : string
}

SpaceVentilationTemperature

he temperature of air that is entering the space in controlled way. In C

Output {
	SpaceVentilationTemperature : string
}

SpaceAirExchangeVolume

he volume of air that is moving from one space to another in controlled way. In m3/s

Output {
	SpaceAirExchangeVolume : string
}

SurfaceNodeTemperature

emperature (Float) of Surface\'s (usize) node (usize) .e. the order is (Surface Index, Node index, Temperature).

Output {
	SurfaceNodeTemperature : string
}

FenestrationNodeTemperature

emperature (Float) of Fenestration\'s (usize) node (usize) .e. the order is (Surface Index, Node index, Temperature).

Output {
	FenestrationNodeTemperature : string
}

SiteDetails

Some information about the site in which the building(s) are located

Examples

.spl

SiteDetails {    
    altitude: 123.0,
    terrain: "Urban"
}

.json

{    
    "altitude": 123.0,
    "terrain": "Urban"
}

Full Specification

SiteDetails {
   altitude : number, // optional,
   terrain : TerrainClass, // optional,
   latitude : number, // optional,
   longitude : number, // optional,
   standard_meridian : number, // optional,
}

altitude (optional)

The altitude of the site.

terrain (optional)

The kind of terrain

latitude (optional)

In degrees. South is negative and North is positive

This value is irrelevant if a simulation is ran based on an EPW weather file (in which case it is extracted such file). However, it can be useful when producing synthetic weathers or HVAC sizing, or other applications.

longitude (optional)

In degrees. West is negative, east is positive.

This value is irrelevant if a simulation is ran based on an EPW weather file (in which case it is extracted such file). However, it can be useful when producing synthetic weathers or HVAC sizing, or other applications.

standard_meridian (optional)

In degrees. This is 15*GMT Time Zone

This value is irrelevant if a simulation is ran based on an EPW weather file (in which case it is extracted such file). However, it can be useful when producing synthetic weathers or HVAC sizing, or other applications.

SofaType

Types of armchair

Supported Variants

Other

Other

Full Specification

"Other"

Rectangular

Rectangular

Full Specification

"Rectangular"

SingleSeat

Single Seat

Full Specification

"SingleSeat"

LShaped

L-Shaped

Full Specification

"LShaped"

LShapedExtension

L-Shaped Extension

Full Specification

"LShapedExtension"

SolarOptions

The options for the solar and lighting calculations

Examples

.spl

SolarOptions {    
    n_solar_irradiance_points: 30,
    solar_sky_discretization: 2,
    optical_data_path: "data.json"
}

.json

{    
    "n_solar_irradiance_points": 30,
    "solar_sky_discretization": 2,
    "optical_data_path": "data.json"
}

Full Specification

SolarOptions {
   n_solar_irradiance_points : int, // optional,
   solar_ambient_divitions : int, // optional,
   solar_sky_discretization : int, // optional,
   optical_data_path : string, // optional,
}

n_solar_irradiance_points (optional)

Number of points utilized to calculate the average incident solar irradiance over each fenestration or surface in W/m2.

A larger number of points leads to more accurate results but, as usual, it has an impact on the time of the computation. Specifically, the time required for creating the model increases linearly with the number of points. The time required to process each timestep is not affected.

solar_ambient_divitions (optional)

Number of primary rays sent from each of the n_solar_irradiance_points when calculating the average incident solar irradiance over each surface or fenestration.

A larger number of rays leads to more accurate results but, as usual, it has an impact on the time of the computation. Specifically, the time required for creating the model increases linearly with the number of points. The time required to process each timestep is not affected.

solar_sky_discretization (optional)

The sky discretization scheme used for solar irradiance. A value of 1 leads to 145 sky patches + the ground.

A larger number leads to more accurate results but, as usual, it has an impact on the time of the computation. Although the time required for creating the model is not greatly affected, the time required for processing each timestep can increase considerably.

optical_data_path (optional)

A path to the file containing information about solar radiation and other optical stuff. If the file does not exist, this information will be calculated and saved in this path. If it does exist, it will be loaded and used directly, saving time

Space

Represents a space with homogeneous temperature within a building. It is often actual room enclosed by walls, but it can also be more than one room. In this latter case, there will be walls within the Space, meaning that there are walls whose Front and Back boundary is this space.

Examples

.spl

Space {
    name: "Walrus Enclosure",
    volume: 249,
    building: "Wonderful Zoo"
}

.json

{
    "name": "Walrus Enclosure",
    "volume": 249,
    "building": "Wonderful Zoo"
}

Full Specification

Space {
   name : string,
   volume : number, // optional,
   infiltration : Infiltration, // optional,
   building : string, // optional,
   storey : int, // optional,
   purposes : [SpacePurpose, ...],
}

name

The name of the space

volume (optional)

Volume of the space

infiltration (optional)

The infiltration in the space

building (optional)

The building in which this Space is inserted

storey (optional)

The storey in which the space is located, indexing from 0 (i.e., ground floor is 0)

purposes

The purposes in a room. It can have multiple purposes (e.g., a Living/Dining/Kithen space)

API Access

// by name
let my_space = space(string);
// by index
let my_space = space(int);

API

The following properties are available for simulating control algorithms

SpacePurpose

The category of a space.

Supported Variants

Bathroom

Bathroom, toilette, shower, etc.

Full Specification

{
	type: "Bathroom"
}

Bedroom

Bedroom

Full Specification

{
	type: "Bedroom"
}

DiningRoom

Dining room

Full Specification

{
	type: "DiningRoom"
}

Kitchen

Kitchen

Full Specification

{
	type: "Kitchen"
}

LivingRoom

Living room

Full Specification

{
	type: "LivingRoom"
}

Office

Office

Full Specification

{
	type: "Office"
}

Storage

Storage

Full Specification

{
	type: "Storage"
}

Garage

Garage

Full Specification

{
	type: "Garage"
}

Hallway

Hallway

Full Specification

{
	type: "Hallway"
}

Laundry

Laundry

Full Specification

{
	type: "Laundry"
}

Other

Other

Full Specification

{
	type: "Other"
}

StorageType

Types of storage

Supported Variants

Cabinet

Enclosed storage

Full Specification

"Cabinet"

Shelf

Open storage (i.e., shelves)

Full Specification

"Shelf"

Substance

A physical substance with physical—i.e., optical, thermal—properties.

Note that, contrary to EnergyPlus' Materials, Substances do not contain information about the thickness, which in Simple is given when creating a Material. The idea is to enable multiple materials of different thicknesses to reference the same material.

Note: Glazing substances are Normal substances with solar_transmitance and visible_transmittance. However, contrary to all other properties, this property does depend on the thickness of the substance. So, in order to build a coherent Glazing, you'll need to match this Substance with an appropriate Material

Examples

A normal substance

Substance {
    type: "Normal",
    name: "the substance", 
    thermal_conductivity: 12,
}

A gas

Substance {
    type: "Gas",
    name: "Some Gas",
    gas: "Xenon"
}

Supported Types

• Normal: A normal (i.e., solid, homogeneous) substance such as glass, timber or concrete.

• Gas: A gas, as understood by the standard ISO-15099(2003).

Normal

Represents a physical material with common physical properties (e.g., timber, concrete, brick, glass). In other words, it cannot change its thermal/optical properties based on its internal state (e.g., it cannot change its specific heat based on temperature, like Gas or Phase Change Materials).

Examples

.spl

Substance {
    type: "Normal",
    name: "the substance", 
    thermal_conductivity: 12,
}

.json

{
    "type": "Normal",
    "name": "the substance", 
    "thermal_conductivity": 12.0 
}

Full Specification

Normal {
   name : string,
   thermal_conductivity : number, // optional,
   specific_heat_capacity : number, // optional,
   density : number, // optional,
   front_solar_absorbtance : number, // optional,
   back_solar_absorbtance : number, // optional,
   solar_transmittance : number, // optional,
   front_visible_reflectance : number, // optional,
   back_visible_reflectance : number, // optional,
   visible_transmissivity : number, // optional,
   front_thermal_absorbtance : number, // optional,
   back_thermal_absorbtance : number, // optional,
}

name

The name of the Substance. Should be unique for each Substance in the Model object

thermal_conductivity (optional)

The thermal conductivity of the substance in W/m.K

specific_heat_capacity (optional)

The specific heat capacity of the substance in J/kg.K

density (optional)

The density of the substance in kg/m3

front_solar_absorbtance (optional)

Solar absorbtance (from 0 to 1) at the front side (Front being the side closer to the first material in a construction)

Absorbtance is used instead of reflectance (which is used in visible radiation properties) to maintain coherence with EnergyPlus

back_solar_absorbtance (optional)

Solar absorbtance (from 0 to 1) at the front side (Back being the side closer to the last material in a construction)

Absorbtance is used instead of reflectance (which is used in visible radiation properties) to maintain coherence with EnergyPlus... because in Thermal calculation we mostly care about how much is absorbed; in lighting we care mainly about how much is reflected.

solar_transmittance (optional)

The front solar transmittance at normal incidence (from 0 to 1)

Please note that, contrary to all other properties, this property does depend on the thickness of the substance. So, in order to build a coherent Glazing, you'll need to match this Substance with an appropriate Material

Transmittance is used instead of transmissivity (which is used in visible radiation properties) to maintain coherence with EnergyPlus... because in Thermal calculation we mostly care about how much is absorbed; in lighting we care mainly about how much is reflected.

front_visible_reflectance (optional)

Solar absorbtance (from 0 to 1) at the front side (Front being the side closer to the first material in a construction)

Reflectance is used instead of Absorbtance (which is used in solar radiation properties) to maintain coherence with Radiance... because in Lighting we really care about how much is reflected; in thermal we care mainly about how much is absorbed.

back_visible_reflectance (optional)

Solar absorbtance (from 0 to 1) at the front side (Back being the side closer to the last material in a construction)

Reflectance is used instead of Absorbtance (which is used in solar radiation properties) to maintain coherence with Radiance... because in Lighting we really care about how much is reflected; in thermal we care mainly about how much is absorbed.

visible_transmissivity (optional)

The front solar transmittance at normal incidence (from 0 to 1)

Please note that, contrary to all other properties, this property does depend on the thickness of the substance. So, in order to build a coherent Glazing, you'll need to match this Substance with an appropriate Material

Transmissivity is used instead of Transmittance (which is used in solar radiation properties) to maintain coherence with Radiance

front_thermal_absorbtance (optional)

Front thermal absorbtance (i.e., emissitivy; from 0 to 1) (Front being the side closer to the first material in a construction)

back_thermal_absorbtance (optional)

Back thermal absorbtance (i.e., emissitivy; from 0 to 1) (Back being the side closer to the last material in a construction)

Gas

Represents a Gas, as understood by the standard ISO-15099(2003).

Examples

.spl

Substance {
    type: "Gas",
    name: "Some Gas",
    gas: "Xenon"
}

.json

{
    "type": "Gas",
    "name": "Some Gas",
    "gas": "Xenon"
}

Full Specification

Gas {
   name : string,
   gas : GasSpecification, // optional,
}

name

The name of the Substance. Should be unique for each Substance in the Model object

gas (optional)

A predefined gas

GasSpecification

Represent a common gas, with known physical properties

Examples

.json

"Air"

Note: This object cannot be declared by itself in a SIMPLE model, as it is always embeded on a Substance of type Gas

Supported Variants

Air

Air

Full Specification

"Air"

Argon

Argon

Full Specification

"Argon"

Krypton

Krypton

Full Specification

"Krypton"

Xenon

Xenon

Full Specification

"Xenon"

ShelterClass

Indicates how sheltered is the building. This affects its infiltration

Examples

.json

"Urban"

Note: This object cannot be declared by itself in a SIMPLE model, as it is always embeded on a Building object

Supported Variants

NoObstructions

No obstructions or local shielding

Full Specification

"NoObstructions"

IsolatedRural

Typical shelter for an isolated rural house

Full Specification

"IsolatedRural"

Urban

Typical shelter caused by other buildings across the street

Full Specification

"Urban"

LargeLotUrban

Typical shelter for urban buildings on larger lots

Full Specification

"LargeLotUrban"

SmallLotUrban

Typical shelter produced by buildings that are immediately adjacent.

Full Specification

"SmallLotUrban"

Surface

A fixed (i.e., not movable) surface in the building (or surroundings). This can be of any Construction, transparent or not.

Examples

.spl

// This should not be empty
Construction {
    name: "the construction",
    materials: []
}
Surface {
    name: "the surface",
    construction:"the construction", 
    vertices: [ 
        0, 0, 0, // X, Y and Z of Vertex 0
        1, 0, 0, // X, Y and Z of Vertex 1
        1, 1, 0, // X, Y and Z of Vertex 2
        0, 1, 0  // ... 
    ]
}

.json

{
    "name": "the surface",
    "construction":"the construction", 
    "vertices": [ 
        0, 0, 0, 
        1, 0, 0, 
        1, 1, 0, 
        0, 1, 0  
    ]
}

Full Specification

Surface {
   name : string,
   vertices : Polygon3D,
   construction : string,
   front_boundary : Boundary,
   back_boundary : Boundary,
   category : SurfaceType, // optional,
   precalculated_front_convection_coef : number, // optional,
   precalculated_back_convection_coef : number, // optional,
}

name

The name of the surface

vertices

An array of Numbers representing the vertices of the surface. The length of this array must be divisible by 3.

construction

The name of the construction in the Model's Construction array

front_boundary

The Boundary in front of the Surface

back_boundary

The Boundary in back of the Surface

category (optional)

The Surface Category.

This field does not affect the simulations, as it was designed to be used based on conventions (see [SurfaceType] documentation). So, if no [SurfaceType] is assigned, we cannot tell you what to do.

precalculated_front_convection_coef (optional)

The front convection coefficient, in W/m2K

This value fixes the value, so the automatic calculations in SIMPLE have no effect.

precalculated_back_convection_coef (optional)

The back convection coefficient, in W/m2K

This value fixes the value, so the automatic calculations in SIMPLE have no effect.

API Access

// by name
let my_surface = surface(string);
// by index
let my_surface = surface(int);

API

The following properties are available for simulating control algorithms

SurfaceType

The kind of surface, useful for pre- and post-processing.

This information does not affect the simulation outcome. For example, SIMPLE will decide whether a wall is interior or exterior based on the boundaries, and will not check these labels. However, these labels can be useful for creating measures (e.g., insulate all the exterior walls)

Example

.json

"ExteriorWall"

Supported Variants

ExteriorWall

A Wall that connects a space with the exterior.

Full Specification

"ExteriorWall"

InteriorWall

A Wall connecting two spaces

Full Specification

"InteriorWall"

GroundFloor

A useful horizontal surface that touches the ground

Full Specification

"GroundFloor"

ExteriorFloor

A floor that leads to the exterior (e.g., a floor suspended by columns)

Full Specification

"ExteriorFloor"

InteriorFloor

Floor/ceiling that connects two spaces, and whose area is part of the
building or project being modelled. For instance, the top ceiling of an apartment is often, strictly speaking, an interior floor... but it is not part of the sellable area of the apartment itself

Full Specification

"InteriorFloor"

Ceiling

A floor/ceiling that connect two spaces, but whose area is not part of the area of the project/building (see the InteriorFloor variant).

Full Specification

"Ceiling"

Roof

A surfaces at the top of a building

Full Specification

"Roof"

Other

Other kind of surface

Full Specification

"Other"

TableShape

Shape of a table

Supported Variants

Other

Other kind of table

Full Specification

"Other"

Rectangular

Rectangular

Full Specification

"Rectangular"

Circular

Circular

Full Specification

"Circular"

LShaped

L-Shaped

Full Specification

"LShaped"

TableType

Type of a table

Supported Variants

Other

Other kind of table

Full Specification

"Other"

Dining

Dining table

Full Specification

"Dining"

Coffee

Cofee table

Full Specification

"Coffee"

TerrainClass

This class modifies the wind speed in the site

Supported Variants

Country

Describes a Flat, Open Country

Full Specification

"Country"

Suburbs

Describes a Rough, Wooded Country or Suburb

Full Specification

"Suburbs"

City

Describes Towns, City Outskirts, and centers of large cities

Full Specification

"City"

Ocean

Describes sites next to the Ocean or Bayou Flat

Full Specification

"Ocean"

Urban

Describes Urban, Industrual or Forest terrain

Full Specification

"Urban"