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 |
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.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.