From 5ab82a05421c98d242b5619bb2d0c29eb2a4795f Mon Sep 17 00:00:00 2001
From: Maximilian Goblirsch-Kolb <goblirsc@cern.ch>
Date: Thu, 8 Oct 2020 12:17:30 +0200
Subject: [PATCH] documentation
---
.../SiDetElementRoadMakerData_xk.h | 41 +++++++++++++------
.../src/SiDetElementRoadMakerData_xk.cxx | 6 +--
.../ISiDetElementsRoadMaker.h | 34 ++++++++++++---
.../SiDetElementsRoadMaker_xk.h | 38 +++++++++++++----
.../src/SiDetElementsRoadMaker_xk.cxx | 21 ++++++----
5 files changed, 103 insertions(+), 37 deletions(-)
diff --git a/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiDetElementRoadMakerData_xk.h b/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiDetElementRoadMakerData_xk.h
index e58e125f7d3f..f85a241ef31f 100644
--- a/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiDetElementRoadMakerData_xk.h
+++ b/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/SiSPSeededTrackFinderData/SiDetElementRoadMakerData_xk.h
@@ -21,41 +21,58 @@ namespace InDet {
@class SiDetElementRoadMakerData_xk
InDet::SiDetElementRoadMakerData_xk holds event dependent data
- used by SiDetElementRoadMaker_xk.
+ used by SiDetElementRoadMaker_xk.
@author goblirsc@cern.ch
*/
class SiDetElementRoadMakerData_xk {
public:
-
-
+ /// This helper class is used to keep track of
+ /// which detector elements are already being
+ /// considered when forming a search road during
+ /// the extension of silicon seeds through the full
+ /// Si detectors.
class UsedFlag {
public:
UsedFlag() : m_used(false) {}
-
+ /// read the flag
bool used() const { return m_used; }
-
+ /// toggle the flag
void setUsed() { m_used=true; }
+ /// reset without having to overwrite the object
void reset(){ m_used=false;}
private:
bool m_used;
};
- /**
- * Constructor
- */
+
+ /// trivial constructor - the members of this event
+ /// data struct need client tool information for
+ /// initialisation, hence this is done at client-level.
SiDetElementRoadMakerData_xk(){}
- /**
- * Default destructor
- */
+ /// Default destructor
~SiDetElementRoadMakerData_xk() = default;
+ /// method to reset the flags stored in the elementUsageTracker
+ /// (below) when building a new search road. Does not perform any
+ /// allocations, but resets the existing slots.
void resetUsageTracker();
- typedef std::array<std::vector<std::vector<UsedFlag> >,3> ElementUsageTracker;
+ /// Following the pattern established for example in the
+ /// seed-maker event data, we use public members directly
+ /// rather than exposing private members with full read-write-access.
+ /// This has the advantage that the members can be intialized by the
+ /// client tools, which provide the tools needed to do so.
+ /// This is a data structure used to track which of our detector elements
+ /// are already on a search road. Nested in the hierarchy of
+ /// detector region - layer - module within layer.
+ /// Dynamic to avoid hard-coding a certain geometry.
+ typedef std::array<std::vector<std::vector<UsedFlag> >,3> ElementUsageTracker;
ElementUsageTracker elementUsageTracker;
+
+ /// Flag to check if the event data was already initialized by the client tool.
bool isInitialized{false};
};
diff --git a/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/src/SiDetElementRoadMakerData_xk.cxx b/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/src/SiDetElementRoadMakerData_xk.cxx
index b64d1dd7f183..56dc7e91c6d1 100644
--- a/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/src/SiDetElementRoadMakerData_xk.cxx
+++ b/InnerDetector/InDetRecEvent/SiSPSeededTrackFinderData/src/SiDetElementRoadMakerData_xk.cxx
@@ -2,9 +2,9 @@
#include <algorithm>
void InDet::SiDetElementRoadMakerData_xk::resetUsageTracker(){
- for (auto & outerVec : elementUsageTracker){
- for (auto & innerVec : outerVec){
- std::for_each(innerVec.begin(), innerVec.end(), [](InDet::SiDetElementRoadMakerData_xk::UsedFlag & flag){flag.reset();});
+ for (auto & outerVec : elementUsageTracker){ /// loop over detector regions
+ for (auto & innerVec : outerVec){ /// loop over layers in region
+ std::for_each(innerVec.begin(), innerVec.end(), [](InDet::SiDetElementRoadMakerData_xk::UsedFlag & flag){flag.reset();}); /// loop over elements on layer
}
}
}
\ No newline at end of file
diff --git a/InnerDetector/InDetRecTools/InDetRecToolInterfaces/InDetRecToolInterfaces/ISiDetElementsRoadMaker.h b/InnerDetector/InDetRecTools/InDetRecToolInterfaces/InDetRecToolInterfaces/ISiDetElementsRoadMaker.h
index a0d1aaf83297..7a2b0e2f8a48 100644
--- a/InnerDetector/InDetRecTools/InDetRecToolInterfaces/InDetRecToolInterfaces/ISiDetElementsRoadMaker.h
+++ b/InnerDetector/InDetRecTools/InDetRecToolInterfaces/InDetRecToolInterfaces/ISiDetElementsRoadMaker.h
@@ -53,17 +53,39 @@ namespace InDet {
///////////////////////////////////////////////////////////////////
/// @name Main methods for road builder
///////////////////////////////////////////////////////////////////
+ /// This signature assumes you already have a list of positions
+ /// along the trajectory. It will look for detector elements
+ /// compatible with being crossed by the linearised
+ /// trajectory provided and fill those into the 'Road' argument.
+ /// If 'testDirection' is used, we only fill detector elements
+ /// encountered while traversing in the positive direction.
+ ///
+ /// @param[in] globalPositions: set of points along the trajectory. Will linearise between them.
+ /// @param[out] Road: List to be populated with the elements of the search road. Will be sorted along the trajectory.
+ /// @param[in] testDirection: If set, avoid adding detector elements encountered only when travelling in the negative direction. Set true for inside-out tracking, false for cosmic tracking.
+ /// @param[in,out] roadMakerData: event data object used to cache information during an event in a thread-safe way
//@{
virtual void detElementsRoad
- (std::list<Amg::Vector3D>&,
- std::list<const InDetDD::SiDetectorElement*>&,
- bool test, InDet::SiDetElementRoadMakerData_xk &) const=0;
-
+ ( std::list<Amg::Vector3D>& globalPositions,
+ std::list<const InDetDD::SiDetectorElement*>& Road,
+ bool testDirection,
+ InDet::SiDetElementRoadMakerData_xk & roadMakerData) const=0;
+
+ /// This is the signature used in most ATLAS clients.
+ /// @param[in] ctx: Event context
+ /// @param[in] fieldCache: Magnetic field cache
+ /// @param[in] Tp: Track parameter hypothesis used for road building. For example obtained from a seed. Will be used to populate a set of space points along the expected trajectory, and to search
+ /// for detector elements along this linearised trajectory using the signature above
+ /// @param[in] direction: Direction of propagation - either along (inside out) or against (cosmic) momentum.
+ /// @param[out] Road: List to be populated with the elements of the search road. Will be sorted along the trajectory.
+ /// @param[in,out] roadMakerData: event data object used to cache information during an event in a thread-safe way
virtual void detElementsRoad
(const EventContext& ctx,
MagField::AtlasFieldCache& fieldCache,
- const Trk::TrackParameters&,Trk::PropDirection,
- std::list<const InDetDD::SiDetectorElement*>&, InDet::SiDetElementRoadMakerData_xk &) const=0;
+ const Trk::TrackParameters& Tp,
+ Trk::PropDirection direction,
+ std::list<const InDetDD::SiDetectorElement*>& Road,
+ InDet::SiDetElementRoadMakerData_xk & roadMakerData) const=0;
//@}
///////////////////////////////////////////////////////////////////
diff --git a/InnerDetector/InDetRecTools/SiDetElementsRoadTool_xk/SiDetElementsRoadTool_xk/SiDetElementsRoadMaker_xk.h b/InnerDetector/InDetRecTools/SiDetElementsRoadTool_xk/SiDetElementsRoadTool_xk/SiDetElementsRoadMaker_xk.h
index cf408c5fdd0f..0136496eaff6 100644
--- a/InnerDetector/InDetRecTools/SiDetElementsRoadTool_xk/SiDetElementsRoadTool_xk/SiDetElementsRoadMaker_xk.h
+++ b/InnerDetector/InDetRecTools/SiDetElementsRoadTool_xk/SiDetElementsRoadTool_xk/SiDetElementsRoadMaker_xk.h
@@ -79,19 +79,39 @@ namespace InDet{
///////////////////////////////////////////////////////////////////
/// @name Main methods for road builder
///////////////////////////////////////////////////////////////////
- //@{
+ ///
+ /// This signature assumes you already have a list of positions
+ /// along the trajectory. It will look for detector elements
+ /// compatible with being crossed by the linearised
+ /// trajectory provided and fill those into the 'Road' argument.
+ /// If 'testDirection' is used, we only fill detector elements
+ /// encountered while traversing in the positive direction.
+ ///
+ /// @param[in] globalPositions: set of points along the trajectory. Will linearise between them.
+ /// @param[out] Road: List to be populated with the elements of the search road. Will be sorted along the trajectory.
+ /// @param[in] testDirection: If set, avoid adding detector elements encountered only when travelling in the negative direction. Set true for inside-out tracking, false for cosmic tracking.
+ /// @param[in,out] roadMakerData: event data object used to cache information during an event in a thread-safe way
virtual void detElementsRoad
- (std::list<Amg::Vector3D>&,
- std::list<const InDetDD::SiDetectorElement*>&,
- bool test,
+ (std::list<Amg::Vector3D>& globalPositions,
+ std::list<const InDetDD::SiDetectorElement*>& Road,
+ bool testDirection,
SiDetElementRoadMakerData_xk & roadMakerData) const override;
+
+ /// This is the signature used in most ATLAS clients.
+ /// @param[in] ctx: Event context
+ /// @param[in] fieldCache: Magnetic field cache
+ /// @param[in] Tp: Track parameter hypothesis used for road building. For example obtained from a seed. Will be used to populate a set of space points along the expected trajectory, and to search
+ /// for detector elements along this linearised trajectory using the signature above
+ /// @param[in] direction: Direction of propagation - either along (inside out) or against (cosmic) momentum.
+ /// @param[out] Road: List to be populated with the elements of the search road. Will be sorted along the trajectory.
+ /// @param[in,out] roadMakerData: event data object used to cache information during an event in a thread-safe way
virtual void detElementsRoad
(const EventContext& ctx,
MagField::AtlasFieldCache& fieldCache,
- const Trk::TrackParameters&,
- Trk::PropDirection,
- std::list<const InDetDD::SiDetectorElement*>&,
+ const Trk::TrackParameters& Tp,
+ Trk::PropDirection direction,
+ std::list<const InDetDD::SiDetectorElement*>& Road,
SiDetElementRoadMakerData_xk & roadMakerData) const override;
//@}
@@ -163,7 +183,9 @@ namespace InDet{
}
return layerVec.cptr();
}
-
+ /// this method is used to initialize the detector element usage tracker member
+ /// of the event data struct in case it has not been previously set.
+ /// modifies the 'data' argument, based on information in the 'layers' argument.
void bookUsageTracker(InDet::SiDetElementRoadMakerData_xk & data, const SiDetElementsLayerVectors_xk &layers) const;
};
diff --git a/InnerDetector/InDetRecTools/SiDetElementsRoadTool_xk/src/SiDetElementsRoadMaker_xk.cxx b/InnerDetector/InDetRecTools/SiDetElementsRoadTool_xk/src/SiDetElementsRoadMaker_xk.cxx
index e219a38bf48f..1c39130f9942 100644
--- a/InnerDetector/InDetRecTools/SiDetElementsRoadTool_xk/src/SiDetElementsRoadMaker_xk.cxx
+++ b/InnerDetector/InDetRecTools/SiDetElementsRoadTool_xk/src/SiDetElementsRoadMaker_xk.cxx
@@ -302,7 +302,7 @@ std::ostream& InDet::operator <<
///////////////////////////////////////////////////////////////////
void InDet::SiDetElementsRoadMaker_xk::detElementsRoad
-(std::list<Amg::Vector3D>& GP,
+(std::list<Amg::Vector3D>& globalPositions,
std::list<const InDetDD::SiDetectorElement*>& Road,
bool testDirection,
SiDetElementRoadMakerData_xk & roadMakerData) const
@@ -323,7 +323,7 @@ void InDet::SiDetElementsRoadMaker_xk::detElementsRoad
const SiDetElementsLayerVectors_xk &layer = *getLayers();
/// iterators over the positions to consider
- std::list<Amg::Vector3D>::iterator currentPosition=GP.begin(), endPositions=GP.end();
+ std::list<Amg::Vector3D>::iterator currentPosition=globalPositions.begin(), endPositions=globalPositions.end();
/// fill an array with the reference point (start with the first one), the road width and a placeholder
/// for the step length
@@ -358,11 +358,16 @@ void InDet::SiDetElementsRoadMaker_xk::detElementsRoad
std::vector<InDet::SiDetElementLink_xk::ElementWay> lDE;
- /// reset the module usage data
+
+ /// reset the detector-element usage info.
+ /// If we are the first client to see this event data object,
+ /// we allocate the storage for all modules
if (!roadMakerData.isInitialized){
bookUsageTracker(roadMakerData,layer);
}
else{
+ /// if we are not the first client, we reset the event data without
+ /// re-allocation
roadMakerData.resetUsageTracker();
}
@@ -524,8 +529,8 @@ void InDet::SiDetElementsRoadMaker_xk::detElementsRoad
(const EventContext& ctx,
MagField::AtlasFieldCache& fieldCache,
const Trk::TrackParameters& Tp,
- Trk::PropDirection D,
- std::list<const InDetDD::SiDetectorElement*>& R,
+ Trk::PropDirection direction,
+ std::list<const InDetDD::SiDetectorElement*>& Road,
SiDetElementRoadMakerData_xk & roadMakerData) const
{
if (!m_usePIX && !m_useSCT) return;
@@ -539,7 +544,7 @@ void InDet::SiDetElementsRoadMaker_xk::detElementsRoad
if (S > 1000. ) S = 1000. ;
bool testDirection = true;
- if (D<0) {
+ if (direction<0) {
testDirection = false;
S=-S;
}
@@ -560,7 +565,7 @@ void InDet::SiDetElementsRoadMaker_xk::detElementsRoad
/// if we are extrapolating along them momentum direction,
/// we pick out the part ascending in R
- if (D > 0) {
+ if (direction > 0) {
std::list<Amg::Vector3D>::iterator currentPosition=G.begin(), nextPosition, endPositions=G.end();
float r0 = (*currentPosition).x()*(*currentPosition).x()+(*currentPosition).y()*(*currentPosition).y();
@@ -579,7 +584,7 @@ void InDet::SiDetElementsRoadMaker_xk::detElementsRoad
}
}
/// now perform the road building using our set of positions
- detElementsRoad(G, R,testDirection, roadMakerData);
+ detElementsRoad(G, Road,testDirection, roadMakerData);
}
--
GitLab