main branch

nuclear-correlation

Developed with ROOT with C++17, nuclear-correlation provides a simple framework to calculate two-particle correlation function. Starting from the base classes, this repository provides a framework (based on the StHbt developed years ago at CERN) to construct the following observable,

$$ \begin{gather*} C(q) = \dfrac{P(p_1, p_2)}{P(p_1)P(p_2)} \end{gather*} $$

where $P(p_1,p_2)$ refers to the probability of detecting a pair of particles with asymptotic momenta $p_1$ and $p_2$. Although the repository was developed with the objective to analyze large dataset in nuclear/particle physics, the framework is compatible with arbitrary analysis since the base classes were written without assumption of any physics.

Why another repository for StHbt?

⚡️Considered as an updated version, developed with modern C++ and cmake for better readability and tractability.
🔥 The legacy code was written years ago using cpp11. Most codes are designed for high-energy community in which many features are not required in low-energy nuclear physics. Old mathematical libraries are rendered obsolete since the advancement of the ROOT.
👷Probably the "most important" reason : for me to learn the process of software development, following the ModernCppStarter.

Change Note

🔥ROOT dictionary are not generated. Unless ROOT 6.29+ is used, rootcling conflicts with the use of std::filesystem, see here.
✨Instead of defining mountains of quantities in track, event classes, uses std::any to handle everything.
✨added a singleton class ame for mass assignment to particles.
use doctest to test source code.
use github action for CI-CD
🎨 use clang-format to format all source code
use codecov to report coverage of test code.

0. Requirements & Installation

This repository is developed in a linux OS with ubuntu distribution. The only dependencies are

cmake version 3.14 or above. To install, simply run apt-get install cmake.
ROOT6, required support of C++17 standard (see the docker page). For installation, follow the instruction in the official page.

Finally, clone the repository

git clone https://github.com/tck199732/nuclear-correlation.git

Alternatively, if you prefer a contained environment, conda manages the dependencies and makes the installation easy. If you don't already have conda, download here.

git clone https://github.com/tck199732/nuclear-correlation.git
source ${miniconda3-prefix}/bin/activate
conda env create -f environment.yml --prefix ./env

1. Get Started

First, check your installation of ROOT6 and cmake. If your installatoin of ROOT is local, activate the startup script

source ${root-prefix}/bin/thisroot.sh

where ${root-prefix} refers to the path of installation in your system. If you are using a conda, activate the environment by

conda activate ./env

You can check the version of the installation by

root-config --version
cmake --version

The output should be similar to the following

6.28/04
cmake version 3.26.4

CMake suite maintained and supported by Kitware (kitware.com/cmake).

To check the installation of the repository, we compile the source code and a program which reads sample data and construct correlation function.

# creating a build
cmake -S standalone -B build 
cmake --build ./build -j4
# run the program
cd ./build
./main.exe

The expected output should be

2. Directory Structure

cmake/ : utility cmake tools, directly copied from ModernCppStarter.
assets/ : contains useful data such as ame amss table and some sample data for testing purpose.
dev : base class and backbone codes for correlation analysis using event-mixing method. User shall not modify in most scenario.
util : utility classes containing useful classes.
custom : all user-defined codes for customizing event reader, kinematic cuts and specific forms of correlation functions.
standalone : contain main scripts to run the program.
tests : contains unit tests for the source codes resided in the above directories. (currently only util is tested.)
all : contains CMakeLists.txt to compile everything, useful to developers for CI-CD.

3. Usage

Users need to write the codes in the directories custom and standalone.

custom : construct classes derived from those in dev
- reader: an event reader according to the format of data.
- cuts: set up gates to veto unwanted entity
- correlations: define the correlation function based on the pair information.
standalone: main script of the program.

4. Further-Reading

Two-Proton CF paper : uses data from experiment E03045, two-proton CF exhibits dependence on momentum.
Zbigniew's phd thesis : Check out chapter 5 for details in spherical-harmonincs decompoistion of Correlation Function.
Spherical-Harmoncis Components Paper : Directly sample 1D numerator and denominator weighted with $Y_l^m$, which alse used to extract components of CF expanded with $Y_l^m$.
Theory on the spherical moments
Debluring source function : extract the underlying source function from 1D correlation function through deblurring, based on Richardson-Lucy algorithm.

tck199732 / nuclear-correlation