Walking Search for Particle Location

Table of Contents

• 1. Core Search Concept
• 2. Settlement Status Model
• 3. Implementation Touchpoints
• 4. Restart Path Specifics
• 5. Current test status
• 6. Failure Modes and Signals

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.

3. Implementation Touchpoints

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

5. Current test status

Current direct coverage is strongest at the orchestrator level:

• LocateAllParticlesInGrid has dedicated direct tests for the prior-cell fast path and the local guess-then-verify path
• restart fast-path migration is covered directly through MigrateRestartParticlesUsingCellID

Current direct gaps still targeted for the next remediation are:

• branch-complete unit coverage for LocateParticleOrFindMigrationTarget
  • boundary clamp
  • ghost-region handoff
  • stuck/tie-breaker
  • LOST and MIGRATING_OUT
• direction-complete and failure-path coverage for the GuessParticleOwnerWithBBox heuristic
• non-restart MPI migration tests for multi-pass handoff and newcomer flagging

6. Failure Modes and Signals

Watch for:

• excessive migration pass counts,
• repeated LOST particles,
• non-convergence of settlement loop,
• elevated traversal effort or repeated tie-break/boundary-clamp events in <run.analysis.metrics>/search_metrics.csv,
• increasing search_failure_fraction, search_work_index, or re_search_fraction,
• increasing lost or lost_cumulative even when migration otherwise appears healthy.

For precise metric definitions and formulas, see Search Robustness Metrics Reference.

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

See Common Fatal Errors and Fixes for troubleshooting commands.