Modules

Module Names

This page describes the skeleton of a minimal module that does some work on every event but nothing else. The class name of the module is MyClass; the focus is on some rules defined by art and some conventions adopted by the Mu2e build system. These rules are case sensitive and are listed below:

1. Your class must inherit from one of the module base classes, EDAnalyzer, EDProducer or EDFilter; these base classes are defined by art. There are other base classes available when using art in multi-threaded mode but those details are beyond the scope of this page. (FIXME: Link to MT section when we make it)
2. This class must be found in a file with a name that matches the class name, MyClass_module.cc; typically this file will be found in a directory named like: MyDirectory/src/MyClass_module.cc, relative to the top of Mu2e Offline.
3. The Mu2e build system will compile this file into an object file named MyDirectory/src/MyClass_module.os
4. The Mu2e build system will link this object file into a dynamic library named lib/libmu2e_MyDirectory_MyClass_module.so; dynamic libraries are also called shared libraries.
5. This .so file is a plugin that art can load and run. You tell art to load and run the file using the fcl language; some basic elements of fcl are described below.
6. The module source file must have the structure:
namespace mu2e { class MyClass : public art::EDAnalyzer { public: explicit MyClass(fhicl::ParameterSet const& pset); void analyze( art::Event const& event ) override; }; MyClass::MyClass(fhicl::ParameterSet const& pset)  : art::EDAnalyzer(pset){ // Body of the constructor. } void MyClass::analyze(art::Event const& event){ // Body of the analyze member function: this is where you do per event work. // You can inspect information already in the event by using the art::Event argument. } } // end namespace mu2e DEFINE_ART_MODULE(mu2e::MyClass); This example is for an analyzer module. To create a producer or a filter module, you must inherit from either art::EDProducer or art::EDFilter. The last line invokes a macro that inserts additional code into the .so file ( for the experts: it inserts a factory method to produce an instance of the class and inserts code that runs at .so load time to register the factory method with art's module registry ). This example uses the variant in which the argument of the constructor is a ParameterSet object; there is a newer variant in which the argument is a smarter type of ParameterSet that knows how to check it's input for validity. (FIXME: Update the example with the validated pset technology)
7. To declare this module to the framework you need to have a fragment like the following in your .fcl file:
physics : { analyzers: { set1 : { module_type  : MyClass } # Any other analyzer modules listed here ... } } The identifiers physics, analyzers and module_type are defined by art. The name MyClass tells art to look in CET_PLUGIN_PATH and find a file that matches the name lib*MyClass_module.so; that's how it finds your module. The string set1 is called a module label; if you are the author of a module then you can choose almost any name you want for a module label. If you are using a standard Mu2e module, you normally must use one of the module labels that Mu2e has defined for you. There is more information about module labels below.
8. The previous item was for the case that your module is an analyzer. If it is a producer or filter, then the text in green needs to be either producers or filters.
9. When a module puts a data product into an event, the art data provenance system records the module label of the module that created the data product.

Module Labels

Most modules have run-time configurable parameters. So the full description of "what a module does" needs two things, it's source code and it's run-time configuration. The purpose of a module label is to uniquely identify a unit of work, a module plus it's runtime configuration. The example below illustrates this.

Consider the following fragment from a .fcl file,

physics: {
  producers: {
    set1: { module_type   : MyClass }
  }
}

1. The string set1 is refered to as the module module label; you will sometimes hear this called "a module instance name".
2. The above fragment may be expanded to include additional parameters, for example,
physics : { analyzers: { set1 : { module_type  : MyClass cutSet : 1 } set2 : { module_type  : MyClass cutSet : 2 } } } This example presumes the module MyClass has code in it's constructor that reads the parameter cutSet and changes the behaviour of the module depending on the value of the parameter. If you look back at the code fragment for MyClass you will see that the constructor has an argument of type fhicl::ParameterSet - the module uses the parameter set object to look up the value of cutSet. You can find the details of how to do this an another tutorial (FIXME: add a link).
3. In this example art will make two instances of the class MyClass, one class will see a cutSet parameter of 1 and the other cutSet parameter of 2. For every event that it processes art will call the analyze member function of both instances.
4. In this sense the unique identifiers of units of work are set1 and set2, the two module labels.
5. Within a single art job, all module labels must be unique.