# Ginkgo solves sparse systems on whichever backend you have

> Ginkgo is a BSD-3-Clause C++17 numerical linear algebra library built around sparse linear systems, where the same algorithms run on a reference executor, on OpenMP, and on NVIDIA, AMD or Intel GPUs through separate modules that are detected and built depending on the machine.

**ginkgo-project/ginkgo** — Numerical linear algebra software package

- Repository: https://github.com/ginkgo-project/ginkgo
- Website: https://gko-project.org
- Stars: 628 · Forks: 134
- Language: C++
- License: BSD-3-Clause
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/ginkgo-project-ginkgo

## A linear algebra library aimed at sparse systems

Ginkgo is described as a high-performance numerical linear algebra library for many-core systems, with a focus on the solution of sparse linear systems. The repository description is shorter, numerical linear algebra software package, and the primary language is C++.

The implementation is modern C++, and the README is explicit that you need at least a C++17 compliant compiler to build it. GPU kernels are implemented for NVIDIA, AMD and Intel GPUs, which is the third distinct vendor story in one library and is the main reason the build system is as elaborate as it is.

The topic list names the problem domain with some precision: sparse linear systems and sparse-matrix vector multiplication, Krylov methods, preconditioning, GPU computing, and the specific toolchains CUDA, DPC++, HIP and OpenMP. The example directories confirm the shape of the library in practice, with solvers named for their algorithm rather than their role, including conjugate gradient with block Jacobi, an ILU preconditioned solver, iterative refinement, inverse iteration, a batched solver, distributed multigrid preconditioned solvers, mixed multigrid solvers, a heat equation example, a minimal CUDA solver, a file config solver, a custom matrix format, a custom logger, a custom stopping criterion, Kokkos assembly, an external library interface example and a Ginkgo overhead example.

The audience is a computational science team with sparse problems and a heterogeneous machine, which is the narrow case the library is built for.

## One algorithm, several executors

The design idea that makes Ginkgo worth the build effort is the separation between the algorithm and the hardware it runs on. The source tree shows the executor modules as siblings of the core: there is a reference directory, an omp directory for OpenMP, a cuda directory, a hip directory and a dpcpp directory, alongside a common directory for shared code and a devices directory.

The reference executor is the CPU implementation and the correctness reference for everything else. The README notes that GINKGO_BUILD_REFERENCE is enabled by default and that you should be able to run the examples with this executor, and that by default Ginkgo tries to enable the relevant modules depending on the machine environment, for example whether CUDA is present. You can also compile explicitly with the OpenMP, CUDA, HIP or DPC++ (SYCL) modules enabled in order to run the examples with those executors.

That last point is the one to hold on to. The default build is not just a CPU build, it is a build that inspects the machine and enables what it finds. On a workstation with a CUDA toolkit installed, you get the CUDA module. On a machine with ROCm, you get HIP. The consequence is that two people building on two different machines can end up with different builds of the same source, which is convenient and also a source of confusion when a bug reproduces on one machine and not another.

The benefit is the payoff. A solver written once against the Ginkgo interfaces can be run on a reference CPU build for correctness, on many OpenMP threads for a quick answer, and on a GPU for a large problem, without three separate implementations.

## Building it with CMake and consuming it with find_package

The build is the standard CMake procedure, and the README gives the three commands:

```sh
mkdir build; cd build
cmake -G "Unix Makefiles" .. && cmake --build .
cmake --install .
```

The Installation page in the repository, INSTALL.md, has the details, and the README notes that the standard build targets are what most people need.

Consuming the library is deliberately simple. After installation, Ginkgo can be added to a CMake project with find_package(Ginkgo), and the exported target is Ginkgo::ginkgo. A worked example of exactly that is in the test_install directory, whose CMakeLists.txt the README points at, which is the right thing to copy when you want a known-good consumer setup.

The core prerequisites for Linux and Mac are cmake 3.16 or later and a C++17 compliant compiler, and the README lists a wide set of acceptable ones: gcc 9+, clang 5+, the Intel compiler 2019+, Apple Clang 15.0 which is what is tested, the Cray Compiler 14.0.1+, and the NVHPC Compiler 22.7+.

On Windows the requirements are cmake 3.16+, and either MinGW with gcc 9+ or Microsoft Visual Studio 2019+, with a 64-bit compiler. The README also notes that restrictions apply to the version of the C and C++ standard libraries installed on the system, and that this needs further investigation, which is a candid admission that the Windows support is the least settled part of the story.

## Each GPU backend brings its own version floors

The additional requirements per module are the part of the README that decides whether a build is possible, so they are worth reading in full.

The CUDA module needs cmake 3.18 or later, or 3.22 or later if the CUDA toolkit came from the NVIDIA HPC Toolkit, plus CUDA 11.0 or later or the NVHPC Package 22.7+, and any host compiler restrictions that your CUDA version imposes apply too.

The HIP module needs ROCm 6.2.0 or later, and the HIP, hipBLAS, hipSPARSE, hip/rocRAND and rocThrust packages compiled with the ROCm backend. If the hipFFT package is available it is used to implement the FFT linear operators, which is a nice detail, because it means the library uses the vendor's own FFT rather than shipping its own. The HIP module also needs cmake 3.21 or later.

The DPC++ (SYCL) module needs oneAPI 2024.1 or later, with dpcpp or icpx set as the CMAKE_CXX_COMPILER, and the oneMKL and oneDPL packages available.

The MPI module needs MPI 3.1 or later, ideally GPU-aware for the best performance, and the README says ideally GPU-Aware, for best performance.

The pattern is clear. Each backend is a separate build with its own toolchain version floor, and the cmake version required rises as the module gets more demanding, from 3.16 for the core to 3.21 for HIP. A team that keeps a single machine image with one CUDA version and one ROCm version is the kind of environment this design expects.

## Two Windows failures the README names explicitly

Most READMEs stop at the toolchain versions. This one names two specific build failures on Windows and how to get past them, and that is the sort of detail that saves a day.

The first is ld: error: export ordinal too large, which the README says needs the compilation flag -O1. The second is cc1plus.exe: out of memory allocating 65536 bytes, which requires a modification of the environment. Both are described as problems that can be encountered in these environments, with the solution given in the Windows section of INSTALL.md.

There is a third requirement worth noting, which is easy to miss because it is attached to a module rather than to the build as a whole. The OMP module on Windows has an additional requirement of MinGW, so an MSVC-only toolchain can build Ginkgo but cannot build the OpenMP executor there.

The OpenSSF Best Practices badge in the README and the presence of a sonar-project.properties file with maintainability and reliability ratings, plus a CDash dashboard, suggest a project with an established continuous integration story. The GitLab CI pipeline badge points at a separate public CI repository on GitLab, and the GitHub Actions workflow is mirrored on GitHub, so the CI runs in both places.

## Tests, examples and the benchmarking setup

Ginkgo does comprehensive unit tests using Google Test, and the tests are enabled by default. They can be turned off by passing -DGINKGO_BUILD_TESTS=NO to the cmake command, and the TESTING.md page has the details on running them.

The examples are the part of the repository that teaches. They are compiled by passing -DGINKGO_BUILD_EXAMPLES=ON, and the README says each example has commented code with explanations. The directory names listed in the repository are a good index of the library's capability, covering a minimal CUDA solver, a batched solver, distributed solvers, multigrid preconditioned and reuse variants, an ILU preconditioned solver, iterative refinement, inverse iteration, a file config solver, a custom matrix format, a custom logger, a custom stopping criterion, an external library interface, a Ginkgo overhead example, Ginkgo ranges, heat equation, a Kokkos assembly example and a script that compares output.

The benchmark side has its own directory and its own document, BENCHMARKING.md, and a CPackConfig.cmake and CTestConfig.cmake at the top level for packaging and test registration.

For contributors, the README lists the extra tooling: clang-format 14, which is downloaded automatically by pre-commit, and two optional tools, clang-tidy with the -DGINKGO_WITH_CLANG_TIDY=ON flag, and Include What You Use with -DGINKGO_WITH_IWYU=ON.

## Licensing, branches and how to cite Ginkgo

The licence is BSD-3-Clause, and the repository takes licensing seriously enough to have a dedicated ABOUT-LICENSING.md and a LICENSES directory, which is where third-party components carry their own terms. Since Ginkgo pulls in vendor libraries and open source components such as Google Test, that separation matters when a company clears a dependency for distribution.

The default branch is develop, and the CI badges in the README all point at develop, which tells you the branch under active development is the one that gets built continuously. There is a separate file, INTERFACE_CHANGE.2.md, at the top level, which is a strong hint that the project changes its public interface between major versions and expects users to read about it. The CHANGELOG.md and CITING.md files are there as well, along with a CITATION.cff for citation tooling, and a JOSS DOI badge pointing at a published software paper.

The release history shows a steady minor-version cadence: 1.11.0 on 2025-12-15, 1.10.0 on 2025-06-13 and 1.9.0 on 2024-12-09. The last push to the repository was on 2026-10-20, and the repository is not archived.

There is also a Python layer. The README badges point to a pyGinkgo package on PyPI, so the same library is reachable from Python, which matters for teams whose production code is in Python and whose solver is in C++.

## Conclusion

Ginkgo fits a numerical team with sparse problems and a heterogeneous machine, who want one algorithm implementation that runs unchanged on a CPU reference build, on OpenMP threads, or on a GPU through CUDA, HIP or SYCL, and who are willing to carry a C++17 toolchain and a CMake build. It is the wrong choice for dense linear algebra or for a small problem that fits in a laptop, and it is the wrong choice if you need a Python-only workflow with a mature scientific stack and no build step. Before adopting it, read INSTALL.md for the backend you intend to use, check the module prerequisites against your CUDA, ROCm or oneAPI versions, and read the interface change document and CITING.md, since the default branch is develop and the project is explicit about interface changes between versions.

## FAQ

### What is Ginkgo used for?

Ginkgo is a high-performance numerical linear algebra library for many-core systems, with a focus on the solution of sparse linear systems. It is implemented in modern C++ and requires a C++17 compliant compiler, with GPU kernels for NVIDIA, AMD and Intel GPUs.

### How do I build and install Ginkgo?

Use the standard CMake procedure: create a build directory, run cmake with the Unix Makefiles generator, build with cmake --build, and install with cmake --install. The Installation page in INSTALL.md has the details, and Ginkgo is then consumed with find_package(Ginkgo) and the Ginkgo::ginkgo target.

### Which GPU backends does Ginkgo support and what do they need?

The CUDA module needs CUDA 11.0 or later and cmake 3.18+, the HIP module needs ROCm 6.2.0+ with the HIP, hipBLAS, hipSPARSE, hip/rocRAND and rocThrust packages and cmake 3.21+, and the DPC++ (SYCL) module needs oneAPI 2024.1+ with oneMKL and oneDPL, using dpcpp or icpx as the CMAKE_CXX_COMPILER.

### Does Ginkgo work on Windows?

It requires cmake 3.16+ and a 64-bit C++17 compiler, either MinGW with gcc 9+ or Visual Studio 2019+. The README names two build failures to expect, an export ordinal error that needs the -O1 flag and a compiler out of memory error that needs an environment change, and the OMP module additionally requires MinGW.

### How do I run the Ginkgo tests and examples?

Unit tests use Google Test and are enabled by default, and can be disabled with -DGINKGO_BUILD_TESTS=NO. Examples are compiled with -DGINKGO_BUILD_EXAMPLES=ON, and they live in the examples directory with commented explanations in each one.

## Sources

- [ginkgo-project/ginkgo on GitHub](https://github.com/ginkgo-project/ginkgo)
- [License: BSD-3-Clause](https://github.com/ginkgo-project/ginkgo/blob/develop/LICENSE)
- [Project website](https://gko-project.org)
- [README](https://github.com/ginkgo-project/ginkgo/blob/develop/README.md)
- [Releases](https://github.com/ginkgo-project/ginkgo/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ginkgo-project-ginkgo