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}