Quick start

ACTS is developed in C++ and is built using CMake. Building the core library requires a C++20 compatible compiler, Boost, and Eigen. The following commands will clone the repository, configure, and build the core library:

git clone https://github.com/acts-project/acts <source>
cmake -B <build> -S <source>
cmake --build <build>

For a full list of dependencies, including specific versions, see the Prerequisites section below. Build options to activate additional components are described in the Build options section.

Prerequisites

The following dependencies are required to build the ACTS core library:

A C++20 compatible compiler (recent versions of either gcc and clang should work)
CMake >= 3.14
Boost >= 1.71 with filesystem, program_options, and unit_test_framework
Eigen >= 3.3.7

The following dependencies are optional and are needed to build additional components:

CUDA for the CUDA plugin and the GNN plugin and its examples
DD4hep >= 1.11 for the DD4hep plugin and some examples
Doxygen >= 1.8.15 for the documentation
Geant4 for some examples
HepMC >= 3.2.1 for some examples
Intel Threading Building Blocks >= 2020.1 for the examples
ONNX Runtime >= 1.12.0 for the ONNX plugin, the GNN plugin and some examples
Pythia8 for some examples
ROOT >= 6.20 for the ROOT plugin and the examples
Sphinx >= 2.0 with Breathe, Exhale, and recommonmark extensions for the documentation
libtorch for the GNN plugin
Pybind11 for the Python bindings of the examples
FastJet >= 3.4.0 for the FastJet plugin

There are some additional dependencies that are automatically provided as part of the build system. These are usually not available through the system package manager and can be found in the thirdparty directory.

All external dependencies must be provided prior to building ACTS. Compatible versions of all dependencies are provided e.g. by the LCG releases starting from LCG 102b. For convenience, it is possible to build the required boost and eigen3 dependencies using the ACTS build system; see Build options. Other options are also available and are discussed in the Building ACTS section.

Profiling details the prerequisites for profiling the ACTS project with gperftools.

Building ACTS

ACTS uses CMake to configure, build, and install the software. After checking out the repository code into a <source> directory, CMake is called first to configure the build into a separate <build> directory. A typical setup is to create a <source>/build directory within the sources, but this is just a convention; not a requirement. The following command runs the configuration and searches for the dependencies. The <build> directory is automatically created.

cmake -B <build> -S <source>

The build can be configured via various options that are listed in detail in the Build options section. Options are set on the command line. The previous command could be e.g. modified to

cmake -B <build> -S <source> -DACTS_BUILD_UNITTESTS=on -DACTS_BUILD_FATRAS=on

After the configuration succeeded, the software is build. This is also done with cmake via the following command

cmake --build <build>

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.

cmake --build <build> -- ActsFatras # to build the Fatras library

The build commands are the same regardless of where you are building the software. Depending on your build environment, there are different ways how to make the dependencies available.

With a LCG release on CVMFS

If you have access to a machine running CVMFS, e.g. CERNs lxplus login machines, the dependencies can be easily satisfied via an LCG releases available through CVMFS. Source the cvmfs setup script provided by the machine. It is suggested to select a recent <lcg_release> and <lcg_platform> combination. (Have a look at the CI jobs to get an overview on what we are currently testing):

source /cvmfs/sft.cern.ch/lcg/views/<lcg_release>/<lcg_platform>/setup.sh

After sourcing the setup script, you can build ACTS as described above.

In a container

A set of container images is available through the ACTS container registry. These images are built using the configuration that is used in CI, and they contain all the dependencies required to build ACTS.

Note: Most containers are only build for the x86_64 platform. If you are on an aarch64 (such as a recent Mac), you'll need to use the ubuntu2404 container, which is built for aarch64 and x86_64!

Furthermore, we are also testing on, but do not provide the corresponding containers:

alma9 (HEP-specific software from LCG 106 or 107 and various clang versions)
macOS-10.15

Warning: We stopped producing fully-contained LCG containers in favor of running LCG based tests directly from CVMFS.

To use these locally, you first need to pull the relevant images from the registry. Stable versions are tagged as vX where X is the version number. The latest, potentially unstable, version is tagged as latest. To list all available tags, e.g. for the ubuntu2004 image, you can use the following command:

docker search --list-tags ghcr.io/acts-project/ubuntu2404

The following command then downloads a stable tag of the ubuntu2404 image:

docker pull ghcr.io/acts-project/ubuntu2404:51

This should print the image id as part of the output. You can also find out the image id by running docker images to list all your locally available container images.

Now, you need to start a shell within the container to run the build. Assuming that <source> is the path to your source checkout on your host machine, the following command will make the source directory available as /acts in the container and start an interactive bash shell

docker run --volume=<source>:/acts:ro --interactive --tty <image> /bin/bash

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:

container $ source /opt/lcg_view/setup.sh

Building ACTS follows the instructions above with /acts as the source directory, e.g.

container $ cmake -B build -S /acts -DACTS_BUILD_FATRAS=on

container $ cmake --build build

On your local machine

Building and running ACTS on your local machine is not officially supported. However, if you have the necessary prerequisites installed it is possible to use it locally. ACTS developers regularly use different Linux distributions and macOS to build and develop ACTS. It is possible to use Spack to more easily install ACTS' dependencies; see the building with Spack page for more information.

Building the documentation

The documentation uses Doxygen to extract the source code documentation and Sphinx with the Breathe extension to generate the documentation website. To build the documentation locally, you need to have Doxygen version 1.9.5 or newer installed. Sphinx and a few other dependencies can be installed using the Python package manager pip:

cd <source>

pip install -r docs/requirements.txt

Remarks: It is strongly recommended to use a virtual >environment for >this purpose! For example, run

python -m venv docvenv

source docvenv/bin/activate

to create a local virtual environment, and then run the pip command above.

To activate the documentation build targets, the ACTS_BUILD_DOCS option has to be set

cmake -B <build> -S <source> -DACTS_BUILD_DOCS=on

Then the documentation can be build with this target

cmake --build <build> --target docs

The default option includes the Doxygen, Sphinx, and the Breathe extension, i.e. the source code information can be used in the manually written documentation. An attempt is made to pull in symbols that are cross-referenced from other parts of the documentation. This is not guaranteed to work: in case of errors you will need to manually pull in symbols to be documented.

Build options

CMake options can be set by adding -D<OPTION>=<VALUE> to the configuration command. The following command would e.g. enable the unit tests

cmake -B <build> -S <source> -DACTS_BUILD_UNITTESTS=ON

Multiple options can be given. cmake caches the options so that only changed options must be specified in subsequent calls to configure the project. The following options are available to configure the project and enable optional components.

Option	Description
ACTS_PARAMETER_DEFINITIONS_HEADER	Use a different (track) parameter definitions header type: filepath, default: ""
ACTS_SOURCELINK_SBO_SIZE	Customize the SBO size used by SourceLink type: string, default: ""
ACTS_FORCE_ASSERTIONS	Force assertions regardless of build type type: bool, default: OFF
ACTS_USE_SYSTEM_LIBS	Use system libraries by default type: bool, default: OFF
ACTS_USE_SYSTEM_ACTSVG	Use the ActSVG system library type: bool, default: ACTS_USE_SYSTEM_LIBS -> OFF
ACTS_USE_SYSTEM_ALGEBRAPLUGINS	Use a system-provided algebra-plugins installation type: bool, default: ACTS_USE_SYSTEM_LIBS -> OFF
ACTS_SETUP_ALGEBRAPLUGINS	If we want to setup algebra-plugins type: bool, default: ON
ACTS_USE_SYSTEM_COVFIE	Use a system-provided covfie installation type: bool, default: ACTS_USE_SYSTEM_LIBS -> OFF
ACTS_SETUP_COVFIE	If we want to setup covfie type: bool, default: ON
ACTS_USE_SYSTEM_DETRAY	Use a system-provided detray installation type: bool, default: ACTS_USE_SYSTEM_LIBS -> OFF
ACTS_SETUP_DETRAY	If we want to setup detray type: bool, default: ON
ACTS_USE_SYSTEM_VECMEM	Use a system-provided vecmem installation type: bool, default: ACTS_USE_SYSTEM_LIBS -> OFF
ACTS_SETUP_VECMEM	If we want to setup vecmem type: bool, default: ON
ACTS_USE_SYSTEM_TRACCC	Use a system-provided traccc installation type: bool, default: ACTS_USE_SYSTEM_LIBS -> OFF
ACTS_USE_SYSTEM_NLOHMANN_JSON	Use nlohmann::json provided by the system instead of the bundled version type: bool, default: ACTS_USE_SYSTEM_LIBS -> OFF
ACTS_USE_SYSTEM_PYBIND11	Use a system installation of pybind11 type: bool, default: ACTS_USE_SYSTEM_LIBS -> OFF
ACTS_USE_SYSTEM_MODULEMAPGRAPH	Use a system installation of ModuleMapGraph type: bool, default: ACTS_USE_SYSTEM_LIBS -> OFF
ACTS_USE_SYSTEM_EIGEN3	Use a system-provided eigen3 type: bool, default: ON
ACTS_BUILD_PLUGIN_ACTSVG	Build SVG display plugin type: bool, default: OFF
ACTS_BUILD_PLUGIN_DD4HEP	Build DD4hep plugin type: bool, default: OFF
ACTS_BUILD_PLUGIN_EDM4HEP	Build EDM4hep plugin type: bool, default: OFF
ACTS_BUILD_PLUGIN_FPEMON	Build FPE monitoring plugin type: bool, default: OFF
ACTS_BUILD_PLUGIN_FASTJET	Build FastJet plugin type: bool, default: OFF
ACTS_BUILD_PLUGIN_GEOMODEL	Build GeoModel plugin type: bool, default: OFF
ACTS_BUILD_PLUGIN_TRACCC	Build Traccc plugin type: bool, default: OFF
ACTS_BUILD_PLUGIN_GEANT4	Build Geant4 plugin type: bool, default: OFF
ACTS_BUILD_PLUGIN_GNN	Build the GNN plugin type: bool, default: OFF
ACTS_GNN_ENABLE_ONNX	Build the Onnx backend for the gnn plugin type: bool, default: OFF
ACTS_GNN_ENABLE_TORCH	Build the torchscript backend for the gnn plugin type: bool, default: ON
ACTS_GNN_ENABLE_CUDA	Enable CUDA for the gnn plugin type: bool, default: OFF
ACTS_GNN_ENABLE_MODULEMAP	Enable Module-Map-based graph construction type: bool, default: OFF
ACTS_GNN_ENABLE_TENSORRT	Enable the native TensorRT inference modules type: bool, default: OFF
ACTS_BUILD_PLUGIN_JSON	Build json plugin type: bool, default: OFF
ACTS_BUILD_PLUGIN_ONNX	Build ONNX plugin type: bool, default: OFF
ACTS_BUILD_PLUGIN_ROOT	Build ROOT plugin type: bool, default: OFF
ACTS_SETUP_ANNOY	Explicitly set up Annoy for the project type: bool, default: OFF
ACTS_BUILD_PLUGIN_HASHING	Build Hashing plugin type: bool, default: OFF
ACTS_BUILD_PYTHON_WHEEL	Settings to build for python deployment with scikit-build-core type: bool, default: OFF
ACTS_BUILD_PYTHON_BINDINGS	Build python bindings for all enabled components type: bool, default: OFF
ACTS_BUILD_FATRAS	Build FAst TRAcking Simulation package type: bool, default: OFF
ACTS_BUILD_FATRAS_GEANT4	Build Geant4 Fatras package type: bool, default: OFF
ACTS_BUILD_ALIGNMENT	Build Alignment package type: bool, default: OFF
ACTS_BUILD_EXAMPLES	Build basic examples components type: bool, default: OFF
ACTS_BUILD_EXAMPLES_DD4HEP	Build DD4hep-based code in the examples type: bool, default: OFF
ACTS_BUILD_EXAMPLES_EDM4HEP	Build EDM4hep-based code in the examples type: bool, default: OFF
ACTS_BUILD_EXAMPLES_PODIO	Build Podio-based code in the examples type: bool, default: OFF
ACTS_BUILD_EXAMPLES_GNN	Build the GNN example code type: bool, default: OFF
ACTS_BUILD_EXAMPLES_GEANT4	Build Geant4-based code in the examples type: bool, default: OFF
ACTS_BUILD_EXAMPLES_HASHING	Build Hashing-based code in the examples type: bool, default: OFF
ACTS_BUILD_EXAMPLES_PYTHIA8	Build Pythia8-based code in the examples type: bool, default: OFF
ACTS_BUILD_EXAMPLES_PYTHON_BINDINGS	[Deprecated] Build python bindings and enables the examples type: bool, default: OFF
ACTS_BUILD_EXAMPLES_ROOT	Build modules based on ROOT I/O type: bool, default: ON
ACTS_BUILD_ANALYSIS_APPS	Build Analysis applications in the examples type: bool, default: OFF
ACTS_BUILD_BENCHMARKS	Build benchmarks type: bool, default: OFF
ACTS_BUILD_INTEGRATIONTESTS	Build integration tests type: bool, default: OFF
ACTS_BUILD_UNITTESTS	Build unit tests type: bool, default: OFF
ACTS_BUILD_EXAMPLES_UNITTESTS	Build unit tests type: bool, default: ACTS_BUILD_UNITTESTS AND ACTS_BUILD_EXAMPLES
ACTS_RUN_CLANG_TIDY	Run clang-tidy static analysis type: bool, default: OFF
ACTS_BUILD_DOCS	Build documentation type: bool, default: OFF
ACTS_SETUP_BOOST	Explicitly set up Boost for the project type: bool, default: ON
ACTS_SETUP_EIGEN3	Explicitly set up Eigen3 for the project type: bool, default: ON
ACTS_BUILD_ODD	Build the OpenDataDetector type: bool, default: OFF
ACTS_ENABLE_CPU_PROFILING	Enable CPU profiling using gperftools type: bool, default: OFF
ACTS_ENABLE_MEMORY_PROFILING	Enable memory profiling using gperftools type: bool, default: OFF
ACTS_GPERF_INSTALL_DIR	Hint to help find gperf if profiling is enabled type: string, default: ""
ACTS_ENABLE_LOG_FAILURE_THRESHOLD	Enable failing on log messages with level above certain threshold type: bool, default: OFF
ACTS_LOG_FAILURE_THRESHOLD	Log level above which an exception should be automatically thrown. If ACTS_ENABLE_LOG_FAILURE_THRESHOLD is set and this is unset, this will enable a runtime check of the log level. type: string, default: ""
ACTS_COMPILE_HEADERS	Generate targets to compile header files type: bool, default: ON

All ACTS-specific options are disabled or empty by default and must be specifically requested.

ACTS comes with a couple of CMakePresets which allow to collect and origanize common configuration workflows. On the surface the current list of presets contains:

dev as a base for developer configurations. This enables everything necessary for running the ODD full chain examples with Fatras. It sets the cpp standard to 20, the generator to ninja and enables ccache.
perf is similar to dev but tweaked for performance measurements.

In addition to the ACTS-specific options, many generic options are available that modify various aspects of the build. The following options are some of the most common ones. For more details, have a look at the annotated list of useful CMake variables or at the CMake documentation.

Option	Description
CMAKE_BUILD_TYPE	Build type, e.g. Debug or Release; affects compiler flags (if not specified RelWithDebInfo will be used as a default)
CMAKE_CXX_COMPILER	Which C++ compiler to use, e.g. g++ or clang++
CMAKE_INSTALL_PREFIX	Where to install ACTS to
CMAKE_PREFIX_PATH	Search path for external packages

The build is also affected by some environment variables. They can be set by prepending them to the configuration call:

DD4hep_DIR=<path/to/dd4hep> cmake -B <build> -S <source>

The following environment variables might be useful.

Environment variable	Description
DD4hep_DIR	Search path for the DD4hep installation
HepMC3_DIR	Search path for the HepMC3 installation
Pythia8_DIR	Search path for the Pythia8 installation

Remarks: Even though these individual environment variables can be used to make CMake locate dependency, it is usually preferable to use CMAKE_PREFIX_PATH to point to the root installation directory of the dependencies.

The OpenDataDetector

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. When configuring with ACTS_BUILD_ODD=ON, the detector is fetched automatically via CMake's ExternalProject_Add. This step requires network access during the first build to clone the upstream repository.

To use it, build ACTS with the ACTS_BUILD_ODD option and then point either LD_LIBRARY_PATH on Linux or DYLD_LIBRARY_PATH and DD4HEP_LIBRARY_PATH on macOS to the install path of the ODD factory (for example: $ODD_BUILD_DIR/factory). The setup scripts generated by the build do this automatically when present.

You can now use the ODD in the python binding by using:

import acts.root
from acts.examples.odd import getOpenDataDetectorDirectory, getOpenDataDetector
 
odd_dir = getOpenDataDetectorDirectory()
materialDecorator = acts.root.RootMaterialDecorator(
    fileName=str(odd_dir / "data/odd-material-maps.root"),
    level=acts.logging.INFO,
)
detector = getOpenDataDetector(materialDecorator=materialDecorator)
trackingGeometry = detector.trackingGeometry()
decorators = detector.contextDecorators()

Using ACTS in downstream code

When using ACTS in your own CMake-based project, you need to include the following lines in your CMakeLists.txt file:

find_package (Acts COMPONENTS comp1 comp2 ...)

where compX are the required components from the ACTS project. See the cmake output for more information about which components are available.