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
Initialize OpenFOAM setup
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
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
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
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
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
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.