MultiFlow reads simulation parameters from a plain-text options file (conventionally named run.mf).
No recompilation is required when this file is changed.
- Any line whose first non-whitespace character is
# is a comment and is ignored.
- The file is divided into keyword blocks. Each block starts with a keyword and ends with
END.
- Keywords and option names are case-insensitive.
- The top-level keywords are:
| Keyword |
Purpose |
PHASE |
Fluid or particle phase properties |
MESH |
Mesh definition |
EXECUTE |
Time-stepping, output and restart control |
NUMERICS |
Discretisation schemes and AMR |
SCALAR |
Additional passive/active Eulerian scalars |
INTERFACES |
VOF/multiphase interface modelling |
FRONTTRACKING |
Front-tracking (FT) interface method |
FRONTREMESHING |
Front-tracking surface mesh remeshing |
ENRICHMENT |
Turbulent enrichment / synthetic turbulence |
CHEMISTRY |
Gas-phase chemistry |
A minimal single-phase incompressible simulation looks like:
# Minimal run.mf example
PHASE 1
Fluid
FluidType incompressible
Density 1.0
Viscosity 1e-3
GravityVector 0.0 -9.81 0.0
END
MESH
BOX 0 0 0 1 1 1 32 32 32
END
EXECUTE
TimeSteps 100 0.001
OutputFormat HDF5
OutputDirectory output
OutputFrequency 10
END
NUMERICS
Time Euler
Space Central
END
PHASE
Each phase is declared with PHASE <N> where N is the phase number starting at 1.
The first token after the phase number selects the phase type: Fluid, Particle, IBM, or MoveIBM.
Fluid phase
PHASE 1
Fluid
...options...
END
| Option |
Arguments |
Description |
Fluid |
— |
Declares this phase as a fluid. |
FluidType |
incompressible | polytropic | compressible |
Compressibility model. |
Density |
<value> |
Fluid density (kg/m³). |
Viscosity |
<value> |
Dynamic viscosity (Pa·s). |
GravityVector |
<gx> <gy> <gz> |
Gravity vector per phase (m/s²). (Gravity is accepted as alias.) |
MomentumSource |
<sx> <sy> <sz> |
Constant momentum source term (N/m³) applied to this phase. |
DriveFlow |
massflow <direction> <plane_position> <magnitude> |
Drive a periodic flow to a target mass-flow rate. direction is an integer (0=X, 1=Y, 2=Z). |
DriveFlow |
pressure <direction> <magnitude> |
Drive a periodic flow by a constant pressure gradient. |
ReferenceEnergy |
<value> |
Reference energy value (J/m³) used in compressible formulations. |
SpecificHeatCapacity |
<value> |
Specific heat capacity at constant pressure Cp (J/(kg·K)). |
ThermalConductivity |
<value> |
Thermal conductivity (W/(m·K)). |
HeatTransfer |
— |
Activates the energy equation for this phase. |
PolytropicExponent |
<value> |
Polytropic exponent γ (must be ≥ 1.0). |
AttractionPressureConstant |
<value> |
Attraction pressure constant for stiffened-gas EoS (Pa). |
CoVolume |
<value> |
Co-volume parameter for stiffened-gas EoS (m³/kg). |
PengRobinson |
Argon | N2 | Air | ... |
Selects the Peng-Robinson equation of state and loads predefined critical properties for the named species. |
TurbulentInitialField |
<modes> <kinetic_energy> <boundary_layer> |
Generates a synthetic turbulent initial velocity field. |
Viscoelastic options
These are activated by first specifying Viscoelastic <model>.
| Option |
Arguments |
Description |
Viscoelastic |
ucm | lptt | eptt | giesekus | shb |
Selects the viscoelastic constitutive model (UCM, linear/exponential PTT, Giesekus, SHB). |
PolymerViscosity |
<value> |
Polymer (extra) viscosity (Pa·s). |
PolymerRelaxationTime |
<value> |
Polymer relaxation time λ (s). |
PolymerExtensibility |
<value> |
Extensibility parameter (L² for FENE-type models). |
PolymerMobilityCoeff |
<value> |
Mobility coefficient (PTT parameter ε). |
PolymerSlipCoeff |
<value> |
Slip coefficient (PTT parameter ξ). |
EVPYieldStress |
<value> |
Yield stress τ₀ for elasto-viscoplastic (EVP/SHB) model (Pa). |
EVPConsistencyCoeff |
<value> |
Consistency coefficient K for EVP power-law viscosity. |
EVPPowerLawCoeff |
<value> |
Power-law exponent n for EVP model. |
LES (Large Eddy Simulation) options
Multiple LES sub-models can be combined in the same phase block.
| Option |
Arguments |
Description |
LES |
— |
Activates LES (required when using any LES sub-model). |
Smagorinsky |
— |
Static Smagorinsky SGS model. |
DynamicGermano |
— |
Dynamic Germano-Lilly SGS model. |
LDKM |
— |
Localised dynamic kinetic-energy model. |
VREMAN |
— |
Vreman SGS model. |
WALE |
— |
Wall-Adapting Local Eddy-viscosity (WALE) model. |
LESConstant |
<Cs> |
Smagorinsky constant Cs (overrides default). |
LESWallConstant |
<value> |
Van Driest wall-damping constant A⁺. |
WallDistanceCorrection |
— |
Enables wall-distance correction for SGS length scale. |
VanDriestDampening |
— |
Applies Van Driest near-wall damping to the SGS viscosity. |
Lagrangian particle / IBM phase
The second phase (or higher) can be declared as a Lagrangian or IBM phase using one of the following type keywords:
| Type keyword |
Description |
Particle |
DEM Lagrangian particles. |
IBM |
Immersed Boundary Method (fixed geometry). |
MoveIBM |
Moving IBM geometry. |
PHASE 2
Particle
...options...
END
Particle type definition
Before injecting particles, each particle type must be defined. Multiple ParticleType lines are allowed.
DEM / IBM particles:
ParticleType DEM <num> <diameter> <density> <YoungsMod> <PoissonRatio> <Friction> <RestCoef>
ParticleType IBM <num> <diameter> <density> <YoungsMod> <PoissonRatio> <Friction> <RestCoef>
ParticleType MOVEIBM <num> <diameter> <density> <YoungsMod> <PoissonRatio> <Friction> <RestCoef>
Hard-sphere particles (no Young's modulus):
ParticleType HARD <num> <diameter> <density> <Friction> <NormalRestCoef> <TangentialRestCoef>
| Argument |
Description |
num |
Unique integer identifier for this particle type. Negative values denote non-Newtonian particles. |
diameter |
Maximum particle diameter (m). |
density |
Particle material density (kg/m³). |
YoungsMod |
Young's modulus E (Pa). |
PoissonRatio |
Poisson's ratio ν (–). |
Friction |
Coefficient of friction μ (–). |
RestCoef |
Normal coefficient of restitution e (–). |
General particle phase options
| Option |
Arguments |
Description |
Gravity |
<gx> <gy> <gz> |
Gravitational acceleration acting on particles (m/s²). |
CollisionModel |
Tsuji | Kuang | Linear | PlasticElastic | Elastic | ParallelBond | Walton | Hardsphere |
Contact-force model for particle–particle and particle–wall collisions. |
TimeStep |
<dt> |
Initial/default DEM time step (s). Required even when auto time-stepping is active. |
MinimumTimeStep |
<dt> |
Minimum allowed DEM time step (s). |
AutomaticTimeStep |
<n> |
Enables automatic DEM time-stepping; n is the minimum number of integration steps per collision. |
AutomaticHardParticleTimeStepFraction |
<fraction> |
XXX |
TimeIntegrationScheme |
VelocityVerlet | VyasVelocityVerlet |
Particle time-integration method. |
ParticleBox |
<factor> |
Multiplier on the largest particle diameter to set the Cartesian collision-search cell size. Must be ≥ 1.0. |
PeriodicX |
— |
Enables periodic boundary conditions in X for particles. |
PeriodicY |
— |
Enables periodic boundary conditions in Y for particles. |
PeriodicZ |
— |
Enables periodic boundary conditions in Z for particles. |
LeesEdwardBC |
<boundary_dir> <flow_dir> <shear_rate> |
Lees-Edwards boundary condition for simple shear. boundary_dir and flow_dir are integers (0=X, 1=Y, 2=Z). |
DisableCollisions |
— |
Turns off all particle–particle collisions (particles still interact with walls). |
ElasticWallBounce |
— |
Uses elastic (energy-conserving) wall bouncing instead of the contact model. |
MPPIC |
— |
Activates the Multi-Phase Particle-In-Cell (MP-PIC) method. |
ExternalForces |
— |
Signals that user-defined external forces are applied to particles (requires user file). |
MaxInjectParticles |
<n> |
Maximum total number of particles that may be injected. |
RemoveParticles |
— |
Enables removal of particles that exit the domain. |
Bodies |
— |
Enables the rigid-body (non-spherical) particle module. |
Voronoi |
<0\|1> |
XXX |
Wall material properties
If omitted, the particle material properties are used for wall contacts.
| Option |
Arguments |
Description |
WallYoungsModulus |
<value> |
Wall Young's modulus (Pa). |
WallPoissonRatio |
<value> |
Wall Poisson's ratio (–). |
WallFriction |
<value> |
Wall–particle friction coefficient (–). |
WallRestCoefNormal |
<value> |
Normal coefficient of restitution for wall contacts (–). |
WallRestCoefTangential |
<value> |
Tangential coefficient of restitution for wall contacts (–). |
WallBoundaryConditionEnforcement |
<n> |
XXX (integer flag for near-wall boundary condition enforcement). |
WallRotationOrigin |
<ox> <oy> <oz> |
Origin point for a rotating wall (m). |
WallAngularVelocity |
<wx> <wy> <wz> |
Angular velocity of the rotating wall (rad/s). |
WallRemove |
<wall_id> |
Removes wall wall_id from particle–wall collision detection. Can be repeated. |
ParticleOutletWall |
<wall_id> |
Designates wall wall_id as a particle outlet (particles are deleted on contact). Can be repeated. |
Per-type property additions
| Option |
Arguments |
Description |
SetRoughness |
<num> <sigma> <length> |
Adds a roughness model to particle type num. sigma and length are roughness parameters. |
SetCohesion |
<num> <dgamma> |
Adds a DMT cohesion model to particle type num; dgamma is the surface energy (J/m²). |
PSDFile |
<num> <filename> |
Assigns a particle size distribution (PSD) file to particle type num. The file contains a cumulative PSD. |
GrowParticles |
<num> <t_start> <t_end> <growthrate> <volfrac> |
XXX: activates particle growth for type num. |
Fluid–particle coupling
| Option |
Arguments |
Description |
MomentumCoupling |
none | psic | particlemesh | filter |
Method for coupling particle momentum to the fluid. |
MomentumCoupling |
explicit | semiimplicit |
Temporal coupling type for the momentum exchange. |
VFracCoupling |
none | psic | particlemesh | filter |
Method for coupling the volume fraction to the fluid. |
VfracTransientTerm |
— |
Includes the transient (∂α/∂t) term in the volume-fraction equation. |
VfracVelocityUnite |
— |
XXX |
FilterRadius |
<value> |
Filter radius used when MomentumCoupling filter is selected (m). |
FilterFunction |
wendland | gaussian |
Kernel function used for the filter coupling. |
FluidInterpolation |
shepards | shepmasju | sheprenka | splines |
Fluid velocity interpolation method at particle positions. |
DirectTrilinearInterp |
yes | no |
Use direct trilinear interpolation for fluid velocity at particle positions. |
DirectTricubicInterp |
yes | no |
Use direct tricubic interpolation for fluid velocity at particle positions. |
TransientVelocityCorrection |
yes | no |
Apply a correction for the transient (unsteady) part of the fluid velocity seen by the particle. |
SteadyWallVelocityCorrection |
yes | no <direction> |
XXX |
FixedParticles |
yes | no |
Fix all particle positions (forces are still computed but particles do not move). |
Drag and lift force models
| Option |
Arguments |
Description |
DragForceModel |
none |
No drag force. |
DragForceModel |
MeanForceMicrostructure |
XXX |
DragForceModel |
Microstructure |
XXX |
DragForceModel |
WenAndYu |
Wen & Yu drag correlation. |
DragForceModel |
FilteredSchillerNaumann |
Filtered Schiller–Naumann drag correlation. |
DragForceModel |
FilteredDragModelTenetti |
Filtered drag model (Tenneti et al.). |
DragForceModel |
DiFelice |
Di Felice drag correlation. |
DragForceModel |
Zeng <direction> |
Zeng near-wall drag correction; direction is the wall-normal direction integer. |
LiftForceModel |
none |
No lift force. |
LiftForceModel |
Zeng <direction> |
Zeng near-wall lift force; direction is the wall-normal direction integer. |
LiftForceModel |
Mei <direction> |
Saffman–Mei–McLaughlin lift force; direction is the wall-normal direction integer. |
AddedMassForce |
yes | no |
Includes the added-mass (virtual-mass) force. Requires compile flag MF_DEM_ADDED_MASS_FORCE. |
HistoryForceModel |
none | daitche | window |
Basset history (memory) force model. Requires compile flag MF_DEM_HISTORY_FORCE. |
Basset/history force sub-settings (inside a BassetSettings … END block):
| Option |
Arguments |
Description |
WindowTime |
<value> |
Time window for the windowed Basset kernel (s). |
ExpTails |
<n> |
Number of exponential tails for the windowed approximation. |
OdarHamilton |
— |
Use the Odar–Hamilton correction to the Basset force. |
MaxSteps |
<n> |
Maximum number of history steps to store. |
Particle initialisation / injection
Multiple injection blocks of different types may be combined.
| Option |
Arguments |
Description |
InitBlockParticles |
<type> <xmin> <ymin> <zmin> <xmax> <ymax> <zmax> <dx> <dy> <dz> <rx> <ry> <rz> |
Place particles of type type on a regular lattice with spacing dx/dy/dz and random jitter rx/ry/rz inside the bounding box. |
InitBlockNoSlipParticles |
(same arguments as above) |
Same as InitBlockParticles but initialises particle velocity to match the local fluid velocity (no-slip). |
InitBlockVelocityParticles |
<type> <xmin…zmax> <dx dy dz> <rx ry rz> <vx vy vz> <vrx vry vrz> |
Lattice placement with prescribed initial velocity vx/vy/vz and velocity randomness vrx/vry/vrz. |
InitBlockTimeVelocityParticles |
(same + <tbegin> <tend> <tdelta>) |
Lattice placement with velocity, active only between times tbegin and tend with period tdelta. |
InitBlockTimeNoSlipParticles |
(type + bounding box + spacing + jitter + vel_random + tbegin + tend + tdelta) |
Timed lattice placement with no-slip velocity initialisation. |
InitBlockRandomParticles |
<type> <volfrac> <xmin…zmax> <vx vy vz> <vrx vry vrz> |
Random placement to achieve target volume fraction volfrac. |
InitBlockNoSlipRandomParticles |
<type> <volfrac> <xmin…zmax> |
Random placement with no-slip velocity initialisation. |
InjectParticles |
<type> <x> <y> <z> <vx> <vy> <vz> <tbegin> <tend> <tdelta> <vrandom> <rx> <ry> <rz> |
Continuous injection of single particles at position x,y,z with velocity vx,vy,vz between tbegin and tend. |
ReadDEMFixedParticleFile |
<filename> |
Read fixed (immobile) DEM particle positions from an ASCII file. |
ReadDEMParticlesFromH5File |
<filename> |
Read DEM particle initial conditions from an HDF5 file. |
IBM / MoveIBM specific options
| Option |
Arguments |
Description |
ParticlesPacking |
BCC | FCC | HCP |
Initialise IBM particles in a body-centred cubic, face-centred cubic, or hexagonal close-packed arrangement. |
ParticlesPacking |
Random <volfrac> |
Place IBM particles randomly to reach volume fraction volfrac. |
IBMParticlesFileName |
<type> <filename> |
Load IBM particle surfaces from a file (.h5 for HDF5, .gts for GTS/MFTL format). |
MFTLOptions |
<scale> <x> <y> <z> <thetaX> <thetaY> <thetaZ> |
Scale, translate, and rotate the last loaded MFTL surface mesh. Angles are in radians; rotation order Z→Y→X. Must follow IBMParticlesFileName with a .gts file. |
IBMMFTLMesh |
<filename> |
Specify the background MFTL mesh file. |
IBMMFTL |
yes <scale> <angleX> <angleY> <angleZ> |
XXX |
IBMSpheroid |
<num> <cohesion> <flattening> <angle_x> <angle_y> <angle_z> |
Define a spheroidal shape for IBM particle type num. |
IBMOneSided |
<n> |
XXX |
IBMBreugem |
<n> |
XXX: IBM Brugem correction integer flag. |
IBMForcedRotation |
<n> |
XXX |
WriteMoveIBMOverlapMesh |
yes | no |
Write the MoveIBM overlap mesh to file for debugging. |
IBMHybrid |
<n> |
XXX |
IBM_Alpha |
<value> |
XXX |
IBMDeltaFunctionSupport |
<n> |
Support width (in cells) for the IBM delta function. |
IBMMLSWeights |
<n> |
XXX: Moving Least Squares weight flag. |
IBMCoupledForcing |
yes | no |
XXX |
IBMPrintMarkersCoordinatesToFile |
yes | no |
Write IBM marker coordinates to a text file. |
STLWallTrianglesFile |
<filename> |
Load an additional STL triangulation as a wall for particle collision. Can be repeated. |
STLWallAddDistance |
<dx> <dy> <dz> |
Offset the STL wall triangles by dx,dy,dz (m). |
FrameRotationalVelocity |
<ox> <oy> <oz> |
Angular velocity of a rotating reference frame (rad/s). |
FrameAccelerationTime |
<value> |
Time over which the frame accelerates to full rotational speed (s). |
OverlapMeshProcRatios |
<rx> <ry> <rz> |
XXX |
OverlapMeshSkewRatios |
<sx> <sy> <sz> |
XXX |
Rigid-body (non-spherical) options
Bodies require Bodies to be set first.
| Option |
Arguments |
Description |
Body superquadric |
<num> <eps1> <eps2> <a> <b> <c> |
Define a superquadric body of type num with blockiness exponents eps1, eps2 and semi-axes a, b, c. |
Body multisphere |
<num> <name> <drag_type> <semi_minor> <aspect_ratio> |
Define a multi-sphere body with name name, drag type integer, and geometric parameters. |
InitBody |
<type> <xs ys zs> <xe ye ze> <dx dy dz> <angle_x angle_y angle_z> <rand_angle_x/y/z> <vx vy vz> <omega_x omega_y omega_z> |
Place bodies of type type in a block arrangement (no time dependency). |
InitBodyInTime |
(same + <tbegin> <tend> <tdelta>) |
Place bodies in a block with timed injection. |
ReadBodyProperties |
<body_num> <filename> |
Read body material/inertia properties from file for body body_num. |
JeffriesParameters |
<body_num> <semi_minor> <aspect_ratio> |
Set Jeffery orbit parameters for a body using Jeffery drag. |
ContactDetection |
singleLevel\|multiLevel manual\|auto <scale> <level> <min_scale> <max_scale> <max_level> |
Configure the hierarchical particle contact detection algorithm. |
ParticleDomainRepartition |
<interval> <imbalance_threshold> |
Dynamically repartition the particle domain every interval seconds if load imbalance exceeds imbalance_threshold. |
MESH
MESH
...options...
END
Geometry
Exactly one of the following geometry options must be given (or MeshFile):
| Option |
Arguments |
Description |
MeshFile |
<filename> |
Read mesh from file. Supported formats: .h5 (HDF5), .gmsh, or other formats handled by the legacy boundary-condition routine. |
MeshType |
<type_string> |
XXX: mesh type override string passed to the I/O layer. |
BOX |
<xmin> <ymin> <zmin> <xmax> <ymax> <zmax> <nx> <ny> <nz> |
Generate a Cartesian box mesh with nx×ny×nz cells. |
Cylinder |
<refinement_level> <radius> <length> |
Generate a structured cylinder mesh. |
Sphere |
<radius> |
Generate a sphere mesh of given radius. |
Mesh properties
| Option |
Arguments |
Description |
Element |
HEX | TET | POLY |
Cell type: hexahedral, tetrahedral, or polyhedral. |
XPeriodic |
— |
Mesh is periodic in the X direction. |
YPeriodic |
— |
Mesh is periodic in the Y direction. |
ZPeriodic |
— |
Mesh is periodic in the Z direction. |
ScalingFactor |
<value> |
Multiplicative scaling factor applied to the entire mesh (default 1.0). |
DomainShape |
box | sphere |
Specifies the overall domain shape for boundary assignment. |
SphericalCapAngle |
<degrees> |
Polar angle (0–90°) used to assign inlet/outlet boundaries on a spherical domain. Use 90° for hemispherical inlet/outlet. |
AngleOfAttack |
<degrees> |
Angle of attack (0–360°) for body-fitted spherical domains; sets the pitch of the particle/body relative to the inflow. |
FreeStreamVelocity |
<value> |
Free-stream velocity magnitude (m/s) used for reference in body-fitted spherical domains. |
ParticleRadius |
<value> |
Equivalent particle radius in a body-fitted spherical mesh (for boundary assignment only; need not be exact). |
StoreProperties |
yes | no |
If yes, store additional mesh geometric properties in memory (higher memory, potentially faster assembly). |
Grid stretching
Applies only to BOX meshes.
| Option |
Arguments |
Description |
TanhX |
LO | HI | BOTH | NONE <ratio> |
Hyperbolic-tangent grid stretching towards the low wall, high wall, both walls, or none in the X direction. ratio controls the stretching strength. |
TanhY |
(same) |
As TanhX but for Y. |
TanhZ |
(same) |
As TanhX but for Z. |
CosX |
— |
Cosine-stretched grid in X (symmetric wall refinement). |
CosY |
— |
Cosine-stretched grid in Y. |
CosZ |
— |
Cosine-stretched grid in Z. |
X_LOW |
<n> |
XXX |
Y_LOW |
<n> |
XXX |
Z_LOW |
<n> |
XXX |
X_HIGH |
<n> |
XXX |
Y_HIGH |
<n> |
XXX |
Z_HIGH |
<n> |
XXX |
Wall |
<n> |
XXX |
Sub-grid refinement (BOX)
| Option |
Arguments |
Description |
RefineBox |
x\|y\|z centre\|corner <n> <d> |
Refine the BOX mesh in a sub-region. n cells are refined within distance d from the centre or corner in the given direction. |
EXECUTE
EXECUTE
...options...
END
Restart
| Option |
Arguments |
Description |
Restart |
yes | no |
Whether to restart from a previously saved state. |
ResDirectory |
<path> |
Directory containing the restart data (required when Restart yes). |
ResTime |
Time <t> | LAST |
Restart from physical time t (s), or from the last available saved state. |
ResStepTime |
<n> |
Time step number from which to restart. |
ResOldStepTime |
<dt> |
Old time-step size (s); required when restarting with SecondOrderBackwardEuler. |
Time stepping
| Option |
Arguments |
Description |
TimeSteps |
<n> <dt> |
Run n time steps of size dt (s). May be repeated to define multiple time-step classes executed sequentially. |
FixedTimeStep |
<dt> |
Fix the time step to dt (s). Acts as the maximum time step when CFLTarget is also set. |
CFLTarget |
<value> |
Target CFL number; activates adaptive time-stepping. FixedTimeStep acts as the upper bound. |
SimulationEndTime |
<t> |
Physical end time of the simulation (s). Optional if TimeSteps fully defines the end time. |
WallTimeEnd |
<t> |
Stop the simulation when the elapsed wall-clock time reaches t (s). |
CapillaryTimestepConstraint |
— |
Enforces the capillary CFL time-step constraint (relevant for surface-tension flows). |
SteadyState |
— |
Flags the simulation as steady-state (terminates on convergence rather than after a fixed number of steps). |
ForceOneIterationPerTimeStep |
— |
Force exactly one outer iteration per time step (disables inner iteration convergence loop). |
Solver convergence
| Option |
Arguments |
Description |
Convergence |
<value> |
Residual tolerance for the linear solver. |
Maxiter |
<n> |
Maximum number of linear solver iterations per time step. |
ConservationError |
L2 <tol> | LINF <tol> |
Stop the simulation if the conservation error (in L2 or L∞ norm) exceeds tol. |
CheckConservationErrorStdDev |
yes | no |
XXX |
Output
| Option |
Arguments |
Description |
OutputFormat |
HDF5 | PETSC | VTK | NONE |
Output file format. May be specified multiple times to write multiple formats. HDF5 produces XDMF-compatible files. |
OutputDirectory |
<path> |
Directory where output files are written. |
OutputFrequency |
<n> |
Write output every n time steps. |
OutputInterval |
<t> |
Write output at equally spaced physical time intervals of t (s). Alternative to OutputFrequency. |
OutputRestartFrequency |
<n> |
Save restart data every n output steps (a multiple of OutputFrequency). |
OutputRestartInterval |
<t> |
Save restart data at equally spaced time intervals of t (s). |
WalltimeLimitRestart |
<t> |
Automatically save a restart file when the remaining wall-clock time (before WallTimeEnd) drops below t (s). |
SaveVariable |
<name> |
Output only the named Eulerian variable (no spaces). Repeat to select multiple variables. If not specified, all variables are written. |
CSVOutputFile |
yes | no |
Write a log.csv file with columns: TimeStep, TimeStepSize, Time, CFL, ResidualNorm, ConservationError. In restart mode, new rows are appended. |
STLOutput |
yes | no |
Write STL surface triangle output files. |
InfoPriority |
low | medium | high |
Verbosity level of the standard output. low prints the most; high prints only high-priority messages. |
NUMERICS
NUMERICS
...options...
END
Source terms
| Option |
Arguments |
Description |
SourceTerms |
yes | no |
Enable user-defined momentum source terms (requires USERBoundary.c or similar user file). |
LinearSourceTerms |
yes | no |
Enable user-defined source terms that are linear in the velocity. |
VolumeFraction |
yes | no |
Enable the volume-fraction equation (needed for Euler–Lagrange coupling). |
Time discretisation
| Option |
Arguments |
Description |
Time |
Euler |
First-order explicit/implicit Euler time integration. |
Time |
SecondOrderBackwardEuler |
Second-order backward Euler (BDF2) time integration. |
Time |
RungeKutta |
Runge-Kutta time integration. |
Spatial discretisation
The Space keyword sets the default scheme for all convective terms. Sub-keywords allow per-equation overrides.
| Option |
Arguments |
Description |
Space |
Central | CentralDifferences |
Second-order central differencing. |
Space |
Upwind |
First-order upwind differencing. |
Space |
TVD | MINMOD |
TVD scheme with MINMOD limiter (deferred correction). |
Space |
VanLeer |
TVD scheme with Van Leer limiter. |
Space |
SuperBee |
TVD scheme with SuperBee limiter. |
Space |
Cubista |
CUBISTA high-resolution scheme. |
Space |
DeferredCentralDifferences | DeferredCentral |
Central differencing with deferred correction. |
Space |
DeferredHalvesCentral |
XXX |
Space |
Momentum <scheme> |
Override the convection scheme for the momentum equation only. <scheme> accepts the same values as Space. |
Space |
Density <scheme> |
Override the convection scheme for the density equation. |
Space |
Enthalpy <scheme> |
Override the convection scheme for the enthalpy/energy equation. |
Space |
ViscoelasticStress <scheme> |
Override the convection scheme for the viscoelastic stress transport. |
Diffusion terms
| Option |
Arguments |
Description |
DiffusionTerms |
AllImplicit |
Full diffusion tensor (including cross derivatives) treated fully implicitly. |
DiffusionTerms |
SemiImplicit |
Full diffusion tensor treated semi-implicitly (cross-derivative terms lag by one iteration). |
DiffusionTerms |
Laplacian |
Simplified Laplacian diffusion (cross-derivative terms omitted). |
Pressure–velocity coupling
| Option |
Arguments |
Description |
MWIPressureTerms |
AllImplicit | SemiImplicit |
Treat the large stencil pressure terms in the momentum-weighted interpolation (MWI/Rhie-Chow) fully or semi-implicitly. |
MWIInterpolation |
linear | half |
Interpolation variant used inside the MWI correction. |
MWITransient |
yes | no |
Include the transient term in the MWI/Rhie-Chow correction. |
ConstantDHat |
no | mean | min | max |
Extract a constant reference value for the MWI D-hat coefficient. |
LaplaceDHat |
yes | no |
XXX |
PressurePoint |
<x> <y> <z> |
Fix the pressure at the given coordinates (removes the hydrostatic nullspace). |
ReferencePressure |
<value> |
Reference pressure (Pa) for compressible/polytropic flows. |
ReferenceTemperature |
<value> |
Reference temperature (K) for compressible flows. |
Linearisation
Multiple Linearisation lines may appear to enable linearisation of individual terms.
| Option |
Arguments |
Description |
Linearisation |
All |
Linearise all terms (momentum + continuity + energy). |
Linearisation |
MomentumAll |
Linearise all momentum terms. |
Linearisation |
MomentumTransient |
Linearise the momentum transient term. |
Linearisation |
MomentumAdvectionConv |
Linearise the convective momentum advection. |
Linearisation |
MomentumAdvectionDensity |
Linearise the density-weighted part of momentum advection. |
Linearisation |
ContinuityAll |
Linearise all continuity terms. |
Linearisation |
ContinuityTransient |
Linearise the continuity transient term. |
Linearisation |
ContinuityAdvectionDensity |
Linearise the density-weighted continuity advection. |
Linearisation |
EnergyAll |
Linearise all energy terms. |
Linearisation |
EnergyTransient |
Linearise the energy transient term. |
Linearisation |
EnergyAdvectionConv |
Linearise the convective energy advection. |
Linearisation |
EnergyAdvectionDensity |
Linearise the density-weighted energy advection. |
Matrix conditioning
| Option |
Arguments |
Description |
NormaliseMatrix |
yes | no |
Row-normalise the linear system before solving (also spelt NormalizeMatrix). |
RemoveTinyCoeffs |
yes <threshold> | no <threshold> |
Remove matrix coefficients smaller than threshold (must be ≤ 1e-3) to improve conditioning. |
GradientCoefficients |
memory | LSHybrid | accurate |
Strategy for computing and storing gradient coefficients. memory minimises storage; accurate uses the most precise scheme; LSHybrid is a hybrid. Default (omit option): classic scheme. |
Viscoelastic numerics
| Option |
Arguments |
Description |
ViscoelasticAdvectionLinearisation |
newton |
Use Newton linearisation for the stress advection term. |
ViscoelasticStrainRate |
explicit | implicit |
Treatment of the strain-rate tensor in the viscoelastic constitutive equation. |
ViscoelasticStressVelocityCoupling |
explicit | semiimplicit | allimplicit |
Coupling between the viscoelastic stress and the velocity field. |
ViscoelasticDeformation |
explicit | taudiagonal \ tauall \ newton |
Implementation of the deformation/upper-convected derivative term. Multiple flags may be combined. |
Adaptive Mesh Refinement (AMR)
| Option |
Arguments |
Description |
AMRefinement |
yes | no |
Enable AMR. |
AMRMinRefinement |
<n> |
Minimum refinement level throughout the simulation. |
AMRMaxRefinement |
<n> |
Maximum refinement level (finest level). |
AMRInitialRefinement |
<n> |
Initial refinement level applied before the simulation starts. |
AMRtimesteps |
<n> |
Perform AMR every n time steps. |
InvokeAfterTimeSteps |
<n> |
Start invoking AMR only after n time steps have been completed. |
AMRPressureGradCriterion |
yes <refine> <coarsen> | no |
Refine cells where the normalised pressure gradient exceeds refine; coarsen below coarsen. |
AMRVorticityCriterion |
yes <refine> <coarsen> <v_ref> | no |
Refine based on vorticity normalised by reference velocity v_ref. |
AMRDivergenceCriterion |
yes <refine> <coarsen> <v_ref> | no |
Refine based on velocity divergence normalised by reference velocity v_ref. |
AMRBoundaryLayerCriterion |
yes | no |
Refine the layer of cells surrounding particle/IBM boundaries. |
AMRIBMFluidCellsSupportCriterion |
yes | no |
XXX |
AMRFronttrackingCriterion |
yes | no |
Use the front-tracking interface location as an AMR refinement criterion. |
AMRColourGradCriterion |
yes | no |
Use the colour-function (VOF) gradient as an AMR refinement criterion. |
SCALAR
Adds one passive or active Eulerian scalar. The block may be repeated for multiple scalars.
SCALAR
Name temperature
Diffusivity 1e-4
Discretisation implicit
Space central
END
| Option |
Arguments |
Description |
Name |
<name> |
Name of the scalar variable (no spaces). |
Diffusivity |
<value> |
Scalar diffusivity (m²/s). |
Discretisation |
implicit | explicit | none |
Temporal discretisation of the scalar equation. |
Space |
central | upwind | none |
Spatial discretisation of the scalar convection. |
INTERFACES
Controls the multiphase interface capturing method (VOF-based).
INTERFACES
VOF algebraic
SurfaceTensionCoeff 0.072
SurfaceTensionModel csf
END
VOF model
| Option |
Arguments |
Description |
VOF |
algebraic |
Algebraic VOF (CICSAM/HRIC advection). |
VOF |
coupled |
Algebraic VOF with coupled solution. |
VOF |
thinc |
THINC (Tangent of Hyperbola for INterface Capturing) VOF. |
VOF |
cthinc |
Coupled THINC VOF. |
VOF |
plic |
Piecewise Linear Interface Calculation (PLIC) VOF. |
VOF |
unsplitplic |
Unsplit PLIC VOF. |
Advection |
cicsam | hric |
Advection scheme for the algebraic VOF colour function. |
CFLTarget |
<value> |
CFL target for the VOF advection sub-stepping. |
Time |
flow |
Use the same time scheme as the flow solver for VOF advection. |
MaxNonLinearIterCoupledVOF |
<n> |
Maximum non-linear iterations for the coupled VOF solver. |
THINC parameters
| Option |
Arguments |
Description |
THINCThickness |
<value> |
Interface thickness parameter β for THINC (default ~3.5). |
THINCTolerance |
<value> |
Convergence tolerance for the THINC reconstruction. |
THINCReconstructionOutput |
yes | no |
Write THINC sample-point reconstruction data to file. |
Surface tension
| Option |
Arguments |
Description |
SurfaceTensionCoeff |
<sigma> |
Surface tension coefficient σ (N/m). |
SurfaceTensionModel |
csf |
Continuum Surface Force (CSF) model. |
SurfaceTensionModel |
ft |
Front-tracking surface tension (coupled with FRONTTRACKING block). |
SurfaceTensionModel |
nlst |
Non-local surface tension model. |
SurfaceTensionModel |
css |
Continuum Surface Stress (CSS) model. |
CurvatureImplicit |
all | momentum | mwi |
Treat the curvature-force term implicitly in the momentum equation and/or MWI. |
LaplaceSmoothing |
<n> |
Number of Laplacian smoothing iterations applied to the curvature field. |
CSSSmoothing |
yes | no |
Apply smoothing to the CSS surface stress tensor. |
CSSNSmoothingSteps |
<n> |
Number of CSS smoothing steps. |
NonLocalSurfaceTensionDimensions |
<n> |
Dimensionality (2 or 3) of the non-local surface tension kernel. |
NonLocalSurfaceTensionEpsilon |
<value> |
Interface thickness parameter ε for the non-local model. |
NonLocalSurfaceTensionKFactor |
<value> |
Kernel scaling factor for the non-local model. |
NonLocalSurfaceTensionNeighbours |
<n> |
Number of neighbour cells used in the non-local convolution. |
NonLocalSurfaceTensionBounds |
<v1> <v2> <v3> <v4> <v5> <v6> |
Bounding-box bounds for the non-local surface tension integration region (6 values). |
Evaporation (CST model)
| Option |
Arguments |
Description |
Evaporation |
cst |
Activate the Constant Stefan-flow evaporation model (CST). |
EvapEnthalpy |
<value> |
Latent heat of evaporation (J/kg). |
CSTDd |
<value> |
Diffusivity in the droplet phase Dd (m²/s). |
CSTDc |
<value> |
Diffusivity in the carrier phase Dc (m²/s). |
HenryCoeff |
<value> |
Henry coefficient for the vapour solubility at the interface. |
mDot |
<value> |
Prescribed evaporation rate ṁ (kg/(m²·s)) for the CST model. |
EnergyVOF |
— |
Activate the energy equation in the VOF framework. |
Marangoni convection
| Option |
Arguments |
Description |
MarangoniCoeff |
<dσ/dT> |
Thermal Marangoni coefficient dσ/dT (N/(m·K)). Activates thermocapillary convection. |
MarangoniTemp |
<T_ref> |
Reference temperature T_ref (K) for the Marangoni model. |
FRONTTRACKING
Activates the Front-Tracking (FT) interface method. The INTERFACES block is not needed alongside this.
FRONTTRACKING
NBodies 1
Centers 0.5 0.5 0.5
Diameters 0.2
SurfaceTensionCoefficient 0.072
END
Basic setup
| Option |
Arguments |
Description |
NBodies |
<n> |
Number of front-tracked bodies. Must be specified before Centers and Diameters. |
Centers |
<x1> <y1> <z1> [<x2> <y2> <z2> …] |
Initial centre coordinates of each body (3 × NBodies values, m). |
Diameters |
<d1> [<d2> …] |
Initial diameter of each body (m). Sets all three axes to this value. |
EllipsoidAxes |
<a1> <b1> <c1> [<a2> …] |
Initial semi-axis lengths (a, b, c) for each body (m), allowing non-spherical initialisation. |
ManualRefinement |
<level> |
XXX |
OutputFrequency |
<n> |
Write front-tracking surface mesh every n time steps. |
VolumeRecovery |
<n> |
Apply volume-recovery correction every n time steps to prevent volume drift. |
Advection and interpolation
| Option |
Arguments |
Description |
AdvectionScheme |
Euler | RungeKutta |
Time-integration scheme for advecting front-tracking markers. |
InterpolationMethod |
PESKIN | DIVFREE | LINEAR |
Method for interpolating the fluid velocity to FT markers. |
SpreadingMethod |
PESKIN | LINEAR |
Method for spreading FT surface forces back to the fluid grid. |
AssMethod |
— |
Activates the Anisotropic Surface Stress (ASS) / corrected-normal advection method. |
NOAMethod |
— |
Alias for AssMethod. |
Surface tension
| Option |
Arguments |
Description |
SurfaceTensionCoefficient |
<sigma> |
Surface tension coefficient σ (N/m). |
SurfaceTensionMethod |
Constant |
Constant surface tension via the Frenet-Serret element method (requires SourceTerms yes in NUMERICS). |
SurfaceTensionMethod |
Variable |
Variable surface tension via the Frenet-Serret element method. |
SurfaceTensionMethod |
User |
User-defined surface tension (via user file). |
SurfaceTensionMethod |
CSF |
Use the Continuum Surface Force approach for FT surface tension. |
Surface rheology
| Option |
Arguments |
Description |
SurfaceShearViscosity |
<eta_s> |
Surface shear viscosity η_s (N·s/m). Activates surface viscosity. |
SurfaceDilatationalViscosity |
<kappa_s> |
Surface dilatational viscosity κ_s (N·s/m). |
Betas |
<value> |
Surface rheology parameter β_s. |
Lambdas |
<value> |
Surface rheology parameter λ_s. |
CharacteristicSurfacePressure |
<value> |
Characteristic surface pressure used for normalisation in surface rheology. |
Shearrate |
<value> |
Applied shear rate (1/s) for surface rheology simulations. |
Topology changes
| Option |
Arguments |
Description |
BreakupCriteria |
<n> <threshold> |
Enable droplet breakup: n selects the criterion, threshold is the critical value. |
CoalescenceCriteria |
<n> <threshold> |
Enable droplet coalescence: n selects the criterion, threshold is the critical gap distance. |
Scalar transport on the surface
| Option |
Arguments |
Description |
SurfaceDiffusionCoefficient |
<value> |
Diffusion coefficient for a scalar transported on the FT surface (m²/s). |
InitialScalarConcentration |
<value> |
Initial uniform scalar concentration on all FT surfaces. |
SurfaceScalarMapping |
PESKIN | AREACLIPPING |
Method for mapping the surface scalar to/from the volume grid. |
Curvature and geometry
| Option |
Arguments |
Description |
ParabolicFitWeightRadius |
<value> |
Radius (normalised by local mesh spacing) of the neighbourhood used for the paraboloid curvature fit. |
FrontReconstruction |
VertexFit | VolumeFit |
Method for reconstructing the paraboloid fit used in curvature computation. |
RoughnessSmoothing |
TSUR3D | VCLS |
Smoothing method applied to the surface roughness. |
MaxRoughness |
<value> |
Maximum permitted roughness amplitude (m). |
MaxGeometricLaplacian |
<value> |
Maximum geometric Laplacian value used to limit surface smoothing. |
MaxCurvature |
<value> |
Maximum curvature value (1/m) allowed on the FT surface (clips extreme values). |
NeighbourhoodOrder |
<n> |
Order of neighbourhood used in the Wendland curvature computation. |
MinPointsInWendland |
<n> |
Minimum number of points required for the Wendland kernel fit. |
AMR coupling
| Option |
Arguments |
Description |
PBoxAdaptation |
<n> |
Adapt the particle box for AMR every n time steps. |
FixedPBox |
<xmin> <ymin> <zmin> <xmax> <ymax> <zmax> |
Fix the AMR particle box to the given bounding box. |
FTDomainMCToFTDomainResolution |
<n> |
XXX |
Indicator function
| Option |
Arguments |
Description |
IndicatorFunction |
POISSON | IRL |
Method for computing the indicator (volume fraction) function from the FT surface. POISSON solves a Poisson equation; IRL uses the Interface Reconstruction Library. |
Generic body acceleration
| Option |
Arguments |
Description |
GenericAcceleration |
BINARYCOLLISION <magnitude> |
Apply a generic acceleration (here a binary collision model) to FT bodies with the given magnitude. |
Force computation
| Option |
Arguments |
Description |
ComputeForces |
ForcesOnPrimaryPhase | ForcesOnSecondaryPhase |
Compute hydrodynamic forces on the FT body by integrating stresses on the primary or secondary phase side of the interface. |
FRONTREMESHING
Controls adaptive remeshing of the front-tracking surface mesh.
FRONTREMESHING
RemeshCriteria 0
ReferenceArea 1e-5
Remeshfrequency 5
RemeshIterations 3
END
| Option |
Arguments |
Description |
RemeshCriteria |
<n> |
Remeshing criterion: 0=area-based, 1=Botsch-Kobbelt standard, 2=Botsch-Kobbelt curvature, 3=Jiao. |
ReferenceArea |
<value> |
Target triangle area for area-based remeshing (m²). |
MaxAreaThreshold |
<value> |
Maximum allowed triangle area; triangles above this are split (m²). |
MinAreaThreshold |
<value> |
Minimum allowed triangle area; triangles below this are merged (m²). |
MaxLength |
<value> |
Maximum edge length for curvature-based remeshing (m). |
MinLength |
<value> |
Minimum edge length for curvature-based remeshing (m). |
Epsilon |
<value> |
Curvature tolerance ε used in curvature-based remeshing. |
Remeshfrequency |
<n> |
Perform remeshing every n time steps. |
RemeshIterations |
<n> |
Number of remeshing passes per invocation. |
Refine |
— |
Enable triangle refinement (splitting). |
Coarse |
— |
Enable triangle coarsening (merging). |
Flip |
— |
Enable edge flipping for quality improvement. |
Optimizer |
0 | 1 | -1 |
Load-balancing optimizer: 0=keep current decomposition, 1=load-balance, -1=sequential remesh (requires Cleanfrequency). |
OptimizerIterations |
<n> |
Number of optimizer iterations. |
DampingFactor |
<value> |
Damping factor for the load-balancing optimizer. |
SizeThreshold |
<value> |
Size threshold for the optimizer. |
MinNoOfTriangles |
<n> |
Minimum number of triangles per process for the optimizer. |
Cleanfrequency |
<n> |
Collect the surface mesh onto a single process and clean every n time steps. |
Tsurfrequency |
<n> |
Apply TSUR3D smoothing every n time steps. |
TangentialRelaxationFrequency |
<n> |
Apply tangential relaxation every n time steps. |
TangentialRelaxationIterations |
<n> |
Number of tangential relaxation iterations per invocation. |
MinQualityThreshold |
<value> |
Minimum triangle quality below which relaxation is triggered. |
MaxQualityThreshold |
<value> |
Maximum triangle quality above which relaxation is skipped. |
LaplacianSmoothingFrequency |
<n> |
Apply Laplacian smoothing every n time steps. |
LaplacianSmoothingIterations |
<n> |
Number of Laplacian smoothing iterations. |
VolumeConservingLaplacianSmoothingFrequency |
<n> |
Apply volume-conserving Laplacian smoothing every n time steps. |
VolumeConservingLaplacianSmoothingIterations |
<n> |
Number of volume-conserving Laplacian smoothing iterations. |
LaplacianSmoothingUnderRelaxation |
<value> |
Under-relaxation factor for Laplacian smoothing (0–1). |
VertexFit |
<n> |
Enable vertex-fit paraboloid reconstruction (n=1) after remeshing. |
ReferenceLength |
<value> |
Reference edge length for remeshing (ratio to fluid mesh spacing). |
DiameterToEdgelengthRatio |
<value> |
Target ratio of sphere diameter to edge length. |
MaxAngleBetweenTris |
<value> |
Maximum angle (degrees) between adjacent triangle normals for feature edge detection. |
ENRICHMENT
Generates a synthetic turbulent initial velocity field via a spectral enrichment method.
ENRICHMENT
NumDomainsX 4
NumDomainsY 4
NumDomainsZ 4
NumberofWaveNumbers 100
InitialTurbulentKE 0.01
END
| Option |
Arguments |
Description |
NumDomainsX |
<n> |
Number of sub-domains in X for the enrichment decomposition. |
NumDomainsY |
<n> |
Number of sub-domains in Y. |
NumDomainsZ |
<n> |
Number of sub-domains in Z. |
NumberofWaveNumbers |
<n> |
Number of Fourier modes used in the synthetic turbulence generation. |
WaveNumCutOff |
<value> |
Minimum wave number (cut-off) for the energy spectrum (m⁻¹). |
WaveNumMax |
<value> |
Maximum wave number for the energy spectrum (m⁻¹). |
InitialTurbulentKE |
<value> |
Target turbulent kinetic energy k₀ (m²/s²). |
TurbulentRe |
<value> |
Turbulent Reynolds number used to parameterise the initial spectrum. |
TaylorRe |
<value> |
Taylor-scale Reynolds number (alternative to TurbulentRe). |
ViscosityConstant |
<value> |
Kinematic viscosity ν (m²/s) used in the spectral enrichment. |
InterpolationAlpha |
<value> |
Under-relaxation factor α for blending the enriched field with the base field. |
TimeStepFactor |
<n> |
XXX |
TurbulentViscosity |
Const |
Use a constant turbulent viscosity in the enrichment. |
TurbulentViscosity |
RNG |
Use an RNG-based turbulent viscosity in the enrichment. |
CHEMISTRY
Activates the gas-phase chemistry solver.
CHEMISTRY
Solver FullyCoupled
SpaceDiscretisation UpWind
DiffusionType Fickian
END
| Option |
Arguments |
Description |
SpaceDiscretisation |
UpWind | CentralDifferences |
Spatial discretisation scheme for species transport. |
Solver |
SemiCoupled | FullyCoupled |
Coupling strategy between the chemistry and the flow solver. |
DisableGasReactions |
— |
Solve species transport but skip the chemical reaction source terms. |
Convergence |
<value> |
Convergence tolerance for the chemistry solver inner iterations. |
DiffusionType |
None |
No species diffusion. |
DiffusionType |
Fickian |
Fickian (binary) diffusion. |
DiffusionType |
Hirschfelder |
Multi-component diffusion via the Hirschfelder–Curtiss approximation. |
FixedProperty |
All |
Fix all fluid properties (density, viscosity, etc.) to their initial values throughout the simulation. |
FixedProperty |
Density |
Fix only the density to its initial value. |
!!! note
Additional FixedProperty sub-options (other than All and Density) may exist; check the source for the latest list.