Warning, /macros/calibrations/sepd/eventplane/README.org is written in an unsupported language. File is not indexed.
0001 #+title: README
0002
0003 * Overview
0004
0005 This project provides a complete, high-throughput pipeline for the Q Vector calibration of the *sPHENIX Event Plane Detector (sEPD)*. It automates the multi-pass procedure required to correct detector acceptance effects and gain non-uniformities, ultimately generating Calibration Database (CDB) payloads.
0006
0007 * Scientific Context
0008
0009 The pipeline corrects sEPD Q-vectors through a three-pass calibration sequence:
0010
0011 1. *Re-centering*: Calculates first-order Q-vector offsets to center the distribution.
0012 2. *Flattening*: Applies re-centering and calculates a whitening matrix to transform elliptical distributions into isotropic unit circles.
0013 3. *Validation & CDB*: Applies the full correction (re-centering + flattening) to verify the final event plane resolution and generates the final CDB payloads.
0014
0015 ** Workflow Architecture
0016
0017 The pipeline is managed by ~runProd.py~, which orchestrates the following stages:
0018
0019 *** 1. Stage-QA (Data Preparation)
0020 - *Process*: Uses ~Fun4All_sEPD.C~ and ~sEPD_TreeGen~ to process DSTs.
0021 - *Output*: Generates DSTs for fast iteration and QA histograms to identify "bad" towers.
0022 - *Condor*: Submits batch jobs to the HTCondor system for high-throughput processing.
0023
0024 *** 2. Stage-QVecCalib (Iterative Calibration)
0025 - *Process*: Iteratively executes the three calibration passes using the ~Fun4All_QVecCalib.C~ macro.
0026 - *Logic*: Pairs TTrees with calibration constants derived from previous passes.
0027 - *Parallelization*: Utilizes Python's ~multiprocessing~ to perform simultaneous ~hadd~ merges of run-by-run results.
0028 - *CDB Generation*: The final pass (Pass 2) automatically produces the ~SEPD_EventPlaneCalib~ and ~SEPD_HotMap~ payloads.
0029
0030 ** Core Components
0031
0032 *** Python Pipeline (~runProd.py~)
0033 - *Requirements*: Python 3.13+.
0034 - *Monitoring*: Implements a passive log-polling strategy that tracks job completion via ~.log~ files rather than polling the schedd, increasing reliability.
0035
0036 *** C++ Classes (C++20)
0037 - *sEPD_TreeGen*: A ~SubsysReco~ module that extracts event-level and tower-level info into DSTs.
0038 - *QVecCalib*: A ~SubsysReco~ module that orchestrates the physics logic for the three calibration passes and CDB writing.
0039 - *QVecShared*: Provides centralized definitions (harmonics, centrality bins) and naming helpers to ensure consistency across the pipeline.
0040
0041 ** Requirements & Build
0042 - *External Tools*: Requires ~CreateDstList.pl~ for DST synchronization.
0043
0044 ** Execution
0045
0046 To run the full production pipeline, execute the primary Python script with your specific run list:
0047
0048 #+begin_src bash
0049 python3 runProd.py -i runs.list --output /path/to/output --cdb-tag my_tag
0050 #+end_src
0051
0052 *** Required Arguments
0053 - -i, --run-list-file: Path to a text file containing the list of run numbers to be processed, with each run on a new line.
0054
0055 *** Data & Path Configuration
0056 - -o, --output: Base directory for all stage outputs, logs, and final results. Defaults to ~test~.
0057 - -i4, --dst-list-dir: Directory containing existing DST lists. If not provided, it defaults to a ~dst-lists~ folder within the output directory.
0058 - -l, --condor-log-dir: Directory where HTCondor will write .log files. If empty, it defaults to ~/tmp/[USER]/dump~.
0059
0060 *** Physics & Macro Parameters
0061 - -i2, --f4a-macro: Path to the Fun4All ROOT macro used for initial TTree generation. Defaults to ~macros/Fun4All_sEPD.C~.
0062 - -i3, --f4a-QVecCalib: Path to the Fun4All ROOT macro used for calibration passes. Defaults to ~macros/Fun4All_QVecCalib.C~.
0063 - -n2, --events: Total number of events to process per job. Setting this to 0 (default) processes all available events in the DST.
0064 - -t1, --dst-tag: The specific sPHENIX DST production tag used for input list generation. Defaults to ~new_newcdbtag_v008~.
0065 - -t2, --cdb-tag: The tag associated with the Calibration Database for both reading existing conditions and writing final payloads. Defaults to ~newcdbtag~.
0066
0067 *** Parallelization & Performance
0068 - -n3, --n-cores: Number of CPU cores to utilize for parallel tasks, including hadd merging of ROOT files and concurrent CDB generation. Defaults to 8.
0069 - -n1, --segments: Number of DST files to process per individual Condor job. Defaults to 15.
0070 - -m1, --f4a-memory: Memory (in GB) requested for Fun4All Condor jobs. Defaults to 3.0.
0071 - -m2, --QVecCalib-memory: Memory (in GB) requested for Q-Vector Calibration Condor jobs. Defaults to 0.5.
0072
0073 *** Binary & Script Locations
0074 - -e1, --f4a-script: The shell script wrapper for executing Fun4All on Condor. Defaults to ~scripts/genFun4All.sh~.
0075 - -e2, --QVecCalib-script: The shell script wrapper for executing the Calibration binary on Condor. Defaults to ~scripts/genQVecCalib.sh~.
0076
0077 *** Debugging
0078 - -v, --verbose: Enables detailed debug logging in the main log.txt file, providing granular information on command execution and Condor status.
0079
