-
Notifications
You must be signed in to change notification settings - Fork 88
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
73 additions
and
50 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,29 +1,41 @@ | ||
| <p align="center"><img src="/assets/logo.png" alt="Ginkgo" width="60%" height="60%"></p> | ||
|
|
||
| <div align="center"> | ||
|
|
||
| License|C++ Standard|Documentation|JOSS paper | ||
| :--:|:--:|:--:|:--: | ||
| [](./LICENSE)|[](https://en.wikipedia.org/wiki/C%2B%2B#Standardization)|[](https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/)|[](https://doi.org/10.21105/joss.02260) | ||
|
|
||
|
|
||
| CI builds|Coverage| Maintainability|Reliability|Dashboard | ||
| :--:|:--:|:--:|:--:|:--: | ||
| [](https://github.com/ginkgo-project/ginkgo/commits/develop)[](https://github.com/ginkgo-project/ginkgo/actions/workflows/osx.yml)[](https://github.com/ginkgo-project/ginkgo/actions/workflows/windows-msvc-ref.yml)|[](https://codecov.io/gh/ginkgo-project/ginkgo)|[](https://sonarcloud.io/dashboard?id=ginkgo-project_ginkgo)|[](https://sonarcloud.io/dashboard?id=ginkgo-project_ginkgo)|[](https://my.cdash.org/index.php?project=Ginkgo+Project) | ||
|
|
||
| </div> | ||
|
|
||
| Ginkgo is a high-performance linear algebra library for many-core systems, with a | ||
| focus on the solution of sparse linear systems. It is implemented using modern C++ | ||
| 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++14 compliant compiler to build it), with GPU kernels | ||
| implemented in CUDA, HIP, and DPC++(SYCL). | ||
|
|
||
| implemented for NVIDIA, AMD and Intel GPUs. | ||
|
|
||
| Performance | ||
| Table of Contents | ||
| ----------- | ||
|
|
||
| An extensive database of up-to-date benchmark results is available in the | ||
| [performance data repository](https://github.com/ginkgo-project/ginkgo-data). | ||
| Visualisations of the database can be interactively generated using the | ||
| [Ginkgo Performance Explorer web application](https://ginkgo-project.github.io/gpe). | ||
| The benchmark results are automatically updated using the CI system to always | ||
| reflect the current state of the library. | ||
| * [Prerequisites](#prerequisites) | ||
| * [Linux and Mac OS](#linux-and-mac-os) | ||
| * [Windows](#windows) | ||
| * [Building and Installing Ginkgo](#building-and-installing-ginkgo) | ||
| * [Tests, Examples and Benchmarks](#testing-examples-and-benchmarks) | ||
| * [Testing](#testing) | ||
| * [Running Examples](#running-examples) | ||
| * [Benchmarking](#benchmarking) | ||
| * [Bug reports and support](#bug-reports-and-support) | ||
| * [Licensing](#licensing) | ||
| * [Contributing to Ginkgo](#contributing-to-ginkgo) | ||
| * [Declaration](#declaration) | ||
| * [Contribution Guidelines](#contribution-guidelines) | ||
| * [Citing Ginkgo](#citing-ginkgo) | ||
|
|
||
|
|
||
| Prerequisites | ||
| ------------- | ||
|
|
@@ -104,73 +116,58 @@ In these environments, two problems can be encountered, the solution for which i | |
| __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 | ||
| Building and Installing Ginkgo | ||
| --------------------------------- | ||
|
|
||
| To build Ginkgo, you can use the standard CMake procedure. | ||
|
|
||
| ```sh | ||
| mkdir build; cd build | ||
| cmake -G "Unix Makefiles" .. && make | ||
| make install # will install to the system default location | ||
| ``` | ||
|
|
||
| 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](./INSTALL.md) for more details. | ||
| run the examples with these executors. | ||
|
|
||
| After the installation, CMake can find ginkgo with `find_package(Ginkgo)`. | ||
| An example can be found in the [`test_install`](test/test_install/CMakeLists.txt). | ||
| Please refer to the [Installation page](./INSTALL.md) for more details. | ||
|
|
||
| ### Ginkgo Examples | ||
| Tip: After installation, in your CMake project, Ginkgo can be added with `find_package(Ginkgo)`. | ||
| An example can be found in the [`test_install`](test/test_install/CMakeLists.txt). | ||
|
|
||
| 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](https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/Examples.html). | ||
| Tests, Examples and Benchmarks | ||
| ----------------------------------- | ||
|
|
||
| ### Ginkgo Testing | ||
| ### 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](./TESTING.md). | ||
|
|
||
| ### Running the benchmarks | ||
| ### 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. 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](https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/Examples.html). | ||
|
|
||
| ### 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)](https://ginkgo-project.github.io/gpe/). | ||
|
|
||
| More details about this can be found in the [BENCHMARKING.md page](./BENCHMARKING.md) | ||
|
|
||
| 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](./LICENSE) file. | ||
|
|
||
| Name Surname <email@domain> Institution(s) | ||
|
|
||
| #### Contributing guidelines | ||
| Bug reports and Support | ||
| ------------------------- | ||
|
|
||
| Contributing guidelines can be accessed in the [CONTRIBUTING.md | ||
| page](./CONTRIBUTING.md). 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. | ||
| If you have any questions about using Ginkgo, please use [Github discussions](https://github.com/ginkgo-project/ginkgo/discussions). | ||
|
|
||
| ### 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](https://github.com/ginkgo-project/ginkgo/issues/new). Another possibility | ||
| is to send an email to [Ginkgo's main email address](mailto:[email protected]) | ||
| or to contact any of the main [contributors](contributors.txt). | ||
| If you would like to request a feature, or have encountered a bug, please [create an | ||
| issue](https://github.com/ginkgo-project/ginkgo/issues/new). 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](mailto:[email protected]) or to contact any of the main [contributors](contributors.txt). | ||
|
|
||
| ### Licensing | ||
| Licensing | ||
| ---------- | ||
|
|
||
| Ginkgo is available under the [3-clause BSD license](LICENSE). All contributions | ||
| to the project are added under this license. | ||
|
|
@@ -180,8 +177,34 @@ software may be pulled as additional dependencies, which have their own | |
| licensing conditions. Refer to [ABOUT-LICENSING.md](ABOUT-LICENSING.md) for | ||
| details. | ||
|
|
||
| Contributing to Ginkgo | ||
| ------------------------- | ||
|
|
||
| We are glad that that you would like to contribute to Ginkgo! If you are contributing for the first time, please add yourself to the list of external contributors with the following info | ||
|
|
||
| ``` text | ||
| 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](contributors.txt)): | ||
|
|
||
| ``` text | ||
| 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](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: | ||
|
|
||