source/acts/README.md

0001 # ACTS Common Tracking Software
0002
0003 or *A Common Tracking Software* if you do not like recursive acronyms
0004
0005 [![10.5281/zenodo.5141418](https://zenodo.org/badge/DOI/10.5281/zenodo.5141418.svg)](https://doi.org/10.5281/zenodo.5141418)
0006 [![Chat on Mattermost](https://badgen.net/badge/chat/on%20mattermost/cyan)](https://mattermost.web.cern.ch/acts/)
0007 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=acts-project_acts&metric=coverage)](https://sonarcloud.io/summary/new_code?id=acts-project_acts)
0008 [![Latest release](https://badgen.net/github/release/acts-project/acts)](https://github.com/acts-project/acts/releases)
0009 [![Status](https://badgen.net/github/checks/acts-project/acts/main)](https://github.com/acts-project/acts/actions)
0010 [![Metrics](https://badgen.net/badge/metric/tracker/purple)](https://acts-project.github.io/metrics/)
0011
0012 ACTS is an experiment-independent toolkit for (charged) particle track
0013 reconstruction in (high energy) physics experiments implemented in modern C++.
0014
0015 More information can be found in the [ACTS documentation](https://acts-project.github.io/).
0016
0017 ## Quick start
0018
0019 ACTS is developed in C++ and is build using [CMake](https://cmake.org). Building
0020 the core library requires a C++20 compatible compiler,
0021 [Boost](https://www.boost.org), and [Eigen](https://eigen.tuxfamily.org). The
0022 following commands will clone the repository, configure, and build the core
0023 library
0024
0025 ```sh
0026 git clone https://github.com/acts-project/acts <source>
0027 cmake -B <build> -S <source>
0028 cmake --build <build>
0029 ```
0030
0031 For more details, e.g. specific versions and additional dependencies, have a
0032 look at the ["Building ACTS"
0033 guide](https://acts-project.github.io/building_acts.html). If you find a bug,
0034 have a feature request, or want to contribute to ACTS, have a look at the
0035 [contribution guidelines](CONTRIBUTING.md).
0036
0037 ### Python bindings
0038
0039 ACTS is also available as a Python package via `pip install pyacts`. See the
0040 [Python bindings documentation](https://acts-project.github.io/group__python__bindings.html)
0041 for details.
0042
0043 ## Versioning and public API
0044
0045 Release versions follow [semantic versioning](https://semver.org/spec/v2.0.0.html)
0046 to indicate whether a new version contains breaking changes within the public API.
0047 Currently, only a limited part of the visible API is considered the public API
0048 and subject to the semantic versioning rules. The details are outlined in the
0049 [versioning and public API documentation](docs/pages/versioning.md).
0050
0051 ## Repository organization
0052
0053 The repository contains all code of the ACTS projects, not just the core
0054 library that a physics experiment is expected to use as part of its
0055 reconstruction code. All optional components are disabled by default. Please
0056 see the ["Building ACTS" guide](https://acts-project.github.io/building_acts.html)
0057 on how-to enable them.
0058
0059
0060 | *Folder*     | *include path*                              | *Namespace*       | *Python module*          |
0061 | :---         | :---                                        | :---              | :---                     |
0062 | `Core/`      | `#include "Acts/..."`                       | `Acts::`          | `acts`                   |
0063 | `Plugins/`   | `#include "ActsPlugins/PluginName/..."`     | `ActsPlugins::`   | `acts.pluginname`        |
0064 | `Fatras/`    | `#include "ActsFatras/..."`                 | `ActsFatras::`    | `acts.fatras`            |
0065 | `Alignment/` | `#include "ActsAlignment/..."`              | `ActsAlignment::` | `acts.alignment`         |
0066 | `Examples/`  | `#include "ActsExamples/..."`               | `ActsExamples::`  | `acts.examples`          |
0067 | `Python/`    | `#include "ActsPython/..."` (not much used) | `ActsPython::`    |  N/A                     |
0068 | `Tests/`     | `#include "ActsTests/..."` (not much used)  | `Acts::Tests::`   |  N/A                     |
0069
0070
0071 Short summary of the modules and directories:
0072 -   `Core/` contains all the core functionality with minimal dependencies and no framework or I/O related code
0073 -   `Plugins/` contains plugins for core functionality that require
0074     additional external packages.
0075 -   `Fatras/` provides fast track simulation tools based on the core
0076     library.
0077 -   `Examples/` contains simulation and reconstruction examples. These are
0078     internal tools for manual full-chain development and tests.
0079 -   `Tests/` contains automated unit tests, integration tests, and
0080     (micro-)benchmarks.
0081 -   `Python/` contains the python bindings for the different modules
0082 -   `thirdparty/` contains external dependencies that are usually not available
0083     through the system package manager.
0084
0085 ## Authors and license
0086
0087 Contributors to the ACTS project are listed in the [AUTHORS](AUTHORS) file.
0088
0089 The ACTS project is published under the terms of the Mozilla Public License, v. 2.0.
0090 A copy of the license can be found in the [LICENSE](LICENSE) file or at
0091 https://mozilla.org/MPL/2.0/ .
0092
0093 The ACTS project contains copies of the following external packages:
0094
0095 -   [OpenDataDetector](https://github.com/acts-project/OpenDataDetector)
0096     licensed under the MPLv2 license.
0097
0098 ACTS is a collaborative open source software project, and hence does not base its
0099 organisational structure on (intellectual) *ownership* of certain pieces of code
0100 by individuals. The usage of GitHub's `CODEOWNERS` system is currently under
0101 evaluation primarily to identify opt-in contact persons for certain parts of the
0102 code base in an attempt to simplify workflows and identify information contacts
0103 and reviewers. A detailed description of our test usage is part of the
0104 `CODEOWNERS` file.