Skip to main content

bessel_zeros/
lib.rs

1//! # Bessel Zeros
2//!
3//! A crate for finding the zeros of the Bessel functions.
4//!
5//! This crate uses the routine described in:
6//! "An Algorithm with ALGOL 60 Program for the Computation of the
7//! zeros of the Ordinary Bessel Functions and those of their
8//! Derivatives".
9//! N. M. Temme
10//! Journal of Computational Physics, 32, 270-279 (1979)
11//!
12//! This crate is inspired by (via several intermediate steps)
13//! Adam Wyatt's Matlab version of this code.
14//!
15//! ## Backends
16//!
17//! Two backends are available:
18//!
19//! | Backend | Module / functions | Order type | Speed |
20//! |---|---|---|---|
21//! | AMOS (`amos-bessel-rs`) | crate root | any `f64`-compatible | slower |
22//! | real-bessel | [`fast`] sub-module | `i32` only | faster |
23//!
24//! ## Primary API (AMOS backend — any real order)
25//!
26//! - [`bessel_zeros_j`]
27//! - [`bessel_zeros_y`]
28//! - [`bessel_zeros_jp`]
29//! - [`bessel_zeros_yp`]
30//! - [`bessel_zeros`] — lower-level, accepts a [`BesselFunType`] and custom precision
31//!
32//! ## Fast API (real-bessel backend — integer orders only)
33//!
34//! Use the [`fast`] sub-module for the same functions with integer orders:
35//!
36//! ```rust
37//! use bessel_zeros::fast;
38//!
39//! let zeros = fast::bessel_zeros_j(0, 5);
40//! assert_eq!(zeros.len(), 5);
41//! assert!((zeros[0] - 2.40482555769577).abs() < 1e-10);
42//! ```
43//!
44//! ## Example (AMOS backend, non-integer order)
45//!
46//! ```rust
47//! use bessel_zeros::bessel_zeros_j;
48//!
49//! let zeros = bessel_zeros_j(0.5_f64, 5);
50//! assert_eq!(zeros.len(), 5);
51//! ```
52
53#![warn(missing_docs, clippy::all, clippy::pedantic)]
54#![allow(
55    clippy::cast_possible_truncation,
56    clippy::cast_possible_wrap,
57    clippy::cast_precision_loss
58)]
59#![cfg_attr(not(feature = "std"), no_std)]
60
61#[macro_use]
62extern crate alloc;
63
64use alloc::vec::Vec;
65#[cfg(not(feature = "std"))]
66use num::Float;
67
68pub(crate) mod algorithm;
69pub(crate) mod backend;
70
71use algorithm::bessel_zeros_impl;
72use backend::amos::AmosBackend;
73
74/// Default relative error tolerance used by the convenience functions
75/// ([`bessel_zeros_j`], [`bessel_zeros_y`], [`bessel_zeros_jp`], [`bessel_zeros_yp`]).
76/// Pass a custom value to [`bessel_zeros`] if you need different precision.
77pub const DEFAULT_PRECISION: f64 = 1e-14;
78
79/// The type of Bessel function of which to find the zeros.
80#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
81pub enum BesselFunType {
82    /// Bessel function of the first kind, Jv(x)
83    J,
84    /// Bessel function of the second kind, Yv(x)
85    Y,
86    /// Derivative of the Bessel function of the first kind, Jv'(x)
87    JP,
88    /// Derivative of the Bessel function of the second kind, Yv'(x)
89    YP,
90}
91
92impl BesselFunType {
93    pub(crate) fn is_non_derivative(self) -> bool {
94        self == BesselFunType::J || self == BesselFunType::Y
95    }
96}
97
98/// Calculates the zeros of the Bessel function of the given kind and `order`.
99///
100/// Note: this general-purpose AMOS-backed function is only defined for non-negative
101/// `order` (`order >= 0.0`). If you need zeros for a negative integer order, use the
102/// integer-only [`fast::bessel_zeros`] function instead, or pass the absolute value
103/// of the order (since J₋ₙ and Y₋ₙ have identical zeros to their positive counterparts).
104///
105/// # Arguments the AMOS backend; `order` can be any type that converts to `f64`
106/// (e.g. `f64`, `f32`, `i32`, `u32`).
107pub fn bessel_zeros_j<OT: Into<f64>>(order: OT, n_zeros: usize) -> Vec<f64> {
108    bessel_zeros(BesselFunType::J, order, n_zeros, DEFAULT_PRECISION)
109}
110
111/// Finds the first `n_zeros` zeros of the Bessel function of the second kind Yv(x).
112///
113/// Uses the AMOS backend; `order` can be any type that converts to `f64`.
114pub fn bessel_zeros_y<OT: Into<f64>>(order: OT, n_zeros: usize) -> Vec<f64> {
115    bessel_zeros(BesselFunType::Y, order, n_zeros, DEFAULT_PRECISION)
116}
117
118/// Finds the first `n_zeros` zeros of the derivative of Jv(x).
119///
120/// Uses the AMOS backend; `order` can be any type that converts to `f64`.
121pub fn bessel_zeros_jp<OT: Into<f64>>(order: OT, n_zeros: usize) -> Vec<f64> {
122    bessel_zeros(BesselFunType::JP, order, n_zeros, DEFAULT_PRECISION)
123}
124
125/// Finds the first `n_zeros` zeros of the derivative of Yv(x).
126///
127/// Uses the AMOS backend; `order` can be any type that converts to `f64`.
128pub fn bessel_zeros_yp<OT: Into<f64>>(order: OT, n_zeros: usize) -> Vec<f64> {
129    bessel_zeros(BesselFunType::YP, order, n_zeros, DEFAULT_PRECISION)
130}
131
132/// Finds the first `n_zeros` zeros of the specified Bessel function.
133///
134/// Uses the AMOS backend, so `order` may be any real value (not just integer).
135///
136/// Note: The Temme algorithm is only valid for positive orders. Negative integer orders
137/// happen to be the same a positive integers, so the algorithm works in that special case
138///
139/// # Panics
140///
141/// Panics on non-integer negative orders
142///
143/// # Arguments
144///
145/// * `func_type` - Which Bessel function (J, Y, J', Y').
146/// * `order`     - The order (must be ≥ 0); any type convertible to `f64`.
147/// * `n_zeros`   - Number of zeros to return.
148/// * `precision` - Relative error tolerance on each root.
149pub fn bessel_zeros<OT: Into<f64>>(
150    kind: BesselFunType,
151    order: OT,
152    n_zeros: usize,
153    precision: f64,
154) -> Vec<f64> {
155    let mut order_f64 = order.into();
156    if order_f64.fract() == 0.0 {
157        order_f64 = order_f64.abs();
158    }
159    assert!(
160        order_f64 >= 0.0,
161        "bessel_zeros requires order >= 0.0 or integer order"
162    );
163    bessel_zeros_impl::<AmosBackend>(kind, order_f64, n_zeros, precision)
164}
165
166/// Fast Bessel zero computation using the `real-bessel` backend.
167///
168/// This module mirrors the crate-root API ([`bessel_zeros_j`], [`bessel_zeros_y`],
169/// [`bessel_zeros_jp`], [`bessel_zeros_yp`], [`bessel_zeros`]) but uses the
170/// [`real_bessel`] crate internally. It is significantly faster than the AMOS
171/// backend but is restricted to **integer orders** (`i32`).
172///
173/// For non-integer orders use the crate-root functions directly.
174///
175/// # Example
176///
177/// ```rust
178/// use bessel_zeros::fast;
179///
180/// let zeros = fast::bessel_zeros_j(0, 5);
181/// assert!((zeros[0] - 2.40482555769577).abs() < 1e-10);
182/// ```
183pub mod fast {
184    use crate::backend::real::RealBackend;
185    use crate::{BesselFunType, DEFAULT_PRECISION, algorithm::bessel_zeros_impl};
186    use alloc::vec::Vec;
187
188    /// Finds the first `n_zeros` zeros of Jn(x) using the fast real-bessel backend.
189    /// Order must be an integer (`i32`).
190    #[must_use]
191    pub fn bessel_zeros_j(order: i32, n_zeros: usize) -> Vec<f64> {
192        bessel_zeros(BesselFunType::J, order, n_zeros, DEFAULT_PRECISION)
193    }
194
195    /// Finds the first `n_zeros` zeros of Yn(x) using the fast real-bessel backend.
196    /// Order must be an integer (`i32`).
197    #[must_use]
198    pub fn bessel_zeros_y(order: i32, n_zeros: usize) -> Vec<f64> {
199        bessel_zeros(BesselFunType::Y, order, n_zeros, DEFAULT_PRECISION)
200    }
201
202    /// Finds the first `n_zeros` zeros of Jn'(x) using the fast real-bessel backend.
203    /// Order must be an integer (`i32`).
204    #[must_use]
205    pub fn bessel_zeros_jp(order: i32, n_zeros: usize) -> Vec<f64> {
206        bessel_zeros(BesselFunType::JP, order, n_zeros, DEFAULT_PRECISION)
207    }
208
209    /// Finds the first `n_zeros` zeros of Yn'(x) using the fast real-bessel backend.
210    /// Order must be an integer (`i32`).
211    #[must_use]
212    pub fn bessel_zeros_yp(order: i32, n_zeros: usize) -> Vec<f64> {
213        bessel_zeros(BesselFunType::YP, order, n_zeros, DEFAULT_PRECISION)
214    }
215
216    /// Calculates the zeros of the Bessel function for integer orders using `real-bessel`.
217    ///
218    /// This fast integer-only algorithm fully supports negative integer orders. The zeros of
219    /// J₋ₙ and Y₋ₙ are mathematically identical to the zeros of Jₙ and Yₙ.
220    ///
221    /// # Arguments
222    ///
223    /// * `func_type` - Which Bessel function (J, Y, J', Y').
224    /// * `order`     - The order (must be a non-negative integer).
225    /// * `n_zeros`   - Number of zeros to return.
226    /// * `precision` - Relative error tolerance on each root.
227    #[must_use]
228    pub fn bessel_zeros(
229        kind: super::BesselFunType,
230        order: i32,
231        n_zeros: usize,
232        precision: f64,
233    ) -> Vec<f64> {
234        bessel_zeros_impl::<RealBackend>(kind, f64::from(order).abs(), n_zeros, precision)
235    }
236}