Skip to main content

xsf/scipy_special/
spence.rs

1//! NOTE: The Cephes library only provides a real implementation of the Spence function.
2//! For complex argument, `scipy.special.spence` uses the Cython implementation at
3//! `scipy/special/_spence.pxd`.
4//!
5//! Cython converts the real operand of a complex subtraction to complex, so `1 - z` is
6//! `C64::ONE - z` here, with the imaginary part `0.0 - z.im`.
7
8use num_complex::Complex64;
9
10use crate::utils::FRAC_PI_SQ_6;
11use crate::xsf::c64::{C64, ViaC64, c64};
12use crate::xsf::zlog1_c64;
13
14// Relative tolerance for the series
15const TOL: f64 = f64::EPSILON;
16
17/// Compute Spence's function for complex arguments. The strategy is:
18/// - If z is close to 0, use a series centered at 0.
19/// - If z is far away from 1, use the reflection formula
20///
21/// spence(z) = -spence(z/(z - 1)) - pi**2/6 - ln(z - 1)**2/2
22///
23/// to move close to 1. See \[1\].
24/// - If z is close to 1, use a series centered at 1.
25#[inline]
26fn cspence(z: C64) -> C64 {
27    // if zabs(z) < 0.5:
28    //     # This step isn't necessary, but this series converges faster.
29    //     return cspence_series0(z)
30    // elif zabs(1 - z) > 1:
31    //     return -cspence_series1(z/(z - 1)) - FRAC_PI_SQ_6 - 0.5*zlog1(z - 1)**2
32    // else:
33    //     return cspence_series1(z)
34
35    if z.is_nan() {
36        // like in xsf, instead of iterating 500 times
37        C64::NAN
38    } else if z.norm() < 0.5 {
39        // This step isn't necessary, but this series converges faster.
40        cspence_series0(z)
41    } else if (C64::ONE - z).norm() > 1.0 {
42        let zm1 = z - 1.0;
43        let log_zm1 = zlog1_c64(zm1);
44        -cspence_series1(z / zm1) - FRAC_PI_SQ_6 - 0.5 * (log_zm1 * log_zm1)
45    } else {
46        cspence_series1(z)
47    }
48}
49
50/// A series centered at z = 0; see <https://functions.wolfram.com/10.07.06.0005.02>
51#[inline]
52fn cspence_series0(z: C64) -> C64 {
53    if z == C64::ZERO {
54        return c64(FRAC_PI_SQ_6, 0.0);
55    }
56    // cdef:
57    //     int n
58    //     double complex zfac = 1
59    //     double complex sum1 = 0
60    //     double complex sum2 = 0
61    //     double complex term1, term2
62    let mut zfac = C64::ONE;
63    let mut sum1 = C64::ZERO;
64    let mut sum2 = C64::ZERO;
65
66    // for n in range(1, 500):
67    for n in 1..500 {
68        // zfac *= z
69        zfac *= z;
70
71        // term1 = zfac/n**2
72        let term1 = zfac / f64::from(n * n);
73        // sum1 += term1
74        sum1 += term1;
75
76        // term2 = zfac/n
77        let term2 = zfac / f64::from(n);
78        // sum2 += term2
79        sum2 += term2;
80
81        // if zabs(term1) <= TOL*zabs(sum1) and zabs(term2) <= TOL*zabs(sum2):
82        //     break
83        if term1.norm() <= TOL * sum1.norm() && term2.norm() <= TOL * sum2.norm() {
84            break;
85        }
86    }
87
88    // return FRAC_PI_SQ_6 - sum1 + zlog1(z)*sum2
89    c64(FRAC_PI_SQ_6, 0.0) - sum1 + zlog1_c64(z) * sum2
90}
91
92/// A series centered at z = 1 which enjoys faster convergence than the Taylor series.
93/// See Ginsberg, Zaborowski, "The Dilogarithm Function of a Real Argument"].
94/// The number of terms used comes from bounding the absolute tolerance at the edge of the radius of
95/// convergence where the sum is O(1).
96#[inline]
97fn cspence_series1(z: C64) -> C64 {
98    // z = 1 - z
99    let z = C64::ONE - z;
100
101    // if z == 1:
102    //     return 0
103    if z == C64::ZERO {
104        return z;
105    }
106
107    // cdef:
108    //     int n
109    //     double complex zfac = 1
110    //     double complex res = 0
111    //     double complex term, zz
112    let mut zfac = C64::ONE;
113    let mut res = C64::ZERO;
114
115    // for n in range(1, 500):
116    //     if zabs(term) <= TOL*zabs(res):
117    //         break
118    for n in 1..500 {
119        // zfac *= z
120        zfac *= z;
121        // # Do the divisions one at a time to guard against overflow
122        // term = ((zfac/n**2)/(n + 1)**2)/(n + 2)**2
123        let n = f64::from(n);
124        let term = zfac / n.powi(2) / (n + 1.0).powi(2) / (n + 2.0).powi(2);
125        // res += term
126        res += term;
127        if term.norm() <= TOL * res.norm() {
128            break;
129        }
130    }
131
132    // zz = z**2
133    let zz = z * z;
134
135    // res *= 4*zz
136    res *= 4.0 * zz;
137    // res += 4*z + 5.75*zz + 3*(1 - zz)*zlog1(1 - z)
138    res += 4.0 * z + 5.75 * zz + 3.0 * (C64::ONE - zz) * zlog1_c64(C64::ONE - z);
139    // res /= 1 + 4*z + zz
140    res /= 1.0 + 4.0 * z + zz;
141    // return res
142    res
143}
144
145pub trait SpenceArg: crate::sealed::Sealed {
146    fn spence(self) -> Self;
147}
148
149impl SpenceArg for f64 {
150    #[inline]
151    fn spence(self) -> Self {
152        crate::xsf::cephes::spence(self)
153    }
154}
155
156impl SpenceArg for Complex64 {
157    #[inline]
158    fn spence(self) -> Self {
159        self.via(cspence)
160    }
161}
162
163/// Spence's function for real or complex argument, also known as the dilogarithm
164///
165/// $$ \int_1^z {\log(t) \over 1 - t} \dd t $$
166///
167/// Corresponds to [`scipy.special.spence`][scipy].
168///
169/// [scipy]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.spence.html
170#[doc(alias = "dilogarithm", alias = "li2")]
171#[must_use]
172#[inline]
173pub fn spence<T: SpenceArg>(z: T) -> T {
174    z.spence()
175}