# PluginEnergyPlus

(HowtoInstallEP)=
## How to install?

### Step by step

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

### Trouble Shooting
For python > 3.9: make sure that the correct geomeppy is installed (using requirements.txt in the plugin): in this fork of geomeppy, we fixed the imports working from python >= 3.10: https://github.com/BIM2SIM/geomeppy/tree/fix_dependencies

### Test install


## Structure of the plugin

The following figure shows the structure of the EnergyPlus 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 EnergyPlus
---
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 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 taskCreateIdf["task CreateIdf"]
 subgraph "" 

  tCreateIdf["bim2sim > plugins > PluginEnergyPlus > 
bim2sim_energyplus > task >  
 CreateIdf"]
  extCreateIdf(" Create an EnergyPlus Input file. " )
 end

stateCreateIdf[("state
 (reads/touches)")]
    
stateCreateIdf -- elements, weather_file --> tCreateIdf

tCreateIdf -- idf, sim_results_path --> stateCreateIdf

end
    
subgraph taskIdfPostprocessing["task IdfPostprocessing"]
 subgraph "" 

  tIdfPostprocessing["bim2sim > plugins > PluginEnergyPlus > 
bim2sim_energyplus > task >  
 IdfPostprocessing"]
  extIdfPostprocessing(" None. " )
 end

stateIdfPostprocessing[("state
 (reads/touches)")]
    
stateIdfPostprocessing -- elements, idf, ifc_files, sim_results_path --> tIdfPostprocessing
direction RL
end
    
subgraph taskExportIdfForCfd["task ExportIdfForCfd"]
 subgraph "" 

  tExportIdfForCfd["bim2sim > plugins > PluginEnergyPlus > 
bim2sim_energyplus > task >  
 ExportIdfForCfd"]
  extExportIdfForCfd(" Export Idf shapes as . " )
 end

stateExportIdfForCfd[("state
 (reads/touches)")]
    
stateExportIdfForCfd -- elements, idf --> tExportIdfForCfd
direction RL
end
    
subgraph taskRunEnergyPlusSimulation["task RunEnergyPlusSimulation"]
 subgraph "" 

  tRunEnergyPlusSimulation["bim2sim > plugins > PluginEnergyPlus > 
bim2sim_energyplus > task >  
 RunEnergyPlusSimulation"]
  extRunEnergyPlusSimulation(" None. " )
 end

stateRunEnergyPlusSimulation[("state
 (reads/touches)")]
    
stateRunEnergyPlusSimulation -- idf, sim_results_path --> tRunEnergyPlusSimulation
direction RL
end
    
subgraph taskCreateResultDF["task CreateResultDF"]
 subgraph "" 

  tCreateResultDF["bim2sim > plugins > PluginEnergyPlus > 
bim2sim_energyplus > task >  
 CreateResultDF"]
  extCreateResultDF(" This ITask creates a result dataframe for
EnergyPlus BEPS simulations. " )
 end

stateCreateResultDF[("state
 (reads/touches)")]
    
stateCreateResultDF -- idf, sim_results_path --> 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 --> taskWeather 
taskWeather --> taskCreateIdf 
taskCreateIdf --> taskIdfPostprocessing 
taskIdfPostprocessing --> taskExportIdfForCfd 
taskExportIdfForCfd --> taskRunEnergyPlusSimulation 
taskRunEnergyPlusSimulation --> 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?


#TODO
Copy to correct positions:

[Go to EnergyPlus specific tasks](EnergyPlus_specific_tasks)
[Go to EnergyPlusSimSettings](EnergyPlus_sim_settings)

The Plugin EnergyPlus exports the preprocessed IFC data to en EnergyPlus 
Input file (idf). This Plugin contains EnergyPlus specific modifications of 
the geometry and further enrichment for the export. General simulation 
control settings are set here as well as the output variables.


Other IFC requirements (optional, improve model accuracy):
* Material definitions
* Shading Space Boundaries

The Plugin consists of multiple individual tasks that are executed 
consecutively. The default tasks are defined in the PluginEnergyPlus class. 
These tasks can be split in two main blocks: general preparation tasks that 
are used for both BPS workflows (TEASER and EnergyPlus) and EnergyPlus 
specific tasks.

* general tasks (common and BPS-specific):
  * [LoadIFC](LoadIFC)
  * [CreateElements](CreateElements)
  * [CreateSpaceBoundaries](CreateSpaceBoundaries)
  * [Prepare](Prepare)
  * [BindStoreys](BindStoreys)
  * [EnrichUseConditions](EnrichUseConditions)
  * [Verification](Verification)
  * [EnrichMaterial](EnrichMaterial)
  * [DisaggregationCreation](DisaggregationCreation)
  * [BindThermalZones](BindThermalZones)
* EnergyPlus specific tasks:
  * [IfcValidation](ep_ifc_valid)
  * [EPGeomPreprocessing](ep_geom_preproc)
  * [AddSpaceBoundaries2B](ep_add_2b_sbs)
  * [WeatherEnergyPlus](ep_set_weather)
  * [CreateIdf](ep_create_idf_for_export)
  * [IdfPostprocessing](ep_postprocess)
  * [ExportIdfForCfd](ep_cfd_export)
  * [RunEnergyPlusSimulation](ep_run_sim)

(EnergyPlus_specific_tasks)=
## EnergyPlus specific tasks

### Validation of the IFC file 
(ep_ifc_valid)=
[Go to IfcValidation](IfcValidation)

The EnergyPlus specific tasks start with an EnergyPlus specific validation 
of the space boundaries provided by the IFC file. This validation algorihtm 
is included in the default workflow to give an insight in the quality of the 
provided IFC.

### Geometric Preprocessing for EnergyPlus Export
(ep_geom_preproc)=
[Go to EPGeomPreprocessing](EPGeomPreprocessing)

The preprocessed geometry and material needs an additional preprocessing to 
cover all requirements for the EnergyPlus export. This is done in the 
[EPGeomPreprocessing](EPGeomPreprocessing). The space boundaries which are 
further used to model the building geometry are [added](add_bounds_to_elements) 
to the elements. Minor geometric displacements are fixed by 
[moving children to their parents](move_children_to_parents). This covers all 
cases, where opening space boundaries are displaced by the thickness of the wall.
The surface orientation is [fixed](fix_surface_orientation) if needed 
(all surface normals are supposed to point outwards the relating space). To
improve shading calculations and remove inner loops from surfaces, 
[non-convex space boundaries can be split up](split_non_convex_bounds). Similarly,
[shadings can be added and split if needed](add_and_split_bounds_for_shadings). 

Use the [settings](settings) to decide if boundaries should be split up and
if shadings should be added.

### Add 2b Space Boundaries
(ep_add_2b_sbs)=
[Go to AddSpaceBoundaries2B](AddSpaceBoundaries2B)

Space Boundaries of type 2b can be added here if gaps are located in the 
provided set of space boundaries. The resulting set of space boundaries
then forms a watertight model that can be further used for other simulation
purposes such as [CFD export](ExportIdfForCfd).

### Set the Weather File
(ep_set_weather)=
[Go to WeatherEnergyPlus](WeatherEnergyPlus)

Set the Weather File for the EnergyPlus Simulation. 

### Initialize and Export the EnergyPlus IDF File 
(ep_create_idf_for_export)=
[Go to CreateIdf](CreateIdf)

Write all preprocessed geometric data, materials, and boundary conditions
to an EnergyPlus input file (IDF). 

### IDF Postprocessing
(ep_postprocess)=
[Go to IdfPostprocessing](IdfPostprocessing)

Export data to csv. Some modifications may be required to meet your 
individual postprocessing needs here. 

### Export IDF Geometry for CFD Processing
(ep_cfd_export)=
[Go to ExportIdfForCfd](ExportIdfForCfd)

Use the [settings](settings) to specify, if the IDF geometry should be
converted to .stl for further use in CFD applications. 

### Run EnergyPlus Simulation
(ep_run_sim)=
[Go to RunEnergyPlusSimulation](RunEnergyPlusSimulation)

Run the EnergyPlus simulation. Use the [settings](settings) for further
runtime specifications. 


## EnergyPlusSimSettings

EnergyPlus has its own set of EnergyPlus specific 
[Simulation Settings](simulation_setting) that can be found here:

[Go to EnergyPlusSimSettings](EnergyPlus_sim_settings)