Add physics constraint validation and auto-generated docs

.github/workflows/lint-toolchain.yml

@@ -42,5 +42,20 @@ jobs:
 
     - name: Validate example cases
       run: |
-        ./mfc.sh validate examples/1D_sodshocktube/case.py
-        ./mfc.sh validate examples/2D_shockbubble/case.py
+        failed=0
+        passed=0
+        for case in examples/*/case.py; do
+          output=$(./mfc.sh validate "$case" 2>&1)
+          if [ $? -eq 0 ]; then
+            passed=$((passed + 1))
+          else
+            echo "FAIL: $case"
+            echo "$output"
+            failed=$((failed + 1))
+          fi
+        done
+        echo ""
+        echo "Results: $passed passed, $failed failed"
+        if [ "$failed" -ne 0 ]; then
+          exit 1
+        fi

.gitignore

@@ -44,6 +44,7 @@ docs/*/result*
 docs/documentation/*-example.png
 docs/documentation/examples.md
 docs/documentation/case_constraints.md
+docs/documentation/physics_constraints.md
 
 examples/*batch/*/
 examples/**/D/*

CMakeLists.txt

@@ -660,16 +660,19 @@ if (MFC_DOCUMENTATION)
         VERBATIM
     )
 
-    # Generate case_constraints.md from case_validator.py and examples/
+    # Generate case_constraints.md and physics_constraints.md together.
+    # Both are produced by gen_constraints.sh, so a single command avoids races.
     add_custom_command(
         OUTPUT  "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/case_constraints.md"
+                "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/physics_constraints.md"
         DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/gen_case_constraints_docs.py"
+                "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/gen_physics_docs.py"
                 "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/case_validator.py"
                 "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/params/definitions.py"
                 "${examples_DOCs}"
         COMMAND "bash" "${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_constraints.sh"
                        "${CMAKE_CURRENT_SOURCE_DIR}"
-        COMMENT "Generating case_constraints.md"
+        COMMENT "Generating case_constraints.md and physics_constraints.md"
         VERBATIM
     )
 
@@ -732,11 +735,13 @@ if (MFC_DOCUMENTATION)
 
         set(opt_example_dependency "")
         set(opt_constraints_dependency "")
+        set(opt_physics_dependency "")
         set(opt_cli_reference_dependency "")
         set(opt_parameters_dependency "")
         if (${target} STREQUAL documentation)
             set(opt_example_dependency "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/examples.md")
             set(opt_constraints_dependency "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/case_constraints.md")
+            set(opt_physics_dependency "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/physics_constraints.md")
             set(opt_cli_reference_dependency "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/cli-reference.md")
             set(opt_parameters_dependency "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/parameters.md")
         endif()
@@ -749,6 +754,7 @@ if (MFC_DOCUMENTATION)
             DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/${target}-Doxyfile"
                     "${opt_example_dependency}"
                     "${opt_constraints_dependency}"
+                    "${opt_physics_dependency}"
                     "${opt_cli_reference_dependency}"
                     "${opt_parameters_dependency}"
                     "${${target}_SRCs}" "${${target}_DOCs}"

docs/custom.css

@@ -3,6 +3,22 @@
  * Overrides for doxygen-awesome theme
  */
 
+/* Seamless split <code> tags for Fortran % struct accessors.
+ * Doxygen consumes %<word> even inside code spans, so we split around %
+ * into adjacent <code> elements and remove internal borders/padding. */
+code.f90l {
+    border-right: 0;
+    border-top-right-radius: 0;
+    border-bottom-right-radius: 0;
+    padding-right: 0;
+}
+code.f90r {
+    border-left: 0;
+    border-top-left-radius: 0;
+    border-bottom-left-radius: 0;
+    padding-left: 0;
+}
+
 /* Fix inline code visibility in colored admonition blocks (warning, attention, important, note, etc.) */
 
 /* Warning/Attention/Important blocks (red/pink background) */

docs/documentation/case.md

@@ -65,7 +65,7 @@ To run such a case, use the following format:
 For example, to run the `scaling` case in "weak-scaling" mode:
 
 ```shell
-./mfc.sh run examples/scaling/case.py -t pre_process -j 8 -- --scaling weak
+./mfc.sh run examples/scaling/benchmark.py -t pre_process -j 8 -- --scaling weak
 ```
 
 ## Parameters

docs/documentation/contributing.md

@@ -274,6 +274,8 @@ def check_my_feature(self):
         self.errors.append("my_param requires other_param to be set")
 ```
 
+If your check enforces a physics constraint, also add a `PHYSICS_DOCS` entry (see [How to Document Physics Constraints](#how-to-document-physics-constraints) below).
+
 **Step 5: Declare in Fortran** (`src/<target>/m_global_parameters.fpp`)
 
 Add the variable declaration in the appropriate target's global parameters module. Choose the target(s) where the parameter is used:
@@ -659,6 +661,41 @@ Checklist:
 
 See @ref troubleshooting for debugging workflows, profiling tools, GPU diagnostic environment variables, common build/runtime errors, and fixes.
 
+### How to Document Physics Constraints {#how-to-document-physics-constraints}
+
+When adding a new `check_` method to `case_validator.py`, document its physics by adding an entry to the `PHYSICS_DOCS` dict at the top of the file:
+
+```python
+PHYSICS_DOCS = {
+    ...
+    "check_my_feature": {
+        "title": "My Feature Constraint",          # Required: human-readable title
+        "category": "Thermodynamic Constraints",    # Required: groups the constraint in docs
+        "explanation": "Why this constraint exists.", # Required: plain English
+        "math": r"\alpha > 0",                      # Optional: LaTeX formula
+        "references": ["Wilfong26"],                # Optional: BibTeX keys from references.bib
+        "exceptions": ["IBM cases"],                # Optional: when constraint doesn't apply
+    },
+}
+```
+
+The @ref physics_constraints "Physics Constraints" page is **auto-generated** — run `./mfc.sh generate` to rebuild it.
+The generator merges your `PHYSICS_DOCS` entry with the AST-extracted `prohibit()`/`warn()` calls,
+so stage, severity, and parameter information appear automatically.
+
+**Fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `title` | Yes | Section heading in generated docs |
+| `category` | Yes | Grouping category (e.g., "Mixture Constraints") |
+| `explanation` | Yes | Plain English description of the physics |
+| `math` | No | LaTeX formula (rendered by Doxygen's MathJax) |
+| `references` | No | List of BibTeX cite keys from `docs/references.bib` |
+| `exceptions` | No | List of cases where the constraint doesn't apply |
+
+**Categories:** Thermodynamic Constraints, Mixture Constraints, Domain and Geometry, Velocity and Dimensional Consistency, Model Equations, Boundary Conditions, Bubble Physics, Feature Compatibility, Numerical Schemes, Acoustic Sources, Post-Processing.
+
 ## Testing
 
 MFC has 500+ regression tests. See @ref testing for the full guide.

docs/documentation/readme.md

@@ -15,6 +15,7 @@ Welcome to the Multi-component Flow Code (MFC) documentation.
 - @ref parameters "Case Parameters" - All ~3,400 parameters
 - @ref cli-reference "CLI Reference" - Command line options
 - @ref case_constraints "Case Creator Guide" - Feature compatibility
+- @ref physics_constraints "Physics Constraints" - Mathematical basis for validation rules
 
 ## Examples & Visualization
 

docs/gen_constraints.sh

@@ -14,4 +14,5 @@ echo "Generating case constraints documentation..."
 python3 "$REPO_ROOT/toolchain/mfc/gen_case_constraints_docs.py" > "$REPO_ROOT/docs/documentation/case_constraints.md"
 echo "✓ Generated docs/documentation/case_constraints.md"
 
-
+python3 "$REPO_ROOT/toolchain/mfc/gen_physics_docs.py" > "$REPO_ROOT/docs/documentation/physics_constraints.md"
+echo "✓ Generated docs/documentation/physics_constraints.md"

examples/2D_bubbly_steady_shock/case.py

@@ -155,6 +155,7 @@
             "fluid_pp(1)%pi_inf": gam_l * (pi_inf_l) / (gam_l - 1.0),
             # Bubbles
             "bubbles_euler": "T",
+            "nb": nb,
             "bubble_model": 2,
             "polytropic": "T",
             "polydisperse": "F",