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.
For transport_model=tabularEoS, every species must use eos=Table(...).
Its table manifest must contain viscosity and conductivity fields, for example:
file viscosity viscosity_logP_logT.kd
file conductivity conductivity_logP_logT.kd
Place tables in ./EoSTables/<name> or
$CHEMISTRY_DATABASE/data_base/EoSTables/<name>. Use positive transport
properties and table bounds covering the material’s declared EOS range.
Set the manifest bounds to match the table axes.
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.
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.
Boundary Conditions
Use the shared boundary syntax.
For a single-species Gas material:
boundary_conditions: <
Inlet=subsonicInlet(mdot=0.01 kg/s, T=300 K, vof=[Gas=1]),
Outlet=fixedPressureOutlet(p=1 bar)
>
For prescribed material states, supply materialComposition for each
multispecies material with a nonzero volume fraction. For pressure-outlet
backflow, add entrainment with reservoir p, T0 and vof;
this uses a low-Mach stagnation approximation.
Boundary |
Required inputs |
|---|---|
|
Usual wall or symmetry settings |
|
Mapped periodic pair |
|
One of |
|
|
|
|
|
|
|
One of |
|
One of |
|
None |
See flow-rate specifications
for units, signs, expressions and history files. Rates and prescribed static
temperature are evaluated at startTime during initialization and at the
end of each time step, including after restart.
Inlets use the prescribed material state during inflow and the interior state during outflow. Fixed mass and volume outlets use negative rates for outflow. Select the flux pair for the boundary types and surface-tension settings in the case.
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. |
|
Smoothed color and least-squares curvature. Requires |
|
Geometric reconstruction and integrated paraboloid fit. Requires
|
|
Prescribed constant |
|
Curvature from an auxiliary level-set grid; requires |
The 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, and keep wall contact lines away from outlet corners.
celeste supports fixed Cartesian 2-D and 3-D meshes, symmetry, slip and
no-slip walls, prescribed inlet fractions, pressure outlets, and periodic
boundaries. Use gradStencil: standard with use_cellStencil: 1 for
periodic flow with momentumInterpolationOptions: <form=new,conservativePressure>.
CELESTE uses one smoothing pass for curvature estimation. Smoothing leaves
the transported material fractions unchanged. See Wall Contact Angle for
wall angles. Place outlets away from regions where accurate capillary forces
are needed.
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 imposes no contact angle.
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 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.
faceDivergence, nodalDivergence, celeste, paraboloid2019 and
rlsg use static angles. paraboloid2019 requires planar walls in 2-D.
RLSG requires planar walls; use rlsg_seed_type: plic for 3-D wall contact.
For RLSG, keep contact lines away from wall corners and prescribe an angle
strictly between 0 and 180 degrees at every wall the interface meets.
RLSG Curvature
RLSG computes curvature on an auxiliary Cartesian grid and requires a fixed,
convex flow mesh in Cartesian coordinates. rlsg_seed_type selects plic
(default) for 2-D or 3-D, or volumeFit for a curved fit in 2-D. Both support
interior interfaces and wall contact; see Wall Contact Angle for wall
requirements. Periodic and outlet crossings require plic.
Load rlsg before the control-file block and select:
vof_curvature_type: rlsg
rlsg_seed_type: plic
gradStencil: standard
use_cellStencil: 1
rlsg_grid_mode: automatic
gradStencil: full may replace standard with use_cellStencil: 1.
Curvature reconstruction ignores fractions within 1e-6 of a pure phase,
leaving transported fractions unchanged.
For periodic crossings, use one translational pair per periodic direction.
For outlet crossings, use one planar fixedPressureOutlet or two parallel
outlets with opposite outward normals. Place them beyond the region where
accurate capillary forces are needed. Keep the interface away from prescribed
inlets and reservoir boundaries with backflow.
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.
Input |
Default |
Meaning |
|---|---|---|
|
|
Pseudo-time CFL in |
|
|
Dimensionless reconstruction tolerance, greater than zero |
|
|
Maximum reconstruction iterations, at least one |
Check reconstruction-tolerance sensitivity separately from grid spacing.
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.
VOF-to-Particle Transfer
Convert detached material components to Lagrangian parcels on a fixed,
nonperiodic 3-D mesh with gravity off and timeIntegrator: BDF.
For this example, define LH2 and GH2 in materialModels, with
species H2 in GH2. Provide hydrogenDrops.pmdl containing bin
lh2Drop, with density and caloric properties matching LH2.
loadModule: lagrangianParticle
loadModule: cmim_avof
loadModule: cmim_avof_lagrangianParticle
{
particle_model: hydrogenDrops
vofToLagrangianNativeCommit: on
vofToLagrangian: <
lh2Drop=transfer(
donorMaterial=LH2,
coreVof=0.5,supportVof=1.0e-3,
maxEquivalentDiameter=6.0e-5,
maxAspectRatio=1.5,
minRetainedInterfaceDistance=1.0e-5,
persistenceSteps=2,boundaryContact=reject,
particleBin=lh2Drop,carrierMaterial=GH2,
receiverMaterial=GH2,receiverSpecies=H2)
>
}
Lengths are in metres. Use a distinct particle bin for each donor material.
Cells above coreVof seed components; face-connected cells above
supportVof join them. Size, shape, separation, boundary contact and
persistence determine eligibility. vofToLagrangianDistancePasses defaults
to 64 (range 1–1024).
Carrier Replacement
Use vofToLagrangianBackground: none (default) when carrier material is
present in the cells sampled by particles. Select carrier to fill the
converted volume with carrier at the cell pressure, temperature and velocity.
Use a single-species carrier with constant transport coefficients when
converting pure-liquid cells. Include the added carrier mass, momentum and
energy in inventory balances.
Timing
A selected component becomes one parcel at the end of the next converged fluid step. The parcel starts moving on the following step. Particle feedback is applied one fluid step after the particle advances; include pending feedback in inventory balances. Retain the MPI rank count when restarting.
Adaptive Mesh Refinement
Load amr with CMIM and configure adaptation timing.
To mark a material interface, select adaptSensor: CMIMVOFerror and exactly
one of these selectors:
Input example |
Meaning |
|---|---|
|
Volume-fraction jump of one material |
|
Maximum jump over the selected materials |
|
Minimum of the two jumps; both materials must change across the face |
Choose distinct names from materialModels (up to 64 materials).
cmimAdaptVOFJumpFloor suppresses jumps at or below an absolute floor
(default 0). cmimAdaptInterfaceEdgeLength suppresses this sensor when
the selected AMR cell size is at or below that length in metres (default 0,
disabled). Both controls must be finite and nonnegative.
Runtime refinement uses cmimAMRRuntimeMode: basic by default. Set
adaptInterpolationOrder: 1 for first-order cell transfer.
Set cmimAMRFluxRecovery: resetHistory to reset face-flux history on the
first step after remeshing; the default is off. Use a fixed mesh with
no-slip, slip or symmetry boundaries, timeIntegrator: BDF,
pressureBasedMethod: SIMPLEC, inviscidFlux: FOU, vofInviscidFlux: FOU
and momentumInterpolationOptions: <form=new,conservativePressure>.
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.
cmimTransport also writes output/cmimBoundaryFlux.dat with species
mass rates in kg/s, convected enthalpy and wall heat rates in W. Positive
mass flux is outward; each row describes transfer over the following timestep.
With species diffusion active, output/cmimDiffusion.dat records maximum
diffusion coefficients and fluxes at print_freq.
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³.
For RLSG with plic, add plicFallback to plot_output to inspect
cells whose normal fit used a fallback plane. Cell flags are one for fallback
and zero otherwise; plotted values are nodal averages.
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.
Output uses the normal plot frequency. In 2-D, files use
output/<case>_SURF.rlsg/ and the auxiliary mesh lies at z=0. Extract with:
extract -vtk -bc rlsg case 10 rlsgLevelSet rlsgLevelSetValid \
rlsgKappa rlsgKappaValid
Open case_vtk.10/rlsg_Surf.vtu. In 3-D, files use output/ with a
separate model name, <case>_rlsg. Extract the volume mesh with:
extract -vtk case_rlsg 10 rlsgLevelSet rlsgLevelSetValid \
rlsgKappa rlsgKappaValid
Open case_rlsg_vtk.10/Volume.vtu. In either dimension, threshold the
corresponding validity field to one with All Scalars enabled; invalid
entries contain zero. Contour rlsgLevelSet at zero.
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.