# [−][src]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 |

special | Dedicated traits for some |

## Traits

Distance | The abstract notion of the distance between two values. |

Norm | The |

## Functions

normalize | Normalizes the vector |

normalized | Returns the normalization of |