From f1026b956caf67d67dd21c16fc319af12477d8af Mon Sep 17 00:00:00 2001 From: Pratik Nayak Date: Tue, 12 Dec 2023 08:29:53 +0100 Subject: [PATCH] Review updates Co-authored-by: Marcel Koch Co-authored-by: Yu-Hsiang Tsai Co-authored-by: Gregor Olenik --- README.md | 76 +++++++++++++++++++++++-------------------------------- 1 file changed, 32 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 2362c6f8248..49d5f23f300 100644 --- a/README.md +++ b/README.md @@ -2,43 +2,37 @@
-License|C++ Standard|Documentation|JOSS paper -:--:|:--:|:--:|:--: [![License](https://img.shields.io/github/license/ginkgo-project/ginkgo.svg)](./LICENSE)|[![c++ standard](https://img.shields.io/badge/c%2B%2B-14-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B#Standardization)|[![Documentation](https://img.shields.io/badge/Documentation-latest-blue.svg)](https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/)|[![DOI](https://joss.theoj.org/papers/10.21105/joss.02260/status.svg)](https://doi.org/10.21105/joss.02260) +|:-:|:-:|:-:|:-:| -CI builds|Coverage| Maintainability|Reliability|Dashboard -:--:|:--:|:--:|:--:|:--: -[![Build status](https://gitlab.com/ginkgo-project/ginkgo-public-ci/badges/develop/pipeline.svg)](https://github.com/ginkgo-project/ginkgo/commits/develop)[![OSX-build](https://github.com/ginkgo-project/ginkgo/actions/workflows/osx.yml/badge.svg)](https://github.com/ginkgo-project/ginkgo/actions/workflows/osx.yml)[![Windows-build](https://github.com/ginkgo-project/ginkgo/actions/workflows/windows-msvc-ref.yml/badge.svg)](https://github.com/ginkgo-project/ginkgo/actions/workflows/windows-msvc-ref.yml)|[![codecov](https://codecov.io/gh/ginkgo-project/ginkgo/branch/develop/graph/badge.svg)](https://codecov.io/gh/ginkgo-project/ginkgo)|[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=ginkgo-project_ginkgo&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=ginkgo-project_ginkgo)|[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=ginkgo-project_ginkgo&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=ginkgo-project_ginkgo)|[![CDash dashboard](https://img.shields.io/badge/CDash-Access-blue.svg)](https://my.cdash.org/index.php?project=Ginkgo+Project) +[![Build status](https://gitlab.com/ginkgo-project/ginkgo-public-ci/badges/develop/pipeline.svg)](https://gitlab.com/ginkgo-project/ginkgo-public-ci/-/pipelines?page=1&scope=branches&ref=develop)|[![OSX-build](https://github.com/ginkgo-project/ginkgo/actions/workflows/osx.yml/badge.svg)](https://github.com/ginkgo-project/ginkgo/actions/workflows/osx.yml)|[![Windows-build](https://github.com/ginkgo-project/ginkgo/actions/workflows/windows-msvc-ref.yml/badge.svg)](https://github.com/ginkgo-project/ginkgo/actions/workflows/windows-msvc-ref.yml) +|:-:|:-:|:-:| + + +[![codecov](https://codecov.io/gh/ginkgo-project/ginkgo/branch/develop/graph/badge.svg)](https://codecov.io/gh/ginkgo-project/ginkgo)|[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=ginkgo-project_ginkgo&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=ginkgo-project_ginkgo)|[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=ginkgo-project_ginkgo&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=ginkgo-project_ginkgo)|[![CDash dashboard](https://img.shields.io/badge/CDash-Access-blue.svg)](https://my.cdash.org/index.php?project=Ginkgo+Project) +|:-:|:-:|:-:|:-:|
+ 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 for NVIDIA, AMD and Intel GPUs. -Table of Contents ------------ +--- - * [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](#prerequisites)** | +**[Building Ginkgo](#building-and-installing-ginkgo)** | +**[Tests, Examples, Benchmarks](#tests-examples-and-benchmarks)** | +**[Bug reports](#bug-reports-and-support)** | +**[Licensing](#licensing)** | +**[Contributing](#contributing-to-ginkgo)** | +**[Citing](#citing-ginkgo)** -Prerequisites -------------- +# Prerequisites ### Linux and Mac OS @@ -116,15 +110,14 @@ 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. -Building and Installing 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 +cmake -G "Unix Makefiles" .. && cmake --build . +cmake --install . ``` By default, `GINKGO_BUILD_REFERENCE` is enabled. You should be able to run @@ -135,11 +128,10 @@ run the examples with these executors. Please refer to the [Installation page](./INSTALL.md) for more details. -Tip: After installation, in your CMake project, Ginkgo can be added with `find_package(Ginkgo)`. +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`](test/test_install/CMakeLists.txt). -Tests, Examples and Benchmarks ------------------------------------ +# Tests, Examples and Benchmarks ### Testing @@ -147,7 +139,7 @@ Ginkgo does comprehensive unit tests using Google Tests. These tests are enabled ### 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). +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](https://ginkgo-project.github.io/ginkgo-generated-documentation/doc/develop/Examples.html). ### Benchmarking @@ -156,18 +148,15 @@ with the help of the [Ginkgo Performance Explorer (GPE)](https://ginkgo-project. More details about this can be found in the [BENCHMARKING.md page](./BENCHMARKING.md) -Bug reports and Support -------------------------- +# Bug reports and Support If you have any questions about using Ginkgo, please use [Github discussions](https://github.com/ginkgo-project/ginkgo/discussions). -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. +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:ginkgo.library@gmail.com) or to contact any of the main [contributors](contributors.txt). +You can also send an email to [Ginkgo's main email address](mailto:ginkgo.library@gmail.com). -Licensing ----------- +# Licensing Ginkgo is available under the [3-clause BSD license](LICENSE). All contributions to the project are added under this license. @@ -177,10 +166,11 @@ 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 -------------------------- +# 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 +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 ``` text Name Surname Institution(s) @@ -193,7 +183,6 @@ Ginkgo's source is distributed with a BSD-3 clause license. By contributing to G ``` 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 @@ -203,8 +192,7 @@ When contributing to Ginkgo, to ease the review process, please follow the guide It also contains other general recommendations such as writing proper commit messages, understanding Ginkgo's library design, relevant C++ information etc. -Citing Ginkgo ---------------- +# Citing Ginkgo The main Ginkgo paper describing Ginkgo's purpose, design and interface is available through the following reference: