HOWTO Modify the Detector Geometry

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.

HDDS

Before getting started, it's useful to point out 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

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

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

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 defined in BarrelEMcal_HDDS.xml, but the volume is 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

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 to build 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. These are pre-calculated once by sampling various volumes within the detector at a large number of locations.

Here are instructions on updating the map:

1. cd to $HALLD_HOME/src/programs/Utilities/mkMaterialMap
2. make
3. edit mkAllMaterialMaps.csh as needed (see below)
4. 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 CPU time.