exercises » History » Version 41

Version 40 (Kolahal Bhattacharya, 03/01/2017 05:39 PM) → Version 41/42 (Kolahal Bhattacharya, 03/02/2017 07:22 PM)

h1. LArSoft Exercises


h2. Run a simple lar job to create mu-'s of momentum 1.5 GeV/c from a point source.

We will create a file containing events that each have a single muon using the code in a public place. That means you will not need to build any code at this stage. So, go to your test release, that is your working directory. You made this in the guide. Set yourself up to run there with an appropriate mrb working directory, which we call @lgm@ here. All this is explained at In this first exercise you are going to run from fcl files and .so libraries -- files that form the heart of the framework -- that live in the official places. You will setup to run against uboonecode v06_26_02. *It is not obvious we're still using nightly in the modern era. If this is broken, use the latest vX__YY_ZZ instead!* Namely, you are not using your own code. So, let's first show the setup, which we urge you perform via an alias, like the following. Have a line like the below line starting @alias@ in your ~/.bashrc. (Use an alias and hand-execute the alias each login; *do not execute this stuff in your shell-initiated start up scripts* like ~/.profile or ~/.bashrc.)

<> alias ulgmr='source /grid/fermiapp/products/uboone/; cd /uboone/app/users/username/lgm/build; setup uboonecode v6_26_02 nightly -qe10:prof; mrbslp;' # a potential setup alias
<> ulgmr # actually execute the commands in the alias

And now, run the executable on this canned fcl job script file.
lar -c prodsingle_uboone.fcl

This fcl file will produce 5 muons through the set of modules SingleGen, LArG4, and DetSim. That's pretty cool. But where did it find prodsingle_uboone.fcl? How do I know it will run 5 events?
The answer comes from looking at our job script fcl file. We find our fcl files from sleuthing in directories whose names we know from the key environment variable $FHICL_FILE_PATH.

Here's a handy code chunk for looking for parameter sets. e

echo $FHICL_FILE_PATH | sed "s/:/\n/g" | less

It displays each individual path on it's own line, make it much easier
to figure out what's going on.

<> more /grid/fermiapp/products/uboone/uboonecode/nightly/job/prodsingle_uboone.fcl

The job starts each event with a clean slate as indicated by the EmptyEvent key word. Note that in prodsingle_uboone.fcl maxEvents is 5. Note the output root file full of histograms (that we declared and filled in the source code) is specified to be at @single_hist_uboone.root@ and the output ART root file (which serves as the one that we'll pass onto any further modules in subsequent @lar@ jobs) is to be called @single_gen_uboone.root@. Note, that these did indeed appear in your directory!

How did I make 1.5GeV/c muons and not, say, Higgsinos? The answer comes from drilling down into the included fcl files. From the job script we note that for the generator we need the fcl parameter set called @microboone_singlep@. fcl parameter sets are in fcl files in the same places as the job script fcl files: at all possible directories in $FHICL_FILE_PATH. So, let's search ...

@<> grep microboone_singlep /grid/fermiapp/uboone/products/uboone/uboonecode/nightly/job/* @
@<> grep microboone_singlep /grid/fermiapp/products/larsoft/lar*/nightly/job/* @
The relevant return line is from the second effort: @/grid/fermiapp/products/larsoft/larsim/nightly/job/singles.fcl:microboone_singlep: @local::standard_singlep@. That's the only place where microboone_singlep appears on the left hand side of a colon, and that's where the parameter set is defined. Although, what we've learned is that this parameter set is equated to @standard_singlep@, which we must now hunt down, in turn. Note that the return from the greps shows us that after defining microboone_singlep to be standard_singlep, we then proceed to over-write some parameters like X0 and Z0, meaning we force the particles to be generated from a particular point in the TPC. We will return to this idea. We grep the lar* job areas again for singlep and discover the motherlode at @/grid/fermiapp/products/larsoft/larsim/nightly/job/singles.fcl@, which upon investigation shows the full single particle parameter set, including the line @PDG: [13]@. Hence, we have generated mu-s.

h2. Reconstruct your muons

Go run @lar -c standard_reco_uboone.fcl -s single_gen_uboone.root@.

Note that this fcl script is magically just found in some other job/ directory. (Homework: which one?) The -s flag above tells @lar@ to read up the outputted ART root file of our previous job. Also, note this fcl file uses a rather bland series of reconstruction modules: calwire, which you absolutely must perform, then ffthitfinder, then dbcluster.

Now that we're running a job with recon modules in it @source:{ module_type }@ says RootInput, as we're sucking up an already-written root file in a previous job.

What would it take to make this fcl script use gaushitfinder (sic) and fuzzycluster instead of ffthitfinder and dbcluster? What would be required to make it also create spacepoints and run track3dkalmansps on those spacepoints? We leave that as an exercise to the reader. (A suggested starting point is to just copy down this fcl script to some local area and edit it, as before with prodsingle_uboone.fcl.)

h2. Eventdisplay your recon'd muons

Go run @lar -c evd_ub.fcl -s standard_reco_uboone.root@.

Note that you can turn on/off the viewing of Hits/Clusters. This may motivate you to tack on 3D recon modules -- spacepointfinder, track3dkalmansps, showerfinder -- and re-recon your muons and then go see if you can view the 3D objects.

Try out our other event viewer, argo at Note that you can browse to your just-produced ART root files and view events.

h2. Change the mu-'s to K+'s of lower momentum, originating throughout the TPC.

Here we want to still use canned code: stuff from the nightly's or the vX_YY_ZZ's.

But we have to get ahold of the prodsingle_uboone.fcl to alter a couple parameters to do what we want to do in this exercise. For now, let's just grab a copy and put it in our local area and use that. (We know this will work, cuz the very first item in $FHICL_FILE_PATH is "."). So, in your working area go @cp /grid/fermiapp/products/uboone/uboonecode/nightly/job/prodsingle_uboone.fcl .@

We'll show it here, as we'll refer to it a lot.

#include "services.fcl"
#include "singles.fcl"
#include "largeantmodules.fcl"
#include "detsimmodules.fcl"
#include "mccheatermodules.fcl"

process_name: SinglesGen

# Load the service that manages root files for histograms.
TFileService: { fileName: "single_hist_uboone.root" }
Timing: {}
RandomNumberGenerator: {} #ART native random number generator
user: @local::microboone_simulation_services

#Start each new event with an empty event.
module_type: EmptyEvent
maxEvents: 5 # Number of events to create
firstRun: 1 # Run number to use for this file
firstEvent: 1 # number of first event in the file

# Define and configure some modules to do work on each event.
# First modules are defined; they are scheduled later.
# Modules are grouped by type.

generator: @local::microboone_singlep
largeant: @local::microboone_largeant
daq: @local::microboone_simwire
backtrack: @local::standard_backtrackerloader

largana: @local::microboone_largeantana

#define the producer and filter modules for this path, order matters,
#filters reject all following items. see lines starting physics.producers below
simulate: [ generator, largeant, daq, backtrack ]
analyzeIt: [ largana ]
#define the output stream, there could be more than one if using filters
stream1: [ out1 ]

#trigger_paths is a keyword and contains the paths that modify the art::event,
#ie filters and producers
trigger_paths: [simulate]

#end_paths is a keyword and contains the paths that do not modify the art::Event,
#ie analyzers and output streams. these all run simultaneously
end_paths: [analyzeIt, stream1]

#block to define where the output goes. if you defined a filter in the physics
#block and put it in the trigger_paths then you need to put a SelectEvents: {SelectEvents: [XXX]}
#entry in the output stream you want those to go to, where XXX is the label of the filter module(s)
module_type: RootOutput
fileName: "single_gen_uboone.root" #default file name, can override from command line with -o or --output

physics.producers.generator.SigmaThetaXZ: [ 5.0 ]
physics.producers.generator.SigmaThetaYZ: [ 5.0 ]
physics.producers.generator.X0: [ 100.0 ]
physics.producers.generator.Z0: [ 50.0 ]
physics.producers.generator.P0: [ 1.5 ]


Remembering that we can overwrite parameters at this stage, and that the generator module lives in the producers clause of the physics parameter set, open an editor on your new copy of prodsingle_uboone.fcl and put these lines at the bottom in order to run 0.2 GeV/c K+s generated throughout the TPC, and not 1.5 GeV/c mu-s from a fixed point:

physics.producers.generator.PDG: [321] # K+
physics.producers.generator.P0: [ 0.2 ]
physics.producers.generator.SigmaX: [ 125.0 ] # width of Gaussian distribution, in cm
physics.producers.generator.SigmaY: [ 125.0 ]
physics.producers.generator.SigmaZ: [ 500.0 ]

Parameters in brackets are vectors. If instead we say

<pre> physics.producers.generator.PDG: [321, 13, 22, 2112] # K+, mu-, gamma, n

we'll choose randomly (flat distribution) to generate any of those 4 particle types. However, if we do that, we should now go overwrite every possible parameter in that set, as inherited from standard_singlep and make sure all of them are 4-elements long.

Let's note one more thing we have done with our canned code. We have run the module we label @largana@ in prodsingle_microboone.fcl. It is an analyzer, meaning it puts nothing on the event. This is in contrast with the producers which _do_ put persistent data onto the event. largana runs after all the producers. The key word @trigger_paths@ runs the producers, which you'll note are all captured in the @simulate@ array of modules, and the key word @end_paths@ holds the analyzers (held in @analyzeIt@) and the output. We remind you that you will always run producers or analyzers or filters in your fcl scripts.

If we go open the output @single_hist_uboone.root@ file we'll find a directory corresponding to largana, in which its histograms and a TTree reside.
root [0] TFile f("single_hist_uboone.root")
root [1] TDirectoryFile* l = f->Get("largana")
root [2] l->cd()
root [3] MCTTree->Show(0)
======> EVENT:0
MCEvt = 1
MCSub = 0
MCRun = 1

The natural question that follows might be Do these module labels, @generator, largeant, daq@, etc, mean anything? In fact, they don't mean anything per se, but they do mean something in a relative sense. The data from one producer module might well be used in subsequent modules. And thus, among the parameter set information for a producer is generally a label, or series of labels, that specifies which previous modules are needed from which the current module will get data. Those labels then are the names of the previously-run modules _from this or a previous job_. So, yes, those module labels generally have meaning down the line.

h3. Let us urge at this point that you go chase the @daq@ module's parameter set @microboone_simwire@.

* Note that each module's parameter set, first and foremost, gives a @module_type@ field, which is the name of the @* file that holds the producer/analyzer class whose main produce()/analyze() method is run each event-- finally, we make contact with the C++!
* Note also the @DriftEModuleLabel@ field. You'll find that this is @largeant@, by default. That means the daq module needs the data from @largeant@, which it happens is exactly the module that runs before it in our prodsingle_uboone.fcl. If we'd called that module @largeeeeeant@ in prodsingle_uboone.fcl instead, we'd need to overwrite the module name expected by @daq@, which is done by tacking on physics.producers.daq.DriftEModuleLabel: "@largeeeeeant@" at the bottom.
* Go try rerunning prodsingle_uboone.fcl, changing producer module names and, simultaneously, the expected module labels by downstream modules

h2. A more complex job script -- for Yale Workshop.

For the Yale Workshop we've produced a fcl script to walk you through a more elaborate set of modules. We'll let you go get it with the aid of the instructions on our corresponding wiki setup page. (Basically, from your new srcs directory, say @mrb g uboonecode@ if you haven't done that already, and walk down into @uboone/YaleWork/larsoftdemo.fcl@. This is on the develop branch of git.)

This module runs a bunch of producers, 3 analyzers, and a filter. We won't say much here about the producers, but we want to comment on the analyzers. The analyzers are in many ways redundant with one another. We run them all here to demonstrate that it can be done, and each demonstrates something unique. One analyzer that we run is @larg4ana@, which produces a nice TTree and, further, shows you how to get the MC particles off the stack. @analysistree@ is another analyzer module which produces a big end-of-event DST, if you will. (Data Summary Tape, from pre-2005 HEP parlance.) Finally, @analysisexample@ is very nice, as it does some of the the things the other two analyzer modules do in finer grain detail, and, further, introduces cleanly the concept of @art::Associations@. This is the mechanism by which we save and read-back, say, the hits which constitute a cluster. And, last, we learn in this filter module how to write to two streams, with given cuts. The Filter we run demands particular particles are generated as primaries. This is a bit silly for generating single particles, as we've done here. The only primaries are those which, by fiat, we forced to appear, and so the filtered output root file is either entirely overlapping or empty with respect to the non-filtered version here. This particular filter makes more sense if the primary generator is, say, Genie.

One other thing you'll notice about this fcl script is that not all the modules get their parameter sets from the included fcl files. AnalysisExample and the filter module get theirs on-the-fly -- meaning, their needed parameters are within stanzas here in the job script. This demonstrates some fcl flexibility.

AnalysisExample is an involved exercise unto itself and is documented here:

h2. Edit the module that captures the truth information into histograms and TTree branches.

Alright, we've gone as far as we can with the canned code. We need to edit some C++ now. We used above the module we labeled @largana@. That module is, after some exploration,

So, we need to grab that up. How does that work? Well, it's not MicroBooNE specific code, so it's not in uboonecode. That means it's in one of the lar* repositories. I am not so savvy with the O(10) lar* repositories as to know immediately where that is. My approach is to @ls -lt /grid/fermiapp/products/larsoft/lar*/nightly/source/*/LArG4Ana*@. We learn it's in larsim. We no longer want the nightly version. We want our own version. So, go now to and remind yourself how you git clone a repository into your srcs directory.

Once you have larsim, go to @srcs/larsim/LArG4/ and open it in an editor. Note the TTree and Histograms. Add a branch, remove a histogram, whatever. For sure, for piece of mind and if you do nothing else, add a line like @std::cout << "This is my code!!" << std::endl;@ Now, from the guide, go build, install and setup against your installed version. Run your prodsingle_uboone.fcl again.

Look for your message that shows you you've really run your code! Open the output hist*.root file in ROOT and look for your changed histograms and TTrees.