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

## 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.