Particle Model and Coupling Overview

Table of Contents

• 1. Per-Step Particle Pipeline
• 2. Core Particle Fields In Use
• 3. Current Built-In Physics
• 4. Statistics and Diagnostics
• 5. Extending To New Closures
• 6. Related Pages
  • CFD Reader Guidance and Practical Use
    • What To Extract Before Changing A Case
    • Practical CFD Troubleshooting Pattern

This page documents the particle pipeline exactly as orchestrated in the current solver flow.

1. Per-Step Particle Pipeline

Typical order inside coupled step:

1. interpolate Eulerian fields to swarm: InterpolateAllFieldsToSwarm
2. advance particle positions: UpdateAllParticlePositions
3. locate/migrate particles: LocateAllParticlesInGrid
4. update particle physics fields: UpdateAllParticleFields
5. scatter particle fields back to Eulerian storage: ScatterAllParticleFieldsToEulerFields

Each stage relies on valid DMSwarm_CellID, interpolation weights, and synchronized ghost data.

Step 1 dispatches through InterpolateEulerFieldToSwarm, which selects between two interpolation paths based on SimCtx.interpolationMethod:

• Trilinear (default): direct interpolation from the 8 nearest cell centers, second-order on curvilinear grids.
• CornerAveraged (legacy): two-stage center-to-corner averaging then trilinear from corners.

See Trilinear Interpolation and Particle-Grid Projection for method details and configuration.

2. Core Particle Fields In Use

Commonly used swarm fields include:

• position (position)
• velocity (velocity)
• cell ID (DMSwarm_CellID)
• location status (DMSwarm_location_status)
• diffusivity and scalar (Diffusivity, Psi)

Status transitions (NEEDS_LOCATION, ACTIVE_AND_LOCATED, MIGRATING_OUT, LOST) determine whether particles are walked, migrated, or skipped in settlement passes.

3. Current Built-In Physics

Current scalar model path:

• kernel: UpdateParticleField
• batch loop: UpdateFieldForAllParticles
• orchestrator: UpdateAllParticleFields

This presently implements IEM-style relaxation for Psi, with model constants sourced from runtime context.

4. Statistics and Diagnostics

Post statistics currently include global kernels such as:

• ComputeParticleMSD

Additional health indicators are available from migration counters and settlement-pass counts stored in SimCtx fields updated by location logic. For particle-enabled runs, the runtime also writes logs/search_metrics.csv with per-step and cumulative loss plus aggregated search-attempt, traversal, tie-break, boundary-clamp, bbox-guess, and pass-depth signals. The examples/search_robustness/ bundle is the dedicated end-to-end reference for interpreting that artifact.

5. Extending To New Closures

Recommended extension pattern:

1. add particle model selector to YAML/flags,
2. branch inside particle physics orchestrator,
3. isolate model-specific kernels from motion/location kernels,
4. keep scatter/interpolation interfaces unchanged,
5. validate with smoke tests and deterministic small cases.

For configuration contract changes, update:

• Configuration Contract (YAML -> Generated Artifacts -> Runtime)
• Configuration Extension Playbook
• Testing and Validation Guide

6. Related Pages

• Initial Condition Modes
• Particle Initialization and Restart Guide
• Walking Search for Particle Location

CFD Reader Guidance and Practical Use

This page describes Particle Model and Coupling Overview 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.