Skip to main content

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}