Walking Search for Particle Location

Table of Contents

• 1. Core Search Concept
• 2. Settlement Status Model
• 4. Restart Path Specifics

PICurv uses a robust locate-and-migrate pipeline so every particle ends each step with a valid owner rank and host cell (or is explicitly marked lost).

1. Core Search Concept

A particle is tested against candidate cell faces using signed distances. Search starts from prior cell information when available, then walks to neighboring cells by face-crossing logic until a terminal status is reached.

This avoids expensive global brute-force lookup and is suitable for distributed curvilinear grids.

2. Settlement Status Model

Location/migration logic uses ParticleLocationStatus:

• NEEDS_LOCATION
• ACTIVE_AND_LOCATED
• MIGRATING_OUT
• LOST
• UNINITIALIZED

These statuses drive the iterative migration passes in the orchestrator.

2. Code Path In PICurv

• single-particle walking search: LocateParticleInGrid
• robust locate-or-migrate decision: LocateParticleOrFindMigrationTarget (walking-search module)
• global orchestrator: LocateAllParticlesInGrid
• rank migration communication: PerformMigration
• per-particle migration cycle helper: PerformSingleParticleMigrationCycle
• restart fast-path migration: MigrateRestartParticlesUsingCellID

The current orchestrator includes:

1. PID snapshot,
2. per-particle locate/guess/verify,
3. migration,
4. newcomer flagging,
5. repeat until no global migrations remain (or safety pass cap).

4. Restart Path Specifics

For restart-loaded particles with valid CellID, PICurv can skip full walking search and directly resolve owner rank via cell ownership map before migration. This is usually much cheaper than full re-location on first restart step.

4. What This Means For Users

Watch for:

• excessive migration pass counts,
• repeated LOST particles,
• non-convergence of settlement loop.

These usually indicate domain-decomposition mismatch, bounding-box mismatch, or invalid particle coordinates.

See Common Fatal Errors and Fixes for troubleshooting commands.