ginkgo-project / Ginkgo

Ginkgo is a high-performance linear algebra library for manycore systems, with a focus on sparse solution of linear systems. It is implemented using modern C++ (you will need at least C++14 compliant compiler to build it), with GPU kernels implemented in CUDA and HIP.

Performance

An extensive database of up-to-date benchmark results is available in the performance data repository. Visualizations of the database can be interactively generated using the Ginkgo Performance Explorer web application. The benchmark results are automatically updated using the CI system to always reflect the current state of the library.

Prerequisites

Linux and Mac OS

For Ginkgo core library:

• cmake 3.9+
• C++14 compliant compiler, one of:
  • gcc 5.3+, 6.3+, 7.3+, all versions after 8.1+
  • clang 3.9+
  • Intel compiler 2017+
  • Apple LLVM 8.0+ (TODO: verify)

The Ginkgo CUDA module has the following additional requirements:

• CUDA 9.0+
• 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

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

• clang-format 5.0.0+ (ships as part of clang)
• 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)

The Ginkgo HIP module has the following additional requirements:

• ROCm 2.8+
• the HIP, hipBLAS and hipSPARSE packages compiled with either: * AMD backend * CUDA 9.0+ backend. When using CUDA 10+, cmake 3.12.2+ is required.

Windows

The prequirement needs to be verified

• cmake 3.9+
• C++14 compliant 64-bit compiler:
  • MinGW : gcc 5.3+, 6.3+, 7.3+, all versions after 8.1+
  • Cygwin : gcc 5.3+, 6.3+, 7.3+, all versions after 8.1+
  • Microsoft Visual Studio : VS 2017 15.7+

NOTE: Need to add --autocrlf=input after git clone in Cygwin.

The Ginkgo CUDA module has the following additional requirements:

• CUDA 9.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 or Cygwin

Depending on the configuration settings, some manual work might be required. More details are availble in windows section in INSTALL.md:

• Build Ginkgo as shared library: Add PROJECT_BINARY_DIR/GINKGO_WINDOWS_SHARED_LIBRARY_RELPATH into the environment variable PATH. GINKGO_WINDOWS_SHARED_LIBRARY_RELPATH is windows_shared_library by default.
• Build Ginkgo with Debug mode: Some Debug build specific issues can appear depending on the machine and environment. The known issues are the following:
  1. bigobj issue: encountering too many sections needs the compilation flags \bigobj or -Wa,-mbig-obj
  2. ld issue: encountering ld: error: export ordinal too large needs the compilation flag -O1
• Build Ginkgo in MinGW: If encountering the issue cc1plus.exe: out of memory allocating 65536 bytes, please follow the workaround in reference, or compile ginkgo again might work.

NOTE: Microsoft Visual Studio only supports OpenMP 2.0, so it can not compile the ginkgo OMP module.

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

Quick Install

Building Ginkgo

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

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

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++ modules enabled to run the examples with these executors. Please refer to the Installation page for more details.

After the installation, CMake can find ginkgo with find_package(Ginkgo). An example can be found in the test_install.

Ginkgo 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. Documentation for the examples is available within the doc/ folder in each of the example directory and a commented code with explanations can found in the online documentation.

Ginkgo 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 the benchmarks

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

Contributing to Ginkgo

Contributing

When contributing for the first time, please add yourself to the list of external contributors like in the example below.

Contributors

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

Name Surname [email protected] Institution(s)

Contributing guidelines

Contributing guidelines can be accessed in the CONTRIBUTING.md page. This page also contains other information useful to developers, such as writing proper commit messages, understanding Ginkgo's library design, relevant C++ information, and more.

Support

If you have any question, bug to report or would like to propose a new feature, feel free to create an issue on GitHub. Another possibility is to send an email to Ginkgo's main email address or to contact any of the main contributors.

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.

Citing Ginkgo

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

@misc{anzt2020ginkgo,
    title={Ginkgo: A Modern Linear Operator Algebra Framework for High Performance Computing},
    author={Hartwig Anzt and Terry Cojean and Goran Flegar and Fritz Göbel and Thomas Grützmacher and Pratik Nayak and Tobias Ribizel and Yuhsiang Mike Tsai and Enrique S. Quintana-Ortí},
    year={2020},
    eprint={2006.16852},
    archivePrefix={arXiv},
    primaryClass={cs.MS}
}

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