CMIM Module
The cmim_avof module models compressible flow with immiscible materials.
Each material has its own equation of state (EOS) and may contain multiple
species. Materials share pressure, temperature, and velocity.
See the CMIM Theory Guide for the equations and numerical methods.
Basic Setup
Load cmim_avof and the EOS modules required by the materials. Use a fixed
mesh, SIMPLEC, first-order BDF time integration, and total enthalpy.
Add these entries to a case with mesh, boundary, time-step, and linear-solver settings.
They place liquid on the negative-x side of a plane at x=0 and gas on
the other side, at rest at 1 bar and 300 K. Supply gas.mdl and liquid.mdl
with one species each, no reactions, and properties valid at this state.
The liquid uses realFluid.
loadModule: realFluid
loadModule: cmim_avof
{
// Initial conditions
initialConditionRegions: <
default=state(u=0 m/s, p=1 bar, T=300 K, vof=[Gas=1]),
liquid=state(u=0 m/s, p=1 bar, T=300 K, vof=[Liquid=1]),
regions=[leftPlane(point=[0 m, 0 m, 0 m], normal=[1, 0, 0],
composition=liquid)]
>
// Flow properties
flowRegime: laminar
flowCompressibility: compressible
// Transport properties
transport_model: module
diffusion_model: none
// Time-stepping
timeIntegrator: BDF
// Fluxes
inviscidFlux: FOU
momentumInterpolationOptions: <form=new, conservativePressure>
// Pressure-correction equation
pressureBasedMethod: SIMPLEC
// Energy equation
energyEquationOptions: <form=totalEnthalpy>
// CMIM materials
materialModels: <
Gas=materialModel(chemistry_model=gas, eos_type=gas,
thermodynamic_model=adaptive, transport_model=const_viscosity,
mu=1.8e-5, kcond=0.026),
Liquid=materialModel(chemistry_model=liquid, eos_type=fluid,
thermodynamic_model=adaptive, transport_model=const_viscosity,
mu=0.001, kcond=0.6)
>
// CMIM transport
vofInviscidFlux: FOU
// Printing, plotting and restart parameters.
plot_output: vof, materialDensity
}
See Reconstruction for sharper interface transport. Surface tension and phase change are inactive unless configured.
Material Properties
Define named materials in materialModels using materialModel(...).
chemistry_model=gas selects gas.mdl; this file defines species,
thermodynamic data, and any reactions. It is required for inert materials too.
See Appendix: Thermodynamic Data for file syntax and lookup rules.
Option |
Requirement |
Meaning |
|---|---|---|
|
Required |
Material model filename without |
|
Required |
EOS name: |
|
Required |
Caloric model, such as |
|
Required |
|
|
With |
Positive constant viscosity, kg/(m s) |
|
With |
Positive constant conductivity, W/(m K) |
|
Optional pair |
Positive, finite EOS temperature bounds, K; minimum below maximum |
|
Optional pair |
Positive, finite EOS pressure bounds, Pa; minimum below maximum |
Bare coefficients use SI units. Omit mu and kcond for other transport
models. See Appendix: Transport Properties for transport data; select
these models inside each material and keep top-level transport_model: module.
Keep top-level diffusion_model: none; material diffusion is configured
under Turbulence and Diffusion.
Set EOS bounds to the verified range of each material model. Active material states must remain within them. Tabulated liquid/vapor branches may impose narrower limits than the table’s overall pressure and temperature range.
Initial and Boundary Conditions
Use initialCondition or
initialConditionRegions with pressure,
temperature, velocity, and vof=[material=fraction,...]. Names must match
materialModels; fractions must sum to one. Omitted materials are absent.
For active multispecies materials, also give materialComposition, such as
materialComposition=[Air=[N2=0.77,O2=0.23]]. Each composition must sum to
one; omitted species are zero. Single-species compositions are inferred.
Boundary Conditions
Use the shared boundary syntax with these material-state requirements:
Boundary |
Required state |
|---|---|
|
Usual wall or symmetry settings |
|
Mapped periodic pair |
|
Direct velocity, static temperature, |
|
Pressure; with |
For a single-species Gas material:
boundary_conditions: <
inlet=subsonicInlet(v=[1 m/s,0 m/s,0 m/s],T=300 K,vof=[Gas=1]),
outlet=fixedPressureOutlet(p=1 bar,entrainment,T0=300 K,vof=[Gas=1])
>
Use entrainment when backflow is expected. Its reservoir treatment uses
a low-Mach stagnation approximation. Open boundaries require a compatible
flux pair; inlet mass-flow and profile forms
are unsupported. Additional physics may restrict the boundary choices.
Closed-Surface Regions
initialConditionRegions accepts closed surface files. Select the
volume inside a SolidMesh .surf boundary with:
regions=[inSurface(file="liquid.surf",composition=liquid)]
Generate liquid.surf from a volume mesh named liquid.vog with:
vog2surf liquid -o liquid.surf
Surfaces must be closed, consistently oriented, and free of self-intersections; polygonal faces must be planar. Concave and disconnected volumes are supported.
For curved reconstruction, computegeom uses triangular and quadrilateral
VOG boundary faces. Run on one MPI process to write liquid.geom:
computegeom liquid
Select the resulting region with:
regions=[inGeometry(file="liquid.geom",subdivisions=4,
composition=liquid)]
subdivisions controls surface resolution (default 4; range 1–64).
Neither region form accepts VOG files directly.
Cell-Average Volume Fractions
Set cmimVOFInitialization: geometric to average regional fractions over
cells. For single-species Gas and Liquid materials:
cmimVOFInitialization: geometric
cmimGeometricVOFRefinement: 6
cmimGeometricVOFTolerance: 1e-4
initialConditionRegions: <
default=state(u=0 m/s,p=1 atm,T=300 K,vof=[Gas=1]),
liquid=state(u=0 m/s,p=1 atm,T=300 K,vof=[Liquid=1]),
regions=[inSphere(center=[0.5 m,0.5 m,0.5 m],radius=0.25 m,
composition=liquid)]
>
Option |
Default |
Meaning |
|---|---|---|
|
|
|
|
|
Maximum subdivision depth: 0–8, or 0–5 for three or more materials in 3-D. |
|
|
Absolute volume-fraction tolerance for two-material 3-D initialization:
|
Geometric initialization requires a fixed Cartesian mesh with convex cells:
In 2-D, use
grid_file_info: <twoDimensions>and cells extruded in z. Regions must span the thickness: vertical cylinders, boxes, planes with zero z normal, or extrudedinSurfaceandinGeometryboundaries.In 3-D, cell faces must be planar. Supported regions are
inSphere,inBox,leftPlane,inSurface, andinGeometry. With three or more materials, cells must also admit a positive cell-center tetrahedralization matching the mesh volume.
For two-material 3-D initialization, increase refinement if the tolerance cannot be met, or relax the tolerance if a work limit is reached. Small fractions may need a smaller tolerance. For 2-D overlaps or three or more materials, check volume convergence with refinement; the tolerance is unused.
Only volume fractions are averaged. Pressure, temperature and velocity retain their regional values, and each material must have the same active composition in every region. Native restart uses the saved state; startup mesh adaptation reevaluates the geometric initialization on the refined mesh.
Initial Condition Programs
In initialConditionProgram, use
alpha_<material> for volume fractions and Y_<material>_<species> for
material-local mass fractions in model=fields(...). Encode non-alphanumeric
bytes in material and species names as _HH with uppercase hexadecimal;
for example, _Air becomes _5FAir. The volume-fraction and composition
requirements above also apply to program states.
Program initialization samples cell centers and does not support
cmimVOFInitialization=geometric.
For hydrostatic pressure, CMIM evaluates density from the material equations of state.
Numerical Controls
Select the flow and material fluxes together. The equation controls below set solver work, relaxation, and convergence; gravity options follow.
Reconstruction
Select a supported flow/material flux pair. vofInviscidFlux defaults to
FOU; use MIG for sharp material interfaces.
|
|
Requirements |
|---|---|---|
|
|
Closed, periodic, or supported open boundaries. |
|
|
|
|
|
|
|
|
|
For SOU, SLAU, SLAU2, and AUSMUP, omit
consistentEnthalpyProjection from energyEquationOptions.
For bodyForceWeighted interpolation, see the
compatibility requirements.
Equation Controls
Set material advection and convergence controls in vofEquationOptions;
set the species solver in materialSpeciesEquationOptions:
vofEquationOptions: <materialAdvection=implicit,requireConvergence=on>
materialSpeciesEquationOptions: <linearSolver=SGS,relaxationFactor=0.5>
Option |
Default |
Values and meaning |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
Volume-fraction update tolerance, including post-pressure material appearance. |
|
|
Material-volume residual tolerance. |
|
|
Material continuity residual tolerance. |
|
|
Volume-fraction bound and sum-to-one tolerance; must lie in (0,0.5). |
These tolerances are dimensionless, finite, and nonnegative;
admissibilityTolerance must lie in the range shown above.
Invalid states and unconverged material appearance always abort.
Option |
Default |
Values and meaning |
|---|---|---|
|
|
Only |
|
|
Finite value in (0,1]. |
|
|
Positive integer; maximum linear-solver iterations. |
|
|
Finite, nonnegative relative species-density update tolerance. |
|
|
Species densities from minus this tolerance up to zero are set to zero; more negative values abort. Zero rejects every negative density. |
|
|
Zero an entire material below this partial-density cutoff. Equality and
trace species in retained materials are preserved. Materials participating
in |
Both density controls must be finite and nonnegative; bare values use kg/m³.
The material cutoff applies after the species solve and to both saved time
levels on restart. Cleanup changes mass. Species residual tolerances use the
species entries in convergenceAbsoluteTolerance and
convergenceRelativeTolerance;
see Time Step Convergence.
CMIM ignores linearSolver, relaxationFactor, maxIterations, and
residualTolerance in vofEquationOptions and prints a warning.
Composition Limiters
Composition limiters affect material-local mass fractions and their enthalpy
flux. Non-Barth choices require inviscidFlux: SOU; the flow limiter stays
barth.
Option |
Default |
Values and meaning |
|---|---|---|
|
|
|
|
|
Finite, nonnegative smoothing parameter for non-Barth choices. |
|
|
For |
AUSM Parameters
AUSMUP accepts an optional cmimAUSMFluxParameters block:
cmimAUSMFluxParameters: <Kp=0.25,Ku=0.75>
Option |
Default |
Meaning |
|---|---|---|
|
|
Pressure-jump dissipation in the mass flux |
|
|
Velocity-jump dissipation in the face pressure |
|
|
Controls the decrease of pressure-jump dissipation with Mach number |
|
|
Mach-number floor for pressure-jump dissipation |
|
|
Mach-number floor for pressure splitting and velocity-jump dissipation |
All values must be finite. Kp, Ku, and sigma lie in [0,1];
the Mach cutoffs lie in (0,1].
Gravity Density
In buoyancyOptions, density=current (default) uses density entering
the nonlinear sweep. density=predictor uses density after material
prediction for both cell and face gravity. It changes nonlinear coupling,
with the same converged equations.
inviscidFlux: FOU
momentumInterpolationOptions: <form=old,conservativePressure>
gravity: <g=[0.0,-9.81,0.0],rhoref=0.0>
buoyancyOptions: <conservative,density=predictor>
Predictor density requires gravity, form=old, conservative buoyancy,
and FOU or SOU flow fluxes. Use a fixed Cartesian or axisymmetric
mesh with only noslip, slip, or symmetry boundaries.
Hydrostatic Reference
cmimHydrostaticReference: on (default off) preserves a prescribed
hydrostatic background while allowing heating, transport, and perturbations.
Load initial_conditions and supply a
hydrostatic initialConditionProgram
with explicit reference=plane(...). The gravity-aligned line through its
point defines the background temperature and material distribution; prescribe
zero velocity there. Retain this program and material models on restart.
Flux |
Required settings |
|---|---|
|
|
|
|
|
Standard or conservative buoyancy on a Cartesian mesh; omit |
Set form and conservativePressure in momentumInterpolationOptions,
and pressureReconstruction in momentumEquationOptions.
For both form=Denner and form=old, omit highOrder and modified.
Use a fixed mesh without adaptive remeshing, constant nonzero gravity with
rhoref=0, and closed noslip, slip, or symmetry boundaries.
The pressure-based combinations also support axisymmetry with
centroid: wireframe when gravity is parallel to the x axis.
Noninertial frames are unsupported.
If cmimHydrostaticReference is omitted, cmimSlauHydrostaticReference
supplies its value.
Output and Restart
Use the shared output controls for field selection and frequency. Optional model-specific fields and counters are listed under Detailed Diagnostics.
Material and Species Output
Default plots include vof_<material> (volume fraction) and
Y_<species> (mixture mass fraction), selected by vof and mixture.
Identical species names across materials contribute to the same mixture field.
Select additional families with plot_output:
Selector |
Output names |
Meaning |
|---|---|---|
|
|
Material mass divided by mixture mass. |
|
|
Material mass per mixture volume, in kg/m³. |
|
|
Intrinsic material density, in kg/m³; zero where absent. |
|
|
Species mass fraction within the material; zero where absent. |
|
|
Material density times species diffusivity, in kg/(m s). |
Fields are interpolated to nodes; interface nodes may contain intermediate values. Plot selection does not affect restart data.
At print events, output/materialVolume.dat records each material’s
volume in m³; output/cmimMaterialMass.dat records material and species
masses in kg. Material volume can change in compressible flow.
Convergence Status
cmimResidualOutput: species (default) prints one RV_<n>: line per
material at each nonlinear iteration. The columns contain the cycle,
iteration, and species residuals in kg/s. Each residual is the sum of
absolute cell residuals. A startup legend identifies the column order:
# RV_1: material="Gas" index=0 species=["H2"] units=kg/s norm=global_L1
RV_1: 1363 62 1.200000e-08
cmimResidualOutput: summary prints one RV: line containing the
maximum species residual in each material.
The final nonlinear iteration prints CMIM_STOP: cycle iteration
cmim_ok=... all_ok=... at_limit=.... cmim_ok reports CMIM convergence;
all_ok includes all active equations. at_limit is one when
maxIterationsPerTimeStep has been reached.
Plot nonlinearConverged to distinguish convergence (1) from failure (0),
and nonlinearIterationLimitReached to detect the iteration cap (1).
Convergence can occur at the cap. These spatially uniform fields report the
final iteration, or each written iteration with plot_output_iteration: on.
Restart
Use the standard restart procedure and retain the complete CMIM checkpoint, including its state manifest. Material/species definitions, model settings, EOS bounds, and reaction data must match the saved state. Volume-fraction and composition plots alone cannot restore it. The material-density cutoff also applies when reading a restart.
Turbulence and Diffusion
For Menter SST 2003 turbulence, specify:
flowRegime: turbulent
turbulenceEquationOptions: <model=menterSST2003>
Supply k and omega in initial and inlet states (regional states
also accept w for omega). Single-species and multispecies materials
are supported; DES, LES, and rhok are not. See
Turbulence Equations for solver controls.
When molecular or turbulent species diffusion is active, use:
gradStencil: standard
gradType: standard
Omit noSpeciesEnthalpyDiffusion from energyEquationOptions so that
species diffusion also transports enthalpy.
Material Diffusion
Molecular and turbulent diffusion are independent. In turbulent flow,
multispecies materials use turbulent mixing by default, even when their
molecular diffusion_model is none.
Option |
Default |
Values and meaning |
|---|---|---|
|
|
|
|
Unset |
Positive molecular diffusivity in m²/s. Required with |
|
|
|
turbulentSchmidtNumber sets \(Sc_t\) for all materials (default 0.95;
positive and finite). Diffusivity is \(D_t=\mu_t/(\rho Sc_t)\), using
mixture density and eddy viscosity. interfaceTurbDamping affects only
momentum viscosity.
Species diffuse between neighboring cells containing the same material. Periodic boundaries are supported. Physical boundaries have zero species diffusion flux; open boundaries carry species by convection. Conversion within one material has additional diffusion restrictions.
Surface Tension
For two materials, specify their surface tension in sigma_ij using names
from materialModels:
sigma_ij: <Liquid__Gas=0.072 N/m>
momentumInterpolationOptions: <form=new,conservativePressure>
The default cmimCapillaryModel: singlePair requires exactly two materials.
The first named material defines color one and the contact-angle side.
Use new or Denner momentum interpolation. A nonzero global sigma
is rejected because it does not identify a pair.
Select curvature below; wall contact is optional. See Curvature Output for output fields.
Curvature Selection
|
Method |
|---|---|
|
Gradient interpolation and face-normal divergence. |
|
Optional face-based color smoothing, then face-normal divergence. |
|
Optional nodal color smoothing, then curvature from nodal normals. |
|
Taylor-fit derivatives and curvature averaging; requires |
|
Geometric reconstruction and integrated paraboloid fit. Requires
|
|
Prescribed constant |
|
Curvature from an auxiliary level-set grid; requires |
The experimental faceDivergence and nodalDivergence methods accept
vof_curvature_smoothing_passes (default 2, nonnegative integer).
Zero disables smoothing. Smoothing changes only the curvature calculation.
Both methods require fixed Cartesian 2-D or 3-D meshes and support
symmetry, noslip, slip, subsonicInlet, and fixedPressureOutlet
boundaries. Inlets use prescribed material fractions; entraining outlets
use reservoir fractions during backflow. Outflow uses adjacent-cell values.
Keep curved interfaces away from outlets where this extrapolation can
introduce curvature errors. Outlet-corner wetting is unsupported.
direct, faceDivergence, and nodalDivergence accept normalFloor
in curvatureOptions. Omit this block for other methods.
vof_curvature_type: nodalDivergence
curvatureOptions: <normalFloor=1e-3>
normalFloor must be positive and finite. It is a dimensionless color
change over the local cell spacing. Its default is 1e-5 for direct
and 1e-8 for faceDivergence and nodalDivergence.
Larger values suppress weak normals and reduce the local capillary force, including at contact boundaries. Check sensitivity to this setting for the selected curvature method.
Wall Contact Angle
vof_contact_angle_model selects none (default), static or
dynamic. Each wall can override it with contactAngleModel.
none leaves interface normals uncorrected.
For a single pair, vof_contact_angle_deg defaults to 90 degrees (range 0–180).
Override it per wall with contactAngle=30 deg or a named pair:
sigma_ij: <Liquid__Gas=0.072 N/m>
momentumInterpolationOptions: <form=new,conservativePressure>
vof_contact_angle_model: none
boundary_conditions: <wall=noslip(adiabatic,contactAngleModel=static,
contactAngles=[Liquid__Gas=30 deg])>
In contactAngles, angles are measured through the first named material;
Gas__Liquid=150 deg gives the same condition. Use names from
materialModels and supply either contactAngle or contactAngles.
Static angles support noslip and slip walls. Angles require an active
contact-angle model.
For faceDivergence and nodalDivergence,
vof_curvature_wall_treatment: boundary (default) corrects the boundary
normal. cellGradient also corrects adjacent cell gradients, except where
corner angles conflict or the interface direction is unresolved.
dynamic is experimental and requires direct curvature and a noslip
wall. vof_dynamic_contact_angle_coeff defaults to 9 (nonnegative).
vof_dynamic_contact_angle_min_deg and vof_dynamic_contact_angle_max_deg
bound the angle; defaults are 5 and 175 degrees. The model does not provide
wall slip or contact-angle hysteresis.
faceDivergence, nodalDivergence and celeste support static angles
only. paraboloid2019 additionally requires planar walls in 2-D.
rlsg does not support wall contact. Spreading-rate accuracy is not established.
RLSG Curvature
RLSG reconstructs curvature on an auxiliary Cartesian grid. It supports
interior interfaces on fixed, convex 2-D meshes; wall contact and 3-D
fraction reconstruction are unsupported. Load rlsg before the
control-file block and select:
vof_curvature_type: rlsg
rlsg_seed_type: volumeFit
gradStencil: standard
use_cellStencil: 1
vof_contact_angle_model: none
rlsg_grid_mode: automatic
rlsg_grid_splits: 1
gradStencil: full may replace standard with use_cellStencil: 1.
Set rlsg_seed_type: volumeFit explicitly; the default is plic.
Automatic spacing uses the smallest face-normal cell width near the initial
interface, divided by two for each rlsg_grid_splits (default 1).
rlsg_grid_max_splits limits the split count (default 3; allowed range
0–20). In a pure-material initial state, the width is taken over the whole mesh.
For a prescribed spacing, use rlsg_grid_mode: manual (the default) and
set rlsg_grid_spacing to a positive value in metres. Automatic mode
requires rlsg_grid_spacing to remain zero. Spacing is uniform and fixed
during a run; automatic mode recalculates it on restart. Manual mode preserves
the chosen spacing across restarts.
Three-Material Surface Tension
The experimental cmimCapillaryModel: threePhaseCSF computes surface tension for exactly
three immiscible materials. Supply all three pairs using names from
materialModels. This example includes static wall contact:
cmimCapillaryModel: threePhaseCSF
sigma_ij: <matA__matB=0.072 N/m,matA__matC=0.072 N/m,
matB__matC=0.100 N/m>
momentumInterpolationOptions: <form=new,conservativePressure>
vof_curvature_type: nodalDivergence
vof_curvature_smoothing_passes: 2
vof_contact_angle_model: none
cmimSurfaceTensionTreatment: standard
boundary_conditions: <
wall=noslip(adiabatic,contactAngleModel=static,
contactAngles=[matA__matB=60 deg,matA__matC=90 deg])
>
Pair order in sigma_ij does not matter. Each coefficient must be positive
and smaller than the sum of the other two. Use nodalDivergence curvature,
standard surface-tension treatment, and new or Denner momentum
interpolation.
The mode accepts fixed Cartesian 2-D and 3-D meshes with symmetry,
noslip, slip, subsonicInlet and fixedPressureOutlet boundaries.
Inlets use prescribed material fractions. For outlet backflow, supply
entrainment, T0, vof and materialComposition. Keep curved
interfaces away from outlets; extrapolated curvature can prevent convergence.
Static wetting requires vof_curvature_wall_treatment: boundary (default).
Supply two pair angles in contactAngles; these and sigma_ij determine
the third. An optional third angle must agree within 0.5 degrees. All
resulting angles must lie strictly between 0 and 180 degrees. Startup output
CMIM_WETTING_ANGLES lists the angles used. Without contactAngles,
static walls use 90 degrees for all pairs; leave vof_contact_angle_deg at
90. Scalar contactAngle is unsupported.
vof_wetting_trace_tolerance defaults to 1e-6 and must be in [0,1).
Below this smallest-to-largest color-gradient ratio, the wall correction
blends toward the dominant pair. Zero disables blending.
With diagnostics: <cmimCapillary>, CMIM_WETTING reports counts of
active wall faces, trace blends and unresolved interface directions.
Dynamic angles, complete wetting, phase change, AMR and surfaceDiffusion
are unsupported. Use
Cell-Average Volume Fractions for cell-average initial fractions.
Phase Change
phaseChangeModels selects named transfer channels. Use surfaceTransfer
for evaporation and condensation at resolved liquid/gas interfaces, or
volumetricTransfer for pressure-driven cavitation. These channel types
cannot be combined. Omit phaseChangeModels to disable phase change.
See Phase-Change Output for transfer rates and heat balances.
Thermal Surface Phase Change
kunkelmann uses the saturation temperature; schrage couples kinetic
mass transfer to the interface heat balance. Both require a pure liquid
donor. For liquid hydrogen and its vapor:
phaseChangeModels: <hydrogen=surfaceTransfer(
donorMaterial=Liquid,receiverMaterial=Gas,
constituents=[map(donorSpecies=_LH2,receiverSpecies=H2)],
model=kunkelmann(
saturation=antoine(A=3.54314,B=99.395,C=7.726,
pressureUnit=bar,temperatureUnit=K,Tmin=20.01 K,Tmax=32.27 K),
thermalBandLayers=8,
redistribution=hardtWondra(
interfaceValue=0.5,pureMaterialCutoff=1e-3,
smoothingLength=0.05 m)
)
)>
Use material and species names from materialModels. kunkelmann
requires a pure vapor receiver; schrage also accepts a gas mixture with
an ideal-gas, real-fluid, or tabulated EOS. Map the liquid to its vapor species.
Set enthalpy references so vapor enthalpy minus liquid enthalpy gives the
positive latent heat at the interface. Both models use total enthalpy and
require saturation and redistribution.
Use a fixed, nonperiodic Cartesian mesh or a single-layer meridional mesh
with gridCoordinates: axisymmetric (x axial, y radial). Interfaces must
be separated: three-material cut cells and capillary corrections to phase
equilibrium are unsupported. The interface solve respects the
material EOS bounds and
saturation range.
For several liquids evaporating into one gas mixture, give each liquid a
named surfaceTransfer channel using schrage and the same
receiverMaterial. Each channel has its own species map, saturation law,
and controls. Each species may belong to only one liquid/vapor pair.
Thermal Sampling
thermalBandLayers sets the pure-material sample search depth: 1–64 cell
layers, default 8. Both sides must contain pure-material cells within this
band; the gas material may contain several species. Smaller bands reduce
search work but must still reach both samples.
Transfer that exhausts a material or species aborts; reduce the timestep.
With speciesProduction: CVODE, available mass is checked after chemistry.
Redistribution
Set source smoothing and solver controls inside redistribution=hardtWondra(...):
Option |
Default |
Meaning and limits |
|---|---|---|
|
Required |
Interface donor volume fraction; must be |
|
Required |
Pure-material fraction tolerance in (0,0.5) |
|
Required |
Positive smoothing length, with length units |
|
|
Relative residual tolerance in (0,1) |
|
|
Positive maximum linear iterations for each evaporation or condensation solve |
Each channel is smoothed independently. Donor and receiver sources are separately normalized to the transfer rate. Missing pure-material support or failure to converge aborts the run.
smoothingLength changes the spatial distribution; linearSolverTolerance
controls solve accuracy. Check transfer rates, heat balances, and runtime
when loosening the tolerance. petscSolverOutput: on writes iterations,
residuals, and redistribution checks to debug/debug or MPI debug/debug.N.
Schrage Model
Replace kunkelmann(...) with schrage(...), retain the saturation and
redistribution entries, and add accommodationCoefficient. For example:
accommodationCoefficient=0.001,
vaporTemperature=sampled,
Schrage approximates vapor partial pressure as sampled vapor mole fraction times total pressure. Other gas species receive no transfer source. Species enthalpies use total pressure and interface temperature.
Option |
Default |
Meaning and limits |
|---|---|---|
|
Required |
Kinetic accommodation coefficient in (0,1] |
|
|
|
|
|
Positive absolute temperature-bracket tolerance |
|
|
Residual tolerance relative to the sum of absolute donor, receiver, and latent heat fluxes; range [0,1) |
|
|
Nonnegative absolute heat-flux residual tolerance, W/m² |
|
|
Positive limit for the interface-temperature solve; separate from the redistribution limit |
The solve must meet both the temperature tolerance and the heat-balance
limit (absolute plus relative tolerance times the heat-flux scale).
At least one heat-balance tolerance must be positive. Failure to converge
within maxIterations aborts. Controls apply independently to each channel.
Volumetric Cavitation
Select zwart, merkle, or schnerrSauer inside
volumetricTransfer. Each channel has one liquid/vapor species map:
phaseChangeModels: <hydrogen=volumetricTransfer(
liquidMaterial=Liquid,vaporMaterial=Gas,
constituents=[map(liquidSpecies=_LH2,vaporSpecies=H2)],
model=zwart(
saturation=antoine(A=3.54314,B=99.395,C=7.726,
pressureUnit=bar,temperatureUnit=K,Tmin=17 K,Tmax=32.27 K),
bubbleRadius=1e-6 m,nucleationVolumeFraction=5e-4,
vaporizationCoefficient=50,condensationCoefficient=0.01
)
)>
Liquid and vapor species must be distinct, have matching molecular masses, and belong to their named materials. Use compatible EOS and enthalpy references. Each species may appear in only one pair. Additional channels may share materials and use different models or coefficients.
Both laminar flow and Menter SST 2003 are
supported. For conversion within one material, use the same material name
on both sides and set its diffusion_model=none and, in turbulent flow,
turbulent_diffusion_model=none.
The aliases donorMaterial, receiverMaterial, donorSpecies, and
receiverSpecies are accepted. Supply either the liquid/vapor name or
its alias for each option.
Model Parameters
All three models require saturation=antoine(...),
vaporizationCoefficient, and condensationCoefficient. Transfer
coefficients are dimensionless, nonnegative, and cannot both be zero.
No model coefficients have defaults.
Model |
Parameters |
Units and limits |
|---|---|---|
|
|
Positive radius, m; fraction in (0,1) |
|
|
Positive values in m, m/s, and kg/m³; density unit syntax is |
|
|
Positive bubble count per m³ of liquid, entered as a real number; positive radius, m |
To convert Merkle coefficients from cavitation_nist, use
vaporizationCoefficient=1/tauVap and condensationCoefficient=1/tauCond
with the same reference quantities. Enter the evaluated numbers.
Operating Limits
Transfer rates are not clipped; reduce the timestep if a source would consume more species than available. Zwart and Merkle can create either missing phase. Schnerr–Sauer nucleates vapor in pure liquid but has zero rate in pure vapor.
These models use total mechanical pressure. They do not model gas dissolution, vapor partial-pressure equilibrium, or heat-limited evaporation. The entire cell-temperature range must lie within the saturation correlation and both phase EOS ranges, including where a phase is initially absent.
Saturation Laws
antoine(...) is available for both surface and volumetric transfer.
Supply A, B, C, pressureUnit, temperatureUnit, Tmin, and
Tmax, as in the examples above. Pressure units are Pa, kPa, MPa,
or bar; use temperatureUnit=K. States used to evaluate saturation
must stay between Tmin and Tmax.
Surface transfer also accepts:
saturation=clausiusClapeyron(
referencePressure=103632 Pa,referenceTemperature=20.35 K,
referenceLatentHeat=445800 J/kg,Tmin=20.01 K,Tmax=32.27 K)
referenceLatentHeat sets the saturation slope. Material EOS enthalpies
set the latent heat in the interface heat balance.
Chemistry
Reactions listed in a material’s .mdl file are active automatically;
an empty reaction list gives an inert material. Reactions consume and
produce species within that material. Use mechanisms that conserve mass
and elements, with enthalpy references consistent with their reaction heats.
Arrhenius coefficients must be finite with nonnegative prefactors.
Ideal-gas, real-fluid, and tabulated EOS are supported. Thermodynamic reverse rates use caloric reference data without real-fluid Gibbs corrections; a real-fluid EOS does not supply EOS-consistent chemical equilibrium. Do not add a separate reaction-heat source to total enthalpy.
Integration Controls
Use BDF, total enthalpy, and operatorSplitting: source (default).
speciesProduction selects instantaneousImplicit (default) or
CVODE for stiff reactions. CVODE applies first-order chemistry-then-transport
splitting and conserves cell internal energy during chemistry;
operatorSplittingEOS does not change that closure.
speciesProduction: CVODE
operatorSplitting: source
cvodeRelativeTolerance: 1e-10
The example tightens the relative tolerance for ignition calculations. Check reaction results against tolerances and flow timestep.
Input |
Default |
Meaning |
|---|---|---|
|
|
Required CVODE Jacobian form |
|
|
Required CVODE linear solver |
|
|
Positive, finite relative integration tolerance |
|
|
Positive, finite absolute species-density tolerance, kg/m³ of cell volume |
|
|
Finite, nonnegative temperature below which reaction rates are zero, K |
Explicit reaction sources, BDF2 chemistry, and Strang splitting are unsupported. Keep states within the material EOS bounds. See Chemistry Diagnostics for species rates and integration diagnostics.
Reactions Between Materials
materialReactions converts a species into products in other materials.
It requires speciesProduction: CVODE and defaults to an empty list.
For synthetic species _A and _B with equal molecular masses and
consistent enthalpy references:
speciesProduction: CVODE
materialReactions: <
conversion=irreversible(
reactants=[species(material=Liquid,name=_A,coefficient=1)],
products=[species(material=Gas,name=_B,coefficient=1)],
rate=Arrhenius(C=10,eta=0,theta=0))
>
Each reaction has one reactant with coefficient 1 and positive molar
product coefficients. At least one product must enter another material;
others may remain in the donor. Names must match the material models.
Mass and elements must balance; underscore test species receive only the
mass check.
The first-order rate is k=C*T^eta*exp(-theta/T). Supply all three finite
coefficients as numeric SI values: nonnegative C in s⁻¹ K⁻ᵉᵗᵃ,
dimensionless eta, and theta in K.
Multiple reactions share available species. Products can create an absent material and react through its local mechanism during the same chemistry interval. Product EOS models must cover the resulting state. This bulk conversion applies wherever the reactant exists; use Phase Change for evaporation and condensation.
Detailed Diagnostics
Diagnostics and plots do not change convergence or time-step acceptance.
Convergence and Conservation
Select groups with diagnostics:
diagnostics: <cmimConvergence,cmimCapillary>
Selector |
Output |
Contents |
|---|---|---|
|
Console |
Normalized convergence checks, listed below. |
|
|
Material presence, volume-fraction bounds, and composition changes. |
|
|
Pressure-equation residuals, volume balance, and continuity errors. |
|
|
Material and species transport residuals. |
|
|
Maximum curvature and capillary CFL number when surface tension is active. |
cmimAVOF enables all groups in this table. Diagnostic files are written
under output/. Invariant, pressure, and transport files contain one row
per nonlinear iteration; capillary output follows the print frequency.
Fresh runs replace these files. Restarts retain earlier rows and replace
rows from the resumed state onward.
In RCMIM: output, numerical ratios at or below one pass their checks.
The two flags use the values specified in the table.
Field |
Meaning |
|---|---|
|
Largest species equation residual relative to its convergence limit. |
|
Volume-balance and continuity errors relative to their tolerances. |
|
Species and volume-fraction changes relative to their limits. |
|
Newly appearing material update relative to its limit. |
|
Volume-fraction bound and sum-to-one errors relative to their limits. |
|
Zero when volume fractions are valid. |
|
One when all CMIM convergence checks pass. |
Curvature Output
For single-pair surface tension, kappa is the curvature on the flow mesh,
in inverse metres. Three-material surface tension provides
capillaryKappa0, capillaryKappa1, and capillaryKappa2, in the
material order printed at startup. capillaryForce is the total force
per unit volume, in N/m³.
With RLSG curvature, the following selectors write the auxiliary mesh and fields:
Selector |
Quantity |
|---|---|
|
Auxiliary mesh only. |
|
Signed distance, in metres; zero defines the interface. |
|
Initial distance seed, in metres. |
|
Auxiliary curvature, in inverse metres. |
Each field includes its mesh and a validity field, such as rlsgLevelSetValid.
Files use output/<case>_SURF.rlsg/ and the normal plot frequency. Extract with:
extract -vtk -bc rlsg case 10 rlsgLevelSet rlsgLevelSetValid \
rlsgKappa rlsgKappaValid
Open case_vtk.10/rlsg_Surf.vtu. Threshold the corresponding validity field
to one with All Scalars enabled; invalid entries contain zero. Contour
rlsgLevelSet at zero. The auxiliary mesh lies at z=0.
See RLSG Grid-Spacing Utility for spacing comparisons.
Phase-Change Output
Add cmimPhaseChange to diagnostics to write
output/cmimPhaseChange.dat. The file reports signed transfer,
evaporation, condensation, and conservative material/species sources.
Positive signed rates denote evaporation; negative rates denote condensation.
With multiple channels, the file also includes these columns for each
configured channel name:
Column |
Meaning |
Units |
|---|---|---|
|
Net transfer rate |
kg/s |
|
Evaporation rate (nonnegative) |
kg/s |
|
Condensation rate (nonnegative) |
kg/s |
Aggregate evaporation and condensation include all channels, even when
their signed rates cancel. With multiple channels, the donorMaterial
and receiverMaterial index columns contain -1.
Transfer within one material has zero material mass source and nonzero
mapped species sources.
Single-channel surface models also write output/cmimPhaseChangeSurface.dat at each
nonlinear iteration. Use the final converged row of each timestep for
histories. Axisymmetric areas and rates refer to the full revolution.
Columns |
Meaning |
Units |
|---|---|---|
|
Interface area |
m² |
|
Heat supplied by each side and their sum |
W |
|
Net transfer before smoothing, after normalization and in the source |
kg/s |
|
Nonnegative gross rates; net transfer may vanish |
kg/s |
|
Integrated material sources; their sum should be zero |
kg/s |
|
Interface heat/enthalpy balance error |
W |
Multiple surface channels write output/cmimPhaseChangeChannels.dat with
one row per channel and nonlinear iteration: cut-cell count, area,
area-averaged interface temperature and vapor mole fraction, heat rates,
signed and absolute mass rates, and the interface energy-balance residual.
Heat rates refer to the interface. Single-channel plot selectors are phaseChangePairColor,
phaseChangeContourCells, phaseChangeInterfaceBand,
phaseChangeMassFlux and phaseChangeSharpMassSource.
Chemistry Diagnostics
With CVODE, diagnostics: <cmimChemistry> writes
output/cmimChemistry.dat at print_freq: cell counts, integration work,
solver counters, and the slowest cells. Summed cell time measures aggregate
work; identifiers are rank-local, so locate cells by the reported coordinates.
Select spatial counters through plot_output:
Field |
Quantity per completed chemistry interval |
|---|---|
|
Cell integration time, seconds. |
|
Internal CVODE steps. |
|
CVODE RHS calls, excluding Jacobian calls. |
|
Additional RHS calls for the numerical Jacobian. |
|
Jacobian evaluations. |
|
Internal nonlinear iterations. |
|
Failed accuracy tests. |
|
Internal nonlinear convergence failures. |
|
Rejected RHS pressure/temperature reconstructions. |
Counters and mean rates are zero on initial/restart plots, then retain the last completed interval. Summary rows start after the first interval. Failure counters count different events; their sum is not a rejected-step count.
Select species rates with quoted Material::Species names:
speciesProduction: CVODE
diagnostics: <cmimChemistry>
chemistryOutputSpecies: "Gas::H2","Gas::OH"
plot_output: chemistryTime,chemistrySteps,chemistryMeanProductionRate
chemistryProductionRate is the instantaneous rate for either method;
chemistryMeanProductionRate is the CVODE chemistry increment divided by
the timestep, excluding transport. Rates include local and cross-material
reactions, in kg/(m³ s) of cell volume; positive means production.
Names append the species, e.g. chemistryProductionRate_Gas::H2.