GeometryBrowserTutorial2019

Introduction

This page has an introduction to viewing the Mu2e geometry using ROOT's TGeometry browser. It was written for the tutorial day at the University of Minnesota Collaboration meeting in June 2019; and it supercedes the version written for the 2016 tutorial. 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. Copy the files need for this exercise to your working area
   1. If you are working within the Docker container:

      cp -dR /Tutorials_2019/GeometryBrowsing .
      

   2. If you are working on mu2egpvm:

      cp -dR /mu2e/app/Tutorials_2019/GeometryBrowsing  .
      

   Note the use of the -d option ( --no-dereference) to preserve symbolic links. These files include two GDML files plus some scripts for viewing them. One GDML file was created using Offline v5_7_7 and the second by Offline v7_4_1. By default you will use the newer one. This will create a subdirectory named GeometryBrowsing, with the content:

   ls GeometryBrowsing/
   DS3.C          InVacuum.hh         NoBuildingOrCRV.hh         mu2e.gdml
   InPSVacuum.C   InsideDS.C          SelectVirtualDetectors.cc  mu2e_v5_7_7.gdml
   InPSVacuum.cc  InsideDS.cc         SelectVirtualDetectors.hh  mu2e_v7_4_1.gdml
   InPSVacuum.hh  InsideDS.hh         TrackerColored.C           volumeDetails_v5_7_7.txt
   InVacuum.C     NoBuildingOrCRV.C   TrackerMother.C            volumeHierarchy_v5_7_7.txt
   InVacuum.cc    NoBuildingOrCRV.cc  VDs.C                      world.C
   

   The files ending in .C are ROOT 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 following items will walk you through using these files.

2. The file mu2e.gdml is a symbolic link to the new gdml file; if you are not familiar with symbolic links, look it up in any unix documentation.

   ls -l GeometryBrowsing/mu2e.gdml
   lrwxrwxrwx 1 root root 16 2019-06-22 16:57 mu2e.gdml -> mu2e_v7_4_1.gdml
   

3. cd into the new directory and setup a modern release of root. If you have already done the setup for another exercise you do not need to repeat it.
   1. If you are running the tutorial in the Docker container:

      cd GeometryBrowsing
      source /Tutorials_2019/setup_container.sh
      source /Offline/v7_4_1/SLF6/prof/Offline/setup.sh 
      export ROOT_INCLUDE_PATH=".:${ROOT_INCLUDE_PATH}"
      

   2. If you are running the tutorial on mu2egpvm*:

      cd GeometryBrowsing
      mu2einit
      source /cvmfs/mu2e.opensciencegrid.org/Offline/v7_4_1/SLF6/prof/Offline/setup.sh
      export ROOT_INCLUDE_PATH=".:${ROOT_INCLUDE_PATH}"
      

4. If you logout and login again, repeat step 3.
5. In the following you will view some videos that are available in both .mp4 and .mov formats. If your browser supports .mp4, prefer to use that format because it is half the size of .mov .

Warning

In the exercises below you will look at some videos that show how to navigate the Mu2e geometry using the ROOT TGeometry browser. The videos were made using the v5_7_7 gdml file and with slightly older versions of the root scripts. The exercises that you will do will be different from what you see in the videos in 2 ways.

1. By default you will use the v7_4_1 gdml file. The big difference is that the tracker geometry has changed a great deal; also the Mu2e building and some services are modeled in more details. But the big picture is still correct. If you feel more comfortable doing the exercises using the older geometry, you can switch to it as follows:

   ln -sf mu2e_v5_7_7.gdml mu2e.gdml
   

2. In the video the first step is to select the OpenGL viewer. The new scripts do this by default so you can skip that step.

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 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 beige; the thin stiffening rings that also provide shielding for the electronics have been colored red. And the two longitudinal support beams have been colored green; there are colored insets in these beams that model the runs for power, gas and optical fibers. 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.

  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.

• 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:

  #include "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 class. If you look at the code for the helper class 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
  

  The first time that you do this, will take a few minutes because root has to compile the helper class, link it into a shared library and load that shared library. On subsequent invocations ROOT only has to load the shared library, so it will be much faster. If you edit the helper class ROOT is smart enough to recompile, link and load as needed.

  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.