# 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

```matlab
[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

```matlab
% 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.