{"id":9203,"library":"pyamg","title":"PyAMG: Algebraic Multigrid Solvers in Python","description":"PyAMG is a Python library providing implementations of Algebraic Multigrid (AMG) solvers and supporting tools for approximating solutions to large, sparse linear systems of algebraic equations (Ax=b). It is actively maintained, with the current version being 5.3.0, and receives regular updates to support newer Python and SciPy versions and introduce new features.","status":"active","version":"5.3.0","language":"en","source_language":"en","source_url":"https://github.com/pyamg/pyamg","tags":["numerical-methods","algebraic-multigrid","solver","sparse-matrices","scientific-computing","preconditioner"],"install":[{"cmd":"pip install pyamg","lang":"bash","label":"Install latest stable release"}],"dependencies":[{"reason":"Required for numerical operations and array manipulation, specifically for handling matrices and vectors.","package":"numpy"},{"reason":"Required for sparse matrix support and operations, fundamental to PyAMG's functionality.","package":"scipy"},{"reason":"Often used for visualizing results and convergence histories in examples and tutorials.","package":"matplotlib","optional":true},{"reason":"Optional dependency added in v5.3.0 for enhanced aggregation capabilities.","package":"pymetis","optional":true}],"imports":[{"symbol":"pyamg","correct":"import pyamg"},{"symbol":"smoothed_aggregation_solver","correct":"from pyamg import smoothed_aggregation_solver"},{"note":"While 'import pyamg.gallery' works, importing specific modules like 'gallery' directly is common for clarity and consistency with examples.","wrong":"import pyamg.gallery","symbol":"gallery","correct":"from pyamg import gallery"}],"quickstart":{"code":"import numpy as np\nfrom scipy.sparse import csr_matrix\nfrom pyamg import gallery\nfrom pyamg import smoothed_aggregation_solver\n\n# 1. Create a sample sparse matrix (e.g., 2D Poisson problem)\nA = gallery.poisson((100, 100), format='csr')\n\n# 2. Create a right-hand side vector\nb = np.random.rand(A.shape[0])\n\n# 3. Construct the Algebraic Multigrid solver\n# max_coarse controls the size of the coarsest grid\nml = smoothed_aggregation_solver(A, max_coarse=10)\n\n# 4. Solve the linear system Ax = b\nx = ml.solve(b, tol=1e-10)\n\nprint(f\"Matrix shape: {A.shape}\")\nprint(f\"Number of nonzeros: {A.nnz}\")\nprint(f\"Solution vector norm: {np.linalg.norm(x)}\")\nprint(f\"Residual norm: {np.linalg.norm(b - A @ x)}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=5.3.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.1.0"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"ModuleNotFoundError: No module named 'pyamg.amg_core.evolution_strength'"},{"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.","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`).","error":"Error in TokenizeString(): two or more options before an '=' sign in the configuration file."},{"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.","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.","error":"MemoryError: Unable to allocate ..."}]}