Module ferrers 

Real-degree Ferrers functions of the first kind with integer order.

Upstream: treams.special.lpmv at a non-integer degree and a real argument, which calls scipy’s lpmv.

ferrers_real_degree evaluates P_ν^m(x) and dP_ν^m/dx for a non-integer degree 0 < ν < 128, an integer order |m| <= 130 and -1 < x <= 1, with the conventions of NIST DLMF §14.3 (Ferrers functions “on the cut”, Condon–Shortley phase included for m > 0). It implements the DLMF formulas cited below.

Method

Write μ = |m|, n = ⌊ν⌋, f = ν - n, y = |x|, w = 1 - y² = sin²θ and t = s = (1 - y)/2. The functions are computed for the order -μ; positive orders follow from DLMF 14.9.3, P_ν^μ = (-1)^μ Γ(ν+μ+1)/Γ(ν-μ+1) P_ν^{-μ}, with the gamma ratio formed as ∏_{i=1}^{μ} (ν(ν + 1) - i(i - 1)) from an exactly split ν(ν + 1).

• About x = 1 (x >= 0). DLMF 14.3.1 with Euler’s transformation (DLMF 15.8.1) gives P_ν^{-μ}(y) = w^{μ/2}/(2^μ μ!) F(μ - ν, μ + ν + 1; μ + 1; t). The series is summed at a start degree ν₀ ≡ ν (mod 1), μ <= ν₀ <= ν, as large as its alternating leading terms allow, and carried to ν by the degree recurrence DLMF 14.10.3 written for P_ν and D_ν = P_{ν-1} - yP_ν: P_{ν+1} = yP_ν - c_ν D_ν, D_{ν+1} = wP_ν + y c_ν D_ν, c_ν = (ν - μ)/(ν + μ + 1). This form never subtracts nearly equal values near y = 1, and increasing the degree is stable: the regular solution dominates where (ν + 1/2) sinθ < μ, and both solutions oscillate elsewhere. D_ν₀ comes from the same series; the derivative is DLMF 14.10.5, w P' = (ν - μ) D_ν - μ y P_ν.
• About x = 0 (small degrees, (ν + 1/2)|x| small). G = (1 - x²)^{-μ/2} P_ν^{-μ} solves (1 - x²) G'' - 2(μ + 1) x G' + (ν - μ)(ν + μ + 1) G = 0 (from DLMF 14.2.2), so its Taylor coefficients satisfy a two-term recurrence started from the values at zero, DLMF 14.5.1 and 14.5.2, with 1/Γ from a Taylor polynomial and DLMF 5.5.1.
• About x = -1 (x < 0). The connection formula DLMF 14.9.10, P_ν^{-μ}(-y) = (-1)^μ [cos(νπ) P_ν^{-μ}(y) + sin(νπ) S_ν^{-μ}(y)] with S = -(2/π) Q, separates the part regular at x = -1 from the singular one. sin(νπ) and cos(νπ) come from the exactly reduced degree ν - round(ν), so degrees within an ulp of an integer keep their exact offset. Both parts follow from the degenerate (logarithmic) case c = a + b + μ of the 1 - z connection formulas of DLMF §15.8 applied to DLMF 14.3.1: in powers of s with digamma coefficients, plus a finite sum of μ terms for μ >= 1. The digamma reflection DLMF 5.5.4 turns ψ at non-positive arguments into π cot(νπ), whose pole is cancelled analytically against the vanishing factor n - ν of the series coefficients. The order-zero expansion gives Q_ν(y) = ½ Σ_k (ν+1)_k (-ν)_k/(k!)² [2ψ(k+1) - ψ(ν+k+1) - ψ(ν-k+1) - ln s] s^k. These expansions are summed directly when (ν + 1/2) θ is small. Otherwise the order-zero pair is summed at a lower degree and carried to ν by the recurrence above; the regular part of order -μ comes from the series about x = 1, and the singular part from S^1 = -w S^0'/sinθ and the order recurrence DLMF 14.10.1, S^{k+1} = -2k cotθ S^k - (ν - k + 1)(ν + k) S^{k-1}, which is stable upwards because Q_ν^μ(y) dominates P_ν^μ(y) as μ grows for y > 0; its derivative uses w S^μ' = (ν + μ)(ν - μ + 1) sinθ S^{μ-1} + μ y S^μ (§14.10).
• The digamma function uses DLMF 5.5.2 and the asymptotic expansion DLMF 5.11.2.
• Quantities that can leave the double range carry a separate binary exponent, so only a final value or derivative beyond the double range is reported as an error. Sums that share the low-order bits of f are formed without rounding them as a whole, so their rounding errors do not accumulate systematically. At x = 1 the exact limits are returned.

Structs

Convergence 🔒

Convergence test of one series: the term must be negligible twice in a row and the tail, bounded geometrically with ratio rho, as well. Once reached, it stays reached.

OrderSums 🔒

Sums of order_series: Σ r_k, Σ k r_k, Σ r_k g_k and Σ (k r_k g_k + r_k).

OrderZero 🔒

Order-zero functions at 0 < y < 1, with w = 1 - y²: P_ν(y), w P_ν'(y), and S_ν(y) = -(2/π) Q_ν(y) (Ferrers second kind), w S_ν'(y).

Scaled 🔒

mantissa · 2^exponent with 1/2 <= |mantissa| < 1 (or zero): a double with a wider exponent range.

Sums 🔒

Running sums of the logarithmic expansion: Σ q_k (c_k - ln s), Σ q_k, and, as requested, Σ (k q_k (c_k - ln s) - q_k) (SINGULAR) and Σ k q_k (REGULAR). The values and each slope converge separately (for tiny ν the regular slope is tiny next to everything else); the values are frozen once converged, so they do not depend on which slopes are summed.

Enums

Slopes 🔒

Which order-zero slopes a caller needs.

Constants

BIG 🔒

Rescaling threshold 2^512 for recurrences that could leave the double range.

BIG_EXPONENT 🔒

CENTRAL_DEGREE 🔒

CENTRAL_LIMIT 🔒

CENTRAL_LIMIT_POSITIVE 🔒

CENTRAL_ORDER 🔒

CENTRAL_REACH 🔒

The expansion about x = 0 is used for (ν + 1/2)|x| <= CENTRAL_REACH (well conditioned) and |x| <= CENTRAL_LIMIT (or CENTRAL_LIMIT_POSITIVE for x > 0, where the series about x = 1 is cheaper), for degrees and orders that keep 1/Γ cheap.

EXPONENT_MASK 🔒

INVALID 🔒

INV_FACTORIAL 🔒

Correctly rounded 1/k! for k = 0..=130 (MAX_REAL_DEGREE_ORDER).

MAX_REAL_DEGREE_ORDER 🔒

The largest |m| of ferrers_real_degree, two above its largest degree. Orders above the degree are valid; the angular functions pass |m| <= degree.

MAX_TERMS 🔒

Safety bound on series terms; the series converge geometrically for t, s <= 1/2.

NONFINITE 🔒

REGULAR_REACH 🔒

Largest leading-ratio size (ν₀ - μ)(ν₀ + μ + 1) t / (μ + 1) of a regular start series.

RGAMMA_TAYLOR 🔒

Taylor coefficients of 1/Γ(3/2 + h) about h = 0 (enough for |h| <= 1/2).

SINGULAR_REACH 🔒

Largest 2 (ν₀ + 1/2) √s ≈ (ν₀ + 1/2) θ at which the logarithmic series is summed.

SQRT_PI 🔒

TOLERANCE 🔒

Relative truncation tolerance for the series (2^-54).

Functions

central 🔒

(P_ν^{-μ}(x), (1 - x²) dP_ν^{-μ}/dx) from the expansion about x = 0.

degree_product 🔒

ν(ν + 1) as an unevaluated sum high + low.

digamma 🔒

Digamma for x >= 1: DLMF 5.5.2 up to x >= 10, then DLMF 5.11.2.

digamma_reflection_step 🔒

ψ(2 - f) - ψ(1 + f). For f <= 1/2 it is π cot(πf) - 1/f + 1/(1 - f) (DLMF 5.5.2, 5.5.4) from frac_cot = f π cot(πf), with an absolute error of about ε/f that the callers’ factor f removes; otherwise two digamma values.

endpoint 🔒

Exact limits at x = 1: P_ν^m(1) = δ_{m0}; the slope is ν(ν+1)/2 (m = 0), infinite (|m| = 1), -Γ(ν+3)/(4Γ(ν-1)) (m = 2), -1/4 (m = -2) and zero otherwise.

exact_square 🔒

Dekker’s exact square: v² = square + error.

ferrers_real_degree 🔒

Real-degree Ferrers function P_v^m(x) (degree v not an integer) and, with DERIVATIVE, its analytic derivative in x; without it the second element is 0.0.

finish 🔒

Converts (P, (1 - x²) P') to doubles, rejecting results beyond the double range.

floor_small 🔒

⌊value⌋ for 0 <= value < 2^31.

frexp 🔒

value = mantissa · 2^exponent with 1/2 <= |mantissa| < 1; inline fast path for normal numbers, libm otherwise.

gamma_ratio 🔒

Γ(ν + μ + 1)/Γ(ν - μ + 1) = ∏_{i=1}^{μ} (ν + i)(ν + 1 - i); with skip = Some(i) the factor ν + 1 - i of that pair is left out.

log_series 🔒

OrderZero from the logarithmic expansion about y = 1 in s = (1 - y)/2: P_ν = Σ q_k, Q_ν = ½ Σ q_k (c_k - ln s) with q_k = (ν+1)_k (-ν)_k s^k/(k!)² and c_k = 2ψ(k+1) - ψ(ν+k+1) - ψ(ν+1-k), with the slopes selected as in Sums.

nearest_integer 🔒

The integer nearest to 0 <= value < 2^31 (halves rounded up).

nonfinite 🔒

one_minus_square 🔒

1 - y² as an unevaluated sum high + low, accurate far beyond a double.

order_log_sums 🔒

The logarithmic sums of order_series with n - μ = pivot, in three phases like log_series: direct terms for k <= n - μ, the cancelled pole at k = n - μ + 1, and the reflected digamma beyond. One division per term serves all reciprocals.

order_series 🔒

P_ν^m(-y) for 0 < y < 1, 1 <= μ = |m| <= ⌊ν⌋, from the expansion about x = -1 in s = (1 - y)/2: the degenerate case c - a - b = μ of the 1 - z connection formulas (DLMF §15.8) applied to DLMF 14.3.1, after the digamma reflection DLMF 5.5.4, P_ν^{-μ}(-y) = (-1)^μ cos(νπ) R + sin(νπ) (L + F/G) with G = Γ(ν+μ+1)/Γ(ν-μ+1), R = (w/4)^{μ/2}/μ! Σ r_k (that is P_ν^{-μ}(y)), L = (-1)^μ (w/4)^{μ/2}/(π μ!) Σ r_k [ln s - ψ(k+1) - ψ(k+μ+1) + ψ(ν+μ+k+1) + ψ(ν-μ-k+1)], F = (-1)^{μ+1} (μ-1)!/π (w/4)^{μ/2} s^{-μ} Σ_{k<μ} (ν+1)_k (-ν)_k s^k/(k! (1-μ)_k) and r_k = (ν+μ+1)_k (μ-ν)_k s^k/((μ+1)_k k!). As in log_series, the pole of ψ(ν - μ - k + 1) is cancelled against the factor n - ν of r_k (n = ⌊ν⌋).

order_zero 🔒

OrderZero at degree ν: the logarithmic expansion at the largest degree ν₀ ≡ ν (mod 1) with (ν₀ + 1/2) θ small, then the degree recurrence (μ = 0) for both solutions. Only the requested slopes are formed, unless the recurrence needs both.

pi_cot_scaled 🔒

πr cot(πr) for |r| <= 1/2, accurate (and finite) as r → 0.

raise_singular 🔒

(S_ν^μ(y), (1 - y²) dS_ν^μ/dy) for μ >= 1 from order zero: S^1 = -w S^0'/sinθ, then the order recurrence DLMF 14.10.1 upwards.

reflected 🔒

P_ν^m(-y) for 0 < y < 1 by the connection formula DLMF 14.9.10.

regular 🔒

(P_ν^{-μ}(y), (1 - y²) dP_ν^{-μ}/dy) for 0 <= y < 1.

rgamma 🔒

1/Γ(z) for moderate real z: DLMF 5.5.1 shifts into [1, 2), then a Taylor polynomial. The shifts multiply by z + k exactly where Γ has poles, so those zeros are exact.

rgamma_core 🔒

1/Γ(3/2 + h) for |h| <= 1/2 by Estrin’s scheme (short dependency chains).

scalbn 🔒

value · 2^exponent, correctly rounded; inline fast path when 2^exponent is a normal number and value is normalised as in Scaled.

shifted_sum 🔒

Σ_{i=1}^{count} 1/(start + i) for a small integer count, as one fraction.

sin_cos_pi 🔒

(sin(νπ), cos(νπ)) from the exactly reduced degree ν - round(ν).

sine_over_gamma_ratio 🔒

sin(νπ) Γ(ν - μ + 1)/Γ(ν + μ + 1); outside the caller domain (μ > round(ν)) the vanishing factor ν - round(ν) of the gamma ratio is cancelled against sin(νπ).

sine_power 🔒

w^{μ/2} for 1 - y² = w + w_low (0 < w <= 1).

small_integer 🔒

value rounded towards zero, for |value| < 2^31 (larger magnitudes saturate). Callers use it on validated degrees and small shifts; unlike f64::floor it needs no library call.

two_sum 🔒

Knuth’s error-free sum: a + b = sum + error exactly.