cleanRats

cleanRats

Removes rattlers (unstable particles) from a packing by iterative contact counting. In each pass it recomputes the wall lists and the per-particle coordination number Zn (number of overlapping neighbors, with periodic minimum-image distances), drops every particle below the isostatic coordination threshold, and repeats until the set is stable.

Removal threshold (Zn must be greater than it to survive):

Case	Keep
2D, frictionless	Zn > 2
3D (any friction)	Zn > 3
Frictional (mu > 0)	Zn > 1

Physics (Maxwell counting, 2D disks): frictionless isostatic z_iso = 4, frictional z_iso = 3. A particle with Zn <= 1 cannot satisfy force–torque balance in this gravity-free isotropic packing, so it is a rattler even with friction; the frictional variant therefore keeps Zn >= 2 backbone grains and removes floaters plus one-contact rattlers.

Default Syntax

% 2D, PBC in y only, frictionless
[positions, radii] = cleanRats(positions, radii, Ly, Lx)

% 3D, PBC in y and z, frictionless
[positions, radii] = cleanRats(positions, radii, Ly, Lx, Lz)

Full Argument List

[positions, radii] = cleanRats(positions, radii, Ly, Lx, Lz, boolFullyPeriodic, mu)

Arg	Type	Meaning
positions	[N x 2] or [N x 3]	Particle positions (x, y[, z])
radii	[N x 1]	Particle radii
Ly	double	Box extent in y (PBC applied in y always)
Lx	double	Box extent in x
Lz	double or []	Box extent in z; pass [] for a 2D call
boolFullyPeriodic	logical	3D only: apply PBC in x as well as y/z. 2D: ignored (no x-PBC). Defaults false when omitted
mu	double	Friction coefficient; > 0 switches to the frictional threshold (Zn > 1). Defaults 0

All existing callers omit mu (so the frictionless behavior is unchanged). The returned positions/radii contain only the surviving backbone particles.

Examples

% 2D packing, periodic in y only
positions = [x; y]';   % N x 2
radii = Dn / 2;
[positions, radii] = cleanRats(positions, radii, Ly, Lx);

% 2D packing, fully periodic in x and y
[positions, radii] = cleanRats(positions, radii, Ly, Lx, [], true);

% 3D packing, fully periodic
[positions, radii] = cleanRats(positions, radii, Ly, Lx, Lz, true);

% Frictional 2D (mu > 0) — keeps Zn >= 2, removes floaters + 1-contact rattlers
[positions, radii] = cleanRats(positions, radii, Ly, Lx, [], false, 0.5);

pack and processEigenModesDampedPara call this internally; you normally do not call it directly unless cleaning a packing you generated elsewhere.