Warning, /acts/docs/groups/python/custom_algorithms.md is written in an unsupported language. File is not indexed.
0001 @defgroup python_custom_algorithms Custom Algorithms
0002 @ingroup python_bindings
0003 @brief Writing your own `IAlgorithm` or `IReader` in Python, and moving data through the whiteboard.
0004
0005 Most readers, algorithms, and writers that come with ACTS are writtend in C++. However, it is also possible to add Python subclasses of `acts.examples.IAlgorithm` and `acts.examples.IReader` directly to the `Sequencer`. This allows to implement custom functionality without touching C++.
0006
0007 # A minimal algorithm
0008
0009 @snippet{trimleft} examples/test_custom_algorithm.py Custom algorithm filtering particles by pT
0010
0011 Points to note:
0012
0013 - The constructor must call the base class constructor (`acts.examples.IAlgorithm.__init__(self,
0014 name, level)`) before doing anything else.
0015 - `execute(self, context)` is the only method you must override; it returns an
0016 `acts.examples.ProcessCode` (`SUCCESS`, `SKIP`, `ABORT`, or `END`).
0017 - `self.logger` is available once the base constructor has run.
0018
0019 # Reading and writing the whiteboard
0020
0021 Data is passed between steps via an in-memory `WhiteBoard`, keyed by string. The example above
0022 initializes typed `ReadDataHandle` and `WriteDataHandle` objects with those keys. Inside
0023 `execute`, read with `handle(context.eventStore)` and write with `handle(context, value)`.
0024 `context.eventStore` also gives you `.exists(key)` and `.keys` directly, if you need to probe the
0025 whiteboard rather than go through a typed handle.
0026
0027 # A custom reader
0028
0029 `IReader` follows the same pattern, but implements `availableEvents()` (returning
0030 `(firstEvent, lastEventExclusive)`) instead of taking whiteboard input. `acts.examples.uproot`
0031 ships two ready-to-use examples that read ROOT files without the ROOT plugin — read them for a
0032 complete, working `IReader` implementation, including buffered reads across events.
0033
0034 The [PyPI finding and fitting demo](https://github.com/acts-project/acts/blob/main/Examples/Scripts/Python/pypi_finding_fitting_demo.py)
0035 shows dummy Python track-finding and fitting algorithms in a complete chain.
0036
0037 # Python algorithms and the GIL
0038
0039 Regular CPython uses a Global Interpreter Lock (GIL) that ensures only on thread is executing python code at the same time. `Sequencer.run()` releases the GIL while C++ algorithms execute.
0040
0041 Calls back into Python such as `IAlgorithm.execute` acquire it again. This is not a problem usually, but means, that a custom Python algorithm will run single-threaded and can become a bottleneck, regardless of the `numThreads` configuration of the `Sequencer`.
0042
0043 > [!warning]
0044 > If you define callbacks into C++ in plain python, and C++ code can mutate their states, this can lead to correctness issues.
