# rebuildCellList3D

Re-buckets 3D particle positions into a periodic cell list every time the
particles move. Wraps the positions into `[0, L)`, maps each one to its
cell, and returns the updated cell array plus the number of cells per axis.
Extracted from `pack.m` (it was a local subfunction) so it can be unit-tested
directly with synthetic positions.

## Syntax

```matlab
[vecPosX, vecPosY, vecPosZ, cellParticleList, scalNumCellsX, scalNumCellsY, scalNumCellsZ] = ...
    rebuildCellList3D(vecPosX, vecPosY, vecPosZ, scalBoxWidthX, scalBoxHeightY, scalBoxDepthZ, ...
                      scalRawCellWidth, scalTimestep, N)
```

## Arguments

| Arg | Type | Meaning |
|---|---|---|
| `vecPosX` | `[N x 1]` | x-positions (possibly outside `[0,L)`) |
| `vecPosY` | `[N x 1]` | y-positions |
| `vecPosZ` | `[N x 1]` | z-positions |
| `scalBoxWidthX` | double | Box extent in x |
| `scalBoxHeightY` | double | Box extent in y |
| `scalBoxDepthZ` | double | Box extent in z |
| `scalRawCellWidth` | double | Desired (raw) cell width; the actual grid is `round(L / scalRawCellWidth)` cells per axis |
| `scalTimestep` | double | Current timestep (only used in the error message if a particle moved too far) |
| `N` | double | Number of particles |

## Outputs

| Out | Meaning |
|---|---|
| `vecPosX, vecPosY, vecPosZ` | Positions wrapped into `[0, L)` |
| `cellParticleList` | Cell array `[Nx x Ny x Nz]`; `{ix,iy,iz}` lists the particle indices in that cell (column-major, x fastest) |
| `scalNumCellsX/Y/Z` | Number of cells along each axis |

Errors out if any particle moved more than one box length in a single timestep
(a sign the timestep is too large).

## Example

```matlab
N = 6;
vecX = [0.5, 2.5, 7.5, 0.5, 5.5, 0.5]';
vecY = [1.5, 4.5, 10.5, 1.5, 7.5, 1.5]';
vecZ = [1.5, 4.5, 10.5, 1.5, 7.5, 1.5]';
scalBox = 12;              % box is 12 on each side
scalRawCellWidth = 3;      % -> round(12/3) = 4 cells per axis

[vecXw, vecYw, vecZw, cellParticleList, nX, nY, nZ] = ...
    rebuildCellList3D(vecX, vecY, vecZ, scalBox, scalBox, scalBox, ...
                      scalRawCellWidth, 0.01, N);

% nX == nY == nZ == 4; cellParticleList{ix,iy,iz} holds the particle indices
```

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