PyAMG: Algebraic Multigrid Solvers in Python

Common errors

• ModuleNotFoundError: No module named 'pyamg.amg_core.evolution_strength'

  cause This error often indicates an incomplete or incorrect installation of PyAMG, particularly if installed in isolated or non-standard Python environments (e.g., custom Spyder installers or virtual environments without proper build tools). The underlying C++ extensions (`amg_core`) were not compiled or linked correctly.
  fix Reinstall PyAMG in a clean virtual environment using `pip install pyamg`. Ensure `numpy` and `scipy` are installed first. If issues persist, try installing from source (refer to PyAMG's GitHub for build instructions). For Anaconda users, `conda install -c anaconda pyamg` is an alternative.

• Error in TokenizeString(): two or more options before an '=' sign in the configuration file.

  cause This error is typically encountered when PyAMG is integrated with external software like SU2 for mesh adaptation, indicating a syntax error in the configuration file used by the calling application. It implies incorrect parsing of input parameters or missing required options (e.g., `PYADAP_COMPLEXITY`).
  fix Carefully review the configuration file (e.g., `.cfg` file for SU2) for any malformed lines, duplicate options, or missing parameters required by the PyAMG integration. Ensure all options are correctly formatted (e.g., `OPTION = VALUE`). Refer to the specific integration's documentation for required parameters.

• MemoryError: Unable to allocate ...

  cause PyAMG solvers can consume significant memory for large-scale problems, especially when generating coarse grids. This error occurs when the system runs out of available memory.
  fix For `smoothed_aggregation_solver`, try reducing the `max_levels` parameter to limit the number of coarse grids, or increasing `max_coarse` to allow coarser grids to be larger, reducing the total memory footprint. Using the CSR matrix format is also recommended for efficiency.

Warnings

• breaking In PyAMG v5.3.0, the internal matrix storage naming convention changed from `[bc]sr_matrix` to `[bc]sr_array`. Additionally, the matrix-vector multiplication operator should now use `@` instead of `*` for NumPy compatibility.
  Fix: Update code to use `scipy.sparse.csr_array` (or `bsr_array`) instead of `csr_matrix` where relevant, and replace `A * x` with `A @ x` for matrix-vector products.
• breaking Starting from PyAMG v5.1.0, the minimum required Python version is 3.8 and the minimum required SciPy version is 1.8.0. Codebases using older versions of Python or SciPy may encounter compatibility issues.
  Fix: Ensure your Python environment is at least 3.8 and SciPy is version 1.8.0 or newer. For current PyAMG (v5.3.0), Python >=3.9 is required.
• gotcha For optimal performance, especially with iterative solvers, it's best practice to create the `MultilevelSolver` object once and then call its `solve()` method multiple times for different right-hand sides, rather than re-creating the solver for each solve operation.
  Fix: Instantiate the `smoothed_aggregation_solver` (or other solver) once, then reuse the `ml.solve()` method. For example: `ml = smoothed_aggregation_solver(A); x1 = ml.solve(b1); x2 = ml.solve(b2)`.

Install

• pip install pyamg Install latest stable release

Imports

• pyamg

  import pyamg

• smoothed_aggregation_solver

  from pyamg import smoothed_aggregation_solver

• gallery
  wrong:

  import pyamg.gallery

  correct:

  from pyamg import gallery

  While 'import pyamg.gallery' works, importing specific modules like 'gallery' directly is common for clarity and consistency with examples.

Quickstart

This quickstart demonstrates how to set up a 2D Poisson problem using PyAMG's gallery, construct a `smoothed_aggregation_solver`, and solve the resulting sparse linear system. It highlights the typical workflow for using PyAMG as a standalone solver.

import numpy as np
from scipy.sparse import csr_matrix
from pyamg import gallery
from pyamg import smoothed_aggregation_solver

# 1. Create a sample sparse matrix (e.g., 2D Poisson problem)
A = gallery.poisson((100, 100), format='csr')

# 2. Create a right-hand side vector
b = np.random.rand(A.shape[0])

# 3. Construct the Algebraic Multigrid solver
# max_coarse controls the size of the coarsest grid
ml = smoothed_aggregation_solver(A, max_coarse=10)

# 4. Solve the linear system Ax = b
x = ml.solve(b, tol=1e-10)

print(f"Matrix shape: {A.shape}")
print(f"Number of nonzeros: {A.nnz}")
print(f"Solution vector norm: {np.linalg.norm(x)}")
print(f"Residual norm: {np.linalg.norm(b - A @ x)}")