[RVecOp] Adding linSpace, logSpace, and arange prototypes

Fixes #17855

Author: edfink234

math/vecops/inc/ROOT/RVec.hxx

@@ -3242,6 +3242,242 @@ RVec<typename RVec<T>::size_type> Enumerate(const RVec<T> &v)
    return ret;
 }
 
+/**
+ * \brief Produce RVec with N evenly-spaced entries from start to end.
+ *
+ * This function generates a vector of evenly spaced values, starting at \p start and (depending on the
+ * \p endpoint parameter) either including or excluding \p end. If \p endpoint is true (default),
+ * the vector contains \p n values with \p end as the final element, and the spacing is computed as
+ * \f$\text{step} = \frac{\text{end} - \text{start}}{n-1}\f$. If \p endpoint is false,
+ * the sequence consists of n values computed as if there were n+1 evenly spaced samples, with the final
+ * value (\p end) omitted; in this case, \f$\text{step} = \frac{\text{end} - \text{start}}{n}\f$.
+ *
+ * The function is templated to allow for different arithmetic types. The deduced type \c Common_t is
+ * determined as follows: if the common type of \p T1 and \p T2 is a floating point type, that type is used;
+ * otherwise, the arithmetic is performed using \c double.
+ *
+ * \tparam T1 Type of the start value. Default is double.
+ * \tparam T2 Type of the end value. Default is double.
+ * \tparam Common_t Deduced type used for arithmetic, which is std::common_type_t<T1, T2> if that is a
+ * floating point type, or double otherwise.
+ *
+ * \param start The first value in the sequence.
+ * \param end The last value in the sequence if \p endpoint is true; otherwise, \p end is excluded.
+ * \param n The number of evenly spaced entries to produce.
+ * \param endpoint If true (default), \p end is included as the final element; if false, \p end is excluded.
+ *
+ * \return A vector (RVec<Common_t>) containing \p n evenly spaced values.
+ *
+ * \note If \p n is 1, the resulting vector will contain only the value \p start.
+ * \note The check `if (!n || (n > std::numeric_limits<long long>::max()))` is used to ensure that:
+ *   - n is nonzero, and
+ *   - n does not exceed std::numeric_limits<long long>::max(), which would indicate that a negative range (or other arithmetic issue)
+ *     has resulted in an extremely large unsigned value, thereby preventing an attempt to reserve an absurd
+ *     amount of memory.
+ * \note If the template parameter \c Common_t is explicitly overridden with an integral type, the arithmetic may cause rounding issues. Consequently, the resulting sequence may not end exactly at \p end. To ensure that the sequence ends exactly at \p end, consider casting the result as follows: `RVec<integral_type>(Linspace(...))`. This behavior is different than NumPy in Python.
+ *
+ * \par C++23 Enumerate Support:
+ * With C++23, you can use the range-based enumerate view to iterate over the resulting vector with both the index
+ * and the value, similar to Python's `enumerate`. For example:
+ * ~~~{.cpp}
+ * for (auto const [index, val] : std::views::enumerate(ROOT::VecOps::Linspace(6, 10, 16))) {
+ *     // Process index and val.
+ * }
+ * ~~~
+ *
+ * \par Example code, at the ROOT prompt:
+ * ~~~{.cpp}
+ * using namespace ROOT::VecOps;
+ * cout << Linspace(-1, 5, 5) << "\n";
+ * // { -1, 0.5, 2, 3.5, 5 }
+ * cout << Linspace(3, 12, 5) << "\n";
+ * // { 3, 5.25, 7.5, 9.75, 12 }
+ * cout << Linspace(3, 12, 5, false) << "\n";
+ * // { 3, 4.8, 6.6, 8.4, 10.2 }
+ * Linspace<int, int, int>(1, 10, 3) << "\n";
+ * // { 1, 5, 9 }
+ * ~~~
+ */
+template <typename T1 = double, typename T2 = double, typename Common_t = std::conditional_t<std::is_floating_point_v<std::common_type_t<T1, T2>>, std::common_type_t<T1, T2>, double>>
+inline RVec<Common_t> Linspace(T1 start, T2 end, unsigned long long n = 128, const bool endpoint = true)
+{
+    RVec<Common_t> temp;
+    
+    if (!n || (n > std::numeric_limits<long long>::max())) // Check for invalid or absurd n.
+    {
+        return temp;
+    }
+    
+    Common_t step = (static_cast<Common_t>(end) - static_cast<Common_t>(start)) / static_cast<Common_t>(n - endpoint);
+    temp.reserve(n);
+    temp.push_back(static_cast<Common_t>(start));
+    for (unsigned long long i = 1; i < n; i++)
+    {
+        temp.push_back(static_cast<Common_t>(start) + static_cast<Common_t>(i) * step);
+    }
+    return temp;
+}
+
+/**
+ * \brief Produce RVec with n log-spaced entries from base^{start} to base^{end}.
+ *
+ * This function generates a vector of values where the exponents are evenly spaced, and then returns the
+ * corresponding values of base raised to these exponents. If \p endpoint is true (default), the vector
+ * contains \p n values with the last element equal to \f$base^{end}\f$. If \p endpoint is false, the
+ * sequence is computed as if there were n+1 evenly spaced samples over the interval in the exponent space,
+ * and the final value (\f$base^{end}\f$) is excluded, resulting in a sequence of n values.
+ *
+ * The function is templated to allow for different arithmetic types. The deduced type \c Common_t is determined as follows:
+ * if the common type of \p T1, \p T2, and \p T3 is a floating point type, that type is used; otherwise, the arithmetic is performed using \c double.
+ *
+ * \tparam T1 Type of the start exponent. Default is double.
+ * \tparam T2 Type of the end exponent. Default is double.
+ * \tparam T3 Type of the base (and auxiliary type for deducing common type). Default is double.
+ * \tparam Common_t Deduced type used for arithmetic, which is std::common_type_t<T1, T2, T3> if that is a floating point type, or double otherwise.
+ *
+ * \param start The exponent corresponding to the first element (i.e., the first element is \f$base^{start}\f$).
+ * \param end The exponent corresponding to the final element if \p endpoint is true; otherwise, \p end is excluded.
+ * \param n The number of log-spaced entries to produce.
+ * \param base The base to be used in the exponentiation (default is 10.0).
+ * \param endpoint If true (default), \f$base^{end}\f$ is included as the final element; if false, \f$base^{end}\f$ is excluded.
+ *
+ * \return A vector (RVec<Common_t>) containing n log-spaced values.
+ *
+ * \note If \p n is 1, the resulting vector will contain only the value \f$base^{start}\f$.
+ * \note The check `if (!n || (n > std::numeric_limits<long long>::max()))` is used to ensure that:
+ *   - n is nonzero, and
+ *   - n does not exceed std::numeric_limits<long long>::max(), which would indicate that a negative range (or other arithmetic issue)
+ *     has resulted in an extremely large unsigned value, thereby preventing an attempt to reserve an absurd
+ *     amount of memory.
+ * \note If the template parameter \c Common_t is explicitly overridden with an integral type, the arithmetic may introduce rounding errors, and as a consequence, the sequence may not end exactly at \f$base^{end}\f>. To ensure that the final element is exactly \f$base^{end}\f>, consider casting the result as follows: `RVec<integral_type>(Logspace(...))`. This behavior is different than NumPy in Python.
+ *
+ * \par C++23 Enumerate Support:
+ * With C++23, you can use the range-based enumerate view to iterate over the resulting vector with both the index
+ * and the value, similar to Python's `enumerate`. For example:
+ * ~~~{.cpp}
+ * for (auto const [index, val] : std::views::enumerate(ROOT::VecOps::Logspace(4, 10, 12))) {
+ *     // Process index and val.
+ * }
+ * ~~~
+ *
+ * \par Example code, at the ROOT prompt:
+ * ~~~{.cpp}
+ * using namespace ROOT::VecOps;
+ * cout << Logspace(4, 10, 12) << '\n';
+ * // { 10000, 35111.9, 123285, 432876, 1.51991e+06, 5.3367e+06, 1.87382e+07, 6.57933e+07, 2.31013e+08, 8.11131e+08, 2.84804e+09, 1e+10 }
+ * cout << Logspace(0, 0, 50) << '\n';
+ * // { 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 }
+ * cout << Logspace(0, 0, 0) << '\n';
+ * // {  }
+ * cout << Logspace(4, 10, 12, 10.0, false) << '\n';
+ * // { 10000, 31622.8, 100000, 316228, 1e+06, 3.16228e+06, 1e+07, 3.16228e+07, 1e+08, 3.16228e+08, 1e+09, 3.16228e+09 }
+ * cout << Logspace<int, int, int, int>(1, 5, 3) << '\n';
+ * // { 10, 1000, 100000 }
+ * ~~~
+ */
+template <typename T1 = double, typename T2 = double, typename T3 = double, typename Common_t = std::conditional_t<std::is_floating_point_v<std::common_type_t<T1, T2, T3>>, std::common_type_t<T1, T2, T3>, double>>
+inline RVec<Common_t> Logspace(T1 start, T2 end, unsigned long long n = 128, T3 base = 10.0, const bool endpoint = true)
+{
+    RVec<Common_t> temp;
+    
+    if (!n || (n > std::numeric_limits<long long>::max())) // Check for invalid or absurd n.
+    {
+        return temp;
+    }
+    
+    Common_t start_c = static_cast<Common_t>(start);
+    Common_t end_c   = static_cast<Common_t>(end);
+    Common_t base_c  = static_cast<Common_t>(base);
+    Common_t step = static_cast<Common_t>(end_c - start_c)/static_cast<Common_t>(n - endpoint);
+    temp.reserve(n);
+    temp.push_back(static_cast<Common_t>(std::pow(base_c, start_c)));
+    for (unsigned long long i = 1; i < n; i++)
+    {
+        Common_t exponent = start_c + i * step;
+        temp.push_back(static_cast<Common_t>(std::pow(base_c, exponent)));
+    }
+    return temp;
+}
+
+/**
+ * \brief Produce RVec with entries in the range [start, end) in increments of step.
+ *
+ * This function generates a vector of values starting at \p start and incremented by \p step,
+ * continuing until the values reach or exceed \p end (the interval is half-open: [start, end)).
+ * The number of elements is computed as:
+ * \f[
+ * n = \lceil \frac{\text{end} - \text{start}}{\text{step}} \rceil
+ * \f]
+ * ensuring that the arithmetic is performed in a floating-point context when needed.
+ *
+ * The function is templated to allow for different arithmetic types. The deduced type \c Common_t is
+ * determined as follows: if the common type of \p T1, \p T2, and \p T3 is a floating point type, that type is used;
+ * otherwise, the arithmetic is performed using \c double.
+ *
+ * \tparam T1 Type of the start value. Default is double.
+ * \tparam T2 Type of the end value. Default is double.
+ * \tparam T3 Type of the step value. Default is double.
+ * \tparam Common_t Deduced type used for arithmetic, which is
+ * std::common_type_t<T1, T2, T3> if that is a floating point type, or double otherwise.
+ *
+ * \param start The first value in the range.
+ * \param end The end of the range (exclusive).
+ * \param step The increment between consecutive values.
+ *
+ * \return A vector (RVec<Common_t>) containing values starting at \p start, each incremented by \p step,
+ *         up to but not including any value equal to or greater than \p end.
+ *
+ * \note The check `if (!n || (n > std::numeric_limits<long long>::max()))` is used to ensure that:
+ *   - n is nonzero, and
+ *   - n does not exceed std::numeric_limits<long long>::max(), which would indicate that a negative range (or other arithmetic issue)
+ *     has resulted in an extremely large unsigned value, thereby preventing an attempt to reserve an absurd
+ *     amount of memory.
+ * \note If the template parameter \c Common_t is explicitly overridden with an integral type, the arithmetic may introduce rounding errors, and as a consequence, the produced sequence may not strictly adhere to the intended progression. If an exact sequence is desired, consider casting the result as follows: `RVec<integral_type>(Arange(...))`. This behavior is different than NumPy in Python.
+ *
+ * \par C++23 Enumerate Support:
+ * With C++23, you can use the range-based enumerate view to iterate over the resulting vector with both the index
+ * and the value, similar to Python's `enumerate`. For example:
+ * ~~~{.cpp}
+ * for (auto const [index, val] : std::views::enumerate(ROOT::VecOps::Arange(1, 13, 5))) {
+ *     // Process index and val.
+ * }
+ * ~~~
+ *
+ * \par Example code, at the ROOT prompt:
+ * ~~~{.cpp}
+ * using namespace ROOT::VecOps;
+ * cout << Arange(0, 0, 5) << '\n';
+ * // {  }
+ * cout << Arange(-7, 20, 4) << '\n';
+ * // { -7, -3, 1, 5, 9, 13, 17 }
+ * cout << Arange(1, 13, 5) << '\n';
+ * // { 1, 6, 11 }
+ * cout << Arange<unsigned int, unsigned int, unsigned int, unsigned int>(5, 9, 1) << '\n';
+ * // { 5, 6, 7, 8 }
+ * ~~~
+ */
+template <typename T1 = double, typename T2 = double, typename T3 = double, typename Common_t = std::conditional_t<std::is_floating_point_v<std::common_type_t<T1, T2, T3>>, std::common_type_t<T1, T2, T3>, double>>
+inline RVec<Common_t> Arange(T1 start, T2 end, T3 step)
+{
+    RVec<Common_t> temp;
+    unsigned long long n = std::ceil(static_cast<Common_t>(end-start)/static_cast<Common_t>(step)); // Ensure floating-point division.
+    
+    if (!n || (n > std::numeric_limits<long long>::max())) // Check for invalid or absurd n.
+    {
+        return temp;
+    }
+    
+    Common_t start_c = static_cast<Common_t>(start);
+    Common_t step_c = static_cast<Common_t>(step);
+    temp.reserve(n);
+    temp.push_back(start_c);
+    for (unsigned long long i = 1; i < n; i++)
+    {
+        temp.push_back(start_c + i * step_c);
+    }
+    return temp;
+}
+
 /// Produce RVec with entries starting from 0, and incrementing by 1 until a user-specified N is reached.
 /// Example code, at the ROOT prompt:
 /// ~~~{.cpp}
@@ -3309,6 +3545,8 @@ inline RVec<long long int> Range(long long int begin, long long int end, long lo
    return ret;
 }
 
+
+
 ////////////////////////////////////////////////////////////////////////////////
 /// Print a RVec at the prompt:
 template <class T>