Getting started

Quick start

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

$ git clone --recursive 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++17 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:

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 97apython3. 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 a LCG releases available through CVMFS. A setup script is provided to activate a compatible releases that can be used as follows:

$ cd <source>
$ source CI/setup_cvmfs_lcg.sh

After sourcing the setup script, you can build Acts as described above. The following commands will build Acts in the <source>/build directory with the Fatras component.

$ cd <source>
$ source CI/setup_cvmfs_lcg.sh
$ cmake -B build -S . -DACTS_BUILD_FATRAS=on
$ cmake --build build

In a container

A set of container images is available through the Acts container registry. The following containers are used as part of the continous integration setup and come with all dependencies pre-installed.

  • centos7-lcg97apython3-gcc9: based on CentOS 7 with HEP-specific software from LCG 97apython3 using the GCC 9 compiler

  • centos7-lcg98python3-gcc10: based on CentOS 7 with HEP-specific software from LCG 98python3 using the GCC 10 compiler

  • ubuntu2004: based on Ubuntu 20.04 with manual installation of HEP-specific software

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/ubuntu2004

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

$ docker pull ghcr.io/acts-project/ubuntu2004:v9

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 offically 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.

Building the documentation

The documentation uses Doxygen to extract the source code documentation and Sphinx with the Breathe and Exhale extensions to generate the documentation website. To build the documentation locally, you need to have Doxygen installed from your package manager. Sphinx and its extensions can be installed using the Python package manager via

$ cd <source>
# --user installs to a user-specific directory instead of the system
$ pip install --user -r docs/requirements.txt

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 either of the following two build targets

$ cmake --build <build> --target docs # default fast option
# or
$ cmake --build <build> --target docs-with-api # full documentation

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 but the full API documentation is not generated. The second target builds the full documentation using Exhale to automatically generate the API documentation. This is equivalent to the public Read the Docs documentation, but the build takes around ten minutes to finish.

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_BUILD_EVERYTHING

Build with most options enabled (except
HepMC3 and documentation)
type: bool, default: OFF

ACTS_PARAMETER_DEFINITIONS_HEADER

Use a different (track) parameter
definitions header
type: filepath, default: ""

ACTS_FORCE_ASSERTIONS

Force assertions regardless of build
type
type: bool, default: OFF

ACTS_BUILD_PLUGIN_AUTODIFF

Build the autodiff plugin
type: bool, default: OFF

ACTS_USE_SYSTEM_AUTODIFF

Use autodiff provided by the system
instead of the bundled version
type: bool, default: OFF

ACTS_BUILD_PLUGIN_CUDA

Build CUDA plugin
type: bool, default: OFF

ACTS_BUILD_PLUGIN_DD4HEP

Build DD4hep plugin
type: bool, default: OFF

ACTS_BUILD_PLUGIN_EXATRKX

Build the Exa.TrkX plugin
type: bool, default: OFF

ACTS_USE_SYSTEM_ACTSDD4HEP

Use the ActsDD4hep glue library provided
by the system instead of building it
type: bool, default: OFF

ACTS_BUILD_PLUGIN_IDENTIFICATION

Build Identification plugin
type: bool, default: OFF

ACTS_BUILD_PLUGIN_JSON

Build json plugin
type: bool, default: OFF

ACTS_USE_SYSTEM_NLOHMANN_JSON

Use nlohmann::json provided by the
system instead of the bundled version
type: bool, default: OFF

ACTS_BUILD_PLUGIN_LEGACY

Build legacy plugin
type: bool, default: OFF

ACTS_BUILD_PLUGIN_ONNX

Build ONNX plugin
type: bool, default: OFF

ACTS_SETUP_VECMEM

Explicitly set up vecmem for the project
type: bool, default: OFF

ACTS_USE_SYSTEM_VECMEM

Use a system-provided vecmem
installation
type: bool, default: OFF

ACTS_BUILD_PLUGIN_SYCL

Build SYCL plugin
type: bool, default: OFF

ACTS_BUILD_PLUGIN_TGEO

Build TGeo plugin
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 standalone examples
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_EXATRKX

Build the Exa.TrkX example code
type: bool, default: OFF

ACTS_BUILD_EXAMPLES_GEANT4

Build Geant4-based code in the examples
type: bool, default: OFF

ACTS_BUILD_EXAMPLES_HEPMC3

Build HepMC3-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

Build python bindings for the examples
type: bool, default: OFF

ACTS_USE_SYSTEM_PYBIND11

Use a system installation of pybind11
type: bool, default: OFF

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_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_USE_SYSTEM_BOOST

Use a system-provided boost
type: bool, default: ON

ACTS_SETUP_EIGEN3

Explicitly set up Eigen3 for the project
type: bool, default: ON

ACTS_USE_SYSTEM_EIGEN3

Use a system-provided eigen3
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: ""

All Acts-specific options are disabled or empty by default and must be specifically requested. Some of the options have interdependencies that are automatically handled, e.g. enabling any of the specific ACTS_BUILD_EXAMPLES_... options will also enable the overall ACTS_BUILD_EXAMPLES option. You only need to tell the build system what you want and it will figure out the rest.

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

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. It is available via the git submodule feature by performing the following steps (git lfs need to be installed on your machine):

$ git submodule init
$ git submodule update

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 DYLD_LIBRARY_PATH and DD4HEP_LIBRARY_PATH on MacOs to the install path of the ODD factory (for example: build/thirdparty/OpenDataDetector/factory).

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

oddMaterialDeco = acts.IMaterialDecorator.fromFile("PATH_TO_Acts/thirdparty/OpenDataDetector/data/odd-material-maps.root")
detector, trackingGeometry, decorators = getOpenDataDetector(odd_dir, oddMaterialDeco)

Using Acts

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.