Merge master into TerminalOutput: resolve conflicts with #1762

Author: sbryngelson

.claude/rules/common-pitfalls.md

@@ -36,6 +36,35 @@ covered in `docs/documentation/contributing.md`.
 - `@:ACC_SETUP_VFs(...)`/`@:ACC_SETUP_SFs(...)` GPU pointer setup compiles only under
   Cray. Around MPI: `GPU_UPDATE(host=...)` before send, `GPU_UPDATE(device=...)` after
   receive.
+- An array whose bound is a device global (`dimension(num_fluids)`, `dimension(num_species)`) may be
+  passed to a device routine **from a parallel-loop body, but not from inside another
+  `GPU_ROUTINE(parallelism='[seq]')`**. CCE OpenACC rejects the second form with
+  `ftn-7066 ... Global in accelerator routine without declare -- num_fluids`, and reports it at
+  whatever line it gave up on: remove one trigger and the message *walks forward* to the next call,
+  so the reported line is not the cause. Only the plain lanes fail - under `--case-optimization`
+  those bounds are `parameter`s, so a green Case Opt lane beside a failing plain one is the
+  signature. Every accepted call site in the tree already obeys this (`m_cbc`, `m_ibm`,
+  `m_bubbles_EL`, `s_compute_cell_state`): form such a call in the loop body and pass scalars
+  deeper. Neither `cray_inline` nor a `num_fluids_max` bound nor dropping optional dummies helps -
+  all three were measured.
+- nvfortran 23.11/24.1 segfault (`fort2 TERMINATED by signal 11`) on a caller that passes a
+  `parameter` array from `m_thermochem` (e.g. `molecular_weights`) into a declare-target routine.
+  Read such arrays directly in the kernel, or pass a plain local computed from them.
+- The `USING_AMD` fypp guards (86 sites, `#:set` in `src/common/include/shared_parallel_macros.fpp`) are
+  load-bearing, not a stale workaround - do not "modernize" them away. They swap a device-global array
+  bound for a literal: `dimension(3)` for `num_dims`/`num_fluids` when case optimization is off (64
+  sites), and `dimension(20)` for `sys_size` in `m_compute_cbc` (21 sites, with a matching
+  `@:PROHIBIT` in `m_start_up` capping `sys_size <= 20` under AMD+CBC). Setting `USING_AMD = False`
+  and rebuilding amdflang `--gpu mp` without case optimization compiles CLEAN - 728 s, zero
+  diagnostics - and then NaNs at step 50 in CBC, riemann `wave_speeds=2`, IBM, surface tension,
+  QBMM/viscous and MHD HLLD, while both Lagrange bubble cases *complete* with out-of-tolerance
+  answers. Measured 2026-08-29 on MI210. A compile-only check returns green, so any future attempt to
+  drop these must run the tests, not just build.
+- The same "call it from the loop body" rule covers `m_thermochem`: calling `get_species_*` from
+  inside a `GPU_ROUTINE` rather than from the kernel gave CCE OpenMP a runtime
+  `Memory access fault by GPU node-N ... Reason: Unknown` on the first step (exit 134), while every
+  other backend ran. Evaluate them at the call site and pass the arrays in. Note this one only shows
+  at runtime, and only on a case that reaches the path - the build is clean.
 
 ## Parameters
 
@@ -105,6 +134,27 @@ covered in `docs/documentation/contributing.md`.
 - Tests are generated programmatically in `toolchain/mfc/test/cases.py` (parameter
   modifications on `BASE_CFG` via the `CaseGeneratorStack` push/pop pattern); test UUID =
   CRC32 of the trace string; `./mfc.sh test -l` lists all.
+- `--only` matches whole trace *elements*, not substrings, and `_filter_only`
+  (`toolchain/mfc/test/test.py`) **ANDs labels while ORing UUIDs**. So `--only bubbles` matches
+  nothing (the element is `Bubbles`), and `--only low_Mach=1 low_Mach=2` asks for cases carrying
+  both and also matches nothing. It then exits **143**, which reads like an external kill rather
+  than an empty filter. Pass UUIDs whenever you want the union of several groups.
+- Sibling `define_case_d` calls off the same stack level are never *combined*. Two switches that
+  only matter together (`avg_state=1` needs `wave_speeds=2` to be read at all) therefore get zero
+  effective coverage unless something pushes one and defines the other beneath it. Check
+  reachability before trusting that a flag is tested.
+- `--no-build` silently runs whatever binary is on disk for a configuration it did not build.
+  Chemistry has its own config (`gpu-mp-chem-*`) that a plain `./mfc.sh build` never produces, so
+  a `--no-build` run reports failures from stale binaries and hides real compile breaks. Run
+  chemistry-touching sets without it.
+- Pick the newest binary by the *binary's* mtime (`ls -t build/install/*/bin/simulation`), not the
+  install directory's - a stale config's directory can be newer than a fresh build's.
+- The pre-commit hook lives in the main repo's `.git/hooks/` and git exports `GIT_DIR` there
+  during a commit, so from a worktree the toolchain lint enumerates the *other* checkout and
+  fails. Reproduce with `GIT_DIR=<main>/.git ./mfc.sh precheck`. Run precheck by hand and commit
+  with `--no-verify`.
+- `/tmp` is node-local: scratch does not survive a compute-node change, and its absence is
+  silence, not an error. Keep patches and resource baselines on a shared filesystem.
 - Golden files are tolerance-compared. Regenerate only the affected tests
   (`./mfc.sh test --generate --only <tests>`) — an unexplained golden-file diff is a bug
   report, not noise to be regenerated away.

docs/documentation/contributing.md

@@ -452,6 +452,31 @@ $:GPU_DECLARE(create='[my_array]')
 
 If an array is allocated inside an `if` block, its deallocation must follow the same condition.
 
+### How to Add an Equation of State
+
+Every stiffened-gas expression lives in `src/common/m_variables_conversion.fpp`. Adding a second EOS
+means supplying these, not grepping for `gammas`:
+
+| Operator | Gives |
+|---|---|
+| `s_compute_mixture_coefficients` / `_dt` | mixture \f$\Gamma, \Pi_\infty, q_v\f$ from the phase fractions, and their time derivative |
+| `f_pressure` / `s_compute_energy` | \f$p(e)\f$ and \f$E(p)\f$ |
+| `f_bulk_modulus` | \f$K(p)\f$ - every sound speed in MFC is \f$K/\rho\f$, differing only in how phases are mixed |
+| `s_compute_speed_of_sound` / `_avg` | that mixing: Wood's law, 6-equation, bubble-diluted |
+| `f_phase_internal_energy` | per-phase internal energy (6-equation model) |
+| `f_isentrope_exponent` / `f_isentrope_pressure` / `f_pressure_on_isentrope` | the isentrope \f$p + B = \textrm{const}\,\rho^n\f$ |
+| `f_sg_thermal` | the thermal law \f$p + B = (n-1)c_v\rho T\f$ |
+
+The first six are *mechanical* - they need only \f$p, \rho, e, c\f$. The last two are *caloric* and
+additionally need \f$c_v\f$ and \f$q'_v\f$. An EOS that supplies only the mechanical set cannot support
+phase change (`m_phase_change` also needs entropy and enthalpy) or reactive burn, so those features
+must be prohibited for it in `case_validator.py`.
+
+The coefficients arrive in two parameterizations of the same EOS: `gammas`/`pi_infs` are the stored
+forms the user supplies (see @ref sec-stored-forms), and `isentrope_n`/`isentrope_B` are the same EOS
+as \f$p + B = \textrm{const}\,\rho^n\f$, derived once at start-up. Convert with the `f_isentrope_*`
+operators rather than open-coding either relation.
+
 ### How to Add a Test Case
 
 **Step 1: Create a case file**

docs/documentation/equations.md

@@ -644,7 +644,7 @@ Reaction mechanisms are code-generated via Pyrometheus (\cite Cisneros26), which
 
 ## 10. Surface Tension (`surface_tension = .true.`) (\cite Schmidmayer17; \cite Wilfong26 Sec. 4.1.8)
 
-**Source:** `src/simulation/m_surface_tension.fpp`, `src/simulation/include/inline_capillary.fpp`
+**Source:** `src/simulation/m_surface_tension.fpp`
 
 **Color function advection:**
 

docs/documentation/gpuParallelization.md

@@ -614,15 +614,14 @@ Does not do anything for OpenMP currently
 pure, sequential per-thread helpers is:
 
 ```fortran
-subroutine s_accumulate_mixture_properties(nf, alpha_rho_K, alpha_K, rho_K, gamma_K, pi_inf_K, qv_K)
+subroutine s_compute_mixture_coefficients(alpha_rho_K, alpha_K, rho_K, gamma_K, pi_inf_K, qv_K)
 
-    $:GPU_ROUTINE(function_name='s_accumulate_mixture_properties', parallelism='[seq]', cray_inline=True)
+    $:GPU_ROUTINE(function_name='s_compute_mixture_coefficients', parallelism='[seq]', cray_inline=True)
 
-    integer, intent(in)                 :: nf
-    real(wp), dimension(nf), intent(in) :: alpha_rho_K, alpha_K
-    real(wp), intent(out)               :: rho_K, gamma_K, pi_inf_K, qv_K
+    real(wp), dimension(num_fluids), intent(in) :: alpha_rho_K, alpha_K
+    real(wp), intent(out)                       :: rho_K, gamma_K, pi_inf_K, qv_K
     ...
-end subroutine s_accumulate_mixture_properties
+end subroutine s_compute_mixture_coefficients
 ```
 
 **When to use it.** Extract a block into a `GPU_ROUTINE` helper when:

examples/0D_bubblecollapse_adap/case.py

@@ -122,6 +122,7 @@
             "nb": nb,
             # Fluids Physical Parameters
             "fluid_pp(1)%gamma": 1.0e00 / (gam_l - 1.0e00),
+            "fluid_pp(1)%eos": "stiffened_gas",
             "fluid_pp(1)%pi_inf": gam_l * (pi_inf_l / p0) / (gam_l - 1.0),
         }
     )

examples/1D_acoustic_dipole/case.py

@@ -64,6 +64,7 @@
             "acoustic(1)%delay": 1e-7,
             # Fluids Physical Parameters
             "fluid_pp(1)%gamma": 1.0e00 / (4.4e00 - 1.0e00),
+            "fluid_pp(1)%eos": "stiffened_gas",
             "fluid_pp(1)%pi_inf": 4.4e00 * 5.57e08 / (4.4e00 - 1.0e00),
         }
     )

examples/1D_acoustic_gauss_sigmadist/case.py

@@ -63,6 +63,7 @@
             "acoustic(1)%delay": 1e-7,
             # Fluids Physical Parameters
             "fluid_pp(1)%gamma": 1.0e00 / (4.4e00 - 1.0e00),
+            "fluid_pp(1)%eos": "stiffened_gas",
             "fluid_pp(1)%pi_inf": 4.4e00 * 5.57e08 / (4.4e00 - 1.0e00),
         }
     )

examples/1D_acoustic_gauss_sigmatime/case.py

@@ -63,6 +63,7 @@
             "acoustic(1)%delay": 1e-7,
             # Fluids Physical Parameters
             "fluid_pp(1)%gamma": 1.0e00 / (4.4e00 - 1.0e00),
+            "fluid_pp(1)%eos": "stiffened_gas",
             "fluid_pp(1)%pi_inf": 4.4e00 * 5.57e08 / (4.4e00 - 1.0e00),
         }
     )

examples/1D_acoustic_sine_frequency/case.py

@@ -63,6 +63,7 @@
             "acoustic(1)%delay": 0,
             # Fluids Physical Parameters
             "fluid_pp(1)%gamma": 1.0e00 / (4.4e00 - 1.0e00),
+            "fluid_pp(1)%eos": "stiffened_gas",
             "fluid_pp(1)%pi_inf": 4.4e00 * 5.57e08 / (4.4e00 - 1.0e00),
         }
     )

examples/1D_acoustic_sine_wavelength/case.py

@@ -63,6 +63,7 @@
             "acoustic(1)%delay": 0,
             # Fluids Physical Parameters
             "fluid_pp(1)%gamma": 1.0e00 / (4.4e00 - 1.0e00),
+            "fluid_pp(1)%eos": "stiffened_gas",
             "fluid_pp(1)%pi_inf": 4.4e00 * 5.57e08 / (4.4e00 - 1.0e00),
         }
     )