HOWTO Modify the Detector Geometry

From GlueXWiki
Jump to: navigation, search


The Hall-D detector geometry is kept in the software package HDDS. This is a collection of XML files that describe the geometry and a set of tools that convert the XML files into various formats. For example, one of these tools generates GEANT3 based FORTRAN code from the XML that is then compiled into a library that is eventually linked into the hdgeant executable. Some tools access the XML directly at run time.

To make things even more complicated, some programs like hdgeant3 provide an option where the XML to FORTRAN tool can be used at run time to dynamically generate the FORTRAN source, compile it, and link it as a shared object. These options give a lot more flexibility to the user, but consequently require the user to be aware of what option they are using!

This page describes how to checkout the geometry info, modify it, and use it in the sim-recon package. An example is given on how one would move the target position.

A few other relevant pages:


Identifying the scope of your project

Because there are several options, it is worth taking a moment to look at the scope of the project you are working on so that the simplest approach for your particular situation can be identified.

Almost always, your first steps should include using the

Location of Geometry Files

The geometry files are kept in the HDDS directory pointed to by your HDDS_HOME environment variable. Since you are wanting to modify the geometry, you'll want to check out a fresh copy of HDDS from the repository:

svn co

Set your environment variable to point to this freshly checked out directory

setenv HDDS_HOME $PWD/hdds     # tcsh


export HDDS_HOME=$PWD/hdds     # bash

Note that the HDDS directory contains both the XML geometry files and source code for the tools used to convert this into other formats.

Structure of Geometry Files

The files in the hdds directory with a .xml suffix contain the geometry information. A couple of them are special:

  • main_HDDS.xml is the top-level file that includes all of the others. Entire detector systems can be removed by commenting the appropriate line here
  • Material_HDDS.xml contains the material definitions for all of the materials used in the geometry.
  • Regions_HDDS.xml contains information about magnetic field maps and assigns them to specific regions of the detector. (It should be noted that one normally changes which field map is used by specifying it using a different mechanism.)

The other files contain geometry definitions for detectors or other elements (such as the beamline) in the hall. Each of these should have a comment near the top specifying where the origin of the coordinate system used by that file is relative to the Lab coordinate system.

Many files contain two sections. The top is the section used by HDGeant while the bottom was used by an early parametric Monte Carlo based on MCFast. A comment describing this appears in these files marking the separation of the two sections. Only modifications to the top (HDGeant) section will have any affect on code in the sim-recon package. The MCFast-based package has bee deprecated for some time.

Coordinate systems

Each XML file represents a volume that contains the elements described within it. The center of the volume (or origin) is described in a comment near the top of the file. Below is the comment from BarrelEMcal_HDDS.xml

 <!-- Origin of BarrelEMcal is center of upstream end
     of the active region, not including the light guides. -->

The positions of the top-most volumes within the file are given relative to that point in space. The position of the BCAL volume in lab coordinates is given in main_HDDS.xml. The global lab coordinate system has the origin on the beamline at the upstream face of the GlueX solenoid.

Browsing the Detector Geometry

Example: z-Location of BCAL upstream end in Lab coordinates

The upstream end of the BCAL modules is the origin of the BarrelEMcal volume. This is declared in a comment in BarrelEMcal_HDDS.xml, but the volume is actually placed in main_HDDS.xml.

Working our way up from the bottom of the main_HDDS.xml file:

  • "LASSfieldVolume" is placed inside of "everything" with no X_Y_Z parameter meaning their origins coincide
  • "experimentalHall" is placed inside "LASSfieldVolume" with a z-offset of -150.0cm
  • "GlueXdetector" is placed inside "experimentalHall" with a z-offset of 150.0 cm
  • "barrelPackage" is placed inside "GlueXdetector" with no offset
  • "BarrelEMcal" is placed inside of "barrelPackage" with a z-offset of 17.0cm

Adding these up gives: 0 + (-150.0) + (150) + 0 + 17 = 17cm

So, the upstream end of the BCAL is located 17cm downstream of the front face of the Solenoid.

Modifying the geometry

To modify the geometry, do the following:

  1. edit the appropriate XML file(s) using any text editor
  2. run "make" in the $HDDS_HOME directory. This will build a few things including the libhddsGeant3.a library
  3. cd into the $HALLD_HOME/src/programs/Simulation/HDGeant and run "make clean" followed by "make"

(It may not be necessary to do the "make clean" phase above, but it will not hurt.)

Updating the Material Map

Charged particle tracking requires knowledge of the materials that the particle passes through in order to include multiple scattering and energy loss effects. For minor changes to the geometry, you might get away with using the existing material map. For most changes though, you'll want to regenerate the material map.

The material map used by tracking is stored in the calibration database. Tools exist to generate this map from the XML files, but it is not done automatically by any of the standard build procedures (neither hdds nor sim-recon). The reason a separate map is used is because the quantities needed for tracking can be computationally expensive. At least when multiplied by the enormous number of times it must be done just to fit a track. These are, therefore, pre-calculated once by sampling various volumes within the detector at a large number of locations.

The XML geometry files are used to generate a ROOT representation of the geometry at the same time the GEANT3 representation is generated (when you ran "make" in the HDDS directory above). This ROOT representation is compiled into the HDGEOMETRY library that is part of sim-recon. The utility mkMaterialMap is then made by linking with this library. The mkMaterialMap utility will generate a map compatible with the calibration system and tracking code. There are actually several layers of maps made and these are scripted using the mkAllMaterialMaps.csh script.

Here are instructions on updating the map:
  1. cd to $HALLD_HOME/src/libraries/HDGEOMETRY
  2. make
  3. cd to $HALLD_HOME/src/programs/Utilities/mkMaterialMap
  4. make
  5. edit mkAllMaterialMaps.csh as needed (see below)
  6. run mkAllMaterialMaps.csh
  7. copy all of the material map files in the calibration database (see below)

It's worth nothing that some attempts were made to fully automate the process of generating the material map without requiring any knowledge of the detector geometry. In other words, we wanted to make it so only the XML files would need to be modified by hand. In practice, the tracking code needs either a very dense material map, or a hierarchically defined geometry to properly include all material effects. Both of these can be costly in either memory or CPU time. It is because of this that the mkAllMaterialMaps.csh script must be edited by hand to make sure the volumes it generates material maps for line up with the detector geometry.

Once the material maps are made, they must be placed in the proper calibration database directory. This should be indicated by the JANA_CALIB_URL environment variable which has a form like:

JANA_CALIB_URL:  file:///home/jsmith/HallD/calib

For the above example, the material map files should be placed in /home/jsmith/HallD/calib/Material.

It is important to check that no lingering maps exist in the calibration DB since all map files are read in by sim-recon. If you disable creation of a map or rename it, then an old file may still exist in the calibration DB and will need to be removed by hand.

(n.b. If one is using the CCDB, you would need to enter the maps in there using the appropriate tools. At the time of this writing, the CCDB is not being used for production.)

Modifying the Target Location: An Example

Suppose we wanted to replace the 3cm long LH2 target with a 5% radiation length Pb target. Furthermore, we want to move the target 1 meter upstream from the nominal location (centered at z=65cm).

A 5% rad. len. Pb target will be 0.05*(6.37/11.35) = 0.028cm thick. For simplicity we'll keep the same cross-sectional shape and area as the LH2 target.

1.) Open the file Target_HDDS.xml in a text editor and find the section containing the definition of the "LIH2" volume. It should look like this:

  <tubs name="LIH2" Rio_Z="0.00 1.500 30.000" material="LiqHydrogen"
	                        comment="target contents"  />

2.) Modify this to have the correct length and material as shown below. Note that the name "Lead" comes from Material_HDDS.xml. Look in there to see if the material you want to use is defined. If not, then add it. The format is self-explanatory.

  <tubs name="LIH2" Rio_Z="0.00 1.500 0.028" material="Lead"
	                        comment="target contents"  />

n.b. We re-use the name "LIH2" even though our target is no longer Liquid Hydrogen because the reconstruction code looks for that when extracting the target length from the XML source

3.) Open the file main_HDDS.xml in a text editor and find the section that places the "Target" volume. It should look like this:

  <composition name="GlueXdetector">
    <posXYZ volume="Target" X_Y_Z="0.0 0.0 50.0" />
    <posXYZ volume="barrelPackage" />
    <posXYZ volume="forwardPackage" />
<!-- removed from standard geometry 12/11/2007 -rtj
    <posXYZ volume="backwardPackage" />

4.) The value "50.0" is the location of the upstream face of the target in Z (see the comment near the top of Target_HDDS.xml). The default GlueX geometry has the LH2 target located at z=50cm to z=80cm. We want to move this 1m upstream so we subtract 100cm from it:

<composition name="GlueXdetector">
    <posXYZ volume="Target" X_Y_Z="0.0 0.0 -50.0" />
    <posXYZ volume="barrelPackage" />
    <posXYZ volume="forwardPackage" />
<!-- removed from standard geometry 12/11/2007 -rtj
    <posXYZ volume="backwardPackage" />

Now the Pb target should extend from -50cm to -49.072cm in Z.

5.) Run "make" in the HDDS directory.

6.) cd to the $HALLD_HOME/src/libraries/HDGEOMETRY directory and run "make"

(If you're using the HALLD_MY scheme, go to $HALLD_MY/src/libraries/HDGEOMETRY instead)

7.) cd to the $HALLD_HOME/src/programs/Simulation/HDGeant directory and run "make"

8.) cd to the $HALLD_HOME/src/programs/Utilities/mkMaterialMap and run "make"

9.) Edit the mkAllMaterialMaps.csh script to reflect the new target location. The default GlueX geometry defines 3 maps for the target (not including the start counter). These are the maps labeled "Target", "Target wall", and "Scattering chamber". Their default definitions near the top of the script are:

# Target
mkMaterialMap -Nr 2 -Nz 2 -rmin 0 -rmax 1.5 -zmin 50 -zmax 80 -n_r 5 -n_z 5 -n_phi 10
mv material_map material_map00_target

# Target wall
mkMaterialMap -Nr 20 -Nz 2 -rmin 1.50 -rmax 1.55 -zmin 50 -zmax 80 -n_r 100 -n_z 5 -n_phi 10
mv material_map material_map01_target_wall

# Scattering chamber
mkMaterialMap -Nr 100 -Nz 400 -rmin 0.0 -rmax 4.0 -zmin 35 -zmax 90 -n_r 100 -n_z 5 -n_phi 10
mv material_map material_map02_scattering_chamber

Modify these to reflect the new target shape and location. Note that since we didn't modify any of the support structure for the target, only the position needs to be shifted for the last two. When your'e done, those sections should look like this:

# Target
mkMaterialMap -Nr 2 -Nz 2 -rmin 0 -rmax 1.5 -zmin -50 -zmax -49.072 -n_r 5 -n_z 5 -n_phi 10
mv material_map material_map00_target

# Target wall
mkMaterialMap -Nr 20 -Nz 2 -rmin 1.50 -rmax 1.55 -zmin -50 -zmax -20 -n_r 100 -n_z 5 -n_phi 10
mv material_map material_map01_target_wall

# Scattering chamber
mkMaterialMap -Nr 100 -Nz 400 -rmin 0.0 -rmax 4.0 -zmin -65 -zmax -10 -n_r 100 -n_z 5 -n_phi 10
mv material_map material_map02_scattering_chamber

10.) Run the mkAllMaterialMaps.csh script. This can take quite a while to complete so be prepared to go do something else for an hour or two.

11.) Copy the resulting files into the calib/Material directory where calib is referred to in the JANA_CALIB_URL environment variable.

Other notes:

  • For this example, we left in the additional support structure for the LH2 target. This helps to maintain vacuum around the target which we may not need for the Pb target since it is not a cryo target. One could redefine that or remove it completely. These are the volumes CYLW, UWIT, DWIT, UFLT, and DFLT defined in Target_HDDS.xml.
  • We did not adjust the Start-Counter for this location or configuration for this example. One may wish to consider commenting that out or defining a new detector with more appropriate geometry.