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}