[hist] Implement initial RRegularAxis

The first version of this class exposes only ComputeLinearizedIndex
with a simple index computation formula. It does not (yet) implement
the recent changes to improve its precision available in TAxis.

This commit also includes basic build system additions and setup for
unit testing.

Author: hahnjo

hist/histv7/CMakeLists.txt

@@ -0,0 +1,10 @@
+ROOT_STANDARD_LIBRARY_PACKAGE(ROOTHist
+  HEADERS
+    ROOT/RLinearizedIndex.hxx
+    ROOT/RRegularAxis.hxx
+  NO_SOURCES
+  DEPENDENCIES
+    Core
+)
+
+ROOT_ADD_TEST_SUBDIRECTORY(test)

hist/histv7/inc/LinkDef.h

@@ -0,0 +1,22 @@
+#ifndef ROOT_RLinearizedIndex
+#define ROOT_RLinearizedIndex
+
+#include <cstddef>
+
+namespace ROOT {
+namespace Experimental {
+
+/**
+A linearized index that can be invalid.
+
+For example, when an argument is outside the axis and underflow / overflow bins are disabled.
+*/
+struct RLinearizedIndex final {
+   std::size_t index;
+   bool valid;
+};
+
+} // namespace Experimental
+} // namespace ROOT
+
+#endif

hist/histv7/inc/ROOT/RLinearizedIndex.hxx

@@ -0,0 +1,87 @@
+#ifndef ROOT_RRegularAxis
+#define ROOT_RRegularAxis
+
+#include "RLinearizedIndex.hxx"
+
+#include <cstddef>
+
+namespace ROOT {
+namespace Experimental {
+
+/**
+A regular axis with equidistant bins in the interval \f$[fLow, fHigh)\f$.
+
+For example, the following creates a regular axis with 10 normal bins between 5 and 15:
+~~~ {.cxx}
+ROOT::Experimental::RRegularAxis axis(10, 5, 15);
+~~~
+
+It is possible to disable underflow and overflow bins by passing `enableFlowBins = false`. In that case, arguments
+outside the axis will be silently discarded.
+*/
+class RRegularAxis final {
+   /// The number of normal bins
+   std::size_t fNumNormalBins;
+   /// The lower end of the axis interval
+   double fLow;
+   /// The upper end of the axis interval
+   double fHigh;
+   /// The cached inverse of the bin width to speed up ComputeLinearizedIndex
+   double fInvBinWidth; //!
+   /// Whether underflow and overflow bins are enabled
+   bool fEnableFlowBins;
+
+public:
+   /// Construct a regular axis object.
+   ///
+   /// \param[in] numNormalBins the number of normal bins
+   /// \param[in] low the lower end of the axis interval (inclusive)
+   /// \param[in] high the upper end of the axis interval (exclusive)
+   /// \param[in] enableFlowBins whether to enable underflow and overflow bins
+   RRegularAxis(std::size_t numNormalBins, double low, double high, bool enableFlowBins = true)
+      : fNumNormalBins(numNormalBins), fLow(low), fHigh(high), fEnableFlowBins(enableFlowBins)
+   {
+      // FIXME: should validate numNormalBins > 0 and low < high
+      fInvBinWidth = numNormalBins / (high - low);
+   }
+
+   std::size_t GetNumNormalBins() const { return fNumNormalBins; }
+   std::size_t GetTotalNumBins() const { return fEnableFlowBins ? fNumNormalBins + 2 : fNumNormalBins; }
+   double GetLow() const { return fLow; }
+   double GetHigh() const { return fHigh; }
+   bool AreFlowBinsEnabled() const { return fEnableFlowBins; }
+
+   friend bool operator==(const RRegularAxis &lhs, const RRegularAxis &rhs)
+   {
+      return lhs.fNumNormalBins == rhs.fNumNormalBins && lhs.fLow == rhs.fLow && lhs.fHigh == rhs.fHigh &&
+             lhs.fEnableFlowBins == rhs.fEnableFlowBins;
+   }
+
+   /// Compute the linarized index for a single argument.
+   ///
+   /// The normal bins have indices \f$0\f$ to \f$fNumNormalBins - 1\f$, the underflow bin has index
+   /// \f$fNumNormalBins\f$, and the overflow bin has index \f$fNumNormalBins + 1\f$. If the argument is outside the
+   /// interval \f$[fLow, fHigh)\f$ and the flow bins are disabled, the return value is invalid.
+   ///
+   /// \param[in] x the argument
+   /// \return the linearized index that may be invalid
+   RLinearizedIndex ComputeLinearizedIndex(double x) const
+   {
+      bool underflow = x < fLow;
+      // Put NaNs into overflow bin.
+      bool overflow = !(x < fHigh);
+      if (underflow) {
+         return {fNumNormalBins, fEnableFlowBins};
+      } else if (overflow) {
+         return {fNumNormalBins + 1, fEnableFlowBins};
+      }
+
+      std::size_t bin = (x - fLow) * fInvBinWidth;
+      return {bin, true};
+   }
+};
+
+} // namespace Experimental
+} // namespace ROOT
+
+#endif

hist/histv7/inc/ROOT/RRegularAxis.hxx

@@ -0,0 +1 @@
+ROOT_ADD_GTEST(hist_regular hist_regular.cxx LIBRARIES ROOTHist)

hist/histv7/test/CMakeLists.txt

@@ -0,0 +1,89 @@
+#include "hist_test.hxx"
+
+#include <limits>
+
+TEST(RRegularAxis, Constructor)
+{
+   static constexpr std::size_t Bins = 20;
+   RRegularAxis axis(Bins, 0, Bins);
+   EXPECT_EQ(axis.GetNumNormalBins(), Bins);
+   EXPECT_EQ(axis.GetTotalNumBins(), Bins + 2);
+   EXPECT_EQ(axis.GetLow(), 0);
+   EXPECT_EQ(axis.GetHigh(), Bins);
+   EXPECT_TRUE(axis.AreFlowBinsEnabled());
+
+   axis = RRegularAxis(Bins, 0, Bins, /*enableFlowBins=*/false);
+   EXPECT_EQ(axis.GetNumNormalBins(), Bins);
+   EXPECT_EQ(axis.GetTotalNumBins(), Bins);
+   EXPECT_FALSE(axis.AreFlowBinsEnabled());
+}
+
+TEST(RRegularAxis, Equality)
+{
+   static constexpr std::size_t Bins = 20;
+   const RRegularAxis axisA(Bins, 0, Bins);
+   const RRegularAxis axisANoFlowBins(Bins, 0, Bins, /*enableFlowBins=*/false);
+   const RRegularAxis axisA2(Bins, 0, Bins);
+   const RRegularAxis axisB(Bins / 2, 0, Bins);
+   const RRegularAxis axisC(Bins, 0, Bins / 2);
+   const RRegularAxis axisD(Bins, Bins / 2, Bins);
+
+   EXPECT_TRUE(axisA == axisA);
+   EXPECT_TRUE(axisA == axisA2);
+   EXPECT_TRUE(axisA2 == axisA);
+
+   EXPECT_FALSE(axisA == axisANoFlowBins);
+
+   EXPECT_FALSE(axisA == axisB);
+   EXPECT_FALSE(axisA == axisC);
+   EXPECT_FALSE(axisA == axisD);
+
+   EXPECT_FALSE(axisB == axisC);
+   EXPECT_FALSE(axisB == axisD);
+
+   EXPECT_FALSE(axisC == axisD);
+   EXPECT_FALSE(axisD == axisC);
+}
+
+TEST(RRegularAxis, ComputeLinearizedIndex)
+{
+   static constexpr std::size_t Bins = 20;
+   const RRegularAxis axis(Bins, 0, Bins);
+   const RRegularAxis axisNoFlowBins(Bins, 0, Bins, /*enableFlowBins=*/false);
+
+   // Underflow
+   static constexpr double NegativeInfinity = -std::numeric_limits<double>::infinity();
+   static constexpr double UnderflowLarge = -static_cast<double>(Bins);
+   static constexpr double UnderflowSmall = -0.1;
+   for (double underflow : {NegativeInfinity, UnderflowLarge, UnderflowSmall}) {
+      auto linIndex = axis.ComputeLinearizedIndex(underflow);
+      EXPECT_EQ(linIndex.index, Bins);
+      EXPECT_TRUE(linIndex.valid);
+      linIndex = axisNoFlowBins.ComputeLinearizedIndex(underflow);
+      EXPECT_EQ(linIndex.index, Bins);
+      EXPECT_FALSE(linIndex.valid);
+   }
+
+   for (std::size_t i = 0; i < Bins; i++) {
+      auto linIndex = axis.ComputeLinearizedIndex(i + 0.5);
+      EXPECT_EQ(linIndex.index, i);
+      EXPECT_TRUE(linIndex.valid);
+      linIndex = axisNoFlowBins.ComputeLinearizedIndex(i + 0.5);
+      EXPECT_EQ(linIndex.index, i);
+      EXPECT_TRUE(linIndex.valid);
+   }
+
+   // Overflow
+   static constexpr double PositiveInfinity = std::numeric_limits<double>::infinity();
+   static constexpr double NaN = std::numeric_limits<double>::quiet_NaN();
+   static constexpr double OverflowLarge = static_cast<double>(Bins * 2);
+   static constexpr double OverflowSmall = Bins + 0.1;
+   for (double overflow : {PositiveInfinity, NaN, OverflowLarge, OverflowSmall}) {
+      auto linIndex = axis.ComputeLinearizedIndex(overflow);
+      EXPECT_EQ(linIndex.index, Bins + 1);
+      EXPECT_TRUE(linIndex.valid);
+      linIndex = axisNoFlowBins.ComputeLinearizedIndex(overflow);
+      EXPECT_EQ(linIndex.index, Bins + 1);
+      EXPECT_FALSE(linIndex.valid);
+   }
+}

hist/histv7/test/hist_regular.cxx

@@ -0,0 +1,10 @@
+#ifndef hist_test
+#define hist_test
+
+#include <ROOT/RRegularAxis.hxx>
+
+#include "gtest/gtest.h"
+
+using ROOT::Experimental::RRegularAxis;
+
+#endif