Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Addition of L1 tracking code for "TMTT" & (part of) "Hybrid" algorithms (L1Trigger/TrackFindingTMTT) #29381

Merged
merged 23 commits into from
May 22, 2020
Merged
Show file tree
Hide file tree
Changes from 19 commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions L1Trigger/TrackFindingTMTT/BuildFile.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
<use name="CommonTools/UtilAlgos"/>
<use name="DataFormats/Common"/>
<use name="DataFormats/L1TrackTrigger"/>
<use name="DataFormats/Math"/>
<use name="DataFormats/Phase2TrackerDigi"/>
<use name="FWCore/Framework"/>
<use name="FWCore/ParameterSet"/>
<use name="FWCore/ServiceRegistry"/>
<use name="FWCore/Utilities"/>
<use name="Geometry/Records"/>
<use name="Geometry/TrackerGeometryBuilder"/>
<use name="MagneticField/Engine"/>
<use name="MagneticField/Records"/>
<use name="SimDataFormats/EncodedEventId"/>
<use name="SimDataFormats/Track"/>
<use name="SimDataFormats/TrackingAnalysis"/>
<use name="SimGeneral/TrackingAnalysis"/>
<use name="SimTracker/TrackTriggerAssociation"/>
<use name="DataFormats/JetReco"/>
<use name="boost"/>
<use name="roothistmatrix"/>
<export>
<lib name="1"/>
</export>

139 changes: 139 additions & 0 deletions L1Trigger/TrackFindingTMTT/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
Two options:

1) Run the TMTT L1 tracking algorithm (with detailed internal histos)

cd L1Trigger/TrackFindingTMTT/test/
cmsRun -n 4 tmtt_tf_analysis_cfg.py

editing if necessary variables: GEOMETRY (CMS geometry version), inputMCtxt (MC file), makeStubs (regenerate stubs instead of using those from input MC), outputDataSet (write TTTrack collection to file).

- Look at the printout from the job. At the end, it prints the number of track candidates reconstructed
and the algorithmic tracking efficiency.

- Look at the performance histograms Hist.root (explained in class "Histos" below)

2) cmsRun -n 4 L1TrackNtupleMaker_cfg.py
after editing it to change L1TRACKALGO = 'TMTT'. This writes a TTree of the fitted L1 tracks to .root file, from which tracking performance can be studied with ROOT macro L1Trigger/TrackFindingTracklet/test/L1TrackNtuplePlot.C. Other values of L1TRACKALGO permit to run the Hybrid or Tracklet emulation, or floating point emulation.

Both (1) & (2) are able to write a dataset containing the TTTrack collection of the fitted tracks.

N.B. .txt files listing available MC samples can be found in https://github.com/cms-data/L1Trigger-TrackFindingTMTT .

-------------

=== Reproducing stubs ===:

The makeStubs option to remake the stubs is very slow. If you need to do this, it may be better to "cmsRun make_stubs.py" to write the new stubs to disk.

=== Changing configuration options ===:

a) The full set of config parameters, which comments explaining what each is, can be found in
specifiied in L1Trigger/TrackFindingTMTT/python/TMTrackProducer_Defaults_cfi.py.

b) The file mentioned on (a) is imported by
L1Trigger/TrackFindingTMTT/python/TMTrackProducer_cff.py ,
which can optionally override the values of some parameters. This file lists the subset of the cfg
parameters that are most useful.

e.g. Enable tracking down to 2 GeV, enabled displaced tracking etc.

c) Alternatively, you can use L1Trigger/TrackFindingTMTT/python/TMTrackProducer_Ultimate_cff.py ,
which is like (b) but includes improvements not yet available in the firmware, such as reducing the
Pt threshold to 2 GeV. It is suitable for L1 trigger studies.

d) You can also override cfg parameters in tmtt_tf_analysis_cfg.py . A line there illustrates how.
This file imports TMTrackProducer_cff.py.

e) The python files in python/ all disable production of histograms & tracking performance summaries to save CPU. However, tmtt_tf_analysis_cfg overrides this default and switches them on via parameters EnableMCtruth & EnableHistos. If you do not care about this analysis information, and only care about producing TTTracks, then keep them switched off.

-------------

=== Software structure ===:

1) Class "TMTrackProducer" -- This is the main routine, which uses classes: "InputData" to unpack the useful
data from the MC dataset, and "Sector" & "HTphi" to do the L1 Hough transform track-finding,
and "Get3Dtracks" to estimate the helix params in 3D, optionally by running an r-z track filter.
It creates matrices of "Sector", "HTphi" & "Get3Dtracks", where the matrix elements each correspond to
a different (phi,eta) sector. It then uses "TrackFitGeneric" to do the track fitting and optionally
"KillDupFitTrks" to remove duplicate tracks after the fit. It employs "Histos" to create the analysis
histograms.
To allow comparison of our tracks with those of the AM & Tracklet groups, it also converts our tracks
to the agree common TTTrack format, with this conversion done by the "ConverterToTTTrack" class.

2) Class "InputData" -- This unpacks the most useful information from the Stubs and Tracking Particle
(truth particles) collections in the MC dataset, and it for convenient access in the "Stub" and "TP"
classes. Info about tracker silicon modules is stored in "ModuleInfo". The "Stub" class uses a class called "DigitalStub" to digitize and then undigitize again the stub data. This process degrades slightly the resolution, as would happen in the real firmware. The digitisation is optional. It is called from TMTrackProducer after the stubs have been assigned to
sectors.

3) Class "Sector" -- This knows about the division of the Tracker into (phi,eta) sectors that we use
for the L1 tracking, and decides which of these sectors each stub belongs to.

4) Class "HTrphi" implements the Hough transforms in the r-phi plane. It inherits from
a base class "HTbase". The Hough transform array is implemented as a matrix of "HTcell"
objects. The HTrphi class stores tracks it finds using the "L1track2D" class. It optionally
uses class "KillDupTrks" to attempt to eliminate duplicate tracks. And optionally, class "MuxHToutputs"
can be used to multiplex the tracks found in different HT arrays (sectors) onto a single output
optical link pair.

5) Class "HTcell" -- This represents a single cell in an HT array. It provides functions allowing stubs
to be added to this cell, to check if the stubs in a cell give a good track candidate, and to check
if this matches a tracking particle (truth).

6) Class "Get3Dtracks" makes an estimate of the track parameters in 3D, stored in the "L1track3D"
class, by taking the r-phi track found by the HT, assuming z0 = 0 and that eta is given by the centre
of the eta sector that track is in. Optionally it can also create a second collection of L1track3D,
by running an r-z track filter (from class "TrkRZfilter") on the tracks found by the HT, which gives
cleaner tracks with more precise r-z helix param info.

7) Class "L1track2D" represents a 2D track, reconstructed in the r-phi or r-z plane by a Hough transform.
Class "L1track3D" represents a 3D tracks, obtained by combining the information in the 2D tracks
from r-phi and r-z Hough transforms. These classes give access to the stubs associated to each track,
to the reconstructed helix parameters, and to the associated truth particle (if any). They represent
the result of the track finding. Both inherit from a pure virtual class L1trackBase, which contains
no functionality but imposes common function names.

8) Class "KillDupTrks" contains algorithms for killing duplicate tracks found within a single
HT array. Class "KillDupFitTrks" contains algorithms for killing duplicate fitted tracks.

9) Class "TrkRZfilter" contains r-z track filters, such as the Seed Filter, that check if the stubs
on a track are consistent with a straight line in the r-z plane.

10) Class "TrackFitGeneric" does one (or more) helix fit(s) to the track candidates, using various
other classes that implement linearized chi2, linear regression or Kalman filter fits. These are:

- ChiSquared4ParamsApprox (chi2 linear fit, with maths simplified for easier use in FPGA)
- SimpleLR (linear regression fit, which is similar to chi2 fit, but assumes all hits have same uncertainty).
- KFParamsComb: Kalman Filter fit to a 4 or 5 parameter helix.

The fit also uses a classe to represent the helix state + stubs: KalmanState.

11) Class "L1fittedTrack" contains the result of running a track fitter (the algorithm for which is
implemented in class "TrackFitAlgo") on the L1track3D track candidate found by the Hough transform.
It gives access to the fitted track parameters and chi2, and via a link to the L1track3D candidate
that produced it, also to the stubs on the track and the associated truth particle (if any).
It inherits from the pure virutal L1trackBase, ensuring it has some common classes with L1track3D and
L1track2D.

13) Class "DegradeBend" -- This is used by class "Stub" to degrade the resolution on the stub
bend information to that expected in the electronics, as opposed to that currently in CMSSW.

14) "Utility" -- contains a few useful functions, that are not part of a class.

15) Class "Settings" -- Reads in the configuration parameters.

16) Class "Histos" -- Books and fills all the histograms. There are several categories of histograms,
with each category being booked/filled by its own function inside "Histos", and being placed inside its
own ROOT directory in the output histogram file. The categories are "InputData" = plots made with the
Stubs & Tracking Particles; "CheckEtaPhiSectors" = plots checking assignment of stubs to (eta,phi)
sectors; "HT" = plots checking how stubs are stored in the Hough Transform arrays; "TrackCands" = plots
showing number of track candidates found & investigating why tracking sometimes failed,
"EffiAndFakeRate" = plots of tracking efficiency.

Each user of the code will probably want to book their own set of histograms inside "Histos". So
just consider the version of this class in GIT as a set of examples of how to do things. Don't feel
obliged to understand what every histogram does.

17) Class "StubKiller" emulates dead modules. It was written to
model the scenarios requested by the Stress Test committee.

18) Class "GlobalCacheTMTT" contains data shared by all threads. It includes configuration data and histograms.
1 change: 1 addition & 0 deletions L1Trigger/TrackFindingTMTT/data/README
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Add a symbolic link from here to the MCsamples/ directory that can be found in https://github.com/cms-data/L1Trigger-TrackFindingTMTT , where .txt files listing available MC samples can be found.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The contents of https://github.com/cms-data/L1Trigger-TrackFindingTMTT will be automatically linked to L1Trigger/TrackFindingTMTT/data by the CMS build system, once all the PRs are integrated. Therefore, I don't think this note is necessary.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tomalin I still think this can be removed.

21 changes: 21 additions & 0 deletions L1Trigger/TrackFindingTMTT/interface/ChiSquaredFit4.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
#ifndef L1Trigger_TrackFindingTMTT_ChiSquaredFit4_h
#define L1Trigger_TrackFindingTMTT_ChiSquaredFit4_h

#include "L1Trigger/TrackFindingTMTT/interface/ChiSquaredFitBase.h"

namespace tmtt {

class ChiSquaredFit4 : public ChiSquaredFitBase {
public:
ChiSquaredFit4(const Settings* settings, const uint nPar);

protected:
TVectorD seed(const L1track3D& l1track3D);
TVectorD residuals(const TVectorD& x);
TMatrixD D(const TVectorD& x);
TMatrixD Vinv();
};

} // namespace tmtt

#endif
61 changes: 61 additions & 0 deletions L1Trigger/TrackFindingTMTT/interface/ChiSquaredFitBase.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
#ifndef L1Trigger_TrackFindingTMTT_ChiSquaredFitBase_h
#define L1Trigger_TrackFindingTMTT_ChiSquaredFitBase_h

///=== This is the base class for the linearised chi-squared track fit algorithms.

///=== Written by: Sioni Summers and Alexander D. Morton.

#include "L1Trigger/TrackFindingTMTT/interface/Stub.h"
#include "L1Trigger/TrackFindingTMTT/interface/TrackFitGeneric.h"
#include "L1Trigger/TrackFindingTMTT/interface/Settings.h"
#include "L1Trigger/TrackFindingTMTT/interface/L1track3D.h"
#include "TMatrixD.h"
#include "TVectorD.h"

#include <vector>
#include <map>
#include <utility>

namespace tmtt {

class ChiSquaredFitBase : public TrackFitGeneric {
public:
enum PAR_IDS { INVR, PHI0, T, Z0, D0 };

public:
ChiSquaredFitBase(const Settings* settings, const uint nPar);

L1fittedTrack fit(const L1track3D& l1track3D);

protected:
/* Methods */
virtual TVectorD seed(const L1track3D& l1track3D) = 0;
virtual TVectorD residuals(const TVectorD& x) = 0; // Stub residuals/uncertainty
virtual TMatrixD D(const TVectorD& x) = 0; // derivatives
virtual TMatrixD Vinv() = 0; // Covariances

/* Variables */
double qOverPt_seed_;
std::vector<Stub*> stubs_;
TVectorD trackParams_;
uint nPar_;
float largestresid_;
int ilargestresid_;
double chiSq_;

private:
void calculateChiSq(const TVectorD& resids);
void calculateDeltaChiSq(const TVectorD& deltaX, const TVectorD& covX);

int numFittingIterations_;
int killTrackFitWorstHit_;
double generalResidualCut_;
double killingResidualCut_;

unsigned int minStubLayers_;
unsigned int minStubLayersRed_;
};

} // namespace tmtt

#endif
38 changes: 38 additions & 0 deletions L1Trigger/TrackFindingTMTT/interface/ConverterToTTTrack.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
#ifndef L1Trigger_TrackFindingTMTT_ConverterToTTTrack_h
#define L1Trigger_TrackFindingTMTT_ConverterToTTTrack_h

#include "L1Trigger/TrackFindingTMTT/interface/Settings.h"
#include "L1Trigger/TrackFindingTMTT/interface/L1track3D.h"
#include "L1Trigger/TrackFindingTMTT/interface/L1fittedTrack.h"

#include "DataFormats/L1TrackTrigger/interface/TTTypes.h"

//=== Convert non-persistent L1 track collection to the official persistent CMSSW EDM TTTrack format.
//=== Works for both L1track3D and for L1fittedTrk objects.

namespace tmtt {

typedef edmNew::DetSetVector<TTStub<Ref_Phase2TrackerDigi_> > TTStubDetSetVec;
typedef edm::Ref<TTStubDetSetVec, TTStub<Ref_Phase2TrackerDigi_> > TTStubRef;

class ConverterToTTTrack {
public:
// Initialize constants.
ConverterToTTTrack(const Settings* settings) : settings_(settings) { invPtToInvR_ = settings->invPtToInvR(); }

// Convert L1fittedTrack or L1track3D (track candidates after/before fit) to TTTrack format.
TTTrack<Ref_Phase2TrackerDigi_> makeTTTrack(const L1trackBase* trk,
unsigned int iPhiSec,
unsigned int iEtaReg) const;

private:
// Get references to stubs on track. (Works for either L1track3D or L1fittedTrack).
std::vector<TTStubRef> stubRefs(const L1trackBase* trk) const;

private:
const Settings* settings_; // Configuration parameters.
float invPtToInvR_; // converts 1/Pt to 1/radius_of_curvature
};

} // namespace tmtt
#endif
75 changes: 75 additions & 0 deletions L1Trigger/TrackFindingTMTT/interface/DegradeBend.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
#ifndef L1Trigger_TrackFindingTMTT_DegradeBend_h
#define L1Trigger_TrackFindingTMTT_DegradeBend_h

#include "DataFormats/DetId/interface/DetId.h"

#include <vector>

class TrackerTopology;

namespace tmtt {

class DegradeBend {
/*
*-------------------------------------------------------------------------------------------------------------------
* Implements reduced bits to encode stub bend information: 3 bits for PS, 4 bits for 2S, since the Tracker
* doesn't have the bandwidth to output the unreduced data from the FE electronics.
*
* This obtains the stub window sizes from a hard-wired copy of L1Trigger/TrackTrigger/python/TTStubAlgorithmRegister_cfi.py .
* Whenever these window sizes are so large that not all bend values allowed within them with the available bits,
* then it automatically encodes the bend values within these windows.
*
* The TMTT L1 tracking code can optionally tighten these windows further (cfg option "KillLowPtStubs").
* This gives slightly more granular encoding with Pt > 3 GeV.
*
* TMTT histograms "hisBendFEVsLayerOrRingPS" & "hisBendFEVsLayerOrRing2S" produced by the "Histos" class
* are useful for debugging. *-------------------------------------------------------------------------------------------------------------------
*/

public:
DegradeBend(const TrackerTopology* trackerTopo) : theTrackerTopo_(trackerTopo) {}

DegradeBend() {}

// Given the original bend, flag indicating if this is a PS or 2S module, & detector identifier,
// this return the degraded stub bend, a boolean indicatng if stub bend was outside the assumed window
// size programmed below, and an integer indicating how many values of the original bend
// were grouped together into this single value of the degraded bend.
//
// (Input argument windowFEnew specifies the stub window size that should be used for this stub instead
// of the window sizes specified in TTStubAlgorithmRegister_cfi.py , but it will ONLY replace the latter
// sizes if it windowFEnew is smaller. If you always want to use TTStubAlgorithmRegister_cfi.py, then
// std::set windowFEnew to a large number, such as 99999.).
void degrade(float bend,
bool psModule,
const DetId& stDetId,
float windowFEnew,
float& degradedBend,
unsigned int& numInGroup) const;

private:
// Does the actual work of degrading the bend.
void work(float bend,
bool psModule,
const DetId& stDetId,
float windowFEnew,
float& degradedBend,
unsigned int& numInGroup,
unsigned int& windowHalfStrips) const;

private:
const TrackerTopology* theTrackerTopo_;

// Number of bits used to encoded bend output by FE electronics.
const unsigned int bitsPS_ = 3;
const unsigned int bits2S_ = 4;

// Stub window sizes as encoded in L1Trigger/TrackTrigger/interface/TTStubAlgorithm_official.h
static const std::vector<double> barrelCut_;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remaining static variables

Copy link
Contributor Author

@tomalin tomalin May 13, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are not static variables. They are static constants. I understand that these are guaranteed to be thread safe (starting with C++11). e.g. See http://www.cplusplus.com/forum/general/119146/ . Making them static avoids wasting CPU recreating them multiple times. The CMS coding rules say "avoid non-constant shared data".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since "static const" data is thread safe, and following the discussion leading to #29381 (comment) , we propose to leave this code unchanged.

static const std::vector<std::vector<double> > ringCut_;
static const std::vector<std::vector<double> > tiltedCut_;
static const std::vector<double> barrelNTilt_;
};

} // namespace tmtt
#endif
Loading