Usage & I/O

Overview

This page describes how to include the FluidDynamics module in a simulation, configure it via the input file, and interpret the output.

---

Minimal usage example

The following shows a minimal incompressible single-phase flow simulation:

#include "FluidDynamics/FlowSolverLBM.h"
#include "BoundaryConditions.h"
#include "PhaseField.h"
#include "Settings.h"
#include "Velocities.h"

using namespace openphase;

int main(int argc, char* argv[])
{
    std::string InputFile = DefaultInputFileName;

    Settings           OPSettings(InputFile);
    BoundaryConditions BC(OPSettings, InputFile);
    PhaseField         Phase(OPSettings);
    Velocities         Vel(OPSettings);
    FlowSolverLBM      FL(OPSettings, InputFile);
    RunTimeControl     RTC(OPSettings, InputFile);

    // Initialize microstructure ...
    // Initializations::Single(Phase, 0, BC);

    FL.FinalizeInitialization(Phase, Vel, BC);

    while (!RTC.Finished())
    {
        FL.Solve(Phase, Vel, BC);

        if (RTC.WriteVTK())
            FL.WriteVTK(OPSettings, Phase, RTC.Step());

        RTC.Increment();
    }
    return 0;
}

---

Input file parameters

Parameters are read from the project input file (.opi) under the [FlowSolverLBM] section.

Required parameters

Key	Type	Description
N_Fluid_Comp	int	Number of fluid components
nu	double (per component)	Kinematic viscosity [m²/s]
dRho	double	Lattice-to-physical density scaling [kg/m³]
dt	double	Lattice-to-physical time scaling [s]

Optional: flow features

Key	Default	Description
Do_Gravity	false	Enable gravitational force
GA	{0,0,0}	Gravitational acceleration [m/s²]
Do_BounceBack	false	Solid–fluid no-slip boundary
Do_BounceBackElastic	false	Moving solid bounce-back
Do_Drag	false	Interface drag force
h_star	0	Drag force parameter
Do_FixPopulations	false	Fix negative populations

Optional: two-phase flow

Key	Default	Description
Do_TwoPhase	false	Enable two-phase flow
Do_Benzi	false	Use Benzi pseudo-potential
Do_Kupershtokh	false	Use Kupershtokh two-phase model
LiquidDensity	—	Equilibrium liquid density [kg/m³]
VaporDensity	—	Equilibrium vapor density [kg/m³]
SurfaceTension	—	Surface tension [kg/s²]
rho_0	—	Benzi reference density
Gb	—	Benzi interaction strength matrix
Wetting	—	Wetting parameter matrix (phase × fluid component)

Use BenziGas::EquilibriumValues() or VanDerWaalsGas::EquilibriumValues() to determine the correct values for LiquidDensity, VaporDensity, and SurfaceTension.

Optional: thermal compressibility

Key	Default	Description
Do_ThermalComp	false	Enable thermally compressible extension
Pth0	1e5	Initial thermodynamic pressure [Pa]
Poutlet	1e-6	Outlet hydrodynamic pressure [Pa]
GradRho_VanLeer	false	Use Van Leer density gradient
GradRho_Central	false	Use central differences for density gradient

---

Output fields

VTK output

FL.WriteVTK(OPSettings, Phase, tStep);

Writes to VTK/FlowSolverLBM_<tStep>.vts:

Field	Description
FluidDensity	Physical mass density [kg/m³]
FluidVelocity	Physical velocity vector [m/s]
Pressure	Lattice pressure
Obstacle	Solid/fluid mask (0 = fluid, 1 = solid)

Lattice population output

FL.lbWriteVTK(OPSettings, Phase, tStep);

Writes raw populations for debugging — not intended for production output.

Binary restart files

FL.Write(OPSettings, tStep);    // write
FL.Read(OPSettings, BC, tStep); // read

Populations and obstacle states are stored in binary format for checkpointing.

---

Diagnostic quantities

Useful methods for monitoring simulation health:

// Mass monitoring
vector<double> mass = FL.CalculateFluidMass();
double liqVol = FL.CalculateLiquidVolume(0);     // component 0 liquid
double vapVol = FL.CalculateVaporVolume(0);

// Node counts
size_t nFluid    = FL.CountFluidNodes();
size_t nObstacle = FL.CountObstacleNodes();

// Local field access
double p    = FL.Pressure(i, j, k);
dVector3 u  = FL.FluidVelocity(i, j, k);
double rho  = FL.FluidDensity(i, j, k);

---

Boundary conditions

The BoundaryConditions object controls domain boundaries. Typical configurations for LBM:

BC type	LBM effect
Periodic	Populations wrap around domain boundaries
No-slip wall	Bounce-back applied at boundary nodes
Inlet velocity	SetUniformVelocity(BC, U0) — sets populations to equilibrium at ${\mathbf{u}}_0$
Outlet pressure	Poutlet sets the outlet hydrodynamic pressure

Inlet flow with a prescribed velocity:

dVector3 U0 = {0.01, 0.0, 0.0}; // [m/s]
FL.SetUniformVelocity(BC, U0);

---

Validation test cases

Test	Location	Validates
Capillary bridge	tests/LBCapillaryBridge	Surface tension, contact angle
Gravity-driven flow	tests/LBGravity	Body force, Poiseuille profile
Density equilibrium	tests/LBDensity	Multi-component phase separation

Run a test with:

cd openphase/tests/LBCapillaryBridge
make
./LBCapillaryBridge
./compare.sh  # compare to reference results

---

Performance tips

• Use grid dimensions that are multiples of your CPU's SIMD width (multiples of 8 or 16).
• Minimize WriteVTK frequency; VTK I/O is the dominant overhead at high output rates.
• For MPI runs, set domain decomposition along the longest spatial dimension.
• Do_FixPopulations adds overhead; enable only when needed (high density ratio or unstable cases).
• Restart files (Read/Write) are compact — checkpoint every few thousand steps for long runs.