Skip to main content

Tests Docs PyPI Python License

AMJax logo

AMJax brings algebraic multigrid (AMG) methods to JAX for solving large sparse linear systems. It bridges PyAMG and JAX by converting PyAMG-built hierarchies into jax.jit, jax.vmap, GPU-compatible, and differentiable multilevel solvers and preconditioners.

Documentation: https://vboussange.github.io/AMJax/

Installation

uv add amjax

Usage

Direct solve

import jax
import jax.numpy as jnp
import pyamg

from amjax import MultilevelSolver

A = pyamg.gallery.poisson((100, 100), format="csr")
b = jnp.ones(A.shape[0])

ml = MultilevelSolver.from_pyamg(pyamg.ruge_stuben_solver(A))

solve = jax.jit(lambda rhs: ml.solve(rhs, tol=1e-10, maxiter=100, cycle="V"))
x = solve(b)

Preconditioning

MultilevelSolver exposes a preconditioner compatible with JAX Krylov solvers:

import jax.scipy.sparse.linalg
from jax.experimental import sparse as jsparse

A_jax = jsparse.BCOO.from_scipy_sparse(A)
M = ml.aspreconditioner(cycle="V")

x, info = jax.scipy.sparse.linalg.cg(A_jax, b, M=M, tol=1e-10, maxiter=30)

Batched solve with jax.vmap

B = jnp.ones((64, A.shape[0]))
solve_batch = jax.jit(jax.vmap(lambda rhs: ml.solve(rhs, tol=1e-8, maxiter=100)))
X = solve_batch(B)

Differentiating through the solve with jax.grad

def objective(rhs):
    return jnp.sum(ml.solve(rhs, tol=1e-10, maxiter=100))

grad_b = jax.grad(objective)(b)

Benchmark

Benchmark slice: solve $A X = B$, where $A = A_n \in \mathbb{R}^{N \times N}$ is the 2D five-point Poisson matrix on an $n \times n$ grid with $N = n^2$, and $X, B \in \mathbb{R}^{N \times m}$ ($m = 1$ for a single right-hand side and $m = 64$ for the batched jax.vmap rows). Results below use Smoothed Aggregation, V-cycle, pinv coarse solve, jacobi smoothing, f64, tolerance 1e-08, and k=64 for batched solves. AMJax runs on GPU (NVIDIA A100 80GB); PyAMG baselines run on CPU (unspecified).

Scenario Method Grid n (unknowns) PyAMG CPU baseline AMJax GPU time Speedup Residual
Single RHS AMJax 500 (250,000) 452.63 ms 14.61 ms 31.0x 5.93e-09
Single RHS AMJax + PCG 500 (250,000) 397.33 ms 7.14 ms 55.6x 6.94e-09
Batched RHS (vmap) AMJax 500 (250,000) 29.31 s 771.17 ms 38.0x 5.92e-09
Batched RHS (vmap) AMJax + PCG 500 (250,000) 18.40 s 295.15 ms 62.3x 6.97e-09

Timings are the minimum of 10 solves after one JAX warm-up call and exclude hierarchy setup, device transfer, and the first JIT compilation.

Recommendation. For 2D Poisson problems, start with Smoothed Aggregation, V-cycle, Jacobi smoothing, and a pinv coarse solve. Use AMJax as a preconditioner for conjugate gradient (AMJax + PCG) when runtime and convergence both matter. Use f64 for tight residuals; use f32 only for speed-first workloads. When solving many right-hand sides, batch with jax.vmap and use k=64 when memory allows.

Richer benchmark tables are published in the benchmark docs. The full benchmark can be rerun from benchmarks/benchmark.ipynb, or from the shell:

benchmarks/run_full_benchmark.sh

Features

  • V, W, and F cycles compiled with jax.jit
  • Coarse solvers: jacobi, lu, qr, pinv
  • Smoothers: jacobi
  • AMG preconditioning for JAX Krylov solvers
  • jax.vmap support for batched right-hand sides
  • jax.grad support through direct solves and preconditioned Krylov solves

PyAMG interop

MultilevelSolver.from_pyamg accepts hierarchies produced by PyAMG solver factories, including:

Factory Typical use
pyamg.ruge_stuben_solver Classical AMG
pyamg.smoothed_aggregation_solver SPD systems, aggregation AMG
pyamg.rootnode_solver SPD systems, robust aggregation variant
pyamg.pairwise_solver Fast setup; use with care for large standalone solves
pyamg.air_solver Non-symmetric systems

For AMG setup details, use the PyAMG documentation.

Limitations

  • Hierarchy construction is delegated to PyAMG, so setup happens in Python and is not differentiable through the hierarchy itself.
  • A fully native JAX hierarchy is currently blocked by sparse-sparse Galerkin products such as P.T @ A @ P, whose sparsity pattern is not known at JIT trace time.

Metadata

Release files for amjax 0.0.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for amjax 0.0.3
File Size Uploaded Provenance Actions
amjax-0.0.3.tar.gz 241.0 kB Without provenance Details for amjax-0.0.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for amjax 0.0.3
File Interpreter ABI Platform Actions
amjax-0.0.3-py3-none-any.whl Python 3 none any Details for amjax-0.0.3-py3-none-any.whl

Total release size: 257.2 kB

Release files / amjax-0.0.3.tar.gz

Download URL amjax-0.0.3.tar.gz
Size 241.0 kB
Tags Source
SHA-256 checksum
How to use checksums
bda7fcbfa107175aa604f74617ea2cd5b28822556f1604506fbb8b0d794b9b4c
BLAKE2b-256 checksum
How to use checksums
d866151796fca8ebe6a62eccc5e9f88c50f96200ca646578c95a93f2160036f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.15

Release files / amjax-0.0.3-py3-none-any.whl

Download URL amjax-0.0.3-py3-none-any.whl
Size 16.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
db253f6c56415008fe10630141809c0e60d22f50eb1c041dd87720cd3b6c91ae
BLAKE2b-256 checksum
How to use checksums
2f84a511c1bb4b1478cd777f9dde974f3522969e4cfc666d91102c9d5cbaf5bf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.15

Security for amjax 0.0.3

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.

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