Repository Public MIT
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