2. Analytical Type Entries

Value	Maps to
`TGV3D`	`TGV3D`
`UNIFORM_FLOW`	`UNIFORM_FLOW`
`ZERO_FLOW`	`ZERO_FLOW`

ZERO_FLOW

Identity. operation_mode.analytical_type: ZERO_FLOW -> -analytical_type ZERO_FLOW.

What it does. Supplies an exactly zero velocity field.

When to choose it. Isolating a mechanism that must not depend on advection. The diffusivity-gradient and Brownian verification cases use it so that any particle motion observed is attributable to the term under test, not to the flow.

Parameters it owns. None.

Interactions. Requires eulerian_source: analytical. No flow solve runs.

Diagnostics. The startup banner reports the analytical mode.

Evidence. Production exercised - examples/drift_diffusivity_gradient. Analytically verified - brownian-msd-2026-09-18: a Brownian cloud in this field reproduces the Einstein relation to 0.17%, so the carrier adds no motion of its own.

Limitations. No flow, by construction.

UNIFORM_FLOW

Identity. operation_mode.analytical_type: UNIFORM_FLOW -> -analytical_type UNIFORM_FLOW, with components from the analytical_uniform_* options.

What it does. Supplies a spatially uniform, constant velocity field.

When to choose it. Verifying advection: a known constant velocity makes the exact particle trajectory trivially predictable, which is what turns a run into a test.

Parameters it owns. The uniform velocity components.

Interactions. Requires eulerian_source: analytical. Supported on file grids as well as programmatic ones.

Diagnostics. Startup banner; particle displacement should match velocity times elapsed time exactly.

Evidence. Production exercised - examples/drift_uniform_flow. Analytically verified - curvilinear-gcl-2026-09-18: on a curved file grid the face fluxes it sets close to round-off in every cell; uniform-drift-2026-09-18: a particle cloud drifts at exactly the carrier velocity.

Limitations. Uniform only; no shear, so it exercises no velocity-gradient behaviour.

TGV3D

Identity. operation_mode.analytical_type: TGV3D -> -analytical_type TGV3D.

What it does. Supplies the Taylor-Green field u = V0 sin x cos y cos z e^{-2 nu t}, v = -V0 cos x sin y cos z e^{-2 nu t}, w = 0, with pressure decaying as e^{-4 nu t}. It is a prescribed kinematic field, not a solution of the Navier-Stokes equations: the cos z factor makes it a three-dimensional mode whose viscous decay would be e^{-3 nu t}, and the three-dimensional Taylor-Green flow has no closed form. What it offers is a smooth, divergence-free, exactly known field at every time.

When to choose it. Exercising a genuinely three-dimensional field with strong velocity gradients, where a uniform flow would test nothing.

Parameters it owns. None beyond the analytical selector.

Interactions. Requires eulerian_source: analytical. Unlike the two simpler modes it is not supported on the file-grid path.

Diagnostics. Startup banner reports the mode.

Evidence. Production exercised - examples/interpolation_test uses the TGV3D field as the analytic reference for its particle interpolation-error checks. Analytically verified - solution-monitoring-tgv3d-2026-09-18: the staged velocity and pressure match the formula above to 9e-16 and 8e-16 at every step.

Limitations. Not available for file-based grids. Use it as a known field for interpolation, post-processing, statistics and monitoring checks, never as a reference a flow solve should reproduce: a solver started from it will not follow it.

3. Activation Path

Analytical mode is selected by:

solver.yml.operation_mode.eulerian_field_source: analytical
solver.yml.operation_mode.analytical_type: <TYPE>

Flags generated by picurv:

-euler_field_source "analytical"
-analytical_type "..."

Runtime dispatch is handled by function AnalyticalSolutionEngine in analytical execution mode.

Current launcher contract:

TGV3D should be paired with case.yml -> grid.mode: programmatic_c
ZERO_FLOW and UNIFORM_FLOW support case.yml -> grid.mode: programmatic_c and case.yml -> grid.mode: file
grid_gen remains outside the current documented analytical contract

4. Supported Types In Current Code

TGV3D
ZERO_FLOW
UNIFORM_FLOW

Implementation touchpoints:

custom-geometry policy check: AnalyticalTypeRequiresCustomGeometry
analytical geometry assignment: SetAnalyticalGridInfo
state setter dispatch: AnalyticalSolutionEngine

5. TGV3D Details

Current TGV3D implementation sets fields with decaying Taylor-Green style forms in non-dimensional coordinates. Representative form:

\[ \nu = 1/Re, \quad u_x \sim \sin(kx)\cos(ky)\cos(kz)e^{-2\nu k^2 t}, \quad u_y \sim -\cos(kx)\sin(ky)\cos(kz)e^{-2\nu k^2 t}. \]

Geometry behavior for TGV3D in function SetAnalyticalGridInfo follows:

the whole domain is assigned to the single block,
the analytical geometry logic assigns the domain itself; the launcher-side programmatic grid inputs primarily provide resolution (im/jm/km)

6. ZERO_FLOW Details

ZERO_FLOW sets a quiescent background state while preserving the same analytical-mode control path. It is useful for controlled particle-motion or postprocessing validation scenarios.

Grid behavior:

ZERO_FLOW uses the standard analytical grid-ingestion split,
with programmatic_settings for grid.mode: programmatic_c and -grid_file ingestion for grid.mode: file,
but the flow field itself is imposed analytically as zero everywhere.

7. UNIFORM_FLOW Details

UNIFORM_FLOW sets a constant Eulerian velocity field everywhere in the domain while keeping pressure zero. It is intended for deterministic particle-advection verification, where cloud centre-of-mass motion should match the configured constant velocity exactly.

Configuration:

solver.yml -> operation_mode.analytical_type: "UNIFORM_FLOW"
solver.yml -> operation_mode.uniform_flow.{u,v,w}

Grid behavior:

UNIFORM_FLOW uses the standard analytical grid-ingestion split,
with programmatic_settings for grid.mode: programmatic_c and -grid_file ingestion for grid.mode: file,
but the analytical engine populates both Eulerian cell-center and boundary velocity data with the configured constant vector.
the implementation works in curvilinear form: it sets Ucont (contravariant flux) using face-metric dot products and derives Ucat via Contra2Cart, ensuring correctness on non-Cartesian grids.

Verification-only source overrides such as solver.yml -> verification.sources.diffusivity may be paired with ZERO_FLOW when the analytical velocity field itself should remain quiescent. Those overrides are not general production modeling features; they exist only for otherwise-unreachable end-to-end verification scenarios.

The same analytical-solutions layer now also owns verification-only scalar truth evaluation for solver.yml -> verification.sources.scalar. That scalar path supports CONSTANT, LINEAR_X, and SIN_PRODUCT, writes prescribed truth onto particle Psi, and supplies analytical cell-center reference values for the runtime diagnostic <run.analysis.metrics>/scatter_metrics.csv. Keeping scalar truth in AnalyticalSolutions makes the feature reusable for future static deposition checks, moving-cloud verification under UNIFORM_FLOW, and coupled flow-plus-scatter diagnostics under TGV3D without pushing analytical logic into ParticlePhysics.

8. Particle Consistency

Particle-side analytical initialization hooks exist via SetAnalyticalSolutionForParticles so particle fields can remain consistent with analytical Eulerian state when desired.

9. Adding A New Analytical Type

add a new branch in function AnalyticalSolutionEngine for the new type,
define geometry policy in function AnalyticalTypeRequiresCustomGeometry for that type,
implement geometry setup in function SetAnalyticalGridInfo when needed,
update YAML schema/docs and generated-flag mapping.

Also update:

Table of Contents