Difference between revisions of "HOWTO Modify the Detector Geometry"

Revision as of 10:15, 10 April 2012

Introduction

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. One of these tools generates GEANT3 based FORTRAN code from the XML that is compiled into a library that is eventually linked into the hdgeant executable.

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:

• Hall_D_Detector_Specification_(HDDS)
• HDDS Tagged Releases
• HOWTO use the stand-alone HDDS system
• HOWTO visually inspect the simulation geometry
• HOWTO do a Radiation Length Scan
• HOWTO Access Geometry Information from JANA/DANA

HDDS

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 https://halldsvn.jlab.org/repos/trunk/hdds

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

setenv HDDS_HOME $PWD/hdds     # tcsh

or

export HDDS_HOME=$PWD/hdds     # bash

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.

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

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, 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.

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