# AMGX: a GPU algebraic multigrid solver with a JSON-configurable core > NVIDIA's AMGX is a GPU-accelerated algebraic multigrid library for the linear solver stage of implicit simulations, exposing a C API and a JSON configuration system for composing nested solvers and preconditioners. It builds with CMake and CUDA, runs examples against a Matrix Market file, and needs a GPU of compute capability 3.0 or better. **NVIDIA/AMGX** — Distributed multigrid linear solver library on GPU - Repository: https://github.com/NVIDIA/AMGX - Stars: 700 · Forks: 200 - Language: Cuda - License: not declared - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/nvidia-amgx ## A solver library, not an application AMGX is a core library, and the framing matters for adoption decisions. The description is a distributed multigrid linear solver library on GPU, and the README describes it as a GPU accelerated core solver library that speeds up the computationally intense linear solver portion of simulations. It does not ship a simulator. It plugs into one. The target workload is implicit methods on unstructured meshes, which is the regime where classical geometric multigrid cannot be applied because there is no clean geometric hierarchy to exploit. AmgX builds that hierarchy algebraically, from the matrix itself. The access model is a C API that abstracts the parallelism and scale across one or many GPUs, with the user supplying the MPI implementation for distributed runs. The library calls itself a source of the AMGX library on the NVIDIA Registered Developer Program portal, so what sits in the repository is the implementation behind the binary distribution that NVIDIA hands to registered developers. That is a meaningful distinction for a reader wondering whether this is the same code they would get from the portal, and for a reader wondering which one carries a support relationship. The feature list in the README is specific enough to be useful: fp32, fp64 and mixed precision solves, scalar or coupled block systems, classical Ruge-Steuben and unsmoothed aggregation multigrid, Krylov methods including CG, BiCGSTAB and GMRES with optional preconditioning, and smoothers including Jacobi, Gauss-Seidel, Incomplete LU and Chebyshev Polynomial. ## Solver composition happens in JSON, not in code The flexible part of AmgX is the configuration layer. The library exposes a lot of algorithm parameters through solver configuration in JSON format, and the repository keeps a directory of sample configurations at src/configs. The naming convention in the examples directory shows what these look like in practice, with named files such as FGMRES_AGGREGATION.json, and separate example binaries for the MPI and classical variants. This design carries an important consequence. Because a nested solver with its preconditioner, smoother and multigrid hierarchy is described as data, you can change the algorithm without recompiling your application code. That is what makes the library usable from a code you do not own, or a code whose solver layer is generic. The composition model is explicitly hierarchical. The library allows a user to construct complex nested solvers and preconditioners, and the features list names nested solvers, smoothers and preconditioners as three separate things you can combine. The Unbounded Layout Generator style of staged pipeline is not how this works; AmgX instead gives you a tree of configurable components. The cost of that flexibility is verbosity. A solver configuration for a real problem is long, and getting the hierarchy and the Krylov wrapper right is a debugging exercise rather than a one-liner. The shipped configurations in src/configs are the sensible starting point, which is why the run example points at one by name. ## Building needs CMake, CUDA and a compiler with C++11 The dependency list is short and specific. You need CMake and the CUDA Toolkit, a compiler with c++11 support such as GCC 4.8 or MSVC 14.0, and an NVIDIA GPU with Compute Capability 3.0 or better. For the distributed version you additionally need an MPI implementation, with OpenMPI named for Linux and MPICH for Windows. The build itself is a conventional out-of-source CMake build from the project root: ```bash mkdir build cd build cmake ../ make -j16 all ``` Four custom CMake flags control what you get, and two of them matter for a real deployment. CMAKE_NO_MPI forces a non-MPI, single GPU build, which produces a smaller library that runs on systems without MPI installed, and by default MPI is enabled if the FindMPI script finds any MPI installation. AMGX_NO_RPATH stops CMake from adding rpath flags to binaries, which is the flag to reach for when the execution environment is controlled by something else. CUDA_ARCH takes a list of virtual architecture values that CMakeLists translates into the corresponding nvcc flags, for example: ```bash cmake .... -DCUDA_ARCH="60 70" .... ``` MKL_ROOT_DIR and MAGMA_ROOT_DIR point at those libraries, which accelerate some of the AmgX eigensolvers. The documentation is explicit that those solvers return a not supported error if the library was not built with MKL and MAGMA support, so a silent-looking build can still refuse a feature at runtime. ## The example run shows the diagnostics that matter The examples directory holds a sample matrix in Matrix Market format at examples/matrix.mtx, and the run command wires it to a configuration from src/configs: ```bash > examples/amgx_capi -m ../examples/matrix.mtx -c ../src/configs/FGMRES_AGGREGATION.json AMGX version 2.0.0-public-build125 Built on Oct 7 2017, 04:51:11 Compiled with CUDA Runtime 9.0, using CUDA driver 9.0 Warning: No mode specified, using dDDI by default. Reading data... RHS vector was not found. Using RHS b=[1,…,1]^T Solution vector was not found. Setting initial solution to x=[0,…,0]^T Finished reading ``` Two of those lines are warnings you will see on your own first run. The library falls back to a right-hand side of ones and an initial solution of zeros when the Matrix Market file does not carry them, and the documentation says to edit the examples to supply your own values. The mode warning appears when no mode is specified. The output continues with the AMG grid table, giving the number of levels, the rows and non-zeros per level, the sparsity, the grid complexity, the operator complexity, the total memory usage and then an iteration table with residual and convergence rate. The grid complexity and the operator complexity figures are the two numbers to watch. Grid complexity measures how much the hierarchy grew relative to the original matrix, and operator complexity measures the total work in a cycle relative to one matrix-vector product. High values mean the multigrid setup is doing too much work per solve, which is the classic way an AMG approach loses to a plain Krylov method on a badly conditioned problem. Note the version string in that sample output is 2.0.0 from a 2017 build, so treat it as illustrative of the output format rather than of the current release. ## The library is C API only, and the examples show the surface Everything is reached through the C API, and the examples directory is effectively the documentation for how that surface is used. The file names describe the coverage: amgx_capi.c for the single GPU path, amgx_capi_multi.c for a multi-device variant, amgx_mpi_capi.c and its _agg, _cla and _multi variants for the distributed and aggregation cases, amgx_mpi_poisson5pt.c and amgx_mpi_poisson7.c for Poisson operators, amgx_spmv_example and amgx_spmv_test.c for sparse matrix-vector product checks, and eigen_examples plus convert.c and generate_poisson.cu for the eigenvalue and matrix generation side. The headers are split the same way, with amgx_capi.h and amgxP_capi.h for the public and provider interfaces, and amgx_test_common.h for the test harness. The presence of a provider header alongside the public one reflects the modular structure the features list mentions, which is described as a way to implement your own methods. Two operational details catch teams out. The MPI examples are only built if the MPI build was enabled, so a missing binary in a single GPU build is expected rather than broken. And the examples need to find the shared library at runtime: by default the rpath flag points to the build tree, but you can set the path manually in LD_LIBRARY_PATH on Linux or PATH on Windows, which is exactly what you need when the binary runs somewhere other than the build directory. The build products are a shared and a static library, libamgxsh.so or amgxsh.dll and libamgx.a or amgx.lib, plus the example binaries. ## HPC SDK builds want a newer CMake and GCC There is a separate instruction path for teams building with the NVIDIA HPC SDK, and it is stricter than the generic one. The project asks for CMake 3.22 or newer in that case, and for GCC for the C and C++ compilation. The example invocation sets the compilers, forces a Release build type and pins a single virtual architecture: ```bash cmake \ -DCMAKE_C_COMPILER=gcc \ -DCMAKE_CXX_COMPILER=g++ \ -DCMAKE_BUILD_TYPE=Release \ -DCUDA_ARCH="80" .. ``` The build system itself enables CUDA as a language and uses the FindCUDAToolkit and FindMPI modules, so the documentation points you at those scripts in your own CMake installation for the module-specific flags rather than documenting them here. That is a deliberate delegation: those scripts change between CMake releases, and pinning their behaviour in a project README would age badly. Setting CUDA_ARCH to a single value in that example is the deployment decision, not an oversight. A library shipped to a fleet of mixed GPUs needs to know which architectures to compile for, and the same list has to be reflected in the runtime hardware you support. A build targeting one architecture will not run on a card it was not compiled for, which is a common cause of a first-run failure on a workstation that differs from the build server. ## Release cadence has gone quiet since 2025 The release history is uneven. The listed versions are v2.5.0 from 2025-12-21, v2.4.0 from 2023-10-25 and v2.3.0 from 2022-06-29. The gap between v2.4.0 and v2.5.0 is more than two years, and the gap before that is about a year and a half, so this is a project with long gaps between tagged points rather than a steady release train. The repository is not archived and the last push was on 2026-07-09, so work continues on the main branch even between tags. The top-level tree carries a CHANGELOG file, a ReleaseVersion.txt and a ci/ directory, which is the shape of a project that does version itself, just not often. The licence is the item to check before you commit. The repository's licence field is not a recognised identifier, and the tree contains a LICENSES/ directory alongside a NOTICES file at the root, which is the standard layout for a component with third-party licensing obligations. Read those files directly rather than relying on a badge or on the portal distribution terms, because the two may not be identical. This is not legal advice, and the point is only that an unqualified licence field means you have to open the files. ## Conclusion Adopt AMGX if you own an implicit simulation code whose linear solve dominates runtime, you can carry a C API call into your solver stack, and your matrices are unstructured enough that a geometric multigrid is not an option. Do not adopt it for a small or structured problem, because the composition and configuration machinery is sized for industrial workloads, and do not assume a permissive licence: the repository's licence field is not a standard identifier, so read the LICENSES directory and the NOTICES file before shipping. Before you commit, build the project and run the single GPU example against examples/matrix.mtx with a configuration from src/configs, then check your own matrix against the printed grid complexity and operator complexity numbers, since those two figures tell you whether the hierarchy AmgX built is actually paying for itself. ## FAQ ### What are the build requirements for AMGX? You need CMake, the CUDA Toolkit, a compiler with c++11 support such as GCC 4.8 or MSVC 14.0, and an NVIDIA GPU with Compute Capability 3.0 or newer. Distributed builds also need an MPI implementation, OpenMPI for Linux or MPICH for Windows, and the HPC SDK path asks for CMake 3.22 or newer. ### How do I run an AMGX example on a single GPU? From the build directory, run examples/amgx_capi with a matrix file and a configuration, for example the matrix.mtx in the examples directory with a configuration from src/configs. Make sure the examples can find the shared library, through LD_LIBRARY_PATH on Linux or PATH on Windows if the default rpath is not in play. ### What solver methods does AMGX provide? It supports classical Ruge-Steuben and unsmoothed aggregation algebraic multigrid, Krylov methods including CG, BiCGSTAB and GMRES with optional preconditioning, and smoothers such as Jacobi, Gauss-Seidel, Incomplete LU and Chebyshev Polynomial. Solves can run in fp32, fp64 or mixed precision on scalar or coupled block systems. ### What do the grid complexity and operator complexity numbers mean in the AMGX output? They come out of the AMG grid table the library prints at setup. Grid complexity compares the size of the multigrid hierarchy to the original matrix and operator complexity compares the work in one cycle to a matrix-vector product, so high values indicate the hierarchy is doing more work per solve than it should. ### How is an AMGX solver configured? Through JSON configuration files rather than compiled-in settings, with a lot of algorithm parameters exposed that way. Sample configurations live in the src/configs directory of the repository, and the run example points at one such file on the command line. ## Sources - [Issues](https://github.com/NVIDIA/AMGX/issues) - [NVIDIA/AMGX on GitHub](https://github.com/NVIDIA/AMGX) - [README](https://github.com/NVIDIA/AMGX/blob/main/README.md) - [Releases](https://github.com/NVIDIA/AMGX/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nvidia-amgx