From: Wolfgang Bangerth Date: Tue, 9 Jan 2024 22:00:03 +0000 (-0700) Subject: Better document Utilities::pow(). Also make it 'constexpr'. X-Git-Tag: relicensing~184^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F16442%2Fhead;p=dealii.git Better document Utilities::pow(). Also make it 'constexpr'. --- diff --git a/include/deal.II/base/utilities.h b/include/deal.II/base/utilities.h index 30dc5684b6..68a3259f13 100644 --- a/include/deal.II/base/utilities.h +++ b/include/deal.II/base/utilities.h @@ -429,12 +429,29 @@ namespace Utilities * Calculate a fixed power, provided as a template argument, of a number. * * This function provides an efficient way to calculate things like - * t^N where N is a known number at compile time. + * $t^N$ where N is a known number at compile time. + * The function computes the power of $t$ via the "recursive doubling" + * approach in which, for example, $t^7$ is computed as + * @f{align*}{ + * t^7 = (tttt)(tt)(t) + * @f} + * where computing $tt$ requires one product, computing $tttt$ is + * achieved by multiplying the previously computed $tt$ by itself + * (requiring another multiplication), and then the product is computed + * via two more multiplications for a total of 4 multiplications + * instead of the naively necessary 6. * - * Use this function as in fixed_power@ (n). + * The major savings this function generates result, however, from the + * fact that it exploits that we have an integer power of the argument $t$. + * The alternative to computing such powers, `std::pow(t,7)` uses the + * `std::pow` function that takes the exponent as a floating point number + * and, because it has to cater to the complexities of the general situation, + * is vastly slower. + * + * Use this function as in `fixed_power (t)` or `fixed_power<7> (t)`. */ template - T + constexpr T fixed_power(const T t); /** @@ -971,7 +988,7 @@ namespace Utilities namespace Utilities { template - inline T + inline constexpr T fixed_power(const T x) { Assert(((std::is_integral_v == true) && (N >= 0)) ||