Added comments to BDtaunuDef and GraphDef

create_database/tuple_reader/BDtaunuDef.cc

@@ -7,6 +7,9 @@
 
 using namespace bdtaunu;
 
+// RecoDType
+// ---------
+
 RecoDTypeCatalogue::DType 
 RecoDTypeCatalogue::search_d_catalogue(std::vector<int> lund_list) const {
   std::vector<Alphabet> word;
@@ -25,6 +28,7 @@ RecoDTypeCatalogue::search_dstar_catalogue(std::vector<int> lund_list) const {
   return dstar_catalogue.find(word);
 }
 
+
 void RecoDTypeCatalogue::RegisterDecays() {
 
   // D catalogue
@@ -167,12 +171,8 @@ RecoDTypeCatalogue::Alphabet RecoDTypeCatalogue::LundToAlphabet(int lund) const
 }
 
 
-
-
-
-
-
-
+// McBType
+// -------
 
 McBTypeCatalogue::BMcType 
 McBTypeCatalogue::search_catalogue(std::vector<int> lund_list) const {

create_database/tuple_reader/BDtaunuDef.h

@@ -4,19 +4,22 @@
 #include <vector>
 #include <custom_cpp_utilities/trie.h>
 
-/*! \file bdtaunu_definitions.h
- *  \brief Constants defined for this analysis.
+/** @file BDtaunuDef.h
+ *  @brief Definitions of relevant quantities to the \f$B\rightarrow D\tau\nu\f$ analysis. 
+ *
+ *  Several types of quantities are defined in this file:
+ *  * Constants used throughout the analysis. 
+ *  * Particle decay modes. 
  *
- *  This file contains any constants and enumerations that are used
- *  throughout the analysis package.
  */
 
 namespace bdtaunu {
 
-const int UpsilonLund = 70553;
-const int B0Lund = 511;
-const int BcLund = 521;
-const int D0Lund = 421;
+// Lund ID of frequently encountered particles.
+const int UpsilonLund = 70553;    
+const int B0Lund = 511;          
+const int BcLund = 521;         
+const int D0Lund = 421;        
 const int DcLund = 411;
 const int Dstar0Lund = 423;
 const int DstarcLund = 413;
@@ -32,6 +35,7 @@ const int gammaLund = 22;
 const int protonLund = 2212;
 const int neutronLund = 2112;
 
+
 //! B meson flavors.
 enum class BFlavor {
   NoB = 0,                /*!< No \f$B\f$ meson. */
@@ -40,6 +44,8 @@ enum class BFlavor {
   null = -1,  /*!< Undefined */
 };
 
+
+//! \f$D/D^*\f$ modes that are reconstructed. 
 class RecoDTypeCatalogue {
 
   public:
@@ -73,7 +79,10 @@ class RecoDTypeCatalogue {
     };
 
 
+    //! Given a vector of \f$D\f$ daughters, return its decay mode or null.
     DType search_d_catalogue(std::vector<int>) const;
+
+    //! Given a vector of \f$D^*\f$ daughters, return its decay mode or null.
     DstarType search_dstar_catalogue(std::vector<int>) const;
 
     RecoDTypeCatalogue() { RegisterDecays(); }
@@ -92,7 +101,7 @@ class RecoDTypeCatalogue {
 
 };
 
-//! Reconstructed tau decay modes.
+//! \f$\tau\f$ modes that are reconstructed. 
 enum class TauType {
   NoTau = 0,               /*!< \f$ \tau^+\rightarrow \pi^+ \f$ */
   tau_pi = 1,              /*!< \f$ \tau^+\rightarrow \pi^+ \f$ */
@@ -103,9 +112,12 @@ enum class TauType {
 };
 
 
+//! Monte carlo truth \f$B\f$ meson types. 
 class McBTypeCatalogue {
 
   public:
+
+    //! See BDtaunuDef.cc for definitions. 
     enum class BMcType { 
       NoB = 0,
       Dtau = 1,
@@ -119,6 +131,7 @@ class McBTypeCatalogue {
       null = -1,
     };
 
+    //! Given a vector of \f$B^*\f$ daughters, return its MC type or null.
     BMcType search_catalogue(std::vector<int>) const;
 
     McBTypeCatalogue() { RegisterDecays(); }

create_database/tuple_reader/BDtaunuMcReader.cc

@@ -3,8 +3,8 @@
 #include <cmath>
 #include <cassert>
 
-#include "BDtaunuHelpers.h"
 #include "BDtaunuDef.h"
+#include "BDtaunuUtils.h"
 #include "BDtaunuReader.h"
 #include "BDtaunuMcReader.h"
 #include "McGraphManager.h"

create_database/tuple_reader/BDtaunuReader.cc

@@ -9,7 +9,7 @@
 #include <cassert>
 
 #include "BDtaunuDef.h"
-#include "BDtaunuHelpers.h"
+#include "BDtaunuUtils.h"
 #include "RootReader.h"
 #include "BDtaunuReader.h"
 #include "UpsilonCandidate.h"

create_database/tuple_reader/BDtaunuHelpers.cc → create_database/tuple_reader/BDtaunuUtils.cc

@@ -4,7 +4,7 @@
 #include <cassert>
 #include <map>
 
-#include "BDtaunuHelpers.h"
+#include "BDtaunuUtils.h"
 
 // Reads in __PDT_FILE_PATHNAME which contains one particle type on
 // each line in the format: "particle name" lundId, and puts the

create_database/tuple_reader/BDtaunuHelpers.h → create_database/tuple_reader/BDtaunuUtils.h

@@ -1,7 +1,7 @@
 #ifndef __HELPERS_H__
 #define __HELPERS_H__
 
-/*! \file utilities.h
+/*! \file BDtaunuUtils.h
  *  \brief General utility functions. 
  */
 

create_database/tuple_reader/GraphDef.cc

@@ -6,6 +6,9 @@
 #include <cassert>
 #include <initializer_list>
 
+// RecoIndexer
+// -----------
+
 RecoGraph::RecoIndexer::RecoIndexer() : 
   nY(0), nB(0), nD(0), nC(0), 
   nh(0), nl(0), ngamma(0) {};

create_database/tuple_reader/GraphDef.h

@@ -6,6 +6,15 @@
 
 #include "BDtaunuDef.h"
 
+/** @file GraphDef.h
+ *  @brief Definition of graph quantities used in the tuple analysis. 
+ *
+ *  Several types of quantities are defined in this file:
+ *  * Boost graph typedefs.
+ *  * Graph satallite data. e.g. particle satellite data attached to vertices. 
+ *
+ */
+
 namespace boost {
   enum vertex_lund_id_t { vertex_lund_id };
   BOOST_INSTALL_PROPERTY(vertex, lund_id);
@@ -18,8 +27,15 @@ namespace boost {
   BOOST_INSTALL_PROPERTY(vertex, block_index);
 }
 
+namespace boost {
+  enum vertex_mc_index_t { vertex_mc_index };
+  BOOST_INSTALL_PROPERTY(vertex, mc_index);
+}
+
+//! Quantities for the reconstructed particle graph. 
 namespace RecoGraph {
 
+// Boost graph typedefs
 typedef boost::adjacency_list<
   boost::vecS, boost::vecS, boost::directedS,
   boost::property<boost::vertex_reco_index_t, int,
@@ -36,31 +52,43 @@ typedef typename boost::property_map<Graph, boost::vertex_lund_id_t>::type LundI
 typedef typename boost::property_map<Graph, boost::vertex_reco_index_t>::type RecoIndexPropertyMap;
 typedef typename boost::property_map<Graph, boost::vertex_block_index_t>::type BlockIndexPropertyMap;
 
-struct RecoLepton {
+//! Data attached to vertices of reconstructed leptons. 
+/** Leptons can be actual leptons or placeholder tau leptons 
+ * which are either \f$\pi\f$ or \f$\rho\f$ mesons. 
+ */
+struct Lepton {
   int l_block_idx = -1;
   int pi_block_idx = -1;
   int tau_mode = static_cast<int>(bdtaunu::TauType::null);
 };
 
-struct RecoD {
-  RecoD() = default;
+//! Data attached to vertices of reconstructed \f$D/D^*\f$ mesons. 
+/** This stores information for both \f$D\f$ and \f$D^*\f$ mesons. 
+ * For \f$D^*\f$'s all entries are filled. For \f$D\f$'s, the `Dstar_mode`
+ * entry will indicate `NoDstar` as in RecoDTypeCatalogue::DstarType.
+ */
+struct D {
+  D() = default;
   int D_mode = static_cast<int>(bdtaunu::RecoDTypeCatalogue::DType::null);
   int Dstar_mode = static_cast<int>(bdtaunu::RecoDTypeCatalogue::DstarType::NoDstar);
 };
 
-struct RecoB {
-  RecoB() = default;
+//! Data attached to vertices of reconstructed \f$B\f$ mesons. 
+struct B {
+  B() = default;
   int flavor = static_cast<int>(bdtaunu::BFlavor::null);
-  RecoD *D = nullptr;
-  RecoLepton *Lepton = nullptr;
+  D *D = nullptr;
+  Lepton *Lepton = nullptr;
 };
 
-struct RecoY {
-  RecoY() = default;
-  RecoB *tagB = nullptr;
-  RecoB *sigB = nullptr;
+//! Data attached to vertices of reconstructed \f$\Upsilon(4S)\f$ mesons. 
+struct Y {
+  Y() = default;
+  B *tagB = nullptr;
+  B *sigB = nullptr;
 };
 
+
 /** @brief This class assigns a unique index to each reconstructed particle.
  *
  * @detail 
@@ -106,22 +134,10 @@ class RecoIndexer {
 }
 
 
-
-
-
-
-
-
-
-
-
-namespace boost {
-  enum vertex_mc_index_t { vertex_mc_index };
-  BOOST_INSTALL_PROPERTY(vertex, mc_index);
-}
-
+//! Quantities for the MC truth particle graph. 
 namespace McGraph {
 
+// Boost graph typedefs
 typedef boost::adjacency_list<
   boost::vecS, boost::vecS, boost::directedS,
   boost::property<boost::vertex_mc_index_t, int,
@@ -136,23 +152,26 @@ typedef typename boost::graph_traits<Graph>::adjacency_iterator AdjacencyIterato
 typedef typename boost::property_map<Graph, boost::vertex_lund_id_t>::type LundIdPropertyMap;
 typedef typename boost::property_map<Graph, boost::vertex_mc_index_t>::type McIndexPropertyMap;
 
-struct McTau {
-  McTau() = default;
+//! Data attached to vertices of \f$\tau\f$ leptons. 
+struct Tau {
+  Tau() = default;
   int mc_type = static_cast<int>(bdtaunu::TauMcType::null);
 };
 
-struct McB {
-  McB() = default;
+//! Data attached to vertices of \f$B\f$ mesons. 
+struct B {
+  B() = default;
   int flavor = static_cast<int>(bdtaunu::BFlavor::null);
   int mc_type = static_cast<int>(bdtaunu::McBTypeCatalogue::BMcType::null);
-  McTau *tau = nullptr;
+  Tau *tau = nullptr;
 };
 
-struct McY {
-  McY() = default;
+//! Data attached to vertices of \f$\Upsilon(4S)\f$ mesons. 
+struct Y {
+  Y() = default;
   bool isBBbar = true;
-  McB *B1 = nullptr;
-  McB *B2 = nullptr;
+  B *B1 = nullptr;
+  B *B2 = nullptr;
 };
 
 }

create_database/tuple_reader/Makefile

@@ -14,7 +14,7 @@ PKG_LIBPATH = lib
 
 # package Contents
 SOURCES = BDtaunuDef.cc GraphDef.cc \
-          BDtaunuHelpers.cc UpsilonCandidate.cc \
+          BDtaunuUtils.cc UpsilonCandidate.cc \
 					RootReader.cc BDtaunuReader.cc BDtaunuMcReader.cc \
 					RecoGraphVisitors.cc RecoGraphManager.cc \
 					McGraphManager.cc McGraphVisitors.cc

create_database/tuple_reader/McGraphManager.cc

@@ -123,23 +123,23 @@ void McGraphManager::analyze_graph() {
   return;
 }
 
-const McY* McGraphManager::get_mcY() const {
+const Y* McGraphManager::get_mcY() const {
   if (Y_map.size()) {
     return &Y_map.begin()->second;
   } else {
     return nullptr;
   }
 }
 
-const McB* McGraphManager::get_mcB1() const {
+const B* McGraphManager::get_mcB1() const {
   if (B_map.size()) {
     return &B_map.begin()->second;
   } else {
     return nullptr;
   }
 }
 
-const McB* McGraphManager::get_mcB2() const {
+const B* McGraphManager::get_mcB2() const {
   if (B_map.size()) {
     return &(++B_map.begin())->second;
   } else {

create_database/tuple_reader/McGraphManager.h

@@ -111,13 +111,13 @@ class McGraphManager : public GraphManager {
     void clear();
 
     //! Returns pointer to the MC truth \f$\Upsilon(4S)\f$ if it exists, nullptr otherwise.
-    const McGraph::McY* get_mcY() const;
+    const McGraph::Y* get_mcY() const;
 
     //! Returns pointer to one of the MC truth \f$B\f$ if it exists, nullptr otherwise.
-    const McGraph::McB* get_mcB1() const;
+    const McGraph::B* get_mcB1() const;
 
     //! Returns pointer to the other MC truth \f$B\f$ if it exists, nullptr otherwise.
-    const McGraph::McB* get_mcB2() const;
+    const McGraph::B* get_mcB2() const;
 
   private:
 
@@ -137,9 +137,9 @@ class McGraphManager : public GraphManager {
     void ClearGraph();
 
     // Graph analysis
-    std::map<McGraph::Vertex, McGraph::McY> Y_map;
-    std::map<McGraph::Vertex, McGraph::McB> B_map;
-    std::map<McGraph::Vertex, McGraph::McTau> Tau_map;
+    std::map<McGraph::Vertex, McGraph::Y> Y_map;
+    std::map<McGraph::Vertex, McGraph::B> B_map;
+    std::map<McGraph::Vertex, McGraph::Tau> Tau_map;
     void ClearAnalysis();
 
 };