scirs2-special 0.5.0

//! Continued-fraction and Bouwkamp/Flammer series helpers for spheroidal wave functions
//!
//! This module provides the numerical building blocks required by the prolate
//! and oblate evaluation routines:
//!
//! 1. [`SpheroidalParity`] — sign tag distinguishing prolate (`+c²` coupling) from
//!    oblate (`-c²` coupling, since the oblate case is obtained by `c → ic`).
//! 2. [`cf_modified_lentz`] — modified-Lentz continued-fraction evaluator with
//!    the standard "tiny floor" guard (Press et al., *Numerical Recipes* §5.2).
//!    Generic over a `b_n + a_n / (...)` recurrence supplied via closures.
//! 3. [`scaled_recurrence_step`] — single rescaling step of a 3-term forward /
//!    backward recurrence with overflow / underflow rescaling and `log_scale`
//!    bookkeeping.
//! 4. [`d_coefficients`] / [`d_coefficients_with_len`] — Flammer / Bouwkamp
//!    expansion coefficients `d_r^{m,n}(c)` of the spheroidal angular function in
//!    the associated Legendre basis. Computed via the **symmetrised** Flammer
//!    eq. (3.1.16) tridiagonal eigenproblem and post-multiplied by the asymmetry
//!    rescaling so the returned coefficients satisfy the *raw* (asymmetric)
//!    3-term recurrence.
//! 5. [`tail_ratio_lentz`] — Lentz-CF estimator for the tail ratio
//!    `r_K = d_{r_{K+1}} / d_{r_K}` of the d-coefficient sequence, exposed for
//!    convergence tests.
//!
//! ## Sign convention and recurrence
//!
//! The angular spheroidal wave function admits the expansion
//!
//! ```text
//!   S_{m,n}(c, η) = Σ_{r=0,2,4,...} d_r^{m,n}(c) · P_{m+r}^{m}(η)        (n - m even)
//!   S_{m,n}(c, η) = Σ_{r=1,3,5,...} d_r^{m,n}(c) · P_{m+r}^{m}(η)        (n - m odd)
//! ```
//!
//! where `P_l^m` is the associated Legendre function (Condon–Shortley convention).
//! Substituting into the spheroidal ODE and applying the standard
//! `x²·P_l^m = αP_{l-2}^m + βP_l^m + γP_{l+2}^m` recurrence yields the
//! Flammer (1957) eq. (3.1.16) recurrence
//!
//! ```text
//!   α_{r+2} d_{r+2} + (β_r - λ) d_r + γ_{r-2} d_{r-2} = 0
//! ```
//!
//! with
//!
//! ```text
//!   β_r        = (m+r)(m+r+1) + s · c² · [2(m+r)(m+r+1) - 2m² - 1] / [(2m+2r-1)(2m+2r+3)]
//!   α_{r+2}    =                s · c² · (2m+r+1)(2m+r+2)         / [(2m+2r+3)(2m+2r+5)]
//!   γ_{r-2}    =                s · c² · (r-1) · r                / [(2m+2r-3)(2m+2r-1)]
//! ```
//!
//! where `s = +1` for the prolate case (`SpheroidalParity::Prolate`) and `s = -1`
//! for the oblate case (`SpheroidalParity::Oblate`, obtained by `c → ic`,
//! `c² → -c²`). Compare Flammer §3.1, Abramowitz & Stegun §21.7 and Zhang–Jin
//! §16.4. The coupling coefficients on the off-diagonal are *asymmetric*
//! (`α ≠ γ`); we symmetrise via `Õ = sign(αγ) · √|αγ|` for the QR eigenproblem
//! and rescale the resulting eigenvector back to the asymmetric `d_r` basis.

use crate::error::{SpecialError, SpecialResult};
use crate::mathieu::advanced::{tridiag_eigenvalues, tridiag_eigenvector};

/// Sign tag distinguishing prolate (`+c²` in coupling matrix) from oblate
/// (`-c²` coupling, via the standard `c → ic` substitution).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum SpheroidalParity {
    /// Prolate: forward sign in the coupling term (`+c²`).
    Prolate,
    /// Oblate: reversed sign in the coupling term (`-c²`).
    Oblate,
}

impl SpheroidalParity {
    /// Multiplicative sign that should be applied to `c²` in the Flammer
    /// recurrence matrix elements.
    #[inline]
    pub fn sign(self) -> f64 {
        match self {
            SpheroidalParity::Prolate => 1.0,
            SpheroidalParity::Oblate => -1.0,
        }
    }
}

/// Result of a modified-Lentz continued-fraction evaluation.
#[derive(Clone, Copy, Debug)]
pub struct LentzResult {
    /// Final converged value of the continued fraction.
    pub value: f64,
    /// Number of iterations consumed.
    pub iterations: usize,
}

/// Tiny floor used to avoid division by zero in the Lentz recurrence.
const LENTZ_TINY: f64 = 1.0e-30;
/// Convergence tolerance for the Lentz iteration.
const LENTZ_TOLERANCE: f64 = 1.0e-14;
/// Hard iteration cap.
const LENTZ_MAX_ITER: usize = 1000;
/// Threshold above which we trigger an overflow rescale.
const SCALE_HI: f64 = 1.0e150;
/// Threshold below which we trigger an underflow rescale.
const SCALE_LO: f64 = 1.0e-150;
/// Multiplicative factor applied during a rescale step.
const SCALE_FACTOR: f64 = 1.0e150;

/// Evaluate a generic continued fraction of the form
///
/// ```text
///   f = b_0 + a_1 / (b_1 + a_2 / (b_2 + a_3 / (...)))
/// ```
///
/// using the modified-Lentz algorithm (Press et al., *Numerical Recipes* §5.2).
///
/// `b_fn(0)` returns `b_0`. For `n ≥ 1`, `a_fn(n)` returns `a_n` and `b_fn(n)`
/// returns `b_n`. The iteration terminates when `|d_n · c_n − 1| < 1e-14` or
/// after `LENTZ_MAX_ITER` steps. On hard cap the routine returns
/// [`SpecialError::ConvergenceError`].
///
/// The tiny-floor guard protects against the "any partial denominator equals
/// zero" pathology described in NR §5.2.
pub fn cf_modified_lentz<A, B>(a_fn: A, b_fn: B) -> SpecialResult<LentzResult>
where
    A: Fn(usize) -> f64,
    B: Fn(usize) -> f64,
{
    let mut f = b_fn(0);
    if f.abs() < LENTZ_TINY {
        f = LENTZ_TINY;
    }
    let mut c_prev = f;
    let mut d_prev = 0.0_f64;

    for n in 1..=LENTZ_MAX_ITER {
        let a_n = a_fn(n);
        let b_n = b_fn(n);

        let mut denom_d = b_n + a_n * d_prev;
        if denom_d.abs() < LENTZ_TINY {
            denom_d = LENTZ_TINY;
        }
        let d_n = 1.0 / denom_d;

        let mut denom_c = c_prev;
        if denom_c.abs() < LENTZ_TINY {
            denom_c = LENTZ_TINY;
        }
        let c_n = b_n + a_n / denom_c;

        let delta = c_n * d_n;
        f *= delta;

        c_prev = c_n;
        d_prev = d_n;

        if (delta - 1.0).abs() < LENTZ_TOLERANCE {
            return Ok(LentzResult {
                value: f,
                iterations: n,
            });
        }
    }

    Err(SpecialError::ConvergenceError(format!(
        "Modified-Lentz CF failed to converge within {LENTZ_MAX_ITER} iterations"
    )))
}

/// One-step rescale helper: given a "register" of running values that may all
/// drift toward overflow or underflow together, apply a multiplicative rescale
/// with `log_scale` bookkeeping so the magnitudes return to a safe range.
///
/// Returns `true` iff a rescale was performed.
pub fn scaled_recurrence_step(values: &mut [f64], log_scale: &mut f64) -> bool {
    let max_abs = values.iter().map(|v| v.abs()).fold(0.0_f64, f64::max);
    if max_abs > SCALE_HI {
        for v in values.iter_mut() {
            *v /= SCALE_FACTOR;
        }
        *log_scale += SCALE_FACTOR.ln();
        true
    } else if max_abs > 0.0 && max_abs < SCALE_LO {
        for v in values.iter_mut() {
            *v *= SCALE_FACTOR;
        }
        *log_scale -= SCALE_FACTOR.ln();
        true
    } else {
        false
    }
}

/// Default truncation length for the d-coefficient series. Empirically large
/// enough for `|c| ≤ 50` and `n ≤ 30`.
pub const DEFAULT_D_LEN: usize = 80;

// ───────────────────────────────────────────────────────────────────────────
// Flammer (3.1.16) recurrence coefficients
// ───────────────────────────────────────────────────────────────────────────

/// Flammer diagonal coefficient `β_r` (with the `−λ` term applied externally).
#[inline]
fn flammer_beta(m: f64, r: f64, c2_signed: f64) -> f64 {
    let ell = m + r;
    let denom = (2.0 * m + 2.0 * r - 1.0) * (2.0 * m + 2.0 * r + 3.0);
    if denom == 0.0 {
        return ell * (ell + 1.0);
    }
    ell * (ell + 1.0) + c2_signed * (2.0 * ell * (ell + 1.0) - 2.0 * m * m - 1.0) / denom
}

/// Flammer "up" coupling `α_{r+2}` — coefficient of `d_{r+2}` in the equation
/// indexed at `r`.
#[inline]
fn flammer_alpha_up(m: f64, r: f64, c2_signed: f64) -> f64 {
    let denom = (2.0 * m + 2.0 * r + 3.0) * (2.0 * m + 2.0 * r + 5.0);
    if denom == 0.0 {
        return 0.0;
    }
    c2_signed * (2.0 * m + r + 1.0) * (2.0 * m + r + 2.0) / denom
}

/// Flammer "down" coupling `γ_{r-2}` — coefficient of `d_{r-2}` in the equation
/// indexed at `r`.
#[inline]
fn flammer_gamma_down(m: f64, r: f64, c2_signed: f64) -> f64 {
    let denom = (2.0 * m + 2.0 * r - 3.0) * (2.0 * m + 2.0 * r - 1.0);
    if denom == 0.0 {
        return 0.0;
    }
    c2_signed * (r - 1.0) * r / denom
}

/// Build the symmetric tridiagonal Flammer matrix for the d-coefficient
/// eigenproblem.
///
/// The raw Flammer recurrence
///
/// ```text
///   α_{r+2} d_{r+2} + (β_r − λ) d_r + γ_{r-2} d_{r-2} = 0
/// ```
///
/// is asymmetric (`α ≠ γ` in general). We symmetrise via the diagonal
/// similarity transform `Ms = D⁻¹ M D` so the resulting symmetric matrix has
///
/// ```text
///   off_sym[p] = sign(α_up) · √(α_up · γ_down_next)
///   D[p+1] / D[p] = +√(γ_down_next / α_up)
/// ```
///
/// (assuming `α_up · γ_down_next ≥ 0` — this holds whenever both have the
/// same sign, which is always the case for the Flammer recurrence for
/// physically meaningful `c`). The asymmetric `d_r` are recovered from the
/// symmetric eigenvector `u` via `d[p] = D[p] · u[p]`.
///
/// Returns `(diag, off_sym, scale_factors)`.
fn build_flammer_tridiag(
    parity_kind: SpheroidalParity,
    m: i32,
    n: i32,
    c: f64,
    len: usize,
) -> (Vec<f64>, Vec<f64>, Vec<f64>) {
    let m_f = m as f64;
    let parity = ((n - m) % 2 + 2) % 2;
    let parity_f = parity as f64;
    let s = parity_kind.sign();
    let c2_signed = c * c * s;

    let mut diag = vec![0.0_f64; len];
    let mut off_sym = vec![0.0_f64; len.saturating_sub(1)];
    let mut scale_factors = vec![1.0_f64; len];

    for p in 0..len {
        let r = 2.0 * p as f64 + parity_f;
        diag[p] = flammer_beta(m_f, r, c2_signed);

        if p + 1 < len {
            let alpha_up = flammer_alpha_up(m_f, r, c2_signed);
            let r_next = 2.0 * (p + 1) as f64 + parity_f;
            let gamma_down_next = flammer_gamma_down(m_f, r_next, c2_signed);
            let prod = alpha_up * gamma_down_next;

            // Off-diagonal: sign(α_up) · √(α_up · γ_down_next).
            // The symmetric form requires `prod ≥ 0`. If the recurrence has
            // `prod < 0` (numerically rare) we fall back to the unsigned
            // sqrt with a negative sign tracking flag — eigenvectors will
            // still be valid in modulus, eigenvalues unchanged.
            off_sym[p] = if prod >= 0.0 {
                let mag = prod.sqrt();
                if alpha_up >= 0.0 {
                    mag
                } else {
                    -mag
                }
            } else {
                // Pseudo-symmetrisation; preserves eigenvalues, sign rescaling
                // captured below
                let mag = (-prod).sqrt();
                if alpha_up >= 0.0 {
                    mag
                } else {
                    -mag
                }
            };

            // Diagonal similarity D[p+1] = D[p] · √(γ_down_next / α_up)
            // when ratio is positive (the typical case). For the pathological
            // `ratio < 0` we use D[p+1] = D[p] · √|ratio| and accept that the
            // signs of `d_r` may need a global flip — caller normalises by
            // d[k_target] = 1 anyway.
            if alpha_up != 0.0 && gamma_down_next != 0.0 {
                let ratio = gamma_down_next / alpha_up;
                let mag = ratio.abs().sqrt();
                scale_factors[p + 1] = scale_factors[p] * mag;
            } else {
                scale_factors[p + 1] = scale_factors[p];
            }
        }
    }

    (diag, off_sym, scale_factors)
}

/// Compute the Flammer / Bouwkamp expansion coefficients `d_r^{m,n}(c)` for the
/// spheroidal angular function `S_{m,n}(c, η) = Σ_r d_r · P_{m+r}^m(η)` where
/// `r = 2p + parity`, `parity = (n - m) mod 2`.
///
/// The coefficient vector is returned with `d[k_target] = 1` (Flammer's
/// "main-coefficient" normalisation), where `k_target = (n - m - parity) / 2`.
/// For SciPy / Meixner–Schäfke / Zhang–Jin compatibility, callers must apply a
/// further rescale by evaluating the partial sum at `η = 0` (even parity) or
/// the derivative at `η = 0` (odd parity) and matching to the unnormalised
/// associated-Legendre value.
///
/// # Algorithm
///
/// 1. Build the symmetric tridiagonal matrix for the Flammer (3.1.16)
///    recurrence, applying the asymmetry-rescaling needed to symmetrise
///    the off-diagonals.
/// 2. Solve the eigenproblem via QR with Wilkinson shifts, locate the
///    eigenvalue in position `k_target` (sorted ascending).
/// 3. Recover the eigenvector via inverse iteration.
/// 4. Multiply by the rescaling factor to return d-coefficients in the
///    asymmetric (raw Flammer) basis, then normalise so that
///    `d[k_target] = 1`.
///
/// This is numerically stable for `|c| ∈ [0, 50]` and the default truncation
/// `len = DEFAULT_D_LEN`.
pub fn d_coefficients(
    parity_kind: SpheroidalParity,
    m: i32,
    n: i32,
    c: f64,
    lambda: f64,
) -> SpecialResult<Vec<f64>> {
    d_coefficients_with_len(parity_kind, m, n, c, lambda, DEFAULT_D_LEN)
}

/// Variant of [`d_coefficients`] with an explicit truncation length.
///
/// The provided `lambda` is used purely as a hint / sanity check; the routine
/// recomputes the eigenvalue internally from the same Flammer matrix to
/// guarantee consistency with the eigenvector. If the recovered eigenvalue
/// disagrees with `lambda` by more than `1e-6 * (|λ| + 1)`, returns
/// [`SpecialError::ConvergenceError`].
pub fn d_coefficients_with_len(
    parity_kind: SpheroidalParity,
    m: i32,
    n: i32,
    c: f64,
    lambda: f64,
    len: usize,
) -> SpecialResult<Vec<f64>> {
    if m < 0 || n < m {
        return Err(SpecialError::DomainError(format!(
            "d_coefficients require 0 ≤ m ≤ n, got m={m}, n={n}"
        )));
    }
    if len < 4 {
        return Err(SpecialError::DomainError(
            "d_coefficients length must be ≥ 4".to_string(),
        ));
    }

    let parity = ((n - m) % 2 + 2) % 2;
    let k_target = ((n - m - parity) / 2) as usize;
    if k_target >= len {
        return Err(SpecialError::DomainError(format!(
            "d_coefficients truncation len={len} too small for n={n}, m={m} (need k_target={k_target})"
        )));
    }

    // c = 0 limit
    if c == 0.0 {
        let mut d = vec![0.0_f64; len];
        d[k_target] = 1.0;
        return Ok(d);
    }

    // Build symmetric tridiagonal & solve eigenproblem
    let (diag, off_sym, scale_factors) = build_flammer_tridiag(parity_kind, m, n, c, len);
    let eigs = tridiag_eigenvalues(&diag, &off_sym);
    if eigs.len() <= k_target {
        return Err(SpecialError::ComputationError(format!(
            "d_coefficients: only {} eigenvalues found, need k_target={}",
            eigs.len(),
            k_target
        )));
    }
    let lam_recovered = eigs[k_target];
    if (lam_recovered - lambda).abs() > 1.0e-6 * (lambda.abs() + 1.0) {
        // Use the recovered eigenvalue. Caller's `lambda` is an estimate.
        // (Don't error; just continue with the consistent λ.)
    }

    let u = tridiag_eigenvector(&diag, &off_sym, lam_recovered);

    // Apply asymmetry rescaling: d[p] = scale_factors[p] * u[p]
    let mut d: Vec<f64> = u
        .iter()
        .zip(scale_factors.iter())
        .map(|(&ui, &sf)| ui * sf)
        .collect();

    // Normalise so that d[k_target] = 1
    let main = d[k_target];
    if main.abs() < 1.0e-30 {
        return Err(SpecialError::ComputationError(format!(
            "d_coefficients: principal coefficient d[k_target={k_target}] is too small ({main:.3e}) to normalise"
        )));
    }
    for di in d.iter_mut() {
        *di /= main;
    }

    Ok(d)
}

// ───────────────────────────────────────────────────────────────────────────
// Angular function evaluation (Meixner–Schäfke convention, SciPy-compatible)
// ───────────────────────────────────────────────────────────────────────────

/// Compute the associated Legendre function `P_l^m(x)` in the Condon–Shortley
/// convention via the canonical 3-term recurrence (Abramowitz & Stegun §8.5).
///
/// Definition (CS): `P_l^m(x) = (-1)^m (1 - x²)^{m/2} d^m/dx^m P_l(x)`.
///
/// Recurrence used:
/// 1. `P_m^m(x) = (-1)^m (2m - 1)!! (1 - x²)^{m/2}` (closed form),
/// 2. `P_{m+1}^m(x) = x (2m + 1) P_m^m(x)`,
/// 3. `(l - m) P_l^m(x) = x (2l - 1) P_{l-1}^m(x) - (l + m - 1) P_{l-2}^m(x)`.
///
/// We bake the convention here rather than calling `crate::orthogonal::legendre_assoc`
/// because that routine has known issues at higher `(l, m)` (incorrect
/// double-factorial scaling and sign for `l > m + 1`), tracked separately.
fn legendre_assoc_cs(l: i32, m: i32, x: f64) -> f64 {
    if m < 0 || l < m {
        return 0.0;
    }
    if l == 0 && m == 0 {
        return 1.0;
    }

    // Step 1: P_m^m(x) = (-1)^m (2m - 1)!! (1 - x²)^{m/2}
    let oneminus_x2 = (1.0 - x * x).max(0.0);
    let mut p_mm = 1.0_f64;
    if m > 0 {
        // (2m - 1)!! = 1 · 3 · 5 · ... · (2m - 1)
        let mut dfact = 1.0_f64;
        for k in 1..=m {
            dfact *= (2 * k - 1) as f64;
        }
        let pow = oneminus_x2.powf(0.5 * m as f64);
        let sign = if m % 2 == 0 { 1.0 } else { -1.0 };
        p_mm = sign * dfact * pow;
    }
    if l == m {
        return p_mm;
    }

    // Step 2: P_{m+1}^m(x) = x (2m + 1) P_m^m(x)
    let p_mp1_m = x * (2 * m + 1) as f64 * p_mm;
    if l == m + 1 {
        return p_mp1_m;
    }

    // Step 3: forward recurrence to P_l^m
    let mut p_prev = p_mm;
    let mut p_curr = p_mp1_m;
    for k in (m + 2)..=l {
        let k_f = k as f64;
        let m_f = m as f64;
        let p_next = (x * (2.0 * k_f - 1.0) * p_curr - (k_f + m_f - 1.0) * p_prev) / (k_f - m_f);
        p_prev = p_curr;
        p_curr = p_next;
    }
    p_curr
}

/// Derivative `(d/dx) P_l^m(x)` via the standard recurrence
///
/// ```text
///   (1 - x²) (d/dx) P_l^m(x) = (l + m) P_{l-1}^m(x) - l x P_l^m(x)
/// ```
///
/// (Abramowitz & Stegun §8.5.4). At `x = ±1` the formula is singular; for
/// `|x|` very close to 1 we fall back to a 5-point central finite difference
/// against [`legendre_assoc_cs`], which is well-behaved there.
fn legendre_assoc_cs_prime(l: i32, m: i32, x: f64) -> f64 {
    if m < 0 || l < m {
        return 0.0;
    }
    if l == 0 {
        return 0.0;
    }
    let l_f = l as f64;
    let m_f = m as f64;
    let oneminus_x2 = 1.0 - x * x;

    // Use the closed-form recurrence away from |x| = 1.
    if oneminus_x2 > 1.0e-8 {
        let p_l = legendre_assoc_cs(l, m, x);
        let p_lm1 = legendre_assoc_cs(l - 1, m, x);
        return ((l_f + m_f) * p_lm1 - l_f * x * p_l) / oneminus_x2;
    }

    // Fall back: 5-point central difference (clipped to keep |x ± 2h| ≤ 1)
    let h = 1.0e-4_f64;
    let x_use = x.clamp(-1.0 + 8.0 * h, 1.0 - 8.0 * h);
    let f_p2 = legendre_assoc_cs(l, m, x_use + 2.0 * h);
    let f_p1 = legendre_assoc_cs(l, m, x_use + h);
    let f_m1 = legendre_assoc_cs(l, m, x_use - h);
    let f_m2 = legendre_assoc_cs(l, m, x_use - 2.0 * h);
    (-f_p2 + 8.0 * f_p1 - 8.0 * f_m1 + f_m2) / (12.0 * h)
}

/// Evaluate the spheroidal angular function `S_{m,n}(c, η)` of the first kind
/// using the Flammer / Bouwkamp d-coefficient expansion, normalised to match
/// SciPy's `scipy.special.pro_ang1` / `obl_ang1` convention.
///
/// The convention is **non-Condon–Shortley**: at `c = 0`,
/// `S_{m,n}(0, η) = (-1)^m · [CS-Legendre P_n^m(η)] = [un-CS Legendre P_n^m(η)]`,
/// which matches the Meixner–Schäfke normalisation of Flammer (1957) §3.1.
///
/// # Algorithm
/// 1. Compute the Flammer eigenvalue `λ` and d-coefficients (with
///    `d[k_target] = 1`).
/// 2. Form the partial sums `S_raw(η) = Σ_p d_p · P_{m+r_p}^m(η)`,
///    `S_raw'(η) = Σ_p d_p · (P_{m+r_p}^m)'(η)` in the Condon–Shortley basis.
/// 3. Determine the Meixner–Schäfke normalisation factor `K` so that
///    - even parity: `K · S_raw(0) = P_n^m(0)` (Condon–Shortley);
///    - odd  parity: `K · S_raw'(0) = (P_n^m)'(0)` (Condon–Shortley).
/// 4. Apply `(-1)^m` for the SciPy non-CS convention.
///
/// Returns `(S, S')`.
///
/// # Errors
/// - [`SpecialError::DomainError`] if `(m, n)` invalid or `|η| > 1`.
/// - [`SpecialError::ComputationError`] if d-coefficients fail to converge.
pub fn angular_function(
    parity_kind: SpheroidalParity,
    m: i32,
    n: i32,
    c: f64,
    eta: f64,
) -> SpecialResult<(f64, f64)> {
    if m < 0 || n < m {
        return Err(SpecialError::DomainError(format!(
            "angular_function requires 0 ≤ m ≤ n, got m={m}, n={n}"
        )));
    }
    if !(-1.0..=1.0).contains(&eta) {
        return Err(SpecialError::DomainError(format!(
            "angular_function requires |η| ≤ 1, got η={eta}"
        )));
    }

    let parity = ((n - m) % 2 + 2) % 2;
    let parity_us = parity as usize;

    // c = 0 limit: S(η) = (-1)^m · CS-P_n^m(η).
    if c == 0.0 {
        let p_val = legendre_assoc_cs(n, m, eta);
        let p_der = legendre_assoc_cs_prime(n, m, eta);
        let sign_cs = if m % 2 == 0 { 1.0 } else { -1.0 };
        return Ok((sign_cs * p_val, sign_cs * p_der));
    }

    let lambda = flammer_eigenvalue(parity_kind, m, n, c, DEFAULT_D_LEN)?;
    let d = d_coefficients(parity_kind, m, n, c, lambda)?;
    let len = d.len();

    // Compute S_raw(η) and S_raw'(η) in Condon–Shortley basis
    let mut s_raw = 0.0_f64;
    let mut s_raw_prime = 0.0_f64;
    for (p, &dp) in d.iter().enumerate().take(len) {
        if dp.abs() < 1.0e-30 {
            continue;
        }
        let r = 2 * p + parity_us;
        let l = m + r as i32;
        let p_val = legendre_assoc_cs(l, m, eta);
        let p_der = legendre_assoc_cs_prime(l, m, eta);
        s_raw += dp * p_val;
        s_raw_prime += dp * p_der;
    }

    // Meixner–Schäfke normalisation factor K (CS convention)
    let k_factor = if parity == 0 {
        // even parity: match S_raw(0) ≡ P_n^m(0)
        let mut s_at_zero = 0.0_f64;
        for (p, &dp) in d.iter().enumerate().take(len) {
            if dp.abs() < 1.0e-30 {
                continue;
            }
            let r = 2 * p + parity_us;
            let l = m + r as i32;
            s_at_zero += dp * legendre_assoc_cs(l, m, 0.0_f64);
        }
        if s_at_zero.abs() < 1.0e-30 {
            return Err(SpecialError::ComputationError(format!(
                "angular_function: Meixner–Schäfke (even) anchor S(0)={s_at_zero:.3e} too small for m={m}, n={n}, c={c}"
            )));
        }
        let target = legendre_assoc_cs(n, m, 0.0_f64);
        target / s_at_zero
    } else {
        // odd parity: match S_raw'(0) ≡ (P_n^m)'(0)
        let mut sp_at_zero = 0.0_f64;
        for (p, &dp) in d.iter().enumerate().take(len) {
            if dp.abs() < 1.0e-30 {
                continue;
            }
            let r = 2 * p + parity_us;
            let l = m + r as i32;
            sp_at_zero += dp * legendre_assoc_cs_prime(l, m, 0.0_f64);
        }
        if sp_at_zero.abs() < 1.0e-30 {
            return Err(SpecialError::ComputationError(format!(
                "angular_function: Meixner–Schäfke (odd) anchor S'(0)={sp_at_zero:.3e} too small for m={m}, n={n}, c={c}"
            )));
        }
        let target = legendre_assoc_cs_prime(n, m, 0.0_f64);
        target / sp_at_zero
    };

    // Apply SciPy non-CS sign convention
    let sign_cs = if m % 2 == 0 { 1.0 } else { -1.0 };
    let scale = sign_cs * k_factor;
    Ok((scale * s_raw, scale * s_raw_prime))
}

// ───────────────────────────────────────────────────────────────────────────
// Radial function evaluation (Flammer §4.4 / A&S 21.9 / Zhang–Jin §16.4)
// ───────────────────────────────────────────────────────────────────────────

/// Spherical Bessel function selector for the radial function expansion.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum SphericalBesselKind {
    /// First kind `j_l(x)` — regular at `x = 0`. Used by `R_{mn}^{(1)}`.
    First,
    /// Second kind `y_l(x)` — singular at `x = 0`. Used by `R_{mn}^{(2)}`.
    Second,
}

/// Compute spherical Bessel value `z_l(x)` and derivative `(d/dx) z_l(x)` for
/// the requested kind. The derivative uses the recurrence
///
/// ```text
///   (d/dx) z_l(x) = z_{l-1}(x) - (l + 1)/x · z_l(x)
/// ```
///
/// (Abramowitz & Stegun §10.1.20).
fn spherical_bessel_pair(kind: SphericalBesselKind, l: i32, x: f64) -> (f64, f64) {
    let l_us = l;
    let z_l = match kind {
        SphericalBesselKind::First => crate::spherical_jn::<f64>(l_us, x),
        SphericalBesselKind::Second => crate::spherical_yn::<f64>(l_us, x),
    };
    if l == 0 {
        // (d/dx) z_0(x) = -z_1(x)
        let z_1 = match kind {
            SphericalBesselKind::First => crate::spherical_jn::<f64>(1, x),
            SphericalBesselKind::Second => crate::spherical_yn::<f64>(1, x),
        };
        return (z_l, -z_1);
    }
    if x == 0.0 {
        // Derivative at x=0 needs special treatment: for j_l, vanishes for l≥2;
        // for y_l, diverges. We let the caller handle x=0 boundary cases.
        return (z_l, 0.0);
    }
    let z_lm1 = match kind {
        SphericalBesselKind::First => crate::spherical_jn::<f64>(l_us - 1, x),
        SphericalBesselKind::Second => crate::spherical_yn::<f64>(l_us - 1, x),
    };
    let der = z_lm1 - ((l + 1) as f64) / x * z_l;
    (z_l, der)
}

/// Iterative computation of `κ_r = (2m + r)! / r!` to avoid factorial overflow.
fn kappa_r(m: i32, r: i32) -> f64 {
    let mut v = 1.0_f64;
    for k in (r + 1)..=(2 * m + r) {
        v *= k as f64;
    }
    v
}

/// Evaluate the spheroidal radial function `R_{mn}^{(j)}(c, ξ)` of the first
/// or second kind via the Flammer §4.4 / A&S 21.9 spherical Bessel expansion:
///
/// ```text
///   R_{mn}^{(j)}(c, ξ) = (1 / H_n^m(c)) · ((ξ² - s) / ξ²)^{m/2} ·
///                        Σ_p (-1)^{p - target} · κ_{r_p} · d_{r_p}^{mn}(c) ·
///                              z_{m + r_p}^{(j)}(c · ξ)
/// ```
///
/// where `r_p = 2p + parity`, `target = (n - m - parity) / 2`,
/// `κ_r = (2m + r)! / r!`, `s = +1` for prolate (ξ ≥ 1) and `s = -1` for oblate
/// (`ξ ≥ 0`, with the prefactor `((ξ² + 1) / ξ²)^{m/2}`), and the normalisation
///
/// ```text
///   H_n^m(c) = Σ_p κ_{r_p} · d_{r_p}^{mn}(c)
/// ```
///
/// (Flammer 4.4.6) ensures `R_{mn}^{(1)}(c, ξ) → j_n(c · ξ)` as `c → 0` for
/// `m = 0`.
///
/// # Domain
///
/// - **Prolate** (`SpheroidalParity::Prolate`): `ξ ≥ 1`. Argument passed to
///   the spherical Bessel functions is `c · ξ`.
/// - **Oblate** (`SpheroidalParity::Oblate`): `ξ ≥ 0`. Argument is `c · ξ` for
///   `ξ ≥ 1` (exterior), but for `0 ≤ ξ < 1` the modified spherical Bessel
///   functions are needed; we currently support only `ξ ≥ 1` for oblate
///   (and `ξ ≥ 0` for the exterior when `c · ξ` is real and ≥ 0).
///
/// # Errors
///
/// - [`SpecialError::DomainError`] if domain conditions are violated.
/// - [`SpecialError::ComputationError`] if the d-coefficient series fails to
///   converge or `H_n^m(c) ≈ 0`.
///
/// # Limitations
///
/// The pure spherical-Bessel expansion underlying this routine is known to be
/// numerically unstable for the **second kind** at certain odd-`m` /
/// odd-parity combinations, in particular `(m=1, n=2)` and `(m=3, n=4, 6)`
/// (Flammer §4.5 discusses an alternative integral representation that
/// remedies this). The first-kind series is robust for all `m, n, c, ξ`.
pub fn radial_function(
    parity_kind: SpheroidalParity,
    bessel_kind: SphericalBesselKind,
    m: i32,
    n: i32,
    c: f64,
    xi: f64,
) -> SpecialResult<(f64, f64)> {
    if m < 0 || n < m {
        return Err(SpecialError::DomainError(format!(
            "radial_function requires 0 ≤ m ≤ n, got m={m}, n={n}"
        )));
    }
    if c < 0.0 {
        return Err(SpecialError::DomainError(format!(
            "radial_function requires c ≥ 0, got c={c}"
        )));
    }

    match parity_kind {
        SpheroidalParity::Prolate => {
            if xi < 1.0 {
                return Err(SpecialError::DomainError(format!(
                    "prolate radial_function requires ξ ≥ 1, got ξ={xi}"
                )));
            }
        }
        SpheroidalParity::Oblate => {
            // For oblate exterior we accept ξ ≥ 0 but the argument c·ξ goes
            // through real spherical Bessel — which is fine since c, ξ ≥ 0.
            if xi < 0.0 {
                return Err(SpecialError::DomainError(format!(
                    "oblate radial_function requires ξ ≥ 0, got ξ={xi}"
                )));
            }
        }
    }

    let parity = ((n - m) % 2 + 2) % 2;
    let parity_us = parity as usize;

    let lambda = flammer_eigenvalue(parity_kind, m, n, c, DEFAULT_D_LEN)?;
    let d = d_coefficients(parity_kind, m, n, c, lambda)?;
    let len = d.len();

    let target_us = ((n - m - parity) / 2) as usize;

    // Prefactor ((ξ² - s) / ξ²)^{m/2} where s = +1 for prolate, s = -1 for oblate
    let s_pref = parity_kind.sign();
    let prefactor = if m == 0 {
        1.0_f64
    } else {
        if xi.abs() < 1.0e-30 {
            return Err(SpecialError::DomainError(
                "radial_function: prefactor singular at ξ=0 for m > 0".to_string(),
            ));
        }
        let xi2 = xi * xi;
        let arg = (xi2 - s_pref) / xi2;
        if arg < 0.0 {
            // For oblate with ξ < ?, this could happen — error out
            return Err(SpecialError::DomainError(format!(
                "radial_function: prefactor (ξ²-s)/ξ²={arg} < 0 for ξ={xi}"
            )));
        }
        arg.powf(0.5 * m as f64)
    };

    // Effective Bessel argument — prolate uses cξ, oblate also uses cξ for ξ ≥ 0
    let z_arg = c * xi;

    // First pass: build full κ_r · d_r table and compute H_norm.
    let mut kdr = vec![0.0_f64; len];
    for (p, &dp) in d.iter().enumerate().take(len) {
        let r = (2 * p + parity_us) as i32;
        kdr[p] = kappa_r(m, r) * dp;
    }
    let h_norm: f64 = kdr.iter().sum();

    if h_norm.abs() < 1.0e-30 {
        return Err(SpecialError::ComputationError(format!(
            "radial_function: normalisation H_n^m(c)={h_norm:.3e} too small for m={m}, n={n}, c={c}"
        )));
    }

    // Second pass: sum Bessel terms with bounded iteration count and
    // adaptive truncation. We use a HARD cap because the second-kind y_l
    // series grows factorially, so even though the d-coefficients decay
    // super-factorially, the *product* needs a finite truncation to avoid
    // catastrophic intermediate-term overflow.
    //
    // For the FIRST kind (`SphericalBesselKind::First`) the series converges
    // gracefully — `j_l(c·ξ)` decays like `(c·ξ)^l / (2l+1)!!` for `l > c·ξ`,
    // so there's no overflow risk. We use the full d-coefficient length.
    //
    // For the SECOND kind (`SphericalBesselKind::Second`), `y_l(c·ξ)` grows
    // like `(2l-1)!! / (c·ξ)^{l+1}`, so the safe truncation is roughly
    // `p_max = max(target + 8, n + 6)` — empirically sufficient to converge
    // for `|c·ξ| ≥ 1` and `n ≤ 30`.
    //
    // Standard truncation criteria (within the cap):
    //   (a) `|term| < term_floor · running_max` for ≥ 4 consecutive p, or
    //   (b) `z_l` is non-finite (overflow).
    // Truncation strategy depends on Bessel kind:
    // - First kind: j_l decays factorially in l once l > c·ξ; we let the
    //   adaptive convergence test (term magnitude relative to running max)
    //   stop the loop. No hard cap.
    // - Second kind: y_l grows factorially; the d-coefficients eventually
    //   overcompensate, but for small c·ξ the regime where d·y is decreasing
    //   is reached too late to be numerically usable. We cap at
    //   `2·n + 8` terms for second kind. This is a deliberate trade-off
    //   between coverage and accuracy: tests show this gives ≥ 4 digits
    //   for `c·ξ ≥ 1` and `m = 0`.
    let max_iter = match bessel_kind {
        SphericalBesselKind::First => len,
        SphericalBesselKind::Second => (2 * n as usize + 8).min(len),
    };

    let mut numerator = 0.0_f64;
    let mut numerator_prime = 0.0_f64;
    let term_floor: f64 = 1.0e-15;
    let mut max_seen: f64 = 0.0;
    let mut consecutive_below = 0;

    for (p, &kd) in kdr.iter().enumerate().take(max_iter) {
        if kd == 0.0 {
            continue;
        }
        let r = (2 * p + parity_us) as i32;
        let l = m + r;
        let phase = if (p as i32 - target_us as i32).rem_euclid(2) == 0 {
            1.0
        } else {
            -1.0
        };
        let coef = phase * kd;

        let (z_val, z_der) = spherical_bessel_pair(bessel_kind, l, z_arg);
        if !z_val.is_finite() || !z_der.is_finite() {
            break;
        }
        let term = coef * z_val;
        let term_p = coef * c * z_der;
        let abs_term = term.abs();

        if abs_term > max_seen {
            max_seen = abs_term;
        }

        numerator += term;
        numerator_prime += term_p;

        // Adaptive convergence break (first-kind primarily).
        if max_seen > 0.0 && abs_term < term_floor * max_seen && p >= target_us + 6 {
            consecutive_below += 1;
            if consecutive_below >= 4 {
                break;
            }
        } else {
            consecutive_below = 0;
        }
    }

    // Apply prefactor and 1/H_n^m (h_norm guarded above)
    let r_value = prefactor * numerator / h_norm;

    // Derivative of `prefactor · numerator / H` w.r.t. ξ:
    //   = prefactor' · numerator/H + prefactor · numerator'/H
    //   prefactor = ((ξ²-s)/ξ²)^{m/2} = (1 - s/ξ²)^{m/2}
    //   prefactor' = (m/2) · (1 - s/ξ²)^{m/2 - 1} · (2s/ξ³)
    let prefactor_prime = if m == 0 {
        0.0
    } else {
        let xi2 = xi * xi;
        let base = 1.0 - s_pref / xi2;
        if base.abs() < 1.0e-30 {
            0.0
        } else {
            0.5 * m as f64 * base.powf(0.5 * m as f64 - 1.0) * (2.0 * s_pref / (xi2 * xi))
        }
    };
    let r_derivative = prefactor_prime * numerator / h_norm + prefactor * numerator_prime / h_norm;

    Ok((r_value, r_derivative))
}

/// Compute the spheroidal characteristic value `λ_{mn}(c)` directly from the
/// Flammer recurrence tridiagonal eigenproblem.
///
/// This is the "ground-truth" eigenvalue that downstream consumers
/// ([`d_coefficients`], the angular and radial wave functions) all use.
///
/// # Errors
///
/// Returns [`SpecialError::DomainError`] for invalid `(m, n)` and
/// [`SpecialError::ComputationError`] if the QR iteration cannot locate the
/// target eigenvalue.
pub fn flammer_eigenvalue(
    parity_kind: SpheroidalParity,
    m: i32,
    n: i32,
    c: f64,
    len: usize,
) -> SpecialResult<f64> {
    if m < 0 || n < m {
        return Err(SpecialError::DomainError(format!(
            "flammer_eigenvalue requires 0 ≤ m ≤ n, got m={m}, n={n}"
        )));
    }
    if len < 4 {
        return Err(SpecialError::DomainError(
            "flammer_eigenvalue length must be ≥ 4".to_string(),
        ));
    }

    if c == 0.0 {
        return Ok(n as f64 * (n as f64 + 1.0));
    }

    let parity = ((n - m) % 2 + 2) % 2;
    let k_target = ((n - m - parity) / 2) as usize;
    if k_target >= len {
        return Err(SpecialError::DomainError(format!(
            "flammer_eigenvalue truncation len={len} too small for n={n}, m={m}"
        )));
    }

    let (diag, off_sym, _scale) = build_flammer_tridiag(parity_kind, m, n, c, len);
    let eigs = tridiag_eigenvalues(&diag, &off_sym);
    eigs.get(k_target).copied().ok_or_else(|| {
        SpecialError::ComputationError(format!(
            "flammer_eigenvalue: target eigenvalue {k_target} not found"
        ))
    })
}

/// Estimate a pessimistic upper bound on the next-coefficient ratio
/// `|d_{r+2} / d_r|` for very large `r` via Lentz-CF. Used by callers that
/// want a fast convergence check before committing to a full backward sweep.
///
/// The CF is built directly from the Flammer recurrence at index `start_k`
/// (i.e., `r = 2·start_k + parity`).
///
/// This is exposed so the `lentz_cf_*` integration tests can exercise it.
pub fn tail_ratio_lentz(
    parity_kind: SpheroidalParity,
    m: i32,
    n: i32,
    c: f64,
    lambda: f64,
    start_k: usize,
) -> SpecialResult<f64> {
    let m_f = m as f64;
    let parity = ((n - m) % 2 + 2) % 2;
    let parity_f = parity as f64;
    let s = parity_kind.sign();
    let c2_signed = c * c * s;

    if c2_signed == 0.0 {
        return Ok(0.0);
    }

    // From the recurrence written as a CF for r_p = d_{p+1} / d_p:
    //   α_p+1 · d_{p+1} + (β_p − λ) · d_p + γ_p−1 · d_{p−1} = 0
    //   ratio r_p = d_{p+1} / d_p
    // Rearranged:
    //   r_p = -(β_p − λ + γ_p_down · 1/r_{p-1}) / α_p_up
    // For Lentz form we use the equivalent
    //   r_p = -α_p_up^{-1} · (β_p − λ) - α_p_up^{-1} γ_p_down / r_{p-1}
    let r_at = |k: usize| -> f64 { 2.0 * k as f64 + parity_f };
    let beta_at = |k: usize| -> f64 { flammer_beta(m_f, r_at(k), c2_signed) - lambda };
    let alpha_at = |k: usize| -> f64 { flammer_alpha_up(m_f, r_at(k), c2_signed) };
    let gamma_at = |k: usize| -> f64 { flammer_gamma_down(m_f, r_at(k), c2_signed) };

    // CF for r_K via downward propagation:
    //   r_K = -α_{K+1}^{-1} (β_K − λ) - α_{K+1}^{-1} γ_K / r_{K-1}? Actually we go up:
    //   At index k, eqn: α_up(k) d_{k+1} = -(β-λ) d_k - γ_down(k) d_{k-1}
    //   ⇒ r_k = d_{k+1}/d_k = -[(β-λ) + γ_down(k) · (1/r_{k-1})] / α_up(k)
    //
    // Reading downward (k = M, M-1, ..., start_k+1) gives us r_{start_k}.
    //
    // We use Lentz with b_n = (β-λ) at level (start_k + n), a_n = -γ_down(start_k+n)·α_up(start_k+n-1)?
    //
    // The cleanest form: write the CF for `f = -1/r_{start_k}` as
    //   f = (β_{start_k}-λ)/α_{start_k} + γ_{start_k}/α_{start_k} · 1/( ... )
    // Iterating recursively gives a clean Lentz form.
    let result = cf_modified_lentz(
        |idx: usize| {
            if idx == 0 {
                0.0
            } else {
                let k = start_k + idx;
                // a_n = -γ_down(k) · γ_down(k-1) / [α_up(k-1)·α_up(k-2)] approximation...
                // We use the simpler (but correct) form: a_n = ...
                // For a 2-step recurrence written as r_k = b_n + a_n / r_{k+1}, with
                //   r_k_up = -[(β_k - λ) + γ_down(k+1)/r_{k+1}_up] / α_up(k)
                // Rearrange α_up(k) r_k = -(β_k - λ) - γ_down(k+1)/r_{k+1}
                // Define R_k = -α_up(k) r_k:
                //   R_k = (β_k - λ) + γ_down(k+1)/r_{k+1} = (β_k - λ) + γ_down(k+1) · α_up(k+1) / R_{k+1} · (-1)
                //        = (β_k - λ) - γ_down(k+1) · α_up(k+1) / R_{k+1}
                // So with R = b_n + a_n / R_{n+1}, we have:
                //   b_n = β_k - λ        (at k = start_k + n - 1 in Lentz indexing)
                //   a_n = -γ_down(k+1) · α_up(k+1)  with k+1 corresponding to next level
                // Set the convention: for n = 1, this is the equation at k = start_k.
                let level = start_k + idx - 1;
                -gamma_at(level + 1) * alpha_at(level)
            }
        },
        |idx: usize| {
            if idx == 0 {
                0.0
            } else {
                let level = start_k + idx - 1;
                beta_at(level)
            }
        },
    )?;

    // result = R_{start_k} = -α_up(start_k) · r_{start_k}
    // So r_{start_k} = -result / α_up(start_k).
    let alpha_start = alpha_at(start_k);
    if alpha_start.abs() < f64::MIN_POSITIVE * 1.0e6 {
        return Err(SpecialError::ConvergenceError(
            "tail_ratio_lentz: α_up(start_k) too small".to_string(),
        ));
    }
    Ok(-result.value / alpha_start)
}

#[cfg(test)]
mod tests {
    use super::*;
    use approx::assert_abs_diff_eq;

    /// Simple geometric continued fraction:
    ///   tan(x) = x / (1 - x²/(3 - x²/(5 - ...)))
    /// This serves as a baseline correctness check for [`cf_modified_lentz`].
    #[test]
    fn cf_lentz_evaluates_tan_via_cf() {
        let x: f64 = 0.5;
        let x2 = x * x;
        let cf = cf_modified_lentz(
            |n| if n == 0 { 0.0 } else { -x2 },
            |n| if n == 0 { 1.0 } else { (2 * n + 1) as f64 },
        )
        .expect("Lentz CF failed for tan");
        let tan_via_cf = x / cf.value;
        assert_abs_diff_eq!(tan_via_cf, x.tan(), epsilon = 1e-12);
    }

    /// d_coefficients at c=0 must collapse to the unit vector at the main index.
    #[test]
    fn d_coefficients_c_zero_matches_legendre_limit() {
        for n in 0..6 {
            let lam = n as f64 * (n as f64 + 1.0);
            let d = d_coefficients(SpheroidalParity::Prolate, 0, n, 0.0, lam).expect("d coef c=0");
            let parity = (n % 2) as usize;
            let target = ((n as usize) - parity) / 2;
            for (k, &dk) in d.iter().enumerate() {
                if k == target {
                    assert!((dk - 1.0).abs() < 1e-12, "d[target]=1 expected, got {dk}");
                } else {
                    assert!(dk.abs() < 1e-10, "d[{k}]={dk} should be 0 at c=0");
                }
            }
        }
    }

    /// `tail_ratio_lentz` at `c=0` must be exactly zero — no coupling means
    /// off-target coefficients are zero.
    #[test]
    fn tail_ratio_lentz_c_zero_is_zero() {
        let r = tail_ratio_lentz(SpheroidalParity::Prolate, 0, 1, 0.0, 2.0, 5)
            .expect("tail ratio should succeed at c=0");
        assert_abs_diff_eq!(r, 0.0, epsilon = 1e-15);
    }

    /// `scaled_recurrence_step` should rescale exactly once when values blow up.
    #[test]
    fn scaled_recurrence_step_handles_overflow() {
        let mut values = [1.0e160_f64, 5.0e159, -2.0e160];
        let mut log_scale = 0.0_f64;
        let did = scaled_recurrence_step(&mut values, &mut log_scale);
        assert!(did);
        assert!(values.iter().all(|v| v.abs() < 1.0e150));
        assert!(log_scale > 0.0);
    }

    #[test]
    fn scaled_recurrence_step_handles_underflow() {
        let mut values = [1.0e-160_f64, -3.0e-160, 2.0e-161];
        let mut log_scale = 0.0_f64;
        let did = scaled_recurrence_step(&mut values, &mut log_scale);
        assert!(did);
        assert!(values.iter().all(|v| v.abs() > 1.0e-160));
        assert!(log_scale < 0.0);
    }

    /// Eigenvalue λ_{mn}(c) for a few cases against the SciPy reference.
    /// SciPy values: `pro_cv(0,2,1.0)=6.5334718`, `obl_cv(0,2,1.0)=5.4868000`.
    /// Tolerance 1e-7 reflects the iterative tridiagonal eigensolver's QR
    /// shift-strategy convergence — Wilkinson shifts give ~6 to 8 digits
    /// for a single target eigenvalue.
    #[test]
    fn flammer_eigenvalue_matches_scipy_reference() {
        let lam = flammer_eigenvalue(SpheroidalParity::Prolate, 0, 2, 1.0, 60)
            .expect("flammer_eigenvalue prolate");
        assert_abs_diff_eq!(lam, 6.5334718005, epsilon = 1.0e-7);

        let lam = flammer_eigenvalue(SpheroidalParity::Oblate, 0, 2, 1.0, 60)
            .expect("flammer_eigenvalue oblate");
        assert_abs_diff_eq!(lam, 5.4868000164, epsilon = 1.0e-7);
    }
}