Add field indexing, ghost cells, test system, analytical IC docs

- Fix parameter checklist: first 3 mandatory, #4 only if constraints exist
- Fix namelist format: &user_inputs ... &end/ (not &user_inputs / ... / &end)
- Update counts: ~3,400 params (was ~3,300), 560+ tests (was 500+)
- Add ghost cell allocation pattern (-buff_size:m+buff_size, idwint/idwbuff)
- Add field variable indexing system (cont_idx, mom_idx, E_idx, adv_idx, sys_size)
- Add test system details: programmatic generation, CaseGeneratorStack, UUID hashing
- Add scalar_field uses stp (not wp) to precision types
- Add analytical IC available variables (x, y, z, xc, yc, zc, lx, ly, lz, r, e, t)

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

Author: sbryngelson

.claude/rules/common-pitfalls.md

@@ -1,10 +1,28 @@
 # Common Pitfalls
 
-## Array Bounds
-- Arrays use non-unity lower bounds with ghost cells
+## Array Bounds & Ghost Cells
+- Grid dimensions: `m`, `n`, `p` (cells in x, y, z). 1D: n=p=0. 2D: p=0.
+- Interior domain: `0:m`, `0:n`, `0:p`
+- Buffer/ghost region: `-buff_size:m+buff_size` (similar for n, p in multi-D)
+- `buff_size` depends on WENO order and features (typically `2*weno_polyn + 2`)
+- Domain bounds: `idwint(1:3)` (interior `0:m`), `idwbuff(1:3)` (with ghost cells)
+- Cell-center coords: `x_cc(-buff_size:m+buff_size)`, `y_cc(...)`, `z_cc(...)`
+- Cell-boundary coords: `x_cb(-1-buff_size:m+buff_size)`
 - Riemann solver indexing: left state at `j`, right state at `j+1`
 - Off-by-one errors in ghost cell regions are a common source of bugs
 
+## Field Variable Indexing
+- Conserved variables: `q_cons_vf(1:sys_size)`. Primitive: `q_prim_vf(1:sys_size)`.
+- Index ranges depend on `model_eqns` and enabled features (set in `m_global_parameters.fpp`):
+  - `cont_idx` — continuity (partial densities, one per fluid)
+  - `mom_idx` — momentum components
+  - `E_idx` — total energy (scalar)
+  - `adv_idx` — volume fractions (advection equations)
+  - `bub_idx`, `stress_idx`, `xi_idx`, `species_idx`, `B_idx`, `c_idx` — optional
+- Shorthand scalars: `momxb`/`momxe`, `contxb`/`contxe`, `advxb`/`advxe`, etc.
+- `sys_size` = total number of conserved variables (computed at startup)
+- Changing `model_eqns` or enabling features changes ALL index positions
+
 ## Blast Radius
 - `src/common/` is shared by ALL three executables (pre_process, simulation, post_process)
 - Any change to common/ requires testing all three targets
@@ -23,12 +41,15 @@
 - Fypp macros must expand correctly for both GPU and CPU builds
 - GPU builds only work with nvfortran, Cray ftn, and AMD flang
 
-## Test Golden Files
-- Tests compare output against golden files in `tests/<hash>/golden.txt`
+## Test System
+- Tests are generated **programmatically** in `toolchain/mfc/test/cases.py`, not standalone files
+- Each test is a parameter modification on top of `BASE_CFG` defaults
+- Test UUID = CRC32 hash of the test's trace string; `./mfc.sh test -l` lists all
+- To add a test: modify `cases.py` using `CaseGeneratorStack` push/pop pattern
+- Golden files: `tests/<UUID>/golden.txt` — tolerance-based comparison, not exact match
 - If your change intentionally modifies output, regenerate golden files:
   `./mfc.sh test --generate --only <affected_tests> -j 8`
 - Do not regenerate ALL golden files unless you understand every output change
-- Golden file diffs are compared with tolerance, not exact match
 
 ## PR Checklist
 Before submitting a PR:

.claude/rules/fortran-conventions.md

@@ -50,6 +50,11 @@ Enforced by convention/code review (not automated):
 - Always use generic intrinsics: `sqrt` not `dsqrt`, `abs` not `dabs`.
 - Cast with `real(..., wp)` or `real(..., stp)`, never `dble(...)`.
 
+Key derived types (`m_derived_types.fpp`):
+- `scalar_field` — `real(stp), pointer :: sf(:,:,:)`. Uses `stp`, NOT `wp`.
+- `vector_field` — allocatable array of `scalar_field` components.
+- New field arrays MUST use `stp` for storage precision consistency.
+
 ## Size Guidelines (soft)
 - Subroutine: ≤500 lines
 - Helper routine: ≤150 lines

.claude/rules/parameter-system.md

@@ -1,7 +1,7 @@
 # Parameter System
 
 ## Overview
-MFC has ~3,300 simulation parameters defined in Python and read by Fortran via namelist files.
+MFC has ~3,400 simulation parameters defined in Python and read by Fortran via namelist files.
 
 ## Parameter Flow: Python → Fortran
 
@@ -17,15 +17,16 @@ MFC has ~3,300 simulation parameters defined in Python and read by Fortran via n
 
 3. **Input Generation**: `toolchain/mfc/run/input.py`
    - Python case dict → Fortran namelist `.inp` file
-   - Format: `&user_inputs / ... / &end`
+   - Format: `&user_inputs` ... `&end/`
 
 4. **Fortran Reading**: `src/*/m_start_up.fpp`
    - Reads `&user_inputs` namelist
    - Each parameter must be declared in the namelist statement
 
 ## Adding a New Parameter (4-location checklist)
 
-YOU MUST update all 4 locations. Missing any causes silent failures or compile errors.
+YOU MUST update the first 3 locations. Missing any causes silent failures or compile errors.
+Location 4 is required only if the parameter has physics constraints.
 
 1. **`toolchain/mfc/params/definitions.py`**: Add parameter with type, default, constraints
 2. **`src/*/m_global_parameters.fpp`**: Declare the Fortran variable in the relevant
@@ -52,3 +53,14 @@ add Fortran-side checks here in addition to `case_validator.py`.
 ## Analytical Initial Conditions
 String expressions in parameters become Fortran code via `case.py.__get_analytic_ic_fpp()`.
 These are compiled into the binary, so syntax errors cause build failures, not runtime errors.
+
+Available variables in analytical IC expressions:
+- `x`, `y`, `z` — cell-center coordinates (mapped to `x_cc(i)`, `y_cc(j)`, `z_cc(k)`)
+- `xc`, `yc`, `zc` — patch centroid coordinates
+- `lx`, `ly`, `lz` — patch lengths
+- `r` — patch radius; `eps`, `beta` — vortex parameters
+- `e` — Euler's number (2.71828...)
+- Standard Fortran math intrinsics available: `sin`, `cos`, `exp`, `sqrt`, `abs`, etc.
+- For moving immersed boundaries: `t` (simulation time) is also available
+
+Example: `'patch_icpp(1)%vel(2)': '(x - xc) * exp(-((x-xc)**2 + (y-yc)**2))'`

CLAUDE.md

@@ -29,7 +29,7 @@ All commands run from the repo root via `./mfc.sh`.
 ./mfc.sh run case.py -e batch -N 2 -n 4 -c phoenix -a ACCOUNT  # Batch submit on Phoenix
 
 # Testing
-./mfc.sh test -j 8                         # Run full test suite (500+ tests)
+./mfc.sh test -j 8                         # Run full test suite (560+ tests)
 ./mfc.sh test --only 1D -j 8              # Only 1D tests
 ./mfc.sh test --only 2D Bubbles -j 8      # Only 2D bubble tests
 ./mfc.sh test --only <UUID> -j 8          # Run one specific test by UUID
@@ -50,7 +50,7 @@ source ./mfc.sh load -c p -m c             # Load Phoenix CPU modules
 
 # Other
 ./mfc.sh validate case.py                  # Validate case file without running
-./mfc.sh params <query>                    # Search ~3300 case parameters
+./mfc.sh params <query>                    # Search ~3,400 case parameters
 ./mfc.sh clean                             # Remove build artifacts
 ./mfc.sh new <name>                        # Create new case from template
 ```
@@ -117,11 +117,11 @@ src/
   simulation/     # CFD solver (GPU-accelerated via OpenACC / OpenMP target offload)
   post_process/   # Data output and visualization
 toolchain/        # Python CLI, build system, testing, parameter management
-  mfc/params/definitions.py   # ~3300 parameter definitions (source of truth)
+  mfc/params/definitions.py   # ~3,400 parameter definitions (source of truth)
   mfc/case_validator.py       # Physics constraint validation
   mfc/test/                   # Test runner and case generation
 examples/         # Example simulation cases (case.py files)
-tests/            # 500+ regression test golden files
+tests/            # 560+ regression test golden files
 ```
 
 Source files are `.fpp` (Fortran + Fypp macros), preprocessed to `.f90` by CMake.
@@ -137,11 +137,11 @@ NEVER use `stop` or `error stop`. Use `call s_mpi_abort()` or `@:PROHIBIT()`/`@:
 NEVER use `goto`, `COMMON` blocks, or global `save` variables.
 
 Every `@:ALLOCATE(...)` MUST have a matching `@:DEALLOCATE(...)`.
-Every new parameter MUST be added in 4 places:
+Every new parameter MUST be added in at least 3 places (4 if it has constraints):
   1. `toolchain/mfc/params/definitions.py` (parameter definition)
   2. Fortran variable declaration in `src/*/m_global_parameters.fpp`
   3. Fortran namelist in `src/*/m_start_up.fpp` (namelist binding)
-  4. `toolchain/mfc/case_validator.py` (if constraints exist)
+  4. `toolchain/mfc/case_validator.py` (only if parameter has physics constraints)
 
 Changes to `src/common/` affect ALL three executables. Test comprehensively.