An alternative implementation of a type for HGCROC output (#116)

### Briefly, what does this PR introduce?

This PR introduces two types to facilitate work with the output of
HGCROC chips:
1. The component, `edm4eic::HGCROCSample`, which defines for a given
sample read out by the a chip
    - the ADC,
    - the Time of Arrival (TOA),
    - the Time over Threshold (TOT),
    - and the in-progress/complete relevant flags for TOT;
2. And the datatype, `edm4eic::RawHGCROCHit`, which consolidates for a
given hit
    - the geometrical information (cell ID)
    - the time information (time stamp and sample phase),
- and the relevant samples organized into a time series (represented as
a vector member).

This PR is intended to supersede #101. It makes two distinct design
choices from #101 informed by experience from the 2024 LFHCAL and
EEEMCal test beams, both of which utilized HGCROC prototypes.
1. Rather than define separate vector members for the ADC, TOA, and TOT
values, these values are collected into a component which are then
stored as a vector. This more closely matches what the HGCROC actually
reads out, where each value is technically read out once per sample
(even if some, such as the TOA and TOT are zero for most).
2. The dual readout ("Type B") chips are intentionally **not** supported
by this type. This is because such chips are currently not available nor
in use. It is assumed that the processing of such a chip would be
significantly different than the current chips actually in use ("Type
A"), and as such would be better supported by a distinct type.

### What kind of change does this PR introduce?
- [ ] Bug fix (issue #__)
- [x] New feature (issue #89 )
- [ ] Documentation update
- [ ] Other: __

### Please check if this PR fulfills the following:
- [ ] Tests for the changes have been added
- [ ] Documentation has been added / updated
- [x] Changes have been communicated to collaborators

### Does this PR introduce breaking changes? What changes might users
need to make to their code?

No.

### Does this PR change default behavior?

No.

---------

Co-authored-by: Dmitry Kalinkin <[email protected]>

Author: ruse-traveler

CMakeLists.txt

@@ -7,7 +7,7 @@ project(EDM4EIC
   LANGUAGES CXX)
 
 SET( ${PROJECT_NAME}_VERSION_MAJOR 8 )
-SET( ${PROJECT_NAME}_VERSION_MINOR 2 )
+SET( ${PROJECT_NAME}_VERSION_MINOR 3 )
 SET( ${PROJECT_NAME}_VERSION_PATCH 0 )
 SET( ${PROJECT_NAME}_VERSION  "${${PROJECT_NAME}_VERSION_MAJOR}.${${PROJECT_NAME}_VERSION_MINOR}.${${PROJECT_NAME}_VERSION_PATCH}" )
 

edm4eic.yaml

@@ -9,7 +9,7 @@
 ## If there are schema version changes that can be evolved, see the podio documentation
 ## for an example: https://github.com/AIDASoft/podio/tree/master/tests/schema_evolution
 ##
-schema_version: 820
+schema_version: 830
 
 options :
   # should getters / setters be prefixed with get / set?
@@ -191,6 +191,15 @@ components:
       - uint32_t boundValuesSize          // size of bound values
       - std::array<double,16> transform   // row-wise 4x4 affine transform [R T; 0 1] with 3x3 rotation matrix R and translation column 3-vector T
 
+  ## An individual sample output by an HGCROC chip
+  edm4eic::HGCROCSample:
+    Members:
+      - uint16_t ADC                // [ADC Counts], amplitude of signal during sample, valid IFF TOTInProgress is false
+      - uint16_t timeOfArrival      // Time of arrival (TOA) [TDC counts], nonzero IFF ADC crossed threshold upwards during sample
+      - uint16_t timeOverThreshold  // Time over threshold (TOT) [TDC counts], nonzero IFF ADC crossed threshold downwards during sample AND if TOA fired in a previous sample
+      - bool     TOTInProgress      // Flag which indicates if TOT calculation is ongoing, ADC value may be corrupted if this is true
+      - bool     TOTComplete        // Flag which indicates if a TOT calculation is complete and TOT value is valid
+
 datatypes:
 
   edm4eic::Tensor:
@@ -258,6 +267,17 @@ datatypes:
   ## ==========================================================================
   ## Calorimetry
   ## ==========================================================================
+
+  edm4eic::RawHGCROCHit:
+    Description: "Raw hit from an HGCROC chip"
+    Author: "D. Anderson, S. Joosten, T. Protzman, N. Novitzky, D. Kalinkin"
+    Members:
+      - uint64_t cellID                // Detector specific (geometrical) cell id
+      - int32_t  samplePhase           // Phase of samples in [# samples], for synchronizing across chips
+      - int32_t  timeStamp             // [TDC counts]
+    VectorMembers:
+      - edm4eic::HGCROCSample samples  // ADC, Time of Arrival (TOA), and Time over Threshold (TOT) values for each sample read out
+
   edm4eic::CalorimeterHit:
     Description: "Calorimeter hit"
     Author: "W. Armstrong, S. Joosten"