ellip 1.1.0

Elliptic integrals for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159

/*
 * Ellip is licensed under The 3-Clause BSD, see LICENSE.
 * Copyright 2025 Sira Pornsiriprasert <code@psira.me>
 */

#![cfg_attr(not(any(test, feature = "std")), no_std)]
#![cfg_attr(feature = "test_force_fail", allow(unused))]
#![allow(clippy::excessive_precision)]
//! # Ellip - Elliptic integrals for Rust
//!
//! **Ellip** is a pure-Rust implementation of [elliptic integrals](https://dlmf.nist.gov/19).
//! This means there is no dependence on C++ libraries. Ellip also provides less common
//! functions like Bulirsch's `cel` and `el`. Some applications of elliptic integrals include
//! computing the [lengths of plane curves](https://dlmf.nist.gov/19.30), magnetic field from
//! magnets of various shapes (e.g., [cylindrical](https://doi.org/10.1016/j.jmmm.2018.02.003)),
//! [astrophysics](https://dx.doi.org/10.1088/0004-637X/696/2/1616), and [string theory](https://dx.doi.org/10.1088/1126-6708/2004/03/004).
//!
//! Use [Ellip-Rayon](https://github.com/p-sira/ellip/tree/main/ellip-rayon) to parallelize and improve
//! performance for large inputs. Ellip is also available for Python via [EllipPy](https://github.com/p-sira/ellippy).
//!
//! ## Example
//! Calculating the perimeter of an ellipse.
//! ```
//! use ellip::*;
//!
//! fn ellipse_perimeter(a: f64, b: f64) -> Result<f64, StrErr> {
//!     Ok(8.0 * elliprg(0.0, a * a, b * b)?)
//! }
//!
//! // Example: ellipse with semi-major axis 5, semi-minor axis 3
//! println!("{}", ellipse_perimeter(5.0, 3.0).unwrap()); // 25.526998863398124
//! ```
//!
//! # Features
//! ## Legendre's complete integrals
//! - [fn@ellipk]: Complete elliptic integral of the first kind (K).
//! - [fn@ellipe]: Complete elliptic integral of the second kind (E).
//! - [fn@ellippi]: Complete elliptic integral of the third kind (Π).
//! - [fn@ellipd]: Complete elliptic integral of Legendre's type (D).
//! ## Legendre's incomplete integrals
//! - [fn@ellipf]: Incomplete elliptic integral of the first kind (F).
//! - [fn@ellipeinc]: Incomplete elliptic integral of the second kind (E).
//! - [fn@ellippiinc]: Incomplete elliptic integral of the third kind (Π).
//! - [fn@ellippiinc_bulirsch]: Faster implementation of [fn@ellippiinc].
//! - [fn@ellipdinc]: Incomplete elliptic integral of Legendre's type (D).
//! ## Bulirsch's integrals
//! - [fn@cel]: General complete elliptic integral in Bulirsch's form.
//! - [fn@cel1]: Complete elliptic integral of the first kind in Bulirsch's form.
//! - [fn@cel2]: Complete elliptic integral of the second kind in Bulirsch's form.
//! - [fn@el1]: Incomplete elliptic integral of the first kind in Bulirsch's form.
//! - [fn@el2]: Incomplete elliptic integral of the second kind in Bulirsch's form.
//! - [fn@el3]: Incomplete elliptic integral of the third kind in Bulirsch's form.
//! ## Carlson's symmetric integrals
//! - [fn@elliprf]: Symmetric elliptic integral of the first kind (RF).
//! - [fn@elliprg]: Symmetric elliptic integral of the second kind (RG).
//! - [fn@elliprj]: Symmetric elliptic integral of the third kind (RJ).
//! - [fn@elliprc]: Degenerate elliptic integral of RF (RC).
//! - [fn@elliprd]: Degenerate elliptic integral of the third kind (RD).
//! ## Miscellaneous functions
//! - [fn@jacobi_zeta]: Jacobi Zeta function (Z).
//! - [fn@heuman_lambda]: Heuman Lambda function (Λ0).
//! ## Feature Flags
//! - `unstable`: Enable unstable or untested features that might be changed without notice in the future.
//! - `test_force_fail`: Used for testing only. Force tests to reach code unreachable under normal circumstances.
//!
//! # Testing
//! The function results are compared with Boost Math test data and Wolfram Engine test data.
//! The accuracy report and the test data along with the test generation scripts can
//! be found [here](https://github.com/p-sira/ellip/blob/main/tests).
//!
//! # Acknowledgment
//! Ellip is derived from multiple mathematic libraries. We thank
//! the opensource contributors for making mathematic libraries free for all.
//! Following are the main original works used in the development of Ellip.
//! Detailed credits are available in the source code.
//! - [SciPy](https://github.com/scipy/scipy/)
//! - [Cephes Math Library](https://netlib.org/cephes/)
//! - [Boost Math Library](https://www.boost.org/doc/libs/release/libs/math/)
//! - [Russell Lab](https://github.com/cpmech/russell)
//!
//! References for original implementations are:
//! - NIST Digital Library, [Chapter 19: Elliptic Integrals](https://dlmf.nist.gov/19) (Carlson, 2025).
//! - Numerical calculation of elliptic integrals and elliptic functions [I](https://link.springer.com/article/10.1007/BF01397975) (Bulirsch, 1965), [II](https://doi.org/10.1007/BF01436529) (Bulirsch, 1965), and [III](https://doi.org/10.1007/BF02165405) (Bulirsch, 1969).
//! - NIST Digital Library, [Chapter 22 Jacobian Elliptic Functions](https://dlmf.nist.gov/22) (Reinhardt and Walker, 2025).
//!
//! Unicode-style mathematical notation are created using [Diagon](https://github.com/ArthurSonzogni/Diagon).
//!
//! # Citation
//! The paper describing Ellip is published in the [Journal of Open Source Software](https://joss.theoj.org/papers/10.21105/joss.09386). If Ellip is helpful to your work, please consider citing it:
//!
//! ```text
//! Pornsiriprasert, S., (2026). Ellip: An Elliptic Integral Library for Rust. Journal of Open Source Software, 11(118), 9386, https://doi.org/10.21105/joss.09386
//! ```
//!
//! Bibtex format:
//!
//! ```bibtex
//! @article{Pornsiriprasert2026,
//!     doi = {10.21105/joss.09386},
//!    url = {https://doi.org/10.21105/joss.09386},
//!    year = {2026},
//!    publisher = {The Open Journal},
//!    volume = {11}, number = {118}, pages = {9386},
//!    author = {Pornsiriprasert, Sira},
//!    title = {Ellip: An Elliptic Integral Library for Rust},
//!    journal = {Journal of Open Source Software} }
//! ```

num_lazy::declare_nums! {@constant T}
num_lazy::declare_nums! {@special T}

mod crate_util;

/// Static error str
pub type StrErr = &'static str;

pub mod legendre;
// Legendre's complete integrals
pub use legendre::ellipd;
pub use legendre::ellipe;
pub use legendre::ellipk;
pub use legendre::ellippi;

// Legendre's incomplete integrals
pub use legendre::ellipdinc;
pub use legendre::ellipeinc;
pub use legendre::ellipf;
pub use legendre::ellippiinc;
pub use legendre::ellippiinc_bulirsch;

// Bulirsch's integrals
pub mod bulirsch;
pub use bulirsch::cel;
pub use bulirsch::cel1;
pub use bulirsch::cel2;
pub use bulirsch::el1;
pub use bulirsch::el2;
pub use bulirsch::el3;

// Carlson's symmetric integrals
pub mod carlson;
pub use carlson::elliprc;
pub use carlson::elliprd;
pub use carlson::elliprf;
pub use carlson::elliprg;
pub use carlson::elliprj;

// Miscellaneous functions
pub mod misc;
pub use misc::heuman_lambda;
pub use misc::jacobi_zeta;

// Utilities
mod polyeval;
use polyeval::polyeval;
pub mod util;

#[cfg(test)]
mod test_util;