Skip to content
Snippets Groups Projects
README.md 10.2 KiB
Newer Older
Christian Gumpert's avatar
Christian Gumpert committed
# A Common Tracking Software (ACTS) Project {#mainpage}

1. [Introduction](#intro)
2. [Mailing list](#mailing-list)
3. [Getting started](#getting-started)
    1. [Prerequisites](#prerequisites)
    2. [Installation](#installation)
    3. [cmake options](#cmake-options)
    4. [Using docker](#using-docker)
Christian Gumpert's avatar
Christian Gumpert committed
4. [Using ACTS in your own cmake project](#using-acts)
5. [Documentation](#documentation)
6. [License and authors](#license-authors)
Christian Gumpert's avatar
Christian Gumpert committed
# <a name="intro">Introduction</a>
This project is supposed to be an experiment-independent set of track reconstruction tools. The main philosophy is to provide high-level track reconstruction modules that can be used for any tracking detector. The description of the tracking detector's geometry is optimized for efficient navigation and quick extrapolation of tracks. Converters for several common geometry description languages exist. Having a highly performant, yet largely customizable implementation of track reconstruction algorithms was a primary objective for the design of this toolset. Additionally, the applicability to real-life HEP experiments played a major role in the development process. Apart from algorithmic code, this project also provides an event data model for the description of track parameters and measurements.
Christian Gumpert's avatar
Christian Gumpert committed
Key features of this project include:
* tracking geometry description which can be constructed from TGeo, DD4Hep, or gdml input,
* simple and efficient event data model,
* performant and highly flexible algorithms for track propagation and fitting,
* basic seed finding algorithms.
The git repository for the ACTS project can be found at <a href="https://gitlab.cern.ch/acts/a-common-tracking-sw.git">https://gitlab.cern.ch/acts/a-common-tracking-sw.git</a>.

Christian Gumpert's avatar
Christian Gumpert committed
# <a name="mailing-list">Mailing list</a>
jhrdinka's avatar
jhrdinka committed

Christian Gumpert's avatar
Christian Gumpert committed
In order to receive the latest updates, users of the ACTS project are encouraged to subscribe to [acts-users@cern.ch](https://e-groups.cern.ch/e-groups/Egroup.do?egroupName=acts-users). This list provides:
- regular updates on the software,
- access to the ACTS JIRA project for bug fixes/feature requests,
- a common place for asking any kind of questions.
Andreas Salzburger's avatar
Andreas Salzburger committed

Christian Gumpert's avatar
Christian Gumpert committed
If you find a bug, have a feature request, or want to contribute to ACTS, please have a look at the [contribution guide](CONTRIBUTING.md).
Christian Gumpert's avatar
Christian Gumpert committed
# <a name="getting-started">Getting started</a>
Christian Gumpert's avatar
Christian Gumpert committed
## <a name="prerequisites">Prerequisites</a>
Christian Gumpert's avatar
Christian Gumpert committed
Only few dependencies are required to build the Core library of ACTS. A list of prerequisites required is given below with the version numbers indicating which versions were tested. Older versions may or may not work, feedback is very welcome.
Christian Gumpert's avatar
Christian Gumpert committed

The following dependencies are required:

Christian Gumpert's avatar
Christian Gumpert committed
+ [clang](http://clang.llvm.org/) (>= 3.8.0) or [gcc](https://gcc.gnu.org/) (>= 6.2)
+ [cmake](https://cmake.org/) (>= 3.5)
+ [boost](http://boost.org/) (>= 1.62, with <tt>program_options</tt>)
+ [Eigen](http://eigen.tuxfamily.org/) (>= 3.2.10)
Christian Gumpert's avatar
Christian Gumpert committed
The following dependencies are optional and are only needed for some of the plugins
Christian Gumpert's avatar
Christian Gumpert committed
+ [doxygen](http://doxygen.org) (>= 1.8.11) for the documentation
Christian Gumpert's avatar
Christian Gumpert committed
+ [graphviz](http://www.graphviz.org/) (>= 2.26.00) for the documentation
+ [ROOT](https://root.cern.ch/) (>= 6.08.00) for TGeo plugin & for DD4hep plugin
jhrdinka's avatar
jhrdinka committed
+ [DD4Hep](https://github.com/AIDASoft/DD4hep) for DD4Hep plugin
### Using recent CMake releases from CVMFS

Recent releases of CMake can be found on CVMFS at `/cvmfs/sft.cern.ch/lcg/contrib/CMake/`. These builds are self-contained and intended to work even on non-Redhat linux distributions. In particular, they have been successfully used on Ubuntu 14.04.

To use the CMake release x.y.z from this source, do...

    export PATH=/cvmfs/sft.cern.ch/lcg/contrib/CMake/x.y.z/Linux-x86_64/bin:${PATH}

Christian Gumpert's avatar
Christian Gumpert committed
## <a name="installation">Installation</a>
Christian Gumpert's avatar
Christian Gumpert committed
The ACTS repository is hosted on the GitLab instance at CERN. For the time being you need to have a full CERN account in order to access the repository. We are working on a solution for non-CERN users. Cmake is used as build system for compiling and installing ACTS libraries. For a complete description of the available cmake options please see below.
Christian Gumpert's avatar
Christian Gumpert committed
In order to install the latest version, you can follow the instructions below where \<DIR\> refers to some directory which needs to be set depending on your configuration.
Christian Gumpert's avatar
Christian Gumpert committed

> git clone https://gitlab.cern.ch/acts/a-common-tracking-sw.git \<ACTS_DIR\><br />
> mkdir \<BUILD_DIR\><br />
> cd \<BUILD_DIR\><br />
Christian Gumpert's avatar
Christian Gumpert committed
> cmake \<ACTS_DIR\> -DEIGEN_INCLUDE_DIR=\<EIGEN_INSTALLATION\> -DBOOST_ROOT=\<BOOST_INSTALLATION\> -DCMAKE_INSTALL_PREFIX=\<INSTALL_DIR\><br />
Christian Gumpert's avatar
Christian Gumpert committed
> make<br />
> make install<br />

Christian Gumpert's avatar
Christian Gumpert committed
## <a name="cmake-options">cmake options</a>
Christian Gumpert's avatar
Christian Gumpert committed
For a complete list of cmake options please refer to the [official documentation](https://cmake.org/cmake/help/v3.1/index.html) and this nice [list of general cmake options](https://cmake.org/Wiki/CMake_Useful_Variables). A full list of ACTS specific cmake options can be obtained by running the following command
Christian Gumpert's avatar
Christian Gumpert committed
> cmake \<ACTS_DIR\> -DPRINT_OPTIONS=ON
Christian Gumpert's avatar
Christian Gumpert committed
Important options relevant for the ACTS project are given below. They can be set by adding '-D\<OPTION\>=\<VALUE\>' to the cmake command.
Christian Gumpert's avatar
Christian Gumpert committed

|option|default|description|
|------|-------|-----------|
Christian Gumpert's avatar
Christian Gumpert committed
|BOOST_ROOT             | empty                 | path to the ROOT installation                  |
|EIGEN_INCLUDE_DIR      | empty                 | path to the Eigen installation                 |
|BUILD_DD4HEP_PLUGIN    | OFF                   | build DD4Hep plugin (requires DD4hep)          |
|BUILD_DOC              | OFF                   | build doxygen documentation (requires doxygen) |
|BUILD_TESTS            | ON                    | build unit tests                               |
|BUILD_TGEO_PLUGIN      | OFF                   | build TGeo plugin (requires ROOT)              |
|BUILD_MATERIAL_PLUGIN  | OFF                   | build material mapping plugin                  |
|CMAKE_INSTALL_PREFIX   | empty                 | target installation directory                  |
|CMAKE_PREFIX_PATH      | empty                 | search path for external packages              |     
|CMAKE_CXX_COMPILER     | empty                 | set C++ compiler (e.g. g++ or clang++)         |    
|CMAKE_BUILD_TYPE       | None                  | build type (e.g. Debug, Release) affects compiler flags |

## <a name="using-docker">Build ACTS using docker</a>

The ACTS team provides you with a [docker](https://en.wikipedia.org/wiki/Docker_(software)) image with all required software already pre-installed. This is the very same image used in our continuous integration system. Hence, it is very well tested and should be the easiest way to get you started. In order to use it, you need to have docker installed. On Ubuntu systems one could achieve this by running

> sudo apt-get install docker.io

While the docker image provides you with the environment for building ACTS, it does not contain the source code itself. The reasoning behind this is that you can develop ACTS on your host machine using your preferred development tools/editors/GUIs and use the docker container only for compiling/testing. Therefore, you need to clone the ACTS repository first

> git clone https://gitlab.cern.ch/acts/a-common-tracking-sw.git acts

As a second step you need to pull the ACTS docker image

> docker pull gitlab-registry.cern.ch/acts/a-common-tracking-sw

Before starting the docker container, you can create a shorter tag for this image to avoid a lot of typing

> docker tag gitlab-registry.cern.ch/acts/a-common-tracking-sw acts

Now spin up the docker container with the mysterious command

> docker run -d -t -i -v acts:/acts -e LOCAL_USER_ID=\`id -u\` -e LOCAL_GROUP_ID=\`id -g\` --name acts acts

Here is what it means:

- -d runs the container in the background (detached state)
- -t gives you acces to a shell (bash)
- -i stands for interactive and allows you to attach
- -v maps the directory `acts` from your host machine to `/acts` inside the container
- -e sets some environment variables which are used to map the current user to the user inside the container
- --name gives a name to the container
- the last argument is a reference to the docker image used for creating this container

You can attach to the container using

> docker attach acts

You can then go ahead like you would on your host machine and start building ACTS using `cmake ... && make`. Remember that the ACTS source code is located under `/acts` inside the container. There is also a simple python wrapper script called `acts-build` in case you do not remember the longish cmake command. Running `acts-build --help` gives you a (short) list of available options.  

For instance you could compile and install ACTS using

> acts-build /acts/ /workdir/build --make-options "install" --cmake-options " -DCMAKE_INSTALL_PREFIX=/workdir/install"<br />
> cd /workdir/build && make test<br />
> cd /workdir/install/bin<br />
> source setup.sh<br />
> ./Examples/ACTSGenericDetector

You can detach from the container again pressing the key sequence `CTRL+P CTRL+Q`.  
If you just want to test the compilation non-interactively, you could also execute (from the host machine)

> docker exec acts acts-start acts-build /acts /workdir/build

This command could, for instance, be used as custom build command in IDEs.
Christian Gumpert's avatar
Christian Gumpert committed
# <a name="using-acts">Using ACTS in your own cmake project</a>

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.
Christian Gumpert's avatar
Christian Gumpert committed

# <a name="documentation">Documentation</a>

You can find a complete documentation of the ACTS functionality and the class reference guide at [http://acts.web.cern.ch/ACTS/latest/doc/index.html](http://acts.web.cern.ch/ACTS/latest/doc/index.html).
Christian Gumpert's avatar
Christian Gumpert committed
# <a name="license-authors">License and authors</a>
This project is published under the Mozilla Public License, v. 2.0. Details of
this license can be found in the [LICENSE](LICENSE) file or at
http://mozilla.org/MPL/2.0/.
Contributors to the ACTS project are listed in [AUTHORS](AUTHORS).
The ACTS project is based on the ATLAS tracking software. A list of contributors
to the ATLAS tracking repository can be found <a href="http://acts.web.cern.ch/ACTS/ATLAS_authors.html">here</a>.