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.19

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.19
File Actions
packlab-0.8.19-cp314-cp314-win_amd64.whl CPython 3.14 CPython 3.14 Windows x86-64 Details for packlab-0.8.19-cp314-cp314-win_amd64.whl
packlab-0.8.19-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.19-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
packlab-0.8.19-cp314-cp314-macosx_26_0_arm64.whl CPython 3.14 CPython 3.14 macOS 26.0+ ARM64 Details for packlab-0.8.19-cp314-cp314-macosx_26_0_arm64.whl
packlab-0.8.19-cp313-cp313-win_amd64.whl CPython 3.13 CPython 3.13 Windows x86-64 Details for packlab-0.8.19-cp313-cp313-win_amd64.whl
packlab-0.8.19-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.19-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
packlab-0.8.19-cp313-cp313-macosx_26_0_arm64.whl CPython 3.13 CPython 3.13 macOS 26.0+ ARM64 Details for packlab-0.8.19-cp313-cp313-macosx_26_0_arm64.whl
packlab-0.8.19-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details for packlab-0.8.19-cp312-cp312-win_amd64.whl
packlab-0.8.19-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details for packlab-0.8.19-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
packlab-0.8.19-cp312-cp312-macosx_26_0_arm64.whl CPython 3.12 CPython 3.12 macOS 26.0+ ARM64 Details for packlab-0.8.19-cp312-cp312-macosx_26_0_arm64.whl
packlab-0.8.19-cp311-cp311-win_amd64.whl CPython 3.11 CPython 3.11 Windows x86-64 Details for packlab-0.8.19-cp311-cp311-win_amd64.whl
packlab-0.8.19-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.19-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
packlab-0.8.19-cp311-cp311-macosx_26_0_arm64.whl CPython 3.11 CPython 3.11 macOS 26.0+ ARM64 Details for packlab-0.8.19-cp311-cp311-macosx_26_0_arm64.whl

Total release size: 38.1 MB

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

Download URL packlab-0.8.19-cp314-cp314-win_amd64.whl
Size 5.4 MB
Tags CPython 3.14 Windows x86-64
SHA-256 checksum
How to use checksums
cd532ce55bae22326c5fefc488512fe1f4463364dd96e29e4ba460782b28f0d8
BLAKE2b-256 checksum
How to use checksums
c575b9aafa6ff0806e338a3f21461caa0d8360b0469d59943f18285641449f4b
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.19-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL packlab-0.8.19-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
9c2c18fe39fd136f375d27f57fca4bc7d673b4b1a6f09a77a4be459d7bbececa
BLAKE2b-256 checksum
How to use checksums
f7469f06e7da0e458bdb96f10146089631efaad433846dca386af0100dec67d7
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.19-cp314-cp314-macosx_26_0_arm64.whl

Download URL packlab-0.8.19-cp314-cp314-macosx_26_0_arm64.whl
Size 2.7 MB
Tags CPython 3.14 macOS 26.0+ ARM64
SHA-256 checksum
How to use checksums
4f86a6bbe41a3cfd24cfc238f567564069ca1417b492b18fd85fc962785f904a
BLAKE2b-256 checksum
How to use checksums
1ec405a4cbaf5c5f74bc2812eccc3438b95279846a50cc7473fe2d2a334ba285
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.19-cp313-cp313-win_amd64.whl

Download URL packlab-0.8.19-cp313-cp313-win_amd64.whl
Size 5.3 MB
Tags CPython 3.13 Windows x86-64
SHA-256 checksum
How to use checksums
fd3bfc01fcac3e7330816a0236625f4bf1f590556ceb74f6982ab1ed87155085
BLAKE2b-256 checksum
How to use checksums
b8d43266891c001193a8309179aad83ac52cea8df6a995b2c7e9d730835ee368
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.19-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL packlab-0.8.19-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
0ae86fa82253f8987d2d36859775631decad121772e5c555e34449e9934afd9f
BLAKE2b-256 checksum
How to use checksums
649e004484d2845530fcd41d0b514f0eb440e1bb615ba442b388fa5f1cab6093
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.19-cp313-cp313-macosx_26_0_arm64.whl

Download URL packlab-0.8.19-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
fe2183d6428adac874404ce25350d1e7e71fa4e5897bf1c7227d93c7ad4aff5e
BLAKE2b-256 checksum
How to use checksums
8f7f49fc37e2f4f6cda0618973130fde1d51077c43138d4b94519b19ae26fa2f
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.19-cp312-cp312-win_amd64.whl

Download URL packlab-0.8.19-cp312-cp312-win_amd64.whl
Size 5.3 MB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
f00ee87c71ac5229a41f3e592e8cc7ba62887b60b2e7c26d12887926dc5f46d2
BLAKE2b-256 checksum
How to use checksums
8604c95bec01ea0e3142ca566e9784149608fb7388e72f52d5ff4aca1cef8522
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.19-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL packlab-0.8.19-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
30bba40b2428339087d1a3fad56e2bc42385aaa151ac8aa818386c5af92a731e
BLAKE2b-256 checksum
How to use checksums
c5d18e91f83fc7a6a0164838bda017587ecab16e236b0b1794eb714eac47061a
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.19-cp312-cp312-macosx_26_0_arm64.whl

Download URL packlab-0.8.19-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
2fd9d6e4e4c7a4a93c7196606b308ea62a30790f84f99936a64d9edcc82e980f
BLAKE2b-256 checksum
How to use checksums
adf2008d0df3128bda810d892fb108901c5ca4de0183baf9009a9dd0b9ea5101
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.19-cp311-cp311-win_amd64.whl

Download URL packlab-0.8.19-cp311-cp311-win_amd64.whl
Size 5.2 MB
Tags CPython 3.11 Windows x86-64
SHA-256 checksum
How to use checksums
821e5f8cf9ae87f301e76a8324823141338bfc627f360959e5729dc1c85275bb
BLAKE2b-256 checksum
How to use checksums
60041e458bcc63bec2dde41c08041306a9975ec6c757c72619c0f156cbdad905
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.19-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL packlab-0.8.19-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
755c884fae890a765e5d7771a438cb396517b62d6c919d228dbe00ce8fa5cf04
BLAKE2b-256 checksum
How to use checksums
63020d49c60161fc84603eca199930e5b11d7da3c62dc63aa3bd025f43e94394
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.19-cp311-cp311-macosx_26_0_arm64.whl

Download URL packlab-0.8.19-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
f68f38636cef811e79aa8d568bf9ed7fc0e3fb54da96b77534c92d90d3c2e8b4
BLAKE2b-256 checksum
How to use checksums
b8ac06e17af58b7d8c3484bc58815d951495864c05c389a844abc09eb073c005
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.19

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.19 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