# Taylor–Green analytical validation

The planar Taylor–Green vortex is an exact solution of the incompressible
Navier–Stokes equations. With unit initial velocity and wavenumber in the
periodic cube `[0, 2π]^3`, independent of z:

```text
u =  sin(x) cos(y) exp(-2 nu t)
v = -cos(x) sin(y) exp(-2 nu t)
w = 0
p = (cos(2x) + cos(2y)) exp(-4 nu t) / 4 + arbitrary constant
mean kinetic energy = exp(-4 nu t) / 4
```

Here p is kinematic pressure. Advection is balanced by the pressure gradient;
the velocity amplitude decays by viscosity. See the equivalent phase/length
convention in [NVIDIA's analytical Taylor–Green example](https://github.com/NVIDIA/warp/blob/main/warp/examples/fem/example_taylor_green.py).
This is a planar solution exercised on the full 3D MAC solver. It does not test
the nonlinear vortex stretching of the default 3D initial condition, which
multiplies u and v by cos(z). That case requires numerical references and
refinement; neither exp(-4 nu t) nor exp(-6 nu t) is its exact energy history.

## Mandatory regression

`verify-all` always runs `TaylorGreenRegression` with each of SemiLagrangian and
MacCormack, even when its existing baseline directory is empty. The fixed
configuration is 64³, nu=0.1, dt=1/256, t=0…0.25, multigrid, diagnostic interval
16 steps. It checks a roughly 9.5% physical energy decay in 64 steps. This is a
short regression; separate low-viscosity and refinement studies are needed for
long or poorly resolved flows.

Acceptance is fixed before measuring the new regression:

- Relative velocity L2 error <=2% at every diagnostic sample, including the
  initial and final fields. Evaluate the exact solution directly at MAC faces;
  half-weight the duplicated periodic boundary faces. Include the W=0 component.
- Energy-decay error <5% at every diagnostic sample, preserving the existing
  energy tolerance while extending it from endpoint to trajectory coverage.
  Compare E(t)/E(0) with exp(-4 nu t). E is the existing reconstructed-cell
  diagnostic; normalization cancels its initial interpolation factor. The
  independent face-velocity test also detects incorrect initial amplitude.
- Every pressure and velocity-diffusion solve converges; native maxDiv remains
  <1e-5 and is checked at every positive diagnostic time for the planar case. Energy, velocity error,
  pressure magnitude, divergence and times must be finite and present.
- Samples start at zero, advance strictly in time and reach the requested
  endpoint. Invalid samples cannot be discarded to turn a failure into a pass.

Pressure is checked for finiteness; this regression does not assert pressure
accuracy. The split projection's reported pressure requires a separate error
study. Diagnostics use the actual captured time, including adaptive/final steps,
and run only at the configured diagnostic cadence. Solver algorithms are unchanged.

`dotnet test` includes the same two numerical regressions and rejection tests for
reversed velocities with unchanged energy, spurious W, nonfinite/omitted
diagnostics, transient failures and incomplete trajectories.

```bash
dotnet test test/PolyCfd.Tests/PolyCfd.Tests.csproj -c Release \
  --filter FullyQualifiedName~TaylorGreenValidationTests

# Mandatory analytical, moving-fan and backward-step checks without saved CSVs:
dotnet run -c Release --project src/PolyCfd.Cli -- \
  verify-all --suite quick --backend cuda --output output/validation/checks --performance-baseline /path/to/accepted-raw-performance.json

# Standalone analytical run; use a fresh output root to preserve recorded data:
dotnet run -c Release --project src/PolyCfd.Cli -- \
  baseline record taylor-green --scenario examples/scenarios/taylor-green-planar/scenario.json \
  --output-interval 16 \
  --baseline output/validation/planar-example
```

The analytical run needs no saved numerical reference. `record` additionally
writes its samples and manifest; `verify` also checks the selected saved data.
The historical default saved Taylor–Green case is 3D and does not establish
analytical accuracy. Planar mode was introduced in commit `19ca7f0` on 2026-09-15;
the mandatory suite entries and full velocity checks were added on 2026-09-18.
Legacy `planar_...` directories now restore planar mode instead of silently
running the 3D case. Versioned manifests already preserve the mode explicitly.

The planar checks added two performance keys; the subsequent
[Beltrami/traveling-shear controls](/docs/PERIODIC_EXACT_VALIDATION) add four more.
Existing timing references are
preserved; a missing key is reported as missing coverage. Update a performance
reference only through an intentional `verify-all --record-performance` run
after the complete scientific suite passes. Numerical success without a timing
reference is reported as **Performance NOT checked**.

## Current validation results

Both advection schemes pass the mandatory planar checks. Together with the
four exact periodic controls, both moving-fan regressions and backward step,
the mandatory suite passes 9/9. Saved-baseline and performance-reference
comparisons were not rerun.

The production 128³ planar MacCormack run at Re=400, nu=0.0025, dt=1/512 and
t=20 passes: maximum native-face velocity error **0.8564%** and energy-decay
error **1.6512%**, below the unchanged 2% and 5% limits. All saved times are finite
and complete; native convergence/divergence checks pass.

This exact planar result does not establish accuracy of nonlinear 3D vortex
stretching. The latest fully 3D comparison still misses its strict velocity
and refinement targets. See the sibling comparison workspace's
[current report] (unavailable local reference: `../../openfoam/compare/TAYLOR_GREEN_COMPARISON.md`) and
[measurements] (unavailable local reference: `../../openfoam/compare/taylor_green_comparison.json`).