PICurv 0.1.0
A Parallel Particle-In-Cell Solver for Curvilinear LES
Loading...
Searching...
No Matches
Analytical Solution Modes

Table of Contents

Analytical mode bypasses the normal momentum/Poisson time advancement and directly sets Eulerian fields from closed-form expressions.

1. 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

2. Supported Types In Current Code

  • TGV3D
  • ZERO_FLOW
  • UNIFORM_FLOW

Implementation touchpoints:

3. 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:

  • single block: full domain assignment,
  • multi-block: requires perfect-square block count for XY decomposition.
  • the analytical geometry logic assigns the domain itself; the launcher-side programmatic grid inputs primarily provide resolution (im/jm/km)

4. 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.

5. 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 logs/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.

6. Particle Consistency

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

7. Adding A New Analytical Type

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

Also update:

CFD Reader Guidance and Practical Use

This page describes Analytical Solution Modes within the PICurv workflow. For CFD users, the most reliable reading strategy is to map the page content to a concrete run decision: what is configured, what runtime stage it influences, and which diagnostics should confirm expected behavior.

Treat this page as both a conceptual reference and a runbook. If you are debugging, pair the method/procedure described here with monitor output, generated runtime artifacts under runs/<run_id>/config, and the associated solver/post logs so numerical intent and implementation behavior stay aligned.

What To Extract Before Changing A Case

  • Identify which YAML role or runtime stage this page governs.
  • List the primary control knobs (tolerances, cadence, paths, selectors, or mode flags).
  • Record expected success indicators (convergence trend, artifact presence, or stable derived metrics).
  • Record failure signals that require rollback or parameter isolation.

Practical CFD Troubleshooting Pattern

  1. Reproduce the issue on a tiny case or narrow timestep window.
  2. Change one control at a time and keep all other roles/configs fixed.
  3. Validate generated artifacts and logs after each change before scaling up.
  4. If behavior remains inconsistent, compare against a known-good baseline example and re-check grid/BC consistency.
Generated by doxygen 1.9.8