MatchCosmics: cosmics in collision data + raw-cluster writer with TOF

[matthias-kleiner]

Collect cosmic muons in the PbPb async reconstruction for TPC calibration (distortion correction with tracks that do not come from the vertex). This PR makes the matcher usable in collision data and adds an optional writer of the raw data needed for an offline refit. Details and validation are in the commit messages.

1. MatchCosmics: include the last compatible vertex in the DCA veto (off-by-one fix, affects --use-pv-info).
2. MatchCosmics: selection of cosmics in collision data, named presets (--cosmics-preset physics-v1; all new cuts off by default).
3. MatchCosmics: energy-loss sign along the muon's flight; optional eLossSign in GPUO2InterfaceRefit / GPUTrackingRefit (default 0: unchanged for other users).
4. Cosmics: raw clusters of matched cosmics with TOF tag (--enable-cluster-output → o2_cosmics_full.root): TPC road clusters, ITS / TOF / TRD hits, TOF time, refit at the TOF time.
5. MatchCosmics: same-side TPC-only legs compared at a common time (option, off; not in the preset, it adds fakes in PbPb).
6. MatchCosmics: TOF flight pair of the legs as selection criterion (on in physics-v1).

Default behaviour changes: muon mass for seeds and refit, energy-loss sign along the flight (cosmics run 562658: 357 → 358 cosmics, q/pt within ±1 %); the veto fix with --use-pv-info. Everything else is opt-in.

Usage (PbPb async; O2DPG wiring is a follow-up):
o2-cosmics-match-workflow --track-sources TPC --cosmics-preset physics-v1 --enable-cluster-output

Validation: PbPb 568041 from CTF with physics-v1 (19684 TFs): 0.29 cosmics per TF, 15 % TOF-tagged; matcher 0.50 + collector 0.16 CPU s per TF; 1.1 kB per TF. Cosmic MC with PbPb-like distortions: 79.5 % of the muons matched, 0 wrong pairs.

Open points: purity of the untagged cosmics is not yet measured on data (the TOF-tagged sample is the clean one); the collector repeats parts of the matcher's TOF and refit code (a shared helper is possible).

Left: 50 TOF-tagged cosmics from PbPb 568041 with physics-v1 (TOF-tagged, refitted at the TOF time, > 150 TPC clusters, p > 2 GeV). Right: the first 50 cosmics without quality cuts, as written to o2_cosmics_full.root. TPC clusters of both legs, ITS clusters, TOF hits; one colour per cosmic.

[shahor02]

Thanks, looks good as far as I could follow w/o running with AI over it. A small cosmetic comment: the CosmicTrack containing TrackCosmic might be confusing, could you ask Claude to rename it, e.g. to TrackCosmicExtended or something like that?

[shahor02]

would not 3cm cut damage ITS IB coverage?

[matthias-kleiner]

Hi @shahor02 , yes, you are right. With this cut we lose the cosmics crossing the IB. I am running a test on GSI to see whether a lower cut is feasible in PbPb (CPU and fake pairs).

[matthias-kleiner]

Hi @shahor02 , simply lowering these cuts is not feasible in PbPb: already at 1 cm / 3σ the number of cosmic candidates grows by ~40×, almost all of them pairs of tracks from one collision. Instead I added looser selections, minSeedDCAxyTOF and minSeedDCAxyNSigmaTOF (off by default): a TPC leg that fails the standard selection but passes these is only used if the cosmic candidate has a top/bottom TOF hit pair matching the cosmics flight time. Such cosmics are flagged (TrackCosmics::NearBeamBottom/NearBeamTop) so they can be selected or dropped downstream. Additionally, the collector now keeps the 5 closest ITS clusters per leg in each inner-barrel layer, so the ITS clusters can be used offline to reject the remaining fake candidates. With the option switched on, the output grows by ~50 % and the matcher time roughly doubles, to ~1.1 s per TF, so it should be still fine.

[shahor02]

This makes sens. BTW, you could reduce the combinatorics by flagging in advance the TPC tracks with participate in the global tracks - contributors to any PV.

[matthias-kleiner]

Thanks, its implemented. TPC tracks belonging to a PV contributor are now rejected as cosmic legs (--pv-contributor-sources set automatically from $VERTEXING_SOURCES). On 600 TFs of 567939 this keeps all physics-v1 cosmics and reduces the matcher CPU time by 21 % (by 50 % with the looser near-beam selection).

[alibuild]

Error while checking build/O2/fullCI_slc9 for 22bdf41 at 2026-10-09 07:59:

## sw/BUILD/o2codechecker-latest/log
100% tests passed, 0 tests failed out of 1


## sw/BUILD/ThePEG-latest/log
collect2: error: ld returned 1 exit status


## sw/BUILD/O2-full-system-test-latest/log
command /sw/slc9_x86-64/O2/slc9_x86-64-slc9_x86-64-local6/prodtests/full-system-test/dpl-workflow.sh had nonzero exit code 1


## sw/BUILD/o2checkcode-latest/log
--
========== List of errors found ==========
++ GRERR=0
++ grep -a -v clang-diagnostic-error error-log.txt
++ grep -a ' error:'
++ GRERR=1
++ [[ 1 == 0 ]]
++ mkdir -p /sw/INSTALLROOT/859a911b514aafd2ca198d66670b86334a33628f/slc9_x86-64/o2checkcode/1.0-local15/etc/modulefiles
++ alibuild-generate-module
+ HAS_BIN=
+ HAS_LIB=
+ HAS_CMAKE=
+ HAS_ROOT=
+ '[' 0 '!=' 0 ']'
+ cat
+ printf 'if ![ is-loaded '\''BASE/1.0'\'' ] {\n module load BASE/1.0\n}'
+ echo 'BUILD_REQUIRES=CMake alibuild-recipe-tools defaults-release'
BUILD_REQUIRES=CMake alibuild-recipe-tools defaults-release
+ FULL_BUILD_REQUIRES='alibuild-recipe-tools bz2 safe_int UUID defaults-release O2-customization Alice-GRID-Utils double-conversion ninja-fortran json-c ninja MPFR googlebenchmark CMake Python-modules-list pytorch_cpuinfo FairCMakeModules date'
+ echo 'FULL_BUILD_REQUIRES=alibuild-recipe-tools bz2 safe_int UUID defaults-release O2-customization Alice-GRID-Utils double-conversion ninja-fortran json-c ninja MPFR googlebenchmark CMake Python-modules-list pytorch_cpuinfo FairCMakeModules date'
FULL_BUILD_REQUIRES=alibuild-recipe-tools bz2 safe_int UUID defaults-release O2-customization Alice-GRID-Utils double-conversion ninja-fortran json-c ninja MPFR googlebenchmark CMake Python-modules-list pytorch_cpuinfo FairCMakeModules date
++ env
++ cut -f1 -d=
++ grep -v '^DEFAULT_'
++ grep -v PKGREVISION
++ grep -v ALIBUILD_RECIPE_TOOLS
++ grep REVISION
++ sed -e s/_REVISION//
+ for x in $(env | cut -f1 -d= | grep -v "^DEFAULT_" | grep -v PKGREVISION | grep -v ALIBUILD_RECIPE_TOOLS | grep REVISION | sed -e 's/_REVISION//')
++ eval 'echo $LIBFFI_REVISION'
+++ echo 14
+ REVISION_VALUE=14
++ eval 'echo $LIBFFI_VERSION'
+++ echo v3.2.1-alice1
+ VERSION_VALUE=v3.2.1-alice1
++ eval 'echo $LIBFFI_ROOT'
[0 more errors; see full log]

Full log here.

[alibuild]

Error while checking build/O2/fullCI_slc9 for 3f1d9f8 at 2026-10-09 17:02:

## sw/BUILD/o2codechecker-latest/log
100% tests passed, 0 tests failed out of 1


## sw/BUILD/ThePEG-latest/log
collect2: error: ld returned 1 exit status


## sw/BUILD/O2-full-system-test-latest/log
command /sw/slc9_x86-64/O2/slc9_x86-64-slc9_x86-64-local12/prodtests/full-system-test/dpl-workflow.sh had nonzero exit code 1


## sw/BUILD/o2checkcode-latest/log
--
========== List of errors found ==========
++ GRERR=0
++ grep -a -v clang-diagnostic-error error-log.txt
++ grep -a ' error:'
++ GRERR=1
++ [[ 1 == 0 ]]
++ mkdir -p /sw/INSTALLROOT/27063cfef39f318b3e838961e5d45d4edf9c7a64/slc9_x86-64/o2checkcode/1.0-local17/etc/modulefiles
++ alibuild-generate-module
+ HAS_BIN=
+ HAS_LIB=
+ HAS_CMAKE=
+ HAS_ROOT=
+ '[' 0 '!=' 0 ']'
+ cat
+ printf 'if ![ is-loaded '\''BASE/1.0'\'' ] {\n module load BASE/1.0\n}'
+ echo 'BUILD_REQUIRES=CMake alibuild-recipe-tools defaults-release'
BUILD_REQUIRES=CMake alibuild-recipe-tools defaults-release
+ FULL_BUILD_REQUIRES='json-c Alice-GRID-Utils Python-modules-list alibuild-recipe-tools MPFR UUID pytorch_cpuinfo date ninja ninja-fortran defaults-release CMake safe_int googlebenchmark bz2 double-conversion O2-customization FairCMakeModules'
+ echo 'FULL_BUILD_REQUIRES=json-c Alice-GRID-Utils Python-modules-list alibuild-recipe-tools MPFR UUID pytorch_cpuinfo date ninja ninja-fortran defaults-release CMake safe_int googlebenchmark bz2 double-conversion O2-customization FairCMakeModules'
FULL_BUILD_REQUIRES=json-c Alice-GRID-Utils Python-modules-list alibuild-recipe-tools MPFR UUID pytorch_cpuinfo date ninja ninja-fortran defaults-release CMake safe_int googlebenchmark bz2 double-conversion O2-customization FairCMakeModules
++ env
++ cut -f1 -d=
++ grep -v '^DEFAULT_'
++ grep -v PKGREVISION
++ grep -v ALIBUILD_RECIPE_TOOLS
++ grep REVISION
++ sed -e s/_REVISION//
+ for x in $(env | cut -f1 -d= | grep -v "^DEFAULT_" | grep -v PKGREVISION | grep -v ALIBUILD_RECIPE_TOOLS | grep REVISION | sed -e 's/_REVISION//')
++ eval 'echo $LIBFFI_REVISION'
+++ echo 14
+ REVISION_VALUE=14
++ eval 'echo $LIBFFI_VERSION'
+++ echo v3.2.1-alice1
+ VERSION_VALUE=v3.2.1-alice1
++ eval 'echo $LIBFFI_ROOT'
[0 more errors; see full log]

Full log here.

[alibuild]

Error while checking build/O2/fullCI_slc9 for 7803bcf at 2026-10-10 01:37:

## sw/BUILD/o2codechecker-latest/log
100% tests passed, 0 tests failed out of 1


## sw/BUILD/ThePEG-latest/log
collect2: error: ld returned 1 exit status


## sw/BUILD/O2-full-system-test-latest/log
command /sw/slc9_x86-64/O2/slc9_x86-64-slc9_x86-64-local4/prodtests/full-system-test/dpl-workflow.sh had nonzero exit code 1


## sw/BUILD/o2checkcode-latest/log
--
========== List of errors found ==========
++ GRERR=0
++ grep -a -v clang-diagnostic-error error-log.txt
++ grep -a ' error:'
++ GRERR=1
++ [[ 1 == 0 ]]
++ mkdir -p /sw/INSTALLROOT/9351f68695656aa5678f348cbbd683196541e75e/slc9_x86-64/o2checkcode/1.0-local9/etc/modulefiles
++ alibuild-generate-module
+ HAS_BIN=
+ HAS_LIB=
+ HAS_CMAKE=
+ HAS_ROOT=
+ '[' 0 '!=' 0 ']'
+ cat
+ printf 'if ![ is-loaded '\''BASE/1.0'\'' ] {\n module load BASE/1.0\n}'
+ echo 'BUILD_REQUIRES=CMake alibuild-recipe-tools defaults-release'
BUILD_REQUIRES=CMake alibuild-recipe-tools defaults-release
+ FULL_BUILD_REQUIRES='MPFR json-c FairCMakeModules UUID ninja Alice-GRID-Utils ninja-fortran safe_int bz2 alibuild-recipe-tools CMake Python-modules-list defaults-release O2-customization date googlebenchmark double-conversion pytorch_cpuinfo'
+ echo 'FULL_BUILD_REQUIRES=MPFR json-c FairCMakeModules UUID ninja Alice-GRID-Utils ninja-fortran safe_int bz2 alibuild-recipe-tools CMake Python-modules-list defaults-release O2-customization date googlebenchmark double-conversion pytorch_cpuinfo'
FULL_BUILD_REQUIRES=MPFR json-c FairCMakeModules UUID ninja Alice-GRID-Utils ninja-fortran safe_int bz2 alibuild-recipe-tools CMake Python-modules-list defaults-release O2-customization date googlebenchmark double-conversion pytorch_cpuinfo
++ env
++ cut -f1 -d=
++ grep -v '^DEFAULT_'
++ grep -v ALIBUILD_RECIPE_TOOLS
++ grep -v PKGREVISION
++ grep REVISION
++ sed -e s/_REVISION//
+ for x in $(env | cut -f1 -d= | grep -v "^DEFAULT_" | grep -v PKGREVISION | grep -v ALIBUILD_RECIPE_TOOLS | grep REVISION | sed -e 's/_REVISION//')
++ eval 'echo $LIBFFI_REVISION'
+++ echo 14
+ REVISION_VALUE=14
++ eval 'echo $LIBFFI_VERSION'
+++ echo v3.2.1-alice1
+ VERSION_VALUE=v3.2.1-alice1
++ eval 'echo $LIBFFI_ROOT'
[0 more errors; see full log]

Full log here.