# Exact periodic 3D and traveling-flow validation

`periodic-exact` adds two independent unforced analytical controls to the existing
planar Taylor–Green checks. The fully 3D Beltrami field has nonzero velocity in all
directions and depends on every coordinate. The traveling shear separately exposes
transport phase and amplitude errors. Neither replaces the nonlinear 3D
Taylor–Green reference/refinement study.

## Exact problems

The domain is the actual float-grid cube of side L, approximately 2π. An integer
`--wave-number m` gives κ=2πm/L, so the reference is periodic on that exact domain.
Amplitude A defaults to 1. With F=A exp(-3 nu κ² t), the Beltrami case is

```text
u = -F/2 [sqrt(3) cos(κx) sin(κy) sin(κz) + sin(κx) cos(κy) cos(κz)]
v =  F/2 [sqrt(3) sin(κx) cos(κy) sin(κz) - cos(κx) sin(κy) cos(κz)]
w =  F cos(κx) cos(κy) sin(κz)
p = -(u² + v² + w²)/2 + arbitrary constant
mean kinetic energy = 3 A² exp(-6 nu κ² t)/16
```

This specializes the viscous Beltrami validation in
[the ARPS model manual, section 13.3](https://caps.ou.edu/ARPS/download/code/pub/ARPS.docs/ARPS4DOC.PDF/arpsch13.pdf).
It satisfies curl(U)=sqrt(3)κU and ΔU=-3κ²U; its nonzero advection balances the
pressure gradient. Pressure is kinematic; the state starts with the exact
initial pressure, which participates in the static incremental predictor. The
pressure increment starts at zero. Pressure accuracy is not presently an acceptance gate.

The default X-traveling shear has carrying speed C (`--transport-speed`, default 1):

```text
u = C
v = A exp(-nu κ² t) sin(κ(x-Ct))
w = 0
p = arbitrary constant
mean kinetic energy = C²/2 + A² exp(-2 nu κ² t)/4
```

`initial.profile.axis="y"` cyclically maps X/Y/Z to Y/Z/X: the carrier is V and the wave is W.
`initial.profile.axis="z"` maps X/Y/Z to Z/X/Y: the carrier is W and the wave is U. The same proper
cyclic rotations apply to Beltrami. Wavenumber must lie strictly below grid/2;
aliasing a reference mode onto its Nyquist mode is rejected.

## Diagnostics and fixed acceptance

Every velocity component is compared at its native MAC face. Opposite periodic
endpoints receive half weight. Energy uses the corresponding double-accumulated
face quadrature and reports mean energy per unit mass, not the existing
Taylor–Green reconstructed-cell domain integral.

Both total and fluctuation relative velocity L2 must be <=2%; both total and
fluctuation relative energy error must be <5% at every diagnostic sample.
Fluctuations subtract the known uniform carrier, preventing a large C from hiding
an incorrect transported wave. Energy is compared directly with its exact value,
including at initialization. These bounds were fixed before the reported runs.

All diagnostic values must be finite and present. Samples must start at zero,
increase strictly, and reach the requested final time. Native maxDiv must be
<1e-5 at positive sample times; every pressure and diffusion solve must converge.
The runner uses `SimulationSession` and its existing per-step convergence guard.
The controls use the production numerical method without changing its acceptance
thresholds. The later periodic-diffusion correction is characterized separately
below with the same exact-control settings and bounds.

For shear, `waveAmplitudeRatio` fits the sine/cosine coefficients of the fundamental
mode and divides their magnitude by the exact decaying amplitude. `wavePhaseError`
is numerical minus exact phase, wrapped into [-π,π], in radians. These diagnose
errors in addition to the full-field gates. They are placeholders 1 and 0 for
Beltrami; use its velocity and energy errors. Pressure magnitude and mean-velocity
drift are reported; pressure is required to be finite.

## CLI and mandatory checks

```bash
# Actual 3D analytical velocity and pressure balance:
dotnet run -c Release --project src/PolyCfd.Cli -- \
  baseline record periodic-exact --scenario examples/scenarios/periodic-beltrami/scenario.json \
  --baseline output/validation/beltrami-example

# Transport through Z of an X-directed wave; this demanding case may fail:
dotnet run -c Release --project src/PolyCfd.Cli -- \
  baseline record periodic-exact --scenario examples/scenarios/periodic-shear-z/scenario.json \
  --output-interval 64 --baseline output/validation/shear-example
```

Use fresh baseline/export locations. `scenario-run.json` records the flow, axis, wavenumber,
amplitude, speed, grid, cadence and runtime configuration. `baseline replay <directory>` restores all
these settings and the recorded verification policy. HDF5/VTU exports use host options; adaptive stepping is authored in scenario JSON.

`verify-all` always runs four additional MacCormack/multigrid controls: Beltrami
k=1 and shear k=2 along X/Y/Z. All use 64³, A=C=1, nu=.0025, dt=1/256, t=.25 and
diagnostics every 16 steps. These settings and the acceptance bounds were fixed
before characterization. They complement the existing two planar checks, two
moving-fan checks and backward step: **nine mandatory checks total**. New timing
keys do not replace any performance baseline. Existing moving-fan diffusion
failures remain separate failures; individual analytical passes do not establish
that the complete suite passes.

## Original CUDA characterization, before the diffusion fix

The four short guards pass: Beltrami has 0.2069% velocity and 0.01777% energy error;
the shear directions each have approximately 0.6771% fluctuation-velocity and
0.4182% fluctuation-energy error. All pass native divergence/convergence.

The longer t=1 study uses nu=.0025, A=C=1, MacCormack/multigrid, dt=1/512:

| Flow | Grid | Maximum velocity error | Maximum energy error | Result |
| --- | ---: | ---: | ---: | --- |
| Beltrami k=1 | 32³ | 0.5803% | 0.03351% | PASS |
| Beltrami k=1 | 64³ | 0.6659% | 0.02715% | PASS |
| Beltrami k=1 | 128³ | 0.6646% | 0.02912% | PASS |
| Shear k=4, fluctuations | 32³ | 47.433% | 38.088% | FAIL |
| Shear k=4, fluctuations | 64³ | 13.214% | 10.980% | FAIL |
| Shear k=4, fluctuations | 128³ | 3.806% | 3.025% | FAIL: velocity |

Halving dt at 64³ leaves shear k=4 error essentially unchanged (13.278% velocity,
11.042% energy). Its base-step phase error is +0.11649 rad and amplitude ratio
0.94276. Shear k=1 passes at all three grids. The preserved failures demonstrate
transport errors even in a flow with constant carrying velocity and zero pressure
gradient, independent of OpenFOAM or nonlinear vortex stretching.

Beltrami's original 64³ half-step velocity error is 0.6662% and energy error
0.00869%. The original velocity error plateaus rather than showing a consistent
grid/time trend; passing the 2% gate **does not establish convergence**. The
diffusion isolation below identifies a substantial source of this plateau.

All 15 characterization runs reached their requested endpoint on CUDA; source,
binary, command, manifest and sample hashes are under
`output/validation/periodic-exact/`. `summary.json` is the compact result;
`characterization.json` retains samples and provenance. The initial Beltrami
attempt and CSV-parser failures are preserved; the accepted recorded repeat is
`guard-beltrami-attempt2`. These were accuracy runs; no runtime comparison follows.

## Matched rerun after the periodic-diffusion correction

An independent kernel probe found incorrect low-end periodic neighbor reads in
the compiled velocity-diffusion kernel. Separating the endpoint offset from a
nested conditional corrects those reads. The dedicated rectangular-grid and
Fourier-mode regressions fail in all 18 original configurations and pass with the
correction. The exact controls retain their original settings and acceptance
bounds; no advection change is included in this comparison.

All 15 configurations were repeated on CUDA using the corrected frozen GPU
assembly, SHA256 beginning `eaa94e03dae2b89a`. All four short guards still pass:
Beltrami now has 0.01286% velocity and 0.01817% energy error; the three shear
orientations have approximately 0.5309% fluctuation-velocity and 0.3956%
fluctuation-energy error.

The corrected t=1 results are:

| Flow | Grid | Maximum velocity error | Maximum energy error | Result |
| --- | ---: | ---: | ---: | --- |
| Beltrami k=1 | 32³ | 0.11668% | 0.03565% | PASS |
| Beltrami k=1 | 64³ | 0.03378% | 0.02936% | PASS |
| Beltrami k=1 | 128³ | 0.01916% | 0.03045% | PASS |
| Shear k=1, fluctuations | 32³ | 0.99874% | 0.78804% | PASS |
| Shear k=1, fluctuations | 64³ | 0.27708% | 0.19056% | PASS |
| Shear k=1, fluctuations | 128³ | 0.07370% | 0.04212% | PASS |
| Shear k=4, fluctuations | 32³ | 47.190% | 38.120% | FAIL |
| Shear k=4, fluctuations | 64³ | 12.861% | 10.972% | FAIL |
| Shear k=4, fluctuations | 128³ | 3.342% | 2.866% | FAIL: velocity |

At 64³, halving dt gives Beltrami 0.02985% velocity and 0.01082% energy error.
Its velocity now improves with grid refinement, and the large original plateau
is removed. The small remaining errors and the nonmonotonic base-step energy
trend still require separate grid/time interpretation; these controls do not
establish accuracy of the nonlinear Taylor–Green trajectory.

The corrected k=4 shear still fails: halving dt at 64³ gives 12.931% velocity
and 11.048% energy error. At the base timestep its phase error is +0.11280 rad
and amplitude ratio 0.94286. Correcting diffusion therefore does not remove the
transport phase/amplitude error exposed by this exact solution.

An additional isolation run sets C=0 for k=1 shear at 64³, retaining nu=.0025,
dt=1/512 and t=1. Its velocity error drops from 0.72495% to 0.002700%, and mean
velocity drift drops from 7.93e-4 to 8.50e-8. Energy error changes from 0.02621%
to 0.005377%. This stationary decaying wave shows how a significant velocity
distortion can coexist with a small energy error. These two runs are recorded
separately from the original frozen 15-case matrix.

The original evidence remains intact. Corrected commands, manifests, source
copies, assembly hashes, full samples and the comparison summary are under
`output/validation/periodic-exact-diffusion-fix/`. The only changed Core/GPU source
file between the two frozen builds is `DiffusionGpu.cs`; all eight external
dependency assemblies have matching hashes. These remain accuracy measurements,
without a performance claim.

Release build passed with zero warnings/errors. There are 59 passing focused
host/manifest/baseline-settings tests and four passing CUDA guard tests, including
all-axis formula checks, native staggering, endpoint weighting, phase/component
corruption, large-mean masking and invalid/incomplete evidence rejection.

The current production build passes **9/9 mandatory entries** with an empty
baseline directory, including both planar Taylor–Green schemes, all four exact
periodic controls, both moving fans and backward step. The production diffusion
arithmetic and iteration budget are documented in the
[Diffusion README](/src/PolyCfd.Gpu/Diffusion/README). See the
[current comparison report] (unavailable local reference: `../../openfoam/compare/TAYLOR_GREEN_COMPARISON.md`)
for measured status. This mandatory run does not verify saved baselines or a
performance reference.