From 9056a1aeb200869fa22d6f6ae2f40c816e817fd4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20M=C3=BCller-Widmann?= Date: Tue, 3 Nov 2026 13:18:38 +0100 Subject: [PATCH 1/6] Add gamma_inc_dx and fix overflow and cancellation in ChainRules for gamma_inc and loggamma(a, x) Add the public function gamma_inc_dx(a, x), the x-derivative of the regularized incomplete gamma functions, which avoids overflow and underflow of intermediate results for large arguments. Use it in the ChainRules rule of gamma_inc, and compute the derivative of loggamma(a, x) as -1/(x * expintx(1 - a, x)) without cancellation, sharing expintx with the primal. Promote the arguments of loggamma(a, x) with promotereal so that integer a does not widen Float32 x. Co-Authored-By: Claude Opus 5.5 --- Project.toml | 2 +- docs/src/functions_list.md | 1 + docs/src/functions_overview.md | 1 + ext/SpecialFunctionsChainRulesCoreExt.jl | 27 +++++--- src/SpecialFunctions.jl | 4 ++ src/gamma_inc.jl | 82 ++++++++++++++++++++++-- test/chainrules.jl | 27 ++++++++ test/gamma_inc.jl | 46 +++++++++++++ test/qa.jl | 2 + test/type_stability.jl | 1 + 10 files changed, 177 insertions(+), 16 deletions(-) diff --git a/Project.toml b/Project.toml index 46a50664a..db9c89635 100644 --- a/Project.toml +++ b/Project.toml @@ -1,6 +1,6 @@ name = "SpecialFunctions" uuid = "276daf66-3868-5448-9aa4-cd146d93841b" -version = "2.9.1" +version = "2.10.0" [deps] ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4" diff --git a/docs/src/functions_list.md b/docs/src/functions_list.md index 5890373f7..f510a77f6 100644 --- a/docs/src/functions_list.md +++ b/docs/src/functions_list.md @@ -18,6 +18,7 @@ invdigamma trigamma polygamma gamma_inc +gamma_inc_dx gamma_inc_inv loggammadiv gammax diff --git a/docs/src/functions_overview.md b/docs/src/functions_overview.md index 6cea9b02b..7a52d74f0 100644 --- a/docs/src/functions_overview.md +++ b/docs/src/functions_overview.md @@ -19,6 +19,7 @@ Here the *Special Functions* are listed according to the structure of [NIST Digi | [`gamma(a,z)`](@ref SpecialFunctions.gamma(::Number,::Number)) | [upper incomplete gamma function ``\Gamma(a,z)``](https://en.wikipedia.org/wiki/Incomplete_gamma_function) | | [`loggamma(a,z)`](@ref SpecialFunctions.loggamma(::Number,::Number)) | accurate `log(gamma(a,x))` for large arguments | | [`gamma_inc(a,x,IND)`](@ref SpecialFunctions.gamma_inc) | [incomplete gamma function ratio ``P(a,x)`` and ``Q(a,x)``](https://en.wikipedia.org/wiki/Incomplete_gamma_function) (i.e evaluates ``P(a,x)`` and ``Q(a,x)`` for accuracy specified by IND and returns tuple (p,q)) | +| [`gamma_inc_dx(a,x)`](@ref SpecialFunctions.gamma_inc_dx) | derivative ``\partial P(a,x)/\partial x = -\partial Q(a,x)/\partial x`` of the incomplete gamma function ratios | | [`gamma_inc_inv(a,p,q)`](@ref SpecialFunctions.gamma_inc_inv) | [inverse of incomplete gamma function ratio ``P(a,x)`` and ``Q(a,x)``](https://en.wikipedia.org/wiki/Incomplete_gamma_function) (i.e evaluates x given ``P(a,x)=p`` and ``Q(a,x)=q``) | | [`beta(x,y)`](@ref SpecialFunctions.beta) | [beta function](https://en.wikipedia.org/wiki/Beta_function) at `x,y` | | [`logbeta(x,y)`](@ref SpecialFunctions.logbeta) | accurate `log(beta(x,y))` for large `x` or `y` | diff --git a/ext/SpecialFunctionsChainRulesCoreExt.jl b/ext/SpecialFunctionsChainRulesCoreExt.jl index 580f2c4c2..8f108c9cd 100644 --- a/ext/SpecialFunctionsChainRulesCoreExt.jl +++ b/ext/SpecialFunctionsChainRulesCoreExt.jl @@ -3,7 +3,7 @@ module SpecialFunctionsChainRulesCoreExt using SpecialFunctions using ChainRulesCore: ChainRulesCore -using SpecialFunctions: sqrtπ, invπ +using SpecialFunctions: sqrtπ, invπ, gamma_inc_dx const BESSEL_ORDER_INFO = """ derivatives of Bessel functions with respect to the order are not implemented currently: @@ -62,7 +62,7 @@ ChainRulesCore.@scalar_rule( ) ChainRulesCore.@scalar_rule( gamma_inc(a, x, IND), - @setup(z = exp(-x) * x^(a - 1) / gamma(a)), + @setup(z = gamma_inc_dx(a, x)), ( ChainRulesCore.@not_implemented(INCOMPLETE_GAMMA_INFO), z, @@ -172,13 +172,22 @@ ChainRulesCore.@scalar_rule( ) ChainRulesCore.@scalar_rule(loggamma(x), digamma(x)) -ChainRulesCore.@scalar_rule( - loggamma(a, x), - ( - ChainRulesCore.@not_implemented(INCOMPLETE_GAMMA_INFO), - -exp(- (x + Ω)) * x^(a - 1), - ) -) +# Hand-written rules, so that the primal and the derivative share `expintx(1 - a, x)` +function ChainRulesCore.frule((_, Δa, Δx), ::typeof(loggamma), a::Number, x::Number) + Ω, ∂Ω_∂x = SpecialFunctions._loggamma_and_dx(a, x) + ∂Ω_∂a = ChainRulesCore.@not_implemented(INCOMPLETE_GAMMA_INFO) + return Ω, muladd(∂Ω_∂x, Δx, ∂Ω_∂a * Δa) +end +function ChainRulesCore.rrule(::typeof(loggamma), a::Number, x::Number) + Ω, ∂Ω_∂x = SpecialFunctions._loggamma_and_dx(a, x) + project_x = ChainRulesCore.ProjectTo(x) + function loggamma_pullback(ΔΩ) + ā = ChainRulesCore.@not_implemented(INCOMPLETE_GAMMA_INFO) + x̄ = project_x(conj(∂Ω_∂x) * ΔΩ) + return ChainRulesCore.NoTangent(), ā, x̄ + end + return Ω, loggamma_pullback +end # exponential integrals ChainRulesCore.@scalar_rule(expint(z), - exp(-z) / z) diff --git a/src/SpecialFunctions.jl b/src/SpecialFunctions.jl index 8b6c289e6..2eb7c625d 100644 --- a/src/SpecialFunctions.jl +++ b/src/SpecialFunctions.jl @@ -92,6 +92,10 @@ export cosint, lbinomial +@static if VERSION >= v"1.11.0-DEV.469" + eval(Expr(:public, :gamma_inc_dx)) +end + include("bessel.jl") include("erf.jl") include("ellip.jl") diff --git a/src/gamma_inc.jl b/src/gamma_inc.jl index 505888e4c..6e369798e 100644 --- a/src/gamma_inc.jl +++ b/src/gamma_inc.jl @@ -948,6 +948,57 @@ end _gamma_inc(a::Float32,x::Float32,ind::Integer) = Float32.(_gamma_inc(Float64(a),Float64(x),ind)) _gamma_inc(a::Float16,x::Float16,ind::Integer) = Float16.(_gamma_inc(Float64(a),Float64(x),ind)) +@doc raw""" + gamma_inc_dx(a, x) + +Compute the derivative of the incomplete gamma function ratios ``P(a, x)`` and ``Q(a, x)`` +returned by [`gamma_inc(a, x)`](@ref SpecialFunctions.gamma_inc) with respect to `x`: +```math +\frac{\partial P(a, x)}{\partial x} = - \frac{\partial Q(a, x)}{\partial x} = \frac{x^{a - 1} e^{-x}}{\Gamma(a)} +``` +for real `a` and `x ≥ 0`. For `a > 0` it is the probability density function of the +gamma distribution with shape `a` and unit scale. + +The implementation avoids overflow and underflow of the intermediate results in the formula +above, e.g., for large `a` and `x`. +""" +gamma_inc_dx(a::Real, x::Real) = _gamma_inc_dx(map(float, promote(a, x))...) + +function _gamma_inc_dx(a::T, x::T) where {T<:Union{Float64,BigFloat}} + if isnan(a) || isnan(x) + return a + x + elseif x < 0 + throw(DomainError(x, "`x` must be non-negative")) + elseif isinteger(a) && a <= 0 + # 1 / Γ(a) = 0 + return zero(T) + elseif iszero(x) + # For `a < 1`, the sign of `Γ(a)` is the sign of `sinpi(a)` + return a == 1 ? one(T) : a > 1 ? zero(T) : copysign(T(Inf), sinpi(a)) + elseif isinf(x) + return zero(T) + end + + # The direct formula is the most accurate one if `exp(-x)` and `Γ(a)` are normal and finite + # and `x^(a - 1) = 2^((a - 1) * log2(x))` neither overflows nor underflows + # (`|a - 1| * |log2(x)| <= 171 * 5 < 1022` for `1/32 <= x <= 32`) + if T === BigFloat || (x < 708 && -170 < a < 171 && (1/32 <= x <= 32 || abs((a - 1) * log2(x)) < 1022)) + # `a - 1` is exact for `0.5 <= a <= 2^precision(a)` + y = a >= 0.5 ? x^(a - 1) : x^a / x + # Since `|Γ(a)| < 1` for `a < -2`, divide by `Γ(a)` first to avoid premature underflow, + # unless `exp(-x) > 1/e` for `x < 1`, where dividing first could overflow prematurely + return x < 1 ? exp(-x) * y / gamma(a) : y / gamma(a) * exp(-x) + elseif a >= -0.5 + # `rgammax` supports `a >= -0.5` + return rgammax(a, x) / x + else + lg, s = logabsgamma(a) + return s * exp(muladd(a - 1, log(x), -x) - lg) + end +end +_gamma_inc_dx(a::Float32, x::Float32) = Float32(_gamma_inc_dx(Float64(a), Float64(x))) +_gamma_inc_dx(a::Float16, x::Float16) = Float16(_gamma_inc_dx(Float64(a), Float64(x))) + function _gamma_inc_choose_algorithm(a::Float64, x::Float64, ind::Int) r = rgammax(a, x) if r == 0.0 @@ -1168,8 +1219,7 @@ but `loggamma(a,x)` may differ from `log(gamma(a,x))` by an integer multiple of See also [`loggamma(x)`](@ref). """ -loggamma(a::Number, x::Number) = _loggamma(promotereal(float(a), float(x))...) -loggamma(a::Integer, x::Number) = _loggamma(a, float(x)) +loggamma(a::Number, x::Number) = _loggamma(map(float, promotereal(a, x))...) function _loggamma(a::Number, x::Number) if a isa Real && x isa Real && !isfinite(a*x) if isinf(x) && isfinite(a) @@ -1186,11 +1236,31 @@ function _loggamma(a::Number, x::Number) end end end - # from gamma(a,x) = x^a * expintx(1-a, x) * exp(-x): iszero(x) && return loggamma(one(x)*a) - if x isa Real && x < 0 && a isa Integer && isodd(a) + if x isa Real && x < 0 && !(isinteger(a) && isodd(a)) + throw(DomainError((a, x), "loggamma will only return a complex result if called with a complex argument")) + end + return _loggamma(a, x, expintx(1 - a, x)) +end +# from gamma(a,x) = x^a * expintx(1-a, x) * exp(-x), with e = expintx(1-a, x): +function _loggamma(a::Number, x::Number, e::Number) + if x isa Real && x < 0 && isinteger(a) && isodd(a) # minus signs in expintx and x^a may cancel - return a*log(-x) + log(-expintx(1-a, x)) - x + return a*log(-x) + log(-e) - x + end + return a*log(x) + log(e) - x +end + +# Compute `loggamma(a, x)` and its derivative `-x^(a - 1) e^(-x) / Γ(a, x)` with respect to `x` +function _loggamma_and_dx(a::Number, x::Number) + a, x = map(float, promotereal(a, x)) + if isfinite(a) && isfinite(x) && !iszero(x) + e = expintx(1 - a, x) + Ω = _loggamma(a, x, e) + ∂Ω_∂x = -inv(x * e) + else + Ω = _loggamma(a, x) + ∂Ω_∂x = -exp(-(x + Ω)) * x^(a - 1) end - return a*log(x) + log(expintx(1 - a, x)) - x + return Ω, ∂Ω_∂x end diff --git a/test/chainrules.jl b/test/chainrules.jl index 1754d5914..915a7cfe3 100644 --- a/test/chainrules.jl +++ b/test/chainrules.jl @@ -138,6 +138,33 @@ end end + @testset "incomplete gamma functions: large arguments" begin + for (a, x) in ((150.0, 150.0), (1e6, 1e6)) + (p, q), (∂p, ∂q) = frule((NoTangent(), NoTangent(), 1.0, NoTangent()), gamma_inc, a, x, 0) + @test (p, q) == gamma_inc(a, x, 0) + @test ∂p == -∂q == SpecialFunctions.gamma_inc_dx(a, x) + Ω, pullback = rrule(gamma_inc, a, x, 0) + @test Ω == (p, q) + @test pullback(Tangent{typeof(Ω)}(2.0, 1.0))[3] == ∂p + end + test_frule(gamma_inc, 150.0, 150.0, 0) + test_rrule(gamma_inc, 150.0, 150.0, 0) + + # Γ(n, x) = (n - 1)! e^(-x) Σ_{k < n} x^k / k! + function ∂loggamma(n, x) + x = big(x) + return -(x^(n - 1) / factorial(big(n - 1))) / sum(x^k / factorial(big(k)) for k in 0:(n - 1)) + end + for (n, x) in ((2, 1e10), (30, 1e6), (5, 0.1)) + Ω, ∂Ω = frule((NoTangent(), NoTangent(), 1.0), loggamma, n, x) + @test Ω == loggamma(n, x) + @test ∂Ω ≈ ∂loggamma(n, x) rtol = 4 * eps() + Ω, pullback = rrule(loggamma, n, x) + @test Ω == loggamma(n, x) + @test pullback(1.0)[3] == ∂Ω + end + end + @testset "exponential integrals" begin for x in (1.5, 2.5, 10.5, 1.6 + 1.6im, 1.6 - 1.6im, -4.6 + 1.6im) test_scalar(expint, x) diff --git a/test/gamma_inc.jl b/test/gamma_inc.jl index 4ab1c30f6..0026910a7 100644 --- a/test/gamma_inc.jl +++ b/test/gamma_inc.jl @@ -307,6 +307,49 @@ end end end +@testset "derivative of incomplete gamma ratios" begin + gamma_inc_dx = SpecialFunctions.gamma_inc_dx + function ref(a, x) + setprecision(BigFloat, 512) do + lg, s = logabsgamma(big(a)) + return s * exp((big(a) - 1) * log(big(x)) - big(x) - lg) + end + end + + for T in (Float32, Float64), (a, x) in ( + (0.5, 1e-3), (0.5, 2.0), (2.5, 1.0), (150.0, 150.0), (200.0, 180.0), (150.5, 150.0), + (1e6, 1e6), (1e10, 1e10), (-0.3, 1.5), (-2.5, 1.5), (-100.5, 300.0), + ) + @test @inferred(gamma_inc_dx(T(a), T(x))) ≈ T(ref(T(a), T(x))) rtol = 4 * eps(T) + end + # Γ(a) underflows + @test gamma_inc_dx(-175.5, 20.0) ≈ ref(-175.5, 20.0) rtol = 1e-12 + # Γ(n) = (n - 1)! + @test gamma_inc_dx(big(150), big(150)) ≈ big(150)^149 * exp(-big(150)) / factorial(big(149)) rtol = 4 * eps(BigFloat) + @test gamma_inc_dx(Float16(2), Float16(3)) === Float16(3 * exp(-3)) + @test gamma_inc_dx(2, 3) === gamma_inc_dx(2.0, 3.0) + @test gamma_inc_dx(2.5, 1e5) === 0.0 + + for T in (Float32, Float64, BigFloat) + @test gamma_inc_dx(T(1), T(0)) == 1 + for a in (2, 1.5, 0, -1) + @test iszero(gamma_inc_dx(T(a), T(0))) + end + @test gamma_inc_dx(T(0.5), T(0)) == Inf + @test gamma_inc_dx(T(-0.5), T(0)) == -Inf + @test gamma_inc_dx(T(-1.5), T(0)) == Inf + @test iszero(gamma_inc_dx(T(2.5), T(Inf))) + @test isnan(gamma_inc_dx(T(NaN), T(1))) + @test isnan(gamma_inc_dx(T(1), T(NaN))) + @test_throws DomainError(T(-1), "`x` must be non-negative") gamma_inc_dx(T(2), T(-1)) + end + + # Consistency with `gamma_inc`: P(a, x) - P(a + 1, x) = x^a e^(-x) / Γ(a + 1) + for (a, x) in ((2.5, 1.0), (30.0, 25.0), (150.0, 150.0)) + @test gamma_inc(a, x)[1] - gamma_inc(a + 1, x)[1] ≈ gamma_inc_dx(a + 1, x) rtol = 1e-12 + end +end + double(x::Real) = Float64(x) double(x::Integer) = Int(x) double(x::Complex) = ComplexF64(x) @@ -361,7 +404,10 @@ end @test_throws DomainError loggamma(Inf, -3.2) @test loggamma(117.3, 0) == loggamma(117.3) @test loggamma(7, -300.2) ≅ log(gamma(7, -300.2)) + @test loggamma(7.0, -300.2) == loggamma(7, -300.2) @test_throws DomainError loggamma(6, -3.2) + @test loggamma(2, 3f0) isa Float32 + @test loggamma(2f0, 3) isa Float32 end # Run `f(args...)` twice and return only the result of the second call, so that diff --git a/test/qa.jl b/test/qa.jl index 6a38fc945..d03a8f40b 100644 --- a/test/qa.jl +++ b/test/qa.jl @@ -26,6 +26,7 @@ end # Ref https://github.com/JuliaTesting/ExplicitImports.jl/issues/92 :invπ, # SpecialFunctions :sqrtπ, # SpecialFunctions + (VERSION < v"1.11" ? (:gamma_inc_dx,) : ())..., # SpecialFunctions ), ) === nothing @@ -48,6 +49,7 @@ end :version, # Base.MPFR Symbol("@nif"), # Base (VERSION < v"1.11" ? (:depwarn,) : ())..., # Base + :_loggamma_and_dx, # SpecialFunctions (used by SpecialFunctionsChainRulesCoreExt) ), ) === nothing diff --git a/test/type_stability.jl b/test/type_stability.jl index e7acddbb3..63b5ab3a4 100644 --- a/test/type_stability.jl +++ b/test/type_stability.jl @@ -71,6 +71,7 @@ end @testset "incomplete gamma and beta ($T)" for T in (Float16, Float32, Float64) @test @inferred(gamma_inc(T(2), T(3), 0)) isa Tuple{T,T} + @test @inferred(SpecialFunctions.gamma_inc_dx(T(2), T(3))) isa T @test @inferred(gamma_inc_inv(T(2), T(1)/2, T(1)/2)) isa T @test @inferred(beta_inc(T(2), T(3), T(1)/2)) isa Tuple{T,T} @test @inferred(beta_inc_inv(T(2), T(3), T(1)/2)) isa Tuple{T,T} From 3fb753868beb9ef655817496e0575cc089bab32b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20M=C3=BCller-Widmann?= Date: Tue, 3 Nov 2026 16:01:38 +0100 Subject: [PATCH 2/6] Add ChainRules rule for gamma_inc_dx with derivatives in a and x Compute the a-derivative f * (log(x) - digamma(a)) without cancellation for large a by evaluating log(x) - digamma(a) as log(x/a) plus the asymptotic expansion of log(a) - digamma(a), which is factored out of digamma. At the poles of digamma(a), use the reflection formula, which is smooth in a so that nested derivatives are correct. Compute the x-derivative as f * (a - 1 - x) / x unless f underflows, and compute both derivatives in Float64 for Float16 and Float32 arguments. Co-Authored-By: Claude Opus 5.5 --- ext/SpecialFunctionsChainRulesCoreExt.jl | 4 ++ src/gamma.jl | 10 +++-- src/gamma_inc.jl | 45 ++++++++++++++++++++ test/chainrules.jl | 53 +++++++++++++++++++++++- test/gamma_inc.jl | 1 - test/qa.jl | 5 ++- test/runtests.jl | 2 +- test/type_stability.jl | 2 +- 8 files changed, 114 insertions(+), 8 deletions(-) diff --git a/ext/SpecialFunctionsChainRulesCoreExt.jl b/ext/SpecialFunctionsChainRulesCoreExt.jl index 8f108c9cd..b9f46ab3d 100644 --- a/ext/SpecialFunctionsChainRulesCoreExt.jl +++ b/ext/SpecialFunctionsChainRulesCoreExt.jl @@ -74,6 +74,10 @@ ChainRulesCore.@scalar_rule( ChainRulesCore.NoTangent(), ), ) +ChainRulesCore.@scalar_rule( + gamma_inc_dx(a, x), + (SpecialFunctions._gamma_inc_dx_da(a, x, Ω), SpecialFunctions._gamma_inc_dx_dx(a, x, Ω)), +) ChainRulesCore.@scalar_rule( invdigamma(x), inv(trigamma(invdigamma(x))), diff --git a/src/gamma.jl b/src/gamma.jl index e4c7fbb2a..4be1e9646 100644 --- a/src/gamma.jl +++ b/src/gamma.jl @@ -42,11 +42,15 @@ function _digamma(z::ComplexOrReal{Float64}) ψ -= inv(z) z += n end + ψ += log(z) - _log_minus_digamma_asymptotic(z) +end + +# Asymptotic expansion of `log(z) - digamma(z)` for large `z` +function _log_minus_digamma_asymptotic(z::ComplexOrReal{Float64}) t = inv(z) - ψ += log(z) - 0.5*t - t *= t # 1/z^2 + t2 = t * t # the coefficients here are Float64(bernoulli[2:9] .// (2*(1:8))) - ψ -= t * @evalpoly(t,0.08333333333333333,-0.008333333333333333,0.003968253968253968,-0.004166666666666667,0.007575757575757576,-0.021092796092796094,0.08333333333333333,-0.4432598039215686) + return muladd(t2, @evalpoly(t2,0.08333333333333333,-0.008333333333333333,0.003968253968253968,-0.004166666666666667,0.007575757575757576,-0.021092796092796094,0.08333333333333333,-0.4432598039215686), 0.5*t) end function _digamma(x::BigFloat) diff --git a/src/gamma_inc.jl b/src/gamma_inc.jl index 6e369798e..3417b7698 100644 --- a/src/gamma_inc.jl +++ b/src/gamma_inc.jl @@ -999,6 +999,51 @@ end _gamma_inc_dx(a::Float32, x::Float32) = Float32(_gamma_inc_dx(Float64(a), Float64(x))) _gamma_inc_dx(a::Float16, x::Float16) = Float16(_gamma_inc_dx(Float64(a), Float64(x))) +# Derivatives of `f = gamma_inc_dx(a, x)` with respect to `x` and `a` +# (used by the ChainRules rules and by ForwardDiff) +_gamma_inc_dx_dx(a::Real, x::Real, f::Real) = _gamma_inc_dx_dx(map(float, promote(a, x, f))...) +function _gamma_inc_dx_dx(a::T, x::T, f::T) where {T<:Real} + # ∂f/∂x = f * (a - 1 - x) / x = gamma_inc_dx(a - 1, x) - f + # The second form is only needed if `f` underflows but `∂f/∂x` might not (`x < (a - 1) / 2`, + # where it does not cancel), and at zero and infinity, where it is exact + if 0 < x < Inf && abs(f) >= floatmin(f) + return f * ((a - 1 - x) / x) + else + return gamma_inc_dx(a - 1, x) - f + end +end +_gamma_inc_dx_da(a::Real, x::Real, f::Real) = _gamma_inc_dx_da(map(float, promote(a, x, f))...) +function _gamma_inc_dx_da(a::T, x::T, f::T) where {T<:Real} + # ∂f/∂a = f * (log(x) - ψ(a)) + if isinteger(a) && a <= 0 && x < Inf + # At the poles of `ψ(a)`, where `f = 0`, use `ψ(a) = ψ(1 - a) - π cot(πa)` and `Γ(a) Γ(1 - a) = π / sin(πa)` + lx = log(x) + return muladd(f, lx - digamma(1 - a), cospi(a) * exp(muladd(a - 1, lx, loggamma(1 - a) - x))) + elseif iszero(f) + return f + else + return f * _log_minus_digamma(x, a) + end +end +for g in (:_gamma_inc_dx_dx, :_gamma_inc_dx_da) + @eval $g(a::T, x::T, f::T) where {T<:Union{Float16,Float32}} = T($g(Float64(a), Float64(x), Float64(f))) +end + +# Compute `log(x) - digamma(a)`, avoiding cancellation for large `a` and `x ≈ a` +_log_minus_digamma(x::Real, a::Real) = log(x) - digamma(a) +function _log_minus_digamma(x::Float64, a::Float64) + a < 10 && return log(x) - digamma(a) + # `x - a` is exact for `a <= 2x <= 4a`, and `log(x) - log(a)` does not cancel for `x < 1` + l = if 2x >= a + log1p((x - a) / a) + elseif x < 1 + log(x) - log(a) + else + log(x / a) + end + return l + _log_minus_digamma_asymptotic(a) +end + function _gamma_inc_choose_algorithm(a::Float64, x::Float64, ind::Int) r = rgammax(a, x) if r == 0.0 diff --git a/test/chainrules.jl b/test/chainrules.jl index 915a7cfe3..ba6325fff 100644 --- a/test/chainrules.jl +++ b/test/chainrules.jl @@ -142,7 +142,7 @@ for (a, x) in ((150.0, 150.0), (1e6, 1e6)) (p, q), (∂p, ∂q) = frule((NoTangent(), NoTangent(), 1.0, NoTangent()), gamma_inc, a, x, 0) @test (p, q) == gamma_inc(a, x, 0) - @test ∂p == -∂q == SpecialFunctions.gamma_inc_dx(a, x) + @test ∂p == -∂q == gamma_inc_dx(a, x) Ω, pullback = rrule(gamma_inc, a, x, 0) @test Ω == (p, q) @test pullback(Tangent{typeof(Ω)}(2.0, 1.0))[3] == ∂p @@ -165,6 +165,57 @@ end end + @testset "gamma_inc_dx" begin + # includes the poles of `digamma(a)` at `a = 0, -2` + for (a, x) in ((2.5, 1.0), (0.3, 2.0), (-2.5, 1.5), (-2.0, 1.5), (0.0, 1.5), (30.0, 25.0), (150.0, 10.0)) + test_frule(gamma_inc_dx, a, x) + test_rrule(gamma_inc_dx, a, x) + end + + function partials(a, x) + Ω, pullback = rrule(gamma_inc_dx, a, x) + _, ∂a, ∂x = pullback(one(Ω)) + return Ω, ∂a, ∂x + end + # f = x^(a - 1) e^(-x) / Γ(a), ∂f/∂a = f * (log(x) - ψ(a)), ∂f/∂x = f * (a - 1 - x) / x + function partials_ref(a, x) + setprecision(BigFloat, 512) do + a, x = big(a), big(x) + # 1 / Γ(a) = sin(πa) Γ(1 - a) / π + e = exp((a - 1) * log(x) - x) + f = a > 0 ? e / gamma(a) : e * sinpi(a) * gamma(1 - a) / big(π) + ∂a = isinteger(a) && a <= 0 ? cospi(a) * e * gamma(1 - a) : f * (log(x) - digamma(a)) + return f, ∂a, f * (a - 1 - x) / x + end + end + for T in (Float32, Float64), (a, x) in ( + (2.5, 1.0), (12.0, 11.5), (150.0, 150.0), (150.0, 149.5), (1e6, 1e6), (1e6, 999_000.0), (1e10, 1e10), + (0.0, 1.5), (-2.0, 1.5), + ) + Ω, ∂a, ∂x = partials(T(a), T(x)) + _, ∂a_ref, ∂x_ref = partials_ref(T(a), T(x)) + @test Ω === gamma_inc_dx(T(a), T(x)) + @test ∂a isa T + @test ∂a ≈ T(∂a_ref) rtol = 8 * eps(T) + @test ∂x isa T + @test ∂x ≈ T(∂x_ref) rtol = 8 * eps(T) + end + for (a, x) in ((2.5, 1.0), (0.0, 1.5), (-2.0, 1.5)) + Ω, ∂a, ∂x = partials(big(a), big(x)) + _, ∂a_ref, ∂x_ref = partials_ref(a, x) + @test ∂a ≈ ∂a_ref rtol = 8 * eps(BigFloat) + @test ∂x ≈ ∂x_ref rtol = 8 * eps(BigFloat) + end + @test all(p -> p isa Float16, partials(Float16(2.5), Float16(1))) + + # `f` underflows + @test partials(3.0, 1e-160)[3] ≈ 1e-160 rtol = 4 * eps() + for T in (Float32, Float64) + @test partials(T(2), T(0)) === (T(0), T(0), T(1)) + @test partials(T(2.5), T(Inf)) === (T(0), T(0), T(0)) + end + end + @testset "exponential integrals" begin for x in (1.5, 2.5, 10.5, 1.6 + 1.6im, 1.6 - 1.6im, -4.6 + 1.6im) test_scalar(expint, x) diff --git a/test/gamma_inc.jl b/test/gamma_inc.jl index 0026910a7..e8f4de54f 100644 --- a/test/gamma_inc.jl +++ b/test/gamma_inc.jl @@ -308,7 +308,6 @@ end end @testset "derivative of incomplete gamma ratios" begin - gamma_inc_dx = SpecialFunctions.gamma_inc_dx function ref(a, x) setprecision(BigFloat, 512) do lg, s = logabsgamma(big(a)) diff --git a/test/qa.jl b/test/qa.jl index d03a8f40b..3400e05c6 100644 --- a/test/qa.jl +++ b/test/qa.jl @@ -49,7 +49,10 @@ end :version, # Base.MPFR Symbol("@nif"), # Base (VERSION < v"1.11" ? (:depwarn,) : ())..., # Base - :_loggamma_and_dx, # SpecialFunctions (used by SpecialFunctionsChainRulesCoreExt) + # SpecialFunctions (used by SpecialFunctionsChainRulesCoreExt) + :_gamma_inc_dx_da, + :_gamma_inc_dx_dx, + :_loggamma_and_dx, ), ) === nothing diff --git a/test/runtests.jl b/test/runtests.jl index 61c0c25f2..a319c3be3 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -11,7 +11,7 @@ using Aqua: Aqua using ExplicitImports: ExplicitImports using JET: JET -using SpecialFunctions: AmosException, f64, _loggamma_oracle64_point +using SpecialFunctions: AmosException, f64, _loggamma_oracle64_point, gamma_inc_dx # useful test functions for relative error, which differ from isapprox # relerr separately looks at the real and imaginary parts if one of the arguments is complex diff --git a/test/type_stability.jl b/test/type_stability.jl index 63b5ab3a4..45ceaf554 100644 --- a/test/type_stability.jl +++ b/test/type_stability.jl @@ -71,7 +71,7 @@ end @testset "incomplete gamma and beta ($T)" for T in (Float16, Float32, Float64) @test @inferred(gamma_inc(T(2), T(3), 0)) isa Tuple{T,T} - @test @inferred(SpecialFunctions.gamma_inc_dx(T(2), T(3))) isa T + @test @inferred(gamma_inc_dx(T(2), T(3))) isa T @test @inferred(gamma_inc_inv(T(2), T(1)/2, T(1)/2)) isa T @test @inferred(beta_inc(T(2), T(3), T(1)/2)) isa Tuple{T,T} @test @inferred(beta_inc_inv(T(2), T(3), T(1)/2)) isa Tuple{T,T} From 558904f9ce14a36c284bcfa714e2c814bd0ffea2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20M=C3=BCller-Widmann?= Date: Tue, 3 Nov 2026 22:54:01 +0100 Subject: [PATCH 3/6] Avoid cancellation in `log(x) - digamma(a)` for non-Float64 types Use the asymptotic expansion of `log(a) - digamma(a)` for all real types, with a precision-dependent threshold, so that the derivatives of `gamma_inc_dx` with respect to `a` are accurate for, e.g., ForwardDiff duals. Co-Authored-By: Claude Opus 5.5 --- src/gamma.jl | 7 ++++--- src/gamma_inc.jl | 6 +++--- test/chainrules.jl | 2 +- 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/src/gamma.jl b/src/gamma.jl index 4be1e9646..5b85f9f74 100644 --- a/src/gamma.jl +++ b/src/gamma.jl @@ -46,11 +46,12 @@ function _digamma(z::ComplexOrReal{Float64}) end # Asymptotic expansion of `log(z) - digamma(z)` for large `z` -function _log_minus_digamma_asymptotic(z::ComplexOrReal{Float64}) +function _log_minus_digamma_asymptotic(z::Number) t = inv(z) t2 = t * t - # the coefficients here are Float64(bernoulli[2:9] .// (2*(1:8))) - return muladd(t2, @evalpoly(t2,0.08333333333333333,-0.008333333333333333,0.003968253968253968,-0.004166666666666667,0.007575757575757576,-0.021092796092796094,0.08333333333333333,-0.4432598039215686), 0.5*t) + T = real(typeof(t2)) + # the coefficients here are bernoulli[2:9] .// (2*(1:8)) + return muladd(t2, @evalpoly(t2, T(1//12), T(-1//120), T(1//252), T(-1//240), T(1//132), T(-691//32760), T(1//12), T(-3617//8160)), t / 2) end function _digamma(x::BigFloat) diff --git a/src/gamma_inc.jl b/src/gamma_inc.jl index 3417b7698..410d02a6f 100644 --- a/src/gamma_inc.jl +++ b/src/gamma_inc.jl @@ -1030,9 +1030,9 @@ for g in (:_gamma_inc_dx_dx, :_gamma_inc_dx_da) end # Compute `log(x) - digamma(a)`, avoiding cancellation for large `a` and `x ≈ a` -_log_minus_digamma(x::Real, a::Real) = log(x) - digamma(a) -function _log_minus_digamma(x::Float64, a::Float64) - a < 10 && return log(x) - digamma(a) +function _log_minus_digamma(x::T, a::T) where {T<:Real} + # the remainder of the asymptotic expansion relative to `1 / (2a)` is ≈ 6 / a¹⁷ + a < max(10, (6 / eps(T))^(1 / 17)) && return log(x) - digamma(a) # `x - a` is exact for `a <= 2x <= 4a`, and `log(x) - log(a)` does not cancel for `x < 1` l = if 2x >= a log1p((x - a) / a) diff --git a/test/chainrules.jl b/test/chainrules.jl index ba6325fff..124437db1 100644 --- a/test/chainrules.jl +++ b/test/chainrules.jl @@ -200,7 +200,7 @@ @test ∂x isa T @test ∂x ≈ T(∂x_ref) rtol = 8 * eps(T) end - for (a, x) in ((2.5, 1.0), (0.0, 1.5), (-2.0, 1.5)) + for (a, x) in ((2.5, 1.0), (0.0, 1.5), (-2.0, 1.5), (1e6, 1e6)) Ω, ∂a, ∂x = partials(big(a), big(x)) _, ∂a_ref, ∂x_ref = partials_ref(a, x) @test ∂a ≈ ∂a_ref rtol = 8 * eps(BigFloat) From 9e08f1debb0f5fc6ad6a6f849c680c62276fd081 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20M=C3=BCller-Widmann?= Date: Tue, 3 Nov 2026 23:26:56 +0100 Subject: [PATCH 4/6] Compute the test reference for `gamma_inc_dx` in log space `exp((a - 1) * log(x) - x)` overflows the exponent range of MPFR on Windows for `a = x = 1e10`, which made the reference NaN. Co-Authored-By: Claude Opus 5.5 --- test/chainrules.jl | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/test/chainrules.jl b/test/chainrules.jl index 124437db1..ffdc6b7de 100644 --- a/test/chainrules.jl +++ b/test/chainrules.jl @@ -182,8 +182,9 @@ setprecision(BigFloat, 512) do a, x = big(a), big(x) # 1 / Γ(a) = sin(πa) Γ(1 - a) / π - e = exp((a - 1) * log(x) - x) - f = a > 0 ? e / gamma(a) : e * sinpi(a) * gamma(1 - a) / big(π) + l = (a - 1) * log(x) - x + e = exp(l) + f = a > 0 ? exp(l - loggamma(a)) : e * sinpi(a) * gamma(1 - a) / big(π) ∂a = isinteger(a) && a <= 0 ? cospi(a) * e * gamma(1 - a) : f * (log(x) - digamma(a)) return f, ∂a, f * (a - 1 - x) / x end From 6cd1386ee7dad895d1be1e52b42402d2014c4ea8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20M=C3=BCller-Widmann?= Date: Tue, 3 Nov 2026 23:46:56 +0100 Subject: [PATCH 5/6] Test remaining branches of `_log_minus_digamma` and `_loggamma_and_dx` Co-Authored-By: Claude Opus 5.5 --- test/chainrules.jl | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/test/chainrules.jl b/test/chainrules.jl index ffdc6b7de..ab6d4ccc5 100644 --- a/test/chainrules.jl +++ b/test/chainrules.jl @@ -163,6 +163,9 @@ @test Ω == loggamma(n, x) @test pullback(1.0)[3] == ∂Ω end + for (a, ∂Ω_ref) in ((0.5, -Inf), (1.0, -1.0), (2.5, 0.0)) + @test frule((NoTangent(), NoTangent(), 1.0), loggamma, a, 0.0)[2] == ∂Ω_ref + end end @testset "gamma_inc_dx" begin @@ -190,7 +193,7 @@ end end for T in (Float32, Float64), (a, x) in ( - (2.5, 1.0), (12.0, 11.5), (150.0, 150.0), (150.0, 149.5), (1e6, 1e6), (1e6, 999_000.0), (1e10, 1e10), + (2.5, 1.0), (12.0, 11.5), (12.0, 0.5), (150.0, 150.0), (150.0, 149.5), (1e6, 1e6), (1e6, 999_000.0), (1e10, 1e10), (0.0, 1.5), (-2.0, 1.5), ) Ω, ∂a, ∂x = partials(T(a), T(x)) From 971dd1a28b08b67082881c8c4684e44d88377fe6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20M=C3=BCller-Widmann?= Date: Tue, 3 Nov 2026 23:55:02 +0100 Subject: [PATCH 6/6] Run the `min-patch` job on Ubuntu 24.04 Julia < 1.10.9 fails to load on glibc >= 2.41 (https://github.com/JuliaLang/julia/issues/57250). Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 653190bf8..51e9051ff 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -22,6 +22,13 @@ jobs: - ubuntu-latest - macOS-latest - windows-latest + exclude: + # Julia < 1.10.9 fails to load on glibc >= 2.41: https://github.com/JuliaLang/julia/issues/57250 + - version: 'min-patch' + os: ubuntu-latest + include: + - version: 'min-patch' + os: ubuntu-24.04 steps: - uses: actions/checkout@v7 - uses: julia-actions/setup-julia@v3