SaUCE
Sparse and Unbiased Clustering Estimator: pair and N-point
counts for catalogues made of k partitions of a periodic box, of which only m
are available, corrected for the missing partitions. The counting is written
in Rust and used from the Python package pysauce.
Method
Each partition is an independent sample of the whole box at 1/k of the total density, for example one of k runs of a semi-analytic model on the same N-body simulation. An N-tuple whose members lie in s distinct partitions is observed only if all s are among the m selected, which happens with probability
P_s = m (m − 1) ⋯ (m − s + 1) / [k (k − 1) ⋯ (k − s + 1)].
The counters split their counts by s (for pairs, "auto" and "cross"), and the estimators weight each class by 1 / P_s. With m = k the result is the count of the full box; with m < k it is an unbiased estimate of it. The estimators require N ≤ m ≤ k, since with m < N some tuples could never be observed.
The weights can instead be multiplied by (m / k)^N ("scale-down"), giving the counts at the observed density, to compare with random counts for the observed number of points.
Installation
pip install pysauce
This needs Python 3.9 or newer. To build from source instead, install Rust 1.88 or newer (from rustup) and run
pip install "git+https://github.com/OscarHickman/SaUCE.git"
For development, clone the repository and run
pip install maturin && maturin develop --release in a virtual environment.
Usage
import numpy as np
from pysauce import compute_xi
rng = np.random.default_rng(0)
k, box_size = 8, 500.0
coords = rng.uniform(0, box_size, (200_000, 3))
partition_ids = rng.integers(0, k, 200_000)
selected = partition_ids < 3 # m = 3 of the k partitions
result = compute_xi(
coords[selected], partition_ids[selected],
r_bins=np.linspace(5.0, 50.0, 10), box_size=box_size,
n_partitions=k, n_partitions_selected=3,
)
result["xi"] # consistent with 0 for this unclustered field
| Function | Returns |
|---|---|
compute_xi, compute_2pcf, compute_xi_smu |
corrected ξ(r); ξ(r_p, π) and w_p(r_p); ξ(s, μ) and its multipoles |
compute_npcf, compute_npcf3_shape, compute_npcf3_smu |
corrected N-point counts by size, and triplets by shape or orientation |
count_pairs_1d, count_pairs_2d, count_pairs_smu |
raw auto and cross pair counts |
count_pairs_1d_partition_matrix |
pair counts for every pair of partitions |
count_npoint, count_npoint3_shape, count_npoint3_smu |
raw N-tuple counts split by s |
partition_weights |
the weights |
analytic_rr_1d, analytic_rr, analytic_rr_smu |
expected random pair counts |
Conventions: positions lie in [0, box_size)³ and separations use the nearest
periodic image; the line of sight is the z axis (π = |Δz|, μ = |Δz| / s); bins
are half-open, [lo, hi); an N-tuple is binned by its largest pairwise
separation. The count_* functions need float64 positions and int32
labels; the compute_* functions convert their input. See the docstrings for
details.
Examples
The notebooks in examples/ run in seconds on a mock catalogue
they build themselves (pip install ".[examples]" adds Matplotlib and
Jupyter):
01_xi_r.ipynb: ξ(r) from m of k partitions against the full box;02_redshift_space.ipynb: ξ(s, μ), its multipoles and w_p(r_p);03_npoint.ipynb: triplet counts by size, shape and orientation.
How it works
Particles are sorted into columns that span the box along z and are about half the search radius wide. Each particle's partners are searched for in nearby columns, only within the range of z they can reach, and candidates are tested and binned in SIMD blocks. The result is exactly that of comparing every pair. On x86-64 the inner loops are also compiled for AVX2, chosen at run time when the CPU supports it.
The counters use every core; set RAYON_NUM_THREADS to use fewer. The counts
do not depend on the number of threads.
Testing
pip install -e ".[test]"
pytest
cargo test
The tests compare every counter with brute-force references
(tests/reference.py) and with
Corrfunc, and check that the
estimators return the full-box counts for m = k and are unbiased for m < k.
cargo test links against libpython: if it cannot find it, set PYO3_PYTHON
to your Python and add its lib directory to LD_LIBRARY_PATH.
pytest benchmarks (with pip install -e ".[benchmark]") times every counter
on a million points.
Citation
If you use SaUCE, please cite the paper for the statistic you measure:
- two-point functions: Hickman, O. J. et al. (2026), Less is More: Unbiased Galaxy Clustering from Fewer Merger Trees, arXiv preprint;
- N-point functions: Hickman, O. J. et al. (2026), SaUCE for the N-point Correlation Function: Unbiased Higher-Order Galaxy Clustering from Fewer Merger Trees, in prep.
The software itself can be cited with CITATION.cff.
License
MIT; see LICENSE.
Metadata
Release files for pysauce 0.3.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pysauce-0.3.2.tar.gz | 266.1 kB | With provenance | Details for pysauce-0.3.2.tar.gz |
Built distributions (wheels)
Total release size: 7.6 MB
Release files / pysauce-0.3.2.tar.gz
| Download URL | pysauce-0.3.2.tar.gz |
|---|---|
| Size | 266.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
45bee1d6c0e50b8d0660a87b5f2c8d7c519a7855fca341436dea8dee2f25071e
|
|
BLAKE2b-256 checksum How to use checksums |
496b437e056d23fdd0d7bf21ef45e63834d4fc6fa8d3a8feda3a67549868d5c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logRelease files / pysauce-0.3.2-cp39-abi3-win_arm64.whl
| Download URL | pysauce-0.3.2-cp39-abi3-win_arm64.whl |
|---|---|
| Size | 304.0 kB |
| Tags | CPython 3.9 Windows ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
995f69832a4366e5a092557a21e626a98326c8981469cbac7dfcd63e318a8aac
|
|
BLAKE2b-256 checksum How to use checksums |
5fea5cfa4f8deea703605de0189b6d243f221dc12965fada188f0bfd876396b6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logRelease files / pysauce-0.3.2-cp39-abi3-win_amd64.whl
| Download URL | pysauce-0.3.2-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 386.2 kB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
cd10a8fcee8cc821397ab3e9aedc821c37f3e88007f8907af6b76b2483947cd0
|
|
BLAKE2b-256 checksum How to use checksums |
7a55b5f399ef274a2a7647648c63378ad063d70a7a91957b470b0bfd22dae732
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logRelease files / pysauce-0.3.2-cp39-abi3-win32.whl
| Download URL | pysauce-0.3.2-cp39-abi3-win32.whl |
|---|---|
| Size | 274.4 kB |
| Tags | CPython 3.9 Windows x86-32 abi3 |
|
SHA-256 checksum How to use checksums |
733b29a7617ab834c220fdcc44663e97e6a86d07e53be6af29d87a00e9ab5fdd
|
|
BLAKE2b-256 checksum How to use checksums |
5d0726c4da832328ad7146683be33bd2dc13f45f6bf3427cff9949530837562b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logRelease files / pysauce-0.3.2-cp39-abi3-musllinux_1_2_x86_64.whl
| Download URL | pysauce-0.3.2-cp39-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 731.4 kB |
| Tags | CPython 3.9 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
04acfc0953b3d9dde58283b85704b83bb667454f5d0963412f2d837e3f4c8136
|
|
BLAKE2b-256 checksum How to use checksums |
88aceb05ebd2408a0b1b93a04b7e3dd09db709e106bad43b6f80ce62360f2bb3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logRelease files / pysauce-0.3.2-cp39-abi3-musllinux_1_2_i686.whl
| Download URL | pysauce-0.3.2-cp39-abi3-musllinux_1_2_i686.whl |
|---|---|
| Size | 660.0 kB |
| Tags | CPython 3.9 Linux musl 1.2+ x86-32 abi3 |
|
SHA-256 checksum How to use checksums |
faa0ce0e75fd2b773951ec2d38a4db673404c9629fe702b40bed198417df6895
|
|
BLAKE2b-256 checksum How to use checksums |
4039750c94bf86b4e8539834abdee6eda6322710968be9fcaeccd1422d353af7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logRelease files / pysauce-0.3.2-cp39-abi3-musllinux_1_2_armv7l.whl
| Download URL | pysauce-0.3.2-cp39-abi3-musllinux_1_2_armv7l.whl |
|---|---|
| Size | 689.1 kB |
| Tags | CPython 3.9 Linux musl 1.2+ ARMv7l abi3 |
|
SHA-256 checksum How to use checksums |
0f9a69cb5415428cfc8efb52ed466cf52af6692f31130001bfc750211472a869
|
|
BLAKE2b-256 checksum How to use checksums |
af181b9060022b54990a85d0c7e5e3e449b99dad9e009ded716cef6c55c45eb4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logRelease files / pysauce-0.3.2-cp39-abi3-musllinux_1_2_aarch64.whl
| Download URL | pysauce-0.3.2-cp39-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 616.8 kB |
| Tags | CPython 3.9 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
dc71be44274cd353e270149466bd4c44a9c178bd0ec6e7563ae914f5f612edb5
|
|
BLAKE2b-256 checksum How to use checksums |
6ecf5726bed676bd9801de50bf9b081c77939489f417c1418591e65d5ebc9d50
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logRelease files / pysauce-0.3.2-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | pysauce-0.3.2-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
|---|---|
| Size | 520.0 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
d13807978d7d2b593dbcf3ee4314d8d2b7ec131ae08eab101fde7823f702b7bc
|
|
BLAKE2b-256 checksum How to use checksums |
7d6a18f5c4889badcb979323a1aaab68f6f5d41af3621e8f351de02bc084c815
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logRelease files / pysauce-0.3.2-cp39-abi3-manylinux2014_s390x.manylinux_2_17_s390x.whl
| Download URL | pysauce-0.3.2-cp39-abi3-manylinux2014_s390x.manylinux_2_17_s390x.whl |
|---|---|
| Size | 468.8 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ IBM System/390x abi3 |
|
SHA-256 checksum How to use checksums |
32ff300ea69bc9e0b916dec079149b828574583b235423dfb51deec6b991130f
|
|
BLAKE2b-256 checksum How to use checksums |
2d63c394390ddd7b9d809aa7342caa2e92b7c1f644dd95b192fa72925d5afb2a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logRelease files / pysauce-0.3.2-cp39-abi3-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl
| Download URL | pysauce-0.3.2-cp39-abi3-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl |
|---|---|
| Size | 491.4 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ PowerPC 64-le abi3 |
|
SHA-256 checksum How to use checksums |
b73240f671fc78f15b49940de9a70344483455ccea32676136a204bcd3a603fa
|
|
BLAKE2b-256 checksum How to use checksums |
acacad40fd787ec405970418c926ca6c3e58da1d4d95cbea1dcbafd57bb32785
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logRelease files / pysauce-0.3.2-cp39-abi3-manylinux2014_armv7l.manylinux_2_17_armv7l.whl
| Download URL | pysauce-0.3.2-cp39-abi3-manylinux2014_armv7l.manylinux_2_17_armv7l.whl |
|---|---|
| Size | 413.2 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARMv7l abi3 |
|
SHA-256 checksum How to use checksums |
302bee401eca26b2942ace9ae8521b248d70ee527e375e804a8a44780baf6cdb
|
|
BLAKE2b-256 checksum How to use checksums |
5e0a8a587c8fe2e2914ded1622e37aad8a13db40b05f59d98b2ccd8ed310f82c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logRelease files / pysauce-0.3.2-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
| Download URL | pysauce-0.3.2-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
|---|---|
| Size | 437.5 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
55df4dac6930eecb3047fe00516ca77ecc7e3699744acd59749c3661e500d2dd
|
|
BLAKE2b-256 checksum How to use checksums |
b89896de59f51eb8879ddad811ae8e0d451387dbdc26bb3599ab88fe3081cc78
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logRelease files / pysauce-0.3.2-cp39-abi3-manylinux2010_i686.manylinux_2_12_i686.whl
| Download URL | pysauce-0.3.2-cp39-abi3-manylinux2010_i686.manylinux_2_12_i686.whl |
|---|---|
| Size | 445.7 kB |
| Tags | CPython 3.9 Linux glibc 2.12+ x86-32 abi3 |
|
SHA-256 checksum How to use checksums |
4589b4bcdd94f33b79f45d5dc5ba3bdb4d2cb00342e498a2070f6961d7839940
|
|
BLAKE2b-256 checksum How to use checksums |
777549c1d7b90d64e5fe2501820c87277704d9b67ebe92ffd53cab6d7473a564
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logRelease files / pysauce-0.3.2-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | pysauce-0.3.2-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 401.0 kB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
fef2c81e1414c20ad9fd2cc8b84f3a5c965cb583d54086109fb1873a8b786782
|
|
BLAKE2b-256 checksum How to use checksums |
ad3286afc59999bcee946ab494d6942f89ae72183c980929d881476e13dbaeaa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logRelease files / pysauce-0.3.2-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | pysauce-0.3.2-cp39-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 487.2 kB |
| Tags | CPython 3.9 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
63e10b41da235669d5c1ac3081e05330ed8efc3a79ed70656e93117701a50afb
|
|
BLAKE2b-256 checksum How to use checksums |
038bfb5ef662ca5890b00b1c3cf142fe1ecd73cca6b8a720298d7fc67e634df0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 11, 2026.
Transparency logSecurity for pysauce 0.3.2
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.
Full provenance
All 16 files in this release have been uploaded with provenance metadata.
Attestation for pysauce-0.3.2.tar.gz
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 Nov 11, 2026.
Transparency logA 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.