Skip to main content

mathverse_complex/
lib.rs

1//! Complex numbers over `f64`.
2//!
3//! Division by zero and `ln(0)` etc. yield `NaN`/`inf` components, mirroring
4//! std float semantics (no panics).
5
6use core::ops::{Add, Div, Mul, Neg, Sub};
7
8pub mod analysis;
9pub mod special_functions;
10pub mod matrix;
11
12pub use analysis::ComplexAnalysis;
13pub use special_functions::ComplexSpecialFunctions;
14pub use matrix::ComplexMatrix;
15
16/// Complex number `re + im·i`.
17#[derive(Debug, Clone, Copy, PartialEq)]
18pub struct Complex {
19    pub re: f64,
20    pub im: f64,
21}
22
23impl Complex {
24    pub fn new(re: f64, im: f64) -> Complex {
25        Complex { re, im }
26    }
27    pub fn real(r: f64) -> Complex {
28        Complex { re: r, im: 0.0 }
29    }
30    pub fn i() -> Complex {
31        Complex { re: 0.0, im: 1.0 }
32    }
33    /// Zero constant (0 + 0i).
34    pub fn zero() -> Complex {
35        Complex { re: 0.0, im: 0.0 }
36    }
37    /// One constant (1 + 0i).
38    pub fn one() -> Complex {
39        Complex { re: 1.0, im: 0.0 }
40    }
41    /// From polar form `r·e^(iθ)`.
42    pub fn polar(r: f64, theta: f64) -> Complex {
43        Complex::new(r * theta.cos(), r * theta.sin())
44    }
45    pub fn conjugate(&self) -> Complex {
46        Complex::new(self.re, -self.im)
47    }
48    pub fn norm_sq(&self) -> f64 {
49        self.re * self.re + self.im * self.im
50    }
51    pub fn norm(&self) -> f64 {
52        self.norm_sq().sqrt()
53    }
54    /// Principal argument in `(-π, π]`.
55    pub fn arg(&self) -> f64 {
56        self.im.atan2(self.re)
57    }
58    /// `(r, θ)` such that `self == r·e^(iθ)`.
59    pub fn to_polar(&self) -> (f64, f64) {
60        (self.norm(), self.arg())
61    }
62    pub fn is_zero(&self) -> bool {
63        self.re == 0.0 && self.im == 0.0
64    }
65    /// Principal square root.
66    ///
67    /// ```
68    /// use mathverse_complex::Complex;
69    /// let s = Complex::new(-4.0, 0.0).sqrt();
70    /// assert!((s.im - 2.0).abs() < 1e-12 && s.re.abs() < 1e-12);
71    /// ```
72    pub fn sqrt(&self) -> Complex {
73        let (r, theta) = self.to_polar();
74        Complex::polar(r.sqrt(), theta / 2.0)
75    }
76    /// `e^self`.
77    ///
78    /// ```
79    /// use mathverse_complex::Complex;
80    /// let e = Complex::new(0.0, core::f64::consts::PI).exp();
81    /// assert!((e.re + 1.0).abs() < 1e-12 && e.im.abs() < 1e-12);
82    /// ```
83    pub fn exp(&self) -> Complex {
84        let e = self.re.exp();
85        Complex::new(e * self.im.cos(), e * self.im.sin())
86    }
87    /// Principal natural logarithm.
88    pub fn ln(&self) -> Complex {
89        Complex::new(self.norm().ln(), self.arg())
90    }
91    /// `self^p = e^(p·ln self)`, principal branch.
92    pub fn pow(&self, p: Complex) -> Complex {
93        if self.is_zero() {
94            // 0^p: zero for Re(p) > 0, infinite for Re(p) < 0, undefined otherwise
95            return if p.re > 0.0 {
96                Complex::zero()
97            } else if p.re < 0.0 {
98                Complex::new(f64::INFINITY, 0.0)
99            } else {
100                Complex::new(f64::NAN, f64::NAN)
101            };
102        }
103        (p * self.ln()).exp()
104    }
105    /// `self^p` for real exponent.
106    pub fn powf(&self, p: f64) -> Complex {
107        self.pow(Complex::real(p))
108    }
109    pub fn sin(&self) -> Complex {
110        Complex::new(self.re.sin() * self.im.cosh(), self.re.cos() * self.im.sinh())
111    }
112    pub fn cos(&self) -> Complex {
113        Complex::new(self.re.cos() * self.im.cosh(), -self.re.sin() * self.im.sinh())
114    }
115    pub fn tan(&self) -> Complex {
116        self.sin() / self.cos()
117    }
118    /// Hyperbolic sine.
119    pub fn sinh(&self) -> Complex {
120        Complex::new(self.re.sinh() * self.im.cos(), self.re.cosh() * self.im.sin())
121    }
122    /// Hyperbolic cosine.
123    pub fn cosh(&self) -> Complex {
124        Complex::new(self.re.cosh() * self.im.cos(), self.re.sinh() * self.im.sin())
125    }
126    /// Hyperbolic tangent.
127    pub fn tanh(&self) -> Complex {
128        self.sinh() / self.cosh()
129    }
130    /// Inverse hyperbolic sine.
131    pub fn asinh(&self) -> Complex {
132        let s = *self;
133        (s + (s * s + Complex::real(1.0)).sqrt()).ln()
134    }
135    /// Inverse hyperbolic cosine.
136    pub fn acosh(&self) -> Complex {
137        let s = *self;
138        (s + (s + Complex::real(1.0)).sqrt() * (s - Complex::real(1.0)).sqrt()).ln()
139    }
140    /// Inverse hyperbolic tangent.
141    pub fn atanh(&self) -> Complex {
142        let s = *self;
143        ((Complex::real(1.0) + s) / (Complex::real(1.0) - s)).ln() / Complex::real(2.0)
144    }
145    /// Inverse sine.
146    pub fn asin(&self) -> Complex {
147        let s = *self;
148        -Complex::i() * (Complex::i() * s + (Complex::real(1.0) - s * s).sqrt()).ln()
149    }
150    /// Inverse cosine.
151    pub fn acos(&self) -> Complex {
152        let s = *self;
153        -Complex::i() * (s + Complex::i() * (Complex::real(1.0) - s * s).sqrt()).ln()
154    }
155    /// Inverse tangent.
156    pub fn atan(&self) -> Complex {
157        let s = *self;
158        let i = Complex::i();
159        (i / Complex::real(2.0)) * ((Complex::real(1.0) - i * s) / (Complex::real(1.0) + i * s)).ln()
160    }
161    /// Base-10 logarithm.
162    pub fn log10(&self) -> Complex {
163        self.ln() / Complex::real(10.0_f64.ln())
164    }
165    /// Base-2 logarithm.
166    pub fn log2(&self) -> Complex {
167        self.ln() / Complex::real(2.0_f64.ln())
168    }
169    /// Reciprocal (1/self).
170    pub fn recip(&self) -> Complex {
171        let d = self.norm_sq();
172        Complex::new(self.re / d, -self.im / d)
173    }
174    /// Returns true if either component is NaN.
175    pub fn is_nan(&self) -> bool {
176        self.re.is_nan() || self.im.is_nan()
177    }
178    /// Returns true if either component is infinite.
179    pub fn is_infinite(&self) -> bool {
180        self.re.is_infinite() || self.im.is_infinite()
181    }
182    /// Returns true if both components are finite.
183    pub fn is_finite(&self) -> bool {
184        self.re.is_finite() && self.im.is_finite()
185    }
186    /// Signum (sign) function: returns a complex number with same direction but unit magnitude.
187    /// Returns zero if self is zero.
188    pub fn signum(&self) -> Complex {
189        if self.is_zero() {
190            Complex::new(0.0, 0.0)
191        } else {
192            let s = *self;
193            s / Complex::real(s.norm())
194        }
195    }
196    /// Cube root.
197    pub fn cbrt(&self) -> Complex {
198        self.powf(1.0 / 3.0)
199    }
200    /// Nth root (principal branch).
201    pub fn root(&self, n: f64) -> Complex {
202        self.powf(1.0 / n)
203    }
204}
205
206impl Add for Complex {
207    type Output = Complex;
208    fn add(self, o: Complex) -> Complex {
209        Complex::new(self.re + o.re, self.im + o.im)
210    }
211}
212impl Sub for Complex {
213    type Output = Complex;
214    fn sub(self, o: Complex) -> Complex {
215        Complex::new(self.re - o.re, self.im - o.im)
216    }
217}
218impl Mul for Complex {
219    type Output = Complex;
220    fn mul(self, o: Complex) -> Complex {
221        Complex::new(self.re * o.re - self.im * o.im, self.re * o.im + self.im * o.re)
222    }
223}
224impl Div for Complex {
225    type Output = Complex;
226    fn div(self, o: Complex) -> Complex {
227        let d = o.norm_sq();
228        Complex::new((self.re * o.re + self.im * o.im) / d, (self.im * o.re - self.re * o.im) / d)
229    }
230}
231impl Neg for Complex {
232    type Output = Complex;
233    fn neg(self) -> Complex {
234        Complex::new(-self.re, -self.im)
235    }
236}
237
238impl From<f64> for Complex {
239    fn from(r: f64) -> Complex {
240        Complex::real(r)
241    }
242}
243
244impl From<(f64, f64)> for Complex {
245    fn from((re, im): (f64, f64)) -> Complex {
246        Complex::new(re, im)
247    }
248}
249
250impl<'a, 'b> Add<&'b Complex> for &'a Complex {
251    type Output = Complex;
252    fn add(self, o: &'b Complex) -> Complex {
253        Complex::new(self.re + o.re, self.im + o.im)
254    }
255}
256impl<'a, 'b> Sub<&'b Complex> for &'a Complex {
257    type Output = Complex;
258    fn sub(self, o: &'b Complex) -> Complex {
259        Complex::new(self.re - o.re, self.im - o.im)
260    }
261}
262impl<'a, 'b> Mul<&'b Complex> for &'a Complex {
263    type Output = Complex;
264    fn mul(self, o: &'b Complex) -> Complex {
265        Complex::new(self.re * o.re - self.im * o.im, self.re * o.im + self.im * o.re)
266    }
267}
268impl<'a, 'b> Div<&'b Complex> for &'a Complex {
269    type Output = Complex;
270    fn div(self, o: &'b Complex) -> Complex {
271        let d = o.norm_sq();
272        Complex::new((self.re * o.re + self.im * o.im) / d, (self.im * o.re - self.re * o.im) / d)
273    }
274}
275impl<'a> Neg for &'a Complex {
276    type Output = Complex;
277    fn neg(self) -> Complex {
278        Complex::new(-self.re, -self.im)
279    }
280}
281impl<'a> Add<f64> for &'a Complex {
282    type Output = Complex;
283    fn add(self, o: f64) -> Complex {
284        Complex::new(self.re + o, self.im)
285    }
286}
287impl<'a> Sub<f64> for &'a Complex {
288    type Output = Complex;
289    fn sub(self, o: f64) -> Complex {
290        Complex::new(self.re - o, self.im)
291    }
292}
293impl<'a> Mul<f64> for &'a Complex {
294    type Output = Complex;
295    fn mul(self, o: f64) -> Complex {
296        Complex::new(self.re * o, self.im * o)
297    }
298}
299impl<'a> Div<f64> for &'a Complex {
300    type Output = Complex;
301    fn div(self, o: f64) -> Complex {
302        Complex::new(self.re / o, self.im / o)
303    }
304}
305
306#[cfg(test)]
307mod tests {
308    use super::*;
309
310    #[test]
311    fn arithmetic() {
312        let a = Complex::new(3.0, 4.0);
313        assert_eq!(a * a.conjugate(), Complex::real(25.0));
314        assert_eq!(a + Complex::i(), Complex::new(3.0, 5.0));
315        let q = Complex::new(1.0, 1.0) / Complex::new(1.0, -1.0);
316        assert!((q.re - 0.0).abs() < 1e-12 && (q.im - 1.0).abs() < 1e-12);
317        assert_eq!(-a, Complex::new(-3.0, -4.0));
318    }
319
320    #[test]
321    fn polar_and_functions() {
322        let z = Complex::polar(2.0, core::f64::consts::FRAC_PI_2);
323        assert!((z.re - 0.0).abs() < 1e-12 && (z.im - 2.0).abs() < 1e-12);
324        assert!((Complex::new(1.0, 1.0).arg() - core::f64::consts::FRAC_PI_4).abs() < 1e-12);
325        assert!((Complex::new(1.0, 1.0).norm() - 2.0f64.sqrt()).abs() < 1e-12);
326        // ln/e round trip
327        let w = Complex::new(1.0, 2.0);
328        assert!((w.ln().exp() - w).norm() < 1e-12);
329        assert!((Complex::i().powf(2.0).re + 1.0).abs() < 1e-12);
330        assert!((Complex::new(0.5, 0.0).sin().re - 0.5f64.sin()).abs() < 1e-12);
331        assert!((Complex::i().ln().im - core::f64::consts::FRAC_PI_2).abs() < 1e-12);
332    }
333
334    #[test]
335    fn hyperbolic_functions() {
336        let z = Complex::new(1.0, 0.5);
337        let sinh = z.sinh();
338        let cosh = z.cosh();
339        // Check identity: cosh² - sinh² = 1
340        let diff = cosh * cosh - sinh * sinh;
341        assert!((diff - Complex::one()).norm() < 1e-10);
342        
343        // Test atanh
344        let z2 = Complex::new(0.5, 0.0);
345        let atanh = z2.atanh();
346        assert!((atanh.re - 0.5_f64.atanh()).abs() < 1e-10);
347    }
348
349    #[test]
350    fn inverse_trigonometric() {
351        let z = Complex::new(0.5, 0.0);
352        let asin = z.asin();
353        assert!((asin.re - 0.5_f64.asin()).abs() < 1e-10);
354        
355        let acos = z.acos();
356        assert!((acos.re - 0.5_f64.acos()).abs() < 1e-10);
357        
358        let atan = z.atan();
359        assert!((atan.re - 0.5_f64.atan()).abs() < 1e-10);
360    }
361
362    #[test]
363    fn inverse_trig_special_values() {
364        // acos(0) = π/2, atan(1) = π/4, asin(1) = π/2 (regression: sign/branch bugs)
365        let acos0 = Complex::zero().acos();
366        assert!((acos0.re - core::f64::consts::FRAC_PI_2).abs() < 1e-12);
367        assert!(acos0.im.abs() < 1e-12);
368
369        let atan1 = Complex::one().atan();
370        assert!((atan1.re - core::f64::consts::FRAC_PI_4).abs() < 1e-12);
371        assert!(atan1.im.abs() < 1e-12);
372
373        let asin1 = Complex::one().asin();
374        assert!((asin1.re - core::f64::consts::FRAC_PI_2).abs() < 1e-12);
375        assert!(asin1.im.abs() < 1e-12);
376
377        // acos(cos z) = z round trip off the real axis
378        let z = Complex::new(0.7, 0.4);
379        let round = z.cos().acos();
380        assert!((round - z).norm() < 1e-10);
381
382        // atan(tan z) = z round trip
383        let round2 = z.tan().atan();
384        assert!((round2 - z).norm() < 1e-10);
385    }
386
387    #[test]
388    fn logarithms() {
389        let z = Complex::new(10.0, 0.0);
390        let log10 = z.log10();
391        assert!((log10.re - 1.0).abs() < 1e-10);
392        
393        let z2 = Complex::new(2.0, 0.0);
394        let log2 = z2.log2();
395        assert!((log2.re - 1.0).abs() < 1e-10);
396    }
397
398    #[test]
399    fn reciprocal() {
400        let z = Complex::new(2.0, 3.0);
401        let recip = z.recip();
402        let product = z * recip;
403        assert!((product - Complex::one()).norm() < 1e-10);
404    }
405
406    #[test]
407    fn special_values() {
408        assert!(Complex::zero().is_zero());
409        assert_eq!(Complex::zero(), Complex::new(0.0, 0.0));
410        assert_eq!(Complex::one(), Complex::new(1.0, 0.0));
411        
412        let nan_z = Complex::new(f64::NAN, 0.0);
413        assert!(nan_z.is_nan());
414        
415        let inf_z = Complex::new(f64::INFINITY, 0.0);
416        assert!(inf_z.is_infinite());
417        
418        let finite_z = Complex::new(1.0, 2.0);
419        assert!(finite_z.is_finite());
420    }
421
422    #[test]
423    fn signum() {
424        let z = Complex::new(3.0, 4.0);
425        let s = z.signum();
426        assert!((s.norm() - 1.0).abs() < 1e-10);
427        assert!((s * z.norm().into() - z).norm() < 1e-10);
428        
429        assert_eq!(Complex::zero().signum(), Complex::zero());
430    }
431
432    #[test]
433    fn roots() {
434        let z = Complex::new(8.0, 0.0);
435        let cbrt = z.cbrt();
436        assert!((cbrt.re - 2.0).abs() < 1e-8);
437        
438        let z2 = Complex::new(16.0, 0.0);
439        let fourth = z2.root(4.0);
440        assert!((fourth.re - 2.0).abs() < 1e-8);
441    }
442
443    #[test]
444    fn from_implementations() {
445        let z1: Complex = 5.0.into();
446        assert_eq!(z1, Complex::real(5.0));
447        
448        let z2: Complex = (3.0, 4.0).into();
449        assert_eq!(z2, Complex::new(3.0, 4.0));
450    }
451}