Warning, /acts/Traccc/README.md is written in an unsupported language. File is not indexed.
0001 # traccc
0002
0003 Demonstrator tracking chain for accelerators.
0004
0005 ## Features
0006
0007 | Category | Algorithms | CPU | CUDA | SYCL | Alpaka |
0008 | ------------------------- | ---------------------- | --- | ---- | ---- | ------ |
0009 | **Clusterization** | CCL / FastSv / etc. | ✅ | ✅ | ✅ | ✅ |
0010 | | Measurement creation | ✅ | ✅ | ✅ | ✅ |
0011 | **Seeding** | Spacepoint formation | ✅ | ✅ | ✅ | ✅ |
0012 | | Spacepoint binning | ✅ | ✅ | ✅ | ✅ |
0013 | | Seed finding | ✅ | ✅ | ✅ | ✅ |
0014 | | Track param estimation | ✅ | ✅ | ✅ | ✅ |
0015 | **Track finding** | Combinatorial KF | ✅ | ✅ | ✅ | ✅ |
0016 | **Ambiguity resolution** | Greedy resolver | ✅ | 🟡 | ⚪ | ⚪ |
0017 | **Track fitting** | KF | ✅ | ✅ | 🟡 | ✅ |
0018
0019 ✅: exists, 🟡: work started, ⚪: work not started yet
0020
0021 The relations between datatypes and algorithms is given in the (approximately
0022 commutative) diagram shown below. Black lines indicate CPU algorithms, green
0023 lines indicate CUDA algorithms, blue lines indicate SYCL algorithms. Solid algorithms are ready for use, dashed
0024 algorithms are in development or future goals. Data types for different
0025 heterogeneous platforms are contracted for legibility, and identities are
0026 hidden.
0027
0028 ```mermaid
0029 flowchart LR
0030 subgraph clusterization [<a href='https://github.com/acts-project/traccc/blob/main/core/include/traccc/clusterization/'>Clusterization</a>]
0031 direction TB
0032 cell(Cells);
0033 cluster(Clusters);
0034 meas(Measurements);
0035 end
0036
0037 subgraph trkfinding [<a href='https://github.com/acts-project/traccc/blob/main/core/include/traccc/finding/'>Track Finding</a>]
0038 sp(Spacepoints);
0039 bin(Spacepoint Grid);
0040 seed(Seeds);
0041 ptrack(Prototracks);
0042 end
0043
0044 subgraph trkfitting [<a href='https://github.com/acts-project/traccc/blob/main/core/include/traccc/fitting/'>Track Fitting</a>]
0045 trackc(Track Candidates)
0046 tracks(Track States);
0047 end
0048
0049 click cell href "https://github.com/acts-project/traccc/blob/main/core/include/traccc/edm/silicon_cell_collection.hpp";
0050 click cluster href "https://github.com/acts-project/traccc/blob/main/core/include/traccc/edm/silicon_cluster_collection.hpp";
0051 click meas href "https://github.com/acts-project/traccc/blob/main/core/include/traccc/edm/measurement.hpp";
0052 click sp href "https://github.com/acts-project/traccc/blob/main/core/include/traccc/edm/spacepoint.hpp";
0053 click bin href "https://github.com/acts-project/traccc/blob/main/core/include/traccc/seeding/detail/spacepoint_grid.hpp";
0054 click seed href "https://github.com/acts-project/traccc/blob/main/core/include/traccc/edm/seed.hpp";
0055 click ptrack href "https://github.com/acts-project/traccc/blob/main/core/include/traccc/edm/track_parameters.hpp";
0056 click trackc href "https://github.com/acts-project/traccc/blob/main/core/include/traccc/edm/track_candidate.hpp";
0057 click tracks href "https://github.com/acts-project/traccc/blob/main/core/include/traccc/edm/track_state.hpp";
0058
0059 %% Host CCL algorithm
0060 cell -->|<a href='https://github.com/acts-project/traccc/blob/main/core/include/traccc/clusterization/sparse_ccl_algorithm.hpp'>Sparse CCL</a>| cluster;
0061 linkStyle 0 stroke: black;
0062
0063 %% Host measurement creation
0064 cluster -->|<a href='https://github.com/acts-project/traccc/blob/main/core/include/traccc/clusterization/measurement_creation_algorithm.hpp'>Meas. Creat.</a>| meas;
0065 linkStyle 1 stroke: black;
0066
0067 %% SYCL clusterization
0068 cell -->|<a href='https://github.com/acts-project/traccc/blob/main/device/sycl/include/traccc/sycl/clusterization/clusterization_algorithm.hpp'>Clustering</a>| meas;
0069 linkStyle 2 stroke: blue;
0070
0071 %% CUDA clusterization
0072 cell -->|<a href='https://github.com/acts-project/traccc/blob/main/device/cuda/include/traccc/cuda/clusterization/clusterization_algorithm.hpp'>Clustering</a>| meas;
0073 linkStyle 3 stroke: green;
0074
0075 %% Alpaka clusterization
0076 cell -->|<a href='https://github.com/acts-project/traccc/blob/main/device/alpaka/include/traccc/alpaka/clusterization/clusterization_algorithm.hpp'>Clustering</a>| meas;
0077 linkStyle 4 stroke: orange;
0078
0079 %% Host spacepoint formation
0080 meas -->|<a href='https://github.com/acts-project/traccc/blob/main/core/include/traccc/seeding/silicon_pixel_spacepoint_formation_algorithm.hpp'>SP Form.</a>| sp;
0081 linkStyle 5 stroke: black;
0082
0083 %% SYCL spacepoint formation
0084 meas -->|<a href='https://github.com/acts-project/traccc/blob/main/device/sycl/include/traccc/sycl/seeding/silicon_pixel_spacepoint_formation_algorithm.hpp'>SP Form.</a>| sp;
0085 linkStyle 6 stroke: blue;
0086
0087 %% CUDA spacepoint formation
0088 meas -->|<a href='https://github.com/acts-project/traccc/blob/main/device/cuda/include/traccc/cuda/seeding/spacepoint_formation_algorithm.hpp'>SP Form.</a>| sp;
0089 linkStyle 7 stroke: green;
0090
0091 %% Alpaka spacepoint formation
0092 meas -->|<a href='https://github.com/acts-project/traccc/blob/main/device/alpaka/include/traccc/alpaka/seeding/spacepoint_formation_algorithm.hpp'>SP Form.</a>| sp;
0093 linkStyle 8 stroke: orange;
0094
0095 %% Host spacepoint binning
0096 sp -->|<a href='https://github.com/acts-project/traccc/blob/main/core/include/traccc/seeding/spacepoint_binning.hpp'>SP Binning</a>| bin;
0097 linkStyle 9 stroke: black;
0098
0099 %% SYCL triplet seeding
0100 sp -->|<a href='https://github.com/acts-project/traccc/blob/main/device/sycl/include/traccc/sycl/seeding/triplet_seeding_algorithm.hpp'>Triplet Seeding</a>| seed;
0101 linkStyle 10 stroke: blue;
0102
0103 %% CUDA triplet seeding
0104 sp -->|<a href='https://github.com/acts-project/traccc/blob/main/device/cuda/include/traccc/cuda/seeding/triplet_seeding_algorithm.hpp'>Triplet Seeding</a>| seed;
0105 linkStyle 11 stroke: green;
0106
0107 %% Alpaka triplet seeding
0108 sp -->|<a href='https://github.com/acts-project/traccc/blob/main/device/alpaka/include/traccc/alpaka/seeding/triplet_seeding_algorithm.hpp'>Triplet Seeding</a>| seed;
0109 linkStyle 12 stroke: orange;
0110
0111 %% Host seeding
0112 bin -->|<a href='https://github.com/acts-project/traccc/blob/main/core/include/traccc/seeding/seed_finding.hpp'>Seeding</a>| seed;
0113 linkStyle 13 stroke: black;
0114
0115 %% Host param est.
0116 seed -->|<a href='https://github.com/acts-project/traccc/blob/main/core/include/traccc/seeding/track_params_estimation.hpp'>Param. Est.</a>| ptrack;
0117 linkStyle 14 stroke: black;
0118
0119 %% SYCL param est.
0120 seed -->|<a href='https://github.com/acts-project/traccc/blob/main/device/sycl/include/traccc/sycl/seeding/track_params_estimation.hpp'>Param. Est.</a>| ptrack;
0121 linkStyle 15 stroke: blue;
0122
0123 %% CUDA param est.
0124 seed -->|<a href='https://github.com/acts-project/traccc/blob/main/device/cuda/include/traccc/cuda/seeding/track_params_estimation.hpp'>Param. Est.</a>| ptrack;
0125 linkStyle 16 stroke: green;
0126
0127 %% Alpaka param est.
0128 seed -->|<a href='https://github.com/acts-project/traccc/blob/main/device/alpaka/include/traccc/alpaka/seeding/track_params_estimation.hpp'>Param. Est.</a>| ptrack;
0129 linkStyle 17 stroke: orange;
0130
0131 %% Host CKF
0132 ptrack -->|<a href='https://github.com/acts-project/traccc/blob/main/core/include/traccc/finding/combinatorial_kalman_filter_algorithm.hpp'>CKF</a>| trackc;
0133 linkStyle 18 stroke: black;
0134
0135 %% Host Kalman filter
0136 trackc -->|<a href='https://github.com/acts-project/traccc/blob/main/core/include/traccc/fitting/kalman_fitting_algorithm.hpp'>Kalman filter</a>| tracks;
0137 linkStyle 19 stroke: black;
0138
0139 %% SYCL CKF
0140 ptrack -->|<a href='https://github.com/acts-project/traccc/blob/main/device/sycl/include/traccc/sycl/finding/combinatorial_kalman_filter_algorithm.hpp'>CKF</a>| trackc;
0141 linkStyle 20 stroke: blue;
0142
0143 %% SYCL Kalman filter
0144 trackc -->|<a href='https://github.com/acts-project/traccc/blob/main/device/sycl/include/traccc/sycl/fitting/kalman_fitting_algorithm.hpp'>Kalman filter</a>| tracks;
0145 linkStyle 21 stroke: blue;
0146
0147 %% CUDA CKF
0148 ptrack -->|<a href='https://github.com/acts-project/traccc/blob/main/device/cuda/include/traccc/cuda/finding/finding_algorithm.hpp'>CKF</a>| trackc;
0149 linkStyle 22 stroke: green;
0150
0151 %% CUDA Kalman filter
0152 trackc -->|<a href='https://github.com/acts-project/traccc/blob/main/device/cuda/include/traccc/cuda/fitting/fitting_algorithm.hpp'>Kalman filter</a>| tracks;
0153 linkStyle 23 stroke: green;
0154 ```
0155
0156 ## Requirements and dependencies
0157
0158 ### OS & compilers:
0159
0160 Please note that due to the complexity of this software and its build system,
0161 it may be somewhat fragile in the face of compiler version changes. The
0162 following are general guidelines for getting _traccc_ to compile:
0163
0164 - The C++ compiler must support C++20
0165
0166 In addition, the following requirements hold when CUDA is enabled:
0167
0168 - The CUDA Toolkit version must be greater than major version 12
0169 - Ensure that the CUDA host compiler supports C++20 and is compatible with the
0170 `nvcc` compiler driver
0171
0172 The following table lists currently combinations of builds, compilers,
0173 and toolchains that are currently known to work (last updated 2022/01/24):
0174
0175 | Build | OS | gcc | CUDA | comment |
0176 | --- | --- | --- | --- | --- |
0177 | CUDA | Ubuntu 24.04 | 13.3.0 | 12.6 | runs on CI |
0178
0179 ### Dependencies
0180
0181 - [Boost](https://www.boost.org/): program_options
0182 - [CMake](https://cmake.org/)
0183 - (Optional) [ROOT](https://root.cern/): RIO, Hist, Tree
0184
0185 ### Dependency management with Spack
0186
0187 The [Spack](https://spack.io/) project provides a particularly easy way to
0188 install the dependencies that you need to use traccc. In order to use Spack to
0189 manage your dependencies, simply create a new Spack environment using the
0190 provided environment file:
0191
0192 ```sh
0193 spack env create traccc spack.yaml
0194 spack -e traccc concretize -f
0195 spack -e traccc install
0196 spack env activate traccc
0197 ```
0198
0199 This way, Spack will automatically download and install all dependencies
0200 necessary to use traccc with the CUDA, SYCL, and Alpaka programming
0201 models. When using Spack to manage your dependencies, make sure to compile
0202 traccc with the `-DTRACCC_USE_SPACK_LIBS=ON` flag.
0203
0204 ## Getting started
0205
0206 ### Clone the repository
0207
0208 Clone the repository and setup the data directory.
0209
0210 ```sh
0211 git clone https://github.com/acts-project/traccc.git
0212 ./traccc/data/traccc_data_get_files.sh
0213 ```
0214
0215 ### Build the project
0216
0217 ```sh
0218 cmake --preset <preset> [options] -S traccc/ -B build
0219 cmake --build build/
0220 ```
0221
0222 ### Build presets
0223
0224 | Name | Description |
0225 | --- | --- |
0226 | host-fp32 | FP32 build of the host code with ROOT enabled |
0227 | host-fp64 | FP64 build of the host code with ROOT enabled |
0228 | cuda-fp32 | FP32 build of the CUDA code |
0229 | cuda-fp64 | FP64 build of the CUDA code |
0230 | sycl-fp32 | FP32 build of the SYCL code |
0231 | sycl-fp64 | FP64 build of the SYCL code |
0232 | alpaka-fp32 | FP32 build of the Alpaka code |
0233 | alpaka-fp64 | FP64 build of the Alpaka code |
0234
0235 ### Detailed build options
0236
0237 | Option | Description |
0238 | --- | --- |
0239 | TRACCC_BUILD_CUDA | Build the CUDA sources included in traccc |
0240 | TRACCC_BUILD_SYCL | Build the SYCL sources included in traccc |
0241 | TRACCC_BUILD_ALPAKA | Build the Alpaka sources included in traccc |
0242 | TRACCC_BUILD_TESTING | Build the (unit) tests of traccc |
0243 | TRACCC_BUILD_EXAMPLES | Build the examples of traccc |
0244 | TRACCC_USE_SYSTEM_VECMEM | Pick up an existing installation of VecMem from the build environment |
0245 | TRACCC_USE_SYSTEM_ACTS | Pick up an existing installation of Acts from the build environment |
0246 | TRACCC_USE_SYSTEM_GOOGLETEST | Pick up an existing installation of GoogleTest from the build environment |
0247 | TRACCC_USE_ROOT | Build physics performance analysis code using an existing installation of ROOT from the build environment |
0248 | TRACCC_DEVICE_LOG_LVL | Set device code log level (NONE, WARN, INFO, VERBOSE, DEBUG)
0249
0250 ## Examples
0251
0252 ### Full reconstruction chain
0253
0254 ```console
0255 <build_directory>/bin/traccc_seq_example \
0256 --detector-file=geometries/odd/odd-detray_geometry_detray.json \
0257 --material-file=geometries/odd/odd-detray_material_detray.json \
0258 --grid-file=geometries/odd/odd-detray_surface_grids_detray.json \
0259 --digitization-file=geometries/odd/odd-digi-geometric-config.json \
0260 --conditions-file=geomteries/odd/odd-digi-geometric-config.json \
0261 --use-acts-geom-source --input-directory=odd/geant4_10muon_10GeV/ \
0262 --input-events=10
0263
0264 <build_directory>/bin/traccc_throughput_mt \
0265 --detector-file=geometries/odd/odd-detray_geometry_detray.json \
0266 --material-file=geometries/odd/odd-detray_material_detray.json \
0267 --grid-file=geometries/odd/odd-detray_surface_grids_detray.json \
0268 --digitization-file=geometries/odd/odd-digi-geometric-config.json \
0269 --conditions-file=geometries/odd/odd-digi-geometric-config.json \
0270 --use-acts-geom-source --input-directory=odd/geant4_10muon_10GeV/ \
0271 --input-events=10 --processed-events=1000 --threads=1
0272 ```
0273
0274 Depending on the build options, can also use variants of the executables
0275 postfixed by `_cuda`, `_sycl` and `_alpaka`, with the same options.
0276
0277 ### Running a partial chain with simplified simulation data
0278
0279 Users can generate muon-like particle simulation data with the pre-built detray geometries:
0280
0281 ```sh
0282 # Generate telescope geometry data
0283 <build_directory>/bin/traccc_simulate_telescope --gen-vertex-xyz-mm=0:0:0 --gen-vertex-xyz-std-mm=0:0:0 --gen-mom-gev=100:100 --gen-phi-degree=0:0 --gen-events=10 --gen-nparticles=2000 --output-directory=detray_simulation/telescope_detector/n_particles_2000/ --gen-eta=1:3
0284
0285 # Generate toy geometry data
0286 <build_directory>/bin/traccc_simulate_toy_detector --gen-vertex-xyz-mm=0:0:0 --gen-vertex-xyz-std-mm=0:0:0 --gen-mom-gev=100:100 --gen-phi-degree=0:360 --gen-events=10 --gen-nparticles=2000 --output-directory=detray_simulation/toy_detector/n_particles_2000/ --gen-eta=-3:3 --constraint-step-size-mm=1 --search-window 3:3
0287
0288 # Generate drift chamber data
0289 <build_directory>/bin/traccc_simulate_wire_chamber --gen-vertex-xyz-mm=0:0:0 --gen-vertex-xyz-std-mm=0:0:0 --gen-mom-gev=2:2 --gen-phi-degree=0:360 --gen-events=10 --gen-nparticles=100 --output-directory=detray_simulation/wire_chamber/n_particles_100/ --gen-eta=-1:1 --constraint-step-size-mm=1 --search-window 3:3
0290 ```
0291
0292 The simulation will also generate the detector json files (geometry, material and surface_grid) in the current directory. It is user's responsibility to move them to an appropriate place (e.g. `<detector_directory>`) and match them to the input file arguments of reconstruction chains.
0293
0294 If users have a geometry json file already, it is also possible to run simulation with `traccc_simulate` application
0295
0296 ```sh
0297 # Given that users have a geometry json file
0298 <build_directory>/bin/traccc_simulate --output-directory=<output-directory> --detector-file=<geometry_file> --material-file=<material-file> --grid-file=<grid-file> --event=10 --constraint-step-size-mm=1
0299 ```
0300
0301 There are three types of partial reconstruction chain users can operate: `seeding_example`, `truth_finding_example`, and `truth_fitting_example` where their algorithm coverages are shown in the table below. Each of them starts from truth measurements, truth seeds, and truth tracks, respectively.
0302
0303 | Category | Clusterization | Seeding | Track finding | Track fitting |
0304 | ----------------------- | -------------- | ------- | ------------- | ------------- |
0305 | `seeding_example` | | ✅ | ✅ | ✅ |
0306 | `truth_finding_example` | | | ✅ | ✅ |
0307 | `truth_fitting_example` | | | | ✅ |
0308
0309 The dirft chamber will not produce meaningful results with `seeding_example` as the current seeding algorithm is only designed for 2D measurement objects. Truth finding works OK in general but the combinatoric explosion can occur for a few unlucky events, leading to poor pull value distributions. The followings are example commands:
0310
0311 ```sh
0312 # Run cuda seeding example for toy geometry
0313 <build_directory>/bin/traccc_seeding_example_cuda --input-directory=detray_simulation/toy_detector/n_particles_2000/ --check-performance --detector-file=<detector_directory>/toy_detector_geometry.json --material-file=<detector_directory>/toy_detector_homogeneous_material.json --grid-file=<detector_directory>/toy_detector_surface_grids.json --input-events=1 --track-candidates-range=3:30 --constraint-step-size-mm=1000 --run-cpu=1 --search-window 3:3
0314 ```
0315
0316 ```sh
0317 # Run cuda truth finding example for toy geometry
0318 <build_directory>/bin/traccc_truth_finding_example_cuda --input-directory=detray_simulation/toy_detector/n_particles_2000/ --check-performance --detector-file=<detector_directory>/toy_detector_geometry.json --material-file=<detector_directory>/toy_detector_homogeneous_material.json --grid-file=<detector_directory>/toy_detector_surface_grids.json --input-events=1 --track-candidates-range=3:30 --constraint-step-size-mm=1000 --run-cpu=1 --search-window 3:3
0319 ```
0320
0321 ```sh
0322 # Run cuda truth finding example for drift chamber
0323 <build_directory>/bin/traccc_truth_finding_example_cuda --input-directory=detray_simulation/wire_chamber/n_particles_100/ --check-performance --detector-file=<detector_directory>/wire_chamber_geometry.json --material-file=<detector_directory>/wire_chamber_homogeneous_material.json --grid-file=<detector_directory>/wire_chamber_surface_grids.json --input-events=10 --track-candidates-range=6:30 --constraint-step-size-mm=1 --run-cpu=1 --search-window 3:3
0324 ```
0325
0326 ```sh
0327 # Run cpu truth fitting example for drift chamber
0328 <build_directory>/bin/traccc_truth_fitting_example --input-directory=detray_simulation/wire_chamber/n_particles_2000_100GeV/ --check-performance --detector-file=<detector_directory>/wire_chamber_geometry.json --material-file=<detector_directory>/wire_chamber_homogeneous_material.json --grid-file=<detector_directory>/wire_chamber_surface_grids.json --input-events=10 --constraint-step-size-mm=1 --search-window 3:3
0329 ```
0330
0331 Users can open the performance root files (with `--check-performance=true`) and draw the histograms.
0332
0333 ```sh
0334 $ root -l performance_track_finding.root
0335 root [0]
0336 Attaching file performance_track_finding.root as _file0...
0337 (TFile *) 0x3871910
0338 root [1] finding_trackeff_vs_eta->Draw()
0339 ```
0340
0341 ## Contributing
0342
0343 ### Code formatting
0344
0345 The traccc code is formatted using clang-format; the recommended way to ensure that your code is properly formatted is to use [pre-commit](https://pre-commit.com/). The pre-commit webpage has a useful guide for using the tool, but the simplest way of using it (without installing it as a pre-commit hook) is as follows. First, install the tool with your favourite Python package manager:
0346
0347 ```console
0348 # With pip
0349 $ pip install pre-commit
0350 # With pipx
0351 $ pip install pre-commit
0352 ```
0353
0354 The install step needs to be executed only once. After that, the code can be easily formatted as follows:
0355
0356 ```console
0357 $ pre-commit run --all-files
0358 ```
0359
0360 ## Troubleshooting
0361
0362 The following are potentially useful instructions for troubleshooting various
0363 problems with your build:
0364
0365 ### CUDA
0366
0367 #### Incompatible host compiler
0368
0369 You may experience errors being issued about standard library features, for example:
0370
0371 ```
0372 /usr/include/c++/11/bits/std_function.h:435:145: note: ‘_ArgTypes’
0373 /usr/include/c++/11/bits/std_function.h:530:146: error: parameter packs not expanded with ‘...’:
0374 530 | operator=(_Functor&& __f)
0375 ```
0376
0377 In this case, your `nvcc` host compiler is most likely incompatible with your
0378 CUDA toolkit. Consider installing a supported version and selecting it through
0379 the `CUDAHOSTCXX` environment variable at build-time.
0380
0381 #### `ptxas` failures due to non-ASCII characters
0382
0383 You may encounter errors that look like the following:
0384
0385 ```
0386 ptxas fatal : Unexpected non-ASCII character encountered on line 30
0387 ptxas fatal : Ptx assembly aborted due to errors
0388 ```
0389
0390 This means that you are compiling with a version later than CUDA 12.8 which has
0391 not been fixed and you are running in debug mode. This error is due to a bug in
0392 the CUDA toolkit. Either downgrade to CUDA 12.6 or disable the debug build.
