Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion Project.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
1 change: 1 addition & 0 deletions docs/src/functions_list.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ invdigamma
trigamma
polygamma
gamma_inc
gamma_inc_dx
gamma_inc_inv
loggammadiv
gammax
Expand Down
1 change: 1 addition & 0 deletions docs/src/functions_overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
Expand Down
31 changes: 22 additions & 9 deletions ext/SpecialFunctionsChainRulesCoreExt.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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,
Expand All @@ -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))),
Expand Down Expand Up @@ -172,13 +176,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)
Expand Down
4 changes: 4 additions & 0 deletions src/SpecialFunctions.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down
13 changes: 9 additions & 4 deletions src/gamma.jl
Original file line number Diff line number Diff line change
Expand Up @@ -42,11 +42,16 @@ 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::Number)
t = inv(z)
ψ += log(z) - 0.5*t
t *= t # 1/z^2
# 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)
t2 = t * 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)
Expand Down
127 changes: 121 additions & 6 deletions src/gamma_inc.jl
Original file line number Diff line number Diff line change
Expand Up @@ -948,6 +948,102 @@ 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)))

# 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`
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)
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
Expand Down Expand Up @@ -1168,8 +1264,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)
Expand All @@ -1186,11 +1281,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
82 changes: 82 additions & 0 deletions test/chainrules.jl
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,88 @@
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 == 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
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
# 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) / π
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
end
for T in (Float32, Float64), (a, x) in (
(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))
_, ∂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), (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)
@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)
Expand Down
Loading
Loading