Multiphase Cases Repository by HZDR for OpenFOAM Foundation Software

This repository contains simulation setups for the Multiphase Code Repository. The simulation setups are divided into mono- and polydisperse bubbly flows utilising the set of Baseline models of HZDR, setups using the morphology-adaptive multifield two-fluid model (unresolved and resolved interfaces) and miscellaneous cases.

Acknowledgement: OpenFOAM(R) is a registered trade mark of OpenCFD Limited, producer and distributor of the OpenFOAM(R) software via www.openfoam.com. The Multiphase Cases Repository by HZDR for OpenFOAM Foundation Software is not compatible with the software released by OpenCFD Limited, but is based on the software released by the OpenFOAM Foundation via www.openfoam.org.

Highlights of the Multiphase Cases Repository by HZDR

Cases using the Baseline model set by HZDR

Cases using the morphology-adaptive modelling approach

Miscellaneous cases

Installation

Prerequisites

For running the cases in this repository, you need to install the software provided through the Multiphase Code Repository by HZDR for OpenFOAM Foundation Software. Depending on what you have access to

• Helmholtz Code Base: For Helmholtz and Friends via Helmholtz AAI
  or using a HZDR guest account
• Rossendorf Data Repository (RODARE): For everybody

you can install the software in several ways:

• as Debian packages
• by compiling from sources
• by pulling the provided Docker or Apptainer Images

Follow the installation instructions for your preferred approach and make sure your environment is setup correctly, e.g. by running foamVersion.

General remarks

The installation instructions will use the following environment variable:

• FOAM_RUN: directory where simulation setups are stored

Multiphase Cases Repository by HZDR from Helmholtz Code Base

Note that this repository includes content that is versioned using git-lfs to store large binary files in the repository

sudo apt update
sudo apt install git-lfs

After successful installation, simply clone the repository

mkdir -p $FOAM_RUN
git clone --single-branch git@codebase.helmholtz.cloud:fwdc/multiphase/cases.git $FOAM_RUN

Multiphase Cases Repository by HZDR from Rossendorf Data Repository (RODARE)

Download tar archive from RODARE and unpack it

mkdir -p $FOAM_RUN
tar -xzf Multiphase-Cases-Repository-<version>.tgz -C $FOAM_RUN

Snakemake workflow for Computational Fluid Dynamics software

This repository is configured for convenient batch-processing of the contained simulation setups both on workstations and HPC systems using Snakemake.

In order to use this functionality an installation of the multiphasepy package is required. You can obtain it from PYPI.

For usage information refer to the documentation of the package.

Model Testing

For efficiently testing the influence of a certain model or parameter selection for a range of simulation setups, e.g. in the scope of a Snakemake workflow, the corresponding dictionary entry can be placed at a central location and included in individual cases using the #include directive provided by OpenFOAM.

In the following example, the lift model selection in constant/phaseProperties for a case using the addonMultiphaseEuler solver module is centralized.

lift
{
 air_dispersedIn_water
 {
 #include "~/OpenFOAM/cases/models/lift.cfg"
 }
}

The content of ~/OpenFOAM/cases/models/lift.cfg could be

type Tomiyama;

aspectRatio
{
 type Wellek;
}

Note: To allow parallel testing of different model selections, the directory containing the files to be included should be relative to the directory to which the Cases Repository was cloned. Globally overwriting a model via the #includeEtc is discouraged for this reason.

Quantification of the CFD Prediction Quality

A systematic analysis of results can be supported by a quantification of the agreement of simulation results and experimental data. For that purpose a fuzzy logic controller is introduced that allows a comparison of two one-dimensional data sets, e.g. line samples or probes. It generates a concise value between 0 and 1 quantifying the prediction quality or performance of a simulation result. This performance evaluation is performed for all available validation data individually. For details on the fuzzy controller please checkout the mpyfuzzy utility of the multiphasepy package and use mpyfuzzy --help for further options.

For plotting purposes a jupyter notebook to be found under workflow/scripts/plotCFDPerformance.ipynb can be used and a working environment for launching the notebook is provided with the multiphasepy package . Note that for the notebook script to work it has to be copied into the top-level workflow directory. The script plots the error metrics and performance results for all validation fields for the selected cases. The script also averages performance results over all the individual validation data in order to produce an overall performance value for each case, and plots this for all selected cases.

Analysing the Feature Hierarchy of Cases

Results of Model testing can be visualized using a decision tree analysis. Keywords describing each case and listed in the case.yml files serve as labels, while the values computed as a [Quantification of the prediction quality](#Quantification of the prediction quality) can be used as the target feature for building decision tree models.

An automated script for plotting a decision tree from the change in performance after model testing can be found under workflow/scripts/decisionTreeAnalysis.ipynb. In order to use the script the sklearn package needs to be installed, everything else is provided with the multiphasepy package.

How to cite us?

When using the Multiphase Cases Repository by HZDR cite as

Haensch, S. et al. (2025). Multiphase Cases Repository by HZDR for OpenFOAM
Foundation Software. Rodare. http://doi.org/10.14278/rodare.811