From 2777a4eb49c208b3e57ee8de0429993a2e713dce Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Tue, 9 Jan 2024 15:00:03 -0700 Subject: [PATCH] Better document Utilities::pow(). Also make it 'constexpr'. --- include/deal.II/base/utilities.h | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) 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)) || -- 2.39.5