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

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

Total release size: 38.1 MB

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

Download URL packlab-0.8.14-cp314-cp314-win_amd64.whl
Size 5.4 MB
Tags CPython 3.14 Windows x86-64
SHA-256 checksum
How to use checksums
1696b4e1373d3c4c31af634357e31c4522e36a3065ab59f91ee85ef6a1e018ae
BLAKE2b-256 checksum
How to use checksums
49c07919a949afaccc80eaa9f981646b8af77d9786ed379ccb388a7d1327f81c
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.14-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL packlab-0.8.14-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
207d05b5969e718269b55f0c087b229917750cf757e0cc4beb52b948d5a17805
BLAKE2b-256 checksum
How to use checksums
f29898aabd488a35473a121ab375792e7121d6fe8254bc74bf1173e446b0b4f9
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.14-cp314-cp314-macosx_26_0_arm64.whl

Download URL packlab-0.8.14-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
a2b3a9ecf5d381cb7a172082680e4d76cdc4971205a974c34338ab4bcd729b12
BLAKE2b-256 checksum
How to use checksums
0439bfeb3ecb04a6e7ffeb1a35cb16c302d657588898c4431bb582493993c3f8
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.14-cp313-cp313-win_amd64.whl

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

Download URL packlab-0.8.14-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
0a0ca4c2178b76850012dc1438d339691586035054242a364e33bb16364a369a
BLAKE2b-256 checksum
How to use checksums
9871bd65404cd4ed81caf7f62e66913feebfe82ad621c803660d724ba720e7e8
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.14-cp313-cp313-macosx_26_0_arm64.whl

Download URL packlab-0.8.14-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
b2c4b62e0fc06298150ffc8777282226dd196056eb4b64bd1b68884529887618
BLAKE2b-256 checksum
How to use checksums
37eafdcd35dd69b63697117c8b7c7953334fa259e80f35c9324a7ce2dd266695
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.14-cp312-cp312-win_amd64.whl

Download URL packlab-0.8.14-cp312-cp312-win_amd64.whl
Size 5.3 MB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
0b9b606000afd42b99821b3c3ec20385e48739662a19152c3d2ee392d19214aa
BLAKE2b-256 checksum
How to use checksums
43f91cfda933a753800608cd9593f6e7ab497e98280f9cb4004b5b45b7559ddd
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.14-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL packlab-0.8.14-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
2fd8ecebf69480099edbdd8f0e765d7ddd9f6ce300c5687472a22d869d9bce54
BLAKE2b-256 checksum
How to use checksums
39d5cf893862d8cacd20134f6de214ff6adf0261fb654409e3034ce156967c6e
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.14-cp312-cp312-macosx_26_0_arm64.whl

Download URL packlab-0.8.14-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
589b56d970a647017dd5e03eae612c2d5d63f4a84cf68efca0c9aed0f8f0a1af
BLAKE2b-256 checksum
How to use checksums
4184bd6c0749edd2845e16a04d5755c2cfdaa84621856cc0d4545a87c0cfd9d8
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.14-cp311-cp311-win_amd64.whl

Download URL packlab-0.8.14-cp311-cp311-win_amd64.whl
Size 5.2 MB
Tags CPython 3.11 Windows x86-64
SHA-256 checksum
How to use checksums
1b3842e27973827de33f40228b4f0b2e45f950691c23d7283cd9f1b422a657f2
BLAKE2b-256 checksum
How to use checksums
11da51e695224aa1932e5313b628273f8447ff516fd09703a8fc45a81801b494
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.14-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL packlab-0.8.14-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
ed51ca5335c9bbe640f58098fd539a35140beeb05ec7793658d62eb7ddce3da4
BLAKE2b-256 checksum
How to use checksums
bbb546954b029764cadd539a144971110b347856186d8a38151b41949b60e9c2
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.14-cp311-cp311-macosx_26_0_arm64.whl

Download URL packlab-0.8.14-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
c2783717b10572e5bcfd5f25d269d7e28e18ef7a8104416299cc6c62e8c86c0c
BLAKE2b-256 checksum
How to use checksums
baa149754ed1023043de6c8e51e61d4ea1b4aa94fe8cdd8f8c23e92b944d83cf
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.14

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