PackLab 0.1.0

Random Sequential Addition (RSA) particle packing with a fast C++ core.

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: [e-mail].