thermite_special/tables/

bernoulli.rs

// @generated by gen_consts.py at the workspace root. DO NOT EDIT BY HAND.
//! Bernoulli numbers `$B_{2n}$`, as one static table per float format.
//!
//! **The tables start at `$B_2$`**, so entry `i` is `$B_{2i+2}$`. They are even-index
//! only: every odd-index Bernoulli number past `$B_1$` is zero, so storing them would
//! double the table for nothing.
//!
//! ```
//! use thermite_special::tables::bernoulli::BernoulliNumbers;
//!
//! assert_eq!(f64::B2N[0], 1.0 / 6.0);           // B_2
//! assert_eq!(f64::B2N[2], 1.0 / 42.0);          // B_6
//! ```
//!
//! # `$B_0$` and `$B_1$` are deliberately absent
//!
//! `$B_1$` is the single value the two competing conventions disagree on: `$-1/2$` if
//! you take the generating function to be `$x/(e^x - 1)$`, `$+1/2$` if you take it to be
//! `$x/(1 - e^{-x})$` (Knuth has argued in print for the latter). Every _other_ Bernoulli
//! number is identical under both, so omitting `$B_1$` makes this table convention-free
//! rather than convention-bearing.
//!
//! `$B_0 = 1$` is not contested, but it goes with it, because the two co-occur. A formula
//! that indexes the sequence from zero (Faulhaber's sum of powers, the binomial
//! recurrence, the Bernoulli polynomials) reaches `$B_1$` at `$k = 1$` and therefore
//! already special-cases the head of the sequence. A formula that skips `$B_1$`
//! (Euler-Maclaurin, the `$\ln\Gamma$` / `$\psi$` asymptotic series, the `$\zeta(2n)$`
//! identity) starts at `$B_2$` and never wanted `$B_0$` either. Nothing sits in the gap,
//! so the table holds exactly the values that need a table.
//!
//! Callers who want the head should let their heart guide them on `$B_1 = \pm\tfrac{1}{2}$`
//! and write `$B_0 = 1$` beside it.
//!
//! # The table ends where the format does
//!
//! `$|B_{2n}|$` grows factorially,
//!
//! ```math
//! |B_{2n}| = \frac{2\,(2n)!}{(2\pi)^{2n}}\,\zeta(2n)
//!     \sim 4\sqrt{\pi n}\left(\frac{n}{\pi e}\right)^{2n}
//! ```
//!
//! with consecutive terms growing by roughly `$n^2/\pi^2$`, so each format has a _last_
//! representable Bernoulli number and nothing beyond it to return.
//!
//! The tables stop exactly there, which means **`B2N.len()` is the overflow boundary**:
//! `B2N.get(i)` is `None` precisely where the value would be infinite. There is no
//! overflow policy, no error type and no limit constant, because the slice length
//! already carries that information.
//!
//! There is no underflow at the other end. `$|B_{2n}|$` bottoms out at
//! `$B_6 = 1/42$` and grows monotonically after it, so no entry is denormal.
//!
//! | format | entries | first | last finite | first to overflow |
//! |---|---|---|---|---|
//! | `f32` | 32 | `$B_2$` | `$B_{64}$` | `$B_{66}$` |
//! | `f64` | 129 | `$B_2$` | `$B_{258}$` | `$B_{260}$` |
//!
//! `thermite-compensated` implements the same trait for `Compensated<f32>` and
//! `Compensated<f64>` under its `special` feature. Those tables are the SAME lengths: a
//! double-double carries twice the mantissa but the same exponent range, so widening the
//! type buys precision, not reach.

use thermite::element::FloatElement;

/// Static Bernoulli number tables for a float format.
///
/// Implemented for `f32` and `f64` here, and for `Compensated<f32>` /
/// `Compensated<f64>` by `thermite-compensated` under its `special` feature.
pub trait BernoulliNumbers: FloatElement {
    /// `$B_2, B_4, B_6, \ldots$`, every even-index Bernoulli number finite in `Self`,
    /// starting at `$B_2$`, so that entry `i` is `$B_{2i+2}$`.
    ///
    /// See the [module docs](self) for why the table ends where it does, and why
    /// `$B_0$` and `$B_1$` are not in it.
    const B2N: &'static [Self];
}

/// `$B_{2n}$`, or `None` when it is not tabulated: either `$n = 0$`, or `$B_{2n}$`
/// overflows `E`.
///
/// The argument is `n` as in `$B_{2n}$`, following the mathematics rather than the
/// slice index, so `bernoulli_b2n::<f64>(1)` is `$B_2$`, the first entry. Reach for
/// [`BernoulliNumbers::B2N`] directly when iterating, where entry `i` is `$B_{2i+2}$`.
#[inline]
#[must_use]
pub fn bernoulli_b2n<E: BernoulliNumbers>(n: usize) -> Option<E> {
    E::B2N.get(n.checked_sub(1)?).copied()
}

impl BernoulliNumbers for f32 {
    #[rustfmt::skip]
    const B2N: &'static [f32] = &[
        0.16666667,  // B_2
        -0.033333335,  // B_4
        0.023809524,  // B_6
        -0.033333335,  // B_8
        0.07575758,  // B_10
        -0.25311357,  // B_12
        1.1666666,  // B_14
        -7.092157,  // B_16
        54.971176,  // B_18
        -529.12427,  // B_20
        6192.123,  // B_22
        -86580.25,  // B_24
        1425517.1,  // B_26
        -27298232.0,  // B_28
        6.0158086e+08,  // B_30
        -1.5116316e+10,  // B_32
        4.2961463e+11,  // B_34
        -1.3711655e+13,  // B_36
        4.883323e+14,  // B_38
        -1.929658e+16,  // B_40
        8.4169306e+17,  // B_42
        -4.0338073e+19,  // B_44
        2.1150749e+21,  // B_46
        -1.20866265e+23,  // B_48
        7.500867e+24,  // B_50
        -5.038778e+26,  // B_52
        3.6528777e+28,  // B_54
        -2.849877e+30,  // B_56
        2.3865428e+32,  // B_58
        -2.139995e+34,  // B_60
        2.0500976e+36,  // B_62
        -2.0938006e+38,  // B_64
    ];
}

impl BernoulliNumbers for f64 {
    #[rustfmt::skip]
    const B2N: &'static [f64] = &[
        0.16666666666666666,  // B_2
        -0.03333333333333333,  // B_4
        0.023809523809523808,  // B_6
        -0.03333333333333333,  // B_8
        0.07575757575757576,  // B_10
        -0.2531135531135531,  // B_12
        1.1666666666666667,  // B_14
        -7.092156862745098,  // B_16
        54.971177944862156,  // B_18
        -529.1242424242424,  // B_20
        6192.123188405797,  // B_22
        -86580.25311355312,  // B_24
        1425517.1666666667,  // B_26
        -27298231.067816094,  // B_28
        601580873.9006424,  // B_30
        -15116315767.092157,  // B_32
        429614643061.1667,  // B_34
        -13711655205088.332,  // B_36
        488332318973593.2,  // B_38
        -1.9296579341940068e+16,  // B_40
        8.416930475736826e+17,  // B_42
        -4.0338071854059454e+19,  // B_44
        2.1150748638081993e+21,  // B_46
        -1.2086626522296526e+23,  // B_48
        7.500866746076964e+24,  // B_50
        -5.038778101481069e+26,  // B_52
        3.6528776484818122e+28,  // B_54
        -2.849876930245088e+30,  // B_56
        2.3865427499683627e+32,  // B_58
        -2.1399949257225335e+34,  // B_60
        2.0500975723478097e+36,  // B_62
        -2.093800591134638e+38,  // B_64
        2.2752696488463515e+40,  // B_66
        -2.6257710286239577e+42,  // B_68
        3.212508210271803e+44,  // B_70
        -4.159827816679471e+46,  // B_72
        5.692069548203528e+48,  // B_74
        -8.218362941978458e+50,  // B_76
        1.2502904327166994e+53,  // B_78
        -2.001558323324837e+55,  // B_80
        3.3674982915364376e+57,  // B_82
        -5.947097050313545e+59,  // B_84
        1.1011910323627977e+62,  // B_86
        -2.1355259545253502e+64,  // B_88
        4.3328896986641194e+66,  // B_90
        -9.188552824166933e+68,  // B_92
        2.0346896776329074e+71,  // B_94
        -4.700383395803573e+73,  // B_96
        1.131804344548425e+76,  // B_98
        -2.8382249570693707e+78,  // B_100
        7.406424897967885e+80,  // B_102
        -2.0096454802756605e+83,  // B_104
        5.665717005080594e+85,  // B_106
        -1.6584511154136216e+88,  // B_108
        5.036885995049238e+90,  // B_110
        -1.5861468237658186e+93,  // B_112
        5.1756743617545625e+95,  // B_114
        -1.7488921840217116e+98,  // B_116
        6.116051999495218e+100,  // B_118
        -2.2122776912707833e+103,  // B_120
        8.272277679877097e+105,  // B_122
        -3.195892511141571e+108,  // B_124
        1.2750082223387793e+111,  // B_126
        -5.250092308677413e+113,  // B_128
        2.2301817894241627e+116,  // B_130
        -9.76845219309552e+118,  // B_132
        4.409836197845295e+121,  // B_134
        -2.050857088646409e+124,  // B_136
        9.821443327979128e+126,  // B_138
        -4.841260079820888e+129,  // B_140
        2.4553088801480982e+132,  // B_142
        -1.2806926804084748e+135,  // B_144
        6.867616710466858e+137,  // B_146
        -3.7846468581969106e+140,  // B_148
        2.142610125066529e+143,  // B_150
        -1.2456727137183695e+146,  // B_152
        7.434578755100016e+148,  // B_154
        -4.5535795304641704e+151,  // B_156
        2.861211281685887e+154,  // B_158
        -1.843772355203387e+157,  // B_160
        1.2181154536221047e+160,  // B_162
        -8.248218718531412e+162,  // B_164
        5.722587793783294e+165,  // B_166
        -4.0668530525059105e+168,  // B_168
        2.9596092064642052e+171,  // B_170
        -2.2049522565189457e+174,  // B_172
        1.68125970728896e+177,  // B_174
        -1.3116736213556958e+180,  // B_176
        1.0467894009478039e+183,  // B_178
        -8.543289357883371e+185,  // B_180
        7.128782132248655e+188,  // B_182
        -6.08029314555359e+191,  // B_184
        5.299677642484992e+194,  // B_186
        -4.719425916874586e+197,  // B_188
        4.292841379140298e+200,  // B_190
        -3.9876744968232205e+203,  // B_192
        3.781978041935888e+206,  // B_194
        -3.661423368368119e+209,  // B_196
        3.617609027237286e+212,  // B_198
        -3.647077264519136e+215,  // B_200
        3.750875543645441e+218,  // B_202
        -3.934586729643903e+221,  // B_204
        4.208821114819008e+224,  // B_206
        -4.590229622061792e+227,  // B_208
        5.103172577262957e+230,  // B_210
        -5.782276230365695e+233,  // B_212
        6.676248216783588e+236,  // B_214
        -7.853530764445042e+239,  // B_216
        9.410689406705872e+242,  // B_218
        -1.1484933873465185e+246,  // B_220
        1.4272958742848785e+249,  // B_222
        -1.805955958690931e+252,  // B_224
        2.3261535307660807e+255,  // B_226
        -3.0495751715499594e+258,  // B_228
        4.068580607643398e+261,  // B_230
        -5.523103132197436e+264,  // B_232
        7.6277279396434395e+267,  // B_234
        -1.0715571119697886e+271,  // B_236
        1.5310200895969188e+274,  // B_238
        -2.2244891682179836e+277,  // B_240
        3.286267919069014e+280,  // B_242
        -4.935592895596035e+283,  // B_244
        7.534957120083251e+286,  // B_246
        -1.1691485154584178e+290,  // B_248
        1.843526146783894e+293,  // B_250
        -2.953682617296808e+296,  // B_252
        4.807932127750157e+299,  // B_254
        -7.950212504588525e+302,  // B_256
        1.3352784187354634e+306,  // B_258
    ];
}