xsf/scipy_special/ellip_harm_2.rs
1//! Translated from scipy/special/_ellip_harm_2.pyx
2//!
3//! Unlike in SciPy, the integrals are computed after a change of variables that removes the
4//! (weighted) endpoint singularities, so that [`quad`] is enough, instead of QUADPACK's `dqags`
5//! and `dqaws`.
6
7use core::f64::consts::{FRAC_PI_2, PI};
8
9use super::ellip_harm::{Lame, sq_sub};
10use crate::ext::quadpack::quad;
11
12/// The relative tolerance of the integrals
13///
14/// Unlike in SciPy, not `1e-15`, which [`quad`] can't reach. Its error estimate is so pessimistic
15/// that `1e-13` already gives full accuracy.
16const EPSREL: f64 = 1e-13;
17
18/// `(t, t^2 - h^2, t^2 - k^2)`, with the differences computed without cancellation
19type Point = (f64, f64, f64);
20
21/// Ellipsoidal harmonic function $F^p_n(s)$
22///
23/// Also known as the Lamé function of the second kind, a solution of the Lamé equation (see
24/// [`ellip_harm`](crate::ellip_harm)), related to the one of the first kind by
25///
26/// $$
27/// F^p_n(s) = (2n + 1) E^p_n(s)
28/// \int_0^{1/s} \frac{du}{(E^p_n(1/u))^2 \sqrt{(1 - u^2 k^2)(1 - u^2 h^2)}}
29/// $$
30///
31/// Corresponds to [`scipy.special.ellip_harm_2`][scipy].
32///
33/// [scipy]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.ellip_harm_2.html
34///
35/// # Arguments
36/// - `h2`: $h^2$
37/// - `k2`: $k^2$, should be larger than `h2`
38/// - `n`: degree
39/// - `p`: order, `1 <= p <= 2n + 1`
40/// - `s`: coordinate, `s >= k`
41///
42/// Returns NaN if `p` is invalid, or if the integral doesn't converge, e.g. at `s = k` for the
43/// functions of type M and N (see [`ellip_harm`](crate::ellip_harm)).
44///
45/// # See also
46/// - [`ellip_harm`](crate::ellip_harm): Ellipsoidal harmonic function $E^p_n(s)$
47/// - [`ellip_normal`]: Ellipsoidal harmonic normalization constant $\gamma^p_n$
48#[must_use]
49pub fn ellip_harm_2(h2: f64, k2: f64, n: u32, p: u32, s: f64) -> f64 {
50 let Some(lame) = Lame::new(h2, k2, n, p) else {
51 return f64::NAN;
52 };
53
54 // `sqrt(k2) = k + dk`, and `s - sqrt(k2)`, where `s = k` is taken as `s >= sqrt(k2)`
55 let k = k2.sqrt();
56 let dk = -sq_sub(k, k2) / (2.0 * k);
57 let s_k = (s - k) - dk;
58 let s_k = if s == k { s_k.max(0.0) } else { s_k };
59 // `s^2 - k2` and `s^2 - h2`, consistent with `1 / t^2 - k2` and `1 / t^2 - h2` below at
60 // `t = 1/s`, which matters near `s = k`
61 let s2_k2 = s_k * (s + k);
62 let e_s = lame.eval_with(s, s2_k2 + (k2 - h2), s2_k2, 1.0, 1.0);
63 if e_s.is_infinite() {
64 // `F(s) ~ 1 / (s E(s))` underflows
65 return 0.0;
66 }
67
68 // `_F_integrand` over `[0, 1/s]`, with `t = (1 - v^2) / sqrt(k2)` (up to the rounding of `k`),
69 // so that its `1 / sqrt(1 - t sqrt(k2))` is `1 / v`, which cancels, also for `s = k`
70 //
71 // - `1 / t^2 - k2` and `1 / t^2 - h2` follow from `v`, without cancellation;
72 // - `E^2(s)` is folded in, so that the integral doesn't underflow for large `s`.
73 let integrand = |v: f64, t: f64| {
74 let one_m_t2k2 = v * v * (1.0 + t * k);
75 let one_m_t2h2 = one_m_t2k2 + t * t * (k2 - h2);
76 let i = lame.eval_with(
77 1.0 / t,
78 one_m_t2h2 / (t * t),
79 one_m_t2k2 / (t * t),
80 1.0,
81 1.0,
82 );
83 let r = e_s / i;
84 2.0 / k * r * r / ((1.0 + t * k).sqrt() * one_m_t2h2.sqrt())
85 };
86 // over `v in [v1, 1]`, split at `v = 1/2`, so that `v ~ 0` (near `s = k`) and `w = 1 - v ~ 0`
87 // (`t ~ 0` for large `s`) are both resolved
88 let v1 = (s_k / s).sqrt();
89 let (res_v, err_v) = if v1 < 0.5 {
90 quad(|v| integrand(v, (1.0 - v * v) / k), v1, 0.5, 0.0, EPSREL)
91 } else {
92 (0.0, 0.0)
93 };
94 let w1 = k / s / (1.0 + v1);
95 let (res_w, err_w) = quad(
96 |w| integrand(1.0 - w, w * (2.0 - w) / k),
97 0.0,
98 w1.min(0.5),
99 0.0,
100 EPSREL,
101 );
102 let (res, err) = (res_v + res_w, err_v + err_w);
103 if err > 1e-10 * res.abs() + 1e-290 {
104 return f64::NAN;
105 }
106 res * (2.0 * f64::from(n) + 1.0) / e_s
107}
108
109/// Ellipsoidal harmonic normalization constant $\gamma^p_n$
110///
111/// $$
112/// \gamma^p_n = 8 \int_0^h dx \int_h^k dy
113/// \frac{(y^2 - x^2) (E^p_n(y) E^p_n(x))^2}{\sqrt{(k^2 - y^2)(y^2 - h^2)(h^2 - x^2)(k^2 - x^2)}}
114/// $$
115///
116/// Corresponds to [`scipy.special.ellip_normal`][scipy].
117///
118/// [scipy]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.ellip_normal.html
119///
120/// # Arguments
121/// - `h2`: $h^2$
122/// - `k2`: $k^2$, should be larger than `h2`
123/// - `n`: degree
124/// - `p`: order, `1 <= p <= 2n + 1`
125///
126/// Returns NaN if `p` is invalid, or if the integrals don't converge.
127///
128/// # See also
129/// - [`ellip_harm`](crate::ellip_harm): Ellipsoidal harmonic function $E^p_n(s)$
130/// - [`ellip_harm_2`]: Ellipsoidal harmonic function $F^p_n(s)$
131#[must_use]
132pub fn ellip_normal(h2: f64, k2: f64, n: u32, p: u32) -> f64 {
133 let Some(lame) = Lame::new(h2, k2, n, p) else {
134 return f64::NAN;
135 };
136 let (h, k) = (h2.sqrt(), k2.sqrt());
137 let e2 = |(t, t2_h2, t2_k2): Point| {
138 let i = lame.eval_with(t, t2_h2, t2_k2, 1.0, 1.0);
139 i * i
140 };
141
142 // the integrals of `f(t(x))` and `t(x)^2 f(t(x))` over `[0, b]`
143 let moments = |f: &dyn Fn(Point) -> f64, t: &dyn Fn(f64) -> Point, b: f64| {
144 let m0 = quad(|x| f(t(x)), 0.0, b, 0.0, EPSREL);
145 let m2 = quad(
146 |x| {
147 let t = t(x);
148 t.0 * t.0 * f(t)
149 },
150 0.0,
151 b,
152 0.0,
153 EPSREL,
154 );
155 (m0, m2)
156 };
157
158 // `_F_integrand1` and `_F_integrand2` over `[h, k]` with the weight `1 / sqrt((t - h)(k - t))`,
159 // so with `t = h + (k - h) sin^2(theta / 2)` over `[0, pi]`
160 let k_h = (k2 - h2) / (k + h);
161 let ((res, err), (res1, err1)) = moments(
162 &|p| e2(p) / ((p.0 + h) * (p.0 + k)).sqrt(),
163 &|theta| {
164 let (sin, cos) = (0.5 * theta).sin_cos();
165 let (t_h, k_t) = (k_h * sin * sin, k_h * cos * cos);
166 let t = h + t_h;
167 (t, t_h * (t + h), -k_t * (k + t))
168 },
169 PI,
170 );
171
172 // `_F_integrand3` and `_F_integrand4` over `[0, h]` with the weight `1 / sqrt(h - t)`, so with
173 // `t = h sin(phi)` over `[0, pi/2]`, which leaves `E^2(t) / sqrt(k^2 - t^2)`
174 let ((res2, err2), (res3, err3)) = moments(
175 &|p| e2(p) / (-p.2).sqrt(),
176 &|phi| {
177 let (sin, cos) = phi.sin_cos();
178 let h2_t2 = h2 * cos * cos;
179 (h * sin, -h2_t2, -((k2 - h2) + h2_t2))
180 },
181 FRAC_PI_2,
182 );
183
184 let error = 8.0 * (res2 * err1 + err2 * res1 + res * err3 + res3 * err);
185 let result = 8.0 * (res1 * res2 - res * res3);
186 if error > 10e-8 * result.abs() {
187 return f64::NAN;
188 }
189 result
190}