API Reference¶

Public API¶

specialfunctions — SciPy-backed special mathematical functions.

All public symbols are re-exported from specialfunctions.core so callers can simply write:

from specialfunctions import gamma, bessel_j0, erf

This package is a self-contained set of special function utilities inspired by IMSL Fortran Numerical Library Special Functions chapter, backed by scipy.special.

specialfunctions.gamma(x)¶

Compute the Gamma function Γ(x).

Uses scipy.special.gamma(). The function has poles at non-positive integers; passing such a value raises ValueError.

Parameters:: x (float | array_like) – Argument(s). Must not be zero or a negative integer.
Returns:: Γ(x).
Return type:: float | ndarray
Raises:: ValueError – If any element of x is a non-positive integer (0, -1, -2, …).

specialfunctions.log_gamma(x)¶

Compute the natural logarithm of the absolute value of Γ(x).

Uses scipy.special.gammaln().

Parameters:: x (float | array_like) – Argument(s). Non-positive integers are poles of the gamma function; the log of a pole is +∞.
Returns:: ln|Γ(x)|.
Return type:: float | ndarray

specialfunctions.digamma(x)¶

Compute the digamma function ψ(x) = d/dx ln Γ(x).

Uses scipy.special.digamma().

Parameters:: x (float | array_like) – Argument(s).
Returns:: ψ(x).
Return type:: float | ndarray

specialfunctions.polygamma(n, x)¶

Compute the polygamma function ψ^(n)(x) = d^(n+1)/dx^(n+1) ln Γ(x).

Uses scipy.special.polygamma().

Parameters:

n (int) – Order of the derivative (n ≥ 0).
x (float | array_like) – Argument(s).

Returns:

ψ^(n)(x).

Return type:

float | ndarray

Raises:

ValueError – If n is negative.

specialfunctions.beta(a, b)¶

Compute the beta function B(a, b) = Γ(a)Γ(b)/Γ(a+b).

Uses scipy.special.beta().

Parameters:

a (float | array_like) – First parameter. Must be positive.
b (float | array_like) – Second parameter. Must be positive.

Returns:

B(a, b).

Return type:

float | ndarray

Raises:

ValueError – If any element of a or b is ≤ 0.

specialfunctions.log_beta(a, b)¶

Compute the natural log of the beta function ln B(a, b).

Uses scipy.special.betaln().

Parameters:

a (float | array_like) – First parameter. Must be positive.
b (float | array_like) – Second parameter. Must be positive.

Returns:

ln B(a, b).

Return type:

float | ndarray

specialfunctions.incomplete_gamma(a, x)¶

Compute the regularised lower incomplete gamma function P(a, x).

P(a, x) = γ(a, x) / Γ(a), where γ is the lower incomplete gamma function. Uses scipy.special.gammainc().

Parameters:

a (float | array_like) – Shape parameter. Must be positive.
x (float | array_like) – Upper limit of integration. Must be ≥ 0.

Returns:

P(a, x) ∈ [0, 1].

Return type:

float | ndarray

specialfunctions.incomplete_gamma_upper(a, x)¶

Compute the regularised upper incomplete gamma function Q(a, x).

Q(a, x) = Γ(a, x) / Γ(a) = 1 − P(a, x). Uses scipy.special.gammaincc().

Parameters:

a (float | array_like) – Shape parameter. Must be positive.
x (float | array_like) – Lower limit of integration. Must be ≥ 0.

Returns:

Q(a, x) ∈ [0, 1].

Return type:

float | ndarray

specialfunctions.incomplete_beta(a, b, x)¶

Compute the regularised incomplete beta function I_x(a, b).

Uses scipy.special.betainc().

Parameters:

a (float | array_like) – First shape parameter. Must be positive.
b (float | array_like) – Second shape parameter. Must be positive.
x (float | array_like) – Upper limit. Must be in [0, 1].

Returns:

I_x(a, b) ∈ [0, 1].

Return type:

float | ndarray

Raises:

ValueError – If any element of x is outside [0, 1].

specialfunctions.factorial(n)¶

Compute the factorial n! using scipy.special.factorial().

Parameters:: n (int | array_like) – Non-negative integer(s).
Returns:: n!
Return type:: float | ndarray

specialfunctions.bessel_j0(x)¶

Compute the Bessel function of the first kind of order 0, J₀(x).

Uses scipy.special.j0().

Parameters:: x (float | array_like) – Argument(s).
Returns:: J₀(x).
Return type:: float | ndarray

specialfunctions.bessel_j1(x)¶

Compute the Bessel function of the first kind of order 1, J₁(x).

Uses scipy.special.j1().

Parameters:: x (float | array_like) – Argument(s).
Returns:: J₁(x).
Return type:: float | ndarray

specialfunctions.bessel_jn(n, x)¶

Compute the Bessel function of the first kind of integer order n, Jₙ(x).

Uses scipy.special.jn().

Parameters:

n (int) – Order of the Bessel function.
x (float | array_like) – Argument(s).

Returns:

Jₙ(x).

Return type:

float | ndarray

specialfunctions.bessel_y0(x)¶

Compute the Bessel function of the second kind of order 0, Y₀(x).

Uses scipy.special.y0(). Y₀ is only real for x > 0.

Parameters:: x (float | array_like) – Argument(s). Must be positive.
Returns:: Y₀(x).
Return type:: float | ndarray
Raises:: ValueError – If any element of x is ≤ 0.

specialfunctions.bessel_y1(x)¶

Compute the Bessel function of the second kind of order 1, Y₁(x).

Uses scipy.special.y1(). Y₁ is only real for x > 0.

Parameters:: x (float | array_like) – Argument(s). Must be positive.
Returns:: Y₁(x).
Return type:: float | ndarray
Raises:: ValueError – If any element of x is ≤ 0.

specialfunctions.bessel_yn(n, x)¶

Compute the Bessel function of the second kind of integer order n, Yₙ(x).

Uses scipy.special.yn(). Yₙ is only real for x > 0.

Parameters:

n (int) – Order of the Bessel function.
x (float | array_like) – Argument(s). Must be positive.

Returns:

Yₙ(x).

Return type:

float | ndarray

Raises:

ValueError – If any element of x is ≤ 0.

specialfunctions.bessel_i0(x)¶

Compute the modified Bessel function of the first kind of order 0, I₀(x).

Uses scipy.special.i0().

Parameters:: x (float | array_like) – Argument(s).
Returns:: I₀(x).
Return type:: float | ndarray

specialfunctions.bessel_i1(x)¶

Compute the modified Bessel function of the first kind of order 1, I₁(x).

Uses scipy.special.i1().

Parameters:: x (float | array_like) – Argument(s).
Returns:: I₁(x).
Return type:: float | ndarray

specialfunctions.bessel_in(n, x)¶

Compute the modified Bessel function of the first kind of real order n, Iₙ(x).

Uses scipy.special.iv().

Parameters:

n (float) – Order of the Bessel function.
x (float | array_like) – Argument(s).

Returns:

Iₙ(x).

Return type:

float | ndarray

specialfunctions.bessel_k0(x)¶

Compute the modified Bessel function of the second kind of order 0, K₀(x).

Uses scipy.special.k0(). K₀ requires x > 0.

Parameters:: x (float | array_like) – Argument(s). Must be positive.
Returns:: K₀(x).
Return type:: float | ndarray
Raises:: ValueError – If any element of x is ≤ 0.

specialfunctions.bessel_k1(x)¶

Compute the modified Bessel function of the second kind of order 1, K₁(x).

Uses scipy.special.k1(). K₁ requires x > 0.

Parameters:: x (float | array_like) – Argument(s). Must be positive.
Returns:: K₁(x).
Return type:: float | ndarray
Raises:: ValueError – If any element of x is ≤ 0.

specialfunctions.bessel_kn(n, x)¶

Compute the modified Bessel function of the second kind of real order n, Kₙ(x).

Uses scipy.special.kv(). Kₙ requires x > 0.

Parameters:

n (float) – Order of the Bessel function.
x (float | array_like) – Argument(s). Must be positive.

Returns:

Kₙ(x).

Return type:

float | ndarray

Raises:

ValueError – If any element of x is ≤ 0.

specialfunctions.erf(x)¶

Compute the error function erf(x) = (2/√π) ∫₀ˣ exp(−t²) dt.

Uses scipy.special.erf().

Parameters:: x (float | array_like) – Argument(s).
Returns:: erf(x) ∈ [−1, 1].
Return type:: float | ndarray

specialfunctions.erfc(x)¶

Compute the complementary error function erfc(x) = 1 − erf(x).

Uses scipy.special.erfc().

Parameters:: x (float | array_like) – Argument(s).
Returns:: erfc(x) ∈ [0, 2].
Return type:: float | ndarray

specialfunctions.erfinv(x)¶

Compute the inverse error function erfinv(x) such that erf(erfinv(x)) = x.

Uses scipy.special.erfinv(). Defined for x ∈ (−1, 1).

Parameters:: x (float | array_like) – Argument(s). Must satisfy abs(x) < 1.
Returns:: erfinv(x).
Return type:: float | ndarray
Raises:: ValueError – If any element of x satisfies abs(x) >= 1.

specialfunctions.erfcinv(x)¶

Compute the inverse complementary error function erfcinv(x).

erfcinv(x) satisfies erfc(erfcinv(x)) = x. Uses scipy.special.erfcinv(). Defined for x ∈ (0, 2).

Parameters:: x (float | array_like) – Argument(s). Must satisfy 0 < x < 2.
Returns:: erfcinv(x).
Return type:: float | ndarray
Raises:: ValueError – If any element of x is ≤ 0 or ≥ 2.

specialfunctions.fresnel_s(x)¶

Compute the Fresnel sine integral S(x) = ∫₀ˣ sin(πt²/2) dt.

Uses scipy.special.fresnel().

Parameters:: x (float | array_like) – Argument(s).
Returns:: S(x).
Return type:: float | ndarray

specialfunctions.fresnel_c(x)¶

Compute the Fresnel cosine integral C(x) = ∫₀ˣ cos(πt²/2) dt.

Uses scipy.special.fresnel().

Parameters:: x (float | array_like) – Argument(s).
Returns:: C(x).
Return type:: float | ndarray

specialfunctions.ellipk(k)¶

Compute the complete elliptic integral of the first kind K(k).

K(k) = ∫₀^(π/2) 1/√(1 − k sin²θ) dθ. Uses scipy.special.ellipk().

Parameters:: k (float | array_like) – Modulus parameter. Must satisfy 0 ≤ k < 1.
Returns:: K(k).
Return type:: float | ndarray
Raises:: ValueError – If any element of k is < 0 or ≥ 1.

specialfunctions.ellipe(k)¶

Compute the complete elliptic integral of the second kind E(k).

E(k) = ∫₀^(π/2) √(1 − k sin²θ) dθ. Uses scipy.special.ellipe().

Parameters:: k (float | array_like) – Modulus parameter. Must satisfy 0 ≤ k ≤ 1.
Returns:: E(k).
Return type:: float | ndarray
Raises:: ValueError – If any element of k is < 0 or > 1.

specialfunctions.ellipkinc(phi, k)¶

Compute the incomplete elliptic integral of the first kind F(φ, k).

F(φ, k) = ∫₀^φ 1/√(1 − k sin²θ) dθ. Uses scipy.special.ellipkinc().

Parameters:

phi (float | array_like) – Amplitude angle in radians.
k (float | array_like) – Modulus parameter. Must satisfy 0 ≤ k ≤ 1.

Returns:

F(φ, k).

Return type:

float | ndarray

specialfunctions.ellipeinc(phi, k)¶

Compute the incomplete elliptic integral of the second kind E(φ, k).

E(φ, k) = ∫₀^φ √(1 − k sin²θ) dθ. Uses scipy.special.ellipeinc().

Parameters:

phi (float | array_like) – Amplitude angle in radians.
k (float | array_like) – Modulus parameter. Must satisfy 0 ≤ k ≤ 1.

Returns:

E(φ, k).

Return type:

float | ndarray

specialfunctions.legendre_poly(n, x)¶

Evaluate the Legendre polynomial Pₙ(x) of degree n.

Uses scipy.special.legendre() to obtain the polynomial object and evaluates it at x.

Parameters:

n (int) – Degree of the polynomial (n ≥ 0).
x (float | array_like) – Evaluation point(s), typically in [−1, 1].

Returns:

Pₙ(x).

Return type:

float | ndarray

specialfunctions.chebyshev_t(n, x)¶

Evaluate the Chebyshev polynomial of the first kind Tₙ(x).

Uses scipy.special.eval_chebyt().

Parameters:

n (int) – Degree of the polynomial (n ≥ 0).
x (float | array_like) – Evaluation point(s).

Returns:

Tₙ(x).

Return type:

float | ndarray

specialfunctions.chebyshev_u(n, x)¶

Evaluate the Chebyshev polynomial of the second kind Uₙ(x).

Uses scipy.special.eval_chebyu().

Parameters:

n (int) – Degree of the polynomial (n ≥ 0).
x (float | array_like) – Evaluation point(s).

Returns:

Uₙ(x).

Return type:

float | ndarray

specialfunctions.hermite_poly(n, x)¶

Evaluate the probabilist’s Hermite polynomial Heₙ(x).

Uses scipy.special.eval_hermitenorm().

Parameters:

n (int) – Degree of the polynomial (n ≥ 0).
x (float | array_like) – Evaluation point(s).

Returns:

Heₙ(x).

Return type:

float | ndarray

specialfunctions.laguerre_poly(n, x)¶

Evaluate the Laguerre polynomial Lₙ(x).

Uses scipy.special.eval_laguerre().

Parameters:

n (int) – Degree of the polynomial (n ≥ 0).
x (float | array_like) – Evaluation point(s).

Returns:

Lₙ(x).

Return type:

float | ndarray

specialfunctions.jacobi_poly(n, a, b, x)¶

Evaluate the Jacobi polynomial Pₙ^(a,b)(x).

Uses scipy.special.eval_jacobi().

Parameters:

n (int) – Degree of the polynomial (n ≥ 0).
a (float) – First shape parameter (a > −1).
b (float) – Second shape parameter (b > −1).
x (float | array_like) – Evaluation point(s).

Returns:

Pₙ^(a,b)(x).

Return type:

float | ndarray

specialfunctions.expint(n, x)¶

Compute the generalised exponential integral Eₙ(x).

Eₙ(x) = ∫₁^∞ exp(−xt) / tⁿ dt. Uses scipy.special.expn().

Parameters:

n (int) – Order of the integral (n ≥ 0).
x (float | array_like) – Argument(s). Must be ≥ 0.

Returns:

Eₙ(x).

Return type:

float | ndarray

Raises:

ValueError – If any element of x is < 0 or n < 0.

specialfunctions.ei(x)¶

Compute the exponential integral Ei(x) = P.V. ∫₋∞^x exp(t)/t dt.

Uses scipy.special.expi().

Parameters:: x (float | array_like) – Argument(s).
Returns:: Ei(x).
Return type:: float | ndarray

specialfunctions.e1(x)¶

Compute the exponential integral E₁(x) = ∫_x^∞ exp(−t)/t dt.

Uses scipy.special.exp1(). Defined for x > 0.

Parameters:: x (float | array_like) – Argument(s). Must be positive.
Returns:: E₁(x).
Return type:: float | ndarray
Raises:: ValueError – If any element of x is ≤ 0.

specialfunctions.si(x)¶

Compute the sine integral Si(x) = ∫₀ˣ sin(t)/t dt.

Uses scipy.special.sici().

Parameters:: x (float | array_like) – Argument(s).
Returns:: Si(x).
Return type:: float | ndarray

specialfunctions.ci(x)¶

Compute the cosine integral Ci(x) = γ + ln x + ∫₀ˣ (cos t − 1)/t dt.

Uses scipy.special.sici(). The cosine integral is real only for x > 0.

Parameters:: x (float | array_like) – Argument(s). Must be positive.
Returns:: Ci(x).
Return type:: float | ndarray
Raises:: ValueError – If any element of x is ≤ 0.

specialfunctions.airy_ai(x)¶

Compute the Airy function Ai(x).

Uses scipy.special.airy().

Parameters:: x (float | array_like) – Argument(s).
Returns:: Ai(x).
Return type:: float | ndarray

specialfunctions.airy_bi(x)¶

Compute the Airy function Bi(x).

Uses scipy.special.airy().

Parameters:: x (float | array_like) – Argument(s).
Returns:: Bi(x).
Return type:: float | ndarray

specialfunctions.airy_ai_prime(x)¶

Compute the derivative of the Airy function Ai’(x).

Uses scipy.special.airy().

Parameters:: x (float | array_like) – Argument(s).
Returns:: Ai’(x).
Return type:: float | ndarray

specialfunctions.airy_bi_prime(x)¶

Compute the derivative of the Airy function Bi’(x).

Uses scipy.special.airy().

Parameters:: x (float | array_like) – Argument(s).
Returns:: Bi’(x).
Return type:: float | ndarray

specialfunctions.riemann_zeta(s)¶

Compute the Riemann zeta function ζ(s).

ζ(s) = Σₙ₌₁^∞ 1/nˢ, convergent for s > 1. Uses scipy.special.zeta() with a=1.

Parameters:: s (float | array_like) – Argument(s). Must be > 1.
Returns:: ζ(s).
Return type:: float | ndarray
Raises:: ValueError – If any element of s is ≤ 1.

specialfunctions.hurwitz_zeta(s, a)¶

Compute the Hurwitz zeta function ζ(s, a) = Σₙ₌₀^∞ 1/(n+a)ˢ.

Uses scipy.special.zeta().

Parameters:

s (float | array_like) – Exponent parameter. Must be > 1.
a (float | array_like) – Offset parameter. Must be positive.

Returns:

ζ(s, a).

Return type:

float | ndarray

specialfunctions.comb(n, k)¶

Compute the binomial coefficient C(n, k) = n! / (k! (n-k)!).

Uses scipy.special.comb() with exact=True.

Parameters:

n (int) – Total number of items.
k (int) – Number of items to choose.

Returns:

C(n, k).

Return type:

int

specialfunctions.launch_documentation(opener=<function open>, package_dir=None)¶

Open the local specialfunctions HTML documentation in a web browser.

Parameters:

opener (Callable) – Callable used to open the URL. Defaults to webbrowser.open(). Useful for testing.
package_dir (Path | None) – Override for the package root directory. When None the directory containing this file is used.

Returns:

The file:// URI that was opened.

Return type:

str

Raises:

FileNotFoundError – If no built HTML documentation is found under the expected locations.