spheropack
Random sphere packings in Python, generated with the event-driven Lubachevsky-Stillinger algorithm: spheres move ballistically, collide and grow until a target density is reached or the packing jams or crystallises.
import spheropack as sp
p = sp.pack(n=1000, density=0.6, seed=1) # target volume fraction
q = sp.pack(n=1000, density="max", seed=1) # until jammed (isostatic within a few %)
q.positions, q.radii, q.density, q.status
q.to_csv("packing.csv")
- Periodic boxes, flat walls (slabs, closed boxes), cylinders (packed tubes), spherical containers and disks; 2D and 3D; mono- and polydisperse.
- A fast, exact C++20 event-driven core (header-only, no dependencies) with a nanobind Python interface. The GIL is released and Ctrl-C works.
- A well-defined, dimensionless growth rate and composable stopping criteria, including a quasi-static jamming protocol.
- Structure analysis: pair distribution function, contact numbers, rattlers (from the collision forces), isostaticity, Steinhardt bond order, crystallinity, density profiles next to walls, radial porosity profiles in tubes.
- A command-line tool, including drop-in replacements of the legacy
generate_periodic_packingandgenerate_packed_tube.
spheropack.rejection_free provides the rejection-free, event-driven Monte Carlo method
of E.A.J.F. Peters and G. de With, Rejection-free Monte Carlo sampling for general
potentials, Phys. Rev. E 85, 026703 (2012), for Lennard-Jones, WCA, DPD, soft and
hard spheres.
Status: alpha. See the roadmap.
Installation
pip install spheropack
Wheels are available for Linux, macOS and Windows (Python 3.10 and newer). Building
from source needs a C++20 compiler and CMake 3.18 or newer: pip install .
Optional extras: pip install "spheropack[plot]" for the matplotlib helpers.
Documentation
https://computational-chemical-engineering.github.io/spheropack: user guide, example
notebooks, Python and C++ reference. To build it locally from docs/:
pip install sphinx pydata-sphinx-theme myst-nb breathe sphinx-copybutton sphinxcontrib-bibtex matplotlib
cd docs && sphinx-build -b html . _build/html
Citing
If you use spheropack, please cite it (see CITATION.cff); for the rejection-free Monte Carlo method, cite Peters and de With (2012).
Contributing
See CONTRIBUTING.md. Bug reports and feature requests are welcome as issues.
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for spheropack 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| spheropack-0.2.0.tar.gz | 169.6 kB | Details |
Built distributions (wheels)
Total release size: 3.2 MB
Release files / spheropack-0.2.0.tar.gz
| Download URL | spheropack-0.2.0.tar.gz |
|---|---|
| Size | 169.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7a69fcb9506ebaae86d390ba0b46e4f74a541230cf1c8050b5b73091eef51001
|
|
BLAKE2b-256 checksum How to use checksums |
9a86ad43adc07832460e12d543b82c4fedc8c13dce680df04e0007972e41e00f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / spheropack-0.2.0-cp312-abi3-win_amd64.whl
| Download URL | spheropack-0.2.0-cp312-abi3-win_amd64.whl |
|---|---|
| Size | 197.6 kB |
| Tags | CPython 3.12 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
950bef58b2697931480e1657dfaa3c87787db8390df3074aba1efe6cf6667374
|
|
BLAKE2b-256 checksum How to use checksums |
a5b3b143c516068cdfab916de7fceca06080e638a17da1482768df5a55496783
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / spheropack-0.2.0-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | spheropack-0.2.0-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 236.5 kB |
| Tags | CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
33cc122abaf3ec85a48a2f2dd379f9d70c3d460cd821a1c094353e26279e17c1
|
|
BLAKE2b-256 checksum How to use checksums |
084b9c700ecd8fbf439274f12ddc1404799c5fcc8168759b6e02926b1538892c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / spheropack-0.2.0-cp312-abi3-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
| Download URL | spheropack-0.2.0-cp312-abi3-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 219.0 kB |
| Tags | CPython 3.12 Linux glibc 2.27+ ARM64 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
3e2ad52502adbc24b4db0ae35db8ccec513f6cf78871614a66f33f533d6a5104
|
|
BLAKE2b-256 checksum How to use checksums |
59b37404c7f8e117390b7bc89d477f2e7fd4d0c07ab4fe7f07bf39a89d0e35d9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / spheropack-0.2.0-cp312-abi3-macosx_11_0_arm64.whl
| Download URL | spheropack-0.2.0-cp312-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 175.6 kB |
| Tags | CPython 3.12 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
f2210d1975451bc2df2ffca4bb923d3fb4c255d41b294887cc67cd8765aa9350
|
|
BLAKE2b-256 checksum How to use checksums |
26b0a4fffa633ef04fd0f760f3f98fbe52e9ceeaec9e753c887e8232e4df165c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / spheropack-0.2.0-cp312-abi3-macosx_10_15_x86_64.whl
| Download URL | spheropack-0.2.0-cp312-abi3-macosx_10_15_x86_64.whl |
|---|---|
| Size | 187.5 kB |
| Tags | CPython 3.12 abi3 macOS 10.15+ x86-64 |
|
SHA-256 checksum How to use checksums |
c0a7a3835d7b393deebb36389ee0c9c002ffce5c6c8853de24b4b016cfa91c2f
|
|
BLAKE2b-256 checksum How to use checksums |
11b75062e54e0132a36271c33bd02935688d95346d0e11b2a90326c38289b460
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / spheropack-0.2.0-cp311-cp311-win_amd64.whl
| Download URL | spheropack-0.2.0-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 198.1 kB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
411f1adf405a4f0f8acd60ec97249057a7a0ed8ad91a2c35ffc96b1457732c3e
|
|
BLAKE2b-256 checksum How to use checksums |
db0395351b4e281cbd4612e1a4fff36e56d6cf1637b783f261d5d663ff7edab5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / spheropack-0.2.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | spheropack-0.2.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 240.3 kB |
| Tags | CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
a0c37e4aec8921c169d16590b309fd9037965115888eb3523cda9b49e9b5f3f8
|
|
BLAKE2b-256 checksum How to use checksums |
ba0a5e6b324c843eebb681fb997d26de02c5b0e91ef1dae517a9b1aa156fbfc0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / spheropack-0.2.0-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
| Download URL | spheropack-0.2.0-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 222.9 kB |
| Tags | CPython 3.11 Linux glibc 2.27+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
982022b48c8b8badfbf85b567fcb718ec354fa18f42cb0c9cbc951d76fc151ac
|
|
BLAKE2b-256 checksum How to use checksums |
4ddddbe6b380bae17280fc1429939de35cdd5696f3b1571c1ffd94862d03a44a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / spheropack-0.2.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | spheropack-0.2.0-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 177.9 kB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
bd909207860622d2ecc7931ef9ca9ecb0bf7b45651005b3496d60e00340edd5f
|
|
BLAKE2b-256 checksum How to use checksums |
186a6c9018f064fca2da8163cd1c2cb1c8999d5e4e463748b20c417c10a514a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / spheropack-0.2.0-cp311-cp311-macosx_10_15_x86_64.whl
| Download URL | spheropack-0.2.0-cp311-cp311-macosx_10_15_x86_64.whl |
|---|---|
| Size | 189.3 kB |
| Tags | CPython 3.11 macOS 10.15+ x86-64 |
|
SHA-256 checksum How to use checksums |
75d5d8e477ea5dad6c47b12eaa6cdbe3530bddae09bcec1fdb893963aa7af182
|
|
BLAKE2b-256 checksum How to use checksums |
7dccf483b8d41ad48fbd92cdcd8e393e14ee3354be812d5e7e2fea81911b7446
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / spheropack-0.2.0-cp310-cp310-win_amd64.whl
| Download URL | spheropack-0.2.0-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 197.8 kB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
6461effb38832abf276f2cf5465a2a8c4d9cbb89d4963a07b3ce88499d705faa
|
|
BLAKE2b-256 checksum How to use checksums |
0b9912b97501134ef2202a0496c2b19d62b41c5d0f3aa835f0882e859620e1d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / spheropack-0.2.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | spheropack-0.2.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 240.7 kB |
| Tags | CPython 3.10 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
3bbffd20438400e86fe087f38ee61c41bff96164c2d82f25fb3af12eb1c88825
|
|
BLAKE2b-256 checksum How to use checksums |
8a4ba6a08c28da568dd0f25a72f959742cf598cc4c6413b94858276d0726be51
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / spheropack-0.2.0-cp310-cp310-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
| Download URL | spheropack-0.2.0-cp310-cp310-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 223.3 kB |
| Tags | CPython 3.10 Linux glibc 2.27+ ARM64 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
505a4c9f7dfd584e442ad100bc2a3009641d406d2c9c4af6c5002abef821a91b
|
|
BLAKE2b-256 checksum How to use checksums |
9226c68ad1a87d946e3a8e9a52b40217616d06f6c7f58eaaa4993531fbd5c2ae
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / spheropack-0.2.0-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | spheropack-0.2.0-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 178.3 kB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
9a7fa90ee262a877d121675d9c50eed09d3fa21d33e65b72cb2183e8a1cc200e
|
|
BLAKE2b-256 checksum How to use checksums |
3bb8a9f9dac12d249f0ca03b2cca67ef608cefdead2d8c626507988cb687d227
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / spheropack-0.2.0-cp310-cp310-macosx_10_15_x86_64.whl
| Download URL | spheropack-0.2.0-cp310-cp310-macosx_10_15_x86_64.whl |
|---|---|
| Size | 189.8 kB |
| Tags | CPython 3.10 macOS 10.15+ x86-64 |
|
SHA-256 checksum How to use checksums |
efa9b62c6e999767ef957ff550855106eb4073cbd10f0786dc700378484ec27c
|
|
BLAKE2b-256 checksum How to use checksums |
b7dccac9d065e1d76da2c001a38fbaf3439a3e4259c523b42756d5fad66ad3a4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency log
