Crate norman

The norman library provides everything you need for calculationg norms of or general distances between elements of vector spaces.

Based on two traits—Norm and Distance —this crate implements different kinds of norm and distance functions for a wide variety of types—including complex numbers and arrays.

Usage

If you only want to compute the standard norm of an element, like the absolute value of a floating point number or the euclidean norm of a vector, then you can use the traits NormEucl or DistanceEucl without specifying a certain type of norm:

use ndarray::Array1;

use norman::special::NormEucl;

let a = Array1::from(vec![2.0f32, -4.0, -2.0]);

assert_eq!(a.norm_eucl(), (2.0f32*2.0 + 4.0*4.0 + 2.0*2.0).sqrt());

For a detailed description on how these traits are implemented, see the module documentation of special::implementation.

However, there are many ways to define a norm on a vector. If you want more control over the exact kind of norm or distance function used, the full Norm and Distance traits are the right ones for you.

These traits have a generic parameter D, the descriptor of the norm or distance function. This makes it possible to implement not only a single type of norm function for a type, but multiple ones.

E.g. ndarray::ArrayBase implements Norm<Sup>, which yields the spuremum norm, and Norm<PNorm> which yields the p-norm.

use ndarray::Array1;

use norman::Norm;
use norman::desc::{Sup, PNorm};

let a = Array1::from(vec![2.0f32, -4.0, -2.0]);

assert_eq!(a.norm(Sup::new()), 4.0);
assert_eq!(a.norm(PNorm::new(2)), (2.0f32*2.0 + 4.0*4.0 + 2.0*2.0).sqrt());
assert_eq!(a.norm(PNorm::new(1)), 2.0f32 + 4.0 + 2.0);

You see: The norm-function recieves one additional parameter which further describes the norm. There is only one supremum norm, so this one needs no further description—we will always call it with Sup::new().

But the p-norms do need additional specification: We need to specify whether we want a 1-norm or a 2-norm. So we pass PNorm::new(2) or PNorm::new(1) as the additional parameter.

These norms are implemented on ndarray::ArrayBase as long as the elments of the array implement Norm<Abs>:

use num_complex::Complex;
use ndarray::Array1;

use norman::Norm;
use norman::desc::{Sup, PNorm};

let a = Array1::from(vec![
    Complex::new(- 2.0,  0.0),
    Complex::new(  3.0,  4.0),
    Complex::new(-15.0,  8.0),
]);

assert_eq!(a.norm(Sup::new()), 17.0);
assert_eq!(
    a.norm(PNorm::new(2)),
    (2.0f32*2.0 + 0.0*0.0 + 3.0*3.0 + 4.0*4.0 + 15.0*15.0 + 8.0*8.0).sqrt()
);
assert_eq!(a.norm(PNorm::new(1)), (2.0f32 + 5.0 + 17.0));

The Distance trait

In many cases, you do not want to calculate the norm of a single value, but you have to retrieve the distance between two values. This would often be possible by calling (a-b).norm(norm_descriptor), but e.g. for ndarrays this would imply calculating the difference and once storing it in a new ndarray, which will cause one unnecessary memory allocation. Instead you can use the Distance trait, which calculates the same result without storing the intermediate difference of the arrays:

use ndarray::Array1;

use norman::{Norm, Distance};
use norman::desc::{Sup, PNorm};

let a = Array1::from(vec![ 2.0f32, -4.0, -2.0]);
let b = Array1::from(vec![ 6.0f32, -1.0,  4.0]);

assert_eq!(a.distance(&b, Sup::new()), (a.clone()-&b).norm(Sup::new()));
assert_eq!(a.distance(&b, PNorm::new(2)), (a.clone()-b).norm(PNorm::new(2)));

For a detailed description of how norms and distances are implemented on various types, see the module documentation of implementation.

Accessing the implementations

The implementations on types of external crates are behind feature gates, which have the same name as the crate. E.g. in order to use the Norm trait on an ndarray::Array1, norman must be included with the feature “ndarray”, i.e. the corresponding part of your Cargo.toml would look like:

norman = { version = "0.0.4", features = ["ndarray"] }

However, ndarray and num_complex are declared as default features, so they do not need to be named explicitly.

All crate features

• num-complex: Unlocks the implementations on num_complex::Complex.
• ndarray: Unlocks the implementations on ndarray::ArrayBase.
• array: Unlocks the implementations on the array types [T; N] for N=0 to N=32. If const generics land some day, this feature gate will probably be removed.

Modules

desc

A collection of norm descriptors.

implementation

Implementations of the Norm and Distance traits on various types.

special

Dedicated traits for some standard norms like the euclidean norm.

Traits

Distance

The abstract notion of the distance between two values.

Norm

The Norm trait is the core of the norman crate.

Functions

normalize

Normalizes the vector v according to the norm desc, i.e. divides it by its norm.

normalized

Returns the normalization of v according to the norm desc, i.e. v divided by its norm.