apxchol (Python, CPU)

Approximate-Cholesky preconditioner for graph-Laplacian / SDDM linear systems.

pip install apxchol

Prebuilt wheels: Linux x86_64 (manylinux), CPython 3.10–3.14. CPU only. The wheels are built with 32-bit indices: inputs (and factors) beyond ~2.1e9 nonzeros are unsupported — build from source with -DAPXCHOL_64BIT_EDGE_INDICES=ON for larger problems.

import apxchol

solver = apxchol.factorize(A)           # scipy sparse Laplacian or SDDM; factor once
res = solver.solve(b, rtol=1e-8, maxiter=500)
res.x, res.iters, res.residual, res.converged

z = solver.apply(r)                     # M^{-1} r
M = solver.aspreconditioner()           # use as M= in scipy.sparse.linalg.cg

res = apxchol.solve(A, b)               # one-shot convenience

Laplacian vs SDDM is auto-detected: singular Laplacians get a rank-(n−1) factor with native null-space handling; SDDM systems get the full-rank factor. The factor is built once per factorize(A) (alias: apxchol.solver(A)) and reused across right-hand sides; solve runs the library's OpenMP-parallel PCG (threads via OMP_NUM_THREADS).

Solving

res = solver.solve(b, rtol=1e-8, maxiter=500, x0=guess)

rtol is the relative-residual target (SciPy's name; tol is kept as an alias and rtol wins if both are given, default 1e-8). x0 is an optional initial guess — an already-converged x0 returns iters == 0.

out is an optional writable C-contiguous float64 array of length n: the solution is written into it in place (no per-solve allocation) and returned as SolveResult.x.

Options

solver = apxchol.factorize(A, seed=42, partitioner="block_greedy",
                           storage="vec_pool", keep_factor=True)
  • seed — RNG seed for the randomized clique sampling.
  • partitioner — independent-set selector: block_greedy (default), luby, baumann_kyng, rootset.
  • storage — graph backend: vec_pool (default), forward_star, vec, bstr.
  • keep_factor — keep the factor arrays alive for export (default True). Costs one extra factor-sized copy in memory (~8 bytes per factor nonzero in the default fp32 wheels); with keep_factor=False the chol()/L/D export raises, while P, factor_nnz and fill_ratio stay available. Pass keep_factor=False for the leanest factor-once / solve-many footprint (the 0.1.x behavior); apxchol.solve() (one-shot) uses False.

Advanced core knobs are passed through as extra keywords: degree_quantile, degree_multiplier, degree_tiebreak, exact_clique_max_degree, residual_peel (natural | min_degree | bk_serial), stagnation_window. Unknown keywords raise ValueError. Note: degree_multiplier only takes effect when degree_quantile=0 (the quantile cap, default 0.2, replaces it).

Factor export

P = solver.P            # int64: P[original_vertex] = position in elimination order
G = solver.chol()       # scipy.sparse.csc_matrix, lower-triangular incl. sqrt-diagonal
L, D = solver.L, solver.D          # unit-lower CSC and the diagonal of L·D·L^T
solver.factor_nnz, solver.fill_ratio

The factor lives in permuted space, ordered by elimination:

import numpy as np
import scipy.sparse as sp

p = np.argsort(solver.P)     # original index of the k-th eliminated vertex
A_perm = A[p][:, p]
# A_perm ~= G @ G.T ~= L @ sp.diags(D) @ L.T

G is an approximate, randomly sampled factor, so that identity is approximate by construction; L @ diags(D) @ L.T == G @ G.T is exact. For a pure Laplacian (solver.sddm == False) it holds on the rank-(n−k) subspace only, where k is the number of connected components — the last eliminated column of each component carries a placeholder diagonal.

fill_ratio is (2 * factor_nnz - n) / nnz(A): the factor G reflected to a full symmetric pattern (diagonal counted once) against the nonzeros of the full symmetric A.

Exported values are float64 numpy arrays, but default builds store factor values in fp32, so they carry fp32 precision (~7 digits).

Thread safety

A Solver is not safe for concurrent use: solve() and apply() write shared internal scratch buffers. Use one Solver per thread, or serialize calls (each call is itself OpenMP-parallel).

License

BSD 4-Clause (the original "BSD with advertising clause" license) — see LICENSE. Copyright (c) 2026 ETH Zürich and the apxchol contributors.

From source

The wheel build compiles the library's two core translation units directly; building from a repository checkout works the same way:

pip install -e python          # from the repository root
pytest python/tests -v

Source builds use -O3 -march=native (the distributed wheels are built portable). If your environment requires --no-build-isolation, first pip install pybind11 scikit-build-core.

Project links

Data verified by PyPI on Jul 27, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for adamant.pwn from gravatar.com adamant.pwn

Credits

Author: Oleksandr Kulkov, Yves Baumann, Rasmus Kyng

GitHub Statistics

Data verified by PyPI on Jul 27, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

BSD 4-Clause License

Requires

Python >=3.10

Provides Extra

test

Tags

laplacian preconditioner cholesky sparse pcg

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

apxchol-0.2.2-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (426.6 kB view details)

Uploaded CPython 3.14manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

apxchol-0.2.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (426.4 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

apxchol-0.2.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (426.4 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

apxchol-0.2.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (426.4 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

apxchol-0.2.2-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (2.3 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

File details

Details for the file apxchol-0.2.2-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for apxchol-0.2.2-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 6bb8a67d96f29d48884cdd4865ebfcba6ec51522ecd2dcd6ae19608a48dc665f
MD5 82bd2e546ae87b57030d0bfc7800bdbe
BLAKE2b-256 6c0abfc3655d07e0962c93f6d61a0ac8b0dd46f55e03990e41ea26a9a6236927

See more details on using hashes here.

Provenance

The following attestation bundles were made for apxchol-0.2.2-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish.yml on AlgOptGroup/apxchol

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file apxchol-0.2.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for apxchol-0.2.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 b50a9ac83bef42ffb3265b15b423aedfacf685a50eb2d75ef847c90feabcbd89
MD5 125a5bf4932770a9fb7d1a45759084a1
BLAKE2b-256 656e983243c057a39a3171e28c3556c486ad7c6dc4a5cf7e51c4aad48fc7aead

See more details on using hashes here.

Provenance

The following attestation bundles were made for apxchol-0.2.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish.yml on AlgOptGroup/apxchol

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file apxchol-0.2.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for apxchol-0.2.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 5d392e8bca7fecdc036318e4390f62c9d27b7118cf99bd2ef6816df1da09253e
MD5 06fae6c98fd82e73fe2f9a86373d8c34
BLAKE2b-256 2e2cc020a2457e4cdcc65438ed2764011bc0368133dc23a996d10cc31c35a88c

See more details on using hashes here.

Provenance

The following attestation bundles were made for apxchol-0.2.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish.yml on AlgOptGroup/apxchol

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file apxchol-0.2.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for apxchol-0.2.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 c560d3fa9ae90d09f7bdd3c4d4778f1db3254bac6f6153aee024bf64bda5d9cb
MD5 e90fd2ea4d24a9e4f6998b4c4615cb1f
BLAKE2b-256 b9dcba33792bfac20aaf0c18da295837bc04053aa89d09fe5b6a04541f9d116e

See more details on using hashes here.

Provenance

The following attestation bundles were made for apxchol-0.2.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish.yml on AlgOptGroup/apxchol

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file apxchol-0.2.2-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for apxchol-0.2.2-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 87188a2b17f049700d5a52de563cb2d1eea654039a28f791cb7f998e33d73fda
MD5 d8298eccd9c8fe166c2fa1215172d781
BLAKE2b-256 d8a081593e92cae79044bbfc3bc3d0403696fd3041efca0ffd1c61c7f8fe5fcf

See more details on using hashes here.

Provenance

The following attestation bundles were made for apxchol-0.2.2-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish.yml on AlgOptGroup/apxchol

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.2 This release

5 files

0.2.1

5 files

0.2.0

5 files

0.1.1

5 files

0.1.0

5 files

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