HOWTO run the semi-parametric Monte Carlo

From GlueXWiki
Jump to: navigation, search


The Hall-D software contains code for doing semi-parametric Monte Carlo simulations of the GlueX detector. The simulations are semi-parametric in the sense that they use resolution tables derived from full ab initio, hit-based, GEANT simulations with reconstruction. The resolutions are used to smear generated values and apply efficiency cuts. The resulting data can then be analyzed as though it were fully reconstructed GEANT data.

The system works by looking up efficiencies and resolutions tabulated in the form of 2-D histograms inside of ROOT files. Any DANA program can have the hdparsim plugin attached that provides alternate "factory"s (algorithms) for producing charged particles and photons. Configuration parameters control which algorithm is used and aspects of the algorithm (i.e. whether the efficiency cut is applied or not). Input files are in the same HDDM format used to feed generated events into the Hall-D GEANT simulation. However, in this case, the hdgeant simulator is bypassed and the generated events passed directly into the analysis program (i.e. one does not need to run hdgeant or mcsmear).

This method has the benefit of running much faster (>100 times) as opposed to doing the full simulation/reconstruction. It does, however, come with limitations:

  • The resolution tables take a little effort to reproduce and so are not always up to date with the code.
  • Resolutions are represented as simple Gaussians while the actual resolution functions have non-Gaussian tales.
  • Efficiencies are implemented by randomly throwing away some fraction of particles at a certain area of phase space. The efficiencies themselves are based on cuts using the thrown values and the number of σ's. Thus, more poorly reconstructed tracks are the ones to get thrown away in the full simulation/reconstruction. For the semi-parametric, the best fit tracks are just as likely to get dropped due to efficiency as the worst.
  • Effects due to multiple tracks including inefficiencies due to close tracks, and ghost tracks (ones arising from parts of two or more tracks, but not actually representing any of them) are not included.

Obtaining the source

The source code for hdparsim is kept in the Hall-D subversion repository here:

It is included in the source code in all releases, but has not been built as part of the core sim-recon package. If has not been built (check for $HALLD_HOME/lib/$BMS_OSNAME/ then simply invoke "make" in the hdparsim source directory.

Since hdparsim is a plugin, you will need to have a DANA program (probably hd_root) to attach it to in order to run it. Information on how to download a complete set of Hall-D source can be found in the "HOWTO get started with Hall-D Software" HOWTO and instructions on using pre-compiled binaries on the JLab CUE system can be found in the "HOWTO get started with Hall-D Software on the JLab CUE" HOWTO.

Data tables

The hdparsim plugin will need to have the appropriate data tables (ROOT files) present in the directory it is being run in for it to work. The plugin attempts to use the CURL library (if support was compiled in), or run the curl program to download these automatically if they are not already present when the program is started. Therefore, there is no need to download them "by hand". However, for the purposes of documentation, they can be found here:

Running an hdparsim simulation

To make use of the alternate method of producing reconstructed objects that hdparsim provides, one must set a few configuration parameters. A table of the relevant parameters is given in the following section. Here, an example is shown which uses pythia (contained in the bggen program) to generate events and hd_root + hdparsim to process them.

Example: Using hdparsim to process hadronic reaction events generated by PYTHIA

# First, run bggen to generate some events. Copy the files
# from the source directory to your local one first so you can
# edit them.
cp -r $HALLD_HOME/src/progams/Simulation/bggen/run .
# -- you may want to edit some configuration files for bggen here ---

$HALLD_HOME/bin/$BMS_OSNAME/bggen   # use full path since an unrelated binary called "bggen" exists on many Linux systems

# Second, run hd_root with the hdparsim plugin attached to process
# the events. We add the invariant_mass plugin to actually generate 
# some histograms (see sim-recon/src/programs/Analysis/plugin/invariant_mass_hists)
hd_root -PPLUGINS=hdparsim,invariant_mass_hists -PDEFTAG:DTrackTimeBased=HDParSim -PDEFTAG:DPhoton=HDParSim  bggen.hddm

The command line arguments -PDEFTAG:DTrackTimeBased=HDParSim and -PDEFTAG:DPhoton=HDParSim tell the system to use the HDParSim factory as the default when obtaining DTrackTimeBased and DPhoton objects respectively.

HDParSim Configuration Parameters

There are a few configurable options with hdparsim that are available for debugging purposes. They are:

Parameter name Default Description
DEFTAG:DTrackTimeBased One needs to set this to "HDParSim" in order to bypass tracking and use the parametric parameters for reconstructed values
DEFTAG:DPhoton One needs to set this to "HDParSim" in order to bypass photon reconstruction and use the parametric parameters for reconstructed values
HDPARSIM:APPLY_EFFICIENCY_CHARGED 1 If set to 0, does not apply efficiency cut for charged tracks
HDPARSIM:APPLY_EFFICIENCY_PHOTON 1 If set to 0, does not apply efficiency cut for photons
HDPARSIM:SCALE_ERR_PHI 1.0 Scale the "φ" error on momentum (charged particles only!)
HDPARSIM:SCALE_ERR_PT 1.0 Scale the error on relative transverse momentum (charged particles only!)
HDPARSIM:SCALE_ERR_THETA 1.0 Scale the "θ" error on momentum (charged particles only!)

n.b. The efficiency cut includes geometric acceptance so turning off the efficiency will cause un-detectable particles to be created. The efficiency cut is on by default so only turn it off for a special circumstance.

NOTE on Configuring PYTHIA

It should be noted that the default configuration for PYTHIA as manifest in the config. files kept in the bggen/run directory is to allow GEANT to decay most of the particles that it knows how to rather than having PYTHIA do the decay. This is not useful for the case of πos for example since hdparsim cannot smear a πo itself , but only the resulting photons from its decay (i.e. the particles that are actually detected). As such, you will want to tell PYTHIA to decay these for you. This is done by editing the file and inserting a "-" (minus) in front of the GEANT id numbers you wish to have PYTHIA decay for you.

Looking at the results

The resulting histograms from the above example will be in the file hd_root.root in a directory called "INV_MASS".

Using resolution/efficiency tables with a reduced current B-field map

Resolution tables have been produced with an 80% (1200A) B-field map and a 70% (1050A) map. These were done with code stored at The tables themselves can be obtained from the JLab CUE in the directory: /site/www/html/Hall-D/datatables. Direct links are provided below for convenience.

NOTE: when you download these files, they will need to be renamed to:

  • hd_res_charged_pion_1500.root
  • hd_res_charged_proton_1500.root

and placed in the working directory from which you run hdparsim.


The following 2 plots show the ratio of the relative transverse momentum resolution of the 100% field to the that of the 80% and 70% fields. The ratio should scale roughly with the field which scales with the current. These seem consistent with expectations. These plots are for pi+ tracks only.

20091207 pt res ratio80.png 20091207 t res ratio70.png

Below are 2 plots showing the efficiency difference of the reduced field results with that of the nominal (100%) field). Note that the Y-axis is zoomed in to only show up to 1.5GeV/c. As expected, a slight increase in efficiency is observed at lower momentum and angles for the pi+ tracks.

20091207 eff res diff80.png 20091207 eff res diff70.png