Geometry

Next Mu2e Geometry Meeting: TBA

Introduction

This page contains two major sections. The top, labeled part 1 through 6, is the "Working Area." This includes contact information, a to-do list, and pointers to the relevant documentation describing the various requirement and implementation documents. The bottom, part 7, is the big picture philosophy, based on the original version of this Geometry page.

NOTE: If you are planning to change the software description of some part of the Mu2e geometry, or if you have approved changes to the geometry that need to get into the Offline software, please first contact the Geometry Czar.

Contacts

Geometry Czar	TBD	TBD
G4Beamline	Dave Hedin	hedin@niu.edu
MARS	Vitaly Pronskikh	vspron@fnal.gov
Computing	Rob Kutschke	kutschke@fnal.gov

To Do

Current To-Do List: See Mu2e-doc-8378

• Update geometry for calorimeter backplanes, etc - Giani?
• Identify and factor simulation vs. reconstruction Geometry
• Remove underscores from the names of sensitive volumes?
• Add inner walls of building, improve current outer wall reps, add roof
• Improve geometry hierarchy
• Update external shielding endcap
• Continue fleshing out pipes
• Add more services
• Improve upstream vacuum endcap for PS/HRS
• Evaluate simulation model vs. actual construction
• Update cryostat wall thickness
• Add material in proton beam/final focus area
• Add material in remote handling room, including robot
• Add ground-level racks/handlers
• Take proton beampipe further upstream
• Alignment parameters?
• Decouple construct functions from direct SimpleConfig use
• Add the ability to create sub-volumes for MARS use

Recently completed tasks

For recent changes to the Geometry, consult Offline Release Notes or the mu2e Geometry HyperNews forum.

Component documentation

Materials

Here is the current list of materials known to the Mu2e Offline.

Overview

• Geometry Issues for CD-3c
• The Mu2e Apparatus
• Tutorial (2016) on Geometry Browsing

In the following table, "Requirements Documents" describe the requirements on the actual pieces of geometry and are generally not software-specific. "Implementation Documents" describe how the software model of the geometry was designed, how it works, and/or how it performs.

Please forward information about missing items to the Geometry Czar.

Component	Requirements	Implementation	Notes
External Shielding	Docdb-1506 - WBS 5.4 Upstream Docdb-1371 - WBS 5.9 Downstream	External Shielding Geometry Documentation	Produced by David (Louisville) Brown, modular and generic
Muon Beam Stop	Docdb-1351 - WBS 5.8 Docdb-1383 - WBS 5.10 (supports)	Docdb-1519: Initial Implementation	Krzysztof Genser initial implementation, D. No Brown update
Conventional Construction (Building walls, dirt, etc)	Docdb-3494 Docdb-5382 Docdb-5490 Docdb-5680 Docdb-5743	Docdb-4507 Docdb-5121 Docdb-6449	Initial implementation by Kyle Knoepfel

PS Area

PS External Shielding Slide

General Documentation

Geometry Images

Tarball of tiff images using default geom_common.txt)

• Current Geometry (Sept 2015)

GDML's

To make your own gdml file of the Offline geometry model, edit the file Mu2eG4/fcl/prolog.fcl and change the writeGDML parameter from false to true. Run art using any standard fcl config file.

This procedure has been collected in one fcl command

mu2e -c Mu2eG4/fcl/gdmldump.fcl

• Current Geometry (Sept 2016 - Offline v5_7_9) gdml file

You can dump the volume hierarchy by

./buildopts --g4vis=ogl
source setup.sh
scons -j 4
cp Mu2eG4/fcl/transportOnly.fcl ./hierarchy.fcl
echo 'physics.producers.g4run.visualization.initMacro : "Mu2eG4/test/visTree.mac"' >> ./hierarchy.fcl
mu2e -c hierarchy.fcl -n 1 >& hierarchy.log
q

Coordinate translation

• docdb 888 Tracker geometry note
• docdb 5952 talk for cd3
• docdb 11649 has superseded docdb 6449 for general drawings (as-built)
• docdb 13568 defines the main coordinate system w.r.t the building
• docdb 1120 units and coordinates
• The nominal elevation of the Mu2e coordinate system above the lower level concrete topping slab is 91.04196" above the 721' level of that slab

As a reminder to developers:

x(mu2e)	=	x(g4bl) + 3904 mm
y(mu2e)	=	y(g4bl)
z(mu2e)	=	z(g4bl) - 7929 mm

Notes on Geometry Files

To specify a Mu2e geometry in the Mu2e Offline you put the following in the services table of your fcl file:

GeometryService : { inputFile : <filename> }

where <filename> is the name of a geometry file. A typical services table will contain configuration for other services. To choose the currently recommended geometry, use the file:

Mu2eG4/geom/geom_common.txt

where the path is relative to a base release of Mu2e Offline. If you look at this file, you will see that it contains only one line: it includes one of the named geometries. As of July 2017, there six supported and two deprecated named geometries:

Mu2eG4/geom/geom_common_current.txt
Mu2eG4/geom/geom_common_MARSrunMay17.txt
Mu2eG4/geom/geom_common_TrackerShldStdyJun17.txt
Mu2eG4/geom/geom_common_cd3_s4p2.txt   **current default
Mu2eG4/geom/geom_common_cd3_s4p2_backgroundSim.txt
Mu2eG4/geom/geom_common_cd3_s3p2.txt
Mu2eG4/geom/geom_common_cd3_p1.txt  **deprecated
Mu2eG4/geom/geom_common_tdr.txt   **deprecated

The current default is highlighted in this list. Users who need to revive the deprecated geometry files can find them in any Offline v6 tag before v6_2_3 and v5 tags in the v5_7_x series.

If you wish to override the choice of the geometry file, the recommended procedure is to add the following at the bottom of your fcl file:

services.GeometryService.inputFile : <filename>

Some comments on each of these follows:

geom_common_current.txt

This is the bleeding edge geometry - including all recent changes. It is not the default geometry because it is not guaranteed to be backward-compatible with existing data files.

geom_common_MARSrunMay17.txt

This file contains the geometry as used for the large-scale MARS simulation campaign undertaken in May 2017. It is similar to geom_common_cd3_s4p2.txt, but with multiple updates: vastly updated civil construction, more support material, etc.

geom_common_TrackerShldStdyJun17.txt

This file is geom_common_MARSrunMay17.txt, but with a new Tracker geometry: TTracker_v04.txt. This geometry removes the two station gaps that had been in the tracker design and places thin brass rings between stations for radiation shielding.

geom_common_cd3_s4p2_backgroundSim.txt

Relative to geom_common_cd3_s4p2.txt there is one change: the tracker has all 20 stations (not 18 - see the comment in the description of geom_common_cd3_s4p2.txt). This file is used to generate, but not to reconstruct, events in stage 4 pass 2. The strategy is to run g4 on a 20 station tracker. When we make hits we skip straws from the missing stations. In this way we can study trackers with 18, 19 or 20 stations without having to rerun G4.

geom_common_cd3_s4p2.txt

This file should be used to analyze files produced by the second pass of stage 4 onward. It is the current default starting from mid-2016. Relative to geom_common_cd3_s3p2.txt this has the following changes:

• Update the tracker from the TDR to the CD3 geometry
• Update the calorimeter from the BaF (TDR) design to the CsI (CD3) design.
• Add an electronics rack in the hall beside the DS.

In this geometry the tracker design has slots for 20 stations but only 18 stations are present. In the CD3 design we only have money to build 18 stations. Should the finanacial situation improve, we will build one or two more stations and install them in the available slots.

geom_common_cd3_s3p2.txt

This file was used for the second pass of stage 3 and for the first pass of stage 4. Relative to geom_common_cd3_p1.txt it has the following changes:

• Use the GA05 field maps instead of the Mau9 field maps.
• Use the cylindrical proton absorber, not the conical one.
• Add some service pipes on the west wall of the DS hall.

geom_common_cd3_p1.txt

(deprecated) This is the geometry file used to run passes 1 and 2 of the beam simulations in the CD3 simulation campaign. It was also used for the first pass of stage 3. It has TDR era descriptions of the tracker and calorimeter but in these stages those detectors are hidden.

geom_common_tdr.txt

(deprecated) With this geometry file, one can use modern code to analyze the tracker information from TDR era event-data files; be aware when you make hits from the StepPointMCs you will use modern code for hit making - you will not get TDR era hits. You can also do some limited analysis with the calorimeter information from TDR era files; when you make hits you may use code that loads CsI properties by default - you may also need to modify conditions information to get properties of BaF2. Check this out before using this code to look at calorimeter information. If you need to look at other information from TDR era files, you should use code from that era.

See also some history on geometry files

Rob Kutschke's Notes on Geometry Philosophy, circa 2010

This note describes the main ideas behind the geometry system used by the Mu2e software.

Mu2e has three major clients for its geometry description:

1. Reconstruction
2. Simulation
3. Event display ( also called visualization).

Here reconstruction should be broadly construed to include software triggers/filters, online in general, calibration and so on. Simulation includes Geant4 and perhaps one or more fast simulation packages. And there might be several event displays, one optimized for visualizing the geometry and another optimized for visualizing hits and tracks.

These three clients place very different demands on the geometry system and past experience has shown that, for tracking detectors, it is not possible to build a single representation of the geometry information that works well for all three clients. This is discussed further in Appendix I . This leads to the situation that we must build and maintain distinct geometry representations that are optimized separately for each purpose. With this constraint, the critical problem is to ensure that all of the different representations derive their information from a single authoritative source.

The nominal Mu2e detector can be described by a few hundred numbers. By the "nominal detector", I mean the detector that would exist if we could build it without any misalignments. Most of the work in the next few years will focus on variations of the nominal geometry, perhaps with some heuristic treatments of misalignment. We have planned how real alignment information will eventually plug into the system; this is described later.

Some constraints on the single authoritative geometry are:

1. For the nominal detector we would like the single authoritative source to be stored as a few human readable text files so that it is easy to compare two candidate detectors without requiring a tool more complicated than the UNIX diff command.
2. We would like to be able to run an instance of the offline software as the lowest non-real-time level of the online system; this includes use f or software triggers and filters.
3. We would like to use the same reconstruction geometry in the online system that we use in all other reconstruction steps.
4. The online system must not have a dependence on Geant4; we do not want the Geant4 memory footprint or the Geant4 startup delays.

I am told that it is possible to write GDML files that satisfy the first requirement but I have yet to see a successful demonstration; therefore we have decided not to make a GDML file our single authoritative source. That said, it would be perfectly OK to construct a GDML file from the single authoritative source and use it elsewhere. Requirements 2 through 4 argue that the reconstruction geometry must have no run-time dependence on Geant4; therefore the Geant4 geometry must not be the the single authoritative source.

The solution adopted by Mu2e, that satisfies the above constraints, is:

1. There is a framework service named GeometryService. Any element of the geometry that is used by reconstruction code must be described by classes within the GeometryService.
2. The GeometryService will get its information from the geometry database and the ConditionsData database.
   • These databases are ultimately the single authoritative source.
   • For the time being, we do not have these databases and the information is held in flat files; as of May 2010, there is a one such file, Mu2G4/test/geom_01.txt.
3. Reconstruction code must get its geometry information from the GeometryService. It must not directly access the databases.
4. If it is convenient, elements of the geometry that are not needed by reconstruction may also be described by the GeometryService but they need not be. For example the reconstruction code does not need to know about the earthen overburden or the concrete shielding blocks. So there is no requirement to represent these within the GeometryService and the code that instantiates these G4 volumes may get its information directly from the databases.
5. The code that instantiates the Geant4 geometry for elements that are used by reconstruction code must get its information from the GeometryService. It must not directly access the geometry or conditions databases. The classes in the GeometryService should have special accessors that present the information required by Geant4 in a convenient form. As much as possible the computation required to convert from the Geometry Service representation to the G4 represenation, should be done in the geometry service.
6. The magnetic field map will be owned and managed by the GeometryService and the G4 magnetic field routines should contact the geometry service to access the field.
7. The GeometryService has a "front-end" and "back end". The front end is the classes that are seen by the clients; these classes are "mostly dumb data" and must be persistable. These classes will be written to the run-data segment of the event-data file. The front end classes do not know how to populate their own information; that is the job of the back-end classes. A more complete discussion follows.
8. As we develop visualization packages, they should get their information via the geometry service. As needed, we should add functionality to the geometry service to support this.

As mentioned earlier, the GeometryService has a front end and a back end; the front end is the part seen by the clients and our goal is to make this interface stable in time. For example, client code can ask the GeometryService for an LTracker; it can then ask the LTracker for the properties of a straw such as the position of the mid-point of the straw, a unit vector in the direction of the straw, the outer radius of the straw, the material(s) of which the straw is made and so on. A key feature of the design is that the LTracker class is "mostly dumb data"; that is, the LTracker knows the position of each straw but it has no idea where that information came from; it just knows. There is a companion class, the LTrackerMaker, that knows how to create an LTracker fully populated with the correct information. The LTracker class is only "mostly" dumb-data since it may do simple computations on its own member data; for example it may have an accessor that returns a diameter when the relevant data member is a radius.

Why two classes, the LTracker and the LTrackerMaker? The main reason is that the LTracker needs to be persistable while the LTrackerMaker has no reason to be persisted and might be very, very difficult to persist. The difficulty arises because the LTrackerMaker will someday need to know how to interface with databases. To avoid this complication the parts that need to be persistable were kept simple and moved into separate classes.

The existing classes in the Geometry service, LTracker, TTracker an so on should be considered as prototypes. When reconstruction algorithms require that new features be added to these classes, then those features should be added. Presumably this will happen many times in the coming months; when possible we should add to the interface, rather than changing the interface but there may we be times when we need to change interface and, therefore, change client code that depends on it. There is not yet so much client code that it justifies compromises in the design of the geometry classes.

The existing geometry classes currently contain some pointers; they also contain the indices that are necessary to restore the pointers after persistency. We do not yet have a solution to automatically restore the pointers after persistency but we will soon.

Appendix I: Examples of different demands

When doing tracking finding and fitting we will want to know things like: a unit vector that is tangent to the wire catenary at a given position along the wire; the unit normals to each face of support materials. Moreover we will want this information given in one coordinate system for all straws, presumably one with the origin at the nominal center of the tracker. In the Geant4 geometry system the above are derived quantities that are not naturally available and are difficult to compute. A Geant4 geometry object only knows about its position and orientation within its immediate mother volume; it knows nothing about its position and orientation within its grandmother or great-grandmother volumes. Those transformations are computed by Geant4 as needed. There is no point within the execution of G4 that one could write a loop over all straws and find their locations within the coordinate system of the Tracker mother volume.

In the mid to late 1990's there were several spectacular failures in which groups tried to write a track reconstruction and visualization code by deriving classes from the Geant4 geometry classes. The main issue was that it was necessary to carry around the full machinery of Geant4, which requires both a large memory footprint and large CPU time for initialization. This burden was too big to bear in environments like software based high-level triggers on machines with limited memory and otherwise-light-weight graphics applications.