Reduce template usage in accumulators and add method documentation

include/boost/histogram/accumulators/mean.hpp

@@ -23,16 +23,24 @@ namespace accumulators {
   Uses Welfords's incremental algorithm to improve the numerical
   stability of mean and variance computation.
 */
-template <class RealType>
+template <class ValueType>
 class mean {
 public:
-  using value_type = RealType;
+  using value_type = ValueType;
   using const_reference = const value_type&;
 
   mean() = default;
+
+  /// Allow implicit conversion from mean<T>
+  template <class T>
+  mean(const mean<T>& o) noexcept
+      : sum_{o.sum_}, mean_{o.mean_}, sum_of_deltas_squared_{o.sum_of_deltas_squared_} {}
+
+  /// Initialize to external count, mean, and variance
   mean(const_reference n, const_reference mean, const_reference variance) noexcept
       : sum_(n), mean_(mean), sum_of_deltas_squared_(variance * (n - 1)) {}
 
+  /// Insert sample x
   void operator()(const_reference x) noexcept {
     sum_ += static_cast<value_type>(1);
     const auto delta = x - mean_;
@@ -40,6 +48,7 @@ public:
     sum_of_deltas_squared_ += delta * (x - mean_);
   }
 
+  /// Insert sample x with weight w
   void operator()(const weight_type<value_type>& w, const_reference x) noexcept {
     sum_ += w.value;
     const auto delta = x - mean_;
@@ -47,36 +56,41 @@ public:
     sum_of_deltas_squared_ += w.value * delta * (x - mean_);
   }
 
-  template <class T>
-  mean& operator+=(const mean<T>& rhs) noexcept {
+  /// Add another mean accumulator
+  mean& operator+=(const mean& rhs) noexcept {
     if (sum_ != 0 || rhs.sum_ != 0) {
-      const auto tmp = mean_ * sum_ + static_cast<value_type>(rhs.mean_ * rhs.sum_);
+      const auto tmp = mean_ * sum_ + rhs.mean_ * rhs.sum_;
       sum_ += rhs.sum_;
       mean_ = tmp / sum_;
     }
-    sum_of_deltas_squared_ += static_cast<value_type>(rhs.sum_of_deltas_squared_);
+    sum_of_deltas_squared_ += rhs.sum_of_deltas_squared_;
     return *this;
   }
 
+  /** Scale by value
+
+   This acts as if all samples were scaled by the value.
+  */
   mean& operator*=(const_reference s) noexcept {
     mean_ *= s;
     sum_of_deltas_squared_ *= s * s;
     return *this;
   }
 
-  template <class T>
-  bool operator==(const mean<T>& rhs) const noexcept {
+  bool operator==(const mean& rhs) const noexcept {
     return sum_ == rhs.sum_ && mean_ == rhs.mean_ &&
            sum_of_deltas_squared_ == rhs.sum_of_deltas_squared_;
   }
 
-  template <class T>
-  bool operator!=(const mean<T>& rhs) const noexcept {
-    return !operator==(rhs);
-  }
+  bool operator!=(const mean& rhs) const noexcept { return !operator==(rhs); }
 
+  /// Return how many samples were accumulated
   const_reference count() const noexcept { return sum_; }
+
+  /// Return mean value of accumulated samples
   const_reference value() const noexcept { return mean_; }
+
+  /// Return variance of accumulated samples
   value_type variance() const noexcept { return sum_of_deltas_squared_ / (sum_ - 1); }
 
   template <class Archive>
@@ -111,10 +125,10 @@ namespace serialization {
 template <class T>
 struct version;
 
-// version 1 for boost::histogram::accumulators::mean<RealType>
-template <class RealType>
-struct version<boost::histogram::accumulators::mean<RealType>>
-    : std::integral_constant<int, 1> {};
+// version 1 for boost::histogram::accumulators::mean<T>
+template <class T>
+struct version<boost::histogram::accumulators::mean<T>> : std::integral_constant<int, 1> {
+};
 
 } // namespace serialization
 } // namespace boost

include/boost/histogram/accumulators/sum.hpp

@@ -27,10 +27,10 @@ namespace accumulators {
 
   A. Neumaier, Zeitschrift fuer Angewandte Mathematik und Mechanik 54 (1974) 39-51.
 */
-template <class RealType>
+template <class ValueType>
 class sum {
 public:
-  using value_type = RealType;
+  using value_type = ValueType;
   using const_reference = const value_type&;
 
   sum() = default;
@@ -38,6 +38,7 @@ public:
   /// Initialize sum to value and allow implicit conversion
   sum(const_reference value) noexcept : sum(value, 0) {}
 
+  /// Allow implicit conversion from sum<T>
   template <class T>
   sum(const sum<T>& s) noexcept : sum(s.large(), s.small()) {}
 
@@ -45,13 +46,6 @@ public:
   sum(const_reference large, const_reference small) noexcept
       : large_(large), small_(small) {}
 
-  template <class T>
-  sum& operator=(const sum<T>& s) noexcept {
-    large_ = s.large_;
-    small_ = s.small_;
-    return *this;
-  }
-
   /// Increment sum by one
   sum& operator++() noexcept { return operator+=(1); }
 
@@ -59,8 +53,8 @@ public:
   sum& operator+=(const_reference value) noexcept {
     // prevent compiler optimization from destroying the algorithm
     // when -ffast-math is enabled
-    volatile RealType l;
-    RealType s;
+    volatile value_type l;
+    value_type s;
     if (std::abs(large_) >= std::abs(value)) {
       l = large_;
       s = value;

include/boost/histogram/accumulators/weighted_mean.hpp

@@ -23,13 +23,23 @@ namespace accumulators {
   Uses West's incremental algorithm to improve numerical stability
   of mean and variance computation.
 */
-template <class RealType>
+template <class ValueType>
 class weighted_mean {
 public:
-  using value_type = RealType;
+  using value_type = ValueType;
   using const_reference = const value_type&;
 
   weighted_mean() = default;
+
+  /// Allow implicit conversion from other weighted_means
+  template <class T>
+  weighted_mean(const weighted_mean<T>& o)
+      : sum_of_weights_{o.sum_of_weights_}
+      , sum_of_weights_squared_{o.sum_of_weights_squared_}
+      , weighted_mean_{o.weighted_mean_}
+      , sum_of_weighted_deltas_squared_{o.sum_of_weighted_deltas_squared_} {}
+
+  /// Initialize to external sum of weights, sum of weights squared, mean, and variance
   weighted_mean(const_reference wsum, const_reference wsum2, const_reference mean,
                 const_reference variance)
       : sum_of_weights_(wsum)
@@ -38,8 +48,10 @@ public:
       , sum_of_weighted_deltas_squared_(
             variance * (sum_of_weights_ - sum_of_weights_squared_ / sum_of_weights_)) {}
 
+  /// Insert sample x
   void operator()(const_reference x) { operator()(weight(1), x); }
 
+  /// Insert sample x with weight w
   void operator()(const weight_type<value_type>& w, const_reference x) {
     sum_of_weights_ += w.value;
     sum_of_weights_squared_ += w.value * w.value;
@@ -48,44 +60,50 @@ public:
     sum_of_weighted_deltas_squared_ += w.value * delta * (x - weighted_mean_);
   }
 
-  template <class T>
-  weighted_mean& operator+=(const weighted_mean<T>& rhs) {
+  /// Add another weighted_mean
+  weighted_mean& operator+=(const weighted_mean& rhs) {
     if (sum_of_weights_ != 0 || rhs.sum_of_weights_ != 0) {
-      const auto tmp = weighted_mean_ * sum_of_weights_ +
-                       static_cast<value_type>(rhs.weighted_mean_ * rhs.sum_of_weights_);
-      sum_of_weights_ += static_cast<value_type>(rhs.sum_of_weights_);
-      sum_of_weights_squared_ += static_cast<value_type>(rhs.sum_of_weights_squared_);
+      const auto tmp =
+          weighted_mean_ * sum_of_weights_ + rhs.weighted_mean_ * rhs.sum_of_weights_;
+      sum_of_weights_ += rhs.sum_of_weights_;
+      sum_of_weights_squared_ += rhs.sum_of_weights_squared_;
       weighted_mean_ = tmp / sum_of_weights_;
     }
-    sum_of_weighted_deltas_squared_ +=
-        static_cast<RealType>(rhs.sum_of_weighted_deltas_squared_);
+    sum_of_weighted_deltas_squared_ += rhs.sum_of_weighted_deltas_squared_;
     return *this;
   }
 
+  /** Scale by value
+
+   This acts as if all samples were scaled by the value.
+  */
   weighted_mean& operator*=(const_reference s) {
     weighted_mean_ *= s;
     sum_of_weighted_deltas_squared_ *= s * s;
     return *this;
   }
 
-  template <class T>
-  bool operator==(const weighted_mean<T>& rhs) const noexcept {
+  bool operator==(const weighted_mean& rhs) const noexcept {
     return sum_of_weights_ == rhs.sum_of_weights_ &&
            sum_of_weights_squared_ == rhs.sum_of_weights_squared_ &&
            weighted_mean_ == rhs.weighted_mean_ &&
            sum_of_weighted_deltas_squared_ == rhs.sum_of_weighted_deltas_squared_;
   }
 
-  template <class T>
-  bool operator!=(const T& rhs) const noexcept {
-    return !operator==(rhs);
-  }
+  bool operator!=(const weighted_mean& rhs) const noexcept { return !operator==(rhs); }
 
+  /// Return sum of weights
   const_reference sum_of_weights() const noexcept { return sum_of_weights_; }
+
+  /// Return sum of weights squared (variance of weight distribution)
   const_reference sum_of_weights_squared() const noexcept {
     return sum_of_weights_squared_;
   }
+
+  /// Return mean of accumulated weighted samples
   const_reference value() const noexcept { return weighted_mean_; }
+
+  /// Return variance of accumulated weighted samples
   value_type variance() const {
     return sum_of_weighted_deltas_squared_ /
            (sum_of_weights_ - sum_of_weights_squared_ / sum_of_weights_);

include/boost/histogram/accumulators/weighted_sum.hpp

@@ -16,10 +16,10 @@ namespace histogram {
 namespace accumulators {
 
 /// Holds sum of weights and its variance estimate
-template <class RealType>
+template <class ValueType>
 class weighted_sum {
 public:
-  using value_type = RealType;
+  using value_type = ValueType;
   using const_reference = const value_type&;
 
   weighted_sum() = default;
@@ -27,6 +27,7 @@ public:
   /// Initialize sum to value and allow implicit conversion
   weighted_sum(const_reference value) noexcept : weighted_sum(value, value) {}
 
+  /// Allow implicit conversion from sum<T>
   template <class T>
   weighted_sum(const weighted_sum<T>& s) noexcept
       : weighted_sum(s.value(), s.variance()) {}
@@ -35,13 +36,6 @@ public:
   weighted_sum(const_reference value, const_reference variance) noexcept
       : sum_of_weights_(value), sum_of_weights_squared_(variance) {}
 
-  template <class T>
-  weighted_sum& operator=(const weighted_sum<T>& s) noexcept {
-    sum_of_weights_ = s.sum_of_weights_;
-    sum_of_weights_squared_ = s.sum_of_weights_squared_;
-    return *this;
-  }
-
   /// Increment by one.
   weighted_sum& operator++() {
     ++sum_of_weights_;

include/boost/histogram/fwd.hpp

@@ -39,6 +39,7 @@ struct null_type {
 /// Another alias for an empty metadata type
 using empty_type = null_type;
 
+// some forward declarations must be hidden from doxygen to fix the reference docu :(
 #ifndef BOOST_HISTOGRAM_DOXYGEN_INVOKED
 
 namespace transform {
@@ -79,13 +80,16 @@ template <class T>
 struct sample_type;
 
 namespace accumulators {
-template <class Value = double>
+template <class ValueType = double>
 class sum;
-template <class Value = double>
+
+template <class ValueType = double>
 class weighted_sum;
-template <class Value = double>
+
+template <class ValueType = double>
 class mean;
-template <class Value = double>
+
+template <class ValueType = double>
 class weighted_mean;
 
 template <class T>
@@ -123,6 +127,7 @@ using profile_storage = dense_storage<accumulators::mean<>>;
 /// Dense storage which tracks means of weighted samples in each cell.
 using weighted_profile_storage = dense_storage<accumulators::weighted_mean<>>;
 
+// some forward declarations must be hidden from doxygen to fix the reference docu :(
 #ifndef BOOST_HISTOGRAM_DOXYGEN_INVOKED
 
 template <class Axes, class Storage = default_storage>