Go to Notes and Further References, Exercises, top,

Running loon Jobs

Command syntax to run a loon job

      loon [options] [job macro] [list of root files]

Most frequently used options

      -b: Run in batch mode without graphics.
      -q: Exit after processing command line macro files.
      -t: Specify job time limit. Eg. -t'10 minutes'
      -r: Specify limit on number of records to process.
      -o: Set the name of the default output file.

Job macro
- A set of C++ commands to configure the job (see next slides)
- By default the commands executed by CINT : ROOT's interactive C++ compiler
  - Commands run slowly, but only configures job
  - Remainder of the job runs at full speed
- Alternatively, to get script compiled add ++ after job macro file name e.g.:-
```
      loon -bq -r 10 'compiled_job.C++' afile.mdaq.root
```
  (Note single quotes round job macro file name)

List of root files

None or more space separated root files e.g.

     loon my_job.C F00018143_0000.mdaq.root F00018143_0001.mdaq.root

Configuring the Overall Job Environment

Creating a JobC job controller
```
      JobC j;
```
Setting Message Levels (j.Msg)
- Controls the routing, verbosity and appearance.
- Each package has its own message stream, with level set to one of:-
```
	1 Verbose  2 Debug  3 Info  4 Warning  5 Error  6 Fatal 
```
- Example: set level to "Verbose" for the I/O module:
```
      j.Msg.SetLevel("Io","Verbose");  
```

Creating paths (j.Path)

A path is a sequence of JobCModules.

For each JobCModule a method call is specified, typically:-

      Get - input or create    Ana - analyse   Reco - reconstruct

Example create JobCPath called "Reco" with 3 JobCModules:-

    jc.Path.Create("Reco",
                   "NoiseFilterModule::Ana" 
                   "RecordSetupModule::Get"
                   "DigitListModule::Reco");

Running paths and reporting results
- Paths can be run until EOF or for n events e.g 100 events:-
```
     jc.Path("Reco").Run(100);
```
- Paths can report on their composition and performance:-
```
     jc.Path("Reco").Report(); 
```

Configuring Individual JobCModules

Configuring the Input Module (j.Input)
- A standard (implicitly loaded) module.
- Example: set format to input, as opposed to e.g. dds = dispatcher)
```
      j.Input.Set("Format=input");
```

Configuring a Path's Output Module

A normal (explicitly loaded) module

Example: output raw, config and candidate data streams:

      j.Path.Create("Demo","Output::Put");
      // Set output file, can also use "-o testout.root" on loon cmd. line
      j.Path.("Demo").Mod("Output").Set("FileName=testout.root")
      j.Path.("Demo").Mod("Output").Set("AccessMode=New");
      j.Path.("Demo").Mod("Output").Set("Streams=Cand,Config,DaqSnarl");

Configuring other Modules on a Path

Standard method is to use Set. E.g.:-

      j.Path("Reco").Mod("DigitListModule").Set("ListsToMake=1");
      j.Path("Reco").Mod("SliceSRListModule").Set("SliceListAlgConfig=FarCosmic");

Some modules support Cmd method. E.g.:-

      j.Path("Demo").Mod("EventDump").Cmd("Dump Fragments");

Interrogating Modules

Asking for their configuration

      j.Path("Demo").Mod("EventDump").Report();

Asking for help

      j.Path("Demo").Mod("EventDump").Help();

Modules run Algorithms to produce Candidates (results)

Algorithms are not owned by modules
- They are owned by the AlgFactory
- To get to the factory
```
     AlgFactory &af = AlgFactory::GetInstance();
```
Algorithms are accessed via handles
- They are located by algorithm name and configuration name
```
     AlgHandle ah = af.GetAlgHandle("AlgDeMuxDigitList", "default");
```

Algorithms have an associated AlgConfig that can be configured

   AlgConfig &acd = ah.GetAlgConfig();
   acd.UnLockValues();
   acd.Set("DeMuxAlgConfig", "default");
   acd.Set("NormalizeWeights", 1); // Normalize weights to 1 if non-zero
   acd.LockValues();

Notes and Further References

To run loon you need a job macro that specifies what is to be done. The macro

 $MINOS_TUTORIAL_MACROS/loon_reco_job.C

is a typical example. The next tutorial, Writing ROOT Macros will go into more detail on the overall construction of these macros and how the JobControl package is used to assemble the job, so here we will gloss over this area and concentrate on the information that you need to provide.

The macro is broadly divided into the following phases:-

Loading in the application packages
loon is a framework that provides the support services needed by the applications, but it does not contain them. Instead you load the ones you require. This make for an extensible system: new applications can be developed at any time and only those that are required are loaded.
Loading a package is performed by sending a message directly to ROOT e.g.:-
```
    gSystem->Load("libDeMux");
```
This tells ROOT to load the DeMux library.

Creating and assembling a job path

A Job Path is a sequence of JobCModules used as the basis of the main event loop. A path is assembled by sending messages to the JobControl package e.g.:-

  jc.Path.Create("Reco",
                 "NoiseFilterModule::Ana "               
                 "RecordSetupModule::Get "
...
                 "FitTrackSRListModule::Reco "
                 "EventSRListModule::Reco "
                 "RecordSetupModule::Reco "
                 "Output::Put");    jc.Path.Create("Reco",....);

This tells the JobControl package to create a JobCPath from a series of JobCModules.

Configuring the job
For example
```
    jc.Msg.SetLevel("Dbi","Info");
```
sets the DatabaseInterface package messages to Info level.
```
    jc.Path("Reco").Mod("DigitListModule").Set("ListsToMake=1");
```
Configures the DigitListModule JobCModule, and
```
   acd.Set("DeMuxAlgConfig", "default");
   acd.Set("NormalizeWeights", 1); // Normalize weights to 1 if non-zero
```
tunes an individual Algorithm.
JobCModule and Algorithm configuration is the most complicated part of the macro and will be dealt with in more detail below.
Executing the job path and printing the summaries.

E.g.:-
```
  jc.Path("Reco").Run(200);

  //Job Report
  jc.Path("Reco").Report();
  
  //Get Message Statistics
  jc.Msg.Stats();
```
This tells a JobCPath to run itself and give a report. Then the MessageService is instructed to give message statistics..

Configuring the JobCModules and Algorithms

Introduction

In principle, there a number of ways that JobCModules and Algorithms could be configured and this has lead to confusion in the past so there is now a policy on this matter. Unfortunately much of the code predates this policy and only some has been brought into line so far

Configurable Components

Algorithms

Algorithms are the objects that actually carry out reconstruction and analysis tasks. In general Algorithms have one or more tunable parameter. A complete, named, set is stored in an AlgConfig. Every Algorithm comes ready to run, with one or more AlgConfigs. If there is only one, it's name is "default", but if more than one, none will be so named. A job user can decide which AlgConfig is used and can even fine tune the individual parameters in the selected AlgConfig. This is done by operating on the Registry from which the AlgConfig inherits.

JobCModules

A user assembles JobCModules (which all inherit from JobCModule) into a path to be executed in an event loop. JobCModules deploy Algorithms and select which parts of the event object structure they operate on. JobCModules are configurable and all have a default configuration so can operate "out of the box". As with Algorithms, the user can fine tune the JobCModule's parameters, normally via the Set(...) method.

The Standard Configuration Model

The Role of the JobCModule

JobCModules that adhere to our policy allow the user to change the Algorithm it uses and the AlgConfig that Algorithm gets configured with. It may also allow the user to control other aspects such as which parts of the event object structure it is to operate on but must not tinker with individual parameters of the Algorithm's AlgConfig.

The following lines show how the "SR" reconstruction chain configure the Algorithms they use for FD cosmics:-

  //Configure Reconstruction Software for Far Det Cosmics data .
  jc.Path("Reco").Mod("SliceSRListModule").Set("SliceListAlgConfig=FarCosmic");
  jc.Path("Reco").Mod("ClusterSRListModule").Set("ClusterListAlgConfig=FarCosmic");  
  jc.Path("Reco").Mod("ShowerSRListModule").Set("ShowerListAlgConfig=FarCosmic");
  jc.Path("Reco").Mod("TrackSRListModule").Set("TrackListAlgConfig=FarCosmic");
  jc.Path("Reco").Mod("FitTrackSRListModule").Set("FitTrackListAlgConfig=FarCosmic");
  jc.Path("Reco").Mod("EventSRListModule").Set("EventListAlgConfig=FarCosmic");

The Naming Convention

For a JobCModule that produces CandXxx objects:-

The Algorithm is named AlgXxx.
The JobCModule is named XxxModule.
The JobCModule parameters that control the Algorithm it uses and the AlgConfig it is configured with are named XxxAlgorithm and XxxAlgConfig respectively.

Beyond (Behind?) The Standard Model

The Naming Convention

Both the "SR" and "Alt" reconstruction families deviate in minor ways from the naming convention:-

The "SR" modules drop "SR" from the JobCModule parameters, for example SliceSRListAlgConfig becomes SliceListAlgConfig.
The "Alt" modules are named with "Module" before Candidate type, for example AltSliceListModule becomes AltModuleSliceList.

Policy Violations

More serious, if understandable because the policy came so late, are violations of the policy. For example, the "Alt" modules, at least at the time of writing of these notes, could directly manipulate parameters within an AlgConfig. Given that a user can also directly do this, it's not hard to understand why this is banned.

Fine Tuning AlgConfigs

Users who are acquainted with the workings of an Algorithm can directly manipulate their AlgConfigs, as shown by the following code:-

  // Get the AlgFactory
  AlgFactory &af = AlgFactory::GetInstance();
  
  // AlgDeMuxDigitList AlgConfig parameters
  AlgHandle ah = af.GetAlgHandle("AlgDeMuxDigitList", "default");
  AlgConfig &acd = ah.GetAlgConfig();
  acd.UnLockValues();
  acd.Set("DeMuxAlgConfig", "default");
  acd.Set("NormalizeWeights", 1); // Normalize weights to 1 if non-zero
  acd.Set("TrimHyps", 1);    // Drop "0" weights if neg., or keep top N
  acd.LockValues();

Dealing with Specifics

What should you do when you want to configure a specific JobCModule or Algorithm?

For JobCModules:-

Start by looking them up in WebDocs if you are lucky, it will tell you all you need to know.
If that fails look up the JobCModule in the doxygen code at FNAL and check it's DefaultConfig method. This will tell you the names of all it's parameters and their default values. You can then use the Set method (inherited from JobCModule) to change any of these.

For Algorithms

Start by trying to work out what JobCModule uses them and then looking them up in WebDocs
If that fails look up the Algorithm in the doxygen code at FNAL but this time look at the RunAlg(...) method and read through the code to see how they use the AlgConfig they have been passed.

Further References

See the overview Running the Standard Jobs for more details about launch the loon job.

See Configuration of JobCModules and Algorithms for the overall policy on the configuration.

For JobControl see the JobControl section of User Manual at Fnal .

For examples of other macros which we use in production, see the $SRT_PUBLIC_CONTEXT/Production directory tree.

See the following sections for configuring individual packages.

See the Package Overviews
DeMux Module (a bit out of date .jcm have now been replaced with ROOT macros).
Standard Reconstruction (SR) modules e.g. CandTrackSR. Look at the Algorithm Parameters sections.
The subdirectories of $SRT_PUBLIC_CONTEXT/Production contain the job macros used for production runs.

Exercises

Before running any exercises see tutorial preparation.

In this tutorial you will see how a script, called a ROOT macro and also called a job macro, is used to configure the off-line reconstruction job loon. Take a look and see if you can understand the macro by referring to the notes above.

Once the job ROOT macro has been assembled the loon job can be launched for example:-

    loon -qb $MINOS_TUTORIAL_MACROS/loon_reco_job.C $MINOS_TUTORIAL_DATA/F00018143_0000.mdaq.root

See the overview Running the Standard Jobs for more details about launch the loon job. This script has been used for production work, so it's a realistic example and not something trivial for a tutorial! Study the macro and see if you can identify every line as one of the types listed above.

Make a local copy of $MINOS_TUTORIAL_MACROS/loon_reco_job.C and try making the following changes and rerunning the job:-

Increase the number of events to process to 500.
Change the print level on the Calibrator package to Debug.
Change the name of the output file to my_ntupleSR.root

Note to Maintainers: When making changes please follow the maintenance rules

Contact: Nick West <n.west1@physics.ox.ac.uk>


Security, Privacy, Legal

Notes and Further References

Loading in the application packages

Creating and assembling a job path

Configuring the job

Executing the job path and printing the summaries.

Configuring the JobCModules and Algorithms

Introduction

Configurable Components

Algorithms

JobCModules

The Standard Configuration Model

The Role of the JobCModule

The Naming Convention

Beyond (Behind?) The Standard Model

The Naming Convention

Policy Violations

Fine Tuning AlgConfigs

Dealing with Specifics

Further References

Exercises