TrackGeometry.h File Reference

Lightweight O2 track-geometry helpers for propagation to cylindrical radii and TPC row/sector-edge accounting. More...

#include <algorithm>
#include <array>
#include <cmath>
#include <cstdint>
#include <limits>
#include <cstddef>
#include <vector>
#include <utility>
#include "CommonConstants/MathConstants.h"
#include "MathUtils/Utils.h"
#include "ReconstructionDataFormats/Track.h"
#include "TPCBase/Mapper.h"
#include "DetectorsBase/Propagator.h"

Go to the source code of this file.

Classes
struct	o2::recohelpers::TrackParametersAtRadius
	Global track state evaluated at a requested cylindrical radius. More...
struct	o2::recohelpers::TrackParametersAtRadiusBatchResult
	Structure-of-arrays result for batch cylindrical-radius propagation. More...
struct	o2::recohelpers::PrimaryTrackGeometryBatchResult
	Legacy compact batch result containing only position azimuth and fractional sector coordinate. More...
struct	o2::tpc::recohelpers::TPCPrimaryTrackSeed
	Reduced primary-track seed used by the TPC row evaluators. More...
struct	o2::tpc::recohelpers::TPCSectorEdgeConfig
	Configuration for TPC row acceptance and sector-edge classification. More...
struct	o2::tpc::recohelpers::TPCSectorEdgeResult
	Result of one TPC row/sector-edge evaluation. More...
struct	o2::tpc::recohelpers::TPCSectorEdgeBatchResult
	Structure-of-arrays batch result for the TPC row/sector-edge evaluators. More...
struct	o2::tpc::recohelpers::TrajectoryPoint
	Internal global trajectory sample at one TPC row-centre radius. More...

Namespaces
namespace	o2
	a couple of static helper functions to create timestamp values for CCDB queries or override obsolete objects
namespace	o2::recohelpers
namespace	o2::tpc
	Global TPC definitions and constants.
namespace	o2::tpc::recohelpers

Enumerations
enum class	o2::recohelpers::TrackParametersStatus : int32_t {   o2::recohelpers::OK = 0 , o2::recohelpers::InvalidInput = 1 , o2::recohelpers::UnreachableRadius = 2 , o2::recohelpers::WrongDirection = 3 ,   o2::recohelpers::PropagationFailed = 4 , o2::recohelpers::MomentumInvalid = 5 }
	Status returned by the cylindrical-radius track-parameter evaluators. More...

Functions
float	o2::recohelpers::statePhiPos (const TrackParametersAtRadius &state)
	Global azimuth of the propagated position, atan2(y,x), or NaN for an invalid state.
float	o2::recohelpers::statePhiMom (const TrackParametersAtRadius &state)
	Global azimuth of the propagated momentum, atan2(py,px), or NaN for an invalid state.
float	o2::recohelpers::stateTgl (const TrackParametersAtRadius &state)
	tan(lambda)=pz/pT of the propagated state, or NaN for an invalid state.
float	o2::recohelpers::dSector (float phi, int nSectors=18, float sectorPhaseRad=0.f)
	Fractional azimuthal position inside a periodic sector pattern.
float	o2::recohelpers::stateDSector (const TrackParametersAtRadius &state, int nSectors=18, float sectorPhaseRad=0.f)
	dSector() evaluated from the propagated global position azimuth.
o2::track::TrackPar	o2::recohelpers::makeTrackParFromPrimaryApproximation (float phi, float tgl, float qpt, float vx=0.f, float vy=0.f, float vz=0.f)
	Build an O2 TrackPar from a reduced primary-like state.
o2::track::TrackPar	o2::recohelpers::makePrimaryTrackPar (float phi, float tgl, float qpt, float vz=0.f)
	Backward-compatible reduced-primary constructor used by existing commissioning code.
bool	o2::recohelpers::extractGlobalState (const o2::track::TrackPar &track, o2::track::TrackPar::dim3_t &xyz, o2::track::TrackPar::dim3_t &pxyz)
	Extract finite global position and momentum from an O2 TrackPar.
bool	o2::recohelpers::directionMatches (o2::track::DirType dir, float drds)
	Check whether the radial derivative is compatible with the requested propagation direction.
TrackParametersAtRadius	o2::recohelpers::getParametersAtRadiusH (const o2::track::TrackPar &track, float radius, float bzKG, o2::track::DirType dir=o2::track::DirType::DirOutward)
	H transport: analytic helix intersection with a cylindrical radius in uniform Bz.
TrackParametersAtRadius	o2::recohelpers::getParametersAtRadiusK0 (const o2::track::TrackPar &track, float radius, float bzKG, o2::track::DirType dir=o2::track::DirType::DirOutward)
	K0 transport: O2 TrackPar propagation to a cylindrical radius in Bz, without material correction.
float	o2::recohelpers::phiAtRadius (const o2::track::TrackPar &track, float radius, float bzKG, o2::track::DirType dir=o2::track::DirType::DirOutward)
	Backward-compatible scalar wrapper returning only the propagated position azimuth using K0.
float	o2::recohelpers::dSectorAtRadius (const o2::track::TrackPar &track, float radius, float bzKG, int nSectors=18, o2::track::DirType dir=o2::track::DirType::DirOutward, float sectorPhaseRad=0.f)
	Backward-compatible scalar wrapper returning only the propagated fractional sector coordinate using K0.
float	o2::recohelpers::primaryPhiAtRadius (float phi, float tgl, float qpt, float radius, float bzKG, float vz=0.f)
	Position azimuth at radius for the reduced primary-like parameterization, evaluated with K0.
float	o2::recohelpers::primaryDSectorAtRadius (float phi, float tgl, float qpt, float radius, float bzKG, int nSectors=18, float vz=0.f, float sectorPhaseRad=0.f)
	Fractional sector coordinate at radius for the reduced primary-like parameterization, evaluated with K0.
template<typename Evaluator >
TrackParametersAtRadiusBatchResult	o2::recohelpers::primaryTrackParametersAtRadiusBatch (const float *phi, const float *tgl, const float *qpt, const float *vx, const float *vy, const float *vz, std::size_t n, float radius, float bzKG, int nSectors, float sectorPhaseRad, Evaluator &&evaluate)
TrackParametersAtRadiusBatchResult	o2::recohelpers::primaryTrackParametersAtRadiusHBatch (const float *phi, const float *tgl, const float *qpt, const float *vx, const float *vy, const float *vz, std::size_t n, float radius, float bzKG, int nSectors=18, float sectorPhaseRad=0.f)
	Batch H transport for reduced primary-like inputs.
TrackParametersAtRadiusBatchResult	o2::recohelpers::primaryTrackParametersAtRadiusK0Batch (const float *phi, const float *tgl, const float *qpt, const float *vx, const float *vy, const float *vz, std::size_t n, float radius, float bzKG, int nSectors=18, float sectorPhaseRad=0.f)
	Batch K0 transport for reduced primary-like inputs.
o2::track::TrackPar	o2::recohelpers::makeTrackParFromLocalParameters (float x, float alpha, float y, float z, float snp, float tgl, float qpt, int absCharge=1)
	Build an O2 TrackPar from the standard local O2 track parameterization.
template<typename Evaluator >
TrackParametersAtRadiusBatchResult	o2::recohelpers::localTrackParametersAtRadiusBatch (const float *x, const float *alpha, const float *y, const float *z, const float *snp, const float *tgl, const float *qpt, std::size_t n, float radius, float bzKG, int nSectors, float sectorPhaseRad, Evaluator &&evaluate)
TrackParametersAtRadiusBatchResult	o2::recohelpers::localTrackParametersAtRadiusHBatch (const float *x, const float *alpha, const float *y, const float *z, const float *snp, const float *tgl, const float *qpt, std::size_t n, float radius, float bzKG, int nSectors=18, float sectorPhaseRad=0.f)
	Batch H transport for tracks supplied in local O2 parameterization.
TrackParametersAtRadiusBatchResult	o2::recohelpers::localTrackParametersAtRadiusK0Batch (const float *x, const float *alpha, const float *y, const float *z, const float *snp, const float *tgl, const float *qpt, std::size_t n, float radius, float bzKG, int nSectors=18, float sectorPhaseRad=0.f)
	Batch K0 transport for tracks supplied in local O2 parameterization.
std::vector< float >	o2::recohelpers::primaryPhiAtRadiusBatch (const float *phi, const float *tgl, const float *qpt, const float *vz, std::size_t n, float radius, float bzKG)
	Backward-compatible batch wrappers retained for existing commissioning notebooks/tests.
std::vector< float >	o2::recohelpers::primaryDSectorAtRadiusBatch (const float *phi, const float *tgl, const float *qpt, const float *vz, std::size_t n, float radius, float bzKG, int nSectors=18, float sectorPhaseRad=0.f)
PrimaryTrackGeometryBatchResult	o2::recohelpers::primaryTrackGeometryAtRadiusBatch (const float *phi, const float *tgl, const float *qpt, const float *vz, std::size_t n, float radius, float bzKG, int nSectors=18, float sectorPhaseRad=0.f)

TPC row and sector-edge accounting
These helpers evaluate the first outward TPC trajectory branch at sampled Mapper row radii and classify every accepted crossed row using the physical active-pad edge plus an optional inward guard.
enum class	o2::tpc::recohelpers::SectorEdgeStatus : int32_t {   o2::tpc::recohelpers::OK = 0 , o2::tpc::recohelpers::InvalidInput = 1 , o2::tpc::recohelpers::NoRowsCrossed = 2 , o2::tpc::recohelpers::PropagationFailed = 3 ,   o2::tpc::recohelpers::FieldNotInitialized = 4 }
	Status returned by the TPC row/sector-edge evaluators. More...
void	o2::tpc::recohelpers::appendTrajectoryState (std::vector< o2::recohelpers::TrackParametersAtRadius > &trajectory, const TrajectoryPoint &p, float qpt, float tgl)
	Debug-only row state; trajectory[row] is the state at that sampled TPC row. Append even the first state rejected by maxSnp. With tracing disabled no momentum conversion is performed.
void	o2::tpc::recohelpers::setMaskBit (std::array< uint32_t, 5 > &mask, int row)
	Set one of the 152 TPC row bits in the five-word row mask.
int	o2::tpc::recohelpers::regionForRow (const o2::tpc::Mapper &mapper, int row)
	Return the Mapper pad-region index containing a global TPC row, or -1 if none.
float	o2::tpc::recohelpers::rowRadius (const o2::tpc::Mapper &mapper, int row)
	Current sampled TPC row radius [cm]; F6 physical pad-centre correction remains pending.
float	o2::tpc::recohelpers::rowLengthRadial (const o2::tpc::Mapper &mapper, int row)
	Radial row thickness, taken from the Mapper pad height [cm].
float	o2::tpc::recohelpers::rowActiveHalfWidth (const o2::tpc::Mapper &mapper, int row)
	Active half-width of one TPC row in local-y from Mapper pad count and pad width [cm].
float	o2::tpc::recohelpers::trajectoryRadialSnp (const TrajectoryPoint &p)
	Radial-frame sin(phiMom-phiPos); independent of the O2 TrackPar alpha rotation.
float	o2::tpc::recohelpers::trajectoryLocalSnp (const TrajectoryPoint &p)
	Backward-compatible internal spelling; use trajectoryRadialSnp for new code.
bool	o2::tpc::recohelpers::rowWithinAcceptance (const TrajectoryPoint &p, const TPCSectorEdgeConfig &cfg)
	True when a valid row-centre trajectory point satisfies the configured z and snp acceptance.
bool	o2::tpc::recohelpers::reachedMaxSnp (const TrajectoryPoint &p, const TPCSectorEdgeConfig &cfg)
	True when the radial-frame inclination reaches the configured stopping boundary.
bool	o2::tpc::recohelpers::trackOutwardReference (const o2::track::TrackPar &track, float &radius)
	Validate the complete input state and report its global reference radius. An outward-only row query does not back-propagate to rows inside this radius.
TrajectoryPoint	o2::tpc::recohelpers::helixAtRadius (const o2::track::TrackPar &track, float radius, float bzKG)
	One TPC row trajectory sample from a complete O2 local five-parameter track.
TrajectoryPoint	o2::tpc::recohelpers::primaryHelixAtRadius (const TPCPrimaryTrackSeed &seed, float radius)
	Legacy reduced-primary adapter to the same complete-track H implementation.
void	o2::tpc::recohelpers::accumulateRow (const o2::tpc::Mapper &mapper, int row, const TrajectoryPoint &p, float rowLength, const TPCSectorEdgeConfig &cfg, TPCSectorEdgeResult &out)
	Apply acceptance and classify one crossed row as Dead, Excluded, or Available.
TPCSectorEdgeResult	o2::tpc::recohelpers::sectorEdgeHelixRows (const o2::track::TrackPar &track, float bzKG, const TPCSectorEdgeConfig &cfg={}, std::vector< o2::recohelpers::TrackParametersAtRadius > *trajectory=nullptr)
	H row evaluator: analytic helix sampled at the current Mapper row radii.
TPCSectorEdgeResult	o2::tpc::recohelpers::sectorEdgeHelixRows (const TPCPrimaryTrackSeed &seed, const TPCSectorEdgeConfig &cfg={}, std::vector< o2::recohelpers::TrackParametersAtRadius > *trajectory=nullptr)
	Reduced-primary compatibility adapter: construct TrackPar and call the full H evaluator.
bool	o2::tpc::recohelpers::plausibleFirstOutwardStep (float dr, float ds, float tgl, float maxSnp)
	Conservative path-continuity guard against a later outward orbit.
TPCSectorEdgeResult	o2::tpc::recohelpers::sectorEdgeO2PropagatorRows (const o2::track::TrackPar &inputTrack, float bzKG, const TPCSectorEdgeConfig &cfg={}, std::vector< o2::recohelpers::TrackParametersAtRadius > *trajectory=nullptr)
	K row evaluator: O2 Propagator traversal of TPC row radii without material correction.
TPCSectorEdgeResult	o2::tpc::recohelpers::sectorEdgeO2PropagatorRows (const TPCPrimaryTrackSeed &seed, const TPCSectorEdgeConfig &cfg={}, std::vector< o2::recohelpers::TrackParametersAtRadius > *trajectory=nullptr)
	Reduced-primary compatibility adapter to complete-state K row evaluation.
TPCSectorEdgeResult	o2::tpc::recohelpers::sectorEdgeStackLinear (const o2::track::TrackPar &track, float bzKG, const TPCSectorEdgeConfig &cfg={}, std::vector< o2::recohelpers::TrackParametersAtRadius > *trajectory=nullptr)
	L row evaluator: stack-local linear approximation to the analytic helix.
TPCSectorEdgeResult	o2::tpc::recohelpers::sectorEdgeStackLinear (const TPCPrimaryTrackSeed &seed, const TPCSectorEdgeConfig &cfg={}, std::vector< o2::recohelpers::TrackParametersAtRadius > *trajectory=nullptr)
	Reduced-primary compatibility adapter to complete-state L row evaluation.
template<typename Evaluator >
TPCSectorEdgeBatchResult	o2::tpc::recohelpers::sectorEdgeBatch (const float *phi, const float *tgl, const float *qpt, const float *vz, std::size_t n, float bzKG, const TPCSectorEdgeConfig &cfg, Evaluator &&evaluate)
TPCSectorEdgeBatchResult	o2::tpc::recohelpers::sectorEdgeHelixRowsBatch (const float *phi, const float *tgl, const float *qpt, const float *vz, std::size_t n, float bzKG, const TPCSectorEdgeConfig &cfg={})
	Batch wrapper for the analytic H TPC row evaluator.
TPCSectorEdgeBatchResult	o2::tpc::recohelpers::sectorEdgeStackLinearBatch (const float *phi, const float *tgl, const float *qpt, const float *vz, std::size_t n, float bzKG, const TPCSectorEdgeConfig &cfg={})
	Batch wrapper for the stack-linear L TPC row evaluator.
TPCSectorEdgeBatchResult	o2::tpc::recohelpers::sectorEdgeO2PropagatorRowsBatch (const float *phi, const float *tgl, const float *qpt, const float *vz, std::size_t n, float bzKG, const TPCSectorEdgeConfig &cfg={})
	Batch wrapper for the O2 Propagator K TPC row evaluator, without material correction.
template<typename Evaluator >
TPCSectorEdgeBatchResult	o2::tpc::recohelpers::localSectorEdgeBatch (const float *x, const float *alpha, const float *y, const float *z, const float *snp, const float *tgl, const float *qpt, std::size_t n, float bzKG, const TPCSectorEdgeConfig &cfg, Evaluator &&evaluate)
	Evaluate row acceptance for a batch of complete O2 local 5D track states. Input arrays are x, alpha, y, z, snp, tgl, q/pT; all are mandatory. absCharge=1 is currently used by the convenience constructor, as in the generic state-at-radius batch interface. For multi-charge tracks use the scalar TrackPar API.
TPCSectorEdgeBatchResult	o2::tpc::recohelpers::localSectorEdgeHelixRowsBatch (const float *x, const float *alpha, const float *y, const float *z, const float *snp, const float *tgl, const float *qpt, std::size_t n, float bzKG, const TPCSectorEdgeConfig &cfg={})
TPCSectorEdgeBatchResult	o2::tpc::recohelpers::localSectorEdgeStackLinearBatch (const float *x, const float *alpha, const float *y, const float *z, const float *snp, const float *tgl, const float *qpt, std::size_t n, float bzKG, const TPCSectorEdgeConfig &cfg={})
TPCSectorEdgeBatchResult	o2::tpc::recohelpers::localSectorEdgeO2PropagatorRowsBatch (const float *x, const float *alpha, const float *y, const float *z, const float *snp, const float *tgl, const float *qpt, std::size_t n, float bzKG, const TPCSectorEdgeConfig &cfg={})

Detailed Description

Lightweight O2 track-geometry helpers for propagation to cylindrical radii and TPC row/sector-edge accounting.

The header provides two related layers:

1. o2::recohelpers
   • propagation of an o2::track::TrackPar to a cylindrical radius;
   • H: fast analytic helix transport in a uniform Bz field;
   • K0: O2 TrackPar parameter propagation in Bz, without material correction;
   • derived global position/momentum, position azimuth, momentum azimuth, tan(lambda), and fractional sector position;
   • scalar and batch interfaces for primary-like and local O2 track parameters.
2. o2::tpc::recohelpers
   • TPC row sampling geometry from o2::tpc::Mapper (F6 centre correction pending);
   • H: analytic-helix row traversal;
   • L: stack-local linear approximation derived from helix endpoints;
   • K: O2 Propagator row traversal with MatCorrType::USEMatCorrNONE;
   • row counts, approximate track lengths, and 152-row masks for Crossed, Dead, Excluded, and Available rows;
   • configurable longitudinal, local-inclination, and active-pad-edge guard acceptance.

The TPC classification currently samples the Mapper's inner-row reference radius (F6: pad-centre correction pending). Dead is defined by the physical Mapper active-pad boundary, while Excluded is the additional configurable guard measured inward from that active-pad edge. The nominal 20-degree sector boundary is not the guard reference.

This header is intentionally self-contained and header-only so the same definitions can be used from compiled O2 code and from PyROOT/commissioning wrappers.

Propagation hierarchy and implementation status

The frozen TrackGeometry design distinguishes the following transport levels:

• H — analytic helix, constant signed Bz, no material. Implemented for the generic state-at-radius API and for TPC row traversal.
• L — stack-local linear approximation. Implemented for the TPC row/length approximation path only.
• K0 — O2 TrackPar / TrackParametrization, constant signed Bz, no material. Implemented for the generic state-at-radius API.
• K1 — O2 Propagator, initialized O2 magnetic-field machinery, material OFF. The current TPC row evaluator named K already uses Propagator with MatCorrType::USEMatCorrNONE and therefore exercises the K1 transport ingredients for this bounded TPC-row use case. The common generic K0/K1/K2 state-at-radius dispatch and final public K1 naming are not yet implemented.
• K2 — O2 Propagator, initialized O2 magnetic-field machinery, material ON. Not yet implemented. The production material mode and material-map initialization must be explicitly verified during K2 commissioning before this mode is exposed.

The intended diagnostic decomposition is: H-K0 = implementation/convention closure, K1-K0 = realistic-field/Propagator effect, K2-K1 = material effect.

Planned functionality is documented here deliberately so that the public contract is visible before implementation; planned modes must not be presented by wrappers as available until the corresponding C++ path and validation exist.

Definition in file TrackGeometry.h.