Warning, /acts/docs/getting_started.md is written in an unsupported language. File is not indexed.
0001 # Getting started
0002
0003 ## Quick start
0004
0005 ACTS is developed in C++ and is built using [CMake](https://cmake.org). Building
0006 the core library requires a C++20 compatible compiler,
0007 [Boost](https://www.boost.org), and [Eigen](https://eigen.tuxfamily.org). The
0008 following commands will clone the repository, configure, and build the core
0009 library:
0010
0011 ```console
0012 git clone https://github.com/acts-project/acts <source>
0013 cmake -B <build> -S <source>
0014 cmake --build <build>
0015 ```
0016
0017 For a full list of dependencies, including specific versions, see the
0018 [Prerequisites](#prerequisites) section below. Build options to activate
0019 additional components are described in the [Build options](#build-options)
0020 section.
0021
0022 ## Prerequisites
0023
0024 The following dependencies are required to build the ACTS core library:
0025
0026 - A C++17 compatible compiler (recent versions of either gcc and clang should work)
0027 - [CMake](https://cmake.org) >= 3.14
0028 - [Boost](https://www.boost.org) >= 1.71 with `filesystem`, `program_options`, and `unit_test_framework`
0029 - [Eigen](https://eigen.tuxfamily.org) >= 3.3.7
0030
0031 The following dependencies are optional and are needed to build additional
0032 components:
0033
0034 - [CUDA](https://developer.nvidia.com/cuda-zone) for the CUDA plugin and the Exa.TrkX plugin and its examples
0035 - [DD4hep](http://dd4hep.cern.ch) >= 1.11 for the DD4hep plugin and some examples
0036 - [Doxygen](http://doxygen.org) >= 1.8.15 for the documentation
0037 - [Geant4](https://geant4.org/) for some examples
0038 - [HepMC](https://gitlab.cern.ch/hepmc/HepMC3) >= 3.2.1 for some examples
0039 - [Intel Threading Building Blocks](https://github.com/oneapi-src/oneTBB) >= 2020.1 for the examples
0040 - [ONNX Runtime](https://onnxruntime.ai/) >= 1.12.0 for the ONNX plugin, the Exa.TrkX plugin and some examples
0041 - [Pythia8](https://pythia.org) for some examples
0042 - [ROOT](https://root.cern.ch) >= 6.20 for the ROOT plugin and the examples
0043 - [Sphinx](https://www.sphinx-doc.org) >= 2.0 with [Breathe](https://breathe.readthedocs.io/en/latest/), [Exhale](https://exhale.readthedocs.io/en/latest/), and [recommonmark](https://recommonmark.readthedocs.io/en/latest/index.html) extensions for the documentation
0044 - [libtorch](https://pytorch.org/cppdocs/installing.html) for the Exa.TrkX plugin
0045 - [Pybind11](https://github.com/pybind/pybind11) for the Python bindings of the examples
0046 - [FastJet](http://fastjet.fr/) >= 3.4.0 for the FastJet plugin
0047
0048 There are some additional dependencies that are automatically provided as part of
0049 the build system.
0050 These are usually not available through the system package manager and can be found in the ``thirdparty`` directory.
0051
0052 All external dependencies must be provided prior to building ACTS. Compatible
0053 versions of all dependencies are provided e.g. by the [LCG
0054 releases](https://lcginfo.cern.ch/) starting from [LCG 102b](https://lcginfo.cern.ch/release/102b/).
0055 For convenience, it is possible to build the required boost and eigen3 dependencies using the ACTS build system; see [Build options](#build-options).
0056 Other options are also
0057 available and are discussed in the [Building Acts](#building-acts) section.
0058
0059 [Profiling](contribution/profiling.md) details the prerequisites for profiling the ACTS project with gperftools.
0060
0061 ## Building ACTS
0062
0063 ACTS uses [CMake](https://cmake.org) to configure, build, and install the
0064 software. After checking out the repository code into a `<source>` directory,
0065 CMake is called first to configure the build into a separate `<build>`
0066 directory. A typical setup is to create a `<source>/build` directory within the
0067 sources, but this is just a convention; not a requirement. The following command
0068 runs the configuration and searches for the dependencies. The `<build>`
0069 directory is automatically created.
0070
0071 ```console
0072 cmake -B <build> -S <source>
0073 ```
0074
0075 The build can be configured via various options that are listed in detail in the
0076 [Build options](#build-options) section. Options are set on the command line.
0077 The previous command could be e.g. modified to
0078
0079 ```console
0080 cmake -B <build> -S <source> -DACTS_BUILD_UNITTESTS=on -DACTS_BUILD_FATRAS=on
0081 ```
0082
0083 After the configuration succeeded, the software is build. This is also done with cmake via the following command
0084
0085 ```console
0086 cmake --build <build>
0087 ```
0088
0089 This automatically calls the configure build tool, e.g. Make or Ninja. To build only a specific target, the target names has to be separated from the CMake options by `--`, i.e.
0090
0091 ```console
0092 cmake --build <build> -- ActsFatras # to build the Fatras library
0093 ```
0094
0095 The build commands are the same regardless of where you are building the
0096 software. Depending on your build environment, there are different ways how to
0097 make the dependencies available.
0098
0099 ### With a LCG release on CVMFS
0100
0101 If you have access to a machine running [CVMFS](https://cernvm.cern.ch/fs/),
0102 e.g. CERNs lxplus login machines, the dependencies can be easily satisfied
0103 via an LCG releases available through CVMFS. Source the cvmfs setup script
0104 provided by the machine. It is suggested to select a recent `<lcg_release>`
0105 and `<lcg_platform>` combination. (Have a look at the CI jobs to get an
0106 overview on what we are currently testing):
0107
0108 ```console
0109 source /cvmfs/sft.cern.ch/lcg/views/<lcg_release>/<lcg_platform>/setup.sh
0110 ```
0111
0112 After sourcing the setup script, you can build ACTS as described above.
0113
0114 ### In a container
0115
0116 A set of container images is available through the [ACTS container
0117 registry][acts_containers]. These images are built using the configuration that is used in CI,
0118 and they contain all the dependencies required to build ACTS.
0119
0120 .. note::
0121 Most containers are only build for the `x86_64` platform. If you are on an
0122 `aarch64` (such as a recent Mac), you'll need to use the `ubuntu2404`
0123 container, which is built for `aarch64` and `x86_64`!
0124
0125 Furthermore, we are also testing on, but do not provide the corresponding containers:
0126
0127 - `alma9` (HEP-specific software from LCG 106 or 107 and various clang versions)
0128 - `macOS-10.15`
0129
0130 :::{attention}
0131 We stopped producing fully-contained LCG containers in favor of running LCG
0132 based tests directly from CVMFS.
0133 :::
0134
0135 To use these locally, you first need to pull the relevant images from the
0136 registry. Stable versions are tagged as `vX` where `X` is the version number.
0137 The latest, potentially unstable, version is tagged as `latest`. To list all
0138 available tags, e.g. for the `ubuntu2004` image, you can use the following
0139 command:
0140
0141 ```console
0142 docker search --list-tags ghcr.io/acts-project/ubuntu2404
0143 ```
0144
0145 The following command then downloads a stable tag of the `ubuntu2404` image:
0146
0147 ```console
0148 docker pull ghcr.io/acts-project/ubuntu2404:51
0149 ```
0150
0151 This should print the image id as part of the output. You can also find out the
0152 image id by running `docker images` to list all your locally available container
0153 images.
0154
0155 Now, you need to start a shell within the container to run the build. Assuming
0156 that `<source>` is the path to your source checkout on your host machine, the
0157 following command will make the source directory available as `/acts` in the
0158 container and start an interactive `bash` shell
0159
0160 ```console
0161 docker run --volume=<source>:/acts:ro --interactive --tty <image> /bin/bash
0162 ```
0163
0164 where `<image>` is the image id that was previously mentioned. If you are using the Ubuntu-based image you are already good to go. For the images based on LCG releases, you can now activate the LCG release in the container shell by sourcing a setup script:
0165
0166 ```console
0167 container $ source /opt/lcg_view/setup.sh
0168 ```
0169
0170 Building ACTS follows the instructions above with `/acts` as the source directory, e.g.
0171
0172 ```console
0173 container $ cmake -B build -S /acts -DACTS_BUILD_FATRAS=on
0174 container $ cmake --build build
0175 ```
0176
0177 [acts_containers]: https://github.com/acts-project/ci-dependencies/pkgs/container/spack-container
0178
0179 ### On your local machine
0180
0181 Building and running ACTS on your local machine is not officially supported.
0182 However, if you have the necessary prerequisites installed it is possible to
0183 use it locally. ACTS developers regularly use different Linux distributions and
0184 macOS to build and develop ACTS. It is possible to use Spack to more easily
0185 install ACTS' dependencies; see the [building with Spack](misc/spack.md) page for
0186 more information.
0187
0188 (build_docs)=
0189
0190 ## Building the documentation
0191
0192 The documentation uses [Doxygen][doxygen] to extract the source code
0193 documentation and [Sphinx][sphinx] with the [Breathe][breathe] extension to
0194 generate the documentation website. To build the documentation locally, you
0195 need to have [Doxygen][doxygen] version `1.9.5` or newer installed.
0196 [Sphinx][sphinx] and a few other dependencies can be installed using the Python
0197 package manager `pip`:
0198
0199 ```console
0200 cd <source>
0201 pip install -r docs/requirements.txt
0202 ```
0203
0204 :::{tip}
0205 It is **strongly recommended** to use a [virtual
0206 environment](https://realpython.com/python-virtual-environments-a-primer/) for
0207 this purpose! For example, run
0208
0209 ```console
0210 python -m venv docvenv
0211 source docvenv/bin/activate
0212 ```
0213
0214 to create a local virtual environment, and then run the `pip` command above.
0215 :::
0216
0217 To activate the documentation build targets, the `ACTS_BUILD_DOCS` option has to be set
0218
0219 ```console
0220 cmake -B <build> -S <source> -DACTS_BUILD_DOCS=on
0221 ```
0222
0223 Then the documentation can be build with this target
0224
0225 ```console
0226 cmake --build <build> --target docs
0227 ```
0228
0229 The default option includes the Doxygen, Sphinx, and the Breathe extension,
0230 i.e. the source code information can be used in the manually written
0231 documentation. An attempt is made to pull in symbols that are cross-referenced from
0232 other parts of the documentation. This is not guaranteed to work: in case
0233 of errors you will need to manually pull in symbols to be documented.
0234
0235 [doxygen]: https://doxygen.nl/
0236 [sphinx]: https://www.sphinx-doc.org
0237 [breathe]: https://breathe.readthedocs.io
0238
0239 ## Build options
0240
0241 CMake options can be set by adding `-D<OPTION>=<VALUE>` to the configuration
0242 command. The following command would e.g. enable the unit tests
0243
0244 ```console
0245 cmake -B <build> -S <source> -DACTS_BUILD_UNITTESTS=ON
0246 ```
0247
0248 Multiple options can be given. `cmake` caches the options so that only changed
0249 options must be specified in subsequent calls to configure the project. The
0250 following options are available to configure the project and enable optional
0251 components.
0252
0253 <!-- CMAKE_OPTS_BEGIN -->
0254 | Option | Description |
0255 |-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
0256 | ACTS_PARAMETER_DEFINITIONS_HEADER | Use a different (track) parameter<br>definitions header<br> type: `filepath`, default: `""` |
0257 | ACTS_SOURCELINK_SBO_SIZE | Customize the SBO size used by<br>SourceLink<br> type: `string`, default: `""` |
0258 | ACTS_FORCE_ASSERTIONS | Force assertions regardless of build<br>type<br> type: `bool`, default: `OFF` |
0259 | ACTS_USE_SYSTEM_LIBS | Use system libraries by default<br> type: `bool`, default: `OFF` |
0260 | ACTS_USE_SYSTEM_ACTSVG | Use the ActSVG system library<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0261 | ACTS_USE_SYSTEM_ALGEBRAPLUGINS | Use a system-provided algebra-plugins<br>installation<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0262 | ACTS_SETUP_ALGEBRAPLUGINS | If we want to setup algebra-plugins<br> type: `bool`, default: `ON` |
0263 | ACTS_USE_SYSTEM_COVFIE | Use a system-provided covfie<br>installation<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0264 | ACTS_SETUP_COVFIE | If we want to setup covfie<br> type: `bool`, default: `ON` |
0265 | ACTS_USE_SYSTEM_DETRAY | Use a system-provided detray<br>installation<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0266 | ACTS_SETUP_DETRAY | If we want to setup detray<br> type: `bool`, default: `ON` |
0267 | ACTS_USE_SYSTEM_VECMEM | Use a system-provided vecmem<br>installation<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0268 | ACTS_SETUP_VECMEM | If we want to setup vecmem<br> type: `bool`, default: `ON` |
0269 | ACTS_USE_SYSTEM_TRACCC | Use a system-provided traccc<br>installation<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0270 | ACTS_USE_SYSTEM_NLOHMANN_JSON | Use nlohmann::json provided by the<br>system instead of the bundled version<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0271 | ACTS_USE_SYSTEM_PYBIND11 | Use a system installation of pybind11<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0272 | ACTS_USE_SYSTEM_MODULEMAPGRAPH | Use a system installation of<br>ModuleMapGraph<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0273 | ACTS_USE_SYSTEM_EIGEN3 | Use a system-provided eigen3<br> type: `bool`, default: `ON` |
0274 | ACTS_BUILD_PLUGIN_ACTSVG | Build SVG display plugin<br> type: `bool`, default: `OFF` |
0275 | ACTS_BUILD_PLUGIN_DD4HEP | Build DD4hep plugin<br> type: `bool`, default: `OFF` |
0276 | ACTS_BUILD_PLUGIN_PODIO | Build Podio plugin<br> type: `bool`, default: `OFF` |
0277 | ACTS_BUILD_PLUGIN_EDM4HEP | Build EDM4hep plugin<br> type: `bool`, default: `OFF` |
0278 | ACTS_BUILD_PLUGIN_FPEMON | Build FPE monitoring plugin<br> type: `bool`, default: `OFF` |
0279 | ACTS_BUILD_PLUGIN_FASTJET | Build FastJet plugin<br> type: `bool`, default: `OFF` |
0280 | ACTS_BUILD_PLUGIN_GEOMODEL | Build GeoModel plugin<br> type: `bool`, default: `OFF` |
0281 | ACTS_BUILD_PLUGIN_TRACCC | Build Traccc plugin<br> type: `bool`, default: `OFF` |
0282 | ACTS_BUILD_PLUGIN_GEANT4 | Build Geant4 plugin<br> type: `bool`, default: `OFF` |
0283 | ACTS_BUILD_PLUGIN_EXATRKX | Build the Exa.TrkX plugin<br> type: `bool`, default: `OFF` |
0284 | ACTS_EXATRKX_ENABLE_ONNX | Build the Onnx backend for the exatrkx<br>plugin<br> type: `bool`, default: `OFF` |
0285 | ACTS_EXATRKX_ENABLE_TORCH | Build the torchscript backend for the<br>exatrkx plugin<br> type: `bool`, default: `ON` |
0286 | ACTS_EXATRKX_ENABLE_CUDA | Enable CUDA for the exatrkx plugin<br> type: `bool`, default: `OFF` |
0287 | ACTS_EXATRKX_ENABLE_MODULEMAP | Enable Module-Map-based graph<br>construction<br> type: `bool`, default: `OFF` |
0288 | ACTS_EXATRKX_ENABLE_TENSORRT | Enable the native TensorRT inference<br>modules<br> type: `bool`, default: `OFF` |
0289 | ACTS_BUILD_PLUGIN_JSON | Build json plugin<br> type: `bool`, default: `OFF` |
0290 | ACTS_BUILD_PLUGIN_ONNX | Build ONNX plugin<br> type: `bool`, default: `OFF` |
0291 | ACTS_BUILD_PLUGIN_ROOT | Build ROOT plugin<br> type: `bool`, default: `OFF` |
0292 | ACTS_SETUP_ANNOY | Explicitly set up Annoy for the project<br> type: `bool`, default: `OFF` |
0293 | ACTS_BUILD_PLUGIN_HASHING | Build Hashing plugin<br> type: `bool`, default: `OFF` |
0294 | ACTS_BUILD_FATRAS | Build FAst TRAcking Simulation package<br> type: `bool`, default: `OFF` |
0295 | ACTS_BUILD_FATRAS_GEANT4 | Build Geant4 Fatras package<br> type: `bool`, default: `OFF` |
0296 | ACTS_BUILD_ALIGNMENT | Build Alignment package<br> type: `bool`, default: `OFF` |
0297 | ACTS_BUILD_EXAMPLES_DD4HEP | Build DD4hep-based code in the examples<br> type: `bool`, default: `OFF` |
0298 | ACTS_BUILD_EXAMPLES_EDM4HEP | Build EDM4hep-based code in the examples<br> type: `bool`, default: `OFF` |
0299 | ACTS_BUILD_EXAMPLES_PODIO | Build Podio-based code in the examples<br> type: `bool`, default: `OFF` |
0300 | ACTS_BUILD_EXAMPLES_EXATRKX | Build the Exa.TrkX example code<br> type: `bool`, default: `OFF` |
0301 | ACTS_BUILD_EXAMPLES_GEANT4 | Build Geant4-based code in the examples<br> type: `bool`, default: `OFF` |
0302 | ACTS_BUILD_EXAMPLES_HASHING | Build Hashing-based code in the examples<br> type: `bool`, default: `OFF` |
0303 | ACTS_BUILD_EXAMPLES_PYTHIA8 | Build Pythia8-based code in the examples<br> type: `bool`, default: `OFF` |
0304 | ACTS_BUILD_EXAMPLES_PYTHON_BINDINGS | Build python bindings for the examples<br> type: `bool`, default: `OFF` |
0305 | ACTS_BUILD_EXAMPLES_ROOT | Build modules based on ROOT I/O<br> type: `bool`, default: `ON` |
0306 | ACTS_BUILD_ANALYSIS_APPS | Build Analysis applications in the<br>examples<br> type: `bool`, default: `OFF` |
0307 | ACTS_BUILD_BENCHMARKS | Build benchmarks<br> type: `bool`, default: `OFF` |
0308 | ACTS_BUILD_INTEGRATIONTESTS | Build integration tests<br> type: `bool`, default: `OFF` |
0309 | ACTS_BUILD_UNITTESTS | Build unit tests<br> type: `bool`, default: `OFF` |
0310 | ACTS_BUILD_EXAMPLES_UNITTESTS | Build unit tests<br> type: `bool`, default: `ACTS_BUILD_UNITTESTS AND ACTS_BUILD_EXAMPLES` |
0311 | ACTS_RUN_CLANG_TIDY | Run clang-tidy static analysis<br> type: `bool`, default: `OFF` |
0312 | ACTS_BUILD_DOCS | Build documentation<br> type: `bool`, default: `OFF` |
0313 | ACTS_SETUP_BOOST | Explicitly set up Boost for the project<br> type: `bool`, default: `ON` |
0314 | ACTS_SETUP_EIGEN3 | Explicitly set up Eigen3 for the project<br> type: `bool`, default: `ON` |
0315 | ACTS_BUILD_ODD | Build the OpenDataDetector<br> type: `bool`, default: `OFF` |
0316 | ACTS_ENABLE_CPU_PROFILING | Enable CPU profiling using gperftools<br> type: `bool`, default: `OFF` |
0317 | ACTS_ENABLE_MEMORY_PROFILING | Enable memory profiling using gperftools<br> type: `bool`, default: `OFF` |
0318 | ACTS_GPERF_INSTALL_DIR | Hint to help find gperf if profiling is<br>enabled<br> type: `string`, default: `""` |
0319 | ACTS_ENABLE_LOG_FAILURE_THRESHOLD | Enable failing on log messages with<br>level above certain threshold<br> type: `bool`, default: `OFF` |
0320 | ACTS_LOG_FAILURE_THRESHOLD | Log level above which an exception<br>should be automatically thrown. If<br>ACTS_ENABLE_LOG_FAILURE_THRESHOLD is set<br>and this is unset, this will enable a<br>runtime check of the log level.<br> type: `string`, default: `""` |
0321 | ACTS_COMPILE_HEADERS | Generate targets to compile header files<br> type: `bool`, default: `ON` |
0322 <!-- CMAKE_OPTS_END -->
0323
0324 All ACTS-specific options are disabled or empty by default and must be
0325 specifically requested.
0326
0327 ACTS comes with a couple of CMakePresets which allow to collect and
0328 origanize common configuration workflows. On the surface the current
0329 list of presets contains:
0330
0331 - `dev` as a base for developer configurations. This enables everything
0332 necessary for running the ODD full chain examples with Fatras. It
0333 sets the cpp standard to 20, the generator to ninja and enables ccache.
0334 - `perf` is similar to `dev` but tweaked for performance measurements.
0335
0336 In addition to the ACTS-specific options, many generic options are available
0337 that modify various aspects of the build. The following options are some of the
0338 most common ones. For more details, have a look at the annotated list of [useful
0339 CMake variables](https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/Useful-Variables) or at the [CMake
0340 documentation](https://cmake.org/documentation/).
0341
0342 | Option | Description |
0343 |----------------------|-----------------------------------------------------------------------------------------------------------------------------------|
0344 | CMAKE_BUILD_TYPE | Build type, e.g. Debug or Release; affects compiler flags <br/> (if not specified **`RelWithDebInfo`** will be used as a default) |
0345 | CMAKE_CXX_COMPILER | Which C++ compiler to use, e.g. g++ or clang++ |
0346 | CMAKE_INSTALL_PREFIX | Where to install ACTS to |
0347 | CMAKE_PREFIX_PATH | Search path for external packages |
0348
0349 The build is also affected by some environment variables. They can be set by prepending them to the configuration call:
0350
0351 ```console
0352 DD4hep_DIR=<path/to/dd4hep> cmake -B <build> -S <source>
0353 ```
0354
0355 The following environment variables might be useful.
0356
0357 | Environment variable | Description |
0358 |----------------------|------------------------------------------|
0359 | DD4hep_DIR | Search path for the DD4hep installation |
0360 | HepMC3_DIR | Search path for the HepMC3 installation |
0361 | Pythia8_DIR | Search path for the Pythia8 installation |
0362
0363 ## The OpenDataDetector
0364
0365 ACTS comes packaged with a detector modeled using DD4hep that can be used to test your algorithms. It comes equipped with a magnetic field file as well as an already built material map.
0366 It is available via the git submodule feature by performing the following steps ([`git lfs`](https://git-lfs.com/) need to be installed on your machine):
0367
0368 ```console
0369 git submodule init
0370 git submodule update
0371 ```
0372
0373 To use it, you will then need to build ACTS with the `ACTS_BUILD_ODD` option and then point either `LD_LIBRARY_PATH` on Linux or
0374 `DYLD_LIBRARY_PATH` and `DD4HEP_LIBRARY_PATH` on MacOs to the install path of the ODD factory (for example: `build/thirdparty/OpenDataDetector/factory`).
0375
0376 You can now use the ODD in the python binding by using:
0377
0378 ```python
0379 oddMaterialDeco = acts.IMaterialDecorator.fromFile("PATH_TO_Acts/thirdparty/OpenDataDetector/data/odd-material-maps.root")
0380 detector = getOpenDataDetector(oddMaterialDeco)
0381 trackingGeometry = detector.trackingGeometry()
0382 decorators = detector.contextDecorators()
0383 ```
0384
0385 ## Using ACTS
0386
0387 When using ACTS in your own CMake-based project, you need to include the
0388 following lines in your `CMakeLists.txt` file:
0389
0390 ```cmake
0391 find_package (Acts COMPONENTS comp1 comp2 ...)
0392 ```
0393
0394 where `compX` are the required components from the ACTS project. See the
0395 `cmake` output for more information about which components are available.
