# Multigrid Poisson

Geometric V-cycle solver for the Poisson equation `∇²φ = f` on a 3D periodic torus. The HXT Lucas-tier hierarchy is the substrate-natural coarse-grid pyramid: each coarse level halves the resolution of its parent, and the same smoother runs natively at every tier.

## Algorithm

1. Pre-smooth (n_pre red-black Gauss-Seidel sweeps on the 7-point stencil)
2. Compute residual `r = f - L φ`
3. Restrict residual to next-coarser level (full-weighting, 8-cell average)
4. Recurse to coarsest level
5. Hammer coarsest level to floor
6. Prolong correction back up (trilinear interpolation)
7. Post-smooth (n_post sweeps)

The CFL on the smoother is unconditional (Gauss-Seidel is implicit-direction), so the time-to-solution is bounded by the V-cycle count, not by stiffness.

## Validation

For the canonical sine-mode source `f(x,y,z) = -3 k² sin(kx) sin(ky) sin(kz)` the exact solution is `φ = sin(kx) sin(ky) sin(kz)` (up to additive constant on the periodic torus). The 7-point Laplacian has O(h²) discretization error, so the L∞ deviation from exact halves by ~4 under each grid refinement N → 2N. The engine reports the h²·k⁴/12 estimate alongside the measured error.

Verified in unit tests:
- residual drops by >3 orders of magnitude in 6 V-cycles on 16³
- L∞ error follows the 4× per refinement ratio across 8³ → 16³ → 32³
- L∞ ≤ 6× the h²-estimate

## Substrate framing

The Lucas-tier cascade in the GMDBS substrate IS the multigrid pyramid. Each coarse level "tier-k" aggregates 8 tier-(k-1) cells; full-weighting restriction is the exact cell-centered average. The same smoother kernel ports unchanged to GPU via the cascade_tune WGSL dispatch pattern.

## Parameters

| Field | Meaning | Default |
|-------|---------|---------|
| nx, ny, nz | grid dimensions (must all match, must be power of 2 × min_n) | 32 |
| box_length | physical length L of the torus side | 2π |
| n_cycles | maximum V-cycles | 8 |
| n_pre, n_post | smoother sweeps before/after recursion | 2, 2 |
| min_n | coarsest grid size N to stop coarsening at | 4 |
| tol | residual tolerance to break early | 1e-10 |
| source | `sine_mode` (has exact reference), `gaussian`, or `checker` | sine_mode |
| k_mode | frequency for sine_mode source | 1 |