Module Writing Tutorial

Tutorial Session Goal

This tutorial will show how to write an art module for Mu2e. It will explain how to structure the code, define runtime parameters, produce histograms and/or TTrees, and consume and produce data products.

Session Prerequisites and Advance Preparation

This tutorial requires the user to:

• Perform the Tutorial on setting up the Mu2e Offline
• Perform the tutorial on running Mu2e art Framework jobs
• Install the following docker containers ()

This tutorial also assumes that you are somewhat familiar with C++.

Session Introduction

Mu2e uses the art framework to organize our event processing code. The art framework processes events through a configurable sequential set of modules, called a path. Modules expects certain inputs, and optionally produces certain outputs. Modules have a standard interface for interacting with the art framework, giving the user access to data at run/subrun/event transitions. Modules have a standard library for defining configuration parameters that can be changed at runtime.

In this tutorial you will learn how to create an art module from a basic template, and perform basic data operations in that module. You will learn how to configure your module in code and fcl, and how to produce various kinds of output.

Disclaimer! In this tutorial we will be copying old modules to create new modules. In general, this is not a great idea because we can end up copying errorful code. If you do this in the real world make sure you trust the code you're copying!

Basic Exercises

Exercise 1: Running a simple module (Hello, Tutorial!)

In this exercise, we will run a simple module that will print a welcoming message.

1. First create a Satelite release in the ModuleWriting tutorial
> cd $TUTORIAL_BASE/ModuleWriting > /cvmfs/mu2e.opensciencegrid.org/Offline/v7_4_0/SLF6/prof/Offline/bin/createSatelliteRelease --directory . > source setup.sh
2. This first module has already been written for you so we can compile straight away
> scons -j4
3. And run
mu2e -c fcl/HelloEx01.fcl This will write "Hello, world" and the full event id for the first 3 events.

Exercise 2: Adding module configuration (Hello, Fhicl Validation!)

In this exercise, we will add some module configuration parameters that can be set in fcl

1. Copy last exercise's .cc file and create a new file
> cp src/HelloTutorial_module.cc src/HelloFhiclValidation_module.cc
2. Open the new file in your favourite text editor and make the following changes
1. find and replace "HelloTutorial" with "HelloFhiclValidation"
2. in the Config struct, below the using commands add the following:
fhicl::Atom<int> number{Name("number"), Comment("This module will print this number")};
3. add a private member variable to the class:
int _number;
4. add to the constructor initialisation list:
_number(conf().number())
5. add a second std::cout command to print the number e.g.
std::cout << "My number is..." << _number << std::endl;
3. Recompile with scons -j4 and fix any compilation errors
4. Now create a copy of the fcl file, open it and make the following changes:
1. find and replace "HelloTutorial" with "HelloFhiclValidation"
2. add the new fhicl parameter to the module configuation and assign it a value
5. Run mu2e with the new fcl file
6. Try doing the following and note the errors you see:
1. run without the new parameter in the fcl file
2. run with a typo in the parameter name
3. run with the value of the parameter as a float and a string

This is why fhicl validation is nice. We can catch errors in the module configurations before we waste time running the module. Some modules use an old format for module configuration, which does not catch such errors. These will be slowly converted but all new modules should use fhicl validation.

7. We can add parameter with a default value by adding this value to end of the parameter declaration:
fhicl::Atom<int> defaultNumber{Name("number"), Comment("This module will print this number"), 100};
8. Add some code to write this parameter out, recompile and play with the fcl configuration again. Note that it is often best to have default values defined in fcl prolog(?)
9. We can also add an optional parameter:
fhicl::OptionalAtom<int> optionalNumber{Name("optionalNumber"), Comment("This module will print this number but it is optional")}; However, we can't initialise this in the initialiser list. Instead we have to check that the parameter exists: if (_conf.optionalNumber(_optionalNumber)) { std::cout << "My _optionalNumber is..." << _optionalNumber << std::endl; }
10. (Optional): add some more parameters (try floats, strings etc.)

Exercise 3: Reading in a mu2e data product (Hello, Mu2e Data Product!)

In this exercise, we will be reading the results of the track fit and printing their times to the screen.

1. Let's get a minimal working example set up:
1. Copy the first exercise's .cc file to create a new module
2. Add a fhicl parameter of type art::InputTag and a simple print statement that prints the parameter
3. Copy a previous fcl file and edit it so that runs your new module and uses the new parameter (at the moment, it doesn't matter what the value of this parameter is).
4. Compile, run and make sure everything works as you expect
2. Now we want to read in an art file. For the time being, we will do nothing with it.
1. in the source block of your fcl file, change EmptyEvent to RootInput
2. run your fcl file with this option added on the command line -S filelists/mcs.mu2e.CeEndpoint-mix-cat.MDC2018h.1-file.lst to make sure everything works
3. Now let's actually do something with a Mu2e data product. We will be looking at tracks (class KalSeed) from the downstream e-minus fit. Set the value of your fcl parameter to KFFDeM and then make the following changes in your module's analyze() function
1. #include the file RecoDataProducts/inc/KalSeed.hh
2. get a valid handle to the KalSeedCollection from the event:
const auto& kalSeedCollectionHandle = event.getValidHandle<KalSeedCollection>(_input);
3. get the KalSeedCollection itself
const auto& kalSeedCollection = *kalSeedCollectionHandle;
4. loop through and print the t0 of each KalSeed (you can look in $MU2E_BASE_RELEASE/RecoDataProducts/inc/KalSeed.hh to work out why we need two .t0())
for (const auto& i_kalSeed : kalSeedCollection) { std::cout << "t0 = " << i_kalSeed.t0().t0() << " ns" << std::endl; }
4. (Optional): try to print the times of a different KalSeedCollection (e.g. KFFDmuM)
5. (Optional): try to print some other values from the KalSeed (e.g. momentum (which can be found in KalSegment))
6. (Optional): try to read a different type of Mu2e data product (you can find the list of data products in an event with mu2e -c Print/fcl/dumpDataProducts.fcl -S filelist -n 1)

Exercise 4: Filling a histogram (Hello, Histogram!)

In this exercise, we will create a ROOT histogram of the times that we were printing out to the screen in Exercise 3. We will need to use art's TFileService to create and write ROOT objects to a ROOT file.

1. To start, you can either copy or edit the module from exercise 3:
2. Make the following changes to your module's source code:
   1. #include art/Framework/Services/Optional/TFileService.h and TH1F.h
   2. add a new private member variable of type TH1F*
   3. add a new function to your module: void beginJob(). This function will run at the beginning of your job.
   4. in the beginJob() function add:
   art::ServiceHandle<art::TFileService> tfs; double min_t0 = 0; double max_t0 = 1700; double t0_width = 10; int n_t0_bins = (max_t0 - min_t0) / t0_width; _hTrackTimes = tfs->make<TH1F>("hTrackTimes","Track t0", n_t0_bins,min_t0,max_t0);
   5. in the analyze() function of your module, fill the histogram with the track times:
   _hTrackTimes->Fill(i_kalSeed.t0().t0());
3. To run mu2e, use the following command:
mu2e -c yourEx04.fcl -S filelists/mcs.mu2e.CeEndpoint-mix-cat.MDC2018h.1-file.lst --TFileName out.root Note that, instead of defining the output ROOT filename on the command line. You can set the fcl parameter services.TFileService.fileName in your fcl file
4. Open the out.root file and explore it with a TBrowser to find your histogram!

Now that you can create a hsitogram, you can try some of these optional exercises

1. (Optional): make the histogram parameters (min, max, bin width) fcl parameters
2. (Optional): create a second instance of your module and read in a different KalSeedCollection (e.g. KFFDmuM)

Exercise 5: Creating a subset of a data product (Hello, Cool Data Products!)

• Create a subset of a data product and add it to the event

Exercise 6: Creating a new data product (Hello, My Data Product!)

• Create a new data product, fill it, and add it to the event

Exercise 7: Creating and using a pointer to a data product (Hello, Art Ptrs!)

• Create and use a persistent pointer (Ptr) to a data product

Exercise 8: Creating and using an assn between two data products (Hello, Art Assns!)

• Create an association between 2 data products

Reference Materials

• art workbook