This repository is the working code base for heavy-flavour hadronization studies in proton-proton collisions with PYTHIA 8 and ROOT. We now use it as a complete local and Stoomboot workflow: it can generate MONASH, JUNCTIONS, and CLOSEPACKING samples, reduce the raw ROOT trees into subsampled analysis histograms, and make the present comparison plots for multiplicity, pT spectra, selected-particle yields, and baryon-to-meson ratios.
The present chain is centered on a unified heavy-flavour production. In that production charm and beauty are allowed in the same PYTHIA run, and the output tree keeps charm hadrons, beauty hadrons, Bc hadrons, pions, event multiplicity, process code, and per-event heavy-flavour counters. The older split production, where bbbar and ccbar are generated and analyzed independently, is still kept because it is needed for reference samples and for comparisons to earlier productions. In practice, we now make new combined HF samples with SimulationScripts/heavyflavourcorrelations_status.cpp, analyze them with AnalysisScripts/hf_mult_pt_analysis_multi.C, and compare them to the independent samples through the plotting macros under PlottingScripts.
SimulationScripts contains the PYTHIA producers, settings cards, and Makefile. The important executable for current work is heavyflavourcorrelations_status, while bbbarcorrelations_status, bbbarcorrelations_status_JUNCTIONS, ccbarcorrelations_status, and ccbarcorrelations_status_JUNCTIONS are the split legacy producers. The pythiasettings_Hard_Low_ccbb_MONASH.cmnd, pythiasettings_Hard_Low_ccbb_JUNCTIONS.cmnd, and pythiasettings_Hard_Low_ccbb_CLOSEPACKING.cmnd cards are the current combined-HF cards. The split cards remain available as pythiasettings_Hard_Low_bb*.cmnd and pythiasettings_Hard_Low_cc*.cmnd.
AnalysisScripts contains the ROOT reduction macros and shell wrappers. The current macro hf_mult_pt_analysis_multi.C reads RootFiles/HF/MONASH, RootFiles/HF/JUNCTIONS, and RootFiles/HF/CLOSEPACKING, splits the events into subsamples, and writes charm and beauty histogram files into AnalyzedData/<tag>/Charm and AnalyzedData/<tag>/Beauty. The split macros bb_mult_pt_analysis_multi.C and cc_mult_pt_analysis_multi.C do the same for the independent old samples.
PlottingScripts/PtMultiplicity contains the current physics plotting macros for pT spectra, multiplicity-dependent spectra, baryon-to-meson ratios, species-resolved spectra, single-particle spectra, and minimum-bias spectra. These macros read the reduced AnalyzedData files rather than the raw simulation trees. They prefer the hf_ file naming scheme and fall back to bbbar_ or ccbar_ when an older split sample is being plotted.
PlottingScripts/FinalAnalysis contains the final comparison layer. It now has two source macros. Plot_MultiplicityDistributions_TwoSamples.C compares multiplicity distributions between two analyzed samples. Plot_SelectedParticleYields_IndependentVsCombined.C compares selected charm and beauty yields and draws the independent-over-combined ratio inside the same output canvas.
The top level of PlottingScripts contains the paper THnSparse plotting path. improvedPlotting_THnSparse.C reads configuration_multiplicity_reduced_JUNCTIONS_THnSparse.json and treats MONASH, JUNCTIONS, and CLOSEPACKING as equal tunes. Plot_MultiplicityDistribution_PercentileBoundaries.C draws the charged-particle multiplicity distribution with the configured percentile boundaries, and run_paper_plots.sh is the preferred entry point for paper plotting targets. The older configurable plotting machinery is still present: improvedPlotting.C reads the older JSON configuration files, while combinedCanvasPlots.C, B_Balancing_GeneralPlotting.C, and PlottingWizard.C are earlier plotting macros for balancing and angular-correlation studies. ListHistos.C is the small inspection tool used to list objects inside a ROOT file. The DpDmBpBm_ComparisonStudy subdirectory keeps the D+/D- and B+/B- origin, same-mother, different-mother, decay-only, and decay-plus-hadronisation comparison macros.
Balancing_and_Sampling keeps the older balancing, yield, sampling, and uncertainty machinery. This part of the repository is still useful for reproducing the earlier balancing plots and for batch-yield error studies, but it is not the primary entry point for the current combined-HF production. The scripts under Balancing_and_Sampling/CalculateErrors still use the sampling directories from the older /data/alice/pveen/ProductionsPythia layout unless those base paths are overridden in the environment.
RootFiles is the intended place for raw simulation products. The current local checkout does not contain the large raw ROOT productions, except for descriptive text files and old-production notes. The actual raw ROOT files should be treated as external data and should not be forced into Git. AnalyzedData, in contrast, currently stores reduced ROOT outputs for dated samples such as 10-09-2025, 12-01-2026, 27-03-2026, 08-04-2026_100M_Combined, and 08-04-2026_100M_Separate.
Jobs and logs are the Condor work and log areas. They are produced by runCondorJob.sh and the submit files. They are not physics inputs by themselves, but they matter for diagnosing Stoomboot submissions.
Literature stores the reference bibliography and thesis PDF used for context. It is not part of the executable workflow, but it keeps the project references close to the analysis code.
The repository expects ROOT and PYTHIA 8 from the ALICE CVMFS environment. We now use setupEnv.sh as the shared entry point. It resolves HADRONIZATION_BASE from the environment first, then from base_path.txt, and otherwise from the repository location. It then loads VO_ALICE@ROOT::v6-30-01-alice5-2 and VO_ALICE@pythia::v8315-alice1-23.
source ./setupEnv.shOn the Nikhef/Stoomboot filesystem, base_path.txt currently points to:
/data/alice/ipardoza/Hadronization
If the repository is moved, you update that file and then refresh the Condor submit paths:
echo "/new/absolute/path/to/Hadronization" > base_path.txt
./update_submit_paths.shYou build the simulation executables from the repository base after loading the environment.
source ./setupEnv.sh
make -C SimulationScriptsFor a local combined-HF test, you run the unified producer with a tune mode, an output file, and two seed modifiers.
./SimulationScripts/heavyflavourcorrelations_status monash RootFiles/HF/MONASH/hf_MONASH_test.root 123 456
./SimulationScripts/heavyflavourcorrelations_status junctions RootFiles/HF/JUNCTIONS/hf_JUNCTIONS_test.root 123 456
./SimulationScripts/heavyflavourcorrelations_status closepacking RootFiles/HF/CLOSEPACKING/hf_CLOSEPACKING_test.root 123 456The unified output tree is named tree. It writes ID, HFCLASS, PT, ETA, Y, PHI, CHARGE, STATUS, MOTHER, MOTHERID, MULTIPLICITY, PROCESSCODE, NCHARM, NBEAUTY, and NBC. The HFCLASS convention is simple: 5 means beauty, 4 means charm, 45 means Bc, and 0 means pion.
The current combined-HF cards use proton-proton collisions at 14 TeV, Tune:pp = 14, PhaseSpace:pTHatMin = 1., and ParticleDecays:tau0Max = 0.01. The MONASH card enables HardQCD:hardccbar and HardQCD:hardbbbar. The JUNCTIONS card uses the same hard processes and adds the QCD-based color-reconnection, junction, fragmentation, and beam-remnant settings. The CLOSEPACKING card uses the same combined-HF output contract and adds the Close Packing T1 parameters.
The current analysis wrapper reads all raw combined-HF files for the current tunes and writes reduced subsample outputs. The default is ten subsamples and charge-conjugate-combined species histograms.
./AnalysisScripts/run_hf_analysis.sh 27-03-2026You can choose the number of subsamples and ask the analysis to write extra particle and antiparticle histograms while keeping the combined names for compatibility.
./AnalysisScripts/run_hf_analysis.sh 27-03-2026 20 separateThe output layout is:
AnalyzedData/<tag>/Beauty/hf_MONASH_sub0.root
AnalyzedData/<tag>/Beauty/hf_JUNCTIONS_sub0.root
AnalyzedData/<tag>/Beauty/hf_CLOSEPACKING_sub0.root
AnalyzedData/<tag>/Charm/hf_MONASH_sub0.root
AnalyzedData/<tag>/Charm/hf_JUNCTIONS_sub0.root
AnalyzedData/<tag>/Charm/hf_CLOSEPACKING_sub0.root
Each output file contains event-count histograms, tagged-event-count histograms, multiplicity histograms, tagged multiplicity histograms, PDG-versus-multiplicity histograms, aggregate charm or beauty meson and baryon histograms, species-resolved pT-versus-multiplicity histograms, and pion pT histograms. The macros enable Sumw2 so the plotting layer can propagate statistical errors.
The split analysis wrappers are still available for old independent samples.
./AnalysisScripts/run_bb_analysis.sh 12-01-2026 10 combined
./AnalysisScripts/run_cc_analysis.sh 12-01-2026 10 combinedThe current paper THnSparse plotting workflow uses pair-named ROOT files produced by AnalysisScripts/status_analysis_THnSparse_qq.C. The root-level wrappers build the input layout expected by Paul's plotting macro for all three tunes:
./submit_status_analysis.sh ALL 100 Job700
./merge_root_files.sh ALL Job700 21_06_2026
./make_subsamples.shFor large THnSparse productions, the merge and subsample wrappers can use a hybrid ROOT merge backend. This keeps the object-preserving ROOT merger as the default path and uses chunked hadd for the heavy charm-trigger pair files:
MERGE_BACKEND=hybrid HADD_JOBS=1 HADD_FINAL_JOBS=4 HADD_CHUNK_SIZE=10 ./merge_root_files.sh ALL Job700 21_06_2026
MERGE_BACKEND=hybrid HADD_JOBS=1 HADD_FINAL_JOBS=4 HADD_CHUNK_SIZE=10 ./make_subsamples.shFor a smaller validation pass, replace 100 with the number of available raw files to process per tune. The submit wrapper sorts available files by numeric job id and selects the first N completed files, so this works even if some low job ids are still running. For example, the planned three-tune test run uses:
./submit_status_analysis.sh ALL 50 Job700
./merge_root_files.sh ALL Job700 21_06_2026_50job
./make_subsamples.sh ALL 8 6 123 Job700 700_50jobWhen using non-default tags like these, copy one of the THnSparse JSON configs and update bb_bar_complete_root_dir, cc_bar_complete_root_dir, bb_bar_complete_root_dir_sub_samples, and cc_bar_complete_root_dir_sub_samples to the validation tags. Then pass that config through THNSPARSE_CONFIG, THNSPARSE_COMPLETE_ROOT_CONFIG, or MULTIPLICITY_CONFIG when running PlottingScripts/run_paper_plots.sh.
make_subsamples.sh uses non-overlapping shuffled partitions by default. With no arguments, it runs the final paper default: all three tunes, ten independent 10-job subsamples per tune, Job700 input, and SUBSAMPLES_700 output. This covers all 100 jobs per tune.
The resulting paper THnSparse inputs are:
AnalyzedData/complete_root_<tag>_MONASH
AnalyzedData/complete_root_<tag>_JUNCTIONS
AnalyzedData/complete_root_<tag>_CLOSEPACKING
AnalyzedData/SUBSAMPLES_<tag>/combined_root_subSamples_MONASH
AnalyzedData/SUBSAMPLES_<tag>/combined_root_subSamples_JUNCTIONS
AnalyzedData/SUBSAMPLES_<tag>/combined_root_subSamples_CLOSEPACKING
The paper plotting entry point is:
./PlottingScripts/run_paper_plots.sh smoke
./PlottingScripts/run_paper_plots.shsmoke runs the multiplicity-boundary plot, inclusive raw kinematic spectra, and the complete-root THnSparse config without subsampling. The default all target runs the multiplicity-boundary plot, inclusive raw kinematic spectra, and the full THnSparse config. Use ./PlottingScripts/run_paper_plots.sh multiplicity-spectrum to regenerate only the shared raw N_{ch} spectrum with the tune/MONASH ratio panel, MONASH percentile-boundary inset, and short energy/acceptance annotation below the legend. Use ./PlottingScripts/run_paper_plots.sh multiplicity-compact for the standalone compact MONASH percentile-boundary figure.
Paper kinematic spectra are inclusive single-particle spectra drawn directly from RootFiles/HF, not from trigger/associate-conditioned THnSparse pair outputs. Exact PDG-ID matching is used, the raw producer acceptance is preserved, and absolute phi is displayed in [-pi, pi). Correlation Delta phi plots in Paul's THnSparse macro keep the shifted [-pi/2, 3pi/2] convention. The charged multiplicity definition used for these figures is prompt charged primary e, mu, pi, K, and p species, including antiparticles, with PYTHIA status 81-89, pT >= 0.15 GeV/c, |eta| <= 4, in pp at sqrt(s)=14 TeV; activity classes are read from low to high multiplicity as 90-100% -> ... -> 0-1%.
The current pT and multiplicity plots are made from AnalyzedData, not from RootFiles. If no date is passed, the plotting helpers search for the latest dated folder under AnalyzedData. In ordinary use, we pass the date explicitly so that no older production is selected by accident.
root -l -b -q 'PlottingScripts/PtMultiplicity/Plot_HF_Ratios_vsMultiplicityPercentile_subsamples.C("27-03-2026",10,0.0,-1.0)'
root -l -b -q 'PlottingScripts/PtMultiplicity/Plot_HF_SpeciesResolvedPtSpectra_vsMultiplicity_subsamples.C("27-03-2026","Charm",10)'
root -l -b -q 'PlottingScripts/PtMultiplicity/Plot_HF_MinimumBiasPtSpectra_MONASH_JUNCTIONS_subsamples.C("27-03-2026","Beauty",10)'The final-analysis comparisons are similarly run from the repository base.
root -l -b -q 'PlottingScripts/FinalAnalysis/Plot_MultiplicityDistributions_TwoSamples.C("12-01-2026","27-03-2026",10,true)'
root -l -b -q 'PlottingScripts/FinalAnalysis/Plot_SelectedParticleYields_IndependentVsCombined.C("12-01-2026","27-03-2026",10)'The pT and multiplicity plots are written to PlottingScripts/PtMultiplicity/Plots. The final-analysis plots are written to PlottingScripts/FinalAnalysis/Plots. Several macros write both PNG and PDF, while older ratio macros still write only PNG.
The Condor entry point is runCondorJob.sh. It supports both the current combined-HF workflow and the older split workflow. The submit files use the shared filesystem and do not transfer files through Condor.
./update_submit_paths.sh
condor_submit submitCondor_hf_10M.subsubmitCondor_hf_10M.sub submits ten one-million-event jobs per MONASH/JUNCTIONS tune. submitCondor_hf_90M.sub submits ninety one-million-event jobs per MONASH/JUNCTIONS tune. submitCondor_hf_CLOSEPACKING_100M.sub submits one hundred one-million-event jobs for the Close Packing tune. submitCondor_10M.sub submits the old split bbbar and ccbar production for MONASH and JUNCTIONS. The wrapper names output files with the Condor cluster and job id, writes the ROOT file inside the job work directory, and moves the completed file to RootFiles/... only after a successful run.
Raw ROOT files are large production artifacts. They belong under RootFiles on the machine that runs the production, but they should be excluded from ordinary source synchronization unless the task explicitly concerns data transfer. Reduced analysis ROOT files in AnalyzedData are tracked in this working branch because they are the compact products used by the plotting layer.
The three-tune integration branch is three-tunes. When synchronizing with the Nikhef copy, the safe rule is that code, scripts, documentation, submit files, and reduced analysis outputs should match, while raw .root files under RootFiles may differ or remain only on the cluster. This keeps the branch reproducible without moving the heavy raw productions unnecessarily.