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 TGeo 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
0047 There are some additional dependencies that are automatically provided as part of
0048 the build system.
0049 These are usually not available through the system package manager and can be found in the ``thirdparty`` directory.
0050
0051 All external dependencies must be provided prior to building ACTS. Compatible
0052 versions of all dependencies are provided e.g. by the [LCG
0053 releases](https://lcginfo.cern.ch/) starting from [LCG 102b](https://lcginfo.cern.ch/release/102b/).
0054 For convenience, it is possible to build the required boost and eigen3 dependencies using the ACTS build system; see [Build options](#build-options).
0055 Other options are also
0056 available and are discussed in the [Building Acts](#building-acts) section.
0057
0058 [Profiling](contribution/profiling.md) details the prerequisites for profiling the ACTS project with gperftools.
0059
0060 ## Building ACTS
0061
0062 ACTS uses [CMake](https://cmake.org) to configure, build, and install the
0063 software. After checking out the repository code into a `<source>` directory,
0064 CMake is called first to configure the build into a separate `<build>`
0065 directory. A typical setup is to create a `<source>/build` directory within the
0066 sources, but this is just a convention; not a requirement. The following command
0067 runs the configuration and searches for the dependencies. The `<build>`
0068 directory is automatically created.
0069
0070 ```console
0071 cmake -B <build> -S <source>
0072 ```
0073
0074 The build can be configured via various options that are listed in detail in the
0075 [Build options](#build-options) section. Options are set on the command line.
0076 The previous command could be e.g. modified to
0077
0078 ```console
0079 cmake -B <build> -S <source> -DACTS_BUILD_UNITTESTS=on -DACTS_BUILD_FATRAS=on
0080 ```
0081
0082 After the configuration succeeded, the software is build. This is also done with cmake via the following command
0083
0084 ```console
0085 cmake --build <build>
0086 ```
0087
0088 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.
0089
0090 ```console
0091 cmake --build <build> -- ActsFatras # to build the Fatras library
0092 ```
0093
0094 The build commands are the same regardless of where you are building the
0095 software. Depending on your build environment, there are different ways how to
0096 make the dependencies available.
0097
0098 ### With a LCG release on CVMFS
0099
0100 If you have access to a machine running [CVMFS](https://cernvm.cern.ch/fs/),
0101 e.g. CERNs lxplus login machines, the dependencies can be easily satisfied
0102 via a LCG releases available through CVMFS. A setup script is provided to activate a compatible releases that can be used as follows:
0103
0104 ```console
0105 cd <source>
0106 source CI/setup_cvmfs_lcg.sh
0107 ```
0108
0109 After sourcing the setup script, you can build ACTS as described above. The
0110 following commands will build ACTS in the `<source>/build` directory with the
0111 Fatras component.
0112
0113 ```console
0114 cd <source>
0115 source CI/setup_cvmfs_lcg.sh
0116 cmake -B build -S . -DACTS_BUILD_FATRAS=on
0117 cmake --build build
0118 ```
0119
0120 ### In a container
0121
0122 A set of container images is available through the [ACTS container
0123 registry][acts_containers]. The following containers are used as part of the
0124 continuous integration setup and come with all dependencies pre-installed.
0125
0126 - `ubuntu2204`
0127 - `ubuntu2404`
0128
0129 Furthermore, we are also testing on, but do not provide the corresponding containers:
0130
0131 - `alma9` (HEP-specific software from LCG 104 or 105 and gcc13 or clang16)
0132 - `macOS-10.15`
0133
0134 :::{attention}
0135 We stopped producing fully-contained LCG containers in favor of running LCG
0136 based tests directly from CVMFS.
0137 :::
0138
0139 To use these locally, you first need to pull the relevant images from the
0140 registry. Stable versions are tagged as `vX` where `X` is the version number.
0141 The latest, potentially unstable, version is tagged as `latest`. To list all
0142 available tags, e.g. for the `ubuntu2004` image, you can use the following
0143 command:
0144
0145 ```console
0146 docker search --list-tags ghcr.io/acts-project/ubuntu2404
0147 ```
0148
0149 The following command then downloads a stable tag of the `ubuntu2404` image:
0150
0151 ```console
0152 docker pull ghcr.io/acts-project/ubuntu2404:51
0153 ```
0154
0155 This should print the image id as part of the output. You can also find out the
0156 image id by running `docker images` to list all your locally available container
0157 images.
0158
0159 Now, you need to start a shell within the container to run the build. Assuming
0160 that `<source>` is the path to your source checkout on your host machine, the
0161 following command will make the source directory available as `/acts` in the
0162 container and start an interactive `bash` shell
0163
0164 ```console
0165 docker run --volume=<source>:/acts:ro --interactive --tty <image> /bin/bash
0166 ```
0167
0168 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:
0169
0170 ```console
0171 container $ source /opt/lcg_view/setup.sh
0172 ```
0173
0174 Building ACTS follows the instructions above with `/acts` as the source directory, e.g.
0175
0176 ```console
0177 container $ cmake -B build -S /acts -DACTS_BUILD_FATRAS=on
0178 container $ cmake --build build
0179 ```
0180
0181 [acts_containers]: https://github.com/orgs/acts-project/packages?ecosystem=container
0182
0183 ### On your local machine
0184
0185 Building and running ACTS on your local machine is not officially supported.
0186 However, if you have the necessary prerequisites installed it is possible to
0187 use it locally. ACTS developers regularly use different Linux distributions and
0188 macOS to build and develop ACTS. It is possible to use Spack to more easily
0189 install ACTS' dependencies; see the [building with Spack](misc/spack) page for
0190 more information.
0191
0192 (build_docs)=
0193
0194 ## Building the documentation
0195
0196 The documentation uses [Doxygen][doxygen] to extract the source code
0197 documentation and [Sphinx][sphinx] with the [Breathe][breathe] extension to
0198 generate the documentation website. To build the documentation locally, you
0199 need to have [Doxygen][doxygen] version `1.9.5` or newer installed.
0200 [Sphinx][sphinx] and a few other dependencies can be installed using the Python
0201 package manager `pip`:
0202
0203 ```console
0204 cd <source>
0205 pip install -r docs/requirements.txt
0206 ```
0207
0208 :::{tip}
0209 It is **strongly recommended** to use a [virtual
0210 environment](https://realpython.com/python-virtual-environments-a-primer/) for
0211 this purpose! For example, run
0212
0213 ```console
0214 python -m venv docvenv
0215 source docvenv/bin/activate
0216 ```
0217
0218 to create a local virtual environment, and then run the `pip` command above.
0219 :::
0220
0221 To activate the documentation build targets, the `ACTS_BUILD_DOCS` option has to be set
0222
0223 ```console
0224 cmake -B <build> -S <source> -DACTS_BUILD_DOCS=on
0225 ```
0226
0227 Then the documentation can be build with this target
0228
0229 ```console
0230 cmake --build <build> --target docs
0231 ```
0232
0233 The default option includes the Doxygen, Sphinx, and the Breathe extension,
0234 i.e. the source code information can be used in the manually written
0235 documentation. An attempt is made to pull in symbols that are cross-referenced from
0236 other parts of the documentation. This is not guaranteed to work: in case
0237 of errors you will need to manually pull in symbols to be documented.
0238
0239 [doxygen]: https://doxygen.nl/
0240 [sphinx]: https://www.sphinx-doc.org
0241 [breathe]: https://breathe.readthedocs.io
0242
0243 ## Build options
0244
0245 CMake options can be set by adding `-D<OPTION>=<VALUE>` to the configuration
0246 command. The following command would e.g. enable the unit tests
0247
0248 ```console
0249 cmake -B <build> -S <source> -DACTS_BUILD_UNITTESTS=ON
0250 ```
0251
0252 Multiple options can be given. `cmake` caches the options so that only changed
0253 options must be specified in subsequent calls to configure the project. The
0254 following options are available to configure the project and enable optional
0255 components.
0256
0257 <!-- CMAKE_OPTS_BEGIN -->
0258 | Option | Description |
0259 |-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
0260 | ACTS_PARAMETER_DEFINITIONS_HEADER | Use a different (track) parameter<br>definitions header<br> type: `filepath`, default: `""` |
0261 | ACTS_SOURCELINK_SBO_SIZE | Customize the SBO size used by<br>SourceLink<br> type: `string`, default: `""` |
0262 | ACTS_FORCE_ASSERTIONS | Force assertions regardless of build<br>type<br> type: `bool`, default: `OFF` |
0263 | ACTS_USE_SYSTEM_LIBS | Use system libraries by default<br> type: `bool`, default: `OFF` |
0264 | ACTS_USE_SYSTEM_ACTSVG | Use the ActSVG system library<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0265 | ACTS_USE_SYSTEM_COVFIE | Use a system-provided covfie<br>installation<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0266 | ACTS_USE_SYSTEM_DETRAY | Use a system-provided detray<br>installation<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0267 | ACTS_USE_SYSTEM_TRACCC | Use a system-provided traccc<br>installation<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0268 | ACTS_USE_SYSTEM_VECMEM | Use a system-provided vecmem<br>installation<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0269 | ACTS_USE_SYSTEM_ALGEBRAPLUGINS | Use a system-provided algebra-plugins<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_EIGEN3 | Use a system-provided eigen3<br> type: `bool`, default: `ON` |
0273 | ACTS_BUILD_PLUGIN_ACTSVG | Build SVG display plugin<br> type: `bool`, default: `OFF` |
0274 | ACTS_BUILD_PLUGIN_CUDA | Build CUDA 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_GEOMODEL | Build GeoModel plugin<br> type: `bool`, default: `OFF` |
0280 | ACTS_BUILD_PLUGIN_TRACCC | Build Traccc plugin<br> type: `bool`, default: `OFF` |
0281 | ACTS_BUILD_PLUGIN_GEANT4 | Build Geant4 plugin<br> type: `bool`, default: `OFF` |
0282 | ACTS_BUILD_PLUGIN_EXATRKX | Build the Exa.TrkX plugin<br> type: `bool`, default: `OFF` |
0283 | ACTS_EXATRKX_ENABLE_ONNX | Build the Onnx backend for the exatrkx<br>plugin<br> type: `bool`, default: `OFF` |
0284 | ACTS_EXATRKX_ENABLE_TORCH | Build the torchscript backend for the<br>exatrkx plugin<br> type: `bool`, default: `ON` |
0285 | ACTS_EXATRKX_ENABLE_CUDA | Enable CUDA for the exatrkx plugin<br> type: `bool`, default: `OFF` |
0286 | ACTS_BUILD_PLUGIN_JSON | Build json plugin<br> type: `bool`, default: `OFF` |
0287 | ACTS_BUILD_PLUGIN_LEGACY | Build legacy plugin<br> type: `bool`, default: `OFF` |
0288 | ACTS_BUILD_PLUGIN_ONNX | Build ONNX plugin<br> type: `bool`, default: `OFF` |
0289 | ACTS_BUILD_PLUGIN_TGEO | Build TGeo plugin<br> type: `bool`, default: `OFF` |
0290 | ACTS_SETUP_ANNOY | Explicitly set up Annoy for the project<br> type: `bool`, default: `OFF` |
0291 | ACTS_BUILD_PLUGIN_HASHING | Build Hashing plugin<br> type: `bool`, default: `OFF` |
0292 | ACTS_BUILD_FATRAS | Build FAst TRAcking Simulation package<br> type: `bool`, default: `OFF` |
0293 | ACTS_BUILD_FATRAS_GEANT4 | Build Geant4 Fatras package<br> type: `bool`, default: `OFF` |
0294 | ACTS_BUILD_ALIGNMENT | Build Alignment package<br> type: `bool`, default: `OFF` |
0295 | ACTS_BUILD_EXAMPLES_DD4HEP | Build DD4hep-based code in the examples<br> type: `bool`, default: `OFF` |
0296 | ACTS_BUILD_EXAMPLES_EDM4HEP | Build EDM4hep-based code in the examples<br> type: `bool`, default: `OFF` |
0297 | ACTS_BUILD_EXAMPLES_EXATRKX | Build the Exa.TrkX example code<br> type: `bool`, default: `OFF` |
0298 | ACTS_BUILD_EXAMPLES_GEANT4 | Build Geant4-based code in the examples<br> type: `bool`, default: `OFF` |
0299 | ACTS_BUILD_EXAMPLES_HEPMC3 | Build HepMC3-based code in the examples<br> type: `bool`, default: `OFF` |
0300 | ACTS_BUILD_EXAMPLES_HASHING | Build Hashing-based code in the examples<br> type: `bool`, default: `OFF` |
0301 | ACTS_BUILD_EXAMPLES_PYTHIA8 | Build Pythia8-based code in the examples<br> type: `bool`, default: `OFF` |
0302 | ACTS_BUILD_EXAMPLES_PYTHON_BINDINGS | Build python bindings for the examples<br> type: `bool`, default: `OFF` |
0303 | ACTS_BUILD_ANALYSIS_APPS | Build Analysis applications in the<br>examples<br> type: `bool`, default: `OFF` |
0304 | ACTS_BUILD_BENCHMARKS | Build benchmarks<br> type: `bool`, default: `OFF` |
0305 | ACTS_BUILD_INTEGRATIONTESTS | Build integration tests<br> type: `bool`, default: `OFF` |
0306 | ACTS_BUILD_UNITTESTS | Build unit tests<br> type: `bool`, default: `OFF` |
0307 | ACTS_BUILD_EXAMPLES_UNITTESTS | Build unit tests<br> type: `bool`, default: `ACTS_BUILD_UNITTESTS AND ACTS_BUILD_EXAMPLES` |
0308 | ACTS_BUILD_NONCOMPILE_TESTS | Build tests that check build failure<br>invariants<br> type: `bool`, default: `OFF` |
0309 | ACTS_RUN_CLANG_TIDY | Run clang-tidy static analysis<br> type: `bool`, default: `OFF` |
0310 | ACTS_BUILD_DOCS | Build documentation<br> type: `bool`, default: `OFF` |
0311 | ACTS_SETUP_BOOST | Explicitly set up Boost for the project<br> type: `bool`, default: `ON` |
0312 | ACTS_SETUP_EIGEN3 | Explicitly set up Eigen3 for the project<br> type: `bool`, default: `ON` |
0313 | ACTS_BUILD_ODD | Build the OpenDataDetector<br> type: `bool`, default: `OFF` |
0314 | ACTS_ENABLE_CPU_PROFILING | Enable CPU profiling using gperftools<br> type: `bool`, default: `OFF` |
0315 | ACTS_ENABLE_MEMORY_PROFILING | Enable memory profiling using gperftools<br> type: `bool`, default: `OFF` |
0316 | ACTS_GPERF_INSTALL_DIR | Hint to help find gperf if profiling is<br>enabled<br> type: `string`, default: `""` |
0317 | ACTS_ENABLE_LOG_FAILURE_THRESHOLD | Enable failing on log messages with<br>level above certain threshold<br> type: `bool`, default: `OFF` |
0318 | 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: `""` |
0319 <!-- CMAKE_OPTS_END -->
0320
0321 All ACTS-specific options are disabled or empty by default and must be
0322 specifically requested.
0323
0324 ACTS comes with a couple of CMakePresets which allow to collect and
0325 origanize common configuration workflows. On the surface the current
0326 list of presets contains:
0327
0328 - `dev` as a base for developer configurations. This enables everything
0329 necessary for running the ODD full chain examples with Fatras. It
0330 sets the cpp standard to 20, the generator to ninja and enables ccache.
0331 - `perf` is similar to `dev` but tweaked for performance measurements.
0332
0333 In addition to the ACTS-specific options, many generic options are available
0334 that modify various aspects of the build. The following options are some of the
0335 most common ones. For more details, have a look at the annotated list of [useful
0336 CMake variables](https://gitlab.kitware.com/cmake/community/-/wikis/doc/cmake/Useful-Variables) or at the [CMake
0337 documentation](https://cmake.org/documentation/).
0338
0339 | Option | Description |
0340 |----------------------|-----------------------------------------------------------------------------------------------------------------------------------|
0341 | CMAKE_BUILD_TYPE | Build type, e.g. Debug or Release; affects compiler flags <br/> (if not specified **`RelWithDebInfo`** will be used as a default) |
0342 | CMAKE_CXX_COMPILER | Which C++ compiler to use, e.g. g++ or clang++ |
0343 | CMAKE_INSTALL_PREFIX | Where to install ACTS to |
0344 | CMAKE_PREFIX_PATH | Search path for external packages |
0345
0346 The build is also affected by some environment variables. They can be set by prepending them to the configuration call:
0347
0348 ```console
0349 DD4hep_DIR=<path/to/dd4hep> cmake -B <build> -S <source>
0350 ```
0351
0352 The following environment variables might be useful.
0353
0354 | Environment variable | Description |
0355 |----------------------|------------------------------------------|
0356 | DD4hep_DIR | Search path for the DD4hep installation |
0357 | HepMC3_DIR | Search path for the HepMC3 installation |
0358 | Pythia8_DIR | Search path for the Pythia8 installation |
0359
0360 ## The OpenDataDetector
0361
0362 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.
0363 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):
0364
0365 ```console
0366 git submodule init
0367 git submodule update
0368 ```
0369
0370 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
0371 `DYLD_LIBRARY_PATH` and `DD4HEP_LIBRARY_PATH` on MacOs to the install path of the ODD factory (for example: `build/thirdparty/OpenDataDetector/factory`).
0372
0373 You can now use the ODD in the python binding by using:
0374
0375 ```python
0376 oddMaterialDeco = acts.IMaterialDecorator.fromFile("PATH_TO_Acts/thirdparty/OpenDataDetector/data/odd-material-maps.root")
0377 detector = getOpenDataDetector(oddMaterialDeco)
0378 trackingGeometry = detector.trackingGeometry()
0379 decorators = detector.contextDecorators()
0380 ```
0381
0382 ## Using ACTS
0383
0384 When using ACTS in your own CMake-based project, you need to include the
0385 following lines in your `CMakeLists.txt` file:
0386
0387 ```cmake
0388 find_package (Acts COMPONENTS comp1 comp2 ...)
0389 ```
0390
0391 where `compX` are the required components from the ACTS project. See the
0392 `cmake` output for more information about which components are available.
