d6/d52/Extrapolator_8h_source.html

/*

   Copyright (C) 2002-2025 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;


  virtual 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