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
/****************************************************************************** * Copyright 2019 Manuel Simon * This file is part of the norman library. * * Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or * https://www.apache.org/licenses/LICENSE-2.0> or the MIT license * <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your * option. This file may not be copied, modified, or distributed * except according to those terms. *****************************************************************************/ //! Implementations of the `Norm` and `Distance` traits on various //! types. //! //! Below you find a detailed description of how these traits are implemented //! on different types. //! //! # Primitive types //! //! Primitive integer and floating point types only implement `Norm<Abs>`. //! For unsigned types, the norm function simply returns the original value, //! for signed types, it returns the absolute value. //! //! # Complex numbers //! //! For `Complex<T>`, the `Norm` and `Distance` traits //! are implemented if `T` implements [`Float`](num_traits::Float). //! `Norm<Abs>` calculates the euclidean norm; //! they also implement `Norm<Sup>`, which calculates the maximum //! of the absolute values of real and imaginary part. //! //! # Vector types //! //! On types that represent vectors, the `Norm` trait is implemented //! if the elements of the collection implement `Norm<Abs>`. //! //! For a vector of the form `[x_1, …, x_n]`, the supremum norm //! will return the maximum of the Abs-norms of the `x_i`, i.e. //! `max_(1≤i≤n) x_i.norm(Abs::new())`. //! //! The _p_-norms will return the _p_-th root of the sum of the //! _p_-th powers of the Abs-norms of the `x_i`, i.e. //! `(sum_(1≤i≤n) x_i.norm(Abs::new()).pow(p)).pow(1/p)`. //! //! Higher dimensional arrays of ndarray are simply considered //! like single long vectors containing all the elements. Decent //! operator norms of matrices (with their own norm descriptors) //! will follow in a later release. //! //! The `Distance` trait calculates the norm of the difference //! between two vectors. It is implemented if the elements of the collection //! implement `Distance<Abs>` with an output that implements `PartialOrd`. //! For `ndarray::ArrayBase` it will try //! to broadcast the vectors together. If this fails, the function panics. //! //! ## Numerical edge cases for floating point elements //! //! NaNs in vectors are ignored, except if the vector contains only NaNs. //! In this case, `norm` returns NaN. //! //! If the norm of one element of a vector is infinite, the norm of //! the vector will be infinite, too. //! //! For _p_-norms there is however a special case: If the norms of all //! elements are finite, but the _p_-the power of an element is infinite, //! (which will usually only occur for a very high _p_), the supremum norm is returned. //! This is done because the supremum norm is usually a better approximation to the _p_-norm //! for high _ps_ than just returning Inf would be. //! //! ### Example //! //! ``` //! use ndarray::Array1; //! //! use norman::Norm; //! use norman::desc::PNorm; //! //! let a = Array1::from(vec![2.0f32, std::f32::INFINITY, 3.0]); //! assert_eq!(a.norm(PNorm::new(3)), std::f32::INFINITY); //! //! let b = Array1::from(vec![2.0f32, -4.0, 3.0]); //! // 4^10000 is to high to be represented as an f32, but since the norms //! // of all elements of b are finite, the _p_-norm falls back to calculating //! // the supremum norm. //! assert_eq!(b.norm(PNorm::new(10000)), 4.0); //! ``` #[doc(hidden)] pub mod primitives; #[cfg(feature = "array")] #[doc(hidden)] pub mod array; #[doc(hidden)] pub mod std_collections; #[cfg(feature = "num-complex")] #[doc(hidden)] pub mod num_complex; #[cfg(feature = "ndarray")] #[doc(hidden)] pub mod ndarray; #[doc(hidden)] pub mod noisy_float;