CMIM Module

The cmim_avof module models compressible mixtures of materials with material-local species compositions.

Setup

Load cmim_avof and the EOS module required by the selected material models. Define each material in materialModels with chemistry_model, eos_type, transport_model, and thermodynamic_model. Each chemistry model’s .mdl file defines that material’s species. Set the global transport_model: module to use the material transport models.

Curvature and Surface Tension

The cmim_avof module computes curvature for one oriented material pair in an exactly two-material case. Specify the material names from materialModels in sigma_ij:

sigma_ij: <matA__matB=0.072 N/m>
momentumInterpolationOptions: <form=new,conservativePressure>
vof_curvature_type: faceDivergence
vof_curvature_smoothing_passes: 2
vof_contact_angle_model: static
vof_contact_angle_deg: 30.0

The first material defines color one and the side through which the contact angle is measured. Reversing the pair requires the supplementary angle. The momentum-interpolation form must be new or Denner when surface tension is active. A nonzero global sigma is rejected because it does not identify the material pair.

Curvature Selection

Curvature providers
`vof_curvature_type`	Method
`direct` (default)	Existing gradient interpolation and face-normal divergence.
`faceDivergence`	Optional face-based color smoothing, then face-normal divergence.
`nodalDivergence`	Optional nodal color smoothing, then curvature from nodal normals.
`celeste`	Taylor-fit derivatives and curvature averaging; requires `gradStencil: full`.
`paraboloid2019`	Geometric reconstruction and integrated paraboloid fit. Requires `gradStencil: full`, or `standard` with `use_cellStencil: 1`.
`analytical`	Prescribed constant `kappaAnalytical` (default zero), in inverse metres.

The two differential methods accept vof_curvature_smoothing_passes, a nonnegative integer with default 2. Zero passes preserves the input color. Smoothing affects a separate field used to calculate curvature; it does not change the transported volume fractions. These are CMIM discretizations, not options that reproduce every internal choice of a commercial solver.

Their scope is fixed Cartesian-coordinate 2-D and 3-D meshes with symmetry, no-slip or fixed-pressure outlet boundaries. The outlet treatment extrapolates the curvature geometry from adjacent cells; checks cover outlets separated from the interface by pure fluid. Interface passage through an outlet, mixed-phase backflow and wetting at an outlet corner are not qualified. The configuration checks reject other boundary types, moving meshes, axisymmetry and dynamic angles. Curvature accuracy and coupled capillary stability remain under qualification; method selection does not establish mesh convergence.

Wall Contact Angle

vof_contact_angle_model: none is the default. With static, use vof_contact_angle_deg (default 90 degrees), or a boundary override:

boundary_conditions: <wall=noslip(adiabatic,contactAngle=30 deg)>

Each curvature method enforces the angle within its own reconstruction. The differential methods correct the boundary normal used in the divergence. They also accept an optional correction of the adjacent cell gradients:

vof_curvature_type: nodalDivergence
vof_contact_angle_model: static
vof_curvature_wall_treatment: cellGradient

cellGradient applies the angle before gradients are interpolated to vertices or faces. It works with nodalDivergence and faceDivergence. The default boundary retains boundary-only enforcement. Gradient magnitudes and transported fractions remain unchanged.

For cells touching several walls, the correction uses all prescribed angle conditions together. If they cannot define a compatible unit normal, or if the gradient provides no needed tangential direction, the cell keeps its original gradient while each boundary face retains its angle condition. This numerical fallback does not model contact-line pinning at corners.

The geometric method supports static wall contact only in fixed 2-D geometry. The existing direct method also provides the dynamic model; selecting that model does not enable dynamic contact in the other methods.

Verification

The companion stream_cases case 111_differential_curvature compares the production methods against independent geometric fixtures. Case 103_capillary_startup accepts either new selection through --curvature and the smoothing count through --smoothing-passes. Use --wall-treatment cellGradient for the corrected-wall comparison and --grid to select the same mesh in both runs. Its computed-curvature profile checks nonlinear convergence and reports curvature error and spurious velocity separately.

Volumetric Cavitation

The cmim_avof module supports zwart, merkle, and schnerrSauer pressure-driven cavitation models. Select one liquid/vapor species pair in phaseChangeModels. Each species must belong to its named material.

phaseChangeModels: <hydrogen=volumetricTransfer(
  liquidMaterial=Liquid,vaporMaterial=Ullage,
  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
  )
)>

Define Liquid and Ullage in materialModels with compatible liquid and vapor EOS and enthalpy references. These example coefficients require qualification for the fluid and operating conditions. Load cmim_avof and the required EOS module; no separate cavitation module is needed.

Use flowCompressibility: compressible, timeIntegrator: BDF, and form=totalEnthalpy in energyEquationOptions. The two material names may be identical for conversion between distinct phase-labelled species in one material. That material must use diffusion_model=none. The liquid and vapor molecular masses must agree. One channel and one constituent map are supported. Multispecies materials require laminar flow; CMIM’s SST profile currently permits only one species per material.

Model Parameters

All three models require saturation=antoine(...), vaporizationCoefficient, and condensationCoefficient. Coefficients are dimensionless, nonnegative, and cannot both be zero. No model coefficients are supplied by default.

Additional required parameters
Model	Parameters	Units and limits
`zwart`	`bubbleRadius`, `nucleationVolumeFraction`	Positive radius in metres; fraction strictly between zero and one.
`merkle`	`referenceLength`, `referenceVelocity`, `referenceDensity`	Positive values in m, m/s, and kg/m³. Unit syntax for density is `kg/m/m/m`.
`schnerrSauer`	`bubbleNumberDensity`, `nucleationRadius`	Positive bubble count per m³ of liquid, entered as a real number; positive radius in metres.

For Merkle, the pressure/time scale is \(2/(\rho_{ref}L_{ref}U_{ref})\). To reproduce the cavitation_nist coefficient convention, use vaporizationCoefficient=1/tauVap and condensationCoefficient=1/tauCond with the same reference quantities. Enter the evaluated numbers in the control file.

Antoine requires A, B, C, pressureUnit, temperatureUnit, Tmin, and Tmax. Pressure units are Pa, kPa, MPa, or bar; coefficient temperatures use kelvin. The entire cell-temperature range must lie within the saturation correlation and both phase EOS ranges, including where a phase is initially absent.

Behavior and Output

Positive transfer evaporates liquid; negative transfer condenses vapor through the same mapping. Only the mapped species exchange mass. The EOS and total-enthalpy solve determine the temperature change. Accepted phase volumes supply the rate support for each timestep; reduce the timestep if the source would exhaust a constituent. Rates are not clipped.

Zwart and Merkle can create either missing phase. Schnerr–Sauer nucleates vapor in pure liquid, but its rate is zero in pure vapor because no liquid bubble population remains. Nuclei parameters do not add transported mass.

Other constituents, including helium, keep their own EOS and species transport. These models use total mechanical pressure for bubble growth and collapse. They do not model helium dissolution, vapor partial-pressure equilibrium, or heat-limited cryogenic evaporation.

Add cmimPhaseChange to diagnostics to write output/cmimPhaseChange.dat. The ledger reports signed transfer, evaporation, condensation, and conservative material/species sources. Intramaterial transfer has zero material mass source and nonzero mapped species sources. The intrinsic-volume diagnostic uses the two phase EOS densities.

The legacy names donorMaterial, receiverMaterial, donorSpecies, and receiverSpecies remain accepted aliases. Do not specify an alias and its liquid/vapor equivalent together.

Initial Conditions

Use initialCondition or initialConditionRegions with pressure, temperature, velocity, and vof=[material=fraction,...]. Material names must match materialModels. Volume fractions must sum to one; omitted materials have zero volume fraction.

For each active multicomponent material, supply its species mass fractions in materialComposition, for example materialComposition=[Air=[N2=0.77,O2=0.23]]. Fractions within each material must sum to one; omitted species are zero. A single-species material’s composition is inferred.

Closed-Surface Regions

With cmim_avof, initialConditionRegions accepts closed surface files. Use inSurface for the volume enclosed by a SolidMesh .surf boundary:

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. Concave volumes and separate closed components are supported. Polygonal .surf faces must be planar.

For a curved reconstruction, use Loci’s computegeom utility. It runs on one MPI process and writes liquid.geom from triangular and quadrilateral VOG boundary faces:

computegeom liquid

Select the resulting region with:

regions=[inGeometry(file="liquid.geom",subdivisions=4,composition=liquid)]

The reconstruction approximates the VOG boundary. subdivisions controls its surface tessellation, ranges from 1 through 64, and defaults to 4. Increase it to check convergence with respect to surface resolution. Neither region form accepts VOG files directly.

Cell-Average Volume Fractions

For cell-average volume fractions, use initialConditionRegions with the controls below. This example assumes single-species Gas and Liquid materials defined in materialModels:

CMIM spherical region with cell-average volume fractions

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)]
>

Geometric Initialization Options
Option	Default	Meaning
`cmimVOFInitialization`	`cellCenter`	`cellCenter` samples cell centers; `geometric` averages regional material volume fractions over each cell.
`cmimGeometricVOFRefinement`	`4`	Maximum subdivision depth, from 0 through 8. Controls overlapping regions in 2-D and approximate intersections in 3-D.
`cmimGeometricVOFTolerance`	`1e-3`	Maximum absolute error in each 3-D cell’s volume fraction, from `1e-8` through `0.1`. Excludes surface-tessellation error.

For 2-D overlaps, increase refinement and compare fractions. A 3-D start stops if it cannot meet the tolerance: increase refinement, or relax the tolerance if the diagnostic reports a work limit. Small volume fractions may require a smaller tolerance.

Geometric initialization requires two materials, a fixed mesh in Cartesian coordinates, and convex computational cells:

With grid_file_info: <twoDimensions>, cells must be extruded in z and regions must be constant through the thickness. Use vertical cylinders, thickness-spanning boxes, planes with zero z normal, or extruded inSurface and inGeometry boundaries.
In 3-D, cell faces must be planar. Use inSphere, inBox, leftPlane, inSurface, or inGeometry. Cylinders and cones are unsupported in 3-D geometric mode.

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.

Output and Diagnostics

Use the shared output controls to select fields and output frequency. CMIM provides the following additional fields and diagnostics.

Material and Species Output

For the cmim_avof module, the default vof family writes vof_<material> and the default mixture family writes Y_<species>. The latter is a mixture-wide species mass fraction:

\[Y_s = \frac{\sum_{m:\,s\in\mathcal S_m} \alpha_m\rho_m Y_{ms}} {\sum_m \alpha_m\rho_m}.\]

If more than one material model contains the exact same species name, that name identifies one chemical species for output and the mass contributions are added to the same Y_<species> field. Different species must use different names. Thus Y_He answers how much helium is present in the complete mixture at a location; it is not the composition of a hypothetical helium material at that location. The files contain the standard cell-to-node interpolation, so a node on a material interface can have an intermediate value even when an adjacent cell contains none of that species.

CMIM evaluates these mixture-species fields only when the mixture output family is active. It does not maintain a flattened global y field or run Stream’s base species-equation solver. The authoritative conservative state is material mass per mixture volume q_m and packed material-species mass per mixture volume z_ms. CMIM derives vof and material-local composition from that state on active material support.

The remaining CMIM field families are optional and are selected by family name:

Optional CMIM field families
`plot_output` selector	Output names	Meaning
`materialMassFraction`	`materialMassFraction_<material>`	Material mass divided by total mixture mass, \(\alpha_m\rho_m/\rho\).
`materialPartialDensity`	`materialPartialDensity_<material>`	Material mass per mixture volume, \(\alpha_m\rho_m\).
`materialDensity`	`materialDensity_<material>`	Intrinsic material density for active material; exact absence is zero.
`materialComposition`	`materialComposition_<material>::<species>`	Species mass fraction within an active material. Exact absence is zero.
`materialSpeciesRhoD`	`materialSpeciesRhoD_<material>::<species>`	Material-local \(\rho_m D_{ms}\) transport coefficient.

For example, the raw conditional composition is requested with:

plot_output: materialComposition

The material-mass-fraction output is computed directly from material mass, not by summing the material’s species outputs. Thus a composition-sum residual does not alter the reported material abundance. Plot selection does not affect restart data: CMIM writes q_m and z_ms to restart files whether or not these families are plotted, and does not write vof, y_ms, or a flattened global y as authoritative restart state.

Console and Detailed Diagnostics

CMIM adds two concise nonlinear-iteration records to the normal log. RV prints one global L1 q-equation residual per material followed by, for each material, the largest global L1 z-equation residual among its species. All values are in kg/s. RCMIM prints qEq, zEq, closure, and state ratios normalized by their active acceptance limits, plus ok. A ratio at or below one passes its group; ok=1 means all CMIM convergence gates pass. These records replace the former CMIM RS, RSR, and RQZ records.

Detailed diagnostic files are opt-in through diagnostics:

CMIM diagnostic selectors
Selector	File	Purpose
`cmimInvariants`	`cmimInvariants.dat`	Material support, alpha admissibility, and active-composition updates.
`cmimPressure`	`cmimPressure.dat`	Pressure-row, fixed-q volume, and accepted-continuity checks.
`cmimTransport`	`cmimTransportResidual.dat`	Material q and direct-z transport residuals.
`cmimCapillary`	`capillaryDiagnostics.dat`	Curvature and capillary-CFL maxima when surface tension is active.

cmimAVOF remains a compatibility umbrella for all applicable groups. Selector-free runs do not schedule these detailed reductions or create their files. The invariant, pressure, and transport ledgers write one row per nonlinear iteration; the capillary ledger follows the selected print cadence. Fresh runs replace each requested file on its first write. On restart, rows before each file’s first resumed key are retained and its recomputed tail is replaced; a missing header is restored.

Nonlinear Convergence Status

When the cmim_avof module is loaded, two optional status fields distinguish a time step that satisfied its active nonlinear convergence criteria from one that stopped because it reached maxIterationsPerTimeStep:

nonlinearConverged is 1 when all active convergence criteria represented by the standard momentum, pressure, energy, turbulence, and species convergence facts have passed, and is 0 otherwise. CMIM adds its material-volume and material-local species criteria to the same result.
nonlinearIterationLimitReached is 1 on the configured final nonlinear iteration and is 0 otherwise.

Both fields can be 1 when convergence is reached on the last permitted iteration. With the default plot_output_iteration: off setting, the fields are written from the actual terminal nonlinear iteration, whether the loop stopped early through convergence or at its iteration cap. With plot_output_iteration: on, they report the state of each written nonlinear iteration.

The pair is read as follows:

Nonlinear termination status
`nonlinearConverged`	`nonlinearIterationLimitReached`	Meaning
1	0	Converged before the configured limit.
1	1	Converged on the last permitted iteration.
0	1	Reached the limit without satisfying the convergence criteria.
0	0	Still iterating; visible only when iteration output is enabled.

These fields are registered by cmim_avof and are available only when that module is loaded. The current convergence criteria are global reductions, so nonlinearConverged is spatially uniform even though it is stored as a cell field for convenient plotting. Together, the two fields describe the nonlinear-iteration state and, on terminal output, distinguish convergence from termination at the iteration cap. They are not maps of local convergence quality. Use the residual, turnover-time, and residual-ratio fields to localize troublesome cells. This is nonlinear outer-iteration status for the standard residual-driven SIMPLE-family path and CMIM, not linear-solver convergence. These status outputs are observational only and do not change whether an unconverged time step is accepted. Request them through the ordinary output list:

Nonlinear Termination Status Output

plot_output: nonlinearConverged, nonlinearIterationLimitReached