2023 KLF Simulations

Installing Software

The reconstruction and analysis software are built on the same software stack used for the analysis of photon beam measurements with the GlueX detector.

• You can find some general information on GlueX software and computing at this page.
  • If you are running the software at JLab, you should use the instructions on this page to set up the GlueX software and maybe this as well.
• A general overview of the GlueX software can be found here.

There are a couple of different ways to install the GlueX software stack.

• You can follow these instructions to build the full software stack locally.
• Or you can run the GlueX software in a container.

Note that the GlueX software installation has been verified to work on RedHat/CentOS 7 and various Ubuntu versions - basically anywhere you can install the scons package. Instructions exist on how to install on RedHat/CentOS 8, link to them. The software currently does not build under RedHat/CentOS 9 - you are better off running the software inside a container in this case, for now.

You can then install the KLF-specific branches using the my_halld_update.py script from the build_scripts package, and the XML configuration file given below, e.g., my_halld_update.py -x /path/to/version.klf.xml.

Example version.klf.xml configuration file (Click "Expand" to the right for more details -->):

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="https://halldweb.jlab.org/halld_versions/version7.xsl"?>
<gversions file="version_5.11.0.xml" date="2023-06-14">
<package name="amptools" version="0.14.5"/>
<package name="ccdb" version="1.06.09"/>
<package name="cernlib" version="2005" word_length="64-bit"/>
<package name="diracxx" version="2.0.2"/>
<package name="evio" version="4.4.6"/>
<package name="evtgen" version="01.07.00"/>
<package name="geant4" version="10.04.p02"/>
<package name="gluex_MCwrapper" version="v2.7.0"/>
<package name="gluex_root_analysis" version="1.24.0" dirtag="hdr441"/>
<package name="halld_recon" branch="sdobbs_klong_beam"/>
<package name="halld_sim" version="4.45.0"/>
<package name="hdds" version="4.15.0"/>
<package name="hdgeant4" version="2.35.0" dirtag="hdr441"/>
<package name="hd_utilities" version="1.45"/>
<package name="hepmc" version="2.06.10"/>
<package name="jana" version="0.8.2" dirtag="ccdb169"/>
<package name="lapack" version="3.9.0"/>
<package name="photos" version="3.61"/>
<package name="rcdb" version="0.07.01"/>
<package name="root" version="6.24.04"/>
<package name="sqlitecpp" version="3.1.1"/>
<package name="sqlite" version="3.36.0" year="2021"/>
<package name="xerces-c" version="3.2.3"/>
</gversions>

A version of the dedicated KLF event generator can be downloaded and installed from here https://github.com/sdobbs/KLGenerator_hddm_V3 using the following commands:

git clone https://github.com/sdobbs/KLGenerator_hddm_V3
cd KLGenerator_hddm_V3
scons install

Note that KLGenerator_hddm_V3 is installed under $HALLD_MY/bin, so make sure that you have that directory in your PATH.

Easy Configuration at JLab

If you are on the JLab CUE, you can load a KLF environment using the following script:

source /work/halld/home/sdobbs/KLF/load_KLF_sw.sh

If you want to start a development environment, you can copy the .sh and .xml files from this directory, check out a version of halld_recon, and edit the XML file to have the field home=/wherever/you/put/your/halld_recon.

Generating Events

The KLGenerator_hddm_V3 program has some good online help through the -h switch.

For an example, let's try generating 1M KL p -> Ks p events.

KLGenerator_hddm_V3 -M100 -Fgenerated.root -Ekaon:histo:1.0:4.0 -Rkl2

This writes events out to a file named generated.hddm.

Here are some useful/interesting switches to consider for these studies:

• -t - disables KL beam propagation calculation - this basically forces hdgeant4 to treat this as a photon beam reaction
• -c - disables simulation of KPT z size, so all KLs are produced exactly 24 m from the target center.

Note that right now all events are generated in the center of the LH2 target (z=65 cm). I'm working on updating this.

There are two next steps: running the events through the GEANT4-based detector simulation, and applying the detector response. When running all of these pieces of software, the following environment variable must be set to the following value: JANA_CALIB_CONTEXT variation=mc.

The GEANT4-based simulation package is called hdgeant4. It relies on a configuration file called control.in. There is some thorough documentation at this location, however, you can find a simple control.in file to start out with below.

Example control.in file

(Click "Expand" to the right for more details -->):

INFILE 'generated.hddm'
TRIG 10
RUNG 30730
OUTFILE 'hdgeant4_output.hddm'
TOFMAX 1e-5
HADR 1
CKOV 1
LABS 1

You can then run the program as, for example, hdgeant4 -t6 (the -t6 says to run with 6 threads - please change this to whatever is convenient to your system). The output is then saved as hdgeant4_output.hddm.

You can apply the detector smearing then by running the command mcsmear hdgeant4_output.hddm. The output file will then be hdgeant4_output_smeared.hddm.

Analyzing simulated data

There are two ways we can go about analyzing the simulated data.

The program hd_dump prints out values of different objects event by event.

Here is an example of how to run it:

hd_dump -DDVertex:KLong -DBeamKLong -DBeamKLong:MCGEN DTrackTimeBased -DChargedTrackHypothesis -DMCThrown -PVERTEX:USEWEIGHTEDAVERAGE=1 hdgeant4_output_smeared.hddm

To generate histograms or trees, you can use the program hd_root. Here is an example of how to run it:

hd_root --nthreads=8 -PPLUGINS=EVENTRFBUNCH:USE_TAG=KLong -PVERTEX:USEWEIGHTEDAVERAGE=1 -PPLUGINS=monitoring_hists hdgeant4_output_smeared.hddm

Some notes:

• hd_root runs very well multithreaded! Use as many as you want, i.e., with the --nthreads flag
• Most options can be set using the -P switch, as -P[key]=[value]. Use the -Pprint option to get a list of different flags that can be set!
• -PPLUGINS lets you specify a comma-separated list of plugins to use. There are many standard plugins, but monitoring_hists is a good place to start - it makes a ton of standard histograms.

Note that you should always include the flag -PPLUGINS=EVENTRFBUNCH:USE_TAG=KLong !

One can also write your own plugins, instructions to come.

Interesting things to look at

• How does the vertex spatial and time resolution depend on the number of charged particles in the event, and where they go in the detector (BCAL vs. TOF)?
• Is the time-of-flight (Delta t_"RF") properly centered at zero, and what is the resolution, in various detectors?

Relevant objects to consider

• DVertex:KLong - uses charged tracks to determine the primary vertex position and time. There are several interesting flags associated with this:
  • VERTEX:USEWEIGHTEDAVERAGE=(0/1) - to get the event time, we take the simple average of the track times propagated to the vertex. We can also weight this average by the resolution of these times (i.e. the track times as determined by fast timing detectors).
  • VERTEX:MINTRACKINGFOM - to get the overall event vertex, we only want to use reasonably good tracks that come from near the target. this is one quality control flag we can use, cutting on the track fit FOM
  • VERTEX:MINTRACKNDF - same thing here, but cut (implicitly) on the number of hits on the track (num. hits = NDF + 5). junk and beam background tracks will tend to have few hits
• DEventRFBunch:KLong - uses the DVertex:KLong object to determine the event timing
• DBeamKLong - the reconstructed KLong beam object (momentum and timing)
• DBeamKLong:MCGEN - the thrown KLong beam parameters

Next steps

Finish implementing standard ROOT tree output.

Determine some loose default TOF PID selections.

Implement KL beam into the kinematic fitting framework