Using the art Based Offline

The examples presented on this page illustrate how to run the Geant4 based examples of the Mu2e offline.

Instructions

0) Log into any of detsim, or mu2egpmv01 ... mu2egpvm04.
   Check that you can launch an xterm back to your display.  If not, make sure that
   your X permissions are set correctly.>
   If you are visiting this page in a login session in which you have
   previously setup the mu2e software, please log out and log in again.
   If you do not, you may have a stale version of some UPS products in your
   environment; this may cause some of the subsequent steps to fail.
1) cd /mu2e/app/users/
   mkdir your_username
   cd your_username
2) The following presumes you are already running bash. You can check this by typing
   > echo $SHELL
If you see a response like /bin/bash or a similar string, you are running bash.   If not, start a bash shell:
   > bash
3) Source the site-specific setup file. On all Fermilab supported machines this is:
   > setup mu2e
   This will establish your connection to cvs and git.  It will establish the tools needed to
   setup external products, including art.  If you are not running on a Fermilab managed computer,
   the corresponding instruction will be to source some script - contact your local Mu2e expert
   to learn it's name.  All instructions after this one should work exactly the same on all Mu2e
   sites.
4) Check out the head of the complete Mu2e Offline software:
   > git clone ssh://p-mu2eofflinesoftwaremu2eoffline@cdcvs.fnal.gov/cvs/projects/mu2eofflinesoftwaremu2eoffline/Offline.git

   If this fails please try:
   > git clone http://cdcvs.fnal.gov/projects/mu2eofflinesoftwaremu2eoffline/Offline.git

   The first method authenticates you to the server (via kerberos) so that you can later check in modifications to the code.
   The second method gives you readonly access and is open to all.  If the first method does not work for you, please contact
   Rob Kutschke, kutschke@fnal.gov .

   Once you have been given write access, you can tell your read only clone that it now has write access.

   You can read more about the recommended use of git for Mu2e.
5) The above step made a directory named Offline in your currnet working directory.  cd into it:
> cd Offline
6) This step is optional; you should skip it the first time that you build the code
      - By default the build system will build optimized code with -GNDEBUG, which disables asserts.
        In art jargon this is called a "profile build".  It will also use the OpenGL graphics system
        for Geant4 graphics.
      - You can change this behaviour using the command ./buildopts
      - If you wish to change options, you must do so before doing step 7).
      - You can learn about other options by:
> ./buildopts --help
7) Build the software
> source setup.sh
   - This will work on any machine, provided you have done step 3 above.
> scons  -j 4
  - scons is a replacement for gmake; it compiles all of the code and puts the
    object files in shared libraries; for details, see the Mu2e SCons page.
  - The option -j n will run up to n threads in parallel.
  - See details about using scons with multiple threads to
    take advantage of multicore and multiprocessor machines.
  - There will be some warnings that you should ignore:
     - The following two messages come from underlying products.  They do not indicate
       real problems and they will go away when we upgrade these products.
        - warning: "nullptr" redefined
        - warning: dereferencing type-punned pointer will break strict-aliasing rules
     - There will be some messages of the form:
        - warning: #warning BaBar package is absent. TrkRecoTrk cannot be displayed in the event display.
       This just says that you cannot display fitted tracks without checking out and building additional
       code.  More about that later.
     - Our goal is that there will be no other warning messages and I ask everyone to not commit code that
       has warnings.
  - A suggestion.  You can capture the output of scons to a file in several ways:
       1) scons -j 4 >& scons.log
       2) The other option is a three step process.
          a) script scons.log
              - this starts a subshell that captures its output to a file and sends it to the screen
          b) scons -j 4
              - this is run within the subshell
          c) exit
              - this returns you to your original shell,leaving a transcript in scons.log
8) This step is obsolete. (Retained the item so that I don't need to deal with renumbering ).
9) This step is obsolete. (Retained the item so that I don't need to deal with renumbering ).
10) Run the third example
> mu2e -c Mu2eG4/fcl/g4test_03.fcl >& g4test_03.log
  - this runs 200 events but with no graphics and makes an output file
    of event data named data_03.root
  - the geant4 code will create some hits and add them to the event.
  - the example also runs some code to read hits out of the event and
    make an ntuple in g4test_03.root which you can browse.
> root -l Mu2eG4/test/g4test_03.cint
  - this will run root to make three pages of plots.
  - It will also create a pdf file, named g4test_03.pdf, that contains
    all three pages.
  - The first page shows four of the histograms that were created in the
    module ReadBack, found in Analyses/src/ReadBack_module.cc. It should look roughly like this.
  - After the first page has been displayed, the following message will appear
    in the window from which you ran root:
     :Double click in the Canvas to continue:
    When this message appears, move your mouse to the window in which the histograms
    are drawn do one of two things: either double click your mouse or click once and hit enter on your keyboard.
    If you are doing this over a slow network double clicking is not reliable so the other technique is
    recommended.
  - Then the second page will be drawn.  It shows a scatter plot of all of the
    hits in the straws, shown in a "y vs x" view. It should look roughly like this.
  - You will also be prompted to double click or hit return after the second page appears.
  - Then the third page will appear. It shows a scatterplot of the energy deposition in the straw gas
    plotted against the step length in the cell.  It should look roughly like this.
  - On the second page, the script let root choose the titles for the page and for the axes.  On the
    third page, the script chooses its own titles.
  - After the third page, there is no prompt.  The canvas stays up and control returns to the root prompt.
  - To exit root type ".q" at the root prompt:
    root [1] .q
  - On most machines the best way to print the .pdf file is to browse it using kpdf, acroread or a web browser.
    Then use the print feature.
  - On some machines at Fermilab, you can print the pdf file that you just made:
    > flpr -qXXXXXX g4test_03.pdf
    Here XXXXX is the name of a Fermilab print queue.
    This is a little dangerous because some printers do not interpret pdf and instead print it as text!
  - Here is an example of the pdf file.
  - On most machines at fermilab you can use kpdf to view a pdf file.  On some machines you can also use acroread.
    From a linux command line:
      > kpdf file.pdf
      > acroread file.pdf
11) Run the 4th example.
> mu2e -c Analyses/test/readback.fcl
  - This reads back the data file made by g4test_03.fcl and remakes the histograms and ntuples.
  - This runs quickly because it does not need to run G4, it just needs to run the ReadBack module.
  - This will create a root file readback.root.  You can edit Mu2eG4/test/g4test_03.cint to
    read readback.root instead of g4test_03.root.  Give it a try.

The place to start understanding the C++ code is to look at Analyses/src/ReadBack_module.cc.
This is an example of a module, which is the unit of code that is managed by the framework.
There is powerpoint presentation that describes Readback.cc and provides
some background about the framework, the concept of a module, etc.

The file whose name is passed as the command line argument *.fcl, is the
file that configures the job. It is written in a Fermilab developed
languaged named FHiCL.

In the .fcl file, the order of information is important only within the
EndPath statement.  All of the preceding lines just describe Modules and
Services to the framework.  The EndPath statement tells the framework the
order in which to execute things.

The flow of the three g4test_*.fcl jobs is:
1) Create an empty event.

2) Run the module EventGenerator.
   This runs 3 event generators
     - mu2e conversion electrons
     - protons from muon capture on the Al nucleus
     - photons from pi- capture on Aluminium
   The physics content of the first two generators is reasonably good; the spatial
   and temporal distributions of the creation points in the target foils is correct and the
   energy distributions are correct. But the relative rates, are chosen for illustrative
   purposes, not for physics correctness.  The energy distribution of the third
   generator is correct but its spatial and temporal distributions are wrong; this will
   be fixed at a later date.  It's relative rate is also chosen for illustrative purposes.
   The first generator generates exactly one track per event.
   The last two generators each generate a random number of tracks per event; the random
   number is drawn from a Poisson distribution with a mean defined at run time.
    The number tracks from each generator is controlled by a
   run time config file passed as an argument to the generator module.
   Look inside the .fcl files and find the section that defines the
   event generator; the file names are genconfig_xx.txt

3) Run the module Mu2eG4.
   At the start of the job this creates a G4 geometry.  It copies the
   generated tracks out of each event, passes them to G4 and lets G4
   process them. The G4 geometry knows about the halls, walls, coils etc.
   The only detector component that it knows about is the tracker; by default
   the LTracker is chosen but there is an option for the ITracker and soon there
   will be one for the TTracker; the geomtry does not yet have targets or a
   calorimeter; they will come soon.
   ( The event generator code does know about targets, even though they are
     not in G4. )

4) The G4 code has most physics processes turned on, including decays,
   scattering, energy loss, hadronic interactions, and so on. The default
   G4 physics list is QGSP_BERT; this can be modified at run time to
   select any standard G4 physics list, plus several Mu2e home brew lists.
   The code that builds the Mu2e world inside G4 is in:
   Offline/Mu2eG4/src/Mu2eWorld.cc

5) The first two examples draw 2 different scenes.  In both scenes the
   following structures are drawn ( most of them in outline).
     - The earth up to the surface
     - The concrete walls of the hall.
     - The PS and DS cryostats
     - A tube segment to hold the place of the tracker (solid green).
     - A tube segment to hold the place of the calorimeterm (soild yellow).
     - The stopping target foils are also drawn but cannot be seen when the
       view is zoomed out this far.
     - Things that you cannot see include
         - vaccum volumes inside the DS and PS.  These actually
           appear as vertical lines in the yz view.
         - air everywhere else
     - The DS vacuum volume is split up into two regions, an upstream
       and a downstream region; the purpose is to allow a uniform field in
       the downstream region for the purposes of debugging tracking code.
       The upstream/downstream boundary appears as a vertical line in the yz figure.

6) The magnetic field map is computed by FNAL Technical
   Divsion; it contains field for the vacuumn regions inside the PS, TS and
   DS; the default behaviour is that, in the region of the tracker and ECal,
   the magnetic field is overridden with a field that is constant at 1.0 Tesla.

7) The red tracks are negative.  The blue tracks are positive and the
   green tracks are neutral.  The magnetic field is currently defined only in
   the vacuum volumes; therefore, outside of these volumes all particles
   travel in straight lines.

8) In a previous version of this example, cosmic ray muons were generated.
   This has been removed because the startup time of this generator is more than
   1 minute, which makes for a bad example.


Other notes:

How to set step limits. There are two parts:
 1) PhysicsList.cc - add a StepLimiter process to the list of processes.
    Must do this in a per particle bassis.
 2) Mu2eWorld.cc - set step limits in the logical volumes of interest.

The MECO defintion of the detector positions is that:

a) There is a reference point that is on axis in the DS at
   z=12000 mm relative to the MECO orgin at the TS middle.

b) The tracker is centered at z=-1800mm relative to this.

c) The targets are centered at z=-6100mm relative to this.

d) the calorimeter is centered z=+700mm relative to tihs.

Some suggested exercises:

1) In g4test_01.fcl, change the number of events to do.
2) Make an xz view of the detector.  Step 1 is to make a copy of
   visxy.mac or visyz.mac and modify the copy to view down the y axis.
   Step 2 is to modify g4test_01.fcl or g4test_02.fcl to use your new
   .mac file; the filename appears in the parameter set for the the module
   labeled g4run.  There is one oddity: if you set the viewpoint looking
   exactly down the y axis, G4 decides to rotate the x and z axes by 45 degrees
   and then to print some warning messages.
3) In genconfig_01.txt enable the models of pi capture and cosmic rays
   by setting their means to non-zero numbers.  You also need to add the
   lines:
    bool cosmictoy.do     = true;
    bool picapture.do     = true;
4) In g4test_*.fcl change the random number seed and see that you
   get different events.
5) In Offline/EventGenerator/src/CosmicToy.cc, change the area covered by
   the cosmic rays and their angular distribution.

Security, Privacy, Legal