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.

Two-dimensional slice through 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_slice_2d(show=False)

PackingResult provides accepted centres, sampled radii, packing statistics, pair-correlation estimators, and plotting helpers. 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.

Two-dimensional slice 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_slice_2d(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.13

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

Total release size: 38.1 MB

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

Download URL packlab-0.8.13-cp314-cp314-win_amd64.whl
Size 5.4 MB
Tags CPython 3.14 Windows x86-64
SHA-256 checksum
How to use checksums
7c6c99ad9c012218b5cfee5ce2f84c20f8d20d9a0a3c61c9140ef567315795cc
BLAKE2b-256 checksum
How to use checksums
1c3473d84f5f38f00ecad7110f493205ac95caaf27666a2c20d30b2172b48bfd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

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

Download URL packlab-0.8.13-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
9c655f2a30c30e527802be37424b0bf9ed35f06f499bfcc8800266d00bba4665
BLAKE2b-256 checksum
How to use checksums
532af9e3d780ebd20e301fe6650563fa60d936d6c500a3770b997def5119e3f0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

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

Download URL packlab-0.8.13-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
e9951eb289ef8fe7b004d605ae5c27136bda0d78ec46ef12fb2a86e3bbcd8523
BLAKE2b-256 checksum
How to use checksums
bbf03bed29722fdab2e0d03ffddf2f7daa08d09f7d04e4ea424a75d2edb904a9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

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

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

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

Download URL packlab-0.8.13-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
f9ad96fae75e525cdcc3311b441d94ba40ffd3b963e7724c01a428943cb63230
BLAKE2b-256 checksum
How to use checksums
cc7548470e6b8f9eeba5e94b85398f4b408ed9f2b4cd9513e2e941896a0eee3e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

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

Download URL packlab-0.8.13-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
628b6a8a2c47630ca6a902df1dcc1017bc90a6a0524ed8773f5c193d60bed4c2
BLAKE2b-256 checksum
How to use checksums
353f620e29e68a80fcfb20bd931c20ef428655aacb0aafcc06d0ee2ebc478534
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

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

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

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

Download URL packlab-0.8.13-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
dea80991a71d18c818833bf4fd982879219aa54ac21894bc5f73b558909a4610
BLAKE2b-256 checksum
How to use checksums
e298b25de9162f3c58e5aaa58128795cf90e0924984d4ebf174654429b40dd23
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

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

Download URL packlab-0.8.13-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
ba47602ef592d25cc4b606bee823c77d174475044ac693e7c2caa04be9057171
BLAKE2b-256 checksum
How to use checksums
38174300de246590a664505c1052cec280a52bf98cf62cff1b553e4ff5d28a3f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

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

Download URL packlab-0.8.13-cp311-cp311-win_amd64.whl
Size 5.2 MB
Tags CPython 3.11 Windows x86-64
SHA-256 checksum
How to use checksums
3fc7be2e19774eca1cba39ed4467fd6bebd694e161a245caa148dfd6725b3f1c
BLAKE2b-256 checksum
How to use checksums
52aff3039264d612c4dc0cca972676ea12f87e35c4c61a3e94c6d241a09eb93b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

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

Download URL packlab-0.8.13-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
015d4f2778fdd40ee609f4e66c559755db5f1349ffa34040da20393bfc7e157a
BLAKE2b-256 checksum
How to use checksums
e91217ab43de72be49e6eed865a93a5d37dc49714b5dc973a7c587da6de6acd1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

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

Download URL packlab-0.8.13-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
6e2b65283f62737527657729f34927718dbbc999dadf7805105c54575a565e86
BLAKE2b-256 checksum
How to use checksums
0754817c0e06c02a17bb28d121fd0df2cee711466af391965be613dcab3a6aba
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.17

Security for PackLab 0.8.13

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