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

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.12
File Actions
packlab-0.8.12-cp314-cp314-win_amd64.whl CPython 3.14 CPython 3.14 Windows x86-64 Details for packlab-0.8.12-cp314-cp314-win_amd64.whl
packlab-0.8.12-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.12-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
packlab-0.8.12-cp314-cp314-macosx_26_0_arm64.whl CPython 3.14 CPython 3.14 macOS 26.0+ ARM64 Details for packlab-0.8.12-cp314-cp314-macosx_26_0_arm64.whl
packlab-0.8.12-cp313-cp313-win_amd64.whl CPython 3.13 CPython 3.13 Windows x86-64 Details for packlab-0.8.12-cp313-cp313-win_amd64.whl
packlab-0.8.12-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.12-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
packlab-0.8.12-cp313-cp313-macosx_26_0_arm64.whl CPython 3.13 CPython 3.13 macOS 26.0+ ARM64 Details for packlab-0.8.12-cp313-cp313-macosx_26_0_arm64.whl
packlab-0.8.12-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details for packlab-0.8.12-cp312-cp312-win_amd64.whl
packlab-0.8.12-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.12-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
packlab-0.8.12-cp312-cp312-macosx_26_0_arm64.whl CPython 3.12 CPython 3.12 macOS 26.0+ ARM64 Details for packlab-0.8.12-cp312-cp312-macosx_26_0_arm64.whl
packlab-0.8.12-cp311-cp311-win_amd64.whl CPython 3.11 CPython 3.11 Windows x86-64 Details for packlab-0.8.12-cp311-cp311-win_amd64.whl
packlab-0.8.12-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.12-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
packlab-0.8.12-cp311-cp311-macosx_26_0_arm64.whl CPython 3.11 CPython 3.11 macOS 26.0+ ARM64 Details for packlab-0.8.12-cp311-cp311-macosx_26_0_arm64.whl

Total release size: 38.1 MB

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

Download URL packlab-0.8.12-cp314-cp314-win_amd64.whl
Size 5.4 MB
Tags CPython 3.14 Windows x86-64
SHA-256 checksum
How to use checksums
c16835981ecc6b0d9739ffedde6f60940c698509da64cd57da05e82225c4d9de
BLAKE2b-256 checksum
How to use checksums
15dfffeb41932a0a7ab0b8b3c9f53130ceb7f83713b8e1bf26039c589fef93b5
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.12-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL packlab-0.8.12-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
bf26889adda8a1d0a40e3b318379c9880508ee207fe0a9ca4cba199744127536
BLAKE2b-256 checksum
How to use checksums
33f47e98fc5985dfdd1ff0d60594ed72850e474e8dd271ca85655c77b0b27298
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.12-cp314-cp314-macosx_26_0_arm64.whl

Download URL packlab-0.8.12-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
a66f64a522fa1e14ce786a2ab518510a42e99dd426528dcc299962cd83330be2
BLAKE2b-256 checksum
How to use checksums
2de76883e1356ca1a32f6c51d63735b404bedb6b1bd74e3f5acfbf1696999d13
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.12-cp313-cp313-win_amd64.whl

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

Download URL packlab-0.8.12-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
57c310e6851f7f9c6c8972de0a912d43206d32ca36fff10b9badcc84388bee4f
BLAKE2b-256 checksum
How to use checksums
c45655b00f6e41bb3547adb71146bd90d631f8f9655c34e011ca8fb9e17b8cca
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.12-cp313-cp313-macosx_26_0_arm64.whl

Download URL packlab-0.8.12-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
e24321cf5df6f64a96e5fdb78510ea1216ef0f3f1c4d781d000cbd9ee072bc88
BLAKE2b-256 checksum
How to use checksums
c19d92e80802d6522d205fb4d6690d2250f63c87fdb54b80c7900aafa60aecb1
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.12-cp312-cp312-win_amd64.whl

Download URL packlab-0.8.12-cp312-cp312-win_amd64.whl
Size 5.3 MB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
69d266ac4d5ca398e3bfe8ae30f60c70e8fee972f0596331178e47fcc1d66bdc
BLAKE2b-256 checksum
How to use checksums
fb019c88289a6836fefe7614931c89c310f6fd730ff845ca0c7bbe1b947ebe67
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.12-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL packlab-0.8.12-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
e8d6c2b12f748dfc6d998583a01c4a4d2d7d025ff99ff639dcae873497908af2
BLAKE2b-256 checksum
How to use checksums
819183de9e74d48ccfc01d3cb21d0fd2eb2941225d9b2d26a9feb8625ca56c88
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.12-cp312-cp312-macosx_26_0_arm64.whl

Download URL packlab-0.8.12-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
5d2fe71a67d98a9454b1bc88edb2fd6f79d687d0e928fa620122d06c9cb38a92
BLAKE2b-256 checksum
How to use checksums
a106f204ce89bffb509bc66cae2466e47293658f7e905a27ab2748c4fd4ffed8
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.12-cp311-cp311-win_amd64.whl

Download URL packlab-0.8.12-cp311-cp311-win_amd64.whl
Size 5.2 MB
Tags CPython 3.11 Windows x86-64
SHA-256 checksum
How to use checksums
8ad0e8cf90d6ef47e23f9e5e9f938c947ae298bf5c40adf03c4b3a280c07bf44
BLAKE2b-256 checksum
How to use checksums
682c8f102d72ce7e13163f46c21c6552b38d0fb0b05b45250923696a0747552b
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.12-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL packlab-0.8.12-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
029a22be1bcb488cc71b9662cd70c9b1e2f29004816fd26378ae049a72116dc3
BLAKE2b-256 checksum
How to use checksums
601231266c695268eff4340d46012350a74040ba6e79b903526d105b03be394c
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.12-cp311-cp311-macosx_26_0_arm64.whl

Download URL packlab-0.8.12-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
b5930dfac70c61b30454a5f4ee37749b740693f625a4723ce5342762c5d513aa
BLAKE2b-256 checksum
How to use checksums
05b457af8dba883dda1d4b95c0bd0403982785dfbc87ccd069f5f1b2da690aa4
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.12

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