Add a new algorithm

Purpose

The main part of ACTS code is located in the Core packages. To use this code in the ACTS examples framework, an algorithm is needed. Before doing so, the ideas explored in Examples are typically first developed as algorithms. In a second step, the essential parts of this code are then moved to the Core packages, which the algorithm then executes.

Code Organisation

Algorithms reside in Examples/Algorithms of the repository. The code is split into a header with the algorithm class declaration and a source file containing the implementation.

Assuming that you want to experiment with a new seeding algorithm the files to add would be: Examples/Algorithms/TrackFinding/include/ActsExamples/TrackFinding/MySeedingAlgorithm.h and Examples/Algorithms/TrackFinding/src/MySeedingAlgorithm.cpp

The CMakeLists.txt file needs to be updated as well.

Algorithm Class

The algorithm class has to inherit from ActsExamples::IAlgorithm and thus implement this single method:

    ProcessCode execute(const AlgorithmContext& ctx) const final override;

Hint

There are other types of algorithms for reading inputs from files or for saving data to files. All these interfaces can be found in Examples/Framework/include/ActsExamples/Framework. In particular, there are base classes for algorithms for IO operations.

Important

The constructor should ideally follow certain rules. See section on configuration below.

The execute method will be called once for each event. Other methods can also be added to your class. It is good to remember that the algorithmic code in ACTS is typically stateless, and if the state needs to be passed between the calls it should be done explicitly. An algorithm is stateless if does not modify its own attributes while executing. This way it becomes reentrant and in consequence thread safe. For instance if the event processing is best organized with such methods:

    void prepareBuffers();
    void fillBuffers( const SpacePoint& );
    void extractInfo();

that need to pass the data between each other these methods should rather look like this:

    struct SeedingBuffers{ ... some buffers ... };
    void prepareBuffers(SeedingBuffers& buffers);
    void fillBuffers(SeedingBuffers& buffers, const SpacePoint& );
    void extractInfo(const SeedingBuffers& buffers);

Tip

It is common practice to put the algorithm code in the ActsExamples namespace.

Input and Output

The algorithm would be typically part of some processing sequence and thus consume and produce some event data. In the hypothetical example discussed here, space-points are the input and track seeds an output. The data can be retrieved in the algorithm using the get method of the “store” object of such signature:

    template<typename T>
    const T& get(const std::string& name);
    // example
    ctx.eventStore.get<MyType>("A_name");

The data is fetched from the “store” that is populated by a preceding algorithm or by the reader.

The data object (or objects) produced by an algorithm can be placed in the store using “store” add method:

    template<typename T>
    void add(const std::string& name, T&& object);
    // example
    ctx.eventStore.add("A_name", std::move(mydata));

The ownership of the object is transferred to the store. That is, the destruction of this object at the end of event processing is taken care of.

Configurability

It is customary that an algorithm requires configuration parameters. For example, in a seeding algorithm these parameters could include which detector layers should be used. The configuration can be provided to an algorithm through an additional class/structure. For algorithm it is typically an inner class named Config.

That is how the configuration object could look like for MySeedingAlgorithm:

class MySeedingAlgoritm : ...
    public:
    struct Config {
        std::vector<int> layers; // layers to use by the seeder
        float deltaZ;  // the maximum allowed deviation in r-z plane
    };
    ...

Tip

It is customary to put the config structures in the Acts namespace.

The algorithm constructor would take a MySeedingAlgorithm::Config object during the construction in addition to an argument controlling verbosity of diagnostic messages.

    MySeedingAlgorithm::MySeedingAlgorithm( Config cfg, Acts::Logging::Level lvl):
      ActsExamples::BareAlgortihm("MySeedingAlgorithm", lvl),
      m_cfg(std::move(cfg)){...}

Python bindings

In order to use an algorithm in standalone ACTS the algorithm and the associated config structure need to be accessible from python. For that, python bindings need to be created using the pybind11 library. The binding is defined in C++ code in Examples/Python/src/ directory. There is one source file per category, in this particular case the file to edit would be TrackFinding.cpp.

The algorithm class and associated config class can be made known to python via such binding definition:

    ACTS_PYTHON_DECLARE_ALGORITHM(
      ActsExamples::MySeedingAlgorithm,
      "MySeedingAlgorithm",
      layers, deltaZ);

The bindings can be tested in a standalone python session:


    from acts .examples import *
    help(MySeedingAlgorithm)
    help(MySeedingConfig)

An info about the class and config structure should be printed.

Example empty algorithm

A complete example of an algorithm called UserAlgorithm can be found in these two branches/locations:

Algorithm definition

Python bindings definition