SPB Git

Repository Public MIT

SpecialFunctionTests.swift 13.1 KB 212 lines swift

1// ORIX Calc2// File: Packages/ORIXStatistics/Tests/ORIXStatisticsTests/SpecialFunctionTests.swift3// Description: Special functions against 50-digit mpmath references, identities, round trips and domain errors.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai7import Foundation8import Testing9@testable import ORIXStatistics1011/// Evaluates one reference case of special.json.12func evaluateSpecial(_ fn: String, _ a: [Double]) throws -> Double? {13    switch fn {14    case "logGamma": try SpecialFunctions.logGamma(a[0])15    case "gamma": try SpecialFunctions.gamma(a[0])16    case "logBeta": try SpecialFunctions.logBeta(a[0], a[1])17    case "beta": try SpecialFunctions.beta(a[0], a[1])18    case "gammaP": try SpecialFunctions.regularizedGammaP(a: a[0], x: a[1])19    case "gammaQ": try SpecialFunctions.regularizedGammaQ(a: a[0], x: a[1])20    case "betaI": try SpecialFunctions.regularizedBeta(x: a[0], a: a[1], b: a[2])21    case "betaIc": try SpecialFunctions.regularizedBetaComplement(x: a[0], a: a[1], b: a[2])22    case "erfinv": try SpecialFunctions.inverseErf(a[0])23    case "erfcinv": try SpecialFunctions.inverseErfc(a[0])24    case "normQ": try SpecialFunctions.normalQuantile(a[0])25    case "normQupper": try SpecialFunctions.normalQuantile(upperTail: a[0])26    case "normCDF": try SpecialFunctions.normalCDF(a[0])27    case "normSF": try SpecialFunctions.normalSurvival(a[0])28    case "gammaPinv": try SpecialFunctions.inverseRegularizedGammaP(a: a[0], p: a[1])29    case "gammaQinv": try SpecialFunctions.inverseRegularizedGammaQ(a: a[0], q: a[1])30    case "betaIinv": try SpecialFunctions.inverseRegularizedBeta(p: a[0], a: a[1], b: a[2])31    case "betaIcinv": try SpecialFunctions.inverseRegularizedBetaComplement(q: a[0], a: a[1], b: a[2])32    default: nil33    }34}3536/// Worst relative error per function. Incomplete-beta cases are split by the size of the larger shape parameter.37func specialAccuracy() throws -> [String: ErrorTracker] {38    var trackers: [String: ErrorTracker] = [:]39    for c in try Reference.cases("special") {40        let fn = c.string("fn"), a = c.doubles("args"), e = c.double("expected")41        guard let v = try evaluateSpecial(fn, a) else { continue }42        var key = fn43        if fn == "betaI" || fn == "betaIc" { key += max(a[1], a[2]) > 1000 ? " (a shape > 1000)" : " (shapes ≤ 1000)" }44        trackers[key, default: .init()].record(v, e, "\(fn)\(a) = \(v) vs \(e)")45    }46    return trackers47}4849@Suite struct SpecialFunctionReferenceTests {50    /// Tolerances are the measured accuracy (see VALIDATION.md) with a small safety factor.51    static let limits: [String: Double] = [52        "logGamma": 1e-15, "gamma": 1e-15, "logBeta": 2e-15, "beta": 2e-14,53        "erfinv": 2e-15, "erfcinv": 2e-15, "normQ": 2e-15, "normQupper": 2e-15, "normCDF": 5e-13, "normSF": 5e-13,54        "gammaP": 5e-13, "gammaQ": 5e-13, "gammaPinv": 5e-13, "gammaQinv": 5e-13,55        "betaI (shapes ≤ 1000)": 2e-12, "betaIc (shapes ≤ 1000)": 2e-12, "betaI (a shape > 1000)": 5e-13, "betaIc (a shape > 1000)": 5e-13,56        "betaIinv": 5e-13, "betaIcinv": 5e-13,57    ]5859    @Test func matchesMpmathOnTheWholeGrid() throws {60        let trackers = try specialAccuracy()61        #expect(trackers.values.reduce(0) { $0 + $1.count } > 5000)62        if ProcessInfo.processInfo.environment["ORIX_ACCURACY_REPORT"] != nil {63            for (k, t) in trackers.sorted(by: { $0.key < $1.key }) { print("SPC|\(k)|\(t.count)|\(t.worst)|\(t.worstCase)") }64        }65        for (key, t) in trackers {66            let limit = try #require(Self.limits[key], "no tolerance declared for \(key)")67            #expect(t.worst <= limit, "\(key): worst relative error \(t.worst) at \(t.worstCase)")68        }69        #expect(Set(trackers.keys) == Set(Self.limits.keys))70    }7172    @Test func acklamCoefficientsAreTheRealOnes() throws {73        // The unrefined rational approximation must show Acklam's published 1.15e-9 bound, which a mistyped coefficient would break.74        var worst = 0.075        for c in try Reference.cases("special") where c.string("fn") == "normQ" {76            let p = c.doubles("args")[0], e = c.double("expected")77            guard p <= 0.5, p > 1e-300 else { continue }78            worst = max(worst, relativeError(SpecialFunctions.acklam(p), e))79        }80        #expect(worst < 1.2e-9)81        #expect(worst > 1e-11)      // and the refinement is really what delivers full precision82    }83}8485@Suite struct SpecialFunctionIdentityTests {86    @Test func complementsSumToOne() throws {87        for a in [0.2, 1, 3.5, 40, 900] {88            for x in [0.01, 0.7, 2, 35, 1000] {89                let p = try SpecialFunctions.regularizedGammaP(a: a, x: x), q = try SpecialFunctions.regularizedGammaQ(a: a, x: x)90                #expect(abs(p + q - 1) < 4e-16)91            }92        }93        for (a, b) in [(0.5, 0.5), (2, 7), (30, 4), (120, 250)] {94            for x in [0.001, 0.2, 0.5, 0.83, 0.999] {95                let p = try SpecialFunctions.regularizedBeta(x: x, a: a, b: b)96                #expect(abs(p + (try SpecialFunctions.regularizedBetaComplement(x: x, a: a, b: b)) - 1) < 4e-16)97                // Symmetry I_x(a, b) = 1 − I_{1−x}(b, a)98                #expect(close(p, try SpecialFunctions.regularizedBetaComplement(x: 1 - x, a: b, b: a), rtol: 1e-12, atol: 1e-300))99            }100        }101    }102103    @Test func closedForms() throws {104        // P(1, x) = 1 − e^(−x);  I_x(1, b) = 1 − (1 − x)^b;  I_x(a, 1) = x^a;  Γ(½) = √π;  B(a, b) by gamma functions105        for x in [1e-9, 0.3, 4, 50.0] { #expect(close(try SpecialFunctions.regularizedGammaP(a: 1, x: x), -expm1(-x), rtol: 1e-14)) }106        for x in [1e-9, 0.3, 0.97] {107            #expect(close(try SpecialFunctions.regularizedBeta(x: x, a: 1, b: 3.5), -expm1(3.5 * log1p(-x)), rtol: 1e-14))108            #expect(close(try SpecialFunctions.regularizedBeta(x: x, a: 2.25, b: 1), pow(x, 2.25), rtol: 1e-14))109        }110        #expect(close(try SpecialFunctions.gamma(0.5), Double.pi.squareRoot(), rtol: 1e-15))111        #expect(close(try SpecialFunctions.beta(2.5, 4), tgamma(2.5) * tgamma(4) / tgamma(6.5), rtol: 1e-14))112        #expect(try SpecialFunctions.regularizedGammaP(a: 3, x: 0) == 0)113        #expect(try SpecialFunctions.regularizedGammaQ(a: 3, x: .infinity) == 0)114        #expect(try SpecialFunctions.regularizedBeta(x: 0, a: 2, b: 3) == 0)115        #expect(try SpecialFunctions.regularizedBeta(x: 1, a: 2, b: 3) == 1)116        #expect(try SpecialFunctions.normalCDF(0) == 0.5)117        #expect(try SpecialFunctions.normalCDF(-.infinity) == 0)118        #expect(try SpecialFunctions.inverseErf(0) == 0)119    }120121    @Test func inverseRoundTrips() throws {122        for p in [1e-250, 1e-40, 1e-9, 0.02, 0.31, 0.5, 0.77, 0.999, 1 - 1e-13] {123            #expect(close(try SpecialFunctions.normalCDF(try SpecialFunctions.normalQuantile(p)), p, rtol: 5e-13))124            for a in [0.3, 1, 4.5, 60, 2500] {125                let x = try SpecialFunctions.inverseRegularizedGammaP(a: a, p: p)126                if x == 0 { #expect(p < 1e-200 && a < 1); continue }       // the true solution is below the smallest double127                #expect(close(try SpecialFunctions.regularizedGammaP(a: a, x: x), p, rtol: 2e-12), "gamma a=\(a) p=\(p)")128            }129            for (a, b) in [(0.4, 0.7), (1, 1), (3, 9), (45, 12), (300, 800)] {130                let x = try SpecialFunctions.inverseRegularizedBeta(p: p, a: a, b: b)131                if x == 0 { #expect(p < 1e-200 && a < 1); continue }132                if x == 1 { #expect(1 - p < 1e-12); continue }             // 1 − x is below one ulp of 1133                #expect(close(try SpecialFunctions.regularizedBeta(x: x, a: a, b: b), p, rtol: 2e-11), "beta a=\(a) b=\(b) p=\(p)")134            }135        }136        for q in [1e-280, 1e-30, 1e-6, 0.04, 0.5] {137            #expect(close(try SpecialFunctions.normalSurvival(try SpecialFunctions.normalQuantile(upperTail: q)), q, rtol: 5e-13))138            #expect(close(try SpecialFunctions.regularizedGammaQ(a: 7.5, x: try SpecialFunctions.inverseRegularizedGammaQ(a: 7.5, q: q)), q, rtol: 2e-12))139            // Upper tail of a beta whose mass sits near 0: the solution stays away from 1, so it is representable.140            let x = try SpecialFunctions.inverseRegularizedBetaComplement(q: q, a: 0.4, b: 30)141            if x < 0.99 { #expect(close(try SpecialFunctions.regularizedBetaComplement(x: x, a: 0.4, b: 30), q, rtol: 2e-11)) }142            else { #expect(q < 1e-50) }      // 1 − x no longer has enough digits for a relative round trip143        }144        for y in [-0.999999, -0.4, 1e-12, 0.2, 0.86, 1 - 1e-12] {145            #expect(close(Foundation.erf(try SpecialFunctions.inverseErf(y)), y, rtol: 4e-16, atol: 1e-300))146        }147        #expect(try SpecialFunctions.inverseRegularizedBeta(p: 0, a: 2, b: 3) == 0)148        #expect(try SpecialFunctions.inverseRegularizedBeta(p: 1, a: 2, b: 3) == 1)149        #expect(try SpecialFunctions.inverseRegularizedGammaP(a: 2, p: 0) == 0)150    }151152    @Test func internalHelpers() {153        for a in [1e-12, 1e-5, 0.01, 0.15, 0.1999, 0.2, 0.7] {154            // lgamma(1 + a) from the Taylor branch agrees with libm where libm is accurate, and is ≈ −γa for tiny a.155            #expect(close(SpecialFunctions.logGamma1p(a), SpecialFunctions.lg(1 + a), rtol: 1e-12, atol: 2e-16))156        }157        #expect(close(SpecialFunctions.logGamma1p(1e-12), -0.5772156649015329e-12, rtol: 1e-11))158        for u in [-0.9, -0.3, -1e-8, 1e-8, 0.4, 3.0] {159            #expect(close(SpecialFunctions.log1pmx(u), abs(u) < 1e-4 ? -u * u / 2 + u * u * u / 3 : log1p(u) - u, rtol: 1e-9))160        }161        for z in [0.3, 1, 9.99, 10, 50, 1e6] {162            #expect(close(SpecialFunctions.stirlingRemainder(z), SpecialFunctions.lg(z) - (z - 0.5) * log(z) + z - SpecialFunctions.halfLog2Pi, rtol: 1e-6, atol: 3e-9))163        }164    }165166    @Test func combinatorics() throws {167        #expect(try SpecialFunctions.factorial(0) == 1)168        #expect(try SpecialFunctions.factorial(10) == 3_628_800)169        #expect(try SpecialFunctions.factorial(20) == 2_432_902_008_176_640_000)170        #expect(close(try SpecialFunctions.factorial(170), 7.257415615307994e306, rtol: 1e-15))171        #expect(close(try SpecialFunctions.logFactorial(1000), 5912.128178488163, rtol: 1e-15))172        #expect(try SpecialFunctions.binomialCoefficient(52, 5) == 2_598_960)173        #expect(try SpecialFunctions.binomialCoefficient(60, 30) == 118_264_581_564_861_424)174        #expect(try SpecialFunctions.binomialCoefficient(5, 9) == 0)175        #expect(try SpecialFunctions.binomialCoefficient(7, 0) == 1)176        #expect(try SpecialFunctions.permutations(10, 3) == 720)177        #expect(try SpecialFunctions.permutations(4, 6) == 0)178    }179180    @Test func domainErrors() {181        #expect(throws: StatisticsError.self) { try SpecialFunctions.gamma(0) }182        #expect(throws: StatisticsError.self) { try SpecialFunctions.gamma(-3) }183        #expect(throws: StatisticsError.overflow("Γ(200)")) { try SpecialFunctions.gamma(200) }184        #expect(throws: StatisticsError.self) { try SpecialFunctions.logGamma(-1) }185        #expect(throws: StatisticsError.self) { try SpecialFunctions.logGamma(.nan) }186        #expect(throws: StatisticsError.self) { try SpecialFunctions.beta(-1, 2) }187        #expect(throws: StatisticsError.self) { try SpecialFunctions.regularizedGammaP(a: 0, x: 1) }188        #expect(throws: StatisticsError.self) { try SpecialFunctions.regularizedGammaP(a: 1, x: -0.1) }189        #expect(throws: StatisticsError.self) { try SpecialFunctions.regularizedGammaQ(a: 1, x: .nan) }190        #expect(throws: StatisticsError.self) { try SpecialFunctions.regularizedBeta(x: 1.2, a: 1, b: 1) }191        #expect(throws: StatisticsError.self) { try SpecialFunctions.regularizedBeta(x: 0.2, a: 0, b: 1) }192        #expect(throws: StatisticsError.probabilityOutOfRange(1.5)) { try SpecialFunctions.inverseRegularizedBeta(p: 1.5, a: 1, b: 1) }193        #expect(throws: StatisticsError.self) { try SpecialFunctions.inverseRegularizedGammaP(a: 2, p: -0.1) }194        #expect(throws: StatisticsError.self) { try SpecialFunctions.inverseRegularizedGammaP(a: 2, p: 1) }195        #expect(throws: StatisticsError.self) { try SpecialFunctions.normalQuantile(0) }196        #expect(throws: StatisticsError.self) { try SpecialFunctions.normalQuantile(1) }197        #expect(throws: StatisticsError.self) { try SpecialFunctions.normalQuantile(.nan) }198        #expect(throws: StatisticsError.self) { try SpecialFunctions.inverseErf(1) }199        #expect(throws: StatisticsError.self) { try SpecialFunctions.inverseErfc(0) }200        #expect(throws: StatisticsError.self) { try SpecialFunctions.factorial(-1) }201        #expect(throws: StatisticsError.self) { try SpecialFunctions.factorial(171) }202        #expect(throws: StatisticsError.self) { try SpecialFunctions.binomialCoefficient(-1, 2) }203    }204205    @Test func errorMessagesAreUserFacing() {206        #expect(StatisticsError.emptyData.description == "The data list is empty.")207        #expect(StatisticsError.insufficientSample(required: 2, actual: 1).description == "This calculation needs at least 2 observations; 1 was given.")208        #expect(StatisticsError.probabilityOutOfRange(1.5).description == "1.5 is not a valid probability or level.")209        #expect(StatisticsError.emptyData.errorDescription == "The data list is empty.")210    }211}212
Files main
Menu

Theme