This tutorial provides a manual for the operation of the HERMES Generator Monte Carlo suite GMC, as well as instructions and example codes for analyzing its output.
Introduction to GMC
The HERMES Generator Monte Carlo (GMC) is a suite of programs
that can simulate a diverse array of physics processes using a common
interface and output format.
The programs are named
gmc_package, where package
refers to the type of physics generator involved. For example,
gmc_disNG is the standard HERMES generator and simulates
deep-inelastic events. Meanwhile, gmc_aroma generates
heavy flavour events, gmc_photo produces photoproduction events,
gmc_dipsi simulates diffractive vector-meson production,
etc ...
In this introductory section we'll get you started as quickly as possible with some basic information. The entirety of the tutorial assumes that you have the full HERMES software tree installed on your machine under the HERMES_TOP directory /hermes.
The Monte Carlo code is subdivided into units called packages. Some of these packages produce only libraries (the QED radiative-corrections package RADGEN is an example). The others, like disNG, produce executable GMC programs, and may or may not produce a library as well. The PEPSI4 package, for example, produces a library which is used by the gmc_disNG program, but it also generates its own program, gmc_pepsi4.
The structure of the code makes it very easy for a user to develop his or her own GMC physics generator, or modify an existing one. To create a new GMC program, only a few subroutines must be written. The infrastructure of the program, including the main program itself, is entirely supplied by linking with the GMC libraries you need. A small template package is supplied with the distribution which provides you with all the files you need to create a new generator, including dummy versions of the user-routines you have to write.
To create a GMC generator, the user only has to write a handful of subroutines. All are stored in files with standard names of the form gen_*. Here are the two most important gen files:
gen_init.F Initialize generator gen_event.F Generate one good eventWith this slight information you're already set to examine the key source code of any GMC package!
The other gen files provide optional functionality. Dummy versions have to be present, but they don't have to do anything.
gen_name_init.F Optionally add NAME variables to generator gen_set.in Optionally add SET variables to generator gen_setchk.F Optionally check SET variables for validity gen_evout.F Optionally create extra event output gen_exit.F Optionally do extra things at end of run gen_info.F Optionally produce diagnositcs for the GENINFO command gen_ffkey.F Optionally declare arrays for use in FFREAD CARD files gen_hbook.F Optionally book and fill special HBOOK objects
Each GMC package also contains a little file called info which establishes the dependencies between packages. The info file need only contain 3 lines. As an example, here is the info file for the disNG generator:
set MAKELIB = yes set MAKEEXEC = yes set NEEDPACKAGES = ( radgen pepsi4 )The first two lines determine whether this package (disNG) creates a library and/or an executable GMC program. The last line indicates which other GMC packages it depends on (i.e. those which the Makefiles need to link in). gmc_disNG needs packge RADGEN for QED radiation, and package PEPSI4 for spin-depedent generation of the struck quark and target remnant. It also needs the Lund JETSET library for fragmentation, as do many other GMC programs. But the Lund packages JETSET and PYTHIA are now bundled in a common library that is part of all recent CERN releases. This library is used so often in the GMC suite hat it is automatically linked in with all generators. Not all generators use it ... but no harm in a spurious -l argument on the loader line. :-)
Let's assume that you have release 20 of the HERMES software installed in /hermes/r20. GMC is then housed in the subdirectory /hermes/r20/gmc, and the source code is in the directory src below that. The organization of the src tree reflects the package structure of GMC. Here is a partial snapshot of src:
aroma./ include.aroma/ mc/ aroma_lib/ include.dvcs/ mc_adamo/ disNG/ include.gmc/ mc_commands/ disNG_lib/ include.gmc_lund/ mc_ddl/ dvcs/ include.gmc_pythia6/ mc_kinema/ gmc/ include.mc/ mc_util/ gmc_commands/ include.mc_ddl/ pepsi4/ gmc_lund/ include.pepsi4/ pepsi4_lib/ gmc_pythia6/ include.radgen/ radgen/ gmc_util/This snapshot contains 8 packages: aroma, disNG, dvcs, gmc, mc, pepsi4, and radgen. The core packages mc and gmc are not really packages: they contain the code for GMC's core libraries which are automatically linked in with every package. The main program, e.g., is found in src/gmc/gmc_main.F.
To decipher which other packages are present in the listing, here are the naming rules for the source directories:
Let me now introduce you to some of the standard physics packages used by the GMC suite:
These packages all have their own manuals, and you should read them if you're going to be doing simulations with them. The best place to go is the List of Monte Carlo Programs at DESY, an extremely useful page which provides links to the homesites of all standard Monte Carlo packages for high-energy lepton scattering.
Most of the GMC programs are front-ends to these standard MC packages, but some of them are homegrown. Here are the principal programs of the GMC suite:
The sequence for running any GMC program is always the same:
And here is how you do it. We'll use gmc_disNG for our example:
Finally, GMC programs can also be run in non-interactive batch mode. You simply type all your commands into a kumac, and supply its name to GMC on the command line:
gmc_disNG -b batch_file.kumac
The SET, NAME, and MKLOGON commands
These three commands are how you adjust all parameters in a GMC program. Since they're so important, let's look at them in more detail:
Go ahead and start gmc_disNG again. At the prompt, type set. You will get an intimidating list of all SET parameters, their current values, their default values, and some information about them. Here are some features of the SET command and the parameters it controls:
The NAME command controls input and output filenames. Different programs require different input files, and so the list will, in general, be different from program to program. Some files, however, are needed by all programs.
Each input or output file is assigned a file key, which is simply a 4-character identifier. The most important example is EVEN, the file key for the primary ADAMO output file. Associated with each file key is the filename, the logical unit number on which the file will be opened, the ADAMO or DAD driver that will be used to access it, and a help string describing the file's function. All this is controllled by the NAME command.
Obviously you don't want to type in all the SET and NAME commands by hand every time you run the Monte Carlo. The easy thing to do is to bundle all of your settings into a kumac script, and execute that whenever you run GMC. The MKLOGON command provides you with a template script that you can modify for exactly this purpose.
To produce one, start gmc_disNG again, type mklogon at the prompt, then exit. You will be informed that a file GMCLOGON.KUMAC has been written. This file contains all set and name commands along with their default values. The normal way to run GMC is to produce such a file, copy it to something like myrun.kumac and adjust all the parameters once and for all. When you run GMC, you can now type exec myrun and all your settings will be invoked.
You can also hand your kumac to GMC in batch mode with the -b option. For this purpose, a better kumac can be obtained with mklogon b. This one also contains commands at the end to initialize, generate events, and exit. Please have a look at this file, I trust its content will be clear.
One useful thing that these MKLOGON kumac files do is set the run number and adjust all the output filenames accordingly. The run number is accessed by the SET parameter runno. It is one of the most important parameters, as it determines the starting seeds for the random number generator. To accumulate statistics, one typically makes many runs of a fixed event size, changing the run number each time. GMC uses CERN's excellent RANLUX generator and so run numbers of arbitrarily large magnitude can be used.
In real life we can only determine the probable identity of a particle (pion? kaon? electron?) using the responses of our PID detectors. But in the world of Monte Carlo we know everything! The Monte Carlo packages we use at HERMES record the actual identity of particles using either the GEANT or Lund particle code schemes. The GEANT scheme contains about 50 codes, while the Lund scheme contains many more. The reason is simple. The GEANT package tracks particles through the materials of a detector ... and it therefore has no interest in a particle such as the rho meson which decays so fast (within about 1 fm) that no detector can observe its brief career as a rho. Detectors such as ours can of course deduce the existence of a rho meson by measuring the invariant mass of the pions to which it decays ... but the rho itself is not observed directly. The Lund programs, however, are not detector tracking packages but physics generators and they are very interested in the rho. The Lund particle-code scheme contains codes for all manner of hard-scattering exotica including individual quarks, exchange bosons, colour-strings, and every hadronic resonance you can imagine.
You will typically find variables called iGType and iLType in GMC data files and analysis codes, referring respectively to the GEANT and Lund codes of the particle in question. You may also see such things as iLParent, indicating the Lund code for a particle's parent. If you are going to do any sort of Monte Carlo study, I strongly suggest that you print out the following particle code table and keep it with you at all times, coffee stains and all. It lists both GEANT and Lund codes. I created this table a long time ago, for my own convenience, and my printed copy now sports many coffee stains. :-)
One of the main things that we want out of our Monte Carlo is cross-sections. The Monte Carlo produces lots of events for us, thrown according to the cross-sections it knows. So the histograms we make from our simulated events will have the right shapes. But to obtain absolute cross-sections, we must know how to normalize our histograms so that they come out in absolute units. Further, to get even the shapes to come out right, some generators require that we apply event weights.
I'd like to explain some basic Monte Carlo principles first. The MC's job is to throw kinematic variables according to a known physics cross-section. Take the inclusive DIS xsec, for example, which is a function of two independent variables (Q2 and nu, or x and y, or x and Q2, etc...). To be specific, let's say our Monte Carlo throws in Q2 and nu --- these are then the generation variables. When the MC initializes, it first integrates the cross-section over a box corresponding to the generation range you have requested in Q2 and nu. This integral is the total cross-section inside your limits, so it has units of area. The ratio of the differential cross-section to this integral is thus a probability distribution that is dimensionless and normalized to 1. We'll call it P(Q2,nu).
So how do you generate random x values according to a given probability distribution P(x)? There are a number of methods:
In practice, Monte Carlo's often employ some hybrid of these methods. gmc_disNG is a perfect example. The inclusive cross-section is not a simple function, but it roughly goes as 1/Q4 and is roughly flat in nu. P(nu,Q2) = 1/Q4 is simple enough that a magic variable can be found to replace Q4. So disNG splits the different cross-section into two multiplicative pieces: the simple 1/Q4, and the complicated factor that's left over. It then uses magic-variable to throw the simple part, and assigns the left-over part to an event weight. The analyzer must therefore weight all her histograms with this factor to correct the thrown distribution up to the true cross-section. Other Monte Carlo packages avoid event weights entirely by combining the magic-variable and dart-board methods.
We can now deduce the steps that an analyzer must follow to generate absolutely-normalized cross-section histograms, in units of area. We'll use the symbol P(x,y) to refer to the dimensionless probability distribution that the MC is generating.
I hope that makes sense. For GMC, the Monte Carlo normalization rule is this:
Here's where to find those three important quantities in GMC's output:
Download: grab-ievgen
One last note about sumievgen: it is one number, it is the total number of generated events for the entire Monte Carlo sample you are processing. If you are producing histograms from the output of, say, 8 Monte Carlo runs, sumievgen is the sum over all 8 runs. In particular, you must never use the mcEvent_iEvGen entry on an event-by-event basis, only its sum. OK, 'nuff said. :-)
GMC uses the following unit system, inspired by GEANT and Lund:
The Cartesian coordinate system is exactly what you would expect:
The GMC source tree contains some ASCII help files that travel along with the distribution. They are located in /hermes/r??/gmc/help. Unfortunately, they are not 100% complete and they're not 100% up-to-date either :-/ (eventually, this manual will replace them entirely). But much of the information given here is available in those files so you might find them a useful reference if you're working offline. Also they tend to provide more technical detail (and so less pedagogy) than this manual. As you'll see, a few of this manual's sections refer directly to the help files for more info.
For reference, here are links to local copies of all the help files.
Following is a list of the commands available to all Monte Carlo programs. All of this help is available online, the commands are just listed here for convenience and to give you an overview of what's available. But I'll first provide some structure with a summary of the commands.
These commands were already covered above:
KEY C 'KEY of the name to change' D='?'
NAME C 'New filename' D='?'
Set or show defined filename keys and their current values.
NAME List all file keys and their current values
NAME ? List all file keys and their current values
NAME KEY List current values of file key KEY
NAME KEY FILENAME Change the filename for KEY to FILENAME
NRNDM1 C 'first random seed' D='-1' NRNDM2 C 'second random seed' D='0' Reset random generator seeds. If either of the given seed values NRNDM1,2 is negative, the seeds are reset to the values they had just before the most recent event. NOTE (GMC only): GMC now uses the RANLUX generator. In this generator, seed2 is almost always 0, or else a very small integer. If you use seed2 > 0, you will be in for a long wait ... Here's why: in RANLUX, the seeds approximately specify your position in the current sequence, which is roughly seed2 * 10^9 + seed1. When the seeds are reset, RANLUX starts back at the beginning (seed1,2) = (0,0) of the current sequence and goes forward to your requested position. So if you specify a big value for seed2, RANLUX will take a VERY long time to find it.
List all defined ADAMO tables.
Print format:
ID: the reference of that table
Count: number of rows in the table
LaSeNu: highest ID allocated
IniCrd: initial number of rows given in the call to CRETAB
MaxCrd: maximum number of rows the table can hold
Open: if the table is open
Division: ZEBRA division holding the table
List all defined ADAMO dataflows.
ROW I 'which row (not ID) to print (0=all)' D=0 Print table showing details of all the open GAFs.
ROW I 'which row (not ID) to print (0=all)' D=0 WHAT C 'which table to print (case sensitive)' Print contents of ADAMO table. If you print a single row, vertical mode is used. Remember that the row number and the ID number may be different.
WHAT C 'which dataflow to print (case sensitive)'
FULL C 'Full listing of all tables?' D='N'
Possible FULL values are:
Y
N
Print contents of ADAMO dataflow.
Either a list off all connected tables, or also a list of the contents
of all tables
WHAT C 'which table or dataflow to treat? (case sensitive)' Print relationships of a table or dataflow.
Initialize GENERATOR
NEVENTS I 'number of events to be generated' D=1
Generate events
NEVENTS = number of events to be generated
= 0 : infinite number (until time limit reached)
WHAT C 'parameter name' D=' '
VALUE C 'set value' D=' '
Set or show genSet and mcSet parameters
SET * Show status of all variables
SET ? Show list of all menus
SET MENU Show status of all variables in MENU
SET TABLE Show status of all variables in TABLE = mcSet|genSet
SET PAR Show status of parameter PAR
SET * * Set all parameters to their default values
SET MENU * Set all parameters in MENU to their default values
SET TABLE * Set all parameters in TABLE = mcSet|genSet to their defaults
SET PAR * Set parameter PAR to its default value
SET PAR VAL Set parameter PAR to value VAL
Some variables are checked, to see if the value you have supplied is
appropriate. If the new value is invalid, the parameter is not changed, and
sometimes detailed help will be provided about the parameter. Setting a
parameter INTENTIONALLY to something invalid is a good way to obtain this
information.
COPT C 'info option' D=' ' Show generator-specific event information. The options are generator-specific, if you supply an unrecognized option (such as '?') you will be given help.
OPTION C 'options' D=' '
FILE C 'filename for output hmclogon file' D='HMCLOGON.KUMAC'
Produce a template HMCLOGON.KUMAC file.
The file will contain all Set parameters, and appropriate values for them.
Possible OPTION values are (you can specify more than one) :
'P' Use present values of all mcSet variables rather than defaults
'B' Include extra lines at end of file suitable for batch generation
We learned above that all GMC input and output files are assigned a 4-character file key, and that the associated filenames and ADAMO drivers can be modified with the NAME command. Following is a list of all such keys.
Honestly, I have no idea what any of these do, but I'll list them anyway. :-) They probably just specify generator-specific input files. Typing NAME without an argument will give you a basic help string.
As was stressed earlier, the best way to set all GMC parameters for the generator of your choice is to first dump them all to a kumac script with the mklogon b command. The file will show all the default settings, plus a help string. We will now go through the available parameters. Those in the table mcSet are available to all generators, and are explained in this section. Those in the genSet table are generator-specific, but they tend to follow a common mold. In the next section, I'll present the genSet parameters for our standard generator, disNG.
Let's start with the basic parameters that were explained earlier.
Set RunNo [runno] : run number Set bStop YES : stop on error Set UseCards NO : read in FFREAD cards, from CARD file if it exists Set wOutput YES : write events into output file Set wHBOOK NO : write user-defined HBOOK objects to file Set UseSelector NO : apply selector, using selector file SELE if it existsLet's also get some useless parameters out of the way:
Set Generator DIS : select generator Set bValid YES : mcSet table on GAF is validThese variables are internal to the code. They'll be overwritten so don't bother changing them.
The next sets of parameters are all from menu BEAMVERTEX and control the beam and target specification. The particle types and energies are set with
Set TarA 1 : target atomic number Set TarZ 1 : target charge Set BeamParType POSI : beam particle type (POSI|ELEC|GAM|MUON) Set EneBeam 27.57 : beam energy (GeV)The polarization of either can in theory be longitudinal (L) or transverse (T) and take on any value. In practice, however, only longitudinal polarization at +100%, -100%, or 0 is supported by our present generators:
Set PBeam L : beam polarization type (T,L) Set PTarget L : targ polarization type (T,L) Set PBValue 1. : beam polarization value Set PTValue 1. : targ polarization valueEach DIS event is assigned a primary vertex: a randomly-generated location in space at which the primary beam-target interaction occurred. This vertex is thrown according to the longitudinal density-profile of the target and the transverse size of the beam.
Set VerLon DIST : type of longit vtx distrib (DIST|FLAT|GAUS|TRIA) Set VerTra GAUS : type of transv vtx distrib (FLAT|GAUS|TRIA) Set VerSizX 0. : width in x of vtx distrib (cm) Set VerSizY 0. : width in y of vtx distrib (cm) Set VerSizZ 40. : length in z of vtx distrib (cm)Options VerLon and VerTra set the type of vertex distribution to produce in the longitudinal (z axis) and transverse (x,y axes) direction:
Set VerPosX 0. : x-position of vtx (cm) Set VerPosY 0. : y-position of vtx (cm) Set VerPosZ 0. : z-position of vtx (cm) Set BeamSlopeX 0. : x-slope of beam (rad) Set BeamSlopeY 0. : y-slope of beam (rad)
The last parameter in menu BEAMVERTEX is a bit technical:
Set VerPrecision 0.01 : min separation for new vtx (cm)Amongst the ADAMO tables of the GMC output file is table mcVert. It contains the x,y,z coordinates of every space point generated in the event. This not only includes the primary vertex, but also the vertices at which unstable particles decayed to produce yet more particles. The VerPrecision parameter determines how far away these secondary vertices have to be (from the primary vertex or from each other) to have them stored as separate entries in mcVert.
Next, let's tackle cuts (all parameters in menu CUTS, surprise!). If an event fails any of these cuts, GMC does not write it to disk and goes back for another one. The cuts come in two varieties. First, we have vertex cuts which allow us to restrict the kinematics of each event. The are turned on and off as a set with the boolean CutVertex parameter:
Set CutVertex YES : apply cuts on vertex kinematics Set Q2Min 0.5 : min Q2 Set Q2Max 20. : max Q2 Set NuMin 0. : min nu (energy transfer) Set NuMax 27.57 : max nu (energy transfer) Set W2Min 1.5 : min W2 Set W2Max 500. : max W2 Set XMin 0. : min x Bjorken Set XMax 1. : max x Bjorken Set YMin 0. : min y (nu/Ebeam) Set YMax 1. : max y (nu/Ebeam)Second, we have track cuts. These are cuts on the direction and momentum of the scattered beam lepton. They are turned on and off as a set with the CutScat parameter:
Set CutScat YES : apply track cuts to scat lepton Set Pmin 0. : min momentum Set Pmax 27.57 : max momentum Set TheMin 0.037 : min theta Set TheMax 0.3 : max theta Set TheXMin 0.0 : min theta_x Set TheXMax 0.18 : max theta_x Set TheYMin 0.037 : min theta_y Set TheYMax 0.15 : max theta_y
Finally, the following parameters determine how much information GMC spits out to the screen. These variables are in menu PRINTING:
Set iPrint 100 : info line every iPrint events Set ListInit NO : list initialization steps Set ListEvent NO : list event processing steps Set PriInit NO : print detailed initialization info Set PriEvent NO : print detailed event infoIf you turn on all four List and Pri options, you'll get a ton of output ... which can be useful for debugging.
The following parameters are specific to the disNG generator, which combines the polarized-DIS generator PEPSI4 with the QED radiative corrections package RADGEN (and adds in a few tricks of its own :-)). However, many of the parameters described here can also be found in other DIS packages.
This subsection also gives me the opportunity to explain in a bit more detail how gmc_disNG works. As briefly described in the package list earlier, disNG throws the inclusive part of the cross-section all on its own (LEPTO/PEPSI are not consulted). There are two reasons for this:
First let's present the parameters that control disNG's simulation of the inclusive cross-section:
Set GenKine 1 : throw kinematics flat in: 1 Nu,log(Q2), 2 Nu,Q2 Set FStruct ALLM : structure function parametrization Set R 1990 : param. of R=sL/sT (1990, 1998 or 0 for R=0) Set PA1asym PDF : parametrization of asymmetry A1(x,Q2)For the last 3 variables, various parametrizations of F2, R, and A1 are available. A list of the available parametrizations can be obtained them by setting any of the options to something invalid, like '?'. For FStruct and PA1asym, the value 'PDF' indicates that the quantity should be computed from the selected PDF set, in the manner of LEPTO and PEPSI.
If you read the LEPTO or PEPSI manuals, you'll see that those programs support numerous parameters. They are stored in the arrays LST, PARL, and CUT. The following options directly set the most important of these parameters:
Set PartonSet 118 : PDF set for PEPSI/LUND (LST(15,16)) Set MaxSeaFl 3 : heaviest sea flav (LST(12)) Set MaxFusFl 4 : heaviest boson-g fusion flav (LST(13)) Set Shower 1 : parton showers (LST(8)) Set QTrace YES : turn on JETSET quark tracing (T|F:MSTU(16)=2|1) Set LepQ2Min 0.5 : Q2 minimum for PEPSI/LEPTO (CUT(5)) Set LepW2Min 4.0 : W2 low cut for PEPSI/LEPTO (CUT(7))The PartonSet parameter controls the all-important selection of a PDF set. A great many are available ... you can discover what they are with set PartonSet ?. The LepQ2Min and LepW2Min are limits below which PEPSI will not be called at all. Reason: it'll crash. If an event is generated with true kinematics below these Q2 and W2 limits (e.g. by RADGEN), a 'lowe' quasi-elastic event will be thrown. Finally, you should be aware that parton showering is not supported when polarized beams or targets are in use in PEPSI4.
The next parameters control fragmentation. After disNG throws the inclusive kinematics of the primary vertex, and PEPSI selects the flavour of the struck quark, the Lund-fragmentation program JETSET is summoned to generate final-state hadrons from the debris of the target. If you're only interested in inclusive stuff, the entire fragmentation process can be bypassed by turning off GenHadrons (saves some time):
Set GenHadrons YES : generate hadrons with Lund program
Further control is available for unstable particles. By default, Lund decays all unstable particles, even if the are very long-lived. Those long-lived, weakly-decaying particles fall roughly into two camps. (1) pi+, pi-, K+, K-, and K0-long have really long lifetimes, so it is unlikely they will decay within an experimental detector. (2) K0-short and the Hyperons (sounds like a band :-)) are moderately long-lived and typically decay after a few centimeters, at HERMES energies. You can enable/suppress the decay of these particle classes with the following parameters:
Set DecayPiK NO : Have Lund decay charged pi,K and K0_L? Set DecayLamKs YES : Have Lund decay Lambda,Sigma,Xi,Omega,K0_S?Of course the decay vertices of all unstable particles are recorded in the output file ... so if you're careful to cut on vertex positions in your analysis file, you can decay everything. The point of turning off DecayPiK by default is that this most closely produces the tracks your detector see, without the need for secondary-vertex cuts.
The following parameters control the generation of QED radiation (the bane of all electron-scattering experiments ;-)):
Set GenRad NO : radiative effects (NO,YES,POL) Set GenLUT NO : generate LUT for pol. rad. corr. Set UseLUT YES : use LUT for pol. rad. corr.The GenRad options bear explaning:
Finally, gmc_disNG adds one parameter to the PRINTING menu which tells PEPSI to print out its highly-technical QCD-Weights table:
Set PriQCDW NO : print prob for q, qg, qqg events after init
As you learned in the previous section, the SET parameters allow you to place cuts on the kinematics of the scattered beam lepton in each event. However they don't allow you to cut on the kinematics of any hadrons produced by fragmentation. Naturally, you can impose such cuts in your analysis program. But this is highly inefficient if you are studying a rare event topology, e.g. D-meson production near the charm threshold: since the cross-section for this process is small, GMC will fill up gigabytes of disk space with events that have no chance of making it past your analysis cuts. In cases like this, you want to use a selector file.
Selector files allow you to place rather complex restrictions on your events. For example, you can request 2 positively-charged pions and 1 negatively-charged kaon, all within some angle and momentum range, and together reconstructing to some invariant mass interval. The event will not be written to disk if it does not meet your criteria.
An extensive and complete description of the selector-file syntax is found in the GMC Help File 6:Event_Selector.
Following is a description of all ADAMO tables used by GMC. They are the same for every generator, and their structure is described by the DDL file MCARLO.ddl. All tables are stored in the primary output file (key EVEN) with one event per record.
mcBeam_EBe REAL : the beam energy (GeV) mcBeam_XVx REAL : the x-position of the primary vertex (cm) mcBeam_YVx REAL : the y-position of the primary vertex (cm) mcBeam_ZVx REAL : the z-position of the primary vertex (cm) mcBeam_XSl REAL : the x-slope of the beam (not used at present) mcBeam_YSl REAL : the y-slope of the beam (not used at present)The x,y,z coordinates of the primary vertex also appear as the first row in the mcVert table.
mcVert_X REAL : the x-position of the point (cm) mcVert_Y REAL : the y-position of the point (cm) mcVert_Z REAL : the z-position of the point (cm)
mcEvent_cType CHA4 : a 4-character description of the event typecType is typically used merely to identify the generator (so all AROMA events have mcEvent_cType = 'AROM', etc ...) However, several of the generators modify the last character if QED radiation was generated in the event. Thus, all disNG-generated events are called 'DIS', but when QED radiation occurs mcEvent_cType is set to 'DISR'.
mcEvent_iEvent INTE : the event number mcEvent_nRndm1 INTE : the 1st seed, from the beginning of the event mcEvent_nRndm2 INTE : the 2nd seed, from the beginning of the eventThe random number seeds are recorded at the start of event generation. They are made available so that you can duplicate an event later, by reseting the random number sequence to the starting seeds using the RESET command.
mcEvent_iEvGen INTE : the number of generated eventsiEvGen is the total number of events which were generated before the current 'good' event was found. It is used to normalize the Monte Carlo results: the MC output must be divided by the sum of all iEvGen entries. Please note: iEvGen is never used on an event-by-event basis, only its sum over all events is useful.
mcEvent_process INTE : a process codeThis code is intended to indicate the specific hard-scattering process which occurred during the event. For LEPTO-based generators, the code comes from LST(24); for PYTHIA-based generators, it is MSTI(1). You must consult those packages' manuals to discover the meaning of the process codes.
mcEvent_nucleon INTE : struck nucleon (1=p, 2=n)For an A > 1 target, this is the nucleon which was actually struck during this event.
mcEvent_qflavour INTE : struck quark flavourSimilarly, qflavour is the identity of the parton which participated in the hard scattering. The Lund particle code is used (i.e. 1=d, 2=u, 3=s, 4=c, 0=g, -1=dbar, -2=ubar, ...)
mcEvent_remnant INTE : remnant codeIf your generator produces a target remnant, this is its Lund particle code.
mcEvent_weight REAL : Monte Carlo event weightThis weight should be applied, on an event-by-event basis, to all histograms made from the Monte Carlo. The normalization rule is that if these histograms are then divided by the sum of mcEvent_iEvGen for the run, and multiplied by MCEXTRAWEIGHT, the result comes out in MICROBARNS. (Both the sum of iEvGen and the MCEXTRAWEIGHT factor are recorded in the gmc.norm.kumac output file).
mcEvent_X REAL : x-Bjorken mcEvent_Y REAL : y = nu/Ebeam mcEvent_Nu REAL : nu mcEvent_Q2 REAL : Q^2 mcEvent_W2 REAL : inv mass of hadronic final state, W^2 mcEvent_EP REAL : E' = energy of scattered electron mcEvent_The REAL : polar angle of scattered electron mcEvent_Phi REAL : azimuthal angle of scattered electronAll of these variables are straightforward, and simply describe the kinematics of the event vertex. Note: If radiative corrections are in use, these are the kinematics as they would be measured by a perfect detector. In other words, they include the effect of any radiation. The actual kinematics at the hard scattering vertex are recorded in the 'True' variables of table mcRadCor.
mcEvent_PolB REAL : beam polarization for this event mcEvent_PolT REAL : target polarization for this eventThese quantities are typically constant throughout a run, but are very useful when forming asymmetries in your analysis code using a mixture of runs.
mcTrack_cType CHA4 : 4-character description of track typeThis type designator is quite important. The recognized GMC cTypes are as follows:
mcTrack_iCharge INTE : particle charge mcTrack_iGType INTE : GEANT particle code mcTrack_iLType INTE : Lund particle codeThese last two entries identify the particle (pi0, K+, etc ...) using the GEANT and Lund numbering schemes respectively (see the particle code discussion above).
mcTrack_The REAL : polar angle of particle track mcTrack_Phi REAL : azimuthal angle of particle track mcTrack_Px REAL : x-component of particle momentum mcTrack_Py REAL : y-component of particle momentum mcTrack_Pz REAL : z-component of particle momentum mcTrack_E REAL : particle energy mcTrack_M REAL : particle massAll of these quantities denote the particle's initial kinematics (i.e. at the point where it was produced).
mcTrack_Parent REL : pointer to parent-track row in mcTrackThe Parent entry is a link back to another row in the mcTrack table. Parent links make it possible to reconstruct the entire history of an event.
mcTrack_pT REAL : transverse momentum (relative to q-vector) mcTrack_xF REAL : x-Feynman mcTrack_z REAL : z = Ptarg.Phadron/Ptarg.q mcTrack_rap REAL : rapidity, in gamma*-P CM frame mcTrack_raplab REAL : rapidity, in e-P CM frame mcTrack_PhiL REAL : azimuthal angle around q-vec rel to lep scat plane mcTrack_rank REAL : rank in frag order (0,1=struck_q,remnant)All of these variables can be calculated from the other information in the mcTrack and mcEvent tables, so they are 'derivative' = extraneous entries, in principle. They are included for convenience ... but also because the calculation of these quantities in an asymmetric collider environment is non-trivial! The quantities pT, xF, z, rap, and raplab are all familiar. PhiL is the Amsterdam-convention azimuthal angle needed for transversity and related studies. mcTrack_Rank, however, deserves some comment. It is a phenomenological concept, based on the hypothesis that the order in which primary hadrons are produced from the Lund string-fragmentation model is meaningful. A rank of 0 means that the hadron in question contains the struck quark, possibly via a decay chain. Conversely, a rank of 1 means that it contains the target remnant, with the same caveat. An example: suppose the initial series of string breaks produces a rho, and that this rho contains the struck quark (i.e. the rho is at the struck-quark end of the color string that is formed between the struck quark and the target remnant.) In this case, not only the rho but also the pions into which it decays will get a rank of 0. To learn more about this sort of 'quark tracing' in JETSET, consult the PYTHIA manual and its description of the option MSTU(16). There are a number of cases where ranking in this simple fashion is not possible, most notably when more than one string is formed (e.g. a NLO event such as photon-gluon fusion). In these cases, a negative rank is assigned. Also note that the calculation of ranks will be disabled entirely if the option QTrace (available in all JETSET-based generators) is turned off. Finally, please note that this set of variables is only meaningful for final-state hadrons from the fragmentation process. Calculations are performed for other tracks (like the scattered beam lepton or the struck quark) but they generally yield pretty ridiciulous values that should be ignored.
mcTrack_startVert REL : pointer to mcVert, gives particle production point mcTrack_stopVert REL : pointer to mcVert, gives particle destructon point mcTrack_magVert REL : pointer to mcVert, gives point where pcle left magnetic fieldThese three pointers to mcVert are initialized to INULL. If not null, they indicate three important space points on the track. startVert is the point at which the particle was produced. stopVert is the point at which the particle was destroyed (decayed, converted to something else, etc ...) A stable particle is left with stopVert = INULL in GMC. When tracked by hmc, its stopVert is set to the point at which tracking stopped (i.e. just behind the spectrometer). Finally, magVert is the point at which the particle left the magnetic field (naturally, this is only determined by HMC). If magVert = INULL, the particle did not make it through the magnet. Also note: using Pmagnet, magVert, and stopVert, one can obtain a description of the back partial track.
mcStrFu_KF INTE : Lund particle code used in PDF callThis particle code is almost always 2212, indicating that PDF distributions for the proton have been requested.
mcStrFu_x REAL : x-Bjorken value used in PDF call mcStrFu_Q2 REAL : Q^2 value used in PDF callThese variables record the actual kinematics used in the call to the PDF routine. Very occasionally, the first PDF call (which is used to fill this table) is done at x and Q2 values which do not match those in mcEvent. Consequently we record the kinematics of the call here explicitly.
mcStrFu_d REAL : d(x,Q2) quark density mcStrFu_u REAL : u(x,Q2) quark density mcStrFu_s REAL : s(x,Q2) quark density mcStrFu_c REAL : c(x,Q2) quark density mcStrFu_b REAL : b(x,Q2) quark density mcStrFu_t REAL : t(x,Q2) quark density mcStrFu_g REAL : G(x,Q2) gluon density mcStrFu_dbar REAL : dbar(x,Q2) anti-quark density mcStrFu_ubar REAL : ubar(x,Q2) anti-quark density mcStrFu_sbar REAL : sbar(x,Q2) anti-quark density mcStrFu_cbar REAL : cbar(x,Q2) anti-quark density mcStrFu_bbar REAL : bbar(x,Q2) anti-quark density mcStrFu_tbar REAL : tbar(x,Q2) anti-quark densityThese are the unpolarized PDF's.
mcStrFu_dd REAL : d(x,Q2) quark polarization density mcStrFu_du REAL : u(x,Q2) quark polarization density mcStrFu_ds REAL : s(x,Q2) quark polarization density mcStrFu_dc REAL : c(x,Q2) quark polarization density mcStrFu_db REAL : b(x,Q2) quark polarization density mcStrFu_dt REAL : t(x,Q2) quark polarization density mcStrFu_dg REAL : G(x,Q2) gluon polarization density mcStrFu_ddbar REAL : dbar(x,Q2) anti-quark polarization density mcStrFu_dubar REAL : ubar(x,Q2) anti-quark polarization density mcStrFu_dsbar REAL : sbar(x,Q2) anti-quark polarization density mcStrFu_dcbar REAL : cbar(x,Q2) anti-quark polarization density mcStrFu_dbbar REAL : bbar(x,Q2) anti-quark polarization density mcStrFu_dtbar REAL : tbar(x,Q2) anti-quark polarization densityThese are the polarized PDF's, and are all zero if you are working with an unpolarized PDF set. (Only the PEPSI package currently provides polarized PDF sets).
mcRadCor_cType CHA4 : type of event at true vertexRADGEN may decide that the generated event actually came from the radiative tail of the quasielastic or elastic scattering peak. cType records this information:
mcRadCor_XTrue REAL : true x-Bjorken seen by target nucleon mcRadCor_YTrue REAL : true y = nu/Ebeam seen by target nucleon mcRadCor_NuTrue REAL : true nu = E-E'-EBrems seen by target nucleon mcRadCor_Q2True REAL : true Q^2 seen by target nucleon mcRadCor_W2True REAL : true W^2 seen by target nucleonThese variables record the TRUE kinematics at the hard scattering vertex.
mcRadCor_EBrems REAL : energy of radiative photon mcRadCor_ThetaBrems REAL : theta of radiative photon (Tsai system) mcRadCor_PhiBrems REAL : phi of radiative photon (Tsai system)These variables record the kinematics of any radiative photon which was produced. EBrems = 0 indicates that NO real photon was generated.
mcRadCor_SigCor REAL : correction factor to be applied to cross-section mcRadCor_SigCorErr REAL : error on SigCormcRadCor_SigCor is a cross-section correction for radiative effects. It is internally applied to mcEvent_weight when QED radiation is turned on.
mcRadCor_TailIne REAL : inelastic radiative tail mcRadCor_TailEla REAL : quasielastic radiative tail mcRadCor_TailCoh REAL : coherent (elastic) radiative tail mcRadCor_Vacuum REAL : vacuum term of virtual radcor factor mcRadCor_Vertex REAL : vertex correction mcRadCor_Small REAL : small radiative correction (?) mcRadCor_RedFac REAL : radiative reduction factor (?)These are the components of the correction factor SigCor:
SigCor = RedFac*(1+Vacuum+Vertex+Small)+TailIne+TailEla+TailCoh
mcRadCor_SigRad REAL : radiatively corrected cross-sectionNo one uses this, or has bothered to figure out what units it is in. :-|
mcUser_Name CH16 : name of user variable mcUser_Val REAL : value of user variable
mcSetPar_Name CH16 : Set parameter name mcSetPar_Value CH16 : Set parameter value
You now know how to run GMC to produce ADAMO files of simulated events. But how do you analyze them? Clearly you need some tool to extract the information you need from the ADAMO files and turn it into something PAW can read, like an HBOOK file with ntuples or histograms. Below are three tools for this purpose, going from easiest to hardest. By 'easy' and 'hard', what I really mean is how much you have to know about ADAMO ... and inversely, how powerful the tool is. If you actually worked through the previous Mission, you are such an ADAMO expert that you don't even need a tool. ;-) But even if you only read through the ADAMO section of the Reconnaissance mission, we can already get you writing ntuples of pretty decent complexity.
The Pink Browser allows you to examine the contents of any ADAMO file in a user-friendly graphical format. It can't do any analysis for you, but it's extremely useful for learning what's inside an ADAMO file. Click here to see the description of how it works from the ADAMO tutorial. If you want to know more, check out the official PinK Pages (hehe, MysT ...).
hexe, on the other hand, is a command-line utility that can yank data out of any ADAMO file and send it to screen (i.e. to UNIX STDOUT). hexe does other things too, like filtering and merging, and you should know about it. Check out the hexe section of the ADAMO tutorial. The extract-to-screen allows you to generate simple row-wise ntuples in ASCII form, which can then be read into PAW using nt/read. But if that's what you're after, better go to the next section ...
makent: The Ntuple-Writer for the Whole Family
Combining the power of hexe, hister, and the awesome perl scripting language, makent allows you to create row-wise ntuples of significant complexity from any HERMES ADAMO file using only a text file to define the ntuple. makent is now part of hister, so it should be available in the bin directory of your software release (/hermes/r??/bin or whatever).
All you need to know are: the variables available in your DDL file (only basic DDL-reading required here), and makent's simple syntax. makent's documentation comes in two forms:
makent -help explains command-line options
makent -example provides a quick-reference example of the
ntuple-definition file you have to write
The makent script is great for doing studies, but it does have two limitations:
makent: Examples and Exercises
Here are some examples of analysis tasks that can be accomplished with makent. Each example page starts with a 'Goal', and then presents a possible way of achieving it. The first example page goes into explicit detail on every step of the analysis, so you should read through that one first and try it out. After that, you can use the other examples as exercises: take a shot at the analysis goal, then check out the proposed solutions.
Example 1 Find the inclusive DIS yield at HERMES in 100 pb-1
Example 2 Find the semi-inclusive DIS yields at HERMES in 100 pb-1
Hanna is a code framework that greatly facilitates the processing of any HERMES ADAMO file. Writing a Hanna analysis code is very similar to writing a GMC generator: Hanna/GMC provides the engine; what you have to write are a number of user routines that are called by the engine.
The Hanna Page provides complete documentation of the library. One of Hanna's main goals is to permit the seamless analysis of any HERMES data file, and that includes lots of stuff that has nothing to do with Monte Carlo. As a rule of thumb: ignore anything you read containing the words 'burst' or 'slow control' ... those are data-only concepts, but dealing with them is much of what Hanna does. Next, you should know that native-Hanna only understands user routines written in C. To learn about the routines you have to write, go to the first link 'The Hanna frame' from the Hanna homepage and then scroll down to the section 'Your Analysis Code: User funtions'. But don't despair if you're a Fortran person. A Fortran frontend to Hanna is available. It's called Mainframe, and it's linked right off the Hanna mainpage. The Mainframe routines are bundled in with the F77 example codes supplied below, so if you start with those you don't have to download anything.
Now some example codes. The executables they produce are all called frame.
First, we have a simple Hanna code to write a row-wise ntuple. This one is track-level, meaning that each ntuple record corresponds to one particle track of interest (pions, kaons, electrons, etc ...). Unpack the tar file, then read the README, it will tell you how to proceed. As it is row-wise, this is a simple ntuple. But being simple, it's a good example code with which to start building your own.
Download: frame-gmc-rwn.tar.gz (F77)
The second example is not so simple, and produces a large column-wise ntuple that preserves virtually every bit of information in the GMC file being processed. This is an event-level ntuple, meaning one record per event. But thanks to HBOOK's column-wise ntuple facility, we can store track-level arrays within each such record, so all tracks are recorded too. Pretty much everything's recorded, in fact.
Download: frame-gmc.tar.gz (F77)
Rather than being a good example to start from, this is a good code to produce standard ntuples for you. Without even looking at the code, you can process your GMC files through it and get comprehensive ntuples whose structure closely mimics that of the original ADAMO files.To gain intuition, it is often useful to look at your generated events in a graphical format. For this purpose, a special package called HMC (originally, "HERMES Monte Carlo") has been included with GMC. This program is not a physics generator, but rather a GEANT-based detector simulation. A very simple detector has been defined, mostly to set some sort of scale for your event displays.
HMC reads a GMC file as input, then uses GEANT to track all the generated particles through a simple detector model.
Suppose you have made a GMC file called gmc.devents. To view the events with HMC, here's what you do. First start HMC by typing hmc. When prompted for a workstation-type, hit Return (i.e. choose the default option '1') to get a graphical X-window. Then type this at the HMC> prompt:
name EVIN gmc.devents : then EVIN file key sets your GMC input file
: (note: gmc.devents is the default name)
init : initialize HMC
ev 1 : read in one event
view 5 : view your event using predefined view #5
ev 1 ; view : read in the next event and view in the same way
exit : leave HMC
The key command here is VIEW, which draws the detector and the generated tracks. Type help view to discover all the options. You will see that there are two basic ways to view the current event: (1) select a predefined view number (e.g. view 4, as shown in the example above) (2) construct the view yourself (e.g. view ENTIRE 3pch to view the Entire detector in 3-D, in colour, by projection, and with attached header text). GEANT is doing all the drawing work here, of course. But you might find some nice enhancements ... e.g. check out the command HMC/PSTYLE which allows you to change the drawing style (colour, line style, and line width) for individual particle types. You can even turn off the drawing of certain particle types entirely. This can be quite helpful for picking out the particles you're interested in from the mess that's produced in a high-energy DIS event!
Several new SET options have been included with HMC to adjust the way events are tracked and drawn. They are explained in detail below. But first, we need to understand the simple detector-geometry that's been defined in HMC ...
To set the scale for your event displays, a very-simple detector has been defined in HMC. If you'd like to play with it, the GEANT code for this detector is housed in the subroutine gmc/src/hmc_geom/init_geom.F of your GMC installation.
The simple detector consists of 5 cylindrical volumes:
| Volume | Description | Inner Radius (cm) | Outer Radius (cm) | Half-length (cm) | Material | Visible |
|---|---|---|---|---|---|---|
| S... | supervolume | 0 | 450 | 550 | air | no |
| CALO | barrel calorimeter | 300 | 400 | 500 | lead glass | yes |
| CALE | endcap calorimeter | 0 | 300 | 50 | lead glass | yes |
| VRTX | vertex detector | 13.2 | 13.1 | 150 | silicon | yes |
| MVTX | microvertex volume | 0 | 1 | 1 | vacuum | yes |
By default, HMC will track particles through the indicated detector materials, with the attendant multiple scattering and generation of secondary particles. But if you type set AllVac yes, all materials will be set to vacuum. Generation of secondary particles can also be suppressed with set TraSec no.
The 'microvertex volume' MVTX deserves some comment. It is not a real volume (it's filled with vacuum) ... it's only purpose is to allow tracks to be stopped very near the interaction point (IP) for drawing convenience. To be precise: the VIEW command draws the names of each particle next to its track. But the particle names are always drawn at the track's stopping-point. If you want to zoom in on the tiny vertex displacements involved in, e.g. charmed-meson decay, and still see the particle names, you have to stop all the tracks very close to the IP. Setting the SET parameter DrawMicro to YES activates this mode. You then use the command VIEW M to display the tracks within the tiny MVTX volume, so you can see the displaced vertices. (IN THEORY ... I still haven't managed to see any D-decay vertices ... :-/)
Normally, HMC processes GMC-generated events from the external file attached to key EVIN. This behaviour is activated by the default setting
set Generator EXT : read events from external GMC file with key EVIN
But HMC has its own little background generator as well. This simple generator does nothing but throw particles of a given type within a kinematic box in momentum, theta, and phi. To activate the background detector, type this within HMC:
set Generator BACK : generate 'background' tracks
You the select the particle type and kinematic limits for your background
tracks with these SET options:
set BacType 2 : select GEANT particle type 2 = positron
set PMin 1. : set minimum momentum for background tracks
set PMax 250. : set maximum momentum for background tracks
set TheMin 0. : set minimum polar angle for background tracks
set TheMax 3.15 : set maximum polar angle for background tracks
set PhiMin 0. : set minimum azimuthal angle for background tracks
set PhiMax 6.30 : set maximum azimuthal angle for background tracks
Finally, you set the number of background tracks to generate per event
with the BacNum option:
set BacNum 1 : number of background tracks to throw per event
If you have a serious detector model coded in, the background generator can be a useful tool. But with the toy model we have currently, it's not so interesting, except for debugging.
In the commands section of the GMC Manual above, you learned about commands in two KUIP menus: MC and GMC. All the MC commands are also available in HMC, but the GMC commands are not. Rather, we have a new command menu: HMC (suprise ... :-)). The standard GEANT menu of commands is also available. If you know something about GEANT, you can use these commands to alter the detector geometry, draw things in many ways, and generally modify the GEANT part of HMC to your heart's content. :-) I'll leave it to you to look at the online help for the GEANT commands.
Initialize detector Monte Carlo.
NEVENTS I 'number of events to be processed' D=1 Process NEVENTS events from input file EVIN. If NEVENTS is less than 1, process all events.
WHAT C 'parameter name' D=' '
VALUE C 'set value' D=' '
Set or show hmcSet and mcSet parameters.
SET * Show status of all variables
SET ? Show list of all menus
SET MENU Show status of all variables in MENU
SET TABLE Show status of all variables in TABLE = mcSet|hmcSet
SET PAR Show status of parameter PAR
SET * * Set all parameters to their default values
SET MENU * Set all parameters in MENU to their default values
SET TABLE * Set all parameters in TABLE = mcSet|hmcSet to their defaults
SET PAR * Set parameter PAR to its default value
SET PAR VAL Set parameter PAR to value VAL
Some variables are checked, to see if the value you have supplied is
appropriate. If the new value is invalid, the parameter is not changed, and
sometimes detailed help will be provided about the parameter. Setting a
parameter INTENTIONALLY to something invalid is a good way to obtain this
information.
COPT C 'info option' D=' ' Show generator-specific event information The options are generator-specific, if you supply an unrecognized option (such as '?') you will be given help.
OPTION C 'options' D=' '
FILE C 'filename for output hmclogon file' D='HMCLOGON.KUMAC'
Produce a template HMCLOGON.KUMAC file. The file will contain all Set
parameters, and appropriate values for them.
Possible OPTION values are (you can specify more than one) :
'P' Use present values of all set variables rather than defaults
'B' Include extra lines at end of file suitable for batch generation
Event I 'Number of the event to read in (0=next event)' D=0 Run I 'Number of the run to read in (0=any run)' D=0 Print C 'Print event?' D='Y' Read GMC event from input file EVIN. The principal purpose of this command is to allow graphical viewing of events, via the VIEW command. The data can also be printed to screen with PRINTTABLE.
OPTION C 'options' D=' ' Redo GEANT tracking of current event. The principal purpose of this command is to apply modified tracking and/or track-drawing parameters to the current event. Explanation: When an event's tracks are drawn (using MC/VIEW or GEANT/DRAWING/DXYZ), their tracjectories are taken from the spacepoints stored in the data-structure JXYZ. These spacepoints are stored (or not) during each step of GEANT's tracking phase, and they cannot be altered after tracking is completed. Thus, to alter the way the tracks of the *current* event are drawn, the event must be retracked, and then redisplayed. As a rule, all SET options in the menus TRACKING and DRAWING require a RETRACK before taking effect. By comparison, the options in menu DISPLAY take effect immediately (just run the VIEW command again), while changes to the options of menu GEANTINI require a complete restart of HMC. If OPTION=D is specified, the retracked event is immediately redrawn via the command 'VIEW SAME'. The command MC/REDRAW has been defined to do this very thing.
Run 'HMC/RETRACK D' to retrack the current event according to current TRACKING and DRAWING parameters, and redisplay it with 'VIEW SAME'. See 'HELP RETRACK' for further details.
WHAT C ' What to plot' D='SAME'
OPTIONS C ' Options T,S,F,O,3,...' D=' '
BANK_NO I ' Number of view bank to store plot' D=0
U1 R ' left corner of zoom rectangle' D=0
U2 R ' right corner of zoom rectangle' D=1
V1 R ' lower corner of zoom rectangle' D=0
V2 R ' upper corner of zoom rectangle' D=1
Draw Detector and tracks. List of what may be plotted:
Entire : entire detector
Vertex : vertex-detector region
Micro : micro-vertex region (do SET MICROVIEW YES and REDRAW to
stop tracks in micro region so particle names can be seen)
Same : same view as the last one with identical zoom etc,
but current event
1,2,.. : number of predefined viewbank to plot
1 = ENTIRE, top cut view, coloured (options THAC)
2 = ENTIRE, side cut view, coloured (options SHAC)
3 = ENTIRE, front proj view, coloured (options FHACP)
4 = ENTIRE, 3-D proj view, coloured (options 3HACP)
5 = ENTIRE, 3-D proj view, coloured, no subdiv (options 3HACPB)
6 = ENTIRE, 3-D proj view, black&wh (options 3HAP)
7 = ENTIRE, 3-D proj view, black&wh, no subdiv (options 3HAPB)
8 = MICRO, top cut view, coloured (options THAC)
9 = MICRO, side cut view, coloured (options SHAC)
10 = MICRO, front proj view, coloured (options FHACP)
11 = MICRO, 3-D proj view, coloured (options 3HACP)
12 = MICRO, 3-D proj view, coloured, no subdiv (options 3HACPB)
13 = MICRO, 3-D proj view, black&wh (options 3HAP)
14 = MICRO, 3-D proj view, black&wh, no subdiv (options 3HAPB)
List of options:
Kind of view:
T: top view
S: side view
F: front view
+: top +30 degree view
-: top -30 degree view
O: oblique (low angle) view
3: 3-dim view
How to plot:
P: projection (otherwise cut view)
C: coloured detector
What to plot:
N: no plot of tracks
H: plot header
X: draw x,y,z axes
A: draw axis scale
G: plot girl
M: plot man
B: don't draw any detector subdivisions
K: keep screen (dont clear screen before plottting)
Number of view bank to store plot:
0: dont store plot, just draw
1,2,...: Number of view bank to store plot
Zoom rectangle: relative factors which allow to draw a zoomed
part of the view
Zoom picture. Select two cursor coordinates with your mouse. The formed rectangle is the size of the zoomed picture. If the rectangle has zero size, the picture is reset to original size.
Move picture. The given curser position is the center of the moved picture.
OPTION C 'open/close postscript metafile' D='OPEN' Open/close postscript metafile hmc.ps.
TEXT C 'text (or type "LINE" for plotting line)' D='LINE' SIZE R 'character size (cm)' D=0.3 ANGLE R 'rotation angle (deg)' D=0 LWIDTH I 'line width' D=1 IOPT I 'centering option for text (-1,0,1)' D=0 Draw text (e.g. for labeling plots). The curser positions are stored in HMC.KUMAC text: position curser where text shall be drawn LINE: position curser where polyline shall be drawn until two same positions are given.
IGTYPE I 'GEANT particle code' D=0 COLO I 'Color index' D=0 MODE I 'Line style index' D=0 LWID I 'Line width' D=0 Adjust drawing style for individual particle types. IGTYPE = 0 means apply change to all particle types. COLO < 0 or MODE < 0 means do not draw this particle type at all. COLO, MODE, or LWID = 0 means revert to GEANT default style for given attribute.
KEY C 'What to print (MATE,MEDI,VOLU,PART,VOLMED,VOLSHAPE,VOLPOS,KINE,VERT)' D='*'
Print information stored in GEANT banks.
KEY = * print all
KEY = MATE material banks
= MEDI tracking media
= VOLU volume shapes
= PART particle definitions
= VOLMED volume - media - material relations
= VOLSHAPE volume shape and radiation lengths
= VOLPOS positions of all volumes
= KINE kinematics banks
= VERT vertex banks
By default, HMC produces no file output, its purpose is only to display graphics. However, if you set wOutput yes, you'll get an output file associated with the standard GMC file key EVEN. This file will contain all the tracks and vertices generated by GMC, plus any secondary tracks and vertices produced by HMC. The mcTrack varible mcTrack_cType will tell you the origin of each track: GMC-generated tracks always have cType in lowercase, while HMC-generated tracks have cType in uppercase.
With that introduction, here are the file keys known to HMC. First, we have the file keys that are special to HMC:
And then we have the file keys common to both GMC and HMC:
The SET parameters of menu mcSet are available to all Monte Carlo packages, including HMC. None of GMC's genSet variables are available, but HMC adds its own options in table hmcSet. Within this table, there are several submenus. It is important to know when the SET options of each submenu take effect: some take effect immediately, some require retracking of the current event, and some only take effect at INITialization time.
| SET menu | takes effect ... |
|---|---|
| PRINTING | on next EVENT command, if background generator is in use |
| GENERATE | on next EVENT command |
| DISPLAY | on next VIEW command (i.e. no need to RETRACK or REDRAW) |
| TRACKING | at tracking time (i.e. use RETRACK or REDRAW command to apply to current event) |
| DRAWING | at tracking time (i.e. use RETRACK or REDRAW command to apply to current event) |
| GEANTINI | only at INITialization (i.e. requires HMC restart) |
Set BacType 2 : GEANT code of backgnd particle Set BacNum 1 : number of backgnd particles per event
Set ColGamma 4 : HIGZ color index for gammas Set ColElec 2 : HIGZ color index for electrons Set ColNeut 1 : HIGZ color index for neutrals Set ColHad 2 : HIGZ color index for hadrons Set ColMuon 3 : HIGZ color index for muons Set ColGeantino 1 : HIGZ color index for geantinos Set ColCer 6 : HIGZ color index for cerenkov Set ColIon 5 : HIGZ color index for ions Set LTypGamma 3 : HIGZ line type for gammas Set LTypElec 1 : HIGZ line type for electrons Set LTypNeut 4 : HIGZ line type for neutrals Set LTypHad 1 : HIGZ line type for hadrons Set LTypMuon 2 : HIGZ line type for muons Set LTypGeantino 1 : HIGZ line type for geantinos Set LTypCer 3 : HIGZ line type for cerenkov Set LTypIon 1 : HIGZ line type for ions
Set EneMin 0.001 : min energy cut for all tracking media Set AllVac NO : set all detector materials to vacuum Set UseFluka NO : use FLUKA (not GHEISHA) for hadronic interactions
Set TraStopZ 9999. : |z|-position at which to stop particles Set TraStopR 9999. : cylindrical radius at which to stop particles Set PminPrim 0.8 : P cut for non-vertex primaries Set TraSec YES : track secondaries produced by GEANT Set TraENon NO : track scattered beam lepton as non-interacting e Set TrackLamKs YES : Have GEANT retrack Lamdba,Sigma,Xi,Omega,K0_S? Set TrackPiK YES : Have GEANT retrack charged pi,K, and K0_L? Set MorePrim YES : make non-vertex secondaries passing PminPrim primaries
Set DrawEneMin 0. : minimum energy for drawn tracks Set DrawReso 1. : minimal resolution of track drawing (cm) Set DrawSim NO : draw event simultaneously with processing Set DrawTracks YES : draw GEANT tracks for event Set DrawMicro NO : stop tracks outside microvtx volume MVTX (use with VIEW M) Set DrawNeut YES : draw neutral-particle tracks
Set PriBank NO : print geometry, etc ... banks Set ListTrack NO : list tracking steps (for debugging)
Technical Details for Developers
Gory details about the installation and building procedure:
Gory details for programmers, particularly those who want to write their own GMC simulation: