From 18b7997e6f48c5c5fff486bf62c72899adae1e5b Mon Sep 17 00:00:00 2001
From: Sylvester Joosten <sjoosten@anl.gov>
Date: Wed, 22 Sep 2021 17:10:16 +0000
Subject: [PATCH] Better consistency in EICD, preparing to store MC truth
 links.

 - Cleanup comments
 - Improved variable names for ClusterRelations
 - ProtoClusters now use VectorMembers for smaller memory footprint
 - Get rid of ClusterInfo structures, merging relevant parts into
 Cluster
 - Add provision for MC truth info to Cluster
---
 dd4hep.yaml   | 185 ++++++++++++++++++++++++++++++--------------------
 eic_data.yaml | 135 +++++++++++++++++-------------------
 2 files changed, 174 insertions(+), 146 deletions(-)

diff --git a/dd4hep.yaml b/dd4hep.yaml
index 5c091be..18f6a1f 100644
--- a/dd4hep.yaml
+++ b/dd4hep.yaml
@@ -7,96 +7,131 @@ options :
   includeSubfolder: True
 
 components:
-  dd4pod::ThreeVector:
-    #Description: "three vector"
-    #Author : "W.Armstrong"
+
+  dd4pod::VectorXYZ:
     Members:
-      - double x
-      - double y
-      - double z
+      - double x          // [mm] or [GeV]
+      - double y          //
+      - double z          //
+    ExtraCode:
+      includes: "#include <cmath>\n#include<tuple>"
+      declaration: "
+        VectorXYZ() : x{0}, y{0}, z{0} {}\n
+        VectorXYZ(double xx, double yy, double zz) : x{xx}, y{yy}, z{zz} {}\n
+        double& operator[](unsigned i) {return *(&x + i);}\n
+        const double& operator[](unsigned i) const {return *(&x + i);}\n
+        double mag() const {return std::hypot(x, y, z);}\n
+        double r() const {return mag();}\n
+        double theta() const {return acos(z/mag());}\n
+        double phi() const {return atan2(y,x);}\n
+        double eta() const {return -log(tan(0.5*theta()));}\n
+        operator std::tuple<double, double, double>() {return {x, y, z};}\n
+        double dot(const VectorXYZ& rhs) const {return x*rhs.x + y*rhs.y + z*rhs.z;}\n
+        VectorXYZ add(const VectorXYZ& rhs) const {return {x+rhs.x, y+rhs.y, z+rhs.z};}\n
+        VectorXYZ subtract(const VectorXYZ& rhs) const {return {x-rhs.x, y-rhs.y, z-rhs.z};}\n
+        VectorXYZ scale(double f) const {return {f*x, f*y, f*z};}\n
+      "
 
   dd4pod::MonteCarloContrib:
-    #Description: "Podio implementation of dd4hep's dd4hep::sim::MonteCarloContrib class"
-    #Author : "W.Armstrong"
     Members:
-      - int trackID // track id
-      - int pdgID // pdgID
-      - double deposit // en deposit
-      - double time // time
-      - double length //length
-      - double x // x
-      - double y // x
-      - double z // x
-
-datatypes :
-
-  dd4pod::FourVector :
-    Description: "four vector"
-    Author : "W.Armstrong"
-    Members :
-      - double x // x
-      - double y // y
-      - double z // z
-      - double t // t
+      - int32_t   trackID // track id, -1 if none/invalid. Maps to Geant4Particle::ID.
+      - int32_t   pdgID   // PDG Particle ID code 
+      - double    deposit // energy deposit [GeV]
+      - double    time    // time [ns]
+      - double    length  // length [mm]
+      - float     x       // x position [mm]
+      - float     y       // y position [mm]
+      - float     z       // z position [mm]
+    ExtraCode:
+      includes: "#include <cmath>"
+      declaration: "
+        MonteCarloContrib() : trackID{-1}, pdgID{0}, deposit{0}, time{0}, x{0}, y{0}, z{0} {}\n
+        MonteCarloContrib(int32_t id, int32_t pdg, double e, double t,\n
+                          double l, double xx, double yy, double zz)\n
+            : trackID{id}, pdgID{pdg}, deposit{e}, time{t}, length{l}\n
+            , x{static_cast<float>(xx)}, y{static_cast<float>(yy)}, z{static_cast<float>(zz)} {}\n
+        double mag() const {return std::hypot(x, y, z);}\n
+        double r() const {return mag();}\n
+        double theta() const {return acos(z/mag());}\n
+        double phi() const {return atan2(y,x);}\n
+        double eta() const {return -log(tan(0.5*theta()));}
+        bool valid() const {return trackID >= 0;}\n
+        bool empty() const {return trackID < 0;}\n
+      "
 
+datatypes:
 
   dd4pod::Geant4Particle:
     Description: "Podio implementation of dd4hep's dd4hep::sim::Geant4Particle class"
-    Author : "W.Armstrong"
+    Author : "W. Armstrong, S. Joosten"
+    Members:
+      - int32_t                   ID                // unique identifier for this particle
+      - int32_t                   g4Parent          // g4 parent particle
+      - int32_t                   reason            // TODO document
+      - int32_t                   mask              // TODO document
+      - int32_t                   steps             // TODO document
+      - int32_t                   secondaries       // TODO document
+      - int32_t                   pdgID             // TODO document
+      - int32_t                   status            // TODO document
+      - std::array<int,2>         colorFlow         // TODO document
+      - int32_t                   genStatus         // Generator status code
+      - int32_t                   charge            // Particle charge
+      - int32_t                   _spare            // extra int to have doubles properly aligned at 8 bytes
+      - std::array<float,3>       spin              // Particle spin state
+      - dd4pod::VectorXYZ         vs                // Start vertex [mm]
+      - dd4pod::VectorXYZ         ve                // End vertex [mm]
+      - dd4pod::VectorXYZ         ps                // 3-momentum at start vertex [GeV]
+      - dd4pod::VectorXYZ         pe                // 3-momentum at end vertex [GeV]
+      - double                    mass              // particle mass [GeV]
+      - double                    time              // start vertex time [ns]
+      - double                    properTime        // proper time
+    VectorMembers:
+      - int32_t                   parents           // parent IDs
+      - int32_t                   daughters         // daughter IDs
+    ConstExtraCode :
+      declaration: "
+        double px() const {return ps().x;}\n
+        double py() const {return ps().y;}\n
+        double pz() const {return ps().z;}\n
+        double energy() const {return std::hypot(ps().mag(), mass());}
+      "
+
+  dd4pod::PhotoMultiplierHit:
+    Description: "Podio implementation of a pmt hit "
+    Author : "W. Armstrong, S. Joosten"
     Members:
-      - int ID // x
-      - int g4Parent  // x
-      - int reason // x
-      - int mask // x
-      - int steps // x
-      - int secondaries // x
-      - int pdgID // x
-      - int status // x
-      - std::array<int,2> colorFlow // x
-      - int  genStatus // x
-      - int  charge   // x
-      - std::array<int,1> spare // x
-      - std::array<float,3>  spin  // x
-      - double vsx   // x
-      - double vsy   // x
-      - double vsz  // x
-      - double vex   // x
-      - double vey   // x
-      - double vez  // x
-      - double psx   // x
-      - double psy   // x
-      - double psz  // x
-      - double pex   // x
-      - double pey   // x
-      - double pez  // x
-      - double mass  // x
-      - double time  // x
-      - double properTime // x 
-    OneToManyRelations:
-      - dd4pod::Geant4Particle parents  // x
-      - dd4pod::Geant4Particle daughters  // x
+      - int64_t                   cellID            // cellID
+      - int32_t                   flag              // User flag to classify hits
+      - int32_t                   g4ID              // Original Geant4 track identifier of the creating track (for debugging)
+      - dd4pod::VectorXYZ         position          // hit position [mm]
+      - dd4pod::VectorXYZ         momentum          // 3-momentum [GeV]
+      - double                    length            // length [mm]
+      - dd4pod::MonteCarloContrib truth             // truth info
+      - double                    energy            // photon energy [GeV]
 
   dd4pod::TrackerHit:
     Description: "Podio implementation of dd4hep's dd4hep::sim::Geant4Tracker::Hit class"
-    Author : "W.Armstrong"
+    Author : "W. Armstrong, S. Joosten"
     Members:
-      - long cellID  // cellID
-      - long flag    // User flag to classify hits
-      - long g4ID    // Original Geant 4 track identifier of the creating track (debugging)
-      - dd4pod::ThreeVector position // position 
-      - dd4pod::ThreeVector momentum // momentum
-      - double length // length 
-      - dd4pod::MonteCarloContrib truth // truth 
-      - double energyDeposit // energyDeposit
+      - int64_t                   cellID            // cellID
+      - int32_t                   flag              // User flag to classify hits
+      - int32_t                   g4ID              // Original Geant4 track identifier of the creating track (debugging)
+      - dd4pod::VectorXYZ         position          // position [mm]
+      - dd4pod::VectorXYZ         momentum          // 3-momentum [GeV]
+      - double                    length            // length [mm]
+      - dd4pod::MonteCarloContrib truth             // truth info
+      - double                    energyDeposit     // energy deposit [GeV]
 
   dd4pod::CalorimeterHit:
     Description: "Podio implementation of dd4hep's dd4hep::sim::Geant4Calorimeter::Hit class"
-    Author : "W.Armstrong"
+    Author : "W. Armstrong, S. Joosten"
     Members:
-      - long cellID  // cellID 
-      - long flag // User flag to classify hits
-      - long g4ID // Original Geant 4 track identifier of the creating track (debugging)
-      - dd4pod::ThreeVector position // position
-      - dd4pod::MonteCarloContrib truth // truth
-      - double energyDeposit // energyDeposit
+      - int64_t                   cellID            // cellID 
+      - int32_t                   flag              // User flag to classify hits
+      - int32_t                   g4ID              // Original Geant4 track identifier of the creating track (debugging)
+      - dd4pod::VectorXYZ         position          // position [mm]
+      - dd4pod::MonteCarloContrib truth             // truth-info of one of the contributing hits
+      - double                    energyDeposit     // energy deposit [GeV]
+    VectorMembers:
+      - dd4pod::MonteCarloContrib contributions     // All contributing hits. Not filled by default.
 
diff --git a/eic_data.yaml b/eic_data.yaml
index 27843a3..c46dc47 100644
--- a/eic_data.yaml
+++ b/eic_data.yaml
@@ -58,6 +58,12 @@ components:
         operator float() const {return value;}
       "
 
+  ## Index with weight
+  eic::WeightedIndex:
+    Members:
+      - eic::Index  ID
+      - eic::Weight weight
+
   ## first-second pair of float s
   eic::FloatPair:
     Members:
@@ -248,7 +254,7 @@ datatypes:
     Members:
       - uint64_t          run              // Run number.
       - uint64_t          number           // Event number.
-      - int32_t           type             // event type identifier (TBD).
+      - int32_t           type             // Event type identifier (TBD).
       - int32_t           proc             // Process identifier (TBD).
       - int32_t           source           // Source/identifier (TBD)
       - eic::Weight       weight           // Optional event weight (useful for MC)
@@ -263,10 +269,10 @@ datatypes:
     Author: "W. Armstrong, S. Joosten"
     Members:
       - eic::Index        ID                // Unique particle index
-      - eic::VectorXYZ    p                 // momentum [GeV]
-      - eic::VectorXYZ    v                 // vertex [mm]
+      - eic::VectorXYZ    p                 // Momentum [GeV]
+      - eic::VectorXYZ    v                 // Vertex [mm]
       - float             time              // Time in [ns]
-      - int32_t           pid               // particle PDG code
+      - int32_t           pid               // Particle PDG code
       - int16_t           status            // Status code
       - int16_t           charge            // Particle charge (or sign)
       - eic::Weight       weight            // Particle weight, e.g. from PID algorithm [0-1]
@@ -276,8 +282,8 @@ datatypes:
     Author: "W. Armstrong, S. Joosten"
     Members:
       - eic::Index        ID                // Unique particle index
-      - eic::VectorXYZ    p                 // momentum vector [GeV]
-      - eic::VectorXYZ    v                 // vertex [mm]
+      - eic::VectorXYZ    p                 // Momentum vector [GeV]
+      - eic::VectorXYZ    v                 // Vertex [mm]
       - float             time              // Time in [ns]
       - int32_t           pid               // PID of reconstructed particle.
       - int16_t           status            // Status code
@@ -308,7 +314,7 @@ datatypes:
     Description: "Raw (digitized) calorimeter hit"
     Author: "W. Armstrong, S. Joosten"
     Members:
-      - eic::Index        ID                // unique ID for this hit
+      - eic::Index        ID                // Unique hit ID. For MC, the value equals the Geant4 hit index.
       - int64_t           cellID            // The detector specific (geometrical) cell id.
       - int64_t           amplitude         // The amplitude of the hit in ADC counts.
       - int64_t           time              // Timing in TDC
@@ -317,10 +323,10 @@ datatypes:
     Description: "Calorimeter hit"
     Author: "W. Armstrong, S. Joosten"
     Members:
-      - eic::Index        ID                // unique ID for this hit
+      - eic::Index        ID                // Unique hit ID, same as one of the involved raw hits.
       - int64_t           cellID            // The detector specific (geometrical) cell id.
-      - int32_t           layer             // layer for this hit
-      - int32_t           sector            // sector for this hit
+      - int32_t           layer             // Layer for this hit
+      - int32_t           sector            // Sector for this hit
       - float             energy            // The energy for this hit in [GeV].
       - float             energyError       // Error on energy [GeV].
       - float             time              // The time of the hit in [ns].
@@ -337,48 +343,35 @@ datatypes:
     Description: "Relational info linking hits to their associated cluster"
     Author: "S. Joosten"
     Members:
-      - eic::Index        hitID             // Hit ID
-      - eic::Index        clusterID         // ID of the cluster associated with this hit (-1 if none)
-      - eic::Weight       weight            // How much of this hit belongs to the cluster? [0->1]
+      - eic::Index        ID                // ID of the cluster 
+    VectorMembers:
+      - eic::WeightedIndex hits             // List of hits associated with the cluster
 
   eic::Cluster:
     Description: "EIC cluster"
     Author: "W. Armstrong, S. Joosten, C.Peng"
     Members:
-      - eic::Index        ID                // unique ID for this cluster
+      - eic::Index        ID                // Unique ID for this cluster, value identical to ProtoCluster ID
       - float             energy            // Reconstructed energy of the cluster [GeV].
       - float             energyError       // Error on the cluster energy [GeV]
       - float             time              // [ns]
       - uint32_t          nhits             // Number of hits in the cluster.
       - eic::VectorXYZ    position          // Global position of the cluster [mm].
       - eic::CovXYZ       positionError     // Covariance matrix of the position (6 Parameters).
-      - float             radius            // shower radius [mm]
-      - float             skewness          // shower skewness [unitless]
-
-  eic::Cluster2DInfo:
-    Description: "Additional info for 3D clusters" 
-    Author: "S. Joosten"
-    Members:
-      - eic::Index        clusterID         // Primary cluster ID
-      - eic::VectorPolar  polar             // Cluster position polar information
-      - float             eta               // Cluster pseudorapidity
-
-  eic::Cluster3DInfo:
-    Description: "Additional info for 3D clusters" 
-    Author: "S. Joosten"
-    Members:
-      - eic::Index        clusterID         // Primary cluster ID
+      - float             radius            // Shower radius [mm]
+      - float             skewness          // Shower skewness [unitless]
       - eic::VectorPolar  polar             // Cluster position polar information
       - float             eta               // Cluster pseudorapidity
-      - eic::Direction    direction         // Intrinsic direction of the cluster at the central position [rad, 0->pi and -pi->pi]
+      - eic::Direction    direction         // Intrinsic direction of the cluster propagation [rad, 0->pi, -pi->pi]
+      - eic::Index        mcID              // For MC only - associated MC particle
 
   eic::ClusterLayer:
     Description: "2D Cluster in a single layer for a multi-layer detector"
     Author: "S. Joosten, C. Peng"
     Members:
-      - eic::Index        ID                // unique layer ID
-      - eic::Index        clusterID         // associated full 3D cluster, -1 if none
-      - int32_t           layer             // layer number for this cluster layer
+      - eic::Index        ID                // Unique layer ID
+      - eic::Index        clusterID         // Associated full 3D cluster, -1 if none
+      - int32_t           layer             // Layer number for this cluster layer
       - uint32_t          nhits             // Number of hits
       - float             energy            // Energy in this cluster layer [GeV]
       - float             energyError       // Error on energy [GeV]
@@ -390,9 +383,9 @@ datatypes:
     Description: "Relational info between a merged cluster and its parents"
     Author: "S. Joosten"
     Members:
-      - eic::Index        clusterID         // associated cluster ID
-      - uint32_t          size              // number of valid parents
-      - std::array<eic::Index, 4> parent    // (up to 4) parents for this cluster
+      - eic::Index        clusterID         // Associated cluster ID
+      - uint32_t          size              // Number of valid parents
+      - std::array<eic::Index, 4> parent    // (Up to 4) parents for this cluster
 
   ## ==========================================================================
   ## RICH/Cherenkov data structures
@@ -402,7 +395,7 @@ datatypes:
     Description: "EIC Raw PMT hit"
     Author: "S. Joosten, C. Peng"
     Members:
-      - eic::Index        ID                // unique hit ID
+      - eic::Index        ID                // Unique hit ID. For MC, the value equals the Geant4 hit index.
       - int64_t           cellID            // The detector specific (geometrical) cell id.
       - uint32_t          amplitude         // PMT signal amplitude [ADC]
       - uint32_t          time              // PMT signal time [TDC]
@@ -411,9 +404,9 @@ datatypes:
     Description: "EIC PMT hit"
     Author: "S. Joosten, C. Peng"
     Members:
-      - eic::Index        ID                // Unique hit ID
+      - eic::Index        ID                // Unique hit ID, same as one of the involved raw hits.
       - int64_t           cellID            // The detector specific (geometrical) cell id.
-      - float             npe               // estimated number of photo-electrons [#]
+      - float             npe               // Estimated number of photo-electrons [#]
       - float             time              // Time [ns]
       - float             timeError         // Error on the time [ns]
       - eic::VectorXYZ    position          // PMT hit position [mm]
@@ -425,13 +418,13 @@ datatypes:
     Author: "S. Joosten, C. Peng"
     Members:
       - eic::Index        ID                // Unique cluster ID
-      - float             npe               // number of photo-electrons [#]
+      - float             npe               // Number of photo-electrons [#]
       - eic::VectorXYZ    position          // Global position of the cluster [mm]
       - eic::VectorXYZ    positionError     // Error on the position
-      - float             theta             // opening angle of the ring [rad, 0->pi]
-      - float             thetaError        // error on the opening angle
-      - float             radius            // radius of the best fit ring [mm]
-      - float             radiusError       // estimated error from the fit [mm]
+      - float             theta             // Opening angle of the ring [rad, 0->pi]
+      - float             thetaError        // Error on the opening angle
+      - float             radius            // Radius of the best fit ring [mm]
+      - float             radiusError       // Estimated error from the fit [mm]
 
   ## ==========================================================================
   ## Tracking
@@ -441,16 +434,16 @@ datatypes:
     Description: "Raw (digitized) tracker hit"
     Author: "W. Armstrong, S. Joosten"
     Members:
-      - eic::Index        ID                // unique ID for this hit
+      - eic::Index        ID                // Unique hit ID. For MC, the value equals the Geant4 hit index.
       - int64_t           cellID            // The detector specific (geometrical) cell id.
-      - int32_t           time              // tdc value.
-      - int32_t           charge            // adc value
+      - int32_t           time              // TDC value.
+      - int32_t           charge            // ADC value
 
   eic::TrackerHit:
     Description: "Tracker hit (reconstructed from Raw)"
     Author: "W. Armstrong, S. Joosten"
     Members:
-      - eic::Index        ID                // unique ID for this hit
+      - eic::Index        ID                // Unique hit ID, same as one of the involved raw hits.
       - int64_t           cellID            // The detector specific (geometrical) cell id.
       - eic::VectorXYZT   position          // Hit (cell) position and time [mm, ns]
       - eic::CovDiagXYZT  covMatrix         // Covariance Matrix
@@ -478,37 +471,37 @@ datatypes:
     Description: "ACTS Bound Track parameters"
     Author: "W. Armstrong, S. Joosten"
     Members:
-      - eic::Index        ID                // unique ID for this track 
-      - eic::FloatPair    loc               // tracking location
-      - eic::FloatPair    locError          // error on the location
-      - eic::Direction    direction         // track direction (theta, phi) [rad, 0-pi and -pi->pi]
-      - eic::Direction    directionError    // error on the direction [rad]
+      - eic::Index        ID                // Unique track ID.
+      - eic::FloatPair    loc               // Tracking location
+      - eic::FloatPair    locError          // Error on the location
+      - eic::Direction    direction         // Track direction (theta, phi) [rad, 0-pi and -pi->pi]
+      - eic::Direction    directionError    // Error on the direction [rad]
       - float             qOverP            // [e/GeV]
-      - float             qOverPError       // error on qOverP
-      - float             time              // track time [ns]    
-      - float             timeError         // error on the time
-      - float             charge            // assumed track charge, units of [e]
+      - float             qOverPError       // Error on qOverP
+      - float             time              // Track time [ns]    
+      - float             timeError         // Error on the time
+      - float             charge            // Assumed track charge, units of [e]
 
   eic::Trajectory:
     Description: "Trajectory"
     Author: "W. Armstrong, S. Joosten"
     Members:
-      - eic::Index        ID                // unique ID for this trajectory 
-      - eic::Index        protoTrackID      // proto track index
-      - eic::Index        parameters        // index for track parameters
-      - eic::VectorXYZT   momentum          // postion of vertex [mm]
-      - float             length            // track length from first to last hit[mm]
-      - float             charge            // charge of particle trajectory
-      - float             TOF               // time of flight from first to last hit [ns]
+      - eic::Index        ID                // Unique trajectory ID, the value equals the track ID.
+      - eic::Index        protoTrackID      // Proto track index
+      - eic::Index        parameters        // Index for track parameters
+      - eic::VectorXYZT   momentum          // Postion of vertex [mm]
+      - float             length            // Track length from first to last hit[mm]
+      - float             charge            // Charge of particle trajectory
+      - float             TOF               // Time of flight from first to last hit [ns]
 
 
   eic::Track:
     Description: "Particle Track"
     Author: "W. Armstrong, S. Joosten"
     Members:
-      - eic::Index        ID                // unique ID for this track 
-      - eic::Index        parameters        // index for track parameters
-      - eic::VectorXYZT   momentum          // momentum of vertex [mm]
+      - eic::Index        ID                // Unique track ID.
+      - eic::Index        parameters        // Index for track parameters
+      - eic::VectorXYZT   momentum          // Momentum of vertex [mm]
 
 
   ## ==========================================================================
@@ -519,9 +512,9 @@ datatypes:
     Description: "EIC vertex"
     Author: "W. Armstrong, S. Joosten"
     Members:
-      - eic::Index        ID                // unique vertex ID
-      - eic::VectorXYZ    position          // postion of vertex [mm]
-      - float             time              // time of vertex [ns]
+      - eic::Index        ID                // Unique vertex ID
+      - eic::VectorXYZ    position          // Postion of vertex [mm]
+      - float             time              // Time of vertex [ns]
       - float             chi2              // Chi squared of the vertex fit.
       - float             probability       // Probability of the vertex fit
       - bool              primary           // Whether it is the primary vertex of the event
-- 
GitLab