Merge pull request #48857 from Electricks94/MultiVectorManager

Move MultiVectorManager to DataFormats/Common and address discussion from #48826 and rename it to MultiSpan

Author: cmsbuild

DataFormats/Common/interface/MultiSpan.h

@@ -0,0 +1,158 @@
+// Author: Felice Pantaleo (CERN), 2023, [email protected]
+#ifndef DataFormats_Common_MultiSpan_h
+#define DataFormats_Common_MultiSpan_h
+
+#include <algorithm>
+#include <cassert>
+#include <span>
+#include <stdexcept>
+#include <vector>
+
+namespace edm {
+
+  /**
+* @brief A view-like container that provides a contiguous indexing interface over multiple disjoint spans.
+*
+* MultiSpan allows to append multiple `std::vector<T>` as std::span<const T> instances and access them through a
+* single global index as if they formed one continuous sequence. 
+*
+* This class is read-only and does not take ownership of the underlying data.
+* It is intended for iteration over heterogeneous but logically connected data ranges without copying 
+* or merging them into a single container.
+*
+* To find a span that corresponds to a global index, a binary search is used, making the access time logarithmic in the number of spans.
+* This means when iterating over the elements the binary search over spans is repeated for every element.
+*
+*/
+  template <typename T>
+  class MultiSpan {
+  public:
+    MultiSpan() = default;
+
+    void add(std::span<const T> sp) {
+      // Empty spans are not added to reduce the number of spans and speed up the binary search
+      if (sp.empty()) {
+        return;
+      }
+
+      spans_.emplace_back(sp);
+      offsets_.push_back(totalSize_);
+      totalSize_ += sp.size();
+    }
+
+    const T& operator[](const std::size_t globalIndex) const {
+#ifndef NDEBUG
+      if (globalIndex >= totalSize_) {
+        throw std::out_of_range("Global index out of range");
+      }
+#endif
+      const auto [spanIndex, indexWithinSpan] = spanAndLocalIndex(globalIndex);
+      return spans_[spanIndex][indexWithinSpan];
+    }
+
+    std::size_t globalIndex(const std::size_t spanIndex, const std::size_t indexWithinSpan) const {
+#ifndef NDEBUG
+      if (spanIndex >= spans_.size()) {
+        throw std::out_of_range("spanIndex index out of range");
+      }
+      if (indexWithinSpan >= spans_[spanIndex].size()) {
+        throw std::out_of_range("indexWithinSpan index out of range");
+      }
+#endif
+
+      return offsets_[spanIndex] + indexWithinSpan;
+    }
+
+    std::pair<std::size_t, std::size_t> spanAndLocalIndex(const std::size_t globalIndex) const {
+#ifndef NDEBUG
+      if (globalIndex >= totalSize_) {
+        throw std::out_of_range("Global index out of range");
+      }
+#endif
+      auto it = std::upper_bound(offsets_.begin(), offsets_.end(), globalIndex);
+      std::size_t spanIndex = std::distance(offsets_.begin(), it) - 1;
+      std::size_t indexWithinSpan = globalIndex - offsets_[spanIndex];
+
+      return {spanIndex, indexWithinSpan};
+    }
+
+    std::size_t size() const { return totalSize_; }
+
+    class ConstRandomAccessIterator {
+    public:
+      using iterator_category = std::random_access_iterator_tag;
+      using difference_type = std::ptrdiff_t;
+      using value_type = T;
+      using pointer = const T*;
+      using reference = const T&;
+
+      ConstRandomAccessIterator(const MultiSpan& ms, const std::size_t index) : ms_(&ms), currentIndex_(index) {}
+
+      reference operator*() const { return (*ms_)[currentIndex_]; }
+      pointer operator->() const { return &(*ms_)[currentIndex_]; }
+
+      reference operator[](difference_type n) const { return (*ms_)[currentIndex_ + n]; }
+
+      ConstRandomAccessIterator& operator++() {
+        ++currentIndex_;
+        return *this;
+      }
+      ConstRandomAccessIterator operator++(int) {
+        auto tmp = *this;
+        ++(*this);
+        return tmp;
+      }
+      ConstRandomAccessIterator& operator--() {
+        --currentIndex_;
+        return *this;
+      }
+      ConstRandomAccessIterator operator--(int) {
+        auto tmp = *this;
+        --(*this);
+        return tmp;
+      }
+
+      ConstRandomAccessIterator& operator+=(difference_type n) {
+        currentIndex_ += n;
+        return *this;
+      }
+      ConstRandomAccessIterator& operator-=(difference_type n) {
+        currentIndex_ -= n;
+        return *this;
+      }
+
+      ConstRandomAccessIterator operator+(difference_type n) const {
+        return ConstRandomAccessIterator(*ms_, currentIndex_ + n);
+      }
+
+      ConstRandomAccessIterator operator-(difference_type n) const {
+        return ConstRandomAccessIterator(*ms_, currentIndex_ - n);
+      }
+
+      difference_type operator-(const ConstRandomAccessIterator& other) const {
+        return currentIndex_ - other.currentIndex_;
+      }
+
+      bool operator==(const ConstRandomAccessIterator& other) const { return currentIndex_ == other.currentIndex_; }
+      bool operator!=(const ConstRandomAccessIterator& other) const { return currentIndex_ != other.currentIndex_; }
+      auto operator<=>(const ConstRandomAccessIterator& other) const { return currentIndex_ <=> other.currentIndex_; }
+
+    private:
+      const MultiSpan* ms_;
+      std::size_t currentIndex_;
+    };
+
+    using const_iterator = ConstRandomAccessIterator;
+
+    const_iterator begin() const { return const_iterator(*this, 0); }
+    const_iterator end() const { return const_iterator(*this, totalSize_); }
+
+  private:
+    std::vector<std::span<const T>> spans_;
+    std::vector<std::size_t> offsets_;
+    std::size_t totalSize_{0};
+  };
+
+}  // namespace edm
+
+#endif  // DataFormats_Common_MultiSpan_h

DataFormats/Common/test/test_catch2_MultiSpan.cpp

@@ -0,0 +1,178 @@
+#include <algorithm>
+#include <cassert>
+#include <cmath>
+#include <numeric>
+#include <vector>
+#include <catch.hpp>
+
+#include "DataFormats/Common/interface/MultiSpan.h"
+
+TEST_CASE("MultiSpan basic indexing", "[MultiSpan]") {
+  edm::MultiSpan<int> emptyMultiSpan;
+  edm::MultiSpan<int> ms;
+
+  edm::MultiSpan<int> ms1;  // MultiSpan with empty span as first span
+  edm::MultiSpan<int> ms2;  // MultiSpan with several empty spans
+  edm::MultiSpan<int> ms3;  // MultiSpan with empty span as last span
+
+  std::vector<int> a = {1, 2, 3};
+  std::vector<int> b = {4, 5};
+  std::vector<int> c;
+
+  ms.add(a);
+  ms.add(b);
+
+  ms1.add(c);
+  ms1.add(b);
+  ms1.add(a);
+
+  ms2.add(b);
+  ms2.add(c);
+  ms2.add(c);
+  ms2.add(c);
+  ms2.add(b);
+  ms2.add(a);
+  ms2.add(c);
+
+  ms3.add(a);
+  ms3.add(c);
+
+  using ElementType = decltype(ms[0]);
+  // Check that the const-correctness of the MultiSpan
+  static_assert(!std::is_assignable<ElementType, int>::value,
+                "It should not be possible to assign to an element of MultiSpan; See PR #48826");
+
+  SECTION("Empty MultiSpan") {
+    REQUIRE(emptyMultiSpan.size() == 0);
+    REQUIRE(emptyMultiSpan.begin() == emptyMultiSpan.end());
+    REQUIRE_THROWS_AS(emptyMultiSpan[0], std::out_of_range);
+    REQUIRE_THROWS_AS(emptyMultiSpan.globalIndex(0, 0), std::out_of_range);
+  }
+
+  SECTION("Size is correct") { REQUIRE(ms.size() == 5); }
+
+  SECTION("Range check") {
+    REQUIRE_THROWS_AS(ms[5], std::out_of_range);
+    REQUIRE_THROWS_AS(ms.globalIndex(2, 0), std::out_of_range);
+    REQUIRE_THROWS_AS(ms.globalIndex(1, 2), std::out_of_range);
+    REQUIRE_THROWS_AS(ms.spanAndLocalIndex(5), std::out_of_range);
+  }
+
+  SECTION("Indexing returns correct values") {
+    REQUIRE(ms[0] == 1);
+    REQUIRE(ms[1] == 2);
+    REQUIRE(ms[2] == 3);
+    REQUIRE(ms[3] == 4);
+    REQUIRE(ms[4] == 5);
+  }
+
+  SECTION("Global index from span index and local index") {
+    REQUIRE(ms.globalIndex(0, 0) == 0);
+    REQUIRE(ms.globalIndex(0, 2) == 2);
+    REQUIRE(ms.globalIndex(1, 0) == 3);
+    REQUIRE(ms.globalIndex(1, 1) == 4);
+  }
+
+  SECTION("Span and local index from global index") {
+    auto [span0, local0] = ms.spanAndLocalIndex(0);
+    REQUIRE(span0 == 0);
+    REQUIRE(local0 == 0);
+
+    auto [span1, local1] = ms.spanAndLocalIndex(4);
+    REQUIRE(span1 == 1);
+    REQUIRE(local1 == 1);
+  }
+
+  SECTION("Iterators work with range-based for") {
+    std::vector<int> collected;
+    for (auto val : ms) {
+      collected.push_back(val);
+    }
+    REQUIRE(collected == std::vector<int>{1, 2, 3, 4, 5});
+  }
+
+  SECTION("Random access iterator supports arithmetic") {
+    auto it = ms.begin();
+    REQUIRE(*(it + 2) == 3);
+    REQUIRE(*(ms.end() - 2) == 4);
+    REQUIRE((ms.end() - ms.begin()) == 5);
+  }
+
+  SECTION("std::find works") {
+    auto it = std::find(ms.begin(), ms.end(), 4);
+    REQUIRE(it != ms.end());
+    REQUIRE(*it == 4);
+    REQUIRE((it - ms.begin()) == 3);
+  }
+
+  SECTION("std::distance returns correct result") {
+    auto dist = std::distance(ms.begin(), ms.end());
+    REQUIRE(dist == 5);
+  }
+
+  SECTION("std::copy copies all values") {
+    std::vector<int> out(5);
+    std::copy(ms.begin(), ms.end(), out.begin());
+
+    REQUIRE(ms[0] == out[0]);
+    REQUIRE(ms[1] == out[1]);
+    REQUIRE(ms[2] == out[2]);
+    REQUIRE(ms[3] == out[3]);
+    REQUIRE(ms[4] == out[4]);
+  }
+
+  SECTION("Check MultiSpan with empty span as first span") {
+    REQUIRE(ms1.size() == 5);
+
+    REQUIRE(ms1[0] == b[0]);
+    REQUIRE(ms1[1] == b[1]);
+    REQUIRE(ms1[2] == a[0]);
+    REQUIRE(ms1[3] == a[1]);
+    REQUIRE(ms1[4] == a[2]);
+
+    REQUIRE(ms1.globalIndex(0, 0) == 0);
+    REQUIRE(ms1.globalIndex(1, 1) == 3);
+
+    std::vector<int> collected;
+    for (auto val : ms1) {
+      collected.push_back(val);
+    }
+    REQUIRE(collected == std::vector<int>{b[0], b[1], a[0], a[1], a[2]});
+  }
+
+  SECTION("Check MultiSpan with serveral empty spans") {
+    REQUIRE(ms2.size() == 7);
+
+    REQUIRE(ms2[0] == b[0]);
+    REQUIRE(ms2[1] == b[1]);
+    REQUIRE(ms2[2] == b[0]);
+    REQUIRE(ms2[3] == b[1]);
+    REQUIRE(ms2[4] == a[0]);
+    REQUIRE(ms2[5] == a[1]);
+    REQUIRE(ms2[6] == a[2]);
+
+    REQUIRE(ms2.globalIndex(0, 0) == 0);
+    REQUIRE(ms2.globalIndex(1, 1) == 3);
+    REQUIRE(ms2.globalIndex(2, 1) == 5);
+
+    std::vector<int> collected;
+    for (auto val : ms2) {
+      collected.push_back(val);
+    }
+    REQUIRE(collected == std::vector<int>{b[0], b[1], b[0], b[1], a[0], a[1], a[2]});
+  }
+
+  SECTION("Check MultiSpan with serveral empty spans") {
+    REQUIRE(ms3.size() == 3);
+
+    REQUIRE(ms3[0] == a[0]);
+    REQUIRE(ms3[1] == a[1]);
+    REQUIRE(ms3[2] == a[2]);
+
+    std::vector<int> collected;
+    for (auto val : ms3) {
+      collected.push_back(val);
+    }
+    REQUIRE(collected == std::vector<int>{a[0], a[1], a[2]});
+  }
+}