Physics Constraints Reference

Auto-generated from PHYSICS_DOCS in case_validator.py and AST-extracted validation rules. Do not edit by hand.

This document catalogs the physics constraints enforced by MFC's case parameter validator. Constraints are organized by physical category with mathematical justifications.

For parameter syntax and allowed values, see Case Files and the Case Parameters reference. For feature compatibility and working examples, see Case Creator Guide.

Thermodynamic Constraints

Stiffened EOS Positivity

\[\Gamma > 0, \quad \Pi_\infty \geq 0, \quad c_v \geq 0\]

The equation-of-state parameters must satisfy basic positivity requirements for thermodynamic stability.

Stage: common, pre_process, simulation, post_process | Severity: error

Enforced checks:

fluid_pp(i)%gamma must be positive
fluid_pp(i)%pi_inf must be non-negative
fluid_pp(i)%cv must be positive
model_eqns = 1 does not support fluid_pp(i)%gamma
model_eqns = 1 does not support fluid_pp(i)%pi_inf

References: Wilfong et al. [54]

EOS Parameter Sanity (Transformed Gamma)

\[\Gamma = \frac{1}{\gamma - 1}\]

MFC uses the transformed stiffened gas parameter. A common mistake is entering the physical gamma (e.g., 1.4 for air) instead of the transformed value 1/(gamma-1) = 2.5.

Stage: common, pre_process, simulation, post_process | Severity: warning

Enforced checks:

\(\triangle\) fluid_pp(i)%gamma implies physical gamma (unusually high). MFC uses the transformed parameter Gamma = 1/(gamma-1)
\(\triangle\) fluid_pp(i)%gamma implies physical gamma (very close to 1). Did you enter the physical gamma instead of 1/(gamma-1)?

References: Wilfong et al. [54], Allaire et al. [1]

Patch Initial Condition Constraints

\[p > 0, \quad \alpha_i \rho_i \geq 0, \quad 0 \leq \alpha_i \leq 1\]

All initial patch pressures must be strictly positive. Partial densities must be non-negative. Volume fractions must be in [0,1].

Stage: pre_process | Severity: error

Enforced checks:

patch_icpp(i)%pres must be positive
patch_icpp(i)%alpha(j) must be non-negative
patch_icpp(i)%alpha(j) must be <= 1
patch_icpp(i)%alpha_rho(j) must be non-negative
patch_icpp(i)%length_x must be positive
patch_icpp(i)%length_y must be positive
patch_icpp(i)%length_z must be positive
patch_icpp(i)%radius must be positive
patch_icpp(i)%r0 must be positive

Mixture Constraints

Volume Fraction Sum

\[\sum_{i=1}^{N_f} \alpha_i = 1\]

For multi-component models, volume fractions must satisfy the mixture constraint.

Stage: pre_process | Severity: warning

Enforced checks:

\(\triangle\) patch_icpp(i): volume fractions sum to alpha_sum, expected 1.0

Exceptions (constraint does not apply):

Single-fluid Euler-Euler bubble models (alpha represents void fraction)
Lagrangian bubble models (Lagrangian phase not tracked on Euler grid)
IBM cases (alpha acts as level-set indicator)
Alter patches and hard-coded IC patches (values computed at runtime)
Analytical expressions (cannot validate statically)

Alpha-Rho Consistency

\[\alpha_j = 0 \Rightarrow \alpha_j \rho_j = 0, \quad \alpha_j > 0 \Rightarrow \alpha_j \rho_j > 0\]

Warns about physically inconsistent combinations: density assigned to an absent phase, or a present phase with zero density.

Stage: pre_process | Severity: warning

Enforced checks:

\(\triangle\) patch_icpp(i): alpha(j) = 0 but alpha_rho(j) = alpha_rho (density in absent phase)
\(\triangle\) patch_icpp(i): alpha(j) = alpha but alpha_rho(j) = 0 (present phase has zero density)

Domain and Geometry

Domain Bounds

\[x_{\mathrm{end}} > x_{\mathrm{beg}}, \quad y_{\mathrm{end}} > y_{\mathrm{beg}}, \quad z_{\mathrm{end}} > z_{\mathrm{beg}}\]

Each active spatial dimension must have positive extent.

Stage: common, pre_process, simulation, post_process | Severity: error

Enforced checks:

x_domain%end (x_end) must be greater than x_domain%beg (x_beg)
y_domain%end (y_end) must be greater than y_domain%beg (y_beg)
z_domain%end (z_end) must be greater than z_domain%beg (z_beg)

Dimensionality

\[m > 0, \quad n \geq 0, \quad p \geq 0\]

The x-direction must have cells. Cannot have z without y. Cylindrical coordinates require odd p.

Stage: common, pre_process, simulation, post_process | Severity: error

Enforced checks:

m must be set
m must be positive
n must be non-negative
p must be non-negative
p must be odd for cylindrical coordinates
p must be 0 if n = 0

Patch Within Domain

For patches with centroid + length geometry, the bounding box must not be entirely outside the computational domain. Skipped when grid stretching is active.

Stage: pre_process | Severity: error

Enforced checks:

patch_icpp(i): x-extent [patch_x_lo, patch_x_hi] is entirely outside domain [x_beg, x_end]
patch_icpp(i): y-extent [patch_y_lo, patch_y_hi] is entirely outside domain [y_beg, y_end]
patch_icpp(i): z-extent [patch_z_lo, patch_z_hi] is entirely outside domain [z_beg, z_end]

Velocity and Dimensional Consistency

Velocity Components in Inactive Dimensions

\[n = 0 \Rightarrow v_2 = 0, \quad p = 0 \Rightarrow v_3 = 0\]

Setting velocity components in dimensions that do not exist is almost certainly a mistake.

Stage: pre_process | Severity: error

Enforced checks:

patch_icpp(i)%vel(2) is nonzero but n = 0 (1D simulation)
patch_icpp(i)%vel(3) is nonzero but p = 0 (1D/2D simulation)

Exceptions (constraint does not apply):

MHD simulations (transverse velocity couples to magnetic field in 1D)

Model Equations

Model Equation Selection

Model 1: gamma-law single-fluid. Model 2: five-equation (Allaire). Model 3: six-equation (Saurel). Model 4: four-equation (single-component with bubbles).

Stage: common, pre_process, simulation, post_process | Severity: error

Enforced checks:

model_eqns must be 1, 2, 3, or 4
num_fluids must be positive
num_fluids is not supported for model_eqns = 1
5-equation model (model_eqns = 2) requires num_fluids to be set
6-equation model (model_eqns = 3) requires num_fluids to be set
4-equation model (model_eqns = 4) requires num_fluids to be set
model_eqns = 1 does not support mpp_lim
num_fluids = 1 does not support mpp_lim
6-equation model (model_eqns = 3) does not support cylindrical coordinates (cyl_coord = T and p != 0)

References: Wilfong et al. [54], Allaire et al. [1], Saurel et al. [41]

Boundary Conditions

Boundary Condition Compatibility

Periodicity must match on both ends. Valid BC values range from -1 to -17. Cylindrical coordinates have specific BC requirements at the axis.

Stage: common, pre_process, simulation, post_process | Severity: error

Enforced checks:

Boundary condition -13 (BC_NULL) is not supported
bc_key is not supported for var = 0
var != 0 but bc_key is not set
bc_dir%beg and bc_dir%end must be both periodic (= -1) or both non-periodic
bc_key must be between -1 and -17
bc_key must not be -14 (BC_AXIS) for non-cylindrical coordinates
n must be positive (2D or 3D) for cylindrical coordinates
bc_y%beg must be -2 (BC_REFLECTIVE) for 2D cylindrical coordinates (p = 0)
bc_y%beg must be -14 (BC_AXIS) for 3D cylindrical coordinates (p > 0)
bc_y%end must be between -1 and -17
bc_y%end must not be -14 (BC_AXIS)
bc_z%beg must be -1 (periodic) or -2 (reflective) for 3D cylindrical coordinates
bc_z%end must be -1 (periodic) or -2 (reflective) for 3D cylindrical coordinates

Bubble Physics

Euler-Euler Bubble Model

Requires nb >= 1, positive reference quantities. Polydisperse requires odd nb > 1 and poly_sigma > 0. QBMM requires nnode = 4.

Stage: common, pre_process, simulation, post_process | Severity: error

Enforced checks:

The Ensemble-Averaged Bubble Model requires nb >= 1
Polydisperse bubble dynamics requires nb > 1
nb must be odd for polydisperse bubbles
thermal must be <= 3
Bubble models untested with 6-equation model (model_eqns = 3)
Bubble models untested with pi-gamma model (model_eqns = 1)
rhoref must be set if using bubbles_euler with model_eqns = 4
rhoref (reference density) must be positive
pref must be set if using bubbles_euler with model_eqns = 4
pref (reference pressure) must be positive
4-equation model (model_eqns = 4) is single-component and requires num_fluids = 1
Bubble models untested in cylindrical coordinates
bub_pp%R0ref (reference bubble radius) must be positive
bub_pp%p0ref (reference pressure) must be positive
bub_pp%rho0ref (reference density) must be positive
bub_pp%T0ref (reference temperature) must be positive
bub_pp%mu_l (liquid viscosity) must be non-negative
bub_pp%mu_g (gas viscosity) must be non-negative
bub_pp%mu_v (vapor viscosity) must be non-negative
bub_pp%ss (surface tension) must be non-negative

References: Bryngelson et al. [8]

Bubble Simulation Constraints

Requires HLLC Riemann solver and arithmetic average. Five-equation model does not support Gilmore bubble_model.

Stage: simulation | Severity: error

Enforced checks:

Activate only one of the bubble subgrid models (bubbles_euler or bubbles_lagrange)
Bubble modeling requires HLLC Riemann solver (riemann_solver = 2)
Bubble modeling requires arithmetic average (avg_state = 2)
The 5-equation bubbly flow model does not support bubble_model = 1 (Gilmore)

Euler-Lagrange Bubble Model

2D/3D only. Requires polytropic = F and thermal = 3. Not compatible with model_eqns = 3.

Stage: simulation | Severity: error

Enforced checks:

bubbles_lagrange accepts 2D and 3D simulations only
file_per_process must be false for bubbles_lagrange
The 6-equation flow model does not support bubbles_lagrange
bubbles_lagrange requires polytropic = F
bubbles_lagrange requires thermal = 3
cluster_type >= 2 requires smooth_type = 1

Feature Compatibility

Magnetohydrodynamics (MHD)

Requires model_eqns = 2, num_fluids = 1, HLL or HLLD Riemann solver. No relativity with HLLD.

Stage: common, pre_process, simulation, post_process | Severity: error

Enforced checks:

MHD is only available for single-component flows (num_fluids = 1)
MHD is only available for the 5-equation model (model_eqns = 2)
relativity requires mhd to be enabled
Bx0 must not be set if MHD is not enabled
Bx0 must be set in 1D MHD simulations
Bx0 must not be set in 2D/3D MHD simulations

Surface Tension

Requires model_eqns 2 or 3, num_fluids = 2.

Stage: common, pre_process, simulation, post_process | Severity: error

Enforced checks:

sigma must be set if surface_tension is enabled
sigma must be greater than or equal to zero
sigma is set but surface_tension is not enabled
The surface tension model requires model_eqns = 2 or model_eqns = 3
The surface tension model requires num_fluids = 2

Hypoelasticity

Requires model_eqns = 2, HLL Riemann solver.

Stage: common, pre_process, simulation, post_process | Severity: error

Enforced checks:

hypoelasticity requires model_eqns = 2
hypoelasticity requires HLL Riemann solver (riemann_solver = 1)

Phase Change

Model 2: relax_model 5 or 6. Model 3: relax_model 1, 4, 5, or 6.

Stage: common, pre_process, simulation, post_process | Severity: error

Enforced checks:

phase change requires model_eqns==2 with relax_model in [5,6] or model_eqns==3 with relax_model in [1,4,5,6]
palpha_eps must be positive
palpha_eps must be less than 1
ptgalpha_eps must be positive
ptgalpha_eps must be less than 1

Alternative Sound Speed

Requires model_eqns = 2, num_fluids 2 or 3, HLLC solver. Incompatible with bubbles.

Stage: simulation | Severity: error

Enforced checks:

5-equation model (model_eqns = 2) is required for alt_soundspeed
alt_soundspeed is not compatible with bubbles_euler
alt_soundspeed requires avg_state = 2
alt_soundspeed requires HLLC Riemann solver (riemann_solver = 2)
alt_soundspeed requires num_fluids = 2 or 3

Iterative Generalized Riemann (IGR)

Requires model_eqns = 2. Incompatible with characteristic BCs, bubbles, MHD, and elastic models.

Stage: common, pre_process, simulation, post_process | Severity: error

Enforced checks:

igr_pres_lim requires igr to be enabled
igr_order must be 3 or 5
m must be at least igr_order - 1 (= igr_order - 1)
n must be at least igr_order - 1 (= igr_order - 1)
p must be at least igr_order - 1 (= igr_order - 1)

Numerical Schemes

WENO Reconstruction

weno_order must be 1, 3, 5, or 7. Grid must have enough cells. Only one of mapped_weno, wenoz, teno can be active.

Stage: common, pre_process, simulation, post_process | Severity: error

Enforced checks:

weno_order must be 1, 3, 5, or 7
m must be at least weno_order - 1 (= weno_order - 1)
For 2D simulation, n must be at least weno_order - 1 (= weno_order - 1)
For 3D simulation, p must be at least weno_order - 1 (= weno_order - 1)

MUSCL Reconstruction

muscl_order must be 1 or 2. Second order requires muscl_lim in {1,2,3,4,5}.

Stage: common, pre_process, simulation, post_process | Severity: error

Enforced checks:

int_comp (THINC interface compression) requires recon_type = 2 (MUSCL)
muscl_order must be 1 or 2
m must be at least muscl_order - 1 (= muscl_order - 1)
For 2D simulation, n must be at least muscl_order - 1 (= muscl_order - 1)
For 3D simulation, p must be at least muscl_order - 1 (= muscl_order - 1)

Time Stepping

time_stepper in {1,2,3}. Fixed dt must be positive. CFL-based modes require cfl_target in (0,1].

Stage: simulation, post_process | Severity: error

Enforced checks:

time_stepper must be 1, 2, or 3
dt must be positive
cfl_target must be in (0, 1]
t_stop must be positive
t_save must be positive
t_save must be <= t_stop
n_start must be non-negative
t_step_start must be non-negative
t_step_stop must be non-negative
t_step_stop must be > t_step_start
t_step_save must be positive
t_step_save must be <= (t_step_stop - t_step_start)
dt must be set when using fixed time stepping (t_step_start/t_step_stop)

Viscosity

\[\mathrm{Re}_1 > 0, \quad \mathrm{Re}_2 > 0\]

Reynolds numbers must be positive. Not supported with model_eqns = 1.

Stage: simulation | Severity: error

Enforced checks:

fluid_pp(i)%Re(j) must be positive
model_eqns = 1 does not support fluid_pp(i)%Re(j)
weno_order = 1 without weno_avg does not support fluid_pp(i)%Re(j)
Re(j) is specified, but viscous is not set to true
viscous is set to true, but fluid_pp(i)%Re(1) is not specified

Acoustic Sources

Dimension-specific support types. Pulse type in {1,2,3,4}. Non-planar sources require foc_length and aperture.

Stage: simulation | Severity: error

Enforced checks:

num_source must be specified for acoustic_source
num_source must be non-negative
acoustic(j)%support must be specified for acoustic_source
Only acoustic(j)%support = 1 is allowed for 1D simulations
acoustic(j)%loc(1) must be specified for support = 1
Only acoustic(j)%support = 2, 6, or 10 is allowed for 2D axisymmetric
Only acoustic(j)%support = 2, 5, 6, 9, or 10 is allowed for 2D
acoustic(j)%loc(1:2) must be specified for the given support
Only acoustic(j)%support = 3, 7, or 11 is allowed for 3D
Acoustic source is not supported in 3D cylindrical simulations
acoustic(j)%loc(1:2) must be specified for support = 3
acoustic(j)%loc(1:3) must be specified for the given support
acoustic(j)%mag must be specified
acoustic(j)%pulse must be specified
Only acoustic(j)%pulse = 1, 2, 3, or 4 is allowed
One and only one of acoustic(j)%frequency or wavelength must be specified for the given pulse
acoustic(j)%frequency must be positive
acoustic(j)%wavelength must be positive
One and only one of acoustic(j)%gauss_sigma_time or gauss_sigma_dist must be specified for pulse = 2
acoustic(j)%delay must be specified for pulse = 2 (Gaussian)
acoustic(j)%gauss_sigma_time must be positive
acoustic(j)%gauss_sigma_dist must be positive
acoustic(j)%bb_num_freq must be specified for pulse = 4
acoustic(j)%bb_bandwidth must be specified for pulse = 4
acoustic(j)%bb_lowest_freq must be specified for pulse = 4
acoustic(j)%npulse must be specified
acoustic(j)%npulse must be an integer for support >= 5 (non-planar)
acoustic(j)%dipole is not supported for npulse >= 5
acoustic(j)%dir must be specified for support < 5 (planar)
acoustic(j)%dir must be non-zero for support = 1
acoustic(j)%support >= 5 is not allowed for pulse = 3 (square wave)
acoustic(j)%length must be specified for the given support
acoustic(j)%length must be positive for the given support
acoustic(j)%height must be specified for support = 3
acoustic(j)%height must be positive for support = 3
acoustic(j)%foc_length must be specified for support >= 5 (non-planar)
acoustic(j)%foc_length must be positive for support >= 5
acoustic(j)%aperture must be specified for support >= 5 (non-planar)
acoustic(j)%aperture must be positive for support >= 5
acoustic(j)%num_elements must be specified for the given support (transducer array)
acoustic(j)%num_elements must be positive for the given support
acoustic(j)%element_on must be non-negative for the given support
acoustic(j)%element_on must be <= num_elements for the given support
acoustic(j)%element_spacing_angle must be specified for the given support (2D transducer)
acoustic(j)%element_spacing_angle must be non-negative for the given support
acoustic(j)%element_polygon_ratio must be specified for support = 11 (3D transducer)
acoustic(j)%element_polygon_ratio must be positive for support = 11

Post-Processing

Vorticity Output

omega_wrt requires at least 2D (n > 0). 3D components require p > 0. Requires fd_order.

Stage: post_process | Severity: error

Enforced checks:

omega_wrt requires n > 0 (at least 2D)
omega_wrt(1) and omega_wrt(2) require p > 0 (3D)
fd_order must be set for omega_wrt

FFT Output

Requires 3D with all periodic boundaries. Global dimensions must be even. Incompatible with cylindrical coordinates.

Stage: post_process | Severity: error

Enforced checks:

FFT WRT requires periodic BCs (all BCs should be -1)
FFT WRT only supported in 3D
FFT WRT incompatible with cylindrical coordinates
FFT WRT requires global dimensions divisible by 2

Page last updated: 2026-02-22