Skip to content

TrackTools: shared TrackGeometry utilities for track acceptance and PID studies" - #15999

Merged
shahor02 merged 4 commits into
AliceO2Group:devfrom
miranov25:feature/track-geometry-tools
Oct 24, 2026
Merged

TrackTools: shared TrackGeometry utilities for track acceptance and PID studies"#15999
shahor02 merged 4 commits into
AliceO2Group:devfrom
miranov25:feature/track-geometry-tools

Conversation

@miranov25

@miranov25 miranov25 commented Oct 23, 2026

Copy link
Copy Markdown
Contributor

Motivation

TrackTools is a shared collection of C++ utilities; TrackGeometry is its first component. It provides reusable geometry observables to quantify how shortened usable tracks affect tracking efficiency, fake associations, dE/dx PID resolution, biases, and comparisons between reconstruction passes, data and simulation.

The initial application is TPC sector-edge acceptance. The generic at-radius track state can also be queried at reachable TPC, TRD and TOF radii.

Implementation

  • Header-only TrackGeometry.h, using the complete O2 TrackPar state.
  • At-radius H (analytic helix) and K0 (O2 propagation) queries.
  • TPC sector-edge row, mask and approximate length evaluation with H/L/K methods. L is the candidate fast per-stack approximation; H/K are reference calculations used to establish its accuracy.
  • Configurable active-pad-edge guards and independent available-row or length selections.
  • C++ physics-analysis and step-by-step interactive ROOT examples; supplementary Python/AliasDataFrame demonstration.

Files in this PR (7)

  • Common/TrackTools/include/TrackGeometry.h — header-only geometry implementation.
  • Common/TrackTools/test/python/conftest.py — PyROOT test setup.
  • Common/TrackTools/test/python/test_full_state_radius.py — full-state at-radius tests.
  • Common/TrackTools/test/python/test_sector_rows_primary_baseline.py — TPC row and guard tests.
  • Common/TrackTools/test/README_TESTS.md — test instructions.
  • Common/TrackTools/README.md — C++/ROOT usage, motivation and Python example.
  • Common/TrackTools/docs/figures/trackgeometry_synthetic_5d_available_rows.png — synthetic geometry illustration.

Validation

  • O2 portable PyROOT pytest against this header: 12 passed, 1 expected failure (F6 row-centre sampling).
  • ROOT ACLiC full-5D demonstration: successful.
  • Two-guard example: 143 versus 134 available rows for guards of 0.5 and 1.5 cm; with a 140-row requirement, the first accepts and the second rejects.
  • H–L difference for this near-edge example: 6 available rows and 4.58417 cm; precision domain and speedup are not yet established by this example.

This Draft PR requests technical review of the shared C++ interface, its geometry semantics and its proposed O2 placement. It is not a claim of completed physics validation.

@miranov25
miranov25 requested a review from a team as a code owner October 23, 2026 18:12
@alibuild alibuild mentioned this pull request Oct 23, 2026
Closed
@shahor02

shahor02 commented Oct 23, 2026

Copy link
Copy Markdown
Collaborator

@miranov25 see the formatting / licence problems reported by CI.

I don't see any CMakeLists, this header cannot be installed. See how it is done for Common/Constant, which is also a header-only library.
Note that O2 headers should be in the include/<libname>/ directory, not in the include/

miranov25 added a commit to miranov25/AliceO2 that referenced this pull request Oct 23, 2026
@miranov25
TrackTools: integrate header-only geometry interface with O2 packaging
d13595b 
Address the maintainer feedback on AliceO2 PR AliceO2Group#15999.

- Register a public header-only O2::TrackTools interface in Common CMake.
- Propagate the required O2::CommonConstants, MathUtils,
  ReconstructionDataFormats, TPCBase and DetectorsBase dependencies.
- Install the header under include/TrackTools/TrackGeometry.h.
- Reuse the clang-format bot's formatted implementation without changing
  numerical algorithms; add the O2 copyright notice and include guard.
- Update PyROOT tests and README to include TrackTools/TrackGeometry.h.
- Correct outdated portable-test scope and build-install documentation.

Exact changed-file inventory (7 paths):
  - Common/CMakeLists.txt
  - Common/TrackTools/CMakeLists.txt
  - Common/TrackTools/include/TrackTools/TrackGeometry.h
  - Common/TrackTools/README.md
  - Common/TrackTools/test/README_TESTS.md
  - Common/TrackTools/test/python/conftest.py
  - Common/TrackTools/include/TrackGeometry.h (removed)

Validation: static checks of the unchanged formatted C++ implementation,
header guard, license text, public includes, LF endings and CMake wiring.
O2 configure/build and PyROOT tests must be rerun on alma2; not claimed here.

No unrelated line-ending changes or numerical-tolerance modifications.
miranov25 added a commit to miranov25/AliceO2 that referenced this pull request Oct 23, 2026
@miranov25
TrackTools: update Common CMake copyright header
62ac9f7 
Replace the obsolete copyright notice in Common/CMakeLists.txt with the current ALICE O2 standard notice.

This resolves the copyright CI finding on PR AliceO2Group#15999.

Exact changed-file inventory:
- Common/CMakeLists.txt (copyright notice only)

No CMake logic, C++ source, physics calculations, tests, or tolerances changed.

Validation:
- Exact replacement checksum verified
- One-file Git diff reviewed
- git diff --check passed
- Canonical dEdxAI TrackGeometry: 26 passed, 1 XFAIL
- O2 TrackTools portable tests: 12 passed, 1 XFAIL
- ROOT/ACLiC demonstration: PASS

The previous physics test results refer to the unchanged TrackGeometry header.
@miranov25

miranov25 commented Oct 23, 2026

Copy link
Copy Markdown
Contributor Author

Thank you for the review. We have addressed the reported TrackTools issues:

  • Added CMake registration and header-only library installation.
  • Moved the public header to include/TrackTools/.
  • Corrected the copyright headers and applied clang-format.
  • Revalidated the implementation: 12 passed / 1 expected XFAIL in O2, 26 passed / 1 expected XFAIL in dEdxAI, and successful ROOT/ACLiC compilation.

The clang-format, copyright and whitespace checks now pass.

Two formatting checks remain failing, but both concern files unrelated to this PR:

  1. Analysis/DataModel/include/Analysis/Jet.h — #pragma once.
  2. Detectors/TPC/reconstruction/macro/findKrBoxCluster.C — CRLF line endings.

@shahor02

shahor02 commented Oct 24, 2026

Copy link
Copy Markdown
Collaborator

@vkucera any idea why the format checker complains about the files not touched by the PR?

@shahor02

shahor02 commented Oct 24, 2026

Copy link
Copy Markdown
Collaborator

@miranov25 note that your CMakeLists does not install the scripts, they will be available only from the source directory but not from the built module.

@vkucera

vkucera commented Oct 24, 2026

Copy link
Copy Markdown
Collaborator

@vkucera any idea why the format checker complains about the files not touched by the PR?

Because the check scans the entire repository and runs on the head of the PR branch which is 6 years old.

@shahor02

shahor02 commented Oct 24, 2026

Copy link
Copy Markdown
Collaborator

Hm, indeed, thanks.
@miranov25 , please rebase your branch to dev.

@miranov25
TrackTools: introduce full-state TrackGeometry C++ utilities and port…
64e5484 
…able tests

Introduce TrackGeometry as the first component of the shared TrackTools
package for O2 reconstruction, O2Physics and calibration workflows.

The goal is to provide consistent geometry-derived track observables
for detector acceptance, tracking-quality and dE/dx PID studies.

C++ implementation:
- Accept complete O2 TrackPar states, including displaced tracks.
- Provide analytic helix (H) and O2 transport (K0) queries at
  requested cylindrical radii, relevant to TPC, TRD and TOF.
- Provide TPC row-geometry evaluation with H, per-stack linear (L)
  and O2 propagator (K) methods.
- Calculate crossed, dead, guard-excluded and available TPC rows,
  geometrical lengths and 152-row classification masks.
- Support configurable sector-edge guards and acceptance limits.
- Provide reduced-primary compatibility adapters.
- Use H/K as references for validating the accuracy of fast L.

Portable tests:
- conftest.py: ROOT/PyROOT setup for standalone O2 testing.
- test_full_state_radius.py: full-track state-at-radius checks.
- test_sector_rows_primary_baseline.py: TPC row baseline checks.
- README_TESTS.md: portable test execution instructions.

The implementation enables configurable geometrical selections
to study shortened tracks and their impact on tracking and PID.

This commit does not include the main README, physics figure,
O2 CMake registration or the extended full-state TPC test suite.
Those are handled separately. Numerical performance and remaining
physics-validation issues are tracked in the project CRR.
@miranov25
TrackTools: document TrackGeometry physics motivation and C++ usage
a300256 
Document TrackGeometry as the first component of the shared
TrackTools package.

Explain the impact of geometrically shortened TPC tracks on
tracking efficiency, fake associations, dE/dx PID resolution,
biases and comparisons between data, MC and reconstruction passes.

Document the purpose of the three geometry methods:
- L: candidate fast per-stack linear approximation.
- H: analytic helix reference for precision studies.
- K: O2 propagation reference.

Provide practical user examples:
- C++ analysis with two configurable sector-edge guard widths.
- Verified interactive ROOT session using a complete 5D track.
- Independent available-row selections and H/L comparisons.
- Python/AliasDataFrame visualization with synthetic primary
  and secondary trajectories.

Document the committed portable tests, execution instructions,
geometry conventions and the distinction between predicted
available rows and measured clusters.

Include the synthetic geometry figure as supplementary QA.
Detailed physics-validation findings remain in the project CRR.
@miranov25
TrackTools: integrate header-only geometry interface with O2 packaging
b61f71c 
Address the maintainer feedback on AliceO2 PR AliceO2Group#15999.

- Register a public header-only O2::TrackTools interface in Common CMake.
- Propagate the required O2::CommonConstants, MathUtils,
  ReconstructionDataFormats, TPCBase and DetectorsBase dependencies.
- Install the header under include/TrackTools/TrackGeometry.h.
- Reuse the clang-format bot's formatted implementation without changing
  numerical algorithms; add the O2 copyright notice and include guard.
- Update PyROOT tests and README to include TrackTools/TrackGeometry.h.
- Correct outdated portable-test scope and build-install documentation.

Exact changed-file inventory (7 paths):
  - Common/CMakeLists.txt
  - Common/TrackTools/CMakeLists.txt
  - Common/TrackTools/include/TrackTools/TrackGeometry.h
  - Common/TrackTools/README.md
  - Common/TrackTools/test/README_TESTS.md
  - Common/TrackTools/test/python/conftest.py
  - Common/TrackTools/include/TrackGeometry.h (removed)

Validation: static checks of the unchanged formatted C++ implementation,
header guard, license text, public includes, LF endings and CMake wiring.
O2 configure/build and PyROOT tests must be rerun on alma2; not claimed here.

No unrelated line-ending changes or numerical-tolerance modifications.
@miranov25
TrackTools: install portable Python tests
48ea923
@miranov25
miranov25 force-pushed the feature/track-geometry-tools branch from 2cf8b8b to 48ea923 Compare October 24, 2026 13:18
@miranov25

miranov25 commented Oct 24, 2026

Copy link
Copy Markdown
Contributor Author

Thanks. The branch has now been rebased onto the current dev.

@shahor02
shahor02 merged commit 25a9d44 into AliceO2Group:dev Oct 24, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@shahor02 shahor02 shahor02 approved these changes

Assignees

No one assigned

Labels

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@miranov25 @shahor02 @vkucera