GeometryBrowserTutorial

Introduction

This page has was originally written for a Mu2e Software Tutorial in 2016; it still works but has been superceded by an updated tutorial prepared for June 2019. There are a few elements that were not transferred to the new page and this page will be retained until they are transferred.

This page has an introduction to viewing the Mu2e geometry using ROOT's TGeometry browser. The input to this exercise is a GDML file that was created by running Mu2e Offline and telling it to export the geometry to a GDML file.

Preparation

1. Download this gzipped tar file which contains the GDML file plus some scripts for viewing it. The GDML file was created using Offline v5_7_7.
2. Extract the files:

   tar xzf ~/Downloads/GeometryBrowsing.tar.gz
   

   This will create a subdirectory named GeometryBrowsing, with the content:

   ls GeometryBrowsing/
   DS3.C                     InVacuum.cc               NoBuildingOrCRV.C         TrackerColored.C          notes.txt
   InPSVacuum.C              InVacuum.hh               NoBuildingOrCRV.cc        TrackerMother.C           volumeDetails.txt
   InPSVacuum.cc             InsideDS.C                NoBuildingOrCRV.hh        VDs.C                     volumeHierarchy.txt
   InPSVacuum.hh             InsideDS.cc               SelectVirtualDetectors.cc mu2e.gdml                 world.C
   InVacuum.C                InsideDS.hh               SelectVirtualDetectors.hh mu2e_v5_7_7.gdml
   

   The files ending in .C are ROOT CINT scripts to view different parts of the geometry. The files ending in .hh and .cc are C++ code that are used by some of the .C files. The files volumeHierarchy.txt and volumeDetails.txt contain some summary information about each volume. The following items will walk you through using

   these files.
3. cd into the new directory and setup a modern release of root:

   cd GeometryBrowsing
   mu2einit
   setup root v6_12_04e -qe15:prof
   

   If you prefer you can setup a base release of the Mu2e Offline software, for example:

   source /cvmfs/mu2e.opensciencegrid.org/Offline/v7_0_4/SLF6/prof/Offline/setup.sh
   

   Among many other things, this will setup a modern version of root.
4. If you logout and login again, repeat step 3.

Exercises

• Exercise 1: Use the script world.C to get basic familiarity with the browser. This script shows shows the full Mu2e world volume - so most of what you see it earth and concrete. Look at the script world.C. It has three steps:
  • Read the GDML file
  • Create a TBrowser window
  • Draw the geometry starting from the highest level volume, the Mu2e world volume.

        View the introductory video in either (.mov) or
        (.mp4) format;
        this video illustrates the basics of
        using the TGeometry browser.  Try it yourself:
  

  root -l world.C
  

        If you see no display and you see an error message "cannot load swrast driver",
        follow the instructions on the page that discusses the
        [ComputingLogin#Mac_OpenGL_3D_Error|OPEN GL 3D graphics error].
  

• Exercise 2: In this exercise you will learn how to use the clipping features of the TGeometry browser. This exercise also uses the script world.C. View the video that shows how to use the clipping features ( formats: (.mov) or (.mp4)).

  root -l world.C
  

  After viewing the video, practice clipping yourself.

• Exercise 3: The previous two exercises told the browser to start from the top of the volume heirarchy; in this exercise you will learn how to tell the browser to start from somewhere else in the heirarchy. Look at the file TrackerMother.C; compared to world.C the only difference is the last line, which tells the code to start from a particular named volume, the mother volume of the tracking system. To run the exercise:

  root -l TrackerMother.C
  

  Experiment a bit with zooming, rotating and picking volumes; don't spend too much time because the next exercise will highlight a few of the volumes with color. You can read about the tracker geometry in Mu2e-doc-888

  Some facts about the tracker mother volume:

  • it is the annulus of a tube; that is, the hollow interior is not part of the mother volume.
  • the path in the volume hierarchy from the world volume to the TrackerMother is:

    World->HallAir->DS3Vacuum->TrackerMother
    

• Exercise 4: This exercise uses the file TrackerColored.C. Compare this to TrackerMother.C; you will see that it contains extra lines that ask that certain volumes be colored. To run this exercise:

  root -l TrackerColored.C
  

  In this figure the upstream stiffening ring has been colored red; the two half-rings that form the interface to the rail system have also been colored red. And the three longitudinal support beams have been colored green. The virtual detector at the mid-plane of the track has been colored blue; because the tracker mother volume is the annulus of a tube, the virtual detector is the annulus of a disk. The remaining structures are all tracker planes, arranged as stations of two planes each.

  If you carefully compare the display to Mu2e-doc-888 you will see that the two downstream stiffening rings are missing from this drawing; they will be added in a future version of Mu2e Offline.

  Next watch the video that shows how to navigate the volume heirarchy (.mov) (.mp4) using the TBrowser. To finish this part of exercise, repeat the example shown in the video.

  Another way to learn about the volume hierarchy is to look at the two files volumeHierarchy.txt and volumeDetails.txt that were included in the gzipped tar file that you unpacked. These files were created for Mu2e Offline v5_7_7.

  
  

  volumeHierarchy.txt

  This file contains one line for each volume in the volume hierarchy. The content of each column is:

  1. ordinal number (0 based)
  2. depth in the hiearchy tree (1-based, will be changed to 0 based in a later version).
  3. volume name - this is the same name seen in the hierarchy listing in the TBrowser left sidebar.
  4. copy number (0 based)
  5. total number of placements - see below for a comment
  6. ordinal number of the parent volume (-1 means no parent)
  7. Number of children
  8. Name of the material
  9. Name of the shape

  Comment on the copy number and the total number of placements: one tracker panel contains 96 straws; each has a unique copy number, 0...95. We make one panel object and place it 216 times:

   18 stations x 2 planes per station x 6 panels per plane = 216 panels
  

  volumeDetails.txt

  This file is a work in progress and is not yet complete; the description below is a complete description of the parts that are present.

  In this file there is one group of lines for each entry in volumeHierarchy.txt, typically four or seven lines. The content of the lines is:

  1. First row:
     1. ordinal number (0 based)
     2. name of the volume
     3. copy number (0 based)
     4. material
     5. name of mother; for the world volume the name of the mother is “Top”
  2. Second row:
     The translation of the center of the object relative to the center of its mother.
  3. Third line or lines 3 through 6:
     The rotation of the object relative to its mother.
  4. Last line: The name of the shape followed by the standard shape parameters in the standard order for that shape. See the Geant4 manual for the meaning of these numbers. For some shapes the code has not yet been written to extract the shape parameters; these shapes are G4ExtrudedSolid, G4IntersectionSolid, G4Polyhedra, and G4SubtractionSolid.

  
  The placement algorithm is to place the object in it's standard orientation at the center of the mother; then rotate; then translate. Rotations are specified as passive rotations. A planned future improvement is to express the rotation matrices in a more readable format, perhaps as 3 Euler angles in the Goldstein convention.

  A forseen future version of this file will include an option to display the translation and rotation relative to the Mu2e origin and the standard Mu2e coordinate axes.

  • Exercise 5: This exercise displays all of the objects inside the DS3Vacuum volume. To run the exercise:

    root -l DS3.C
    

    
    So what is DS3? For technical reasons we split the DS vacuum into 3 parts, DS1, DS2, DS3. DS1 is not interesting; it is the outer annulus of the DS vaccum in the region in which the TS5 assembly penetrates into the DS. The DS2 region extends from DS1 up to a value of z just upstream of the tracker. The remainder of DS, from DS2 downstream, is called DS3. Upstream of this is the DS2 and downstream is the DS3.

    When you view the figure you can identify the major structures inside theDS3: the tracker, the calorimeter and the muon beam stop. The model of the calorimeter includes the crates that will hold the front end boards; these live in the space above the calorimeter crystals. Other structures include the rails and bearing blocks. THe last structure of note is the piece of the Outer proton absorber that lives inside DS3; this is the green ring just upstream of the tracker.

    Do not confuse this use of DS1, DS2 etc with similar names with different meanings used by the magnetic group.

  • Exercise 6: This exercise, using the script InsideDS.C shows all objects inside the combined DS2 or DS3. To make this work requires a helper class, InsideDS.hh and InsideDS.cc. Look at InsideDS.C. Compared to world.C, it contains two additional lines:

      gROOT->ProcessLine(".L InsideDS.cc+");
    

    and

      InsideDS d(geom->GetTopNode(),false);
    

    The first of these tells ROOT to compile, link and load the helper class. The second line invokes the helper function. If you look at the code for the helper function you will see that it traverses the geometry hierarchy and sets all volumes inside the DS2 or DS3 to be visible and all other volumes to be invisible. The entire hierarchy below DS2 and DS3 is made visible so one can use the browser to remove or clip outer volumes and look inside them.

    In this example the draw command starts from the top of the volume hierarchy; another option would have been to start it at the HallAir volume. These are the only two volumes in the hierarchy that contain both DS2 and DS3 as descendants.

    To run this exercise:

    root -l InsideDS.C
    

    Compared to DS.C one can see the complete outer proton absorber, named protonabs3. Right click on this volume and set it invisible. With this removed one can see:

    • The stopping target foils and their supports
    • The fragment of the outer proton absorber inside DS3; it is called protonabs4.
    • The inner proton absorber, named protonabs1.
    • The part of the rails inside DS2
    • The volume TSdA4; this is the small green piece at the most upstream end of the figure; it is a piece of polyethylene that is designed to absorb neutrons that originate in TS5 or the upstream wall of the DS cryostat.

    Next, right click on the inner proton absorber and set it invisble. This will allow you to see the two stiff rings that support the inner proton absorber.

    So where is protonabs2? In this model there is none; it is reserved in case we extend the inner proton absorber to higher z; if it extends into the DS3, we will need to make it in two pieces, one in DS2 and one in DS3. The name protonabs2 is reserved for the fragment inside the DS3. Our present understanding of the optimal design for the inner proton absorber does not require such a fragment.

  • Exercise 7: This exercise shows all objects that have any ancestor that is a vacuum volume. The script for this exercise is InVacuum.C; as with the previous exercise, this one has a helper class InVacuum.hh and InVacuum.cc. The difference with respect to the previous exercise is the logic inside InVacuum.cc. To run this exercise:

    root -l InVacuum.C
    

    In this figure one can see all of the elements of the previous figure plus, the PS and the collimators at TS1, TS3 and TS5; one can also see many virtual detectors. Virtual detectors do not correspond to any real object in the detector; they are thin volumes, made of the same material as their parent; their job is to record any particles that pass through them.

    To complete he exercise, explore the new objects in the figure.

  • Exercise 8: This shows all volumes whose name starts with “Virtual”, The idea was to show all virtual detectors but some virtual detectors do not follow this naming pattern. So they are not shown in this figure. This script is much like the previous except that it's helper class is SelectVirtualDetectors.hh and SelectVirtualDetectors.cc. To run this exercise:

    root -l VDs.C
    

    On some computers the TBrowser screen stays white and there appears to be nothing on the screen. Open the OpenGL window and you will see the intended scene.

    
    Most of the virutal detectors appear in grey and most are either thin disks or thin boxes. Those associated with the tracker are colored. Zoom in on the tracker. The yellow object is a thin walled tube that sits just inside the outer surface of the tracker mother. Right click on this and set it invisible. The cyan object is a thin walled tube that sits just inside the tracker mother, at its inside edge; remember that the tracker mother is the annulus of a tube so that the many low energy electrons that travel along the beamline never enter the tracker mother. Right click on the cyan tube and set it invisible. There are green virtual detectors at the front and back of the tracker mother. These extend all the way to a radius of 0 mm. These are used to record the MC truth about conversion electrons and the tracking debug code compares measured-generated quantities at these surfaces. This leaves the blue and red colored object at the mid plane of the tracker. Together they form the virtual detector at the z mid-plane of the tracker that is used in the same way as the green virtual detectors. The blue part is a volume inside the tracker mother. The red part is a separate volume outside of the tracker mother. It is not legal in Geant4 to create this as a single volume, part of which is inside the tracker mother and part of which is outside; therefore two volumes are needed.

    
    If you look carefully in the calorimeter region you will see that each disk is surrounded by 4 virtual detectors, one each on the front face, the rear face, the inner edge and the outer edge. These are used to record MC truth information to assist in debugging and characterizing reconstruction algorithms.

  • Exercise 9: In this exercise you will be able to look at two assemblies inside the PS Vacuum. This script, InPSVacuum.C, follows the same pattern as the previous scripts and the draw command starts at the PSCVacuum volume; the helper class is found in InPSVacuum.hh and InPSVacuum.cc. To run this exercise:

    root -l InPSVacuum.C
    

    Again it might be hard to see anything in the TBrowser window. Open the OpenGL window; you may need to zoom out a little to get two assemblies into the scene, the prodution target plus its mounting system, on the left,, and the pbar asbosrber plus its mounting system, on the right. If you rotate, zoom and shift the scene you can view the details of the production target and the pbar absorber. For reference you can view figures of the production target assembly and the pbar abosrber assembly.

    
    

  • Exercise 10: In this exercise you will see a scene that starts from the top of the Mu2e world with all of the following made invisible:
    • Anything in the top two levels of the volume heirarchy (mostly dirt)
    • Anything related to dirt, the building, shielding or the CRV
    • Any volume whose name starts wtih VirtualDetector.

    The script for this exercise, NoBuildingOrCRV.C, follows the same pattern as previous scripts and the helper class is found in NoBuildingOrCRV.hh and NoBuildingOrCRV.cc. To run this exercise

    root -l NoBuildingOrCRV.C
    

    Open the OpenGL viewer and you should see a scene like the one in this pdf file. In this figure you can see the PS, DS and TS cryostats, plus their support systems. To the the right of the scene you can see the proton beam dump and elements of the extinction monitor system. To the far left of the scene is the muon stopping target monitor and its physical supports. Immediately downstream of the DS are the magnet and collimator that sweep charged particles out of the beam that is incident on the stopping target monitor. Two other items in the scene are an electronics rack, near the downstream end of the DS and two pipes near the top of the scene.

    Explore the scene. Open up the cryostat to look at the internal detail of the cryostat and the details of the collimators in TS1, TS3 and TS5.