spheropack.pack

spheropack.pack(n=None, radii=None, container=None, *, density=None, growth_rate=0.02, stop=None, seed=None, strict=False, collision_rule='elastic_growing')

Packs spheres (disks in 2D) with the Lubachevsky-Stillinger algorithm.

The spheres start as points at random positions with Maxwell-Boltzmann velocities, move ballistically, collide, and grow at a constant rate until the target density is reached or a stopping criterion fires.

Parameters:

• n (int | None) – Number of spheres. Needed when radii is a scalar or omitted.

• radii (float | Sequence[float] | ndarray | None) – One radius for all spheres, or one per sphere. With density given, only the ratios matter: all radii are scaled by a common factor. Default: equal radii (then density is required).

• container (Box | None) – Where to pack. Default: the periodic unit cube.

• density (float | Literal['max'] | None) – None: grow until the spheres have the given radii. A number: grow until this volume (area) fraction. "max": no target; grow until an arrest criterion in stop fires (jamming or crystallisation).

• growth_rate (float) –

  Dimensionless growth rate

  \[\Gamma = \frac{1}{v_\mathrm{th}}\frac{\mathrm{d}\langle d\rangle}{\mathrm{d}t},\]

  where \(\langle d\rangle\) is the arithmetic mean diameter and \(v_\mathrm{th} = \sqrt{k_BT/m}\) the thermal speed (the standard deviation of one velocity component; all spheres have the same mass). While a sphere moving at \(v_\mathrm{th}\) travels one mean diameter, the mean diameter grows by the fraction \(\Gamma\). Jammed packings of equal spheres in 3D reach 0.634 to 0.650 for \(\Gamma\) from 0.3 down to 0.001 (0.64 at the default); slower growth gives denser, more ordered packings, and below about 0.001 equal spheres start to crystallise. The run time grows roughly as \(1/\Gamma\) for slow growth. See the user guide page on the growth rate.

• stop (Criterion | Iterable[Criterion] | None) – Stopping criteria from spheropack.stop; the first that fires ends the run. Default: [Jammed()] for density="max", otherwise [Pressure(1e6)] (stop early if the spheres jam before the target).

• seed (int | None) – Random seed. None draws one; it is stored in the result.

• strict (bool) – Raise PackingError instead of warning when the run fails: the target density was not reached, or with density="max" no arrest criterion fired.

• collision_rule (Literal['elastic_growing', 'legacy']) – "elastic_growing" (default): collisions are elastic in the frame of the growing surfaces, which gives jammed packings with a well-defined contact network. "legacy": the rule of the original code, which can trap clusters of spheres in endless collisions near jamming.

Returns:

Positions, radii and run statistics; status says why the run stopped.

Return type:

Packing