Candidate/doc/Candidate.doc

0001 /*!
0002 \page DataFormats_Candidate Package DataFormats/Candidate
0003 <center>
0004 <small>
0005 <a href=http://cmsdoc.cern.ch/swdev/viewcvs/viewcvs.cgi/CMSSW/DataFormats/Candidate/?cvsroot=CMSSW>CVS head for this package</a> -
0006 <a href=http://cmsdoc.cern.ch/swdev/viewcvs/viewcvs.cgi/CMSSW/DataFormats/Candidate/.admin/developers?rev=HEAD&cvsroot=CMSSW&content-type=text/vnd.viewcvs-markup>Administrative privileges</a>
0007 </small>
0008 </center>
0009
0010 \section desc Description
0011 Classes defining particle candidate. The class reco::Candidate is
0012 intended to be a common class for many Physics Analysis tools.
0013
0014 \subsection interface Public interface
0015 - reco::Particle: a reconstructed particle with momentum 4-vector, a vertex and an electric charge.
0016 - reco::Candidate: a generic reconstructed particle candidates. It adds
0017   to reco::Particle interface for navigation among constituents.
0018   Utilities to extract components from a reco::Candidate avoiding explicit <tt>dynamic_cast</tt>
0019   are provided. A tag struct can be used as optional second template parameter to
0020   disambiguate between more components in a Candidate of the same type.
0021   The following example shows how to extract references to a reco::Track or reco::Muon.
0022   The following syntaxes are all equivalent:
0023 \htmlonly
0024 <pre>
0025   const Candidate & cand = ...;
0026   TrackRef track1 = c.get&lt;TrackRef&gt;( c );
0027   TrackRef track2 = get&lt;TrackRef&gt;( c );
0028   TrackRef track3 = component&lt;TrackRef&gt;::get( c );
0029 </pre>
0030 \endhtmlonly
0031   It is possible to access different types of components,
0032   but you have to get sure to <tt>#include</tt> the
0033   header files of the concrete candidate subclass in order
0034   to define the proper template specialization.
0035 \htmlonly
0036 <pre>
0037   const Candidate & c = ...;
0038   TrackRef track = c.get&lt;TrackRef&gt;();
0039   SuperClusterRef cluster = c.get&lt;SuperClusterRef&gt;();
0040
0041   const Candidate & g = ...;
0042   const HepMC::GenParticle * gen = g.get&lt;const HepMC::GenParticle *&gt;();
0043 </pre>
0044 \endhtmlonly
0045   In case of multiple components of the same type, it is possible to specify an extra
0046   "tag" to disentangle the ambiguity. For instance:
0047 \htmlonly
0048 <pre>
0049   const Candidate & muon = ...;
0050   // tracker fit: default
0051   TrackRef trackerFit = muon.get&lt;TrackRef&gt;();
0052   // stand alone muon fit
0053   TrackRef standAloneMuFit = muon.get&lt;TrackRef, StandAloneMuonTag&gt;();
0054   // combined muon + tracker fit
0055   TrackRef combinedFit = muon.get&lt;TrackRef, CombinedMuonTag&gt;();
0056 </pre>
0057 \endhtmlonly
0058 - reco::LeafCandidate: a reco::Candidate with no component nor daughters.
0059 Suitable to store just 4-vector, vertex and electric charge.
0060 - reco::CompositeCandidate: a composite reco::Candidate where the daughters
0061 are owned by the composite candidate.
0062 - reco::CompositeRefCandidate: a composite reco::Candidate where the daughters
0063 have persistent references (edm::RefVector <b><...></b>) to reco::Candidate stored in
0064 a separate collection.
0065 - reco::CompositeRefBaseCandidate: a composite reco::Candidate  where the daughters
0066 have persistent references (edm::RefToBase <b><...></b>) to reco::Candidate stored in
0067 a separate collection of concrete types.
0068 - reco::ShallowCloneCandidate: a candidate with a reference to a "master clone". All
0069 methods, except the kinematics, that is copied, are delegated to the master clone.
0070 - OverlapChecker: utility to check overlap between two candidates,
0071   looking for a common component recursively along daughters.
0072
0073
0074 \subsection typedefs
0075 - reco::CandidateCollection: collection of reco::Candidate objects
0076 - reco::CandidateRef: persistent reference to a reco::Candidate object
0077 - reco::CandidateBaseRef: persistent reference to a reco::Candidate object as base class
0078 - reco::CandidateRefProd: reference to a reco::Candidate collection
0079 - reco::CandidateRefVector: vector of references to reco::Candidate objects in the same collection
0080 - reco::candidate_iterator: iterator over a vector of references to reco::Candidate objects in the same collection
0081 - reco::CandMatchMap: one-to-one candidate association map by reference
0082
0083 \subsection modules Modules
0084 None.
0085
0086 \subsection tests Unit tests and examples
0087 - <b>testParticle</b>: test reco::Particle class
0088 - <b>testCompositeCandidate</b>: test reco::CompositeCandidate class
0089 - <b>testSetup</b>: test reco::Setup mechanism
0090
0091 \section status Status and planned development
0092 Complete.
0093
0094 <hr>
0095 Last updated: @DATE@ L. Lista
0096 */