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 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
, andunit_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 Exa.TrkX 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 for the ONNX plugin, the Exa.TrkX plugin and some examples
Pythia8 for some examples
ROOT >= 6.20 for the TGeo plugin and the examples
Sphinx >= 2.0 with Breathe, Exhale, and recommonmark extensions for the documentation
SYCL for the SYCL plugin
cugraph for the Exa.TrkX plugin
libtorch for the Exa.TrkX plugin
Pybind11 for the Python bindings of the examples
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 compilercentos7-lcg98python3-gcc10
: based on CentOS 7 with HEP-specific software from LCG 98python3 using the GCC 10 compilerubuntu2004
: 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 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 depencencies can be installed using the Python
package manager pip
:
$ cd <source>
$ pip install -r docs/requirements.txt
Tip
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 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 to automatically generate full API listings. This is equivalent to the public Read the Docs documentation, but the build takes a while to finish.
A special phony target exists to clean the documentation output files:
$ cmake --build <build> --target clean-docs
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 |
ACTS_PARAMETER_DEFINITIONS_HEADER |
Use a different (track) parameter |
ACTS_FORCE_ASSERTIONS |
Force assertions regardless of build |
ACTS_USE_SYSTEM_LIBS |
Use system libraries by default |
ACTS_BUILD_PLUGIN_AUTODIFF |
Build the autodiff plugin |
ACTS_USE_SYSTEM_AUTODIFF |
Use autodiff provided by the system |
ACTS_USE_SYSTEM_ACTSVG |
Use the ActSVG system library |
ACTS_BUILD_PLUGIN_ACTSVG |
Build SVG display plugin |
ACTS_BUILD_PLUGIN_CUDA |
Build CUDA plugin |
ACTS_BUILD_PLUGIN_DD4HEP |
Build DD4hep plugin |
ACTS_BUILD_PLUGIN_GEANT4 |
Build Geant4 plugin |
ACTS_BUILD_PLUGIN_EXATRKX |
Build the Exa.TrkX plugin |
ACTS_EXATRKX_ENABLE_ONNX |
Build the Onnx backend for the exatrkx |
ACTS_EXATRKX_ENABLE_TORCH |
Build the torchscript backend for the |
ACTS_BUILD_PLUGIN_IDENTIFICATION |
Build Identification plugin |
ACTS_BUILD_PLUGIN_JSON |
Build json plugin |
ACTS_USE_SYSTEM_NLOHMANN_JSON |
Use nlohmann::json provided by the |
ACTS_BUILD_PLUGIN_LEGACY |
Build legacy plugin |
ACTS_BUILD_PLUGIN_ONNX |
Build ONNX plugin |
ACTS_SETUP_VECMEM |
Explicitly set up vecmem for the project |
ACTS_USE_SYSTEM_VECMEM |
Use a system-provided vecmem |
ACTS_BUILD_PLUGIN_SYCL |
Build SYCL plugin |
ACTS_BUILD_PLUGIN_TGEO |
Build TGeo plugin |
ACTS_BUILD_FATRAS |
Build FAst TRAcking Simulation package |
ACTS_BUILD_FATRAS_GEANT4 |
Build Geant4 Fatras package |
ACTS_BUILD_ALIGNMENT |
Build Alignment package |
ACTS_BUILD_EXAMPLES |
Build standalone examples |
ACTS_BUILD_EXAMPLES_DD4HEP |
Build DD4hep-based code in the examples |
ACTS_BUILD_EXAMPLES_EDM4HEP |
Build EDM4hep-based code in the examples |
ACTS_BUILD_EXAMPLES_EXATRKX |
Build the Exa.TrkX example code |
ACTS_BUILD_EXAMPLES_GEANT4 |
Build Geant4-based code in the examples |
ACTS_BUILD_EXAMPLES_HEPMC3 |
Build HepMC3-based code in the examples |
ACTS_BUILD_EXAMPLES_PYTHIA8 |
Build Pythia8-based code in the examples |
ACTS_BUILD_EXAMPLES_PYTHON_BINDINGS |
Build python bindings for the examples |
ACTS_BUILD_EXAMPLES_BINARIES |
Build the examples binaries (deprecated) |
ACTS_USE_SYSTEM_PYBIND11 |
Use a system installation of pybind11 |
ACTS_USE_EXAMPLES_TBB |
Use Threading Building Blocks library in |
ACTS_BUILD_ANALYSIS_APPS |
Build Analysis applications in the |
ACTS_BUILD_BENCHMARKS |
Build benchmarks |
ACTS_BUILD_INTEGRATIONTESTS |
Build integration tests |
ACTS_BUILD_UNITTESTS |
Build unit tests |
ACTS_RUN_CLANG_TIDY |
Run clang-tidy static analysis |
ACTS_BUILD_DOCS |
Build documentation |
ACTS_SETUP_BOOST |
Explicitly set up Boost for the project |
ACTS_USE_SYSTEM_BOOST |
Use a system-provided boost |
ACTS_SETUP_EIGEN3 |
Explicitly set up Eigen3 for the project |
ACTS_USE_SYSTEM_EIGEN3 |
Use a system-provided eigen3 |
ACTS_BUILD_ODD |
Build the OpenDataDetector |
ACTS_ENABLE_CPU_PROFILING |
Enable CPU profiling using gperftools |
ACTS_ENABLE_MEMORY_PROFILING |
Enable memory profiling using gperftools |
ACTS_GPERF_INSTALL_DIR |
Hint to help find gperf if profiling is |
ACTS_ENABLE_LOG_FAILURE_THRESHOLD |
Enable failing on log messages with |
ACTS_LOG_FAILURE_THRESHOLD |
Log level above which an exception |
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 |
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.