PluginOpenFOAM

How to install?

Step by step

To install PluginOpenFOAM: you need to do the following (in the root directory of the repo, here is the pyproject.toml file)

pip install -e '.[PluginOpenFOAM]'

The bim2sim core installation as well as the installation of the EnergyPlus plugin 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

To test the installation, open a Python Interactive Shell and try importing the module:

import bim2sim.plugins.PluginOpenFOAM

Unless you receive an error message, the plugin was installed successfully.

Examples

Please also take a look at bim2sim/plugins/PluginOpenFOAM/bim2sim_openfoam/examples, which provides some runnable examples for the OpenFOAM plugin. You can use these examples to test your installation and learn from them. Additionally, they serve as good starting points for your own projects.

Structure of the plugin

The following figure shows the structure of the OpenFOAM plugin. Here you see which tasks are used and how they are combined.

(Hint: firefox has issue display mermaid figures completely, for more infos see issue #766)

Flowchart of the plugin (Mermaid Figure)

        ---
title: plugin openfoam
---
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 taskCreateElementsOnIfcTypes["task CreateElementsOnIfcTypes"]
 subgraph "" 

  tCreateElementsOnIfcTypes["bim2sim > tasks > common >  
 CreateElementsOnIfcTypes"]
  extCreateElementsOnIfcTypes(" Create bim2sim elements based on information of
IFC types. " )
 end

stateCreateElementsOnIfcTypes[("state
 (reads/touches)")]
    
stateCreateElementsOnIfcTypes -- ifc_files --> tCreateElementsOnIfcTypes

tCreateElementsOnIfcTypes -- elements, _initial_elements, ifc_files --> stateCreateElementsOnIfcTypes

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
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 taskCorrectSpaceBoundaries["task CorrectSpaceBoundaries"]
 subgraph "" 

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

stateCorrectSpaceBoundaries[("state
 (reads/touches)")]
    
stateCorrectSpaceBoundaries -- elements --> tCorrectSpaceBoundaries
direction RL
end
    
subgraph taskCreateRelations["task CreateRelations"]
 subgraph "" 

  tCreateRelations["bim2sim > tasks > common >  
 CreateRelations"]
  extCreateRelations(" Relations of elements, run() method holds detailed
information. " )
 end

stateCreateRelations[("state
 (reads/touches)")]
    
stateCreateRelations -- elements --> tCreateRelations
direction RL
end
    
subgraph taskDisaggregationCreationAndTypeCheck["task DisaggregationCreationAndTypeCheck"]
 subgraph "" 

  tDisaggregationCreationAndTypeCheck["bim2sim > tasks > bps >  
 DisaggregationCreationAndTypeCheck"]
  extDisaggregationCreationAndTypeCheck(" Disaggregation of elements, run() method holds
detailed information. " )
 end

stateDisaggregationCreationAndTypeCheck[("state
 (reads/touches)")]
    
stateDisaggregationCreationAndTypeCheck -- elements --> tDisaggregationCreationAndTypeCheck
direction RL
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 --> tEnrichMaterial
direction RL
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 -- elements --> tEnrichUseConditions
direction RL
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 taskComfortSettings["task ComfortSettings"]
 subgraph "" 

  tComfortSettings["bim2sim > plugins > PluginComfort > 
bim2sim_comfort > task >  
 ComfortSettings"]
  extComfortSettings("  Create Comfort Settings for an EnergyPlus Input
file. " )
 end

stateComfortSettings[("state
 (reads/touches)")]
    
stateComfortSettings -- elements, idf, sim_results_path --> tComfortSettings

tComfortSettings -- idf --> stateComfortSettings

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 --> tSerializeElements

tSerializeElements -- serialized_elements --> stateSerializeElements

end
    
subgraph taskRunEnergyPlusSimulation["task RunEnergyPlusSimulation"]
 subgraph "" 

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

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

  tInitializeOpenFOAMSetup["bim2sim > plugins > PluginOpenFOAM > 
bim2sim_openfoam > task >  
 InitializeOpenFOAMSetup"]
  extInitializeOpenFOAMSetup(" This ITask initializes the OpenFOAM Setup. " )
 end

stateInitializeOpenFOAMSetup[("state
 (reads/touches)")]
    
tInitializeOpenFOAMSetup -- openfoam_case --> stateInitializeOpenFOAMSetup

end
    
subgraph taskCreateOpenFOAMGeometry["task CreateOpenFOAMGeometry"]
 subgraph "" 

  tCreateOpenFOAMGeometry["bim2sim > plugins > PluginOpenFOAM > 
bim2sim_openfoam > task >  
 CreateOpenFOAMGeometry"]
  extCreateOpenFOAMGeometry(" This ITask initializes the OpenFOAM Geometry. " )
 end

stateCreateOpenFOAMGeometry[("state
 (reads/touches)")]
    
stateCreateOpenFOAMGeometry -- openfoam_case, elements --> tCreateOpenFOAMGeometry

tCreateOpenFOAMGeometry -- openfoam_case, openfoam_elements --> stateCreateOpenFOAMGeometry

end
    
subgraph taskAddOpenFOAMComfort["task AddOpenFOAMComfort"]
 subgraph "" 

  tAddOpenFOAMComfort["bim2sim > plugins > PluginOpenFOAM > 
bim2sim_openfoam > task >  
 AddOpenFOAMComfort"]
  extAddOpenFOAMComfort(" This ITask adds the openfoam comfort settings. " )
 end

stateAddOpenFOAMComfort[("state
 (reads/touches)")]
    
stateAddOpenFOAMComfort -- openfoam_case --> tAddOpenFOAMComfort
direction RL
end
    
subgraph taskCreateOpenFOAMMeshing["task CreateOpenFOAMMeshing"]
 subgraph "" 

  tCreateOpenFOAMMeshing["bim2sim > plugins > PluginOpenFOAM > 
bim2sim_openfoam > task >  
 CreateOpenFOAMMeshing"]
  extCreateOpenFOAMMeshing(" This ITask initializes the OpenFOAM Meshing. " )
 end

stateCreateOpenFOAMMeshing[("state
 (reads/touches)")]
    
stateCreateOpenFOAMMeshing -- openfoam_case, openfoam_elements --> tCreateOpenFOAMMeshing

tCreateOpenFOAMMeshing -- openfoam_case, openfoam_elements --> stateCreateOpenFOAMMeshing

end
    
subgraph taskSetOpenFOAMBoundaryConditions["task SetOpenFOAMBoundaryConditions"]
 subgraph "" 

  tSetOpenFOAMBoundaryConditions["bim2sim > plugins > PluginOpenFOAM > 
bim2sim_openfoam > task >  
 SetOpenFOAMBoundaryConditions"]
  extSetOpenFOAMBoundaryConditions(" This ITask initializes the OpenFOAM Setup. " )
 end

stateSetOpenFOAMBoundaryConditions[("state
 (reads/touches)")]
    
stateSetOpenFOAMBoundaryConditions -- openfoam_elements, openfoam_case --> tSetOpenFOAMBoundaryConditions

tSetOpenFOAMBoundaryConditions -- openfoam_case, openfoam_elements --> stateSetOpenFOAMBoundaryConditions

end
    
subgraph taskRunOpenFOAMMeshing["task RunOpenFOAMMeshing"]
 subgraph "" 

  tRunOpenFOAMMeshing["bim2sim > plugins > PluginOpenFOAM > 
bim2sim_openfoam > task >  
 RunOpenFOAMMeshing"]
  extRunOpenFOAMMeshing(" This ITask runs the openfoam meshing on linux
systems. " )
 end

stateRunOpenFOAMMeshing[("state
 (reads/touches)")]
    
stateRunOpenFOAMMeshing -- openfoam_case --> tRunOpenFOAMMeshing
direction RL
end
    
subgraph taskRunOpenFOAMSimulation["task RunOpenFOAMSimulation"]
 subgraph "" 

  tRunOpenFOAMSimulation["bim2sim > plugins > PluginOpenFOAM > 
bim2sim_openfoam > task >  
 RunOpenFOAMSimulation"]
  extRunOpenFOAMSimulation(" This ITask runs the openfoam simulation on linux
systems. " )
 end

stateRunOpenFOAMSimulation[("state
 (reads/touches)")]
    
stateRunOpenFOAMSimulation -- openfoam_case --> tRunOpenFOAMSimulation
direction RL
end
    taskLoadIFC --> taskCreateElementsOnIfcTypes 
taskCreateElementsOnIfcTypes --> taskCreateSpaceBoundaries 
taskCreateSpaceBoundaries --> taskAddSpaceBoundaries2B 
taskAddSpaceBoundaries2B --> taskCorrectSpaceBoundaries 
taskCorrectSpaceBoundaries --> taskCreateRelations 
taskCreateRelations --> taskDisaggregationCreationAndTypeCheck 
taskDisaggregationCreationAndTypeCheck --> taskEnrichMaterial 
taskEnrichMaterial --> taskEnrichUseConditions 
taskEnrichUseConditions --> taskWeather 
taskWeather --> taskCreateIdf 
taskCreateIdf --> taskComfortSettings 
taskComfortSettings --> taskSerializeElements 
taskSerializeElements --> taskRunEnergyPlusSimulation 
taskRunEnergyPlusSimulation --> taskInitializeOpenFOAMSetup 
taskInitializeOpenFOAMSetup --> taskCreateOpenFOAMGeometry 
taskCreateOpenFOAMGeometry --> taskAddOpenFOAMComfort 
taskAddOpenFOAMComfort --> taskCreateOpenFOAMMeshing 
taskCreateOpenFOAMMeshing --> taskSetOpenFOAMBoundaryConditions 
taskSetOpenFOAMBoundaryConditions --> taskRunOpenFOAMMeshing 
taskRunOpenFOAMMeshing --> taskRunOpenFOAMSimulation 
    

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

How to create a project?

In order to create a project, first an IFC file and an EnergyPlus Weather file path must be specified. Within the building from the IFC file, a single room should be chosen through a provided Space GUID. The user can decide to add room elements such as heaters, air terminals, furniture or people and define simulation and meshing parameters like radiation model, steady/transient, grid sizes or simulation time.

How to configure my project?

Simulation settings

The main configuration options are provided through the Simulation Settings. The OpenFOAM-specific settings can be found here.

Default tasks

The Plugin OpenFOAM uses an IFC-based EnergyPlus simulation to set up and export a case for an OpenFOAM simulation. This Plugin includes extending the geometric extensions of a specified room. General simulation and meshing control settings are set here.

The Plugin consists of multiple individual tasks that are executed consecutively. The default tasks are defined in the PluginOpenFOAM class. These consist of some general preparation tasks for the EnergyPlus simulation, some OpenFOAM case and geometry initialization tasks and the optional CFD simulation tasks, which are only run if specified via the SimSettings.

As a base, the full PluginEnergyPlus and the PluginComfort are executed without any plotting. Then the following OpenFOAM tasks are performed.

• OpenFOAM specific tasks:

  • InitializeOpenFOAMSetup

  • SetOpenFOAMBoundaryConditions

  • CreateOpenFOAMGeometry

  • CreateOpenFOAMMeshing

  • RunOpenFOAMMeshing

  • RunOpenFOAMSimulation

  • AddOpenFOAMComfort

OpenFOAM specific tasks

Initialize OpenFOAM setup

Go to InitializeOpenFOAMSetup

Every OpenFOAM simulation requires a base case that is later modified based on the SimSettings. This base case is initialized in this task.

Set OpenFOAM Boundary Conditions

Go to SetOpenFOAMBoundaryConditions

In this task, the Boundary Conditions of the OpenFOAM case are modified based on the previously run EnergyPlus Simulation and the SimSettings. This includes radiation properties, initial temperatures and heat balances and solver specific properties.

Create OpenFOAM Geometry

Go to CreateOpenFOAMGeometry

This task initializes the geometry of the OpenFOAM case by using the selected Space GUID from the specified IFC-file and adding additional elements (heating, air terminals, furniture, people) if chosen via the SimSettings. This step results in an export of the geometry to the STL-format.

Create OpenFOAM Meshing

Go to CreateOpenFOAMMeshing

This task is performed after creating the geometry and sets up the mesh properties and sections. First, parameters and boundaries for the blockMesh are set. Then the snappyHexMesh parameters are set, which includes defining refinement zones and levels around the walls and more complex geometries.

Run Meshing

Go to RunOpenFOAMMeshing

For Linux-based devices, this task can automatically start the meshing step of the OpenFOAM simulation. This requires an existing OpenFOAM installation of v2206 or newer and usually takes about 5 - 20 minutes depending on the number of cores.

Run Simulation

Go to RunOpenFOAMSimulation

For Linux-based devices, this task can automatically start the OpenFOAM simulation. This requires an existing OpenFOAM installation of v2206 or newer and usually takes several hours, highly depending on the number of cores, iterations, geometric complexity, and resulting mesh size.

Add OpenFOAM Comfort

Go to AddOpenFOAMComfort

This task adds output parameters to the OpenFOAM output dictionaries, which enable the evaluation of local thermal comfort in the simulated room.

Additional templates

Some of the OpenFOAM-specific SimSettings add additional elements to the simulated room such as heating, specific ventilation in-/outlets, furniture or people. The base stl-files for these can be found in bimsim/plugins/PluginOpenFOAM/bim2sim_openfoam/assets/geometry.

How to run the simulation?

If you are working on a linux system, you may decide to run the simulation immediately on your device. Otherwise, you can move the exported OpenFOAM case onto an adequate system with OpenFOAM/v2206 or newer to run the simulation through one of the provided scripts.

How to analyze the project?

What kind of results exist?

The main result of a PluginOpenFOAM simulation is an OpenFOAM case. This is a folder that typically consists of 3 subfolders:

• 0: defines initial conditions for the simulation

• constant: defines boundary conditions and solver-specific constants

• system: defines the geometry, simulation and meshing settings

Additionally, the exported folder provides some scripts for running the OpenFOAM simulation on a compute cluster with several cores.

After running the simulation using OpenFOAM/v2206 or newer, you can take a look at the results using Paraview. Here, the most relevant variables are usually the temperature and velocity distribution.

What programs/tools to use for further analysis?

The provided OpenFOAM case can be simulated using OpenFOAM/v2206 or newer versions. For visualizing the generated meshes or evaluating CFD results, it is recommended to open them in Paraview through a .foam-file.