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:
Newer release available (0.2.2)

1 maintainer

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

Credits

Author: Oleksandr Kulkov

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.1-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (426.5 kB view details)

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

apxchol-0.2.1-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.1-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.1-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.1-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.1-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for apxchol-0.2.1-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 7af0ec2d279097327d4cba80dd8d4e7b7825508284d99c1824264fac7f22fea9
MD5 9b5270391212b82d87c4157ac653b66b
BLAKE2b-256 c93f74a0e7efe4a3716fc35e68f3b456750729aaab7b994943501efd0d941186

See more details on using hashes here.

Provenance

The following attestation bundles were made for apxchol-0.2.1-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.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for apxchol-0.2.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e4a052a4b48614ca9661af81cfa51abbf11a8555de88917fff41136c113edc15
MD5 d86c3674268e65a1acc1856c87f9429e
BLAKE2b-256 cd511e74100a44cda1a8dc113b7251bf7e5b9851c4fe42ae58fb6e66a2804a40

See more details on using hashes here.

Provenance

The following attestation bundles were made for apxchol-0.2.1-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.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for apxchol-0.2.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 a347ea7de538656459fd3b0ffd5713fe62e6c3485cdea40a198306aa1fee0409
MD5 2af43c546709d946568ff3852f926549
BLAKE2b-256 7662c3f7ccd5966ccb4f3fd0bf90e9180df9d50cf71f0b4244133d0fdff3ecb8

See more details on using hashes here.

Provenance

The following attestation bundles were made for apxchol-0.2.1-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.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for apxchol-0.2.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 5f1d67d52a941eaf6e2eb56601dd8960d205ce5a62bad1078944e5e59597f682
MD5 4ea10ab5effaaaf1f5d39d49e090149a
BLAKE2b-256 cab548a2b3c3af9527713d95fbd8e74fc977b92cead63fe6cbba949a290806b6

See more details on using hashes here.

Provenance

The following attestation bundles were made for apxchol-0.2.1-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.1-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for apxchol-0.2.1-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 d47f4fc0e8785a459f154ffb76a7d5b334fe13693eb554b199c881a8d14b8ed9
MD5 4f31c0df6d73ec98c286bf566b552b7a
BLAKE2b-256 93c5cb1c0019f7b969165b1b8bc3449d9ae7d0d3ecac9dab22f30e990417e2f0

See more details on using hashes here.

Provenance

The following attestation bundles were made for apxchol-0.2.1-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

0.2.2

5 files

This release

0.2.1 This release

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