1// Keeps us from accidentally creating a recursive impl rather than a real one.
2#![deny(unconditional_recursion)]
3
4use core::ops::Neg;
5
6use num_traits::{Float, FloatConst, Num, NumCast};
7
8use crate::Complex;
9
10mod private {
11 use num_traits::{Float, FloatConst};
12
13 use crate::Complex;
14
15 pub trait Seal {}
16
17 impl<T> Seal for T where T: Float + FloatConst {}
18 impl<T: Float + FloatConst> Seal for Complex<T> {}
19}
20
21/// Generic trait for floating point complex numbers.
22///
23/// This trait defines methods which are common to complex floating point
24/// numbers and regular floating point numbers.
25///
26/// This trait is sealed to prevent it from being implemented by anything other
27/// than floating point scalars and [Complex] floats.
28pub trait ComplexFloat: Num + NumCast + Copy + Neg<Output = Self> + private::Seal {
29 /// The type used to represent the real coefficients of this complex number.
30 type Real: Float + FloatConst;
31
32 /// Returns `true` if this value is `NaN` and false otherwise.
33 fn is_nan(self) -> bool;
34
35 /// Returns `true` if this value is positive infinity or negative infinity and
36 /// false otherwise.
37 fn is_infinite(self) -> bool;
38
39 /// Returns `true` if this number is neither infinite nor `NaN`.
40 fn is_finite(self) -> bool;
41
42 /// Returns `true` if the number is neither zero, infinite,
43 /// [subnormal](http://en.wikipedia.org/wiki/Denormal_number), or `NaN`.
44 fn is_normal(self) -> bool;
45
46 /// Take the reciprocal (inverse) of a number, `1/x`. See also [Complex::finv].
47 fn recip(self) -> Self;
48
49 /// Raises `self` to a signed integer power.
50 fn powi(self, exp: i32) -> Self;
51
52 /// Raises `self` to a real power.
53 fn powf(self, exp: Self::Real) -> Self;
54
55 /// Raises `self` to a complex power.
56 fn powc(self, exp: Complex<Self::Real>) -> Complex<Self::Real>;
57
58 /// Take the square root of a number.
59 fn sqrt(self) -> Self;
60
61 /// Returns `e^(self)`, (the exponential function).
62 fn exp(self) -> Self;
63
64 /// Returns `2^(self)`.
65 fn exp2(self) -> Self;
66
67 /// Returns `base^(self)`.
68 fn expf(self, base: Self::Real) -> Self;
69
70 /// Returns the natural logarithm of the number.
71 fn ln(self) -> Self;
72
73 /// Returns the logarithm of the number with respect to an arbitrary base.
74 fn log(self, base: Self::Real) -> Self;
75
76 /// Returns the base 2 logarithm of the number.
77 fn log2(self) -> Self;
78
79 /// Returns the base 10 logarithm of the number.
80 fn log10(self) -> Self;
81
82 /// Take the cubic root of a number.
83 fn cbrt(self) -> Self;
84
85 /// Computes the sine of a number (in radians).
86 fn sin(self) -> Self;
87
88 /// Computes the cosine of a number (in radians).
89 fn cos(self) -> Self;
90
91 /// Computes the tangent of a number (in radians).
92 fn tan(self) -> Self;
93
94 /// Computes the arcsine of a number. Return value is in radians in
95 /// the range [-pi/2, pi/2] or NaN if the number is outside the range
96 /// [-1, 1].
97 fn asin(self) -> Self;
98
99 /// Computes the arccosine of a number. Return value is in radians in
100 /// the range [0, pi] or NaN if the number is outside the range
101 /// [-1, 1].
102 fn acos(self) -> Self;
103
104 /// Computes the arctangent of a number. Return value is in radians in the
105 /// range [-pi/2, pi/2];
106 fn atan(self) -> Self;
107
108 /// Hyperbolic sine function.
109 fn sinh(self) -> Self;
110
111 /// Hyperbolic cosine function.
112 fn cosh(self) -> Self;
113
114 /// Hyperbolic tangent function.
115 fn tanh(self) -> Self;
116
117 /// Inverse hyperbolic sine function.
118 fn asinh(self) -> Self;
119
120 /// Inverse hyperbolic cosine function.
121 fn acosh(self) -> Self;
122
123 /// Inverse hyperbolic tangent function.
124 fn atanh(self) -> Self;
125
126 /// Returns the real part of the number.
127 fn re(self) -> Self::Real;
128
129 /// Returns the imaginary part of the number.
130 fn im(self) -> Self::Real;
131
132 /// Returns the absolute value of the number. See also [Complex::norm]
133 fn abs(self) -> Self::Real;
134
135 /// Returns the L1 norm `|re| + |im|` -- the [Manhattan distance] from the origin.
136 ///
137 /// [Manhattan distance]: https://en.wikipedia.org/wiki/Taxicab_geometry
138 fn l1_norm(&self) -> Self::Real;
139
140 /// Computes the argument of the number.
141 fn arg(self) -> Self::Real;
142
143 /// Computes the complex conjugate of the number.
144 ///
145 /// Formula: `a+bi -> a-bi`
146 fn conj(self) -> Self;
147}
148
149macro_rules! forward {
150 ($( $base:ident :: $method:ident ( self $( , $arg:ident : $ty:ty )* ) -> $ret:ty ; )*)
151 => {$(
152 #[inline]
153 fn $method(self $( , $arg : $ty )* ) -> $ret {
154 $base::$method(self $( , $arg )* )
155 }
156 )*};
157}
158
159macro_rules! forward_ref {
160 ($( Self :: $method:ident ( & self $( , $arg:ident : $ty:ty )* ) -> $ret:ty ; )*)
161 => {$(
162 #[inline]
163 fn $method(self $( , $arg : $ty )* ) -> $ret {
164 Self::$method(&self $( , $arg )* )
165 }
166 )*};
167}
168
169impl<T> ComplexFloat for T
170where
171 T: Float + FloatConst,
172{
173 type Real = T;
174
175 fn re(self) -> Self::Real {
176 self
177 }
178
179 fn im(self) -> Self::Real {
180 T::zero()
181 }
182
183 fn l1_norm(&self) -> Self::Real {
184 self.abs()
185 }
186
187 fn arg(self) -> Self::Real {
188 if self.is_nan() {
189 self
190 } else if self.is_sign_negative() {
191 T::PI()
192 } else {
193 T::zero()
194 }
195 }
196
197 fn powc(self, exp: Complex<Self::Real>) -> Complex<Self::Real> {
198 Complex::new(self, T::zero()).powc(exp)
199 }
200
201 fn conj(self) -> Self {
202 self
203 }
204
205 fn expf(self, base: Self::Real) -> Self {
206 base.powf(self)
207 }
208
209 forward! {
210 Float::is_normal(self) -> bool;
211 Float::is_infinite(self) -> bool;
212 Float::is_finite(self) -> bool;
213 Float::is_nan(self) -> bool;
214 Float::recip(self) -> Self;
215 Float::powi(self, n: i32) -> Self;
216 Float::powf(self, f: Self) -> Self;
217 Float::sqrt(self) -> Self;
218 Float::cbrt(self) -> Self;
219 Float::exp(self) -> Self;
220 Float::exp2(self) -> Self;
221 Float::ln(self) -> Self;
222 Float::log(self, base: Self) -> Self;
223 Float::log2(self) -> Self;
224 Float::log10(self) -> Self;
225 Float::sin(self) -> Self;
226 Float::cos(self) -> Self;
227 Float::tan(self) -> Self;
228 Float::asin(self) -> Self;
229 Float::acos(self) -> Self;
230 Float::atan(self) -> Self;
231 Float::sinh(self) -> Self;
232 Float::cosh(self) -> Self;
233 Float::tanh(self) -> Self;
234 Float::asinh(self) -> Self;
235 Float::acosh(self) -> Self;
236 Float::atanh(self) -> Self;
237 Float::abs(self) -> Self;
238 }
239}
240
241impl<T: Float + FloatConst> ComplexFloat for Complex<T> {
242 type Real = T;
243
244 fn re(self) -> Self::Real {
245 self.re
246 }
247
248 fn im(self) -> Self::Real {
249 self.im
250 }
251
252 fn abs(self) -> Self::Real {
253 self.norm()
254 }
255
256 fn recip(self) -> Self {
257 self.finv()
258 }
259
260 // `Complex::l1_norm` uses `Signed::abs` to let it work
261 // for integers too, but we can just use `Float::abs`.
262 fn l1_norm(&self) -> Self::Real {
263 self.re.abs() + self.im.abs()
264 }
265
266 // `Complex::is_*` methods use `T: FloatCore`, but we
267 // have `T: Float` that can do them as well.
268 fn is_nan(self) -> bool {
269 self.re.is_nan() || self.im.is_nan()
270 }
271
272 fn is_infinite(self) -> bool {
273 !self.is_nan() && (self.re.is_infinite() || self.im.is_infinite())
274 }
275
276 fn is_finite(self) -> bool {
277 self.re.is_finite() && self.im.is_finite()
278 }
279
280 fn is_normal(self) -> bool {
281 self.re.is_normal() && self.im.is_normal()
282 }
283
284 forward! {
285 Complex::arg(self) -> Self::Real;
286 Complex::powc(self, exp: Complex<Self::Real>) -> Complex<Self::Real>;
287 Complex::exp2(self) -> Self;
288 Complex::log(self, base: Self::Real) -> Self;
289 Complex::log2(self) -> Self;
290 Complex::log10(self) -> Self;
291 Complex::powf(self, f: Self::Real) -> Self;
292 Complex::sqrt(self) -> Self;
293 Complex::cbrt(self) -> Self;
294 Complex::exp(self) -> Self;
295 Complex::expf(self, base: Self::Real) -> Self;
296 Complex::ln(self) -> Self;
297 Complex::sin(self) -> Self;
298 Complex::cos(self) -> Self;
299 Complex::tan(self) -> Self;
300 Complex::asin(self) -> Self;
301 Complex::acos(self) -> Self;
302 Complex::atan(self) -> Self;
303 Complex::sinh(self) -> Self;
304 Complex::cosh(self) -> Self;
305 Complex::tanh(self) -> Self;
306 Complex::asinh(self) -> Self;
307 Complex::acosh(self) -> Self;
308 Complex::atanh(self) -> Self;
309 }
310
311 forward_ref! {
312 Self::powi(&self, n: i32) -> Self;
313 Self::conj(&self) -> Self;
314 }
315}
316
317#[cfg(test)]
318mod test {
319 use crate::{
320 complex_float::ComplexFloat,
321 test::{_0_0i, _0_1i, _1_0i, _1_1i, float::close},
322 Complex,
323 };
324 use std::f64; // for constants before Rust 1.43.
325
326 fn closef(a: f64, b: f64) -> bool {
327 close_to_tolf(a, b, 1e-10)
328 }
329
330 fn close_to_tolf(a: f64, b: f64, tol: f64) -> bool {
331 // returns true if a and b are reasonably close
332 let close = (a == b) || (a - b).abs() < tol;
333 if !close {
334 println!("{:?} != {:?}", a, b);
335 }
336 close
337 }
338
339 #[test]
340 fn test_exp2() {
341 assert!(close(ComplexFloat::exp2(_0_0i), _1_0i));
342 assert!(closef(<f64 as ComplexFloat>::exp2(0.), 1.));
343 }
344
345 #[test]
346 fn test_exp() {
347 assert!(close(ComplexFloat::exp(_0_0i), _1_0i));
348 assert!(closef(ComplexFloat::exp(0.), 1.));
349 }
350
351 #[test]
352 fn test_powi() {
353 assert!(close(ComplexFloat::powi(_0_1i, 4), _1_0i));
354 assert!(closef(ComplexFloat::powi(-1., 4), 1.));
355 }
356
357 #[test]
358 fn test_powz() {
359 assert!(close(ComplexFloat::powc(_1_0i, _0_1i), _1_0i));
360 assert!(close(ComplexFloat::powc(1., _0_1i), _1_0i));
361 }
362
363 #[test]
364 fn test_log2() {
365 assert!(close(ComplexFloat::log2(_1_0i), _0_0i));
366 assert!(closef(ComplexFloat::log2(1.), 0.));
367 }
368
369 #[test]
370 fn test_log10() {
371 assert!(close(ComplexFloat::log10(_1_0i), _0_0i));
372 assert!(closef(ComplexFloat::log10(1.), 0.));
373 }
374
375 #[test]
376 fn test_conj() {
377 assert_eq!(ComplexFloat::conj(_0_1i), Complex::new(0., -1.));
378 assert_eq!(ComplexFloat::conj(1.), 1.);
379 }
380
381 #[test]
382 fn test_is_nan() {
383 assert!(!ComplexFloat::is_nan(_1_0i));
384 assert!(!ComplexFloat::is_nan(1.));
385
386 assert!(ComplexFloat::is_nan(Complex::new(f64::NAN, f64::NAN)));
387 assert!(ComplexFloat::is_nan(f64::NAN));
388 }
389
390 #[test]
391 fn test_is_infinite() {
392 assert!(!ComplexFloat::is_infinite(_1_0i));
393 assert!(!ComplexFloat::is_infinite(1.));
394
395 assert!(ComplexFloat::is_infinite(Complex::new(
396 f64::INFINITY,
397 f64::INFINITY
398 )));
399 assert!(ComplexFloat::is_infinite(f64::INFINITY));
400 }
401
402 #[test]
403 fn test_is_finite() {
404 assert!(ComplexFloat::is_finite(_1_0i));
405 assert!(ComplexFloat::is_finite(1.));
406
407 assert!(!ComplexFloat::is_finite(Complex::new(
408 f64::INFINITY,
409 f64::INFINITY
410 )));
411 assert!(!ComplexFloat::is_finite(f64::INFINITY));
412 }
413
414 #[test]
415 fn test_is_normal() {
416 assert!(ComplexFloat::is_normal(_1_1i));
417 assert!(ComplexFloat::is_normal(1.));
418
419 assert!(!ComplexFloat::is_normal(Complex::new(
420 f64::INFINITY,
421 f64::INFINITY
422 )));
423 assert!(!ComplexFloat::is_normal(f64::INFINITY));
424 }
425
426 #[test]
427 fn test_arg() {
428 assert!(closef(
429 ComplexFloat::arg(_0_1i),
430 core::f64::consts::FRAC_PI_2
431 ));
432
433 assert!(closef(ComplexFloat::arg(-1.), core::f64::consts::PI));
434 assert!(closef(ComplexFloat::arg(-0.), core::f64::consts::PI));
435 assert!(closef(ComplexFloat::arg(0.), 0.));
436 assert!(closef(ComplexFloat::arg(1.), 0.));
437 assert!(ComplexFloat::arg(f64::NAN).is_nan());
438 }
439}
440