From f7bb72606c70e455a201d008a80dde4a5cfb1b45 Mon Sep 17 00:00:00 2001 From: Joana Niermann Date: Mon, 20 Jan 2025 16:57:28 +0100 Subject: [PATCH 1/4] Describe how to run the validation tools --- README.md | 39 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4632c55b9..418d44f66 100644 --- a/README.md +++ b/README.md @@ -70,8 +70,45 @@ The following cmake options are available and can also be specified explicitly f | DETRAY_VC_SOA_PLUGIN | Build Vc based SoA math plugin (currently only supports the ray-surface intersectors) | OFF | | DETRAY_SVG_DISPLAY | Build ActSVG display module | OFF | +## Detector Validation + +Given a 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``` flag. And 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. + +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 [OPTION]... +``` +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). + +### Navigation Validation + +In order to validate that the navigation works correctly in a given detector geometry, run the detector validation tool. It will first perform a consistency check on the detector, followed by a "ray scan" of the detector. The scan result will be compared to a full straight-line navigation run for every ray. After that, the navigation in a constant magnetic field of 2T is being tested in a similar fashion, using parameterized helix trajectories and a Newton-Raphson/Bisection algorithm to generate the truth intersections. For example: +```shell +detray-build/bin/detray_detector_validation \ + --geometry_file ./toy_detector/toy_detector_geometry.json \ + --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. + +### Material Validation + +This tool checks whether the navigator picks up the material correctly by comparing the material found during a ray scan with the material collected during navigation by a specialized actor: +```shell +detray-build/bin/detray_material_validation \ + --geometry_file toy_detector/toy_detector_geometry.json \ + --material_file toy_detector/toy_detector_homogeneous_material.json \ + --phi_steps 100 --eta_steps 100 --eta_range -4 4 +``` +Note: The correct material file must be loaded in addition to the geometry file! + ## Continuous benchmark -Monitoring the propagation speed with the toy geometry +Monitoring the propagation throughput with the toy geometry From 89f44614ff632521b40e24872d2bc201b1ea5be7 Mon Sep 17 00:00:00 2001 From: Joana Niermann Date: Mon, 20 Jan 2025 18:07:32 +0100 Subject: [PATCH 2/4] Add instructions for the benchmarks --- README.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 418d44f66..71cfd4f31 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ a geometry without polymorphic inheritance structure. ## Getting started -The respository is meant to be possible to build "out of the box", with standard +The respository should build "out of the box", with standard CMake build procedures. ```shell @@ -72,7 +72,7 @@ The following cmake options are available and can also be specified explicitly f ## Detector Validation -Given a 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``` flag. And 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``` flag. And example detector file can then be obtained using e.g. ```shell detray-build/bin/detray_generate_toy_detector --write_material --write_grids ``` @@ -107,8 +107,20 @@ detray-build/bin/detray_material_validation \ ``` Note: The correct material file must be loaded in addition to the geometry file! -## Continuous benchmark +## Benchmarks -Monitoring the propagation throughput with the toy geometry +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__ \ + --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```). + +### Continuous benchmark + +Monitoring the propagation throughput with the toy geometry per commit: From f4d81d911f624e2abc3061e5a8ad6b351272f537 Mon Sep 17 00:00:00 2001 From: Joana Niermann Date: Mon, 20 Jan 2025 18:45:10 +0100 Subject: [PATCH 3/4] Some general updates --- README.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 71cfd4f31..7e6f70fd2 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,20 @@ # detray -Detray is part of the ACTS project (R&D line for parallelization), the ACTS project can be found: https://github.com/acts-project/acts. +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 for detector surface intersections using different algebra plugin libraries. It follows the navigation and propagation concept of ACTS, however, with an attempt to create -a geometry without polymorphic inheritance structure. +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. +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. -## Requirements and dependencies -#### OS & compilers: +## Requirements and Dependencies +#### OS & Compilers: - The C++ compiler must support C++20 - The CUDA Toolkit version must be greater than major version 11 -#### Dependency -- CMake +#### Dependencies: +- CMake (version >= 3.11) + ## Getting started @@ -26,7 +27,7 @@ cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -S detray -B detray-build cmake --build detray-build ``` -For tests and benchmarks with the inhomogeneous magnetic field, the ODD field in covfie format should be downloaded and the environment variable should be set. +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: ```shell cd detray/data bash detray_data_get_files.sh @@ -70,9 +71,10 @@ The following cmake options are available and can also be specified explicitly f | DETRAY_VC_SOA_PLUGIN | Build Vc based SoA math plugin (currently only supports the ray-surface intersectors) | OFF | | DETRAY_SVG_DISPLAY | Build ActSVG display module | OFF | + ## 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``` flag. And 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 ``` @@ -81,9 +83,9 @@ All of the validation tools presented in the following can also be run as part o 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 [OPTION]... + --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). +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 @@ -107,6 +109,7 @@ detray-build/bin/detray_material_validation \ ``` 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: From 614a2770dba8b7d88c079688f237d07bf0cc9acb Mon Sep 17 00:00:00 2001 From: Joana Niermann Date: Mon, 20 Jan 2025 19:12:38 +0100 Subject: [PATCH 4/4] Add some status badges --- README.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 7e6f70fd2..bc0d3b0c1 100644 --- a/README.md +++ b/README.md @@ -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: @@ -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 @@ -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 @@ -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 ``` @@ -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: @@ -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 @@ -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 @@ -112,7 +116,7 @@ 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__ \ --geometry_file ./toy_detector/toy_detector_geometry.json \ @@ -120,7 +124,7 @@ detray-build/bin/detray_propagation_benchmark__ \ --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