feat: measurement and sim-hit tables for the Arrow/Parquet output

Examples/Io/Arrow/CMakeLists.txt

@@ -1,6 +1,7 @@
 add_library(
     ActsExamplesIoArrow_obj
     OBJECT
+    src/ArrowMeasurementOutputConverter.cpp
     src/ArrowParticleOutputConverter.cpp
     src/ArrowSimHitOutputConverter.cpp
     src/ArrowTrackOutputConverter.cpp

Examples/Io/Arrow/include/ActsExamples/Io/Arrow/ArrowMeasurementOutputConverter.hpp

@@ -0,0 +1,109 @@
+// This file is part of the ACTS project.
+//
+// Copyright (C) 2016 CERN for the benefit of the ACTS project
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+#pragma once
+
+#include "Acts/Geometry/GeometryIdentifier.hpp"
+#include "Acts/Geometry/TrackingGeometry.hpp"
+#include "ActsExamples/EventData/Cluster.hpp"
+#include "ActsExamples/EventData/Measurement.hpp"
+#include "ActsExamples/EventData/SimHit.hpp"
+#include "ActsExamples/EventData/SimParticle.hpp"
+#include "ActsExamples/EventData/TruthMatching.hpp"
+#include "ActsExamples/Framework/DataHandle.hpp"
+#include "ActsExamples/Io/Parquet/ArrowOutputConverter.hpp"
+#include "ActsPlugins/Arrow/ArrowUtil.hpp"
+#include "ActsPlugins/Arrow/Export.hpp"
+
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <string>
+#include <vector>
+
+namespace ActsExamples {
+
+/// Convert measurements into the per-event RECO table (`tracker_hits`): one
+/// entry per measurement, the entry's position being the measurement id
+/// referenced by track `hit_ids`. Carries the measured local parameters and
+/// variances (always expanded to the full bound layout, with a `subspace`
+/// bitmask saying which components were actually measured: bit0 = loc0,
+/// bit1 = loc1, bit2 = time), the reco global position, cluster-shape
+/// features from the geometric digitization, and truth LINKS only:
+/// `particle_ids` (rows in the particle table) and `simhit_ids` (rows in the
+/// `tracker_simhits` table of the same event, see
+/// `ArrowSimHitOutputConverter`).
+class ACTS_ARROW_EXPORT ArrowMeasurementOutputConverter final
+    : public ArrowOutputConverter {
+ public:
+  struct Config {
+    /// Measurement container (required). One output row per measurement.
+    std::string inputMeasurements;
+    /// Optional cluster container parallel to the measurements (produced by
+    /// the geometric digitization). When unset - e.g. smearing-only
+    /// digitization - the shape columns are emitted as zeros so the schema
+    /// stays stable.
+    std::string inputClusters;
+    /// Optional input @c SimHitContainer; must be set together with
+    /// @c inputSimHitMeasurementsMap. When unset (e.g. data, or a reco-only
+    /// conversion) the @c particle_ids / @c simhit_ids link columns are
+    /// emitted as empty lists.
+    std::string inputSimHits;
+    /// Optional input particle container used to resolve a contributing
+    /// sim-hit's particle barcode to a row index in the corresponding parquet
+    /// table. Must be the same container the @c ArrowParticleOutputConverter
+    /// consumes for that table — leaving it empty forces the unmatched
+    /// sentinel.
+    std::string inputParticles;
+    /// Optional sim-hit → measurement(s) map keyed by @c SimHitIndex; must be
+    /// set together with @c inputSimHits. It is inverted internally to
+    /// measurement → contributing sim-hits.
+    std::string inputSimHitMeasurementsMap;
+    /// Output whiteboard key for the resulting @c arrow::Table.
+    std::string outputTable = "tracker_hits";
+    /// Tracking geometry used to find surfaces by @c GeometryIdentifier when
+    /// projecting each measurement's local parameters back to global
+    /// coordinates (required).
+    std::shared_ptr<const Acts::TrackingGeometry> trackingGeometry;
+    /// Diagnostic only: sim-hits contributing to no measurement are absent
+    /// from this table's links (they remain in the truth table). A warning is
+    /// logged when the fraction exceeds this value.
+    double maxUnmatchedSimHitFraction = 0.001;
+    /// Resolves the @c detector subsystem id for a given geometry id.
+    /// Defaults to reading the geometry id's @c extra byte.
+    std::function<std::uint8_t(Acts::GeometryIdentifier)> detectorResolver =
+        [](Acts::GeometryIdentifier gid) {
+          return static_cast<std::uint8_t>(gid.extra());
+        };
+  };
+
+  explicit ArrowMeasurementOutputConverter(
+      const Config& cfg, std::unique_ptr<const Acts::Logger> logger = nullptr);
+
+  const Config& config() const { return m_cfg; }
+
+  std::vector<std::string> collections() const override;
+
+ private:
+  ProcessCode execute(const AlgorithmContext& ctx) const override;
+
+  Config m_cfg;
+
+  ReadDataHandle<MeasurementContainer> m_inputMeasurements{
+      this, "InputMeasurements"};
+  ReadDataHandle<ClusterContainer> m_inputClusters{this, "InputClusters"};
+  ReadDataHandle<SimHitContainer> m_inputSimHits{this, "InputSimHits"};
+  ReadDataHandle<SimParticleContainer> m_inputParticles{this, "InputParticles"};
+  ReadDataHandle<SimHitMeasurementsMap> m_inputSimHitMeasurementsMap{
+      this, "InputSimHitMeasurementsMap"};
+
+  WriteDataHandle<ActsPlugins::ArrowUtil::ArrowTable> m_outputTable{
+      this, "OutputTable"};
+};
+
+}  // namespace ActsExamples

Examples/Io/Arrow/include/ActsExamples/Io/Arrow/ArrowSimHitOutputConverter.hpp

@@ -9,10 +9,8 @@
 #pragma once
 
 #include "Acts/Geometry/GeometryIdentifier.hpp"
-#include "ActsExamples/EventData/Cluster.hpp"
 #include "ActsExamples/EventData/SimHit.hpp"
 #include "ActsExamples/EventData/SimParticle.hpp"
-#include "ActsExamples/EventData/TruthMatching.hpp"
 #include "ActsExamples/Framework/DataHandle.hpp"
 #include "ActsExamples/Io/Parquet/ArrowOutputConverter.hpp"
 #include "ActsPlugins/Arrow/ArrowUtil.hpp"
@@ -27,42 +25,26 @@
 
 namespace ActsExamples {
 
-/// Convert a @c SimHitContainer to an @c arrow::Table.
-///
-/// The output table has one row per event with list-valued columns. Hits are
-/// emitted in @c SimHitContainer iteration order, so the row index of a hit
-/// inside the per-event list equals its @c SimHitIndex; downstream tables
-/// (e.g. tracks) can therefore reference hits by that index.
-///
-/// When @c inputClusters and @c inputSimHitMeasurementsMap are both provided,
-/// the precomputed digitized cluster position (@c Cluster::globalPosition) of
-/// the matched measurement is written into @c x,y,z. Clusters have a one-to-one
-/// relation with measurements, so the @c SimHitMeasurementsMap (keyed by
-/// @c SimHitIndex, valued by measurement index) doubles as a sim-hit → cluster
-/// map. Otherwise those columns are filled with NaN. The truth position is
-/// always written into @c true_x,true_y,true_z.
+/// Convert simulated tracker hits into the per-event TRUTH table
+/// (`tracker_simhits`): one entry per sim-hit, ALL sim-hits in container
+/// order. The entry's position is the sim-hit id that the measurement table
+/// (`ArrowMeasurementOutputConverter`) references via its `simhit_ids`
+/// column. The table is standalone-complete for re-digitization: position +
+/// time, 4-momentum at the hit, deposited energy, particle link, hit index
+/// along the trajectory, and sensor identification.
 class ACTS_ARROW_EXPORT ArrowSimHitOutputConverter final
     : public ArrowOutputConverter {
  public:
   struct Config {
-    /// Input @c SimHitContainer on the whiteboard.
+    /// Input @c SimHitContainer on the whiteboard (required).
     std::string inputSimHits;
-    /// Optional input particle container used to resolve the hit's particle
+    /// Optional input particle container used to resolve a sim-hit's particle
     /// barcode to a row index in the corresponding parquet table. Must be the
     /// same container the @c ArrowParticleOutputConverter consumes for that
     /// table — leaving it empty forces the unmatched sentinel.
     std::string inputParticles;
-    /// Optional cluster container. Required (together with the map below) to
-    /// fill the digitized @c x,y,z columns from @c Cluster::globalPosition;
-    /// otherwise those are NaN. Clusters are indexed one-to-one with
-    /// measurements.
-    std::string inputClusters;
-    /// Optional sim-hit → measurement(s) inverse map; keyed by @c SimHitIndex.
-    /// Because clusters and measurements share indices, the values double as
-    /// cluster indices.
-    std::string inputSimHitMeasurementsMap;
     /// Output whiteboard key for the resulting @c arrow::Table.
-    std::string outputTable = "simhits";
+    std::string outputTable = "tracker_simhits";
     /// Resolves the @c detector subsystem id for a given hit's geometry id.
     /// Defaults to reading the geometry id's @c extra byte; users can swap
     /// in any custom mapping (e.g. by volume or by surface lookup) when the
@@ -96,9 +78,6 @@ class ACTS_ARROW_EXPORT ArrowSimHitOutputConverter final
 
   ReadDataHandle<SimHitContainer> m_inputSimHits{this, "InputSimHits"};
   ReadDataHandle<SimParticleContainer> m_inputParticles{this, "InputParticles"};
-  ReadDataHandle<ClusterContainer> m_inputClusters{this, "InputClusters"};
-  ReadDataHandle<SimHitMeasurementsMap> m_inputSimHitMeasurementsMap{
-      this, "InputSimHitMeasurementsMap"};
 
   WriteDataHandle<ActsPlugins::ArrowUtil::ArrowTable> m_outputTable{
       this, "OutputTable"};