Skip to main content

PackLab logo - sphere packing and correlation curve.

PackLab

PackLab computes structure in three-dimensional hard-sphere systems. Its primary analytical workflow evaluates the Percus–Yevick (PY) approximation for equilibrium mixtures. It also generates explicit random sequential adsorption (RSA) configurations and samples fixed-volume equilibrium configurations with Metropolis Monte Carlo (MC).

Badge

Status

Python versions

Supported Python versions

Documentation

Documentation status

Continuous integration

Continuous integration status

Test coverage

Test coverage

PyPI package

PyPI version

PyPI downloads

Monthly PackLab downloads

Anaconda package

Anaconda version

Anaconda downloads

Anaconda downloads

Latest Anaconda release

Latest Anaconda release date

Citation

Cite PackLab on Zenodo

The workflows share physical inputs such as particle radii, number fractions, and volume fraction, but they answer different questions:

  • PY is a fast analytical equilibrium reference for pair correlations, structure factors, and structure-aware scattering calculations.

  • RSA creates an explicit, non-overlapping deposition configuration. It is irreversible and retains the history of accepted particles.

  • Metropolis MC moves particles in a valid configuration to sample an equilibrium hard-sphere system at fixed volume, particle count, and radii.

Installation

Install the core package from PyPI:

pip install packlab

For scattering calculations, install the optional PyMieSim integration:

pip install "packlab[scattering]"

Or install the Conda package:

conda install -c martinpdes packlab

Verify the compiled package with:

python -c "import PackLab; print(PackLab.__version__)"

1. Compute a Percus–Yevick equilibrium reference

Use PY when you need equilibrium mixture correlations without generating an explicit packing. PackLab computes the partial pair correlations \(g_{ij}(r)\) and reciprocal-space correlations on an automatically resolved wavenumber grid.

Partial pair correlations of a binary Percus--Yevick hard-sphere mixture.
import numpy as np

from PackLab import analytical, ureg

radii = np.array([75, 140]) * ureg.nanometer
domain = analytical.PercusYevickDomain(
    size=50 * ureg.micrometer,
    radii=radii,
    volume_fraction=0.25,
    number_fractions=np.array([0.7, 0.3]),
)
distances = np.linspace(0.0, 1.5, 300) * ureg.micrometer
result = analytical.PercusYevickSolver(
    densities=domain.particle_densities_per_radius,
    radii=domain.radii,
    wavenumber="auto",
).compute(distances)

g_12 = result.g[0, 1]
wavenumber = result.wavenumber

The automatic grid is a useful default. For a resolution study, use analytical.make_wavenumber_grid(...) and compare the resulting curves. PY is an analytical approximation to an equilibrium hard-sphere mixture; it does not create particle centres or reproduce the irreversible RSA process.

2. Generate an explicit RSA packing

RSA proposes particles one at a time and keeps only non-overlapping proposals. Accepted particles never move, so the final configuration is physically valid but history-dependent rather than an equilibrium sample.

Three-dimensional view of a periodic random sequential adsorption packing.
from PackLab import monte_carlo, samplers, ureg

domain = monte_carlo.PackingDomain(
    5 * ureg.micrometer,
    5 * ureg.micrometer,
    5 * ureg.micrometer,
    use_periodic_boundaries=True,
)
sampler = samplers.UniformRadiusSampler(
    90 * ureg.nanometer,
    170 * ureg.nanometer,
    bins=8,
)
options = monte_carlo.RSAOptions()
options.random_seed = 42
options.maximum_attempts = 40_000
options.target_packing_fraction = 0.12

rsa_result = monte_carlo.RSASimulator(domain, sampler, options).run()
print(rsa_result.statistics.packing_fraction_geometry)
figure = rsa_result.plot_packing_3d(show=False)

PackingResult provides accepted centres, sampled radii, packing statistics, pair-correlation estimators, and plotting helpers. The interactive 3D view shows whole spheres at their stored centres; periodic images are not drawn. Large packings can be slow to render. Radius samplers support constant, uniform, normal, log-normal, and discrete distributions.

3. Equilibrate hard spheres with Metropolis MC

Use Metropolis MC when an equilibrium configuration is needed. It can start from the valid RSA configuration above, but then proposes particle displacements; particle count, radii, and class labels remain fixed.

Three-dimensional view of a hard-sphere configuration after Metropolis Monte Carlo moves.
options = monte_carlo.MetropolisOptions()
options.random_seed = 34
options.number_of_sweeps = 500
options.maximum_displacement = 50 * ureg.nanometer

simulator = monte_carlo.MetropolisSimulator(
    domain,
    rsa_result.sphere_configuration,
    options,
)
mc_result = simulator.run()
print(simulator.statistics.acceptance_rate)
figure = mc_result.plot_packing_3d(show=False)

The number of sweeps alone does not establish equilibration. Discard an initial burn-in interval, assess autocorrelation for the quantity of interest, and compare larger systems when finite-size effects may matter.

Choosing the right workflow

Workflow

Use it when you need

Important limitation

PY analytical

Fast equilibrium pair correlations, structure factors, parameter sweeps, or scattering inputs.

It is an equilibrium approximation, not an explicit packing.

RSA

Particle centres, radius-sampling effects, deposition history, or a finite non-overlapping configuration.

It is irreversible and is not an equilibrium sampler.

Metropolis MC

An explicit equilibrium hard-sphere configuration at fixed volume and composition.

Equilibration, autocorrelation, and finite-size effects require checks.

Scattering

The optional PackLab.scattering workflow computes optical amplitudes with PyMieSim. Combine them with the PY correlation tensor when you need a structure-corrected mixture phase function. See the scattering examples for runnable single-particle and mixture calculations.

Documentation, validation, and citation

The online documentation contains theory, API reference, output conventions, assumptions, and executable galleries for PY, RSA, Metropolis MC, scattering, validation, and benchmarks.

For development:

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

If PackLab contributes to academic work, cite the archived Zenodo release you used. Release metadata is included in .zenodo.json.

Metadata

Release files for PackLab 0.8.20

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for PackLab 0.8.20
File Actions
packlab-0.8.20-cp314-cp314-win_amd64.whl CPython 3.14 CPython 3.14 Windows x86-64 Details for packlab-0.8.20-cp314-cp314-win_amd64.whl
packlab-0.8.20-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details for packlab-0.8.20-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
packlab-0.8.20-cp314-cp314-macosx_26_0_arm64.whl CPython 3.14 CPython 3.14 macOS 26.0+ ARM64 Details for packlab-0.8.20-cp314-cp314-macosx_26_0_arm64.whl
packlab-0.8.20-cp313-cp313-win_amd64.whl CPython 3.13 CPython 3.13 Windows x86-64 Details for packlab-0.8.20-cp313-cp313-win_amd64.whl
packlab-0.8.20-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details for packlab-0.8.20-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
packlab-0.8.20-cp313-cp313-macosx_26_0_arm64.whl CPython 3.13 CPython 3.13 macOS 26.0+ ARM64 Details for packlab-0.8.20-cp313-cp313-macosx_26_0_arm64.whl
packlab-0.8.20-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details for packlab-0.8.20-cp312-cp312-win_amd64.whl
packlab-0.8.20-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 Details for packlab-0.8.20-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
packlab-0.8.20-cp312-cp312-macosx_26_0_arm64.whl CPython 3.12 CPython 3.12 macOS 26.0+ ARM64 Details for packlab-0.8.20-cp312-cp312-macosx_26_0_arm64.whl
packlab-0.8.20-cp311-cp311-win_amd64.whl CPython 3.11 CPython 3.11 Windows x86-64 Details for packlab-0.8.20-cp311-cp311-win_amd64.whl
packlab-0.8.20-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details for packlab-0.8.20-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
packlab-0.8.20-cp311-cp311-macosx_26_0_arm64.whl CPython 3.11 CPython 3.11 macOS 26.0+ ARM64 Details for packlab-0.8.20-cp311-cp311-macosx_26_0_arm64.whl

Total release size: 38.3 MB

Release files / packlab-0.8.20-cp314-cp314-win_amd64.whl

Download URL packlab-0.8.20-cp314-cp314-win_amd64.whl
Size 5.5 MB
Tags CPython 3.14 Windows x86-64
SHA-256 checksum
How to use checksums
a047687bfc992dfba31f3a498292bbac0ec3d3e8a776e7f6831445a57abbf4bd
BLAKE2b-256 checksum
How to use checksums
6ce25122a01ed710659cbdc98e77c1a70602a26ed8e518b67bba59b808bb1cca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Release files / packlab-0.8.20-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL packlab-0.8.20-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 1.5 MB
Tags CPython 3.14 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
021d1ad305de8028ee3a49383508a396128e80ccc87c02eefbdea33b4b5b1ce7
BLAKE2b-256 checksum
How to use checksums
fc266472fab16c8cc2a120e93693edfee512e6e28683c27a9bb891edb1187e40
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Release files / packlab-0.8.20-cp314-cp314-macosx_26_0_arm64.whl

Download URL packlab-0.8.20-cp314-cp314-macosx_26_0_arm64.whl
Size 2.8 MB
Tags CPython 3.14 macOS 26.0+ ARM64
SHA-256 checksum
How to use checksums
705c4d628c3a776be763d11dd93de4cb746483d968f75dbfc86163e5a8332492
BLAKE2b-256 checksum
How to use checksums
af63a24e89c272abe4d5e1a2ac0e31e1576222ed799fb07ca890920fc60860b4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Release files / packlab-0.8.20-cp313-cp313-win_amd64.whl

Download URL packlab-0.8.20-cp313-cp313-win_amd64.whl
Size 5.3 MB
Tags CPython 3.13 Windows x86-64
SHA-256 checksum
How to use checksums
e4da28dbc3a3c363cc88cf6a8ab462cfde4892b1e29a61e99478095c5178a923
BLAKE2b-256 checksum
How to use checksums
b41ca582953f922984b7bfca0a607e9688a7a112937e46dc19478438efac660c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Release files / packlab-0.8.20-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL packlab-0.8.20-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 1.5 MB
Tags CPython 3.13 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
a0f6ca0b1284d94353b01e1fd6d81027826f21ea66365601ea4a2cad2d62a548
BLAKE2b-256 checksum
How to use checksums
c84f349b83e225557e66be041fa992e431aa57937c35085517fc026bb6db2b36
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Release files / packlab-0.8.20-cp313-cp313-macosx_26_0_arm64.whl

Download URL packlab-0.8.20-cp313-cp313-macosx_26_0_arm64.whl
Size 2.7 MB
Tags CPython 3.13 macOS 26.0+ ARM64
SHA-256 checksum
How to use checksums
088c46621908d4c55cdf3b3a454e2fa8fc7753b48a090fdb93736f69a47198a8
BLAKE2b-256 checksum
How to use checksums
5212cf9039bd41e5f6ad4280063a5aa47998828a260ba6a12e2920bb5e9456fe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Release files / packlab-0.8.20-cp312-cp312-win_amd64.whl

Download URL packlab-0.8.20-cp312-cp312-win_amd64.whl
Size 5.3 MB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
a201e444c02f780789bbeeca1a49edc442d5baecd137e05edb1c0f6101a8b05e
BLAKE2b-256 checksum
How to use checksums
93bce646631fdcd7a0858051a81e654fe959db19ae884aa7373bfc2fbddfd07d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Release files / packlab-0.8.20-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL packlab-0.8.20-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 1.5 MB
Tags CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
c996fd823962ae15ea3aa4cb84e73824cad8979b0bdd97c2074a6ef6548a5050
BLAKE2b-256 checksum
How to use checksums
7a4541cde31d104847519263ba1244f4c1a7b19d4e29c7cda4f6e01a8bdbf9c3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Release files / packlab-0.8.20-cp312-cp312-macosx_26_0_arm64.whl

Download URL packlab-0.8.20-cp312-cp312-macosx_26_0_arm64.whl
Size 2.7 MB
Tags CPython 3.12 macOS 26.0+ ARM64
SHA-256 checksum
How to use checksums
adbb5786c68a508e93fdcd9286c50a3dadc6956fbebc45eb5dd72906f82f509d
BLAKE2b-256 checksum
How to use checksums
64509e5bcd1442452a2ca5e720c00a29c9fa876d93c920e384586f48937ca059
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Release files / packlab-0.8.20-cp311-cp311-win_amd64.whl

Download URL packlab-0.8.20-cp311-cp311-win_amd64.whl
Size 5.2 MB
Tags CPython 3.11 Windows x86-64
SHA-256 checksum
How to use checksums
307b61356ddbb9e8712ac45af28e4ebe70167ec1c1602f9101899c67d5d76f8d
BLAKE2b-256 checksum
How to use checksums
24de43fd3519ae9ed21bd1bfedb01df6364edb9dc05509cdf360560d8d761da6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Release files / packlab-0.8.20-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL packlab-0.8.20-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 1.5 MB
Tags CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
e0a37d1fe905a0445248533b03c7ea72933a9acf52dc519a539fe40bda42cfe8
BLAKE2b-256 checksum
How to use checksums
b127a2eef37b14f5b9d83bf392f06df85778c2e6c91a4370c086f9b546626083
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Release files / packlab-0.8.20-cp311-cp311-macosx_26_0_arm64.whl

Download URL packlab-0.8.20-cp311-cp311-macosx_26_0_arm64.whl
Size 2.7 MB
Tags CPython 3.11 macOS 26.0+ ARM64
SHA-256 checksum
How to use checksums
eab44d03ed428ba59c6b68a8728dd587b4e2703efa04b6f06c1023b4b9092c47
BLAKE2b-256 checksum
How to use checksums
4fb10167c300fc010a5fa44d73710c771527e0bc5bb22923b890762e336f0f39
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Security for PackLab 0.8.20

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.8.20 This release

12 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page