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++17 compatible compiler,
0007 [Boost](http://boost.org), and [Eigen](http://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](http://boost.org) >= 1.71 with `filesystem`, `program_options`, and `unit_test_framework`
0029 - [Eigen](http://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](http://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 - [SYCL](https://www.khronos.org/sycl/) for the SYCL plugin
0045 - [cugraph](https://github.com/rapidsai/cugraph) for the Exa.TrkX plugin
0046 - [libtorch](https://pytorch.org/cppdocs/installing.html) for the Exa.TrkX plugin
0047 - [Pybind11](https://github.com/pybind/pybind11) for the Python bindings of the examples
0048
0049 There are some additional dependencies that are automatically provided as part of
0050 the build system.
0051 These are usually not available through the system package manager and can be found in the ``thirdparty`` directory.
0052
0053 All external dependencies must be provided prior to building ACTS. Compatible
0054 versions of all dependencies are provided e.g. by the [LCG
0055 releases](https://lcginfo.cern.ch/) starting from [LCG 102b](https://lcginfo.cern.ch/release/102b/).
0056 For convenience, it is possible to build the required boost and eigen3 dependencies using the ACTS build system; see [Build options](#build-options).
0057 Other options are also
0058 available and are discussed in the [Building Acts](#building-acts) section.
0059
0060 [Profiling](contribution/profiling.md) details the prerequisites for profiling the ACTS project with gperftools.
0061
0062 ## Building ACTS
0063
0064 ACTS uses [CMake](https://cmake.org) to configure, build, and install the
0065 software. After checking out the repository code into a `<source>` directory,
0066 CMake is called first to configure the build into a separate `<build>`
0067 directory. A typical setup is to create a `<source>/build` directory within the
0068 sources, but this is just a convention; not a requirement. The following command
0069 runs the configuration and searches for the dependencies. The `<build>`
0070 directory is automatically created.
0071
0072 ```console
0073 $ cmake -B <build> -S <source>
0074 ```
0075
0076 The build can be configured via various options that are listed in detail in the
0077 [Build options](#build-options) section. Options are set on the command line.
0078 The previous command could be e.g. modified to
0079
0080 ```console
0081 $ cmake -B <build> -S <source> -DACTS_BUILD_UNITTESTS=on -DACTS_BUILD_FATRAS=on
0082 ```
0083
0084 After the configuration succeeded, the software is build. This is also done with cmake via the following command
0085
0086 ```console
0087 $ cmake --build <build>
0088 ```
0089
0090 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.
0091
0092 ```console
0093 $ cmake --build <build> -- ActsFatras # to build the Fatras library
0094 ```
0095
0096 The build commands are the same regardless of where you are building the
0097 software. Depending on your build environment, there are different ways how to
0098 make the dependencies available.
0099
0100 ### With a LCG release on CVMFS
0101
0102 If you have access to a machine running [CVMFS](https://cernvm.cern.ch/fs/),
0103 e.g. CERNs lxplus login machines, the dependencies can be easily satisfied
0104 via a LCG releases available through CVMFS. A setup script is provided to activate a compatible releases that can be used as follows:
0105
0106 ```console
0107 $ cd <source>
0108 $ source CI/setup_cvmfs_lcg.sh
0109 ```
0110
0111 After sourcing the setup script, you can build ACTS as described above. The
0112 following commands will build ACTS in the `<source>/build` directory with the
0113 Fatras component.
0114
0115 ```console
0116 $ cd <source>
0117 $ source CI/setup_cvmfs_lcg.sh
0118 $ cmake -B build -S . -DACTS_BUILD_FATRAS=on
0119 $ cmake --build build
0120 ```
0121
0122 ### In a container
0123
0124 A set of container images is available through the [ACTS container
0125 registry][acts_containers]. The following containers are used as part of the
0126 continuous integration setup and come with all dependencies pre-installed.
0127
0128 - `centos7-lcg101-gcc11`: based on CentOS 7 with HEP-specific software from
0129 LCG 101 using the GCC 11 compiler
0130 - `ubuntu2204`: based on Ubuntu 22.04 with manual installation of HEP-specific
0131 software
0132
0133 :::{attention}
0134 We stopped producing fully-contained LCG containers in favor of running LCG
0135 based tests directly from CVMFS.
0136 :::
0137
0138 To use these locally, you first need to pull the relevant images from the
0139 registry. Stable versions are tagged as `vX` where `X` is the version number.
0140 The latest, potentially unstable, version is tagged as `latest`. To list all
0141 available tags, e.g. for the `ubuntu2004` image, you can use the following
0142 command:
0143
0144 ```console
0145 $ docker search --list-tags ghcr.io/acts-project/ubuntu2004
0146 ```
0147
0148 The following command then downloads a stable tag of the `ubuntu2004` image:
0149
0150 ```console
0151 $ docker pull ghcr.io/acts-project/ubuntu2004:v9
0152 ```
0153
0154 This should print the image id as part of the output. You can also find out the
0155 image id by running `docker images` to list all your locally available container
0156 images.
0157
0158 Now, you need to start a shell within the container to run the build. Assuming
0159 that `<source>` is the path to your source checkout on your host machine, the
0160 following command will make the source directory available as `/acts` in the
0161 container and start an interactive `bash` shell
0162
0163 ```console
0164 $ docker run --volume=<source>:/acts:ro --interactive --tty <image> /bin/bash
0165 ```
0166
0167 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:
0168
0169 ```console
0170 container $ source /opt/lcg_view/setup.sh
0171 ```
0172
0173 Building ACTS follows the instructions above with `/acts` as the source directory, e.g.
0174
0175 ```console
0176 container $ cmake -B build -S /acts -DACTS_BUILD_FATRAS=on
0177 container $ cmake --build build
0178 ```
0179
0180 [acts_containers]: https://github.com/orgs/acts-project/packages?ecosystem=container
0181
0182 ### On your local machine
0183
0184 Building and running ACTS on your local machine is not officially supported.
0185 However, if you have the necessary prerequisites installed it is possible to use
0186 it locally. ACTS developers regularly use different Linux distributions
0187 and macOS to build and develop ACTS.
0188
0189 (build_docs)=
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 [exhale]: https://exhale.readthedocs.io
0239 [rtd_acts]: https://acts.readthedocs.io
0240
0241 ## Build options
0242
0243 CMake options can be set by adding `-D<OPTION>=<VALUE>` to the configuration
0244 command. The following command would e.g. enable the unit tests
0245
0246 ```console
0247 $ cmake -B <build> -S <source> -DACTS_BUILD_UNITTESTS=ON
0248 ```
0249
0250 Multiple options can be given. `cmake` caches the options so that only changed
0251 options must be specified in subsequent calls to configure the project. The
0252 following options are available to configure the project and enable optional
0253 components.
0254
0255 <!-- CMAKE_OPTS_BEGIN -->
0256 | Option | Description |
0257 |-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
0258 | ACTS_BUILD_EVERYTHING | Build with most options enabled (except<br>HepMC3 and documentation)<br> type: `bool`, default: `OFF` |
0259 | ACTS_PARAMETER_DEFINITIONS_HEADER | Use a different (track) parameter<br>definitions header<br> type: `filepath`, default: `""` |
0260 | ACTS_SOURCELINK_SBO_SIZE | Customize the SBO size used by<br>SourceLink<br> type: `string`, default: `""` |
0261 | ACTS_FORCE_ASSERTIONS | Force assertions regardless of build<br>type<br> type: `bool`, default: `OFF` |
0262 | ACTS_USE_SYSTEM_LIBS | Use system libraries by default<br> type: `bool`, default: `OFF` |
0263 | ACTS_USE_SYSTEM_ACTSVG | Use the ActSVG system library<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0264 | ACTS_BUILD_PLUGIN_ACTSVG | Build SVG display plugin<br> type: `bool`, default: `OFF` |
0265 | ACTS_BUILD_PLUGIN_CUDA | Build CUDA plugin<br> type: `bool`, default: `OFF` |
0266 | ACTS_BUILD_PLUGIN_DD4HEP | Build DD4hep plugin<br> type: `bool`, default: `OFF` |
0267 | ACTS_BUILD_PLUGIN_PODIO | Build Podio plugin<br> type: `bool`, default: `OFF` |
0268 | ACTS_BUILD_PLUGIN_EDM4HEP | Build EDM4hep plugin<br> type: `bool`, default: `OFF` |
0269 | ACTS_BUILD_PLUGIN_FPEMON | Build FPE monitoring plugin<br> type: `bool`, default: `OFF` |
0270 | ACTS_BUILD_PLUGIN_GEOMODEL | Build GeoModel plugin<br> type: `bool`, default: `OFF` |
0271 | ACTS_USE_SYSTEM_GEOMODEL | Use a system-provided GeoModel<br>installation<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0272 | ACTS_BUILD_PLUGIN_GEANT4 | Build Geant4 plugin<br> type: `bool`, default: `OFF` |
0273 | ACTS_BUILD_PLUGIN_EXATRKX | Build the Exa.TrkX plugin<br> type: `bool`, default: `OFF` |
0274 | ACTS_EXATRKX_ENABLE_ONNX | Build the Onnx backend for the exatrkx<br>plugin<br> type: `bool`, default: `OFF` |
0275 | ACTS_EXATRKX_ENABLE_TORCH | Build the torchscript backend for the<br>exatrkx plugin<br> type: `bool`, default: `ON` |
0276 | ACTS_BUILD_PLUGIN_IDENTIFICATION | Build Identification plugin<br> type: `bool`, default: `OFF` |
0277 | ACTS_BUILD_PLUGIN_JSON | Build json plugin<br> type: `bool`, default: `OFF` |
0278 | 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` |
0279 | ACTS_BUILD_PLUGIN_LEGACY | Build legacy plugin<br> type: `bool`, default: `OFF` |
0280 | ACTS_BUILD_PLUGIN_ONNX | Build ONNX plugin<br> type: `bool`, default: `OFF` |
0281 | ACTS_SETUP_VECMEM | Explicitly set up vecmem for the project<br> type: `bool`, default: `OFF` |
0282 | ACTS_USE_SYSTEM_VECMEM | Use a system-provided vecmem<br>installation<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0283 | ACTS_BUILD_PLUGIN_SYCL | Build SYCL plugin<br> type: `bool`, default: `OFF` |
0284 | ACTS_BUILD_PLUGIN_TGEO | Build TGeo plugin<br> type: `bool`, default: `OFF` |
0285 | ACTS_BUILD_FATRAS | Build FAst TRAcking Simulation package<br> type: `bool`, default: `OFF` |
0286 | ACTS_BUILD_FATRAS_GEANT4 | Build Geant4 Fatras package<br> type: `bool`, default: `OFF` |
0287 | ACTS_BUILD_ALIGNMENT | Build Alignment package<br> type: `bool`, default: `OFF` |
0288 | ACTS_BUILD_EXAMPLES | Build standalone examples<br> type: `bool`, default: `OFF` |
0289 | ACTS_BUILD_EXAMPLES_DD4HEP | Build DD4hep-based code in the examples<br> type: `bool`, default: `OFF` |
0290 | ACTS_BUILD_EXAMPLES_EDM4HEP | Build EDM4hep-based code in the examples<br> type: `bool`, default: `OFF` |
0291 | ACTS_BUILD_EXAMPLES_EXATRKX | Build the Exa.TrkX example code<br> type: `bool`, default: `OFF` |
0292 | ACTS_BUILD_EXAMPLES_GEANT4 | Build Geant4-based code in the examples<br> type: `bool`, default: `OFF` |
0293 | ACTS_BUILD_EXAMPLES_HEPMC3 | Build HepMC3-based code in the examples<br> type: `bool`, default: `OFF` |
0294 | ACTS_BUILD_EXAMPLES_PYTHIA8 | Build Pythia8-based code in the examples<br> type: `bool`, default: `OFF` |
0295 | ACTS_BUILD_EXAMPLES_PYTHON_BINDINGS | Build python bindings for the examples<br> type: `bool`, default: `OFF` |
0296 | ACTS_USE_SYSTEM_PYBIND11 | Use a system installation of pybind11<br> type: `bool`, default: `ACTS_USE_SYSTEM_LIBS -> OFF` |
0297 | ACTS_USE_EXAMPLES_TBB | Use Threading Building Blocks library in<br>the examples<br> type: `bool`, default: `ON` |
0298 | ACTS_BUILD_ANALYSIS_APPS | Build Analysis applications in the<br>examples<br> type: `bool`, default: `OFF` |
0299 | ACTS_BUILD_BENCHMARKS | Build benchmarks<br> type: `bool`, default: `OFF` |
0300 | ACTS_BUILD_INTEGRATIONTESTS | Build integration tests<br> type: `bool`, default: `OFF` |
0301 | ACTS_BUILD_UNITTESTS | Build unit tests<br> type: `bool`, default: `OFF` |
0302 | ACTS_BUILD_NONCOMPILE_TESTS | Build tests that check build failure<br>invariants<br> type: `bool`, default: `OFF` |
0303 | ACTS_RUN_CLANG_TIDY | Run clang-tidy static analysis<br> type: `bool`, default: `OFF` |
0304 | ACTS_BUILD_DOCS | Build documentation<br> type: `bool`, default: `OFF` |
0305 | ACTS_SETUP_BOOST | Explicitly set up Boost for the project<br> type: `bool`, default: `ON` |
0306 | ACTS_USE_SYSTEM_BOOST | Use a system-provided boost<br> type: `bool`, default: `ON` |
0307 | ACTS_SETUP_EIGEN3 | Explicitly set up Eigen3 for the project<br> type: `bool`, default: `ON` |
0308 | ACTS_USE_SYSTEM_EIGEN3 | Use a system-provided eigen3<br> type: `bool`, default: `ON` |
0309 | ACTS_BUILD_ODD | Build the OpenDataDetector<br> type: `bool`, default: `OFF` |
0310 | ACTS_ENABLE_CPU_PROFILING | Enable CPU profiling using gperftools<br> type: `bool`, default: `OFF` |
0311 | ACTS_ENABLE_MEMORY_PROFILING | Enable memory profiling using gperftools<br> type: `bool`, default: `OFF` |
0312 | ACTS_GPERF_INSTALL_DIR | Hint to help find gperf if profiling is<br>enabled<br> type: `string`, default: `""` |
0313 | ACTS_ENABLE_LOG_FAILURE_THRESHOLD | Enable failing on log messages with<br>level above certain threshold<br> type: `bool`, default: `OFF` |
0314 | 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: `""` |
0315 <!-- CMAKE_OPTS_END -->
0316
0317
0318 All ACTS-specific options are disabled or empty by default and must be
0319 specifically requested. Some of the options have interdependencies that are
0320 automatically handled, e.g. enabling any of the specific
0321 `ACTS_BUILD_EXAMPLES_...` options will also enable the overall
0322 `ACTS_BUILD_EXAMPLES` option. You only need to tell the build system what you
0323 want and it will figure out the rest.
0324
0325 In addition to the ACTS-specific options, many generic options are available
0326 that modify various aspects of the build. The following options are some of the
0327 most common ones. For more details, have a look at the annotated list of [useful
0328 CMake variables](https://cmake.org/Wiki/CMake_Useful_Variables) or at the [CMake
0329 documentation](https://cmake.org/documentation/).
0330
0331 | Option | Description |
0332 |----------------------|-----------------------------------------------------------------------------------------------------------------------------------|
0333 | CMAKE_BUILD_TYPE | Build type, e.g. Debug or Release; affects compiler flags <br/> (if not specified **`RelWithDebInfo`** will be used as a default) |
0334 | CMAKE_CXX_COMPILER | Which C++ compiler to use, e.g. g++ or clang++ |
0335 | CMAKE_INSTALL_PREFIX | Where to install ACTS to |
0336 | CMAKE_PREFIX_PATH | Search path for external packages |
0337
0338 The build is also affected by some environment variables. They can be set by prepending them to the configuration call:
0339
0340 ```console
0341 $ DD4hep_DIR=<path/to/dd4hep> cmake -B <build> -S <source>
0342 ```
0343
0344 The following environment variables might be useful.
0345
0346 | Environment variable | Description |
0347 |----------------------|------------------------------------------|
0348 | DD4hep_DIR | Search path for the DD4hep installation |
0349 | HepMC3_DIR | Search path for the HepMC3 installation |
0350 | Pythia8_DIR | Search path for the Pythia8 installation |
0351
0352 ## The OpenDataDetector
0353
0354 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.
0355 It is available via the git submodule feature by performing the following steps ([`git lfs`](https://git-lfs.github.com/) need to be installed on your machine):
0356
0357 ```console
0358 $ git submodule init
0359 $ git submodule update
0360 ```
0361
0362 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
0363 `DYLD_LIBRARY_PATH` and `DD4HEP_LIBRARY_PATH` on MacOs to the install path of the ODD factory (for example: `build/thirdparty/OpenDataDetector/factory`).
0364
0365 You can now use the ODD in the python binding by using:
0366
0367 ```python
0368 oddMaterialDeco = acts.IMaterialDecorator.fromFile("PATH_TO_Acts/thirdparty/OpenDataDetector/data/odd-material-maps.root")
0369 detector, trackingGeometry, decorators = getOpenDataDetector(oddMaterialDeco)
0370 ```
0371
0372
0373 ## Using ACTS
0374
0375 When using ACTS in your own CMake-based project, you need to include the
0376 following lines in your `CMakeLists.txt` file:
0377
0378 ```cmake
0379 find_package (Acts COMPONENTS comp1 comp2 ...)
0380 ```
0381
0382 where `compX` are the required components from the ACTS project. See the
0383 `cmake` output for more information about which components are available.
