/ginkgo

Numerical linear algebra software package

Primary LanguageC++BSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

Ginkgo

License c++ standard Documentation DOI
Build status OSX-build codecov Maintainability Rating Reliability Rating CDash dashboard

Ginkgo is a high-performance numerical linear algebra library for many-core systems, with a focus on solution of sparse linear systems. It is implemented using modern C++ (you will need an at least C++17 compliant compiler to build it), with GPU kernels implemented for NVIDIA, AMD and Intel GPUs.

Prerequisites | Building Ginkgo | Tests, Examples, Benchmarks | Bug reports | Licensing | Contributing | Citing

Prerequisites

Linux and Mac OS

For Ginkgo core library:

  • cmake 3.16+
  • C++17 compliant compiler, one of:
    • gcc 7+
    • clang 5+
    • Intel compiler 2019+
    • Apple Clang 15.0 is tested. Earlier versions might also work.
    • Cray Compiler 14.0.1+
    • NVHPC Compiler 22.7+

The Ginkgo CUDA module has the following additional requirements:

  • cmake 3.18+ (If CUDA was installed through the NVIDIA HPC Toolkit, we require cmake 3.22+)
  • CUDA 11.0+ or NVHPC Package 22.7+
  • Any host compiler restrictions your version of CUDA may impose also apply here. For the newest CUDA version, this information can be found in the CUDA installation guide for Linux or CUDA installation guide for Mac Os X

The Ginkgo HIP module has the following additional requirements:

  • ROCm 4.5+
  • 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 LinOps.
  • cmake 3.21+

The Ginkgo DPC++(SYCL) module has the following additional requirements:

  • oneAPI 2023.1+
  • Set dpcpp or icpx as the CMAKE_CXX_COMPILER
  • The following oneAPI packages should be available:
    • oneMKL
    • oneDPL

The Ginkgo MPI module has the following additional requirements:

  • MPI 3.1+, ideally GPU-Aware, for best performance

In addition, if you want to contribute code to Ginkgo, you will also need the following:

  • clang-format 14 (downloaded automatically by pre-commit)
  • clang-tidy (optional, when setting the flag -DGINKGO_WITH_CLANG_TIDY=ON)
  • iwyu (Include What You Use, optional, when setting the flag -DGINKGO_WITH_IWYU=ON)

Windows

  • cmake 3.16+
  • C++17 compliant 64-bit compiler:
    • MinGW : gcc 7+
    • Microsoft Visual Studio : VS 2019+

The Ginkgo CUDA module has the following additional requirements:

  • CUDA 11.0+
  • Microsoft Visual Studio
  • Any host compiler restrictions your version of CUDA may impose also apply here. For the newest CUDA version, this information can be found in the CUDA installation guide for Windows

The Ginkgo OMP module has the following additional requirements:

  • MinGW

In these environments, two problems can be encountered, the solution for which is described in the windows section in INSTALL.md:

  • ld: error: export ordinal too large needs the compilation flag -O1
  • cc1plus.exe: out of memory allocating 65536 bytes requires a modification of the environment

NOTE: Some restrictions will also apply on the version of C and C++ standard libraries installed on the system. This needs further investigation.

Building and Installing Ginkgo

To build Ginkgo, you can use the standard CMake procedure.

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

By default, GINKGO_BUILD_REFERENCE is enabled. You should be able to run examples with this executor. By default, Ginkgo tries to enable the relevant modules depending on your machine environment (present of CUDA, ...). You can also explicitly compile with the OpenMP, CUDA, HIP or DPC++(SYCL) modules enabled to run the examples with these executors.

Please refer to the Installation page for more details.

Tip: After installation, in your CMake project, Ginkgo can be added with find_package(Ginkgo) and the the target that is exported is Ginkgo::ginkgo. An example can be found in the test_install.

Tests, Examples and Benchmarks

Testing

Ginkgo does comprehensive unit tests using Google Tests. These tests are enabled by default and can be disabled if necessary by passing the -DGINKGO_BUILD_TESTS=NO to the cmake command. More details about running tests can be found in the TESTING.md page.

Running examples

Various examples are available for you to understand and play with Ginkgo within the examples/ directory. They can be compiled by passing the -DGINKGO_BUILD_EXAMPLES=ON to the cmake command. Each of the examples have commented code with explanations and this can be found within the online documentation.

Benchmarking

A unique feature of Ginkgo is the ability to run benchmarks and view your results with the help of the Ginkgo Performance Explorer (GPE).

More details about this can be found in the BENCHMARKING.md page

Bug reports and Support

If you have any questions about using Ginkgo, please use Github discussions.

If you would like to request a feature, or have encountered a bug, please create an issue. Please be sure to describe your problem and provide as much information as possible.

You can also send an email to Ginkgo's main email address.

Licensing

Ginkgo is available under the 3-clause BSD license. All contributions to the project are added under this license.

Depending on the configuration options used when building Ginkgo, third party software may be pulled as additional dependencies, which have their own licensing conditions. Refer to ABOUT-LICENSING.md for details.

Contributing to Ginkgo

We are glad that that you would like to contribute to Ginkgo and we are happy to help you with any questions you may have.

If you are contributing for the first time, please add yourself to the list of external contributors with the following info

Name Surname <email@domain> Institution(s)

Declaration

Ginkgo's source is distributed with a BSD-3 clause license. By contributing to Ginkgo and adding yourself to the contributors list, you agree to the following statement (also in contributors.txt):

I hereby place all my contributions in this codebase under a BSD-3-Clause
license, as specified in the repository's LICENSE file.

Contribution Guidelines

When contributing to Ginkgo, to ease the review process, please follow the guidelines mentioned in CONTRIBUTING.md.

It also contains other general recommendations such as writing proper commit messages, understanding Ginkgo's library design, relevant C++ information etc.

Citing Ginkgo

The main Ginkgo paper describing Ginkgo's purpose, design and interface is available through the following reference:

@article{ginkgo-toms-2022,
title = {{Ginkgo: A Modern Linear Operator Algebra Framework for High Performance Computing}},
volume = {48},
copyright = {All rights reserved},
issn = {0098-3500},
shorttitle = {Ginkgo},
url = {https://doi.org/10.1145/3480935},
doi = {10.1145/3480935},
number = {1},
urldate = {2022-02-17},
journal = {ACM Transactions on Mathematical Software},
author = {Anzt, Hartwig and Cojean, Terry and Flegar, Goran and Göbel, Fritz and Grützmacher, Thomas and Nayak, Pratik and Ribizel, Tobias and Tsai, Yuhsiang Mike and Quintana-Ortí, Enrique S.},
month = feb,
year = {2022},
keywords = {ginkgo, healthy software lifecycle, High performance computing, multi-core and manycore architectures},
pages = {2:1--2:33}
}

For more information on topical subjects, please refer to the CITING.md page.