Warning, /acts/docs/groups/python/index.md is written in an unsupported language. File is not indexed.
0001 @defgroup python_bindings Python Bindings
0002 @brief Use ACTS from Python, with the PyPI wheel or a source build.
0003
0004 The Python bindings primarily expose the ACTS Examples framework: configure readers, algorithms, and writers in a `Sequencer` to run tracking
0005 workflows. Selected Core types are bound where the Examples workflows need them. The bindings do
0006 not aim to expose every Core tool directly to Python; use Core functionality through the
0007 Examples algorithms.
0008
0009 # Installation
0010
0011 The easiest way to get the ACTS Python bindings is via [PyPI](https://pypi.org/project/pyacts/):
0012
0013 ```console
0014 pip install pyacts
0015 ```
0016
0017 The `pyacts` distribution includes bindings for the core library, Fatras, and
0018 the Examples framework.
0019
0020 > [!warning]
0021 > The PyPI package does not include all optional plugins (e.g. DD4hep/ODD, Geant4, ROOT).
0022 > To use those, build from source with the relevant CMake options enabled.
0023
0024 > [!note]
0025 > Even though the name of the PyPI package is `pyacts`, the python module must be imported
0026 > as `import acts`.
0027
0028
0029 The wheel includes `.pyi` type stubs and supports Linux and macOS with Python 3.11 or newer.
0030
0031 For a **source build**, enable the Python bindings and Examples framework, then load the generated
0032 `<build>/this_acts_withdeps.sh` script before importing `acts`:
0033
0034 ```console
0035 cmake -B <build> -S <source> -DACTS_BUILD_PYTHON_BINDINGS=ON -DACTS_BUILD_EXAMPLES=ON
0036 cmake --build <build> --target ActsPythonBindings
0037 source <build>/this_acts_withdeps.sh
0038 ```
0039
0040 Enable optional components with their CMake options. For ROOT readers, writers, and evaluation,
0041 use `-DACTS_BUILD_EXAMPLES_ROOT=ON`; this also enables the ROOT plugin. A source build needs Python
0042 development headers. The `ActsPythonBindings` target builds the enabled bindings, and the setup
0043 script adds the built modules and dependencies to your environment.
0044
0045 | Capability | PyPI (`pyacts`) | Full installation (source build) |
0046 | :--- | :--- | :--- |
0047 | Plugins | Arrow, JSON | All available plugins, including ROOT, DD4hep, or Geant4 |
0048 | I/O | CSV, Parquet, particle and sim-hit ROOT `uproot` readers | Additionally native ROOT and EDM4hep |
0049 | Geometry | `GenericDetector`, Tracking geometry from JSON | Directly build detector geometries with DD4hep or TGeo |
0050 | Evaluation | In-memory performance writers and plotting in Python | Additionally native ROOT performance writers |
0051
0052 # Getting started
0053
0054 An `acts.examples.Sequencer` runs readers, algorithms, and writers over events. This first script
0055 generates muons and prints them; it works with the PyPI wheel:
0056
0057 @snippet{trimleft} examples/test_python_getting_started.py First Python run
0058
0059 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, ...)
0060 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
0061 [PyPI finding and fitting demo](https://github.com/acts-project/acts/blob/main/Examples/Scripts/Python/pypi_finding_fitting_demo.py)
0062 or the [truth-tracking Kalman example](https://github.com/acts-project/acts/blob/main/Examples/Scripts/Python/truth_tracking_kalman.py)
0063 (source build). Their helper signatures and default keys are in
0064 [simulation.py](https://github.com/acts-project/acts/blob/main/Python/Examples/python/simulation.py)
0065 and [reconstruction.py](https://github.com/acts-project/acts/blob/main/Python/Examples/python/reconstruction.py).
