3.4. Framework Registration¶

3.4.1. Algorithms with Multiple Input Data Products¶

The registration example given above in Section 3.4 creates an output family by applying a one-parameter algorithm find_hits to each element of the input family, as specified by family("Waveforms"_in("APA")). In many cases, however, the algorithm will require more than one data product. Consider another algorithm find_hits_subtract_pedestals, which forms hits by first subtracting pedestal values from the waveforms, both of which are presented to the algorithm as data products from the APA. The interface of the algorithm and its registration would look like:

class hits { ... };
class waveforms { ... };
class pedestals { ... };
hits find_hits_subtract_pedestals(waveforms const&, pedestals const&) {...}

PHLEX_REGISTER_ALGORITHMS(config)
{
  products("GoodHits") =
    transform("find_hits", find_hits_subtract_pedestals, concurrency::unlimited)
    .family("Waveforms"_in("APA"), "Pedestals"_in("APA"));
}

The elements of the input family are thus pairs of the data products labeled "Waveforms" and "Pedestals" in each APA. [2] In this case, the data cell for both data products is the same—i.e. for a given invocation of find_hits_subtract_pedestals, both data products will be associated with the same APA.

There are cases, however, where an algorithm needs to operate on data products from different data cells [DUNE 89].

vertices make_vertices(tracks const&, geometry const&) { ... }

PHLEX_REGISTER_ALGORITHMS(config)
{
  products("Vertices") =
    transform("vertex_maker", make_vertices, concurrency::unlimited)
    .family("GoodHits"_in("APA"), "Geometry"_in("Job"));
}

3.4.2. Accessing Configuration Information¶

Instead of hard-coding all pieces of registration information, it is desirable to specify a subset of such information through a program’s run-time configuration. To do this, an additional argument (e.g. config) is passed to the registration opener:

PHLEX_REGISTER_ALGORITHMS(config)
{
  auto selected_data_layer = config.get<std::string>("data_layer");

  products("GoodHits") =
    transform("hit_finder", find_hits, concurrency::unlimited)
    .family("Waveforms"_in(selected_data_layer));
}

Except for the specification of find_hits as the algorithm to be invoked, and transform as the HOF, all other pieces of information may be provided through the configuration.

3.4.3. Framework Dependence in Registration Code¶

Usually, classes like waveforms and hits and algorithms like find_hits are framework-independent (see Section 1.4). There may be scenarios, however, where dependence on framework interface is required, especially if framework-specific metadata types are used by the algorithm. In such cases, it is strongly encouraged to keep framework dependence within the module itself and, more specifically, within the registration stanza. This can be often achieved by registering closure objects that are generated by lambda expressions.

For example, suppose a physicist would like to create an algorithm find_hits_debug that reports a spill number when making tracks. By specifying a lambda expression that takes a phlex::handle<waveforms> object, the data product can be passed to the find_hits_debug function, along with the spill number from the metadata accessed from the handle:

hits find_hits_debug(waveforms const& ws, std::size_t apa_number) { ... }

PHLEX_REGISTER_ALGORITHMS(m)
{
  products("GoodHits") =
    transform(
      "hit_finder",
      [](phlex::handle<waveforms> ws) { return find_hits_debug(*ws, ws.id().number()); },
      concurrency::unlimited
    )
    .family("Waveforms"_in("APA"));
}

The lambda expression does depend on framework interface; the find_hits_debug function, however, retains its framework independence.

3.4.4. Member Functions of Classes¶

In some cases, it may be necessary to register a class and its member functions with the framework. This is done by first creating an instance of the class by invoking make<T>(args...), where T is the user-defined type, and args... are the arguments presented to T’s constructor. For example, the find_hits algorithm author could have instead created a hit_finder class, whose constructor takes a parameter called sigma_threshold:

class hit_finder {
public:
  hit_finder(float sigma_threshold);
  hits find(waveforms const& ws) const;
  ...
};

PHLEX_REGISTER_ALGORITHMS(config)
{
  auto sigma_threshold = config.get<float>("sigma_threshold");
  auto selected_data_layer = config.get<std::string>("data_layer");

  products("GoodHits") =
    make<hit_finder>(sigma_threshold)  // <= Make framework-owned instance of hit_finder
      .transform("hit_finder", &hit_finder::find, concurrency::unlimited)
      .family("Waveforms"_in(selected_data_scope));
}

Note that the hit_finder instance created in the code above is owned by the framework. The hit_finder::find member function’s address is registered in the transform(...) clause, thus instructing the framework to invoke find, bound to the framework-owned hit_finder instance.

3.4.5. Overloaded Functions¶

Phlex performs a substantial amount of type deduction through the transform(...) clause. This works well except in cases where the registered algorithms are overloaded functions. For example, suppose one wants to register C++’s overloaded std::sqrt(...) function with the framework. Simply specifying transform(..., std::sqrt) will fail at compile time as the compiler will not be able to determine which overload is desired.

Instead, the code author can use the following [4]:

transform(..., [](double x){ return std::sqrt(x); }, ...);

where the desired overload is selected based on the double argument to the lambda expression.

Footnotes

References