Particle Model and Coupling Overview

Table of Contents

• 1. Per-Step Particle Pipeline
• 4. Statistics and Diagnostics

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.

3. Field/Coordinate Scaling Conventions

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.

2. Physics and Model Selection

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.

7. Extensibility Status

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, Smoke, and Quality Gates Guide

1. Reference Scales

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