acts/CI/pypi_readme.md

0001 [![ACTS logo](https://raw.githubusercontent.com/acts-project/acts/main/docs/figures/acts_logo_colored.svg)](https://github.com/acts-project/acts)
0002 # ACTS Common Tracking Software
0003
0004 or *A Common Tracking Software* if you do not like recursive acronyms
0005
0006 [![10.5281/zenodo.5141418](https://zenodo.org/badge/DOI/10.5281/zenodo.5141418.svg)](https://doi.org/10.5281/zenodo.5141418)
0007 [![Chat on Mattermost](https://badgen.net/badge/chat/on%20mattermost/cyan)](https://mattermost.web.cern.ch/acts/)
0008 [![Latest release](https://badgen.net/github/release/acts-project/acts)](https://github.com/acts-project/acts/releases)
0009
0010 ACTS is an experiment-independent toolkit for (charged) particle track
0011 reconstruction in (high energy) physics experiments implemented in modern C++.
0012
0013 More information can be found in the [ACTS documentation](https://acts-project.github.io/).
0014
0015 ## Installation
0016
0017 The easiest way to get the ACTS Python bindings is via [PyPI](https://pypi.org/project/pyacts/):
0018
0019 ```console
0020 pip install pyacts
0021 ```
0022
0023 The `pyacts` distribution includes bindings for the core library, Fatras, and
0024 the Examples framework.
0025
0026 > **Warning**
0027 > The PyPI package does not include all optional plugins (e.g. DD4hep/ODD, Geant4, ROOT).
0028 > To use those, build from source with the relevant CMake options enabled.
0029
0030 > **Note**
0031 > Even though the name of the PyPI package is `pyacts`, the python module must be imported
0032 > as `import acts`.
0033
0034
0035 The wheel includes `.pyi` type stubs and supports Linux and macOS with Python 3.11 or newer.
0036
0037 For a **source build**, enable the Python bindings and Examples framework, then load the generated
0038 `<build>/this_acts_withdeps.sh` script before importing `acts`:
0039
0040 ```console
0041 cmake -B <build> -S <source> -DACTS_BUILD_PYTHON_BINDINGS=ON -DACTS_BUILD_EXAMPLES=ON
0042 cmake --build <build> --target ActsPythonBindings
0043 source <build>/this_acts_withdeps.sh
0044 ```
0045
0046 Enable optional components with their CMake options. For ROOT readers, writers, and evaluation,
0047 use `-DACTS_BUILD_EXAMPLES_ROOT=ON`; this also enables the ROOT plugin. A source build needs Python
0048 development headers. The `ActsPythonBindings` target builds the enabled bindings, and the setup
0049 script adds the built modules and dependencies to your environment.
0050
0051 | Capability | PyPI (`pyacts`) | Full installation (source build) |
0052 | :--- | :--- | :--- |
0053 | Plugins | Arrow, JSON | All available plugins, including ROOT, DD4hep, or Geant4 |
0054 | I/O | CSV, Parquet, particle and sim-hit ROOT `uproot` readers | Additionally native ROOT and EDM4hep |
0055 | Geometry | `GenericDetector`, Tracking geometry from JSON | Directly build detector geometries with DD4hep or TGeo |
0056 | Evaluation | In-memory performance writers and plotting in Python | Additionally native ROOT performance writers |
0057
0058 ## Getting started
0059
0060 An `acts.examples.Sequencer` runs readers, algorithms, and writers over events. This first script
0061 generates muons and prints them; it works with the PyPI wheel:
0062
0063 ```python
0064 import acts
0065 from acts import UnitConstants as u
0066 import acts.examples
0067 from acts.examples.simulation import (
0068     EtaConfig,
0069     MomentumConfig,
0070     ParticleConfig,
0071     addParticleGun,
0072 )
0073
0074 s = acts.examples.Sequencer(events=5, numThreads=1)
0075 addParticleGun(
0076     s,
0077     momentumConfig=MomentumConfig(1 * u.GeV, 10 * u.GeV, transverse=True),
0078     etaConfig=EtaConfig(-2.0, 2.0),
0079     particleConfig=ParticleConfig(1, acts.PdgParticle.eMuon),
0080     rnd=acts.examples.RandomNumbers(seed=42),
0081     printParticles=True,
0082 )
0083 s.run()
0084 ```
0085
0086 For convenience, the package contains helpers in `acts.examples.simulation` and `acts.examples.reconstruction` that add entire workflow steps with `addXYZ`-functions (such as simulation, seeding, ...)
0087 and connect their data keys. For full flexibility, the underlying sequencer algorithms can be directly configured as well. For simple but complete chains, see the
0088 [PyPI finding and fitting demo](https://github.com/acts-project/acts/blob/main/Examples/Scripts/Python/pypi_finding_fitting_demo.py)
0089 or the [truth-tracking Kalman example](https://github.com/acts-project/acts/blob/main/Examples/Scripts/Python/truth_tracking_kalman.py)
0090 (source build). Their helper signatures and default keys are in
0091 [simulation.py](https://github.com/acts-project/acts/blob/main/Python/Examples/python/simulation.py)
0092 and [reconstruction.py](https://github.com/acts-project/acts/blob/main/Python/Examples/python/reconstruction.py).