findNeighbors3D

findNeighbors3D

Builds the candidate contact-pair list for a 3D cell list. For every particle in every cell it looks at the 27 cells of the periodic 3x3x3 stencil around that cell and emits each (source, dest) candidate pair once, with source < dest. These are distance candidates, not confirmed contacts — the caller (the pack integration loop) still has to check the actual separation against the contact distance. Extracted from pack.m (it was a local subfunction) so it can be unit-tested directly with a synthetic cellParticleList.

Syntax

[vecPairIdxSource, vecPairIdxDest, scalNumPairs, scalMaxPairs] = ...
    findNeighbors3D(cellParticleList, scalNumCellsX, scalNumCellsY, scalNumCellsZ, ...
                    vecPairIdxSource, vecPairIdxDest, scalMaxPairs)

Arguments

Arg	Type	Meaning
cellParticleList	cell array [Nx x Ny x Nz]	cellParticleList{ix,iy,iz} = list of particle indices in that cell
scalNumCellsX	double	Number of cells along x
scalNumCellsY	double	Number of cells along y
scalNumCellsZ	double	Number of cells along z
vecPairIdxSource	[scalMaxPairs x 1]	Pre-allocated output buffer for source indices
vecPairIdxDest	[scalMaxPairs x 1]	Pre-allocated output buffer for destination indices
scalMaxPairs	double	Current capacity of the buffers

Outputs

Out	Meaning
vecPairIdxSource	Source (smaller) particle index of each candidate pair, first scalNumPairs entries
vecPairIdxDest	Destination (larger) particle index of each candidate pair, first scalNumPairs entries
scalNumPairs	Number of valid candidate pairs written
scalMaxPairs	Possibly-grown buffer capacity (doubled automatically if under-allocated)

If the buffers are too small the function doubles scalMaxPairs and extends the vectors. A 3x3x3 stencil with unique(...,'rows') removes the duplicate neighbor cells that occur when a box has only 2 cells along an axis, so neighbor pairs are never double-counted.

Example

% Build a synthetic cell list and find candidate pairs
Nx = Ny = Nz = 4;
cellParticleList = cell(Nx, Ny, Nz);
% ... fill cellParticleList{ix,iy,iz} with particle indices ...

scalNumPartTot = 100;
% Pre-allocate buffers (N*12 is the same heuristic pack.m uses)
vecPairIdxSource = zeros(scalNumPartTot*12, 1);
vecPairIdxDest   = zeros(scalNumPartTot*12, 1);

[vecPairIdxSource, vecPairIdxDest, scalNumPairs, ~] = ...
    findNeighbors3D(cellParticleList, Nx, Ny, Nz, ...
                    vecPairIdxSource, vecPairIdxDest, scalNumPartTot*12);

% The first scalNumPairs rows are the valid candidate pairs:
pairs = [vecPairIdxSource(1:scalNumPairs), vecPairIdxDest(1:scalNumPairs)];

This is a low-level building block used inside pack; you generally do not call it directly outside the cell-list integration loop or its unit tests.