Skip to content

API Reference

amjax.MultilevelSolver

JAX-compatible algebraic multigrid solver.

Extends pyamg.multilevel.MultilevelSolver with a fully JAX-compatible solve step: JIT-compiled, GPU-accelerated, and registered as a pytree.

Parameters:

Name Type Description Default
levels

Multigrid hierarchy, finest level first, coarsest level last.

required
coarse_solver_fn

Coarse-grid solver (A, x, b) -> x.

required
coarse_solver_name

Name of the coarse solver, stored for pytree serialisation.

'pinv'
coarse_solver_kwargs

Keyword arguments forwarded to the coarse-grid solver. - 'pinv': rcond - 'jacobi': iterations, omega.

None

Attributes:

Name Type Description
levels list of _Level

Multigrid hierarchy.

coarse_solver callable

Coarse-grid solver.

symmetric_smoothing bool

True when pre- and post-smoothers are identical and symmetric.

Methods:

Name Description
from_pyamg

Construct a JAX hierarchy from a PyAMG hierarchy.

aspreconditioner

Return a matvec callable suitable for use as a JAX preconditioner.

solve

Solve Ax = b by repeated multigrid cycles.

operator_complexity

Ratio of total operator nonzeros to finest-level nonzeros.

cycle_complexity

Estimated FLOPs of one cycle relative to the finest level.

Notes

Unlike PyAMG, smoother callables cannot be stored directly inside a jax.jit-traced object. Smoother names and kwargs are stored separately so that they can be reconstructed after each pytree unflatten.

from_pyamg(pyamg_solver, presmoother=('jacobi', {'iterations': 1, 'omega': 1.0}), postsmoother=('jacobi', {'iterations': 1, 'omega': 1.0}), coarse_solver='pinv', coarse_solver_kwargs=None, dtype=None) classmethod

Construct a JAX multigrid hierarchy from a PyAMG hierarchy.

Parameters:

Name Type Description Default
pyamg_solver

Hierarchy built by a PyAMG solver factory (e.g. ruge_stuben_solver).

required
presmoother

Pre-smoother specification. Passed directly to change_smoothers, which applies it to every level of the hierarchy. Accepts: - a string: 'jacobi' - a tuple with kwargs: ('jacobi', {'iterations': 2, 'omega': 0.8}) - a list to set a different smoother per level - None to disable smoothing

('jacobi', {'iterations': 1, 'omega': 1.0})
postsmoother

Post-smoother specification. Same accepted forms as presmoother.

('jacobi', {'iterations': 1, 'omega': 1.0})
coarse_solver

Name of the coarse-grid solver. Available: 'pinv', 'lu', 'qr', 'jacobi'. Defaults to 'pinv'.

'pinv'
coarse_solver_kwargs

Keyword arguments forwarded to the coarse-grid solver. Defaults to {}.

None
dtype jax dtype

Dtype for all hierarchy arrays (e.g. 'jnp.float32').

None

Returns:

Type Description
MultilevelSolver

Fully initialised JAX multigrid hierarchy.

__repr__()

Return a string summary of the multigrid hierarchy.

operator_complexity()

Return the operator complexity of the hierarchy.

Returns:

Type Description
float

Ratio of the total number of stored nonzeros across all levels to the number of nonzeros on the finest level.

cycle_complexity(cycle='V')

Return an estimated FLOP count for one multigrid cycle, normalised by the finest level.

Parameters:

Name Type Description Default
cycle (V, W, F)

Cycle type.

'V'

Returns:

Type Description
float

Estimated work per cycle relative to a single fine-level matrix-vector product.

aspreconditioner(cycle='V', cycles_per_level=1)

Return a JAX-compatible preconditioner applying one multigrid cycle.

Parameters:

Name Type Description Default
cycle str

Cycle type. Available: 'V', 'W', 'F'.

'V'
cycles_per_level int

Number of V-cycles applied after the F-cycle recursion at each level. Only used when cycle='F'. Default is 1.

1

Returns:

Type Description
callable

A matvec(b) -> x function compatible with any JAX Krylov solver accepting an M preconditioner. Returns an approximation of M⁻¹ b ≈ A⁻¹ b.

solve(b, A=None, x0=None, tol=1e-05, maxiter=100, cycle='V', cycles_per_level=1)

Solve Ax = b by repeated multigrid cycles.

Compatible with jax.jit::

solve_jit = jax.jit(MultilevelSolver.solve)
x = solve_jit(ml, b)

Parameters:

Name Type Description Default
b ndarray

Right-hand side, length n.

required
A ndarray or sparse matrix

Finest-level operator to use for this solve. This is an AMJax extension, not a PyAMG solve argument. When supplied, the existing PyAMG-built hierarchy is kept fixed: restriction, prolongation, coarse operators, and coarse solver state are not rebuilt. Only finest-level residuals, smoothing, and matrix-vector products use A.

None
x0 ndarray

Initial guess. Defaults to the zero vector.

None
tol float

Convergence tolerance on the relative residual ||r|| / ||b||.

1e-05
maxiter int

Maximum number of cycles.

100
cycle str

Cycle type. Available: 'V', 'W', 'F'.

'V'
cycles_per_level int

Number of V-cycles applied after the F-cycle recursion at each level. Only used when cycle='F'. Default is 1.

1

Returns:

Type Description
ndarray

Approximate solution to Ax = b.

Notes

Passing A is intended for differentiating or optimizing the finest-level operator while treating the multigrid hierarchy as fixed. If A changes substantially from the matrix used to build the hierarchy, convergence quality may degrade.

amjax.change_smoothers(ml, presmoother, postsmoother)

Initialize pre- and post-smoothers throughout a MultilevelSolver.

For each level of ml (except the coarsest level), initialize the .presmoother() and .postsmoother() methods used in the multigrid cycle, with the option of having different smoothers at different levels.

Parameters:

Name Type Description Default
ml MultilevelSolver

Data structure that stores the multigrid hierarchy.

required
presmoother str, tuple, list, or None

presmoother can be (1) the name of a supported smoother, e.g. 'jacobi', (2) a tuple of the form ('method', kwargs_dict) where 'method' is the name of a supported smoother and kwargs_dict a dict of keyword arguments, or (3) a list of instances of options 1 or 2. If presmoother is a list, presmoother[i] determines the smoothing strategy for level i. Else, the same strategy is used for all levels. If len(presmoother) < len(ml.levels), then presmoother[-1] is used for all remaining levels.

required
postsmoother str, tuple, list, or None

Defines postsmoother in identical fashion to presmoother.

required

Returns:

Type Description
None

ml is modified in place::

ml.levels[i].presmoother  <== presmoother[i]
ml.levels[i].postsmoother <== postsmoother[i]

ml.symmetric_smoothing is set to True or False depending on whether the smoothing scheme is symmetric.

Notes
  • For jacobi method: when withrho=True, omega is scaled by the spectral radius of D⁻¹A on each level, so omega should lie in (0, 2).
Available smoothers
jacobi
None

amjax.jacobi(A, x, b, Dinv, iterations=1, omega=1.0)

Perform damped Jacobi relaxation on the linear system Ax = b.

Applies iterations sweeps of::

x <- (1 - omega) * x + omega * (x + D^{-1}(b - A x))

Parameters:

Name Type Description Default
A BCOO sparse matrix

n x n system matrix.

required
x ndarray

Current iterate, length n.

required
b ndarray

Right-hand side, length n.

required
Dinv ndarray

Pre-computed element-wise inverse of the diagonal of A, length n.

required
iterations int

Number of sweeps to perform.

1
omega scalar

Damping parameter.

1.0

Returns:

Type Description
ndarray

Updated iterate after iterations sweeps.

amjax.inverse_diagonal(A)

Return the element-wise inverse of the diagonal of A.

Zero diagonal entries are mapped to zero in the output.

Parameters:

Name Type Description Default
A BCOO or ndarray

Input matrix.

required

Returns:

Type Description
ndarray

1-D array of inverse diagonal entries.

Notes

JAX evaluates both branches of jnp.where simultaneously, so a naive 1.0 / d would produce a NaN even when guarded by the condition. The safe divisor substitutes 1.0 for zero entries before division, then masks the result back to zero.