# PluginTEASER
The [TEASER Plugin](PluginTEASER) is one the two currently implemented
[Plugins](Plugin) for building performance simulation (BPS). It uses the open
source tool [TEASER](https://github.com/RWTH-EBC/TEASER) as backend to export
Modelica simulation models based on the input IFC data. For a detailed insight
how TEASER works please have a look at the [documentation](http://rwth-ebc.github.io/TEASER/)
of TEASER. The exported simulation models can be simulated using the open source
library [AixLib](https://github.com/RWTH-EBC/AixLib). Following you will find 
some information how TEASER addresses the challenges of automated building 
simulation.

(HowtoInstallTeaser)=
## How to install?

### Step by step
To install `PluginTEASER`: you need to do the following
(in the root directory of the repo, here is the pyproject.toml file)
```shell
pip install -e '.[PluginTEASER]'
```
The [bim2sim core installation](coreInstalltion) needs to be done before.

### Test install


## Structure of the plugin

The following figure shows the structure of the TEASER plugin. Here you see which tasks are used and how they are combined.
<!--- 
the following code is pasted from the a file from /bim2sim/docs/source/img/dynamic/plugindiagram
this figure is generated by the function generate_plugin_structure_fig in file template_mermaid.py
-->

(Hint: firefox has issue display mermaid figures completely, for more infos see
issue [#766](https://github.com/BIM2SIM/bim2sim/issues/766))
```{mermaid}
---
title: plugin TEASER
---
flowchart TB
    
subgraph taskLoadIFC["task LoadIFC"]
 subgraph "" 

  tLoadIFC["bim2sim > tasks > common >  
 LoadIFC"]
  extLoadIFC(" Load all IFC files from PROJECT. " )
 end

stateLoadIFC[("state
 (reads/touches)")]
    
tLoadIFC -- ifc_files --> stateLoadIFC

end
    
subgraph taskCheckIfc["task CheckIfc"]
 subgraph "" 

  tCheckIfc["bim2sim > tasks > common >  
 CheckIfc"]
  extCheckIfc("  Check an IFC file, for a number of conditions
(missing information, incorrect information, etc)
that could lead on future tasks to fatal errors. " )
 end

stateCheckIfc[("state
 (reads/touches)")]
    
stateCheckIfc -- ifc_files --> tCheckIfc
direction RL
end
    
subgraph taskCreateElements["task CreateElements"]
 subgraph "" 

  tCreateElements["bim2sim > tasks > common >  
 CreateElements"]
  extCreateElements(" Create bim2sim elements based on information in
IFC. " )
 end

stateCreateElements[("state
 (reads/touches)")]
    
stateCreateElements -- ifc_files --> tCreateElements

tCreateElements -- elements, ifc_files --> stateCreateElements

end
    
subgraph taskCreateSpaceBoundaries["task CreateSpaceBoundaries"]
 subgraph "" 

  tCreateSpaceBoundaries["bim2sim > tasks > bps >  
 CreateSpaceBoundaries"]
  extCreateSpaceBoundaries(" Create space boundary elements from ifc. " )
 end

stateCreateSpaceBoundaries[("state
 (reads/touches)")]
    
stateCreateSpaceBoundaries -- ifc_files, elements --> tCreateSpaceBoundaries

tCreateSpaceBoundaries -- space_boundaries --> stateCreateSpaceBoundaries

end
    
subgraph taskCorrectSpaceBoundaries["task CorrectSpaceBoundaries"]
 subgraph "" 

  tCorrectSpaceBoundaries["bim2sim > tasks > bps >  
 CorrectSpaceBoundaries"]
  extCorrectSpaceBoundaries(" Advanced geometric preprocessing for Space
Boundaries. " )
 end

stateCorrectSpaceBoundaries[("state
 (reads/touches)")]
    
stateCorrectSpaceBoundaries -- elements, space_boundaries --> tCorrectSpaceBoundaries
direction RL
end
    
subgraph taskAddSpaceBoundaries2B["task AddSpaceBoundaries2B"]
 subgraph "" 

  tAddSpaceBoundaries2B["bim2sim > tasks > bps >  
 AddSpaceBoundaries2B"]
  extAddSpaceBoundaries2B(" Fill gaps in set of space boundary per space with
2B space boundaries. " )
 end

stateAddSpaceBoundaries2B[("state
 (reads/touches)")]
    
stateAddSpaceBoundaries2B -- elements --> tAddSpaceBoundaries2B

tAddSpaceBoundaries2B -- elements --> stateAddSpaceBoundaries2B

end
    
subgraph taskFilterTZ["task FilterTZ"]
 subgraph "" 

  tFilterTZ["bim2sim > tasks > bps >  
 FilterTZ"]
  extFilterTZ(" Filters the thermal zones for later usage and
stores them in state. " )
 end

stateFilterTZ[("state
 (reads/touches)")]
    
stateFilterTZ -- elements --> tFilterTZ

tFilterTZ -- tz_elements --> stateFilterTZ

end
    
subgraph taskBindStoreys["task BindStoreys"]
 subgraph "" 

  tBindStoreys["bim2sim > tasks > common >  
 BindStoreys"]
  extBindStoreys(" None. " )
 end

stateBindStoreys[("state
 (reads/touches)")]
    
stateBindStoreys -- elements --> tBindStoreys

tBindStoreys -- elements --> stateBindStoreys

end
    
subgraph taskEnrichUseConditions["task EnrichUseConditions"]
 subgraph "" 

  tEnrichUseConditions["bim2sim > tasks > bps >  
 EnrichUseConditions"]
  extEnrichUseConditions(" Enriches Use Conditions of thermal zones based on
decisions and translation of zone names. " )
 end

stateEnrichUseConditions[("state
 (reads/touches)")]
    
stateEnrichUseConditions -- tz_elements --> tEnrichUseConditions

tEnrichUseConditions -- enriched_tz --> stateEnrichUseConditions

end
    
subgraph taskVerifyLayersMaterials["task VerifyLayersMaterials"]
 subgraph "" 

  tVerifyLayersMaterials["bim2sim > tasks > bps >  
 VerifyLayersMaterials"]
  extVerifyLayersMaterials(" Verifies if layers and materials and their
properties are meaningful. " )
 end

stateVerifyLayersMaterials[("state
 (reads/touches)")]
    
stateVerifyLayersMaterials -- elements --> tVerifyLayersMaterials

tVerifyLayersMaterials -- invalid --> stateVerifyLayersMaterials

end
    
subgraph taskEnrichMaterial["task EnrichMaterial"]
 subgraph "" 

  tEnrichMaterial["bim2sim > tasks > bps >  
 EnrichMaterial"]
  extEnrichMaterial(" Enriches material properties that were recognized
as invalid LOD. " )
 end

stateEnrichMaterial[("state
 (reads/touches)")]
    
stateEnrichMaterial -- elements, invalid --> tEnrichMaterial

tEnrichMaterial -- elements --> stateEnrichMaterial

end
    
subgraph taskDisaggregationCreation["task DisaggregationCreation"]
 subgraph "" 

  tDisaggregationCreation["bim2sim > tasks > bps >  
 DisaggregationCreation"]
  extDisaggregationCreation(" Disaggregates building elements based on their
space boundaries. " )
 end

stateDisaggregationCreation[("state
 (reads/touches)")]
    
stateDisaggregationCreation -- elements --> tDisaggregationCreation

tDisaggregationCreation -- disaggregations --> stateDisaggregationCreation

end
    
subgraph taskCombineThermalZones["task CombineThermalZones"]
 subgraph "" 

  tCombineThermalZones["bim2sim > tasks > bps >  
 CombineThermalZones"]
  extCombineThermalZones(" Combine thermal zones to reduce the amount of
thermal zones. " )
 end

stateCombineThermalZones[("state
 (reads/touches)")]
    
stateCombineThermalZones -- tz_elements, elements --> tCombineThermalZones

tCombineThermalZones -- bounded_tz --> stateCombineThermalZones

end
    
subgraph taskWeather["task Weather"]
 subgraph "" 

  tWeather["bim2sim > tasks > common >  
 Weather"]
  extWeather(" Task to get the weather file for later simulation. " )
 end

stateWeather[("state
 (reads/touches)")]
    
stateWeather -- elements --> tWeather

tWeather -- weather_file --> stateWeather

end
    
subgraph taskLoadLibrariesTEASER["task LoadLibrariesTEASER"]
 subgraph "" 

  tLoadLibrariesTEASER[" 
 LoadLibrariesTEASER"]
  extLoadLibrariesTEASER(" Load AixLib library for export. " )
 end

stateLoadLibrariesTEASER[("state
 (reads/touches)")]
    
tLoadLibrariesTEASER -- libraries --> stateLoadLibrariesTEASER

end
    
subgraph taskCreateTEASER["task CreateTEASER"]
 subgraph "" 

  tCreateTEASER["bim2sim > plugins > PluginTEASER > 
bim2sim_teaser > task >  
 CreateTEASER"]
  extCreateTEASER(" Creates a TEASER project by using the found
information from IFC. " )
 end

stateCreateTEASER[("state
 (reads/touches)")]
    
stateCreateTEASER -- libraries, elements, weather_file --> tCreateTEASER

tCreateTEASER -- teaser_prj, bldg_names, orig_heat_loads, orig_cool_loads, tz_mapping --> stateCreateTEASER

end
    
subgraph taskSerializeElements["task SerializeElements"]
 subgraph "" 

  tSerializeElements["bim2sim > tasks > common >  
 SerializeElements"]
  extSerializeElements(" Serialize element structure, run() method holds
detailed information. " )
 end

stateSerializeElements[("state
 (reads/touches)")]
    
stateSerializeElements -- elements, space_boundaries, tz_elements --> tSerializeElements

tSerializeElements -- serialized_elements --> stateSerializeElements

end
    
subgraph taskExportTEASER["task ExportTEASER"]
 subgraph "" 

  tExportTEASER["bim2sim > plugins > PluginTEASER > 
bim2sim_teaser > task >  
 ExportTEASER"]
  extExportTEASER(" Exports the previous created TEASER project to
Modelica. " )
 end

stateExportTEASER[("state
 (reads/touches)")]
    
stateExportTEASER -- teaser_prj --> tExportTEASER

tExportTEASER -- teaser_prj --> stateExportTEASER

end
    
subgraph taskSimulateModelEBCPy["task SimulateModelEBCPy"]
 subgraph "" 

  tSimulateModelEBCPy["bim2sim > plugins > PluginTEASER > 
bim2sim_teaser > task >  
 SimulateModelEBCPy"]
  extSimulateModelEBCPy(" None. " )
 end

stateSimulateModelEBCPy[("state
 (reads/touches)")]
    
stateSimulateModelEBCPy -- bldg_names --> tSimulateModelEBCPy

tSimulateModelEBCPy -- teaser_mat_result_paths, sim_results_path --> stateSimulateModelEBCPy

end
    
subgraph taskCreateResultDF["task CreateResultDF"]
 subgraph "" 

  tCreateResultDF["bim2sim > plugins > PluginTEASER > 
bim2sim_teaser > task >  
 CreateResultDF"]
  extCreateResultDF(" This ITask creates a result dataframe for TEASER
BEPS simulations. " )
 end

stateCreateResultDF[("state
 (reads/touches)")]
    
stateCreateResultDF -- teaser_mat_result_paths, sim_results_path, tz_mapping --> tCreateResultDF

tCreateResultDF -- df_finals --> stateCreateResultDF

end
    
subgraph taskPlotBEPSResults["task PlotBEPSResults"]
 subgraph "" 

  tPlotBEPSResults["bim2sim > tasks > bps >  
 PlotBEPSResults"]
  extPlotBEPSResults(" Plots the results for BEPS simulations. " )
 end

statePlotBEPSResults[("state
 (reads/touches)")]
    
statePlotBEPSResults -- df_finals, sim_results_path, ifc_files --> tPlotBEPSResults
direction RL
end
    taskLoadIFC --> taskCheckIfc 
taskCheckIfc --> taskCreateElements 
taskCreateElements --> taskCreateSpaceBoundaries 
taskCreateSpaceBoundaries --> taskCorrectSpaceBoundaries 
taskCorrectSpaceBoundaries --> taskAddSpaceBoundaries2B 
taskAddSpaceBoundaries2B --> taskFilterTZ 
taskFilterTZ --> taskBindStoreys 
taskBindStoreys --> taskEnrichUseConditions 
taskEnrichUseConditions --> taskVerifyLayersMaterials 
taskVerifyLayersMaterials --> taskEnrichMaterial 
taskEnrichMaterial --> taskDisaggregationCreation 
taskDisaggregationCreation --> taskCombineThermalZones 
taskCombineThermalZones --> taskWeather 
taskWeather --> taskLoadLibrariesTEASER 
taskLoadLibrariesTEASER --> taskCreateTEASER 
taskCreateTEASER --> taskSerializeElements 
taskSerializeElements --> taskExportTEASER 
taskExportTEASER --> taskSimulateModelEBCPy 
taskSimulateModelEBCPy --> taskCreateResultDF 
taskCreateResultDF --> taskPlotBEPSResults 
```

This figure is generated by the script template_mermaid.py (see [Visualization of bim2sim plugin structure](genVisPlugins)).



## How to create a project?

## How to load an IFC file?

## How to configure my project?

### Simulation settings

### Configuration file

### Default tasks

### Additional templates

## How to run the project?

## How to run the simulation?

## How to analyze the project?

### What kind of results exist?
### What programs/tools to use for further analysis?

## Enrichment
See [Enrichment](advanced-user-guide/concepts/enrichment.md).

## Space Boundary Usage

Currently, TEASER prefers the semantic input from IFC data to get important data
like the area of walls. But as these information often are not correct or not
existing TEASER uses also the information provided by space boundaries. The
space boundaries are also mandatory for Zoning, see below. With growing quality
of IFC exports in authoring tools we might see complete IFCs with all semantic
information needed to parametrize a BPS. At this point TEASEr will allow
the creation of a single zone simulation model without the need of Space
Boundaries, as the space boundaries are only needed for zoning in this case.

## Zoning

As TEASERs simulation core offers multizone simulation models, but each zone is
adiabatic and interacts only with the environment but the zones don't interact
with each other. Even if just putting every room into one thermalzone might be
easy but not sensible as shown
in [this paper](https://doi.org/10.3384/ecp21181665).

As the zoning of simulation models is a time-consuming task we decided to
automate it with the task (BindThermalZones)[BindThermalZones].
We do this by giving the user multiple criteria to select from:

* External/Internal
* Orientation
* Usage
* Window to wall ratio

To create those zones we first need to [disaggregate](Disaggregations) the
elements
of each room based on 2nd level space boundaries and put them together again
afterwards.

### External/Internal

By selecting this criteria all zones with contact to the environment will
be in one group and all rooms without contact in the other.

### Orientation

This groups the zones into two groups, south-west orientated and
north-east orientated zones. This is useful as the south-west group is
exposed to solar radiation at a high level, while the north-east group will have
only negligible solar radiation input. Mixing both groups together can lead to
misleading results regarding peak loads as loads are smoothed out.

### Usage

This groups the zones based on the usage type of each room. bim2sim tries to
estimate the usage of each room based on the name of the room and multiple IFC
properties which might be set by the authoring tool. If the usage can't be found
a [Decision](Decisions) will be triggered to get the correct usage.

### Window to wall ratio

With this criteria the zones are grouped into 4 groups based on their window to
wall ratio or glass percentage:

* 0 - 30 %
* 30 - 50 %
* 50 - 70 %
* 70 - 100 %
This is useful as rooms with high glass percentage will have less thermal mass
and inertia and higher solar radiation input which makes their dynamic
different from the ones with low glass percentage.