Date: May 01, 2026, Version: 0.0.19

Meta
Testing
PyPI
Anaconda

PackLab#

PackLab is a fast Random Sequential Addition (RSA) particle packing library with a C plus plus core and Python bindings. It helps you generate non overlapping sphere configurations inside a 3D box with optional periodic boundaries. It supports mono disperse and poly disperse radius sampling through a flexible sampling interface.

Features#

Fast C++ implementation with Python bindings
3D box domain with optional periodic boundaries
Configurable stopping criteria: maximum attempts, maximum consecutive rejections, target packing fraction, maximum spheres
Radius samplers designed for future extension to poly disperse systems
Python level convenience API with plotting utilities and summary statistics

Installation#

From PyPI:

pip install packlab

From conda:

conda install -c martinpdes packlab

From source:

git clone https://github.com/MartinPdeS/PackLab.git
cd PackLab
pip install -e .[testing]

Quick start#

 from PackLab import Domain, Options, Simulator, UniformRadiusSampler

 domain = Domain(
     length_x=6.0,
     length_y=6.0,
     length_z=6.0,
     use_periodic_boundaries=True
 )

 radius_sampler = UniformRadiusSampler(
     minimum_radius=0.1,
     maximum_radius=0.4
 )

 options = Options()
 options.random_seed = 42
 options.maximum_attempts = 4_000_000
 options.maximum_consecutive_rejections = 80_000
 options.target_packing_fraction = 0.55
 options.minimum_center_separation_addition = 0.0

 rsa_simulator = Simulator(
     domain=domain,
     radius_sampler=radius_sampler,
     options=options
 )

 result = rsa_simulator.run()

 result.statistics.print()

 result.plot_slice_2d()

 result.plot_pair_correlation(maximum_number_of_pairs=3_000_000)

import PackLab

Testing#

To test locally, clone the repository, install dependencies, and run pytest.

git clone https://github.com/MartinPdeS/PackLab.git
cd PackLab
pip install -e .[testing]
pytest

Documentation#

The documentation includes tutorials, API reference, and gallery examples.

See .

Contributing#

Issues and pull requests are welcome. If you are using PackLab in research, citations and links to your work are appreciated.

Contact Information#

As of 2025, the project is still under development. If you want to collaborate, it would be a pleasure. Feel free to contact me.

PackLab was written by Martin Poinsinet de Sivry Houle.

Email: martin.poinsinet.de.sivry@gmail.com.