Remove shallow PHYSICS_DOCS entries, move to skip set instead

The 16 entries I added were just restating what the code checks without
real physics content (math, references, explanations). Move them to the
lint skip set so domain experts can add proper documentation later.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: sbryngelson

toolchain/mfc/case_validator.py

@@ -242,145 +242,6 @@
             "Global dimensions must be even. Incompatible with cylindrical coordinates."
         ),
     },
-    "check_adaptive_time_stepping": {
-        "title": "Adaptive Time Stepping",
-        "category": "Numerical Schemes",
-        "explanation": (
-            "Requires RK3 time stepper. Only compatible with polytropic or "
-            "Lagrangian bubble models. Incompatible with QBMM."
-        ),
-    },
-    "check_adv_n": {
-        "title": "Bubble Advection",
-        "category": "Bubble Physics",
-        "explanation": (
-            "Bubble advection (adv_n) requires single-fluid Euler bubble solver. "
-            "Incompatible with QBMM."
-        ),
-    },
-    "check_body_forces": {
-        "title": "Body Forces",
-        "category": "Feature Compatibility",
-        "explanation": (
-            "Body force parameters (k, w, p, g components) must be fully specified "
-            "for each active dimension."
-        ),
-    },
-    "check_continuum_damage": {
-        "title": "Continuum Damage Modeling",
-        "category": "Feature Compatibility",
-        "explanation": (
-            "Requires model_eqns = 2 and specification of tau_star, "
-            "cont_damage_s, and alpha_bar parameters."
-        ),
-    },
-    "check_grcbc": {
-        "title": "Generalized Relaxation CBC",
-        "category": "Boundary Conditions",
-        "explanation": (
-            "GRCBC requires specific BC values: -7 (inflow) or -8 (outflow). "
-            "Inflow requires velocity and pressure specification."
-        ),
-    },
-    "check_hyperelasticity": {
-        "title": "Hyperelasticity",
-        "category": "Feature Compatibility",
-        "explanation": (
-            "Pre-stress requires hyperelasticity. Not supported with "
-            "model_eqns = 1. Requires HLL Riemann solver."
-        ),
-    },
-    "check_ibm": {
-        "title": "Immersed Boundary Method",
-        "category": "Domain and Geometry",
-        "explanation": (
-            "Requires 2D or 3D (n > 0). Number of immersed boundaries "
-            "must be between 1 and 10."
-        ),
-    },
-    "check_igr_simulation": {
-        "title": "IGR Simulation Constraints",
-        "category": "Numerical Schemes",
-        "explanation": (
-            "Iterative ghost-cell remapping has numerous incompatibilities "
-            "including polytropic, bubbles, surface tension, MHD, and elasticity."
-        ),
-    },
-    "check_mhd_simulation": {
-        "title": "MHD Simulation Constraints",
-        "category": "Feature Compatibility",
-        "explanation": (
-            "MHD requires HLL or HLLD Riemann solver. HLLD unavailable for "
-            "relativistic MHD. Hyperbolic divergence cleaning not supported in 1D."
-        ),
-    },
-    "check_model_eqns_simulation": {
-        "title": "Six-Equation Model Constraints",
-        "category": "Model Equations",
-        "explanation": (
-            "The six-equation model (model_eqns = 3) requires arithmetic "
-            "averaging and specific wave speed calculation methods."
-        ),
-        "references": ["Saurel09"],
-    },
-    "check_muscl_simulation": {
-        "title": "MUSCL Simulation Constraints",
-        "category": "Numerical Schemes",
-        "explanation": (
-            "Second-order MUSCL reconstruction requires a flux limiter "
-            "selection (muscl_lim in 1-5)."
-        ),
-    },
-    "check_partial_density": {
-        "title": "Partial Density Output",
-        "category": "Post-Processing",
-        "explanation": (
-            "Multi-phase partial density output is incompatible with "
-            "model_eqns = 1 (single-fluid gamma-law)."
-        ),
-    },
-    "check_qbmm_and_polydisperse": {
-        "title": "QBMM and Polydisperse Bubbles",
-        "category": "Bubble Physics",
-        "explanation": (
-            "Both require Euler bubble solver. Polydisperse requires "
-            "poly_sigma > 0. QBMM requires nnode = 4."
-        ),
-        "references": ["Bryngelson21"],
-    },
-    "check_riemann_solver": {
-        "title": "Riemann Solver Selection",
-        "category": "Numerical Schemes",
-        "explanation": (
-            "Five solvers available with different model compatibility. "
-            "Six-equation model requires HLLC. Exact solver does not support "
-            "wave_speeds. Low-Mach correction 2 requires HLLC."
-        ),
-    },
-    "check_schlieren": {
-        "title": "Schlieren Visualization",
-        "category": "Post-Processing",
-        "explanation": (
-            "Requires finite difference order and at least 2D (n > 0). "
-            "Each schlieren_alpha coefficient must be positive."
-        ),
-    },
-    "check_volume_fraction": {
-        "title": "Volume Fraction Output",
-        "category": "Post-Processing",
-        "explanation": (
-            "Volume fraction output is incompatible with model_eqns = 1 "
-            "(single-fluid gamma-law). Requires multi-component model."
-        ),
-    },
-    "check_weno_simulation": {
-        "title": "WENO Simulation Constraints",
-        "category": "Numerical Schemes",
-        "explanation": (
-            "Five WENO variants with mutual exclusivity constraints. "
-            "weno_avg incompatible with model_eqns = 1."
-        ),
-    },
 }
 
 

toolchain/mfc/lint_docs.py

@@ -403,9 +403,11 @@ def check_physics_docs_coverage(repo_root: Path) -> list[str]:
     except ImportError:
         return []
 
-    # Methods that are purely structural/mechanical and don't need physics docs
+    # Methods without PHYSICS_DOCS entries. Add a PHYSICS_DOCS entry (with math,
+    # references, and explanation) to case_validator.py to remove from this set.
     skip = {
-        "check_parameter_types",     # type validation, not physics
+        # Structural/mechanical checks (no physics meaning)
+        "check_parameter_types",     # type validation
         "check_output_format",       # output format selection
         "check_restart",             # restart file logistics
         "check_parallel_io_pre_process",  # parallel I/O settings
@@ -425,6 +427,24 @@ def check_physics_docs_coverage(repo_root: Path) -> list[str]:
         "check_perturb_density",     # parameter pairing validation
         "check_qm",                  # output dimension requirements
         "check_chemistry",           # runtime Cantera validation only
+        # Awaiting proper physics documentation (math, references, explanation)
+        "check_adaptive_time_stepping",
+        "check_adv_n",
+        "check_body_forces",
+        "check_continuum_damage",
+        "check_grcbc",
+        "check_hyperelasticity",
+        "check_ibm",
+        "check_igr_simulation",
+        "check_mhd_simulation",
+        "check_model_eqns_simulation",
+        "check_muscl_simulation",
+        "check_partial_density",
+        "check_qbmm_and_polydisperse",
+        "check_riemann_solver",
+        "check_schlieren",
+        "check_volume_fraction",
+        "check_weno_simulation",
     }
 
     validator_path = repo_root / "toolchain" / "mfc" / "case_validator.py"