AMGCL is a header-only algebraic multigrid solver with pluggable backends

AMG as a preconditioner, not a solver

AMGCL is a header-only C++ library for solving large sparse linear systems with the algebraic multigrid method. The README states that AMG is one of the most effective iterative methods for the solution of equation systems arising, for example, from discretising PDEs on unstructured grids.

The critical word is algebraic. Classical geometric multigrid needs to know the geometry, the mesh, the structure of the discretisation, in order to define the coarse grid operators. AMG does not. The method can be used as a black-box solver for various computational problems, since it does not require any information about the underlying geometry.

That is the property that makes a library like this usable, because the person with a sparse matrix usually has a matrix and not a mesh. The matrix is all AMG needs.

The README also makes the usage point directly, and it is the one that surprises newcomers. AMG is often used not as a standalone solver but as a preconditioner within an iterative solver, with Conjugate Gradients, BiCGStab and GMRES named as the examples. The arithmetic is the same either way, but the roles differ. A preconditioner is not trying to solve the system, it is trying to make the system cheap for somebody else to solve, and that is why the library has to produce something that works well inside a Krylov method rather than only on its own.

The audience is a computational scientist or a numerical analyst with a large sparse system and a tolerance to meet. The licence is MIT, the primary language is C++, the default branch is master, the documentation is at amgcl.readthedocs.io, and the last push to the repository was on 2026-10-17.

Build the hierarchy on the CPU, transfer it to a backend

The second paragraph of the README describes the architecture, and it is the part that makes AMGCL different from a solver that assumes it owns the whole machine.

AMGCL builds the AMG hierarchy on a CPU and then transfers it to one of the provided backends. This allows for transparent acceleration of the solution phase with the help of OpenCL, CUDA or OpenMP technologies. Users may provide their own backends, which enables tight integration between AMGCL and the user code.

So there are two distinct phases with distinct requirements. The setup phase, where the hierarchy is constructed, is the expensive part and it stays on the CPU, where the multigrid machinery runs and where the library can rely on ordinary host code. The solution phase, which is where the actual iterations happen, is the part that gets transferred, and that is the part that is worth accelerating.

That split is a deliberate design decision rather than a limitation of the port. Moving the setup would mean the coarsening and smoothing decisions, which are full of data dependent branching, had to be expressed for a device, and the transfer itself costs time. Keeping setup on the host means the GPU only ever sees the flat data the smoother and the restriction and prolongation operators need.

The backend interface is the extension point, and the last sentence is about it. Users may provide their own backends, which is what tight integration between AMGCL and the user code means. A team with an existing accelerator abstraction, or with a device the shipped backends do not cover, can implement the interface rather than being limited to the three that are provided.

The topics list on the repository matches this: cuda, gpgpu, opencl and openmp, alongside mpi for distributed runs, linear-solvers, multigrid and sparse-linear-systems.

The repository carries bindings, examples and a tutorial

The top level listing shows a project that is much more than a header directory, and the extra directories tell you what the maintainer expects people to do with it.

The library itself is in the amgcl/ directory, with lib/ for what is presumably the shipped headers, cmake/ for the build support, and a CMakeLists.txt at the root. The docs/ directory holds the documentation sources, and there is a tutorial/ directory, which is the first thing to read if you have never used AMG.

Then there are the language bindings. pyamgcl/ is the Python binding, and setup.py at the root is its build, with git_version.py alongside it supplying the version from the git checkout. There is also a delphi/ directory and a fortran/ directory, so the library can be called from three more languages than the C++ it is written in.

The examples/ directory is the widest part and the most useful, because the file names describe the range of use cases. There is solver.cpp for the basic case, block_crs.cpp for block sparse matrices, cpr.cpp and cpr_drs.cpp for the CPR (constrained pressure residual) approach, deflated_solver.cpp for deflation, mixed_precision.cpp for mixed precision arithmetic, and schur_pressure_correction.cpp and schurpc_mixed.cpp for a Schur complement treatment of pressure coupling. There are two solver variants, solver_complex.cpp for complex arithmetic and solver_hpx.cpp for the HPX runtime, an example_mkl.cpp using the Intel Math Kernel Library, a ublas.cpp example for the Boost uBLAS matrix formats, a vexcl.cpp example for the VexCL accelerator abstraction, and an ns_search.cpp for a nested search.

Two of the examples are Python driven, make_poisson.py and mmplot.py, and pyprecond.py and pysolver.py show the bindings in use. There is also a custom_adapter.cpp, which is the example to read if you are considering writing your own backend.

There is a mpi/ subdirectory for distributed runs, a docker/ directory, and a tests/ directory.

The Python build detects the compiler and prefers C++14

The setup.py at the root is the pyamgcl build, and it is more interesting than a typical setup file because it probes the compiler rather than assuming one.

It imports the version from git_version.py, so a source checkout reports the version of the commit you are on rather than a hard coded number. The pybind11 include path is resolved by a small helper class whose docstring explains the reason for the indirection, and the reason is worth reading: the purpose of this class is to postpone importing pybind11 until it is actually installed, so that the get_include method can be invoked. In other words, a pip install that never reaches the build step does not fail on a missing pybind11.

The compiler standard is detected rather than assumed, and the preference is explicit:

    if has_flag(compiler, '-std=c++14'):
        return '-std=c++14'
    elif has_flag(compiler, '-std=c++11'):
        return '-std=c++11'
    else:
        raise RuntimeError('Unsupported compiler -- at least C++11 support '
                           'is needed!')

The docstring says the c++14 is preferred over c++11 when it is available, and the fallback is a clear error rather than a mysterious compile failure.

The has_flag helper works by writing a small test program to a temporary file and compiling it with the candidate flag, catching the compile error to decide. And the build_ext subclass adds the compiler specific options, with the MSVC entry carrying the exception handling flag and the unix entry empty, with further additions for macOS. The overall effect is that the binding builds on MSVC, on Linux and on macOS without the user having to tell it which compiler it is facing.

Three papers, a mailing list and a set of build badges

The README has a Referencing section, and for a research library that is not a formality, it is how the method is credited.

There are three entries, all by Demidov. The first is the library paper in the Lobachevskii Journal of Mathematics, volume 40, issue 5, pages 535 to 546, from May 2019, and the doi and pdf are linked. The second is the Software Impacts paper on AMGCL as a C++ library for efficient solution of large sparse linear systems, volume 6, article 100037, from November 2020. The third is the paper with Lin Mu and Bin Wang on accelerating linear solvers for Stokes problems with C++ metaprogramming, in the Journal of Computational Science, 2020, article 101285, with the arXiv version linked as well.

Each entry has a bib link into the docs/ directory of the repository, so the bibliography is versioned with the code.

The support section is short. There is the GitHub issues page and a mailing list, a Google Group forum, and that is it. So bug reports go to GitHub and discussion goes to the list, which is a common arrangement for a project of this kind where the mailing list carries the research conversations and the tracker carries the fixes.

The badges show the same spread. There is a Read the Docs documentation status badge, a Zenodo DOI badge, Travis CI and AppVeyor build statuses, a Codecov badge, and a Coverity Scan build status. Travis and AppVeyor for the two major platform build matrices, Codecov for test coverage, and Coverity for static analysis on a numerical library, which is a sensible combination for code where an out of bounds read in a smoother is a real bug rather than a cosmetic one.

The release record is healthy. The recent releases are 1.5.0 on 2026-08-03, 1.4.9 on 2026-06-10 and 1.4.8 on 2026-05-11, so a minor version every couple of months, and the last push was on 2026-10-17, over two months after the newest tag.

Editorial conclusion

Adopt AMGCL if you solve large sparse systems from discretised PDEs and you want an algebraic multigrid preconditioner you can drop into an existing iterative solver without knowing anything about the mesh, especially if you also want to move the solution phase onto a GPU. Do not adopt it if your matrices are small enough for a direct solver, since an AMG hierarchy is a significant setup cost, and do not adopt it if you need a maintained production solver with a support contract, because this is a research library maintained by its author. Before you commit, read the tutorial in the repository, look at the examples for the problem type you actually have, and check that your compiler and backend combination is covered by the build badges.

Frequently asked questions

Official sources

1. ddemidov/amgcl on GitHub
2. License: MIT
3. Project website
4. README
5. Releases