spinthyia

A wrapper for a PYTHIA8.3 plugin StringSpinner that integrates quark spin dependence into the hadronization mechanism.

Installation

1. Install and Make the 8.3.10 version of PYTHIA on your own machine. The instructions for installing PYTHIA8 can be found here. This repository was built and tested using the following tar.

2. Ensure the latest version of ROOT is installed on your machine. This repository was built and tested using root6.28.04 with gcc9.2.0

3. Clone this repository and its dependencies (StringSpinner) by executing

git clone --recurse-submodules https://github.com/Gregtom3/spinthyia.git

4. Setup the path to your PYTHIA installation by executing

./configure.sh /path/to/pythia/installation

You may be prompted to edit your PYTHIA8DATA path. If so, you must update this environment variable, ideally in your .cshrc or .bashrc.

5. The scripts responsible for running the PYTHIA MC Eventgen are located in ./spinthyia/pythia_programs and have a .cc extension. The Makefile included in this repository compiles these scripts using ROOT, PYTHIA8, and StringSpinner dependencies. To compile all files...

make

To compile a single program and save time (ex: ./spinthyia/pythia_programs/dis.cc) ...

make prog PROG=dis

6. As an optional convenience, consider adding the ./spinthyia/bin directory to your $PATH variable at startup (ex: .cshrc or .bashrc). For instance, for .cshrc, add the following line...

setenv PATH ${PATH}:/path/to/spinthyia/bin

Usage

To run any one of the compiled PYTHIA programs, simply run bin/<NAME_OF_PROGRAM>. One of the programs that comes native to StringSpinner is dis.cc which calculates the integrated Collins asymmetry. To run it (assuming it was compiled) ...

./spinthyia/bin/dis

To execute any of the programs in macros/ one must first set up the appropriate environment variables. To set up the environment variables needed for this project, please source the appropriate script for your shell:

• If you are using Bash, Zsh, or another Bourne-like shell, run: source environ.sh

• If you are using Csh or Tcsh, run: source environ.csh

Project Creation

In the case where parallel computing (to be implemented in the future) is used to simulate many Monte Carlo events (and potentially event reconstruction), we provide a base project creation script create_project.rb. The goal of the script is to manage the output file locations of the executable being called and the required (and/or optional) input arguments of the executable.

The full list of arguments for the script can be viewed by

create_project.rb --help

The only required argument is the name of the executable being analyzed. By default, the output directory for the executables are in ./out. If a project name is not provided to the script, it defaults to the name tmp. The runcard, if provided by the user, is saved in ./out/<PROJECT_NAME>/runcards for logging.

Sample usage of the script is as follows

create_project.rb -e dis -n my_dis_project

Tutorial / Code Explanation

In the spirit of a comprehensive tutorial, run

create_project.rb -e pythia8_to_gemc_lund -n tutorial -r stringSpinSim.card -c 10000 -f -p example_A_single_pion.C

This command will run the Pythia8 StringSpinner --> GEMC LUND code (see ./pythia_programs) for 10000 events using the runcards/stringSpinSim.card to configure the event generator. The -n flag determines that the project output will be saved to a new directory ./out/tutorial, where the -f flag ignores the fact that this directory may already exist. As standard, we actually run the Pythia8 StringSpinner code 4 separate times with a different mode. These modes (which can be seen in case statements within ./pythia_programs/pythia8_to_gemc_lund.cc determine the quark/target polarization before the fragmentation process. The -p flag is an addendum that says "after Pythia8 generates the .dat files (in ./out/tutorial/gen/pythia8) run ./macros/example_A_single_pion.C on them". By default, the output of the processing macro will be a TFile at ./example_A_out.root.

The pythia8_to_gemc_lund program sets the lifetime=-1 for particles that originate from the diquark (which does not have StringSpinner's decay functionality). Otherwise, the lifetime=1. This flag is useful for discriminating which particles we should look at down the road for studying spin effects.

The LundAnalysis class is used in the example macros in ./macros. The class' purpose is to analyze a set of Lund files (typically .dat's generated by Pythia) based on a set of user-defined criteria. The analysis forms Hadronium (plural Hadronia) objects event-by-event that represent the final state the user is interested in. The key premise of LundAnalysis is that the user can be fairly specific as to what final state they are interested in performing a spin analysis on. The third argument to the LundAnalysis constructor , either HadroniumAnalysisType::SingleHadron or HadroniumAnalysisType::DiHadron determines if the final state information stored by the final ROOT Tree should have single hadron kinematics (ex: $\pi^{+}$, $\omega$, $K_{0}$) or dihadron kinematics (ex: $\pi^{-}\pi^{0}$). The user then sets the criteria for selecting the hadronia. The criteria is a string containing particle pid's (contained in parentheses) and + signs to indicate multi-particle reconstruction. Here are some sample criteria

• "(211)" The hadronia found event-by-event are single $\pi^{+}$. It would not make sense to use HadroniumAnalysisType::DiHadron here.
• "(211) + (22 22)" The hadronia are comprised of a final state $\pi^{+}$ and a diphoton final state. The two sets of parentheses indicate two distinct "hadron" objects, yet one of them is comprised of two final state photons. One can use the HadroniumAnalysisType::DiHadron here, but one can also do the HadroniumAnalysisType::SingleHadron. This flag would merge the two hadrons, the (211) and (22 22), into a single particle, from which single hadron kinematics are calculated.
• "(22 22) + (22 22) + (22 22)" The hadronia are comprised of 3 final state diphotons. This could represent, for example, an $\omega$ meson decay. The beauty of LundAnalysis is that, when it forms the hadronia, it will check to make sure that none of the photons repeat, and that each hadronia is unique from the rest. Since there are three hadrons here, we can only use HadroniumAnalysisType::SingleHadron.

In addition to the final state criteria, we can also narrow down the parenthood of the hadronia. The FilterRules class handles this, and can be seen in use in ./macros/example_C_rhoplus.C. Again defining a hadron as a group of particles (or a single particle) in the criteria parentheses, the rules can specify the parentPid and grandParentPid of each hadron. For instance, if the criteria was "(211) + (22 22)", then rules.addParticleCondition({213, -1}) would filter out hadronia where the first hadron (211) has a parentPid==213 and any grandParentPid. Following up with rules.addParticleCondition({111, 213}) filters hadronia where the second hadron has a parentPid==111 and a grandParentPid==213. Note that since this is a diphoton (or in other words, a multi-particle "hadron"), we ensure that both pid==22 particles have the same parent and grandparent. To build a pure $\rho^{+}$, we lastly must make sure the $\pi^{+}$ and $\pi^{0}\rightarrow\gamma\gamma$ decayed from the same particle. This is handled by rules.addParentIdRelationship({0,1,{RelationshipType::ParentIdAsOtherGrandParentId}}) which says "the parent pid of hadron 0 (the first hadron) must match with the grandparent pid of hadron 1 (the second hadron)". The RelationshipType options are given in ./src/HadroniaFilter.h.

Lastly, the LundAnalysis class handles some basic cuts. Here are some examples

• analysis.addKinematicCut(KinematicCut("Q2", 1., 10.)); // 1 < Q2 < 10
• analysis.addKinematicCut(KinematicCut("Mx", KinematicCut::CutType::MIN, 1.5)); // Mx > 1.5
• analysis.addKinematicCut(KinematicCut("z", KinematicCut::CutType::MAX, 0.95)); // z < 0.95