test: integrate periodic Taylor-Green AMR assessment

docs/validation/taylor_green.md

@@ -0,0 +1,161 @@
+# Periodic 2D Taylor–Green AMR campaign (prepared, not GPU-qualified)
+
+This validation harness complements DFG Re100 and Jet/body tests. It measures
+smooth 2D periodic decay and errors crossing fixed refinement interfaces at
+Re_L=100 and 1000. It does **not** certify 3D turbulence, LES, Jet performance,
+wall conditions, dynamic refinement or general high-Re flows.
+
+## Reference and conventions
+
+Primary implementation-author documentation, checked 2026-10-18:
+- TensorMesh, exact velocity and pressure with a consistent phase:
+  https://docs.tensor-mesh.com/example_gallery/fluid/taylor_green.html
+- AeroSim Nassu, 2D decay, energy and lattice-length Re definition:
+  https://docs.aerosim.io/nassu/validation/analytical/04_taylor_green_vortex_2d/README.html
+
+We use the TensorMesh phase, rescaled to length L=N root cells:
+
+    k = 2*pi/L; A(t) = U*exp(-2*nu*k*k*t)
+    ux = -A*cos(k*x)*sin(k*y)
+    uy =  A*sin(k*x)*cos(k*y)
+    p/rho0 = -A*A/4 * (cos(2*k*x)+cos(2*k*y))
+    E = <|u|^2>/2 = U*U/4 * exp(-4*nu*k*k*t)
+
+Pressure is kinematic, with rho0=1. A global velocity sign reversal leaves
+pressure unchanged; exchanging sine/cosine without the corresponding pressure
+phase can reverse its sign. CPU tests independently check momentum residuals.
+The nonlinear acceleration is a pressure gradient, **not zero**; the AeroSim
+page's prose calling advection zero is not adopted. Do not mix phase variants
+from different references. The formulas above are verified by substitution,
+not by trusting a copied pressure expression.
+
+Re_L=U*L/nu, not Re_k=U/(nu*k)=Re_L/(2*pi). U=.03 in lattice units,
+Ma=U/cs=.0519615, cs^2=1/3, nu_root=.03*N/Re_L. Acoustic refinement uses
+h_l=dt_l=2^-l: lattice velocity stays U, nu_l=2^l*nu_root and
+ tau_l=.5+3*nu_l. The worst root tau is .50288 (N32/Re1000), omega=1.98855,
+inside the existing config guard. No viscosity clamping or guard override.
+
+All initial arrays are physical FP64 equilibrium populations, supplied to the
+public shifted-FP32 postcollision-G initializer. rho=1+3p at each true cell
+center. These are valid equilibrium postcollision states, but do not include
+Chapman–Enskog nonequilibrium stress; startup acoustic/kinetic error remains in
+the measurements and is shared with uniform baselines. The incompressible
+reference is not an exact finite-Mach LBM solution. This is why resolution alone
+need not remove the full error floor.
+
+## Geometry and workload
+
+All patches use level-wide union form, so origins are zero, including fine
+arrays with holes. Coordinates are (index+.5)*2^-level. Metrics integrate only
+ACTIVE leaves, each weighted by 4^-level. Covered cells and halo cells never
+enter norms or mass. Geometry tests prove exact single coverage at root-cell
+resolution. All blocks are 8x8, and both root dimensions are periodic.
+
+At each root N=32,64:
+- 2 levels: L1 rectangle (N/8,N/8,7N/8,3N/4), in L0 indices.
+- 3 levels: same L1 plus L2 rectangle (3N/4,N/2,3N/2,5N/4), in L1 indices.
+
+These off-axis boundaries cross nonzero flow and gradients rather than sitting
+only on symmetry or stagnation lines. Whole geometry scales with N.
+
+16 cases: at each Re, uniform N=32,64,128,256 plus AMR (root32/root64)x(depth2/depth3).
+Each AMR case therefore has both a same-root uniform baseline and a uniform
+baseline at its finest spacing. Uniform N is its own lattice length, so nu and
+step count are scaled to represent the same nondimensional solution.
+Samples t*=tU/L = 0,.12,.24,.36,.48. End time is 16*N base steps, a meaningful
+.48 domain turnover or 3.016 vortex-scale turnover times (scale 1/k).
+At Re1000 energy decays about 7.3%; at Re100 about 53.1%. No plots or full fields;
+each case writes five diagnostic rows and provenance, incrementally.
+
+## Running (GPU owner must schedule launches)
+
+CPU checks, from the repository root:
+
+    PYTHONPATH=src python -m unittest discover -s tests/validation/taylor_green -p 'test_*.py' -v
+
+One GPU case, on the scheduled worker after checking occupancy:
+
+    CUDA_VISIBLE_DEVICES=<physical-id> python tests/validation/taylor_green/run_case.py --repo /path/to/reviewed/checkout --re 100 --n 32 --depth 1 --output output/taylor_green/re100_n32_d1.json
+
+Depth 1 is uniform. Run uniform cases before AMR for each Re; inspect baseline
+screening failures before proceeding. For a complete matrix, repeat the uniform
+call with N=32,64,128,256 and AMR calls with N=32,64 / depth=2,3, at each Re.
+Use serial process startup on the parent's assigned Horsea GPUs. This harness
+does not schedule or acquire GPUs. No GPU was used during preparation.
+
+    python tests/validation/taylor_green/assess.py output/taylor_green/re*_n*_d*.json --output output/taylor_green/assessment.json
+
+The local API/geometry review used clean staging commit
+cd3a657f9d3833e812c3cca173525f165b48710a. This is **not** a claim of results on d79
+or any historical commit. Each runtime output records actual Git HEAD/dirty
+state, an aggregate source-tree hash, plus SHA256 of all harness Python files. Assessment refuses dirty checkouts and mixed source
+or harness identities. Keep reports outside the checkout or .gitignore them so
+new outputs do not change its dirty flag between cases. The source-tree hash excludes bytecode caches; production qualification requires
+a clean checkout.
+The runner uses the existing PeriodicBlockStepper / FixedPatchStepper periodic
+paths only. It does not depend on the new channel-root implementation.
+
+## Preregistered assessment, before any GPU results
+
+All sampled times must satisfy finite screening ceilings:
+- Relative composite velocity L2 <= 5%
+- Relative globally gauge-adjusted pressure L2 <= 15%
+- Relative kinetic-energy error <= 5%
+- Composite mass drift from downloaded t0 <= 1e-5
+
+These are screening budgets, not literature-certified tolerances. Acceptance
+also requires all 16 cases, common source/harness, correct nondimensional times
+and viscosity, and baseline-relative checks on worst post-startup-sample errors:
+- AMR error <= max(2 * same-root uniform error, declared numerical floor).
+- Root64 AMR error <= max(.9 * root32 AMR error, floor), for each depth/Re.
+- Uniform256 error <= max(.9 * uniform32 error, floor).
+
+Floors: velocity .002, pressure .02, energy .004. They are declared low-Mach /
+equilibrium-startup budgets, not fitted to observed results. Ma^2=.0027 motivates
+their scale; it is an asymptotic expectation, not a proof of those coefficients.
+The coarse baseline sets the AMR budget because much of the domain remains
+coarse. The finest uniform error and AMR/fine ratio are always reported, with no
+claim that partial refinement should match a fully fine domain. A pass below a
+floor is bounded accuracy, not a measured convergence order. Report errors and
+ratios even for a pass. Failure requires diagnosis or a separately preregistered
+follow-up, never retroactive tolerance tuning. Higher Re is deliberately absent;
+Re100/1000 must first be stable, resolved and reviewed.
+
+Diagnostics use one global pressure gauge, direct cell-center analytic values,
+kinetic energy per unit reference mass, and actual leaf cell areas. Composite
+midpoint quadrature introduces a small initial energy integration error, retained
+rather than subtracted. Mass drift is relative to downloaded t0, so density
+initialization and mixed-grid quadrature do not masquerade as time drift.
+
+## Pilot scheduling and transfer-consistency scope
+
+Start with one uniform case and one matched AMR case; the 16-case matrix is a
+qualification plan, not authorization to launch every case automatically. The
+GPU owner reviews the pilot before expanding it. Each process prints a flushed
+READY only after initialization, a real base step exercising every level's
+kernel/halo/transfer path, and a finite positive-density download check. That
+step belongs to the measured trajectory; it is not discarded warmup. PROGRESS
+messages contain each of the five diagnostic samples. READY alone is not an
+accuracy pass. Reports include per-level active cells, hops and collision updates.
+
+The complete matrix costs 768,540,672 active collision updates and 21,504 root
+intervals, excluding ghost streaming, halos, transfers and diagnostic work.
+Uniform N256 is the largest case (268,435,456 updates / 4096 intervals per Re).
+AMR N64/depth3 needs 50,987,008 updates / 1024 intervals. These are work counts,
+not GPU wall-time estimates. Baseline comparisons remain available on failed
+screens and partial pilots; absent/nonfinite operands are null, never passing.
+
+Acoustic viscosity scaling and unchanged lattice velocity do not by themselves
+prove nonequilibrium-stress consistency across refinement interfaces. A smooth
+collocated Chapman–Enskog postcollision nonequilibrium has a (tau-1)*h factor;
+the existing implementation instead uses volumetric piecewise-constant explosion
+and stream-only ghosts. Whether that actual transfer construction achieves the
+needed stress accuracy is an unresolved question for this pilot to measure.
+It is not a proven defect, and a collocated-state scaling factor must not be
+inserted into this different transfer operator without a separate derivation
+and validation. This campaign measures the current operator and makes no
+theoretical stress-consistency certification or production-kernel change.
+
+## Repository integration
+
+The four Python harness files remain together under tests/validation/taylor_green, so runtime provenance hashes precisely this harness directory. Formatting changes produce a new harness identity; preparation and integrated receipts must not be mixed. All analytic definitions, numerical floors, assessment gates, sample times, and source-import assertions are unchanged. Production source is unchanged from the cd3 snapshot; these periodic tests do not waive the separate channel GPU gate.