skill-particle-reseeding

name	skill-particle-reseeding
description	MDOODZ particle reseeding and recycling — reseeding modes 0/1, particle deactivation (excess culling), recycling mechanism, markers struct fields, min_part_cell threshold, Nb_part_max hard limit, and common failure modes.

MDOODZ Particle Reseeding & Recycling

Overview

MDOODZ uses marker-in-cell advection. Particles drift with the flow and can cluster in convergent zones (downwellings, corners) while leaving divergent cells depleted. The reseeding system detects under-populated cells and injects new particles, while the deactivation system culls excess particles from over-populated cells. Dead particles (phase = -1) are recycled as slots for new ones.

All reseeding logic lives in MDLIB/ParticleRoutines.c. The file MDLIB/ParticleReseeding.c contained a dead function (CountPartCell2) that has been removed from the build.

Reseeding Modes

Set reseed_mode in the .txt parameter file:

Mode	Function	Placement	Deactivation	Slot Recycling
0	CountPartCell_OLD	Closest-neighbour (per-thread ipreuse[])	None	Per-thread ipreuse[]
1	CountPartCell	Fine-cell centroid	None	Global part_reuse[]
2	CountPartCell_v2	Random within fine cell	Distance-from-centroid, farthest first	Global part_reuse[]

All modes use a fine mesh (2×Ncx × 2×Ncz) for cell-particle assignment, then map back to the coarse mesh for reseeding decisions.

Key Struct Fields (markers)

Field	Type	Meaning
Nb_part	int	Current active particle count
Nb_part_max	int	Hard allocation limit (4.1× initial count)
min_part_cell	int	Minimum particles per cell (from .txt); triggers reseeding
phase[]	int*	Phase index; -1 = dead/air (available for recycling)
Nx_part	int	Particles per cell in x (typically 4)
Nz_part	int	Particles per cell in z (typically 4)

Reseeding Threshold

A cell is considered under-populated when its particle count drops below min_part_cell. The reseeding routine (AddPartCell2) injects new particles at sub-cell positions, assigning phase from the nearest existing neighbour.

Deactivation (Excess Culling)

Only mode 2 (CountPartCell_v2) actively deactivates excess particles. After reseeding, it scans all cells on the fine mesh. If a cell has more than fine_threshold particles (where fine_threshold = ceil(min_part_cell / 4.0) + 4), the excess are sorted by distance from the cell centroid and the farthest are marked phase = -1 (dead), making their array slots available for recycling.

Boundary guard: Cells with BCt.type == 30 (Dirichlet thermal boundary) are skipped — deactivating boundary particles would corrupt boundary conditions.

Modes 0 and 1 have no deactivation. Particles can only become dead (phase = -1) by exiting the domain boundaries or being above the free surface. In a closed-box simulation (e.g., Blankenbach convection), modes 0 and 1 will see monotonic growth of active particle count, eventually hitting Nb_part_max and crashing with exit(190). Mode 2 is the only mode that guarantees bounded active particle count in closed environments.

Recycling Mechanism

• Mode 1: After counting, builds part_reuse[] — an array of indices where phase == -1. New particles are assigned to these slots first. When slots run out, Nb_part is incremented (up to Nb_part_max).
• Mode 0: Each thread maintains ipreuse[ith][]. Same logic: dead slots first, then fresh indices.

Nb_part in HDF5 Output

Nb_part is written as a 1-element integer dataset in the Model group of each HDF5 output file. Use readScalarInt(file, "Model", "Nb_part") from TestHelpers.h to read it in tests.

Common Failure Modes

Symptom	Cause	Fix
exit(190) crash	Nb_part reached Nb_part_max	Deactivation not working or threshold too high
Particles cluster in corners	Convection concentrates markers in downwellings	Normal — deactivation culls excess
Phase smearing at boundaries	Deactivation ran on boundary cells	Check BCt.type != 30 guard
Nb_part grows monotonically	Using mode 0 or 1 (no deactivation)	Switch to reseed_mode = 2 for closed-box simulations

.txt Parameters

Nx_part          = 4     # particles_per_cell_x
Nz_part          = 4     # particles_per_cell_z
min_part_cell    = 16    # Reseeding threshold
reseed_mode      = 1     # 0, 1, or 2

DEBUG Logging

With log_level = 3 (DEBUG), all three reseeding functions emit per-cell and per-particle diagnostic messages:

• Cell trigger: cell (i,j) fine: N particles (threshold=T), reseeding
• Particle placement: new particle at (x, z), reusing slot K or appended at index K
• Deactivation (mode 2 only): cell (i,j): N particles, excess E, deactivating E farthest and deactivated particle K (dist=D from centroid)
• Summary: Nb_part: <before> -> <after> (reused=R, created=C)

Enable in .txt: log_level = 3. These messages are suppressed at the default log_level = 2 (INFO).

See also: VISUAL_TESTS/ReseedingGuide.md for a visual guide with plots from real simulation output.

BlankenBench Test Coverage

The ConvectionDevelops test in TESTS/BlankenBenchTests.cpp asserts that Nb_part stays within 2× the initial count after 500 steps, confirming the recycling mechanism works for closed-box convection.