Extrapolator.h

Go to the documentation of this file.

/*
   Copyright (C) 2002-2026 CERN for the benefit of the ATLAS collaboration
 */

// Extrapolator.h, (c) ATLAS Detector software
 
#ifndef TRKEXTOOLS_EXTRAPOLATOR_H
#define TRKEXTOOLS_EXTRAPOLATOR_H
 
#include "LocalExtrapolatorCache.h" //for Trk::Cache
#include "ExtrUniquePtrHolder.h"
 
#include "TrkExInterfaces/IExtrapolator.h"
#include "TrkExInterfaces/IMaterialEffectsUpdator.h" // in tool handle array
#include "TrkExInterfaces/INavigator.h"              //in tool handle
#include "TrkExInterfaces/IPropagator.h"             //in tool handle
// Trk
#include "TrkEventPrimitives/ParticleHypothesis.h"  //enum
#include "TrkEventPrimitives/PropDirection.h"       //enum
#include "TrkGeometry/MagneticFieldProperties.h"    //member
#include "TrkNeutralParameters/NeutralParameters.h" //typedef
#include "TrkParameters/TrackParameters.h" //template parameter in typedef
#include "TrkSurfaces/BoundaryCheck.h"     //template parameter in typedef
// Amg
#include "EventPrimitives/EventPrimitives.h" //Amg::Vector etc
// xAOD
#include "xAODTracking/NeutralParticle.h" //typedef
#include "xAODTracking/TrackParticle.h"   //typedef
// Gaudi/StoreGate
#include "AthenaBaseComps/AthAlgTool.h"
#include "AthenaBaseComps/AthCheckedComponent.h"
#include "GaudiKernel/ToolHandle.h"
#include <Gaudi/Accumulators.h>
// STL
#include <cstring>
#include <map>
#include <memory>
#include <utility>
#include <vector>
 
class MsgStream;
class EventContext;
 
namespace Trk {
class Track;
class Surface;
class Layer;
class Volume;
class DetachedTrackingVolume;
class TrackingGeometry;
class TrackParticleBase;
class IDynamicLayerCreator;
class IMultipleScatteringUpdator;
class IEnergyLossUpdator;
class AlignableTrackingVolume;
class ExtrapolationCache;
class TrackingVolume;
 
 
using TrackParametersUVector = std::vector<std::unique_ptr<Trk::TrackParameters>>;
using DestSurf = std::pair<const Surface*, BoundaryCheck>;

 
class Extrapolator final
  : public AthCheckedComponent<AthAlgTool>
  , virtual public IExtrapolator
{
public:

  Extrapolator(const std::string&, const std::string&, const IInterface*);
  ~Extrapolator();

  virtual StatusCode initialize() override;
  virtual StatusCode finalize() override;

  virtual std::unique_ptr<TrackParameters> extrapolateDirectly(
    const EventContext& ctx,
    const TrackParameters& parm,
    const Surface& sf,
    PropDirection dir = anyDirection,
    const BoundaryCheck& bcheck = true,
    ParticleHypothesis particle = pion) const override final;

  virtual std::unique_ptr<NeutralParameters> extrapolate(
    const NeutralParameters& parameters,
    const Surface& sf,
    PropDirection dir = anyDirection,
    const BoundaryCheck& bcheck = true) const override final;

  virtual std::unique_ptr<TrackParameters> extrapolate(
    const EventContext& ctx,
    const TrackParameters& parm,
    const Surface& sf,
    PropDirection dir = anyDirection,
    const BoundaryCheck& bcheck = true,
    ParticleHypothesis particle = pion,
    MaterialUpdateMode matupmode = addNoise,
    Trk::ExtrapolationCache* cache = nullptr) const override final;

  virtual TrackParametersUVector extrapolateStepwise(
    const EventContext& ctx,
    const TrackParameters& parm,
    const Surface& sf,
    PropDirection dir = anyDirection,
    const BoundaryCheck& bcheck = true,
    ParticleHypothesis particle = pion) const override final;

  virtual std::unique_ptr<TrackParameters> extrapolateTrack(
    const EventContext& ctx,
    const Track& trk,
    const Surface& sf,
    PropDirection dir = anyDirection,
    const BoundaryCheck& bcheck = true,
    ParticleHypothesis particle = pion,
    MaterialUpdateMode matupmode = addNoise,
    Trk::ExtrapolationCache* cache = nullptr) const override final;

  virtual TrackParametersUVector extrapolateBlindly(
    const EventContext& ctx,
    const TrackParameters& parm,
    PropDirection dir = anyDirection,
    const BoundaryCheck& bcheck = true,
    ParticleHypothesis particle = pion,
    const Volume* boundaryVol = nullptr) const override final;

  virtual std::vector<const TrackStateOnSurface*>* extrapolateM(
    const EventContext& ctx,
    const TrackParameters& parameters,
    const Surface& sf,
    PropDirection dir,
    const BoundaryCheck& bcheck,
    ParticleHypothesis particle = pion,
    Trk::ExtrapolationCache* cache = nullptr) const override final;

  virtual std::unique_ptr<std::vector<std::pair<std::unique_ptr<Trk::TrackParameters>, int>>>
  collectIntersections(
    const EventContext& ctx,
    const Trk::TrackParameters& parm,
    Trk::PropDirection dir,
    Trk::ParticleHypothesis particle,
    int destination = 3) const override final;

  virtual std::pair<std::unique_ptr<TrackParameters>, const Layer*> extrapolateToNextActiveLayerM(
    const EventContext& ctx,
    const TrackParameters& parm,
    PropDirection dir,
    const BoundaryCheck& bcheck,
    std::vector<const Trk::TrackStateOnSurface*>& material,
    ParticleHypothesis particle = pion,
    MaterialUpdateMode matupmode = addNoise) const override final;

  virtual std::unique_ptr<TrackParameters> extrapolateToVolume(
    const EventContext& ctx,
    const TrackParameters& parm,
    const Trk::TrackingVolume& vol,
    PropDirection dir = anyDirection,
    ParticleHypothesis particle = pion) const override final;

  virtual const TrackingGeometry* trackingGeometry() const override final;
 
private:
 
  typedef std::vector<std::pair<std::unique_ptr<Trk::TrackParameters>, int>> identifiedParameters_t;
  Trk::CacheOwnedPtr<Trk::TrackParameters> extrapolateImpl(
    const EventContext& ctx,
    Cache& cache,
    const IPropagator& prop,
    Trk::CacheOwnedPtr<Trk::TrackParameters> parm,
    const Surface& sf,
    PropDirection dir = anyDirection,
    const BoundaryCheck& bcheck = true,
    ParticleHypothesis particle = pion,
    MaterialUpdateMode matupmode = addNoise) const;

  TrackParametersUVector extrapolateStepwiseImpl(
    const EventContext& ctx,
    const IPropagator& prop,
    const TrackParameters& parm,
    const Surface& sf,
    PropDirection dir = anyDirection,
    const BoundaryCheck& bcheck = true,
    ParticleHypothesis particle = pion) const;

  Trk::CacheOwnedPtr<Trk::TrackParameters> extrapolateImpl(
    const EventContext& ctx,
    Cache& cache,
    const IPropagator& prop,
    Trk::CacheOwnedPtr<Trk::TrackParameters> parm,
    const std::vector<MaterialEffectsOnTrack>& sfMeff,
    const TrackingVolume& tvol,
    PropDirection dir,
    ParticleHypothesis particle = pion,
    MaterialUpdateMode matupmode = addNoise) const;

  Trk::CacheOwnedPtr<Trk::TrackParameters> extrapolateImpl(
    const EventContext& ctx,
    Cache& cache,
    Trk::CacheOwnedPtr<Trk::TrackParameters> parm,
    const Surface& sf,
    PropDirection dir = anyDirection,
    const BoundaryCheck& bcheck = true,
    ParticleHypothesis particle = pion,
    MaterialUpdateMode matupmode = addNoise,
    Trk::ExtrapolationCache* extrapolationCache = nullptr) const;

  std::unique_ptr<TrackParameters> extrapolateDirectlyImpl(
    const EventContext& ctx,
    const IPropagator& prop,
    const TrackParameters& parm,
    const Surface& sf,
    PropDirection dir = anyDirection,
    const BoundaryCheck& bcheck = true,
    ParticleHypothesis particle = pion) const;

  Trk::TrackParametersUVector extrapolateBlindlyImpl(
    const EventContext& ctx,
    Cache& cache,
    const IPropagator& prop,
    Trk::CacheOwnedPtr<Trk::TrackParameters> parm,
    PropDirection dir = anyDirection,
    const BoundaryCheck& bcheck = true,
    ParticleHypothesis particle = pion,
    const Volume* boundaryVol = nullptr) const;

  std::pair<std::unique_ptr<TrackParameters>, const Layer*>
  extrapolateToNextActiveLayerImpl(
    const EventContext& ctx,
    const IPropagator& prop,
    const TrackParameters& parm,
    PropDirection dir,
    const BoundaryCheck& bcheck,
    ParticleHypothesis particle = pion,
    MaterialUpdateMode matupmode = addNoise) const;

  std::pair<std::unique_ptr<TrackParameters>, const Layer*>
  extrapolateToNextActiveLayerMImpl(
    const EventContext& ctx,
    const IPropagator& prop,
    const TrackParameters& parm,
    PropDirection dir,
    const BoundaryCheck& bcheck,
    std::vector<const Trk::TrackStateOnSurface*>& material,
    ParticleHypothesis particle = pion,
    MaterialUpdateMode matupmode = addNoise) const;

  std::unique_ptr<TrackParameters> extrapolateToVolumeImpl(
    const EventContext& ctx,
    const IPropagator& prop,
    const TrackParameters& parm,
    const Trk::TrackingVolume& vol,
    PropDirection dir = anyDirection,
    ParticleHypothesis particle = pion) const;

  Trk::CacheOwnedPtr<Trk::TrackParameters> extrapolateInsideVolume(const EventContext& ctx,
                                              Cache& cache,
                                              const IPropagator& prop,
                                              Trk::CacheOwnedPtr<Trk::TrackParameters> parm,
                                              const Surface& sf,
                                              const Layer* associatedLayer,
                                              const TrackingVolume& tvol,
                                              PropDirection dir = anyDirection,
                                              const BoundaryCheck& bcheck = true,
                                              ParticleHypothesis particle = pion,
                                              MaterialUpdateMode matupmode = addNoise) const;

  Trk::CacheOwnedPtr<Trk::TrackParameters> insideVolumeStaticLayers(const EventContext& ctx,
                                               Cache& cache,
                                               bool toBoundary,
                                               const IPropagator& prop,
                                               Trk::CacheOwnedPtr<Trk::TrackParameters> parm,
                                               const Layer* associatedLayer,
                                               const TrackingVolume& tvol,
                                               PropDirection dir = anyDirection,
                                               const BoundaryCheck& bcheck = true,
                                               ParticleHypothesis particle = pion,
                                               MaterialUpdateMode matupmode = addNoise) const;

  Trk::CacheOwnedPtr<Trk::TrackParameters> extrapolateWithinDetachedVolumes(
    const EventContext& ctx,
    Cache& cache,
    const IPropagator& prop,
    Trk::CacheOwnedPtr<Trk::TrackParameters> parm,
    const Surface& sf,
    const TrackingVolume& tvol,
    PropDirection dir = anyDirection,
    const BoundaryCheck& bcheck = true,
    ParticleHypothesis particle = pion,
    MaterialUpdateMode matupmode = addNoise) const;
 
  Trk::CacheOwnedPtr<Trk::TrackParameters> extrapolateToNextMaterialLayer(
    const EventContext& ctx,
    Cache& cache,
    const IPropagator& prop,
    Trk::CacheOwnedPtr<Trk::TrackParameters> parm,
    const Trk::Surface* destSurf,
    const Trk::TrackingVolume* vol,
    PropDirection dir,
    const BoundaryCheck& bcheck,
    ParticleHypothesis particle = pion,
    MaterialUpdateMode matupmode = addNoise) const;
 
  Trk::CacheOwnedPtr<Trk::TrackParameters> extrapolateInAlignableTV(
    const EventContext& ctx,
    Cache& cache,
    const IPropagator& prop,
    Trk::CacheOwnedPtr<Trk::TrackParameters> parm,
    const Trk::Surface* destSurf,
    const Trk::AlignableTrackingVolume* vol,
    PropDirection dir,
    ParticleHypothesis particle = pion) const;
 
  Trk::CacheOwnedPtr<Trk::TrackParameters> extrapolateToVolumeWithPathLimit(
    const EventContext& ctx,
    Cache& cache,
    Trk::CacheOwnedPtr<Trk::TrackParameters> parm,
    double pathLim,
    Trk::PropDirection dir,
    Trk::ParticleHypothesis particle,
    const Trk::TrackingVolume* destVol,
    MaterialUpdateMode matupmod = addNoise) const;

  void extrapolateToVolumeBoundary(
    const EventContext& ctx,
    Cache& cache,
    const IPropagator& prop,
    Trk::CacheOwnedPtr<Trk::TrackParameters> parm,
    const Layer* associatedLayer,
    const TrackingVolume& tvol,
    PropDirection dir = anyDirection,
    const BoundaryCheck& bcheck = true,
    ParticleHypothesis particle = pion,
    MaterialUpdateMode matupmode = addNoise) const;

  Trk::CacheOwnedPtr<Trk::TrackParameters> extrapolateFromLayerToLayer(
    const EventContext& ctx,
    Cache& cache,
    const IPropagator& prop,
    Trk::CacheOwnedPtr<Trk::TrackParameters> parm,
    const TrackingVolume& tvol,
    const Layer* nextLayer,
    const Layer* destinationLayer,
    Trk::CacheOwnedPtr<Trk::TrackParameters> navParameters,
    PropDirection dir = anyDirection,
    const BoundaryCheck& bcheck = true,
    ParticleHypothesis particle = pion,
    MaterialUpdateMode matupmode = addNoise) const;

  Trk::CacheOwnedPtr<Trk::TrackParameters> extrapolateToDestinationLayer(
    const EventContext& ctx,
    Cache& cache,
    const IPropagator& prop,
    Trk::CacheOwnedPtr<Trk::TrackParameters> parm,
    const Surface& sf,
    const Layer& lay,
    const TrackingVolume& tvol,
    const Layer* startLayer,
    PropDirection dir = anyDirection,
    const BoundaryCheck& bcheck = true,
    ParticleHypothesis particle = pion,
    MaterialUpdateMode matupmode = addNoise) const;

  std::pair<Trk::CacheOwnedPtr<Trk::TrackParameters>, bool> extrapolateToIntermediateLayer(
    const EventContext& ctx,
    Cache& cache,
    const IPropagator& prop,
    Trk::CacheOwnedPtr<Trk::TrackParameters> parm,
    const Layer& lay,
    const TrackingVolume& tvol,
    PropDirection dir = anyDirection,
    const BoundaryCheck& bcheck = true,
    ParticleHypothesis particle = pion,
    MaterialUpdateMode matupmode = addNoise,
    bool perpendicularCheck = true) const;

  void overlapSearch(const EventContext& ctx,
                     Cache& cache,
                     const IPropagator& prop,
                     Trk::CacheOwnedPtr<Trk::TrackParameters> parm,
                     Trk::CacheOwnedPtr<Trk::TrackParameters> parsOnLayer,
                     const Layer& lay,
                     const TrackingVolume& tvol,
                     PropDirection dir = anyDirection,
                     const BoundaryCheck& bcheck = true,
                     ParticleHypothesis particle = pion,
                     bool startingLayer = false) const;

  PropDirection initializeNavigation(
    const EventContext& ctx,
    Cache& cache,
    const Trk::IPropagator& prop,
    Trk::CacheOwnedPtr<Trk::TrackParameters> startPars,
    const Trk::Surface& destSurface,
    Trk::PropDirection dir,
    ParticleHypothesis particle,
    Trk::CacheOwnedPtr<Trk::TrackParameters>& referenceParameters,
    const Trk::Layer*& associatedLayer,
    const Trk::TrackingVolume*& associatedVolume,
    const Trk::TrackingVolume*& destinationVolume) const;

  bool radialDirectionCheck(const EventContext& ctx,
                            const IPropagator& prop,
                            const TrackParameters& startParm,
                            const TrackParameters& parsOnLayer,
                            const TrackingVolume& tvol,
                            PropDirection dir = anyDirection,
                            ParticleHypothesis particle = pion) const;

  const IPropagator* subPropagator(const TrackingVolume& tvol) const;

  const IMaterialEffectsUpdator* subMaterialEffectsUpdator(const TrackingVolume& tvol) const;

  std::string positionOutput(const Amg::Vector3D& pos) const;

  void addMaterialEffectsOnTrack(const EventContext& ctx,
                                 Cache& cache,
                                 const Trk::IPropagator& prop,
                                 Trk::CacheOwnedPtr<Trk::TrackParameters> parm,
                                 const Trk::Layer& lay,
                                 const Trk::TrackingVolume& vol,
                                 Trk::PropDirection propDir,
                                 Trk::ParticleHypothesis) const;
 
 

  // unsigned int geoIDToDetOrder(Trk::GeometrySignature geoid) const;
 
  // --------------- Used Tools ----------------------------- //
  ToolHandleArray<IPropagator> m_propagators{ this, "Propagators", {} };
  ToolHandle<IPropagator> m_stepPropagator{
    this,
    "STEP_Propagator",
    "Trk::STEP_Propagator/AtlasSTEP_Propagator"
  };

  ToolHandle<INavigator> m_navigator{ this,
                                      "Navigator",
                                      "Trk::Navigator/AtlasNavigator" };

  ToolHandleArray<IMaterialEffectsUpdator> m_updaters{
    this,
    "MaterialEffectsUpdators",
    {}
  };

  ToolHandle<IMultipleScatteringUpdator> m_msupdater{
    this,
    "MultipleScatteringUpdater",
    "Trk::MultipleScatteringUpdator/AtlasMultipleScatteringUpdator"
  };

  ToolHandle<IEnergyLossUpdator> m_elossupdater{ this,
                                                "EnergyLossUpdater",
                                                "Trk::EnergyLossUpdator/AtlasEnergyLossUpdator" };
 
  // ---------------- For Extrapolation handling ------------ //

  std::vector<const IPropagator*> m_subPropagators;
  std::vector<const IMaterialEffectsUpdator*> m_subupdaters;
 
  // ---------------- For Extrapolator configuration ------------ //
 
  StringArrayProperty m_propNames{this, "SubPropagators", {},
    "configuration of subPropagators"};
  StringArrayProperty m_updatNames{this, "SubMEUpdators", {},
    "configuration of subupdaters"};
 
  // --------------- General steering & Navigation -------------- //
 
  BooleanProperty m_includeMaterialEffects{this, "ApplyMaterialEffects", true,
    "boolean to switch on/off material effects"};
  BooleanProperty m_stopWithNavigationBreak
    {this, "StopWithNavigationBreak", false,
     "return 0 if navigation breaks - for validation reasons"};
  BooleanProperty m_stopWithUpdateZero{this, "StopWithUpdateKill", false,
    "return 0 if update kills the trajectory"};
  BooleanProperty m_skipInitialLayerUpdate{this, "SkipInitialPostUpdate", false,
    "skip the initial post-Update at the layer [Fatras conversion mode]"};
  BooleanProperty m_resolveActive{this, "ResolveMuonStation", false};
  BooleanProperty m_resolveMultilayers{this, "ResolveMultilayers", true};
  //if we have no valid subpropagatos it will be set to an INVALID value
  unsigned int m_numOfValidPropagators;
  UnsignedIntegerProperty m_initialLayerAttempts
    {this, "InitialLayerAttempts", 3,
    "allowed layer intersection attempts at the start of a volume"};
  UnsignedIntegerProperty m_successiveLayerAttempts
    {this, "SuccessiveLayerAttempts", 1,
    "layer intersection attemps after one layer has been hit sucessfully"};
  UnsignedIntegerProperty m_maxMethodSequence
    {this, "MaximalMethodSequence", 2000};
  DoubleProperty m_tolerance{this, "Tolerance", 0.002,
    "surface & volume tolerance"};
  // ------------------------------------------------------- //
  BooleanProperty m_useMuonMatApprox{this, "UseMuonMatApproximation", false,
    "use approximative MS inert material"};
  BooleanProperty m_useDenseVolumeDescription
    {this, "UseDenseVolumeDescription", true,
     "use dense volume description when available in ID/Calo"};
  UnsignedIntegerProperty m_maxRecursion{this, "MaxRecursion", 1000};
 
  static const unsigned int m_maxNavigSurf = 1000;
  static const unsigned int m_maxNavigVol = 50;
  BooleanProperty m_dumpCache{this, "DumpCache", false};
  //------------ Magnetic field properties
  BooleanProperty m_fastField{this, "MagneticFieldProperties", false};
  Trk::MagneticFieldProperties m_fieldProperties;
  //------------Reference surface --------------
  std::unique_ptr<Surface> m_referenceSurface = nullptr;
  //-------------------------- SCREEN output steering -------------------------------------------//
  BooleanProperty m_printRzOutput{this, "positionOutput", true};
  //------------------------- VALIDATION  SECTION ------------------------------------------//
  // flags
  BooleanProperty m_navigationStatistics
    {this, "NavigationStatisticsOutput", false,
     "steer the output for the navigation statistics"};
  BooleanProperty m_navigationBreakDetails
    {this, "DetailedNavigationOutput", false,
     "steer the output for the navigation break details"};
 
  // extrapolation counters
  mutable Gaudi::Accumulators::Counter<> m_extrapolateCalls{};         
  mutable Gaudi::Accumulators::Counter<> m_extrapolateBlindlyCalls{};  
  mutable Gaudi::Accumulators::Counter<> m_extrapolateDirectlyCalls{}; 
  mutable Gaudi::Accumulators::Counter<> m_extrapolateStepwiseCalls{}; 
 
  mutable Gaudi::Accumulators::Counter<> m_startThroughAssociation{};        
  mutable Gaudi::Accumulators::Counter<> m_startThroughRecall{};             
  mutable Gaudi::Accumulators::Counter<> m_startThroughGlobalSearch{};       
  mutable Gaudi::Accumulators::Counter<> m_destinationThroughAssociation{};  
  mutable Gaudi::Accumulators::Counter<> m_destinationThroughRecall{};       
  mutable Gaudi::Accumulators::Counter<> m_destinationThroughGlobalSearch{}; 
  mutable Gaudi::Accumulators::Counter<> m_layerSwitched{};                  
 
  // navigation counters
  mutable Gaudi::Accumulators::Counter<> m_navigationBreakLoop{}; 
  mutable Gaudi::Accumulators::Counter<> m_navigationBreakOscillation{}; 
  mutable Gaudi::Accumulators::Counter<> m_navigationBreakNoVolume{}; 
  mutable Gaudi::Accumulators::Counter<> m_navigationBreakDistIncrease{}; 
  mutable Gaudi::Accumulators::Counter<> m_navigationBreakVolumeSignature{}; 
  mutable Gaudi::Accumulators::Counter<> m_overlapSurfaceHit{}; 
 
  mutable Dbg::PropStat m_propStat ATLAS_THREAD_SAFE;
};
 
} // end of namespace
#include "TrkExTools/Extrapolator.icc"
 
#endif // TRKEXTOOLS_TRKEXTRAPOLATOR_H