manalyzer

manalyzer is the midas analysis framework, in $MIDASSYS/manalyzer. It replaces ROOTANA and the old mana analyzer.

• The same code works online and offline. An analyzer reads midas files given on its command line, or connects to the experiment and reads events from an event buffer if no files are given. It can also be built without midas, to analyse files on a computer without a midas installation
• The analysis is split into modules. Each module does one task, e.g. unpacking the data of one detector or filling one set of histograms. Modules pass results to each other in flow events, which can hold any C++ objects
• Objects are created and destroyed for each run. Each module creates a run object at the start of a run, and destroys it at the end. This avoids many sources of errors related to handling new runs.
• ROOT is optional. With ROOT, histograms are saved in a ROOT file for each run, and can be watched live in a web browser with JSROOT
• Modules can run in parallel, each in its own thread (--mt)

Writing an analyzer

Start from one of the examples in $MIDASSYS/manalyzer, e.g. manalyzer_example_cxx.cxx (pure C++) or manalyzer_example_root.cxx (with ROOT histograms). The built examples are listed in Programs. A module is a class derived from TARunObject, which overrides the methods it needs:

#include "manalyzer.h"
#include "midasio.h"

class MyModule: public TARunObject
{
public:
   MyModule(TARunInfo* runinfo) : TARunObject(runinfo)
   {
      fModuleName = "MyModule";
   }

   void BeginRun(TARunInfo* runinfo)
   {
      // create histograms, load calibrations, ...
   }

   TAFlowEvent* Analyze(TARunInfo* runinfo, TMEvent* event, TAFlags* flags, TAFlowEvent* flow)
   {
      TMBank* bank = event->FindBank("ADC0");
      if (bank) {
         const uint16_t* adc = (const uint16_t*) event->GetBankData(bank);
         // ... use the bank->data_size / 2 values
      }
      return flow;
   }

   void EndRun(TARunInfo* runinfo)
   {
      // fit histograms, print results, ...
   }
};

static TARegister tar(new TAFactoryTemplate<MyModule>);

The methods of a module

Override the TARunObject methods that your module needs. They all do nothing by default.

Registering modules

There is no main() function to write, and no function to call to add a module to the analyzer. The last line of the example above does it.

static TARegister tar(new TAFactoryTemplate<MyModule>);

It creates a static TARegister object, which is constructed when the program starts, before main() runs. Its constructor adds the module's factory to manalyzer's list of modules. The main() function in manalyzer_main then uses the factories to create the modules at the start of each run.

So any module whose source file is built into the program is used, and a module is added by adding its source file to the build. If you put modules in a static library, the linker may leave out a file that nothing else refers to, and that module is then silently missing.

The order in which modules run

Each event is passed to the modules one after the other, so a module can use the flow event objects added by the modules before it. Set the order in the module's constructor with fModuleOrder: modules with a smaller number run first.

MyModule(TARunInfo* runinfo) : TARunObject(runinfo)
{
   fModuleName = "MyModule";
   fModuleOrder = 10;   // run after the modules with a smaller fModuleOrder
}

The default is 0. Modules with the same number run in the order they were registered, which depends on the compiler and linker, so always set fModuleOrder if the order matters. Use numbers between 0 and 9998: manalyzer's built-in event dump module uses -1, and its interactive module 9999. Run the analyzer with -t to print the modules in the order they run.

Module lifespan

The module objects (TARunObject) are created at the start of each run and destroyed at the end. Keep all the data for a run in them, rather than in global variables. This avoids the crashes at the end of a run, or when moving from one run to the next, that were common with older analyzers. These happened when code kept using ROOT objects that had been deleted when their ROOT file was closed.

The same applies to the objects that manalyzer passes to your methods (TARunInfo, TARootHelper and the flow events). manalyzer owns them, so don't keep pointers to them.

Data that lasts longer than one run

The factory, unlike the module, lasts for the whole time the analyzer runs. TAFactoryTemplate<MyModule> (see Registering modules) is the simplest factory.

For things that last longer than one run, write your own factory, derived from TAFactory, and keep them in it. Its methods are:

• NewRunObject(), which you must write. It's called at the start of each run, and creates the module's run object. Pass the module a pointer to the data that the factory keeps
• Init() (optional), which is called once when the analyzer starts, with the module's command-line arguments
• Finish() (optional), which is called once when the analyzer stops, e.g. to print a summary of all the runs
• Usage() (optional), which prints the module's command-line arguments in the analyzer's -h output

There's an example in Command-line arguments for your modules, and another in manalyzer_example_cxx.cxx.

Command-line arguments for your modules

manalyzer passes the arguments after -- on its command line to the modules, without looking at them:

./myana.exe run00123.mid.lz4 -- --verbose --threshold=50

Every module gets all of these arguments, so each module should ignore the ones it doesn't know. There are two ways to read them:

MyModule(TARunInfo* runinfo) : TARunObject(runinfo)
{
   fModuleName = "MyModule";
   for (const std::string& arg : runinfo->fArgs) {
      if (arg == "--verbose")
         fVerbose = true;
   }
}

// Settings from the command line
struct MyFlags
{
   bool fVerbose = false;
   double fThreshold = 100;
};

class MyModule: public TARunObject
{
public:
   MyFlags* fFlags = nullptr;

   MyModule(TARunInfo* runinfo, MyFlags* flags) : TARunObject(runinfo), fFlags(flags)
   {
      fModuleName = "MyModule";
   }

   // ... use fFlags->fVerbose and fFlags->fThreshold
};

class MyModuleFactory: public TAFactory
{
public:
   MyFlags fFlags;

   void Usage()
   {
      printf("\tMyModule:\n");
      printf("\t--verbose: print each event\n");
      printf("\t--threshold=N: ignore ADC values below N (default 100)\n");
   }

   void Init(const std::vector<std::string>& args)
   {
      for (const std::string& arg : args) {
         if (arg == "--verbose")
            fFlags.fVerbose = true;
         else if (arg.rfind("--threshold=", 0) == 0)
            fFlags.fThreshold = std::stod(arg.substr(12));
      }
   }

   TARunObject* NewRunObject(TARunInfo* runinfo)
   {
      return new MyModule(runinfo, &fFlags);
   }
};

static TARegister tar(new MyModuleFactory);

Passing results between modules

Modules pass C++ objects to each other in "flow events". For example, an ADC module may unpack and calibrate the ADC data into an array of pulse heights, which a later module combines with the TDC hits from another module. This is easier than putting the results into midas banks.

Derive the objects to pass from TAFlowEvent. A flow event is a linked list of these objects: each new object is added to the front of the list given to its constructor. Return the new front of the list from Analyze() or AnalyzeFlowEvent():

class AdcHits : public TAFlowEvent
{
public:
   std::vector<double> fPulseHeights;

   AdcHits(TAFlowEvent* flow) : TAFlowEvent(flow) {}
};

// In the ADC module
TAFlowEvent* Analyze(TARunInfo* runinfo, TMEvent* event, TAFlags* flags, TAFlowEvent* flow)
{
   AdcHits* hits = new AdcHits(flow);
   // ... fill hits->fPulseHeights from the ADC bank
   return hits;
}

// In a later module
TAFlowEvent* AnalyzeFlowEvent(TARunInfo* runinfo, TAFlags* flags, TAFlowEvent* flow)
{
   AdcHits* hits = flow->Find<AdcHits>();
   if (hits) {
      // ... use hits->fPulseHeights
   }
   return flow;
}

Find<T>() returns the first object of type T in the list, or NULL. To go through all the objects, follow fNext. manalyzer deletes the flow event and all its objects after the last module has seen it.

manalyzer_example_flow.cxx has more examples.

Analyze() and AnalyzeFlowEvent()

manalyzer passes each midas event through the modules twice:

1. Analyze() of every module, in order. Each one gets the midas event, and the flow event returned by the module before it (NULL for the first module).
2. AnalyzeFlowEvent() of every module, in order, with the flow event from the end of the first pass. This pass only happens if a module returned a flow event, and no module set TAFlag_SKIP or TAFlag_QUIT.

So a common pattern is to unpack the banks in one module's Analyze(), and to do the rest of the analysis in the modules' AnalyzeFlowEvent(). This splits the analysis into steps that run in parallel with --mt, and the same code also works for physics events from the flow event queue, which have no midas event.

Several physics events in one midas event

If a midas event contains several physics events, unpack each one into its own flow event, and add it to the flow event queue with runinfo->AddToFlowQueue():

TAFlowEvent* Analyze(TARunInfo* runinfo, TMEvent* event, TAFlags* flags, TAFlowEvent* flow)
{
   while (PhysicsEvent* e = unpack_next_physics_event(event)) {
      runinfo->AddToFlowQueue(e);
   }
   return flow;
}

After all the modules have analysed the midas event, manalyzer passes each queued flow event through the modules, as if it were a new event. Only AnalyzeFlowEvent() is called for them, because there's no midas event. The flags work the same way, and modules can add objects to the flow event. Each flow event is deleted after the last module, and then manalyzer goes on to the next midas event. manalyzer_example_flow_queue.cxx has an example.

Processing left-over data at the end of a run

Some data can only be processed at the end of a run, after the last midas event, e.g. incomplete data that an unpacker of a continuous data stream keeps between Analyze() calls, or pending events in an event builder. EndRun() is too late for this.

PreEndRun() is called after the last midas event, before EndRun(). Unpack the left-over data there into flow events, and queue them with runinfo->AddToFlowQueue(). They are then processed by the modules' AnalyzeFlowEvent(), as above.

Skipping events and stopping the analysis

Analyze() and AnalyzeFlowEvent() can set flags to change what manalyzer does with the event, e.g. *flags |= TAFlag_SKIP:

Run information (TARunInfo)

runinfo, which is passed to every method, has the information about the run being analysed. When the analyzer moves on to the next subrun file of a run, it's kept, and only the file name changes.

ROOT output (TARootHelper)

With ROOT, runinfo->fRoot has the ROOT output file and the other ROOT objects. It's created and deleted at the same time as runinfo.

By default, ROOT objects created by the modules (e.g. with new TH1D(...)) are created in the ROOT output file of the run, root_output_files/outputNNNNN.root. They're saved when the file is closed at the end of the run, and then deleted. In JSROOT, they're shown under Files › outputNNNNN.root.

To be sure that a histogram goes into the output file, call runinfo->fRoot->fOutputFile->cd() before creating it. For objects that shouldn't be saved (e.g. event or waveform displays), call runinfo->fRoot->fgDir->cd() first. They're then kept in memory, and shown in JSROOT under manalyzer.

Multithreading

With --mt, each module runs in its own thread, and flow events are passed from one module's thread to the next through queues. This can be much faster when several modules do a lot of work.

Rules for code that runs in multithreaded mode:

• Analyze() and AnalyzeSpecialEvent() are always called in the main thread. AnalyzeFlowEvent() is called in the module's own thread
• The flow event and the flags belong to the thread that's processing them, so they don't need locking
• A module's own data members don't need locking, because each module is only used by its own thread
• runinfo is shared by all the threads. Lock TAMultithreadHelper::gfLock to use anything in it that isn't thread-safe (e.g. fRoot)

• Lock TAMultithreadHelper::gfLock around code that isn't thread-safe, such as many ROOT fitting functions:

  {
     std::lock_guard<std::mutex> lock(TAMultithreadHelper::gfLock);
     histogram->Fit("gaus");
  } // unlocked here
  

• Put objects into flow events as pointers created with new, not as local variables, and delete them in the flow event's destructor, not in a module. Once an object is in a flow event, the module that created it no longer owns it

manalyzer turns on ROOT's thread safety (ROOT::EnableThreadSafety() and ROOT::EnableImplicitMT()). See Multi-threading in ROOT for which ROOT classes are thread-safe. To find race conditions, use Helgrind. It also reports printing with std::cout from several threads, which only mixes up the output.

Compiling an analyzer

To build the analyzer, put the module in my_module.cxx, with this CMakeLists.txt next to it. The manalyzer component of midas provides the manalyzer_main library, which contains the main() function and the rest of manalyzer:

cmake_minimum_required(VERSION 3.14)
project(myana)

find_package(Midas REQUIRED COMPONENTS manalyzer PATHS $ENV{MIDASSYS})

add_executable(myana.exe my_module.cxx)
target_link_libraries(myana.exe manalyzer_main)

Then build it, with MIDASSYS set to your midas installation:

mkdir build
cd build
cmake ..
make

add_executable(myana.exe my_module.cxx adc_module.cxx tdc_module.cxx)

Running an analyzer

./myana.exe run00123.mid.lz4        # analyse one file (offline)
./myana.exe run00123*.mid.lz4       # analyse all the subrun files of a run
./myana.exe -R8082                  # connect to the experiment (online), with a JSROOT web server on port 8082
./myana.exe --demo -e100            # analyse 100 events made up by manalyzer, without data or midas
./myana.exe run00123.mid.lz4 -- -v  # pass "-v" to the modules

Viewing analysis results

If manalyzer was built with ROOT, each run's histograms are saved as ROOT files. The default location is root_output_files/outputNNNNN.root, but this can be changed with -D and -O. You can open the file with ROOT, or view it in a web browser with mjsroot (mjsroot.exe -R8083 outputNNNNN.root).

These arguments give you other ways to see the results:

Without ROOT, the analyzer only shows what your modules print or write to files. An online analyzer can also make its results available to custom web pages, which plot them with mplot.