View source for 2023 KLF Simulations

__TOC__

= 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 [https://halldweb.jlab.org/wiki/index.php/Getting_Started_At_GlueX 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 [https://halldweb.jlab.org/wiki/index.php/Building_Private_Versions_of_GlueX_Software:_my_halld_build_jlab and maybe this as well].
* A general overview of the GlueX software [https://halldweb.jlab.org/wiki/index.php/Software can be found here].

There are a couple of different ways to install the GlueX software stack.
* You can [https://halldweb.jlab.org/docs/build_scripts_web/node10.html follow these instructions to build the full software stack locally].
* Or you can [https://halldweb.jlab.org/wiki/index.php/HOWTO_use_the_GlueX_Singularity_Container 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 <code>scons</code> 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., <code>my_halld_update.py -x /path/to/version.klf.xml</code>.

<div class="toccolours mw-collapsible mw-collapsed">
Example version.klf.xml configuration file
(Click "Expand" to the right for more details -->):

<div class="mw-collapsible-content">
<pre>
<?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>
</pre>
</div></div>

A version of the dedicated KLF event generator can be downloaded and installed from here <code>https://github.com/sdobbs/KLGenerator_hddm_V3</code> using the following commands:
<pre>
git clone https://github.com/sdobbs/KLGenerator_hddm_V3
cd KLGenerator_hddm_V3
scons install
</pre>

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

===Easy Configuration at JLab===

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

<pre>
source /work/halld/home/sdobbs/KLF/load_KLF_sw.sh
</pre>

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 <code>home=/wherever/you/put/your/halld_recon</code>.

=== Apptainer (Singularity) Container ===

Here's how to start up a container environment on the CUE, with the standard GlueX container:
<pre>
singularity exec --bind /cvmfs/oasis.opensciencegrid.org/gluex/group/halld:/group/halld,/scratch,/u/home,/work/halld /cvmfs/singularity.opensciencegrid.org/jeffersonlab/gluex_devel:latest gxshell
[inside the shell]
source /home/sdobbs/work/KLF/apptainer-build/load_KLF_sw.sh
</pre>

= Generating Events =

The KLGenerator_hddm_V3 program has some good online help through the <code>-h</code> switch.  

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

<code>
KLGenerator_hddm_V3  -M1000000 -Fgenerated.root -Ekaon:histo:1.0:4.0 -Rkl2
</code>

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.

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: <code>JANA_CALIB_CONTEXT variation=klong</code>.

The GEANT4-based simulation package is called hdgeant4.  It relies on a configuration file called control.in.  There is some thorough documentation [https://github.com/JeffersonLab/HDGeant4/blob/master/test/control.in at this location], however, you can find a simple control.in file to start out with below.

<div class="toccolours mw-collapsible mw-collapsed">
Example control.in file

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

<div class="mw-collapsible-content">
<pre>
INFILE 'generated.hddm'
TRIG 10
RUNG 30730
OUTFILE 'hdgeant4_output.hddm'
TOFMAX 1e-5
HADR 1
CKOV 1
LABS 1
</pre>
</div></div>

You can then run the program as, for example, <code>hdgeant4 -t6</code> (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 <code>mcsmear hdgeant4_output.hddm</code>.  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: 

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


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

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

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