rebuildCellList3D

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

[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

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.