add the tutorial about the merging DJRs UserHook

Generators/Pythia8_i/README.md

@@ -163,3 +163,86 @@ In addition to the Athena interface, James Monk has written a standalone package
 that steers Pythia 8 without needing Athena, and provides Photos++, LHAPDF, LHEF
 and HepMC interfaces and can be more easily steered from the command line.  The
 package is available from the AGILe project on HepForge: https://agile.hepforge.org/
+
+# Getting Differential Distribution Rates ( DJRs ) from CKKWL
+
+In this tutorial, we will outline the procedures for extracting the internally computed DJRs from Pythia8, employing the mergingDJRs.cxx UserHook. We will focus on a straightforward scenario and utilize the Madgraph generator, although any other matrix element generator can be employed. Specifically, we will examine the production of a Z boson with 1-jet multiplicity.
+
+This tutorial is the result of the following Qualification Task: 
+
+https://its.cern.ch/jira/browse/AGENE-2069
+
+# Introduction 
+
+Parton showers (PS) are suitable in soft/collinear parton emissions regions, while they fail with hard and well-separated regions.
+The latter are well modeled only by matrix elements (ME). We will have the hard jet of the process from the Matrix element generator whil the soft jets should be modelled by emissions generated by Pythia8. 
+Consistently merging processes helps eliminate duplicate counts and overlaps between hard and soft partons by introducing a merging scale. One way to validate this approach is by directly extracting the N+1 → N jet clustering scales, also known as the Differential Jet Rates (DJRs), from Pythia8.
+
+For more information about the CKKWL merging scheme, please check the following link:
+https://pythia.org/latest-manual/CKKWLMerging.html
+
+# The steps to use the UserHook and activate the merging procedure:
+
+1) Create multiple JOs depending on the jet multiplicity of your hard process.
+2) Start generating jet multiplicity and the merged sample such as: 
+
+  a) Generate Seperated JOs for each jet multiplicity: 
+
+```
+   p p > z @0 
+
+   p p > z j @1 
+ 
+   p p > z j j @2
+```
+
+  b) generate a sample for the merged process such as: 
+
+```
+  generate p p > z 
+  add process p p > z j 
+  add process p p > z j j 
+```
+
+2) Add to your JO the fragment code which activates the merging procedure and configures all the essential settings for the merging process, such as: 
+
+```
+PYTHIA8_nJetMax=2
+PYTHIA8_Process='pp>e-e+'
+PYTHIA8_Dparameter=0.4
+PYTHIA8_TMS=30.0
+PYTHIA8_nQuarksMerge=4
+
+include("Pythia8_i/Pythia8_CKKWL_kTMerge.py")
+``` 
+
+3) Include the fragment code responsible for computing the DJRs: 
+
+```
+include("Pythia8_i/Pythia8_mergingDJRs.py")
+```
+
+4) You run the JO with Gen_tf.py.
+
+5) The output will be a ROOT file called `hist-DJR.root` that contains histograms fro the first and second DJR. The user then should stack the plots for the different jet multiplicity and the merged sample manually.
+
+# How to know the merging is working ?
+
+**1)  Make sure that the merging is activate:**
+
+ If all the parameters are properly configured, especially with  `Merging:doKTMerging = on `  the merging process should be operational. Consequently, you can verify this by examining your log file, where you should find  `MEPS Merging Initialization ` printout that contains the configurations you have specified.
+
+**2) The merging scale choice:**
+  
+ One crucial configuration in the CKKWL merging scheme is known as  `the merging scale`, which can be specified through the  `Merging:TMS` setting. This parameter serves as a threshold for the jet multiplicities included in our process. 
+ Its selection should be linked to the process's hard scale, such as the mass of the produced particles, HT cut etc. The threshold is ideally chosen within a range of  `~ 1/6 to 1/3 of the hard scale`. We systematically vary the scale within this range and assess the results based on the DJRs plot to determine the optimal setting. 
+ For the SUSY process, it is advisable to utilize the mass of the final particles as the preferred hard scale.
+
+**3) Analyzing the DJRs Plots:**
+   
+ The interpretation of DJRs plots is pivotal in determining the effectiveness of the chosen merging scale. Several key observations can guide the user in assessing the suitability of the merging scale:
+ -  The DJRs histograms should be continuous. 
+ -  The combined jet-multiplicity samples' sum should align with the merged sample.
+ -  In the initial DJR, there should be a clear distinction between the 0-jet sample and the 1-jet sample. Similarly, in the second DJR, the separation between the 1-jet sample and the 2-jet sample should be evident. A more distinct separation indicates a better choice of the merging scale.
+ -  The point where the 1-jet sample becomes dominant and the 0-jet multiplicity reaches zero signifies the initiation of the merging scale. The higher the value for our merging scale is, the greater the corresponding value of DJR at this juncture should be.
+ -  In the case of the first DJR, when dealing with small DJR values, the 0-jet multiplicity should closely resemble the merged sample. As DJR values increase, the 1-jet multiplicity should approximately match the merged sample.