Skip to content

Commit

Permalink
Add some status badges
Browse files Browse the repository at this point in the history
  • Loading branch information
niermann999 committed Jan 21, 2025
1 parent f4d81d9 commit 614a277
Showing 1 changed file with 17 additions and 13 deletions.
30 changes: 17 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,14 @@
# detray

[![Test Status](https://github.com/acts-project/detray/actions/workflows/builds.yml/badge.svg?branch=main)](https://github.com/acts-project/detray/actions/workflows/builds.yml)
[![Lint Status](https://github.com/acts-project/detray/actions/workflows/checks.yml/badge.svg?branch=main)](https://github.com/acts-project/detray/actions/workflows/checks.yml)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=acts-project_detray&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=acts-project_detray)

Detray is part of the [ACTS project](https://github.com/acts-project/acts) (R&D line for parallelization).

This is a C++20 header-only library providing a GPU-friendly tracking detector description using different [linear algebra](https://github.com/acts-project/algebra-plugins) libraries. It follows the navigation and propagation concept of ACTS, however, implementing a geometry using a flat memory layout and no abstract interfaces (virtual functions). A detray detector can therefore be constructed on the host and copied to an accelerator device in a straight-forward way.
This is a C++20 header-only library providing a GPU-friendly tracking detector description using different [linear algebra](https://github.com/acts-project/algebra-plugins) libraries. It follows the navigation and propagation concept of ACTS, implementing a geometry using a flat memory layout and no abstract interfaces (virtual functions). A detray detector can therefore be constructed on the host and copied to an accelerator device in a straight-forward way.

With the geometry description comes a fully featured, GPU-ready track state propagation implementation in inhomogeneous magnetic fields, with track parameter covariance transport including material interactions.
With the geometry description comes a fully featured, GPU-ready track state propagation implementation in inhomogeneous magnetic fields (vector field description using [covfie](https://github.com/acts-project/covfie)), with track parameter covariance transport including material interactions.

## Requirements and Dependencies
#### OS & Compilers:
Expand All @@ -13,7 +17,7 @@ With the geometry description comes a fully featured, GPU-ready track state prop
- The CUDA Toolkit version must be greater than major version 11

#### Dependencies:
- CMake (version >= 3.11)
- CMake (version >= 3.14, version >= 3.18 for CUDA)


## Getting started
Expand All @@ -27,7 +31,7 @@ cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -S detray -B detray-build
cmake --build detray-build
```

For unit and integration tests using the *Open Data Detector* (ODD) solenoid field, a magnetic field map file in [covfie](https://github.com/acts-project/covfie) format needs to be downloaded and the corresponding environment variable should be set to:
For unit and integration tests using the *Open Data Detector* (ODD) solenoid field, a magnetic field map file in covfie format needs to be downloaded and the corresponding environment variable should be set to:
```shell
cd detray/data
bash detray_data_get_files.sh
Expand All @@ -40,7 +44,7 @@ A number of cmake preset configurations are provided and can be listed by:
```shell
cmake -S detray --list-presets
```
For a developer build, the ```dev-fp32``` and ```dev-fp64``` configurations are available (```fp```: floating point precision):
For a developer build, the `dev-fp32` and `dev-fp64` configurations are available (`fp`: floating point precision):
```shell
cmake -S detray -B detray-build --preset dev-fp32
```
Expand All @@ -49,7 +53,7 @@ The developer presets will fetch all dependencies, but not automatically trigger
cmake -S detray -B detray-build --preset dev-fp32 \
-DDETRAY_BUILD_UNITTESTS=ON
```
A full build, containing all components (e.g. tests and benchmarks), can be configured using the ```full-fp32``` and ```full-fp64``` presets.
A full build, containing all components (e.g. tests and benchmarks), can be configured using the `full-fp32` and `full-fp64` presets.

The following cmake options are available and can also be specified explicitly for any preset:

Expand All @@ -74,18 +78,18 @@ The following cmake options are available and can also be specified explicitly f

## Detector Validation

Given a detray detector (and optionally also a grid and a material) json file, a number of validation test can be run from the command-line. For this, the library has to be built with the ```-DDETRAY_BUILD_CLI_TOOLS=ON``` option enabled. An example detector file can then be obtained using e.g.
Given a detray detector (and optionally also a grid and a material) json file, a number of validation test can be run from the command-line. For this, the library has to be built with the `-DDETRAY_BUILD_CLI_TOOLS=ON` option enabled. An example detector file can then be obtained using e.g.
```shell
detray-build/bin/detray_generate_toy_detector --write_material --write_grids
```
All of the validation tools presented in the following can also be run as part of a corresponding python script which takes the same arguments and will automatically create plots from the collected data. However, this requires Python 3, pandas, SciPy and NumPy, as well as Matplotlib to be available.
All of the validation tools presented in the following can also be run as part of a corresponding [python script](https://github.com/acts-project/detray/tree/main/tests/tools/python) which takes the same arguments and will automatically create plots from the collected data. However, this requires Python 3, pandas, SciPy and NumPy, as well as Matplotlib to be available.

The detector geometry can be visualized in svg format with the following command:
The detector geometry can be visualized in SVG format with the following command:
```shell
detray-build/bin/detray_detector_display \
--geometry_file ./toy_detector/toy_detector_geometry.json
```
The tool can also display single volumes or surfaces, as well as the navigation grids and material maps (the corresponding json files need to loaded in this case). For an overview of all available options for the command-line tools add ```--help```.
The tool can also display single volumes or surfaces, as well as the navigation grids and material maps (the corresponding json files need to loaded in this case). For an overview of all available options for the command-line tools add `--help`.

### Navigation Validation

Expand All @@ -96,7 +100,7 @@ detray-build/bin/detray_detector_validation \
--grid_file ./toy_detector/toy_detector_surface_grids.json \
--search_window 3 3 --n_tracks 100 --pT_range 0.5 100
```
In case of failures, this command will give a detailed debug output in the form of a log file, as well as an svg representation of the failed tracks. The grid file is optional, but will trigger the use of spacial grids as acceleration structures during the navigation run.
In case of failures, this command will give a detailed debug output in the form of a log file, as well as an SVG representation of the failed tracks. The grid file is optional, but will trigger the use of spacial grids as acceleration structures during the navigation run.

### Material Validation

Expand All @@ -112,15 +116,15 @@ Note: The correct material file must be loaded in addition to the geometry file!

## Benchmarks

A number of benchmarks exist, which are based on the google benchmark library, and can be run from command-line. For this, the ```-DDETRAY_BUILD_BENCHMARKS=ON``` and ``` -DDETRAY_BUILD_CLI_TOOLS=ON``` flags need to be specified. Then pass the detray detector file(s) and additional options to the benchmark tools for the different hardware backends:
A number of benchmarks exist, which are based on the google benchmark library, and can be run from command-line. For this, the `-DDETRAY_BUILD_BENCHMARKS=ON` and `-DDETRAY_BUILD_CLI_TOOLS=ON` flags need to be specified. Then pass the detray detector file(s) and additional options to the benchmark tools for the different hardware backends:
```shell
detray-build/bin/detray_propagation_benchmark_<backend>_<algebra> \
--geometry_file ./toy_detector/toy_detector_geometry.json \
--grid_file ./toy_detector/toy_detector_surface_grids.json \
--material_file ./toy_detector/toy_detector_homogeneous_material.json \
--sort_tracks --randomize_charge --eta_range -3 3 -pT_range 1 100
```
For every algebra-plugin that was built, a corresponding benchmark executable will be present. The CPU-backend benchmark is built by default and the CUDA-backend benchmark will be available if detray was built with CUDA enabled (```-DDETRAY_BUILD_CUDA=ON```).
For every algebra-plugin that was built, a corresponding benchmark executable will be present. The CPU-backend benchmark is built by default and the CUDA-backend benchmark will be available if detray was built with CUDA enabled (`-DDETRAY_BUILD_CUDA=ON`).

### Continuous benchmark

Expand Down

0 comments on commit 614a277

Please sign in to comment.