Beam Simulations

From GlueXWiki
Jump to: navigation, search

Geant simulations of the Hall D Tagger Hall

A Geant3 simulation exists for the Hall D tagger area. It is maintained in the GlueX software repository, which is currently managed using subversion. Before doing this you should make sure your shell environment is properly configured for running GlueX software. For more information regarding on this, see HOWTO set up the GlueX environment. Once your environment is set up, the following commands will check out, build, and run your own working copy of the simulation.

$ svn co
$ make
$ gxtwist

As you can see, the simulation is performed by an batch-style application called gxtwist. There is also an interactive version called gxtwist++, if you are used to the interactive interface to Geant3. See below for a getting-started guide to interactive plotting of simulated events with gxtwist++.


Most of the information used by the Geant3 library to run the simulation is contained in the compiled application, but there are two inputs that it expects to find in disk files located in your working directory.

  1. configuration controls - The application expects to find this information in a file called "" located in your working directory. A standard version of this file is included in the distribution you checked out from subversion, but you will probably want to modify it before running your own simulations. Most of the commands in are explained in comments within the file itself. If you are not familiar with Geant3 control commands, you should consult the Geant3 documentation. One line in that you should be aware of it the SCAP line. The line starting with SCAP is intended to allow the user to scan a particle source over a region and selectively illuminate parts of the detector. In gxtwist, this line is used to tell the simulation where to inject the electron beam in x,y,z, cm units. The diamond radiator is centered at 0,0,0 and the electron beam is pointing along the direction 0,0,1 when it enters the simulation. The default "SCAP 0. 0. -1." line (decimals tell the system that the numbers are real, don't drop them!) enjects the beam just upstream of the diamond radiator so it passes through a 20 micron diamond before reaching the tagging spectrometer. If you want to simulate the tagger without anything at the diamond radiator, change this line to "SCAP 0. 0., 1.". Just downstream of the goniometer in the simulation is the amorphous radiator target which is a 1micron thick piece of aluminum located at 0,0,61 cm. If you want to simulate the tagger with neither the diamond nor the amorphous radiator, change the SCAP line to "SCAP 0. 0. 65.". The rest of the control lines should be self explanatory. The KINE line defines the beam particle type (electron=103), energy, energy spread, direction, direction spread, etc. The TRIG line defines how many beam particles to simulate. The defaults for most of the remaining lines should be fine.
  2. magnetic field maps - Field map files are needed for the tagger dipole and quadrupole magnets. The names of these map files are hard-wired in the hdds geometry for the tagger hall. These files are not a part of the software distribution, but are set up for downloading from a web server at UConn. The gxtwist application checks for these map files in your working directory when it starts up, and if not it tries to download them for you from the proper location, so you should not have to do this yourself. In case for some reason this is not working, you can download them manually from the following urls.


Geant3 is really only a simulation toolkit, and users normally are expected to customize it with their own sampling code that generates the output needed to answer their questions. This is normally done by modifying gustep.F to save information from each simulation step in histograms, ntuples, or other hits structures, and then save these to an output file in guout.F which is called at the end of the simulation. The distribution comes with a simple implementation of gustep.F that can be used as a guide for further customization. Geant3 distinguishes "sensitive" media in the material model of the setup that are designated as detectors. In the gxtwist geometry, there are several of these, listed below by their 4-character Geant3 volume name.

  1. XTAL - diamond crystal radiator
  2. TAMO - amorphous radiator
  3. MSFI - microscope fiber counter
  4. FX** - fixed array hodoscope counter
  5. ENDP - special scintillator placed near the end-point region on the focal plane

The distributed gustep.F records the passage of each particle that passes through the microscope, hodoscope, and ENDP detectors and saves the results in a separate PAW ntuple for each. The elements of the ntuples are listed below.

  • kind [int] - Geant3 particle type code for interacting particle
  • xin(4) [float] - position and time (x,y,z,t) of particle entry to detector
  • xout(4) [float] - position and time (x,y,z,t) of particle exit from detector
  • pin(5) [float] - momentum (px,py,pz,E,|p|) of particle at entry
  • pout(5) [float] - momentum (px,py,pz,E,|p|) of particle at exit
  • dEsum [float] - energy deposited by particle in detector
  • x0(4) [float] - position and time (x,y,z,t) where particle was born (or entered simulation)
  • p0(5) [float] - momentum (px,py,pz,E,|p|) of particle at birth
  • p1(5) [float] - other properties of particle at birth, for future use, currently unused
  • ppol [float] - linear polarization [0,1] of photon generated by this beam particle in diamond radiator

Interactive simulation and plotting

Normally one runs Geant3 simulations in batch mode, but sometimes one would like to be able to generate graphics views of the simulation geometry, or visualize particles as they pass through the setup. For this, the interactive version of the application called gxtwist++ is most useful. To start the simulation in interactive mode, simply set up your shell environment for running GlueX software and invoke gxtwist++ from this shell. After printing the usual Geant3 log messages, the following prompt is displayed.

*                                                    *
*            W E L C O M E    to   P A W++           *
*                                                    *
*       Version 2.14/04      12 January 2004         *
*                                                    *
 Workstation type (?=HELP) <CR>=1 : 

If you are familiar with the paw++ motif interface and like working that way, respond with "m" followed by Enter, otherwise simply press Enter. A graphics screen should then pop up on your desktop and the prompt GEANT> shows that your session has begun. The Geant3 documentation explains the full range of commands available to you at the command prompt. The most immediately useful ones are those related to drawing, eg. "draw hill 90 90 0 2 10 .005 .005" draws a top-view of the tagger area and all of the beam line elements that are included in the simulation geometry. "HILL" is the name of the top-level volume in gxtwist. The entire geometry hierarchy can be viewed and explored using the Geant3 interactive command "dtree".

The interactive interface is greatly enhanced by its support of paw-style macros called "kumacs". These are invoked by typing "exec <macro name> at the Geant3 prompt. One labor saving trick is to type the command "macro/default . AR" at the beginning of each session (or better yet, put it in your ~/.pawlogon.kumac file which executes automatically at the start of each paw++ or geant++ session). That command saves you the trouble of having to type "exec" in front of every macro you invoke. For the rest of this section, it is assumed that the above macro/default command has been invoked. If you prefer to type an explicit "exec" each time you invoke a macro, everything will still work as described below.

A very useful macro called "wc" is included with this distribution, to help with drawing views of the geometry. The Geant3 commands are fine for viewing the entire simulation at once, but if you want to zoom in on a portion of the setup you soon find that you are navigating around on a huge drawing surface marked off in cm, and how those surface coordinates map onto the 3D coordinates of the setup are difficult to keep track of. The "wc" macro stands for "world coordinates" and it lets you invoke Geant3 graphics commands using world coordinates instead of the artificial drawing surface u,v coordinates, and manages the mapping back and forth between the two. The commands provided by wc are entered as wc#<command> as in wc#draw or wc#dcut. The order and meaning of the wc commands are the same as the corresponding Geant3 primitives, except that coordinates are interpreted as 3D x,y,z coordinates relative to a user-defined origin. If you want to focus on a detector that is positioned at -50.8,0,167.33cm in world coordinates then do "wc#setorigin -50.8 0 167.33" and then wc#draw will naturally generate views centered on that detector from any angle, and wc#dxcut will generate cutaway views of that detector with any plane through its origin. The wc#pick command is also very useful, as it allows you to click on any object visible in a plot and have it look up the vector in the volume hierarchy that uniquely identifies the physical volume. It also prints the magnetic field at that point. Two special options exist for the wc#pick command: "wc#pick o" allows you to visually set the origin for subsequent wc commands by selecting it with the mouse, and "wc#pick m" allows you to measure the distance between two points by clicking the two end points with the mouse. In all cases, wc#pick accepts an arbitrary number of selected points, terminating input when the right mouse button is pressed.

Another very useful macro called "dbug" is provided with this distribution. This macro invokes the obtuse set of interactive commands that are needed to instruct Geant3 to generate various kinds of debug output during tracking. The full set of options accepted by dbug are listed by simply typing "dbug" at the command prompt without any arguments. Here are some useful cases that would be helpful to keep in mind.

  • dbug printout - spools a listing of every step during tracking, how much energy is deposited in each step, what volume boundaries are crossed, and what interaction mechanisms are invoked at each step.
  • dbug plot - saves a record in memory of the chain of positions each particle landed on during tracking, and at the end of tracking draws these with colored polylines on the current view in the graphics window, if any.
  • dbug plotnow - same as plot, except that the polylines are drawn as the tracking proceeds rather than at the end of the event; can be slower but shows the progressive development of complex events.
  • dbug none - turns off all of the above.

Gxtwist 10k.png

The view at the right was obtained using the interactive session below.

*                                                    *
*            W E L C O M E    to   P A W++           *
*                                                    *
*       Version 2.14/04      12 January 2004         *
*                                                    *
 Workstation type (?=HELP) <CR>=1 : 

GEANT > wc#dcut hill y 0 2 10 .005 .005
GEANT > dbug plotnow
GEANT > trig 10000