Module norman::implementation

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. 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);