CelerisLab/docs/validation/taylor_green.md

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=UL/nu, not Re_k=U/(nuk)=Re_L/(2pi). U=.03 in lattice units, Ma=U/cs=.0519615, cs^2=1/3, nu_root=.03N/Re_L. Acoustic refinement uses h_l=dt_l=2^-l: lattice velocity stays U, nu_l=2^lnu_root and tau_l=.5+3nu_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 cd3a657f9d. 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.

Oblique shear wave (test-only diagnostic, not GPU-qualified)

shear_wave.py reuses the frozen oracle's constants, cell centers and geometry. oracle.py is byte-identical, and test_shear_wave.py pins its eec4677 SHA-256. run_case.py --flow shear_wave selects it. The default flow is still the frozen Taylor–Green oracle, and the default receipt is unchanged.

Convention: integer mode (2,1) on the L=N periodic root domain, so k = (2*pi/L)*(2,1) points 26.565° from +x. Mode (1,2) would point 63.435°. A wrong-mode test catches a swap between the two. Polarization is E = (-1,2)/sqrt(5), perpendicular to k:

u = U*E*sin(k.x + phi)*exp(-nu*|k|^2*t),  phi = 0,  p = const,  rho0 = 1

Here nu = U*N/100, the Taylor–Green Re100 viscosity at the same N. The initial condition is FP64 second-order equilibrium at the actual leaf centers, with no non-equilibrium part.

Physical caveats:

1. Finite-Mach error. The second-order D2Q9 equilibrium has third moment sum_i f_eq c_a c_b c_g = rho*cs^2*(u_a d_bg + u_b d_ag + u_g d_ab). The (c.u)^2 term contributes only even moments. The continuum target also has rho*u_a*u_b*u_g. At Navier–Stokes (first Chapman–Enskog) order, the resulting stress error is proportional to d_g(rho u_a u_b u_g). For this field with uniform density, u.grad = 0 and div u = 0, so that particular term vanishes.

   This does not show that all finite-Mach or cubic error vanishes. It does not cover:

   • higher Chapman–Enskog orders;
   • lattice truncation for the oblique wavevector;
   • FP32 storage;
   • any density nonuniformity, which interfaces or anisotropy can create.

2. Startup. Equilibrium initialization omits the non-equilibrium stress. The resulting kinetic transient lasts O(tau) steps and may shift the in-phase amplitude. The decay rate is fitted from ln(a_hat) using only samples with t* >= 0.12, which is about 1.9N root steps and much longer than tau. This is intended to reduce startup sensitivity. It has not been shown to cancel the bias, and that remains unverified until measured.

Metrics are computed on ACTIVE leaf cells only, each weighted by its area 4**-level in root-cell units. The partition must cover the domain exactly once. One global pressure gauge is used, never one per level.

• a_hat, b_hat: weighted least-squares fit of u.E onto the sin and cos modes, solved with the 2x2 Gram matrix of the actual composite quadrature.
• phase_drift = atan2(b_hat, a_hat), in radians.
• rate_error = |rate_fit/(nu|k|^2) - 1|, dimensionless. Rates are per root step.
• velocity_l2: error relative to the exact field.
• residual_l2: the velocity left after subtracting the fitted mode, relative to the exact-field norm.
• longitudinal_l2: the u.k_hat part of the velocity, relative to the exact-field norm.
• pressure_rel = p_rms/(A(t)^2/4): the gauged composite rms of p = (rho-1)/3, divided by a fixed analytic scale.
  • A²/4 is the continuum rms of the Taylor–Green exact pressure at the same amplitude. That makes the number comparable in magnitude with TG pressure_l2, but it is not that norm. TG normalizes by the discrete, globally gauged exact-pressure norm on the composite grid.
  • Exact pressure here is constant, so no relative-to-exact claim is made.
  • Max and per-level values are reported for localization.

Preregistered screens (shear_wave.assess):

• Run set: uniform N, uniform 2N, and refined depth-2 runs at root N, with constant and/or projected_linear explosion.
• eps(N) = (|k| h_root)^2 = 5*(2*pi/N)^2, dimensionless, coefficient one. It is 0.01205 at N=128.
• Absolute screens: rate_error, max |phase_drift| (radians) and max residual_l2 must each be <= eps. This is a preregistered diagnostic choice of the second-order truncation scale, not a proven error bound.
• Existing ceilings also apply: velocity_l2 <= 0.05, mass <= 1e-5 and pressure_rel <= 0.02.
• Budget form, as in assess.py: refined <= max(2*control_N, floor), with floors 0.002 for rate and residual and 0.02 for pressure.
• The ratio to the 2N control is reported, not gated.
• A control failing an absolute screen makes the set INVALID_CONTROL. The screens are never retuned.

Scope: one flow, one rectangle, SRT only. Two resolutions show a trend, not an order. This does not establish placement robustness.