Struct russell_lab::Vector

pub struct Vector { /* fields omitted */ }

Holds vector components and associated functions

Remarks

• Vector implements the Index and IntoIterator traits (mutable or not), thus, we can access components by indices or loop over the components
• Vector has also methods to access the underlying data (mutable or not); e.g., using as_data() and as_mut_data().
• For faster computations, we recommend using the set of functions that operate on Vectors and Matrices; e.g., add_vectors, inner, outer, copy_vectors, mat_vec_mul, and others.

Example

// import
use russell_lab::{Vector, add_vectors};

// create vector
let mut u = Vector::from(&[4.0, 9.0, 16.0, 25.0]);
assert_eq!(
    format!("{}", u),
    "┌    ┐\n\
     │  4 │\n\
     │  9 │\n\
     │ 16 │\n\
     │ 25 │\n\
     └    ┘"
);

// create vector filled with zeros
let n = u.dim();
let v = Vector::filled(n, 10.0);
assert_eq!(
    format!("{}", v),
    "┌    ┐\n\
     │ 10 │\n\
     │ 10 │\n\
     │ 10 │\n\
     │ 10 │\n\
     └    ┘"
);

// create a copy and change its components
let mut w = u.get_copy();
w.map(|x| f64::sqrt(x));
w[0] *= -1.0;
w[1] *= -1.0;
w[2] *= -1.0;
w[3] *= -1.0;
assert_eq!(
    format!("{}", w),
    "┌    ┐\n\
     │ -2 │\n\
     │ -3 │\n\
     │ -4 │\n\
     │ -5 │\n\
     └    ┘"
);

// change the components
for x in &mut u {
    *x = f64::sqrt(*x);
}

// add vectors
let mut z = Vector::new(n);
add_vectors(&mut z, 1.0, &u, 1.0, &w)?;
println!("{}", z);
assert_eq!(
    format!("{}", z),
    "┌   ┐\n\
     │ 0 │\n\
     │ 0 │\n\
     │ 0 │\n\
     │ 0 │\n\
     └   ┘"
);

Implementations

impl Vector

pub fn new(dim: usize) -> Self

Creates a new (zeroed) vector

Example

use russell_lab::Vector;
let u = Vector::new(3);
let correct = "┌   ┐\n\
               │ 0 │\n\
               │ 0 │\n\
               │ 0 │\n\
               └   ┘";
assert_eq!(format!("{}", u), correct);

pub fn filled(dim: usize, value: f64) -> Self

Creates new vector completely filled with the same value

Example

use russell_lab::Vector;
let u = Vector::filled(3, 4.0);
let correct = "┌   ┐\n\
               │ 4 │\n\
               │ 4 │\n\
               │ 4 │\n\
               └   ┘";
assert_eq!(format!("{}", u), correct);

pub fn from<'a, T, U>(array: &'a T) -> Self where
    T: AsArray1D<'a, U>,
    U: 'a + Into<f64>, 

Creates a vector from data

Example

use russell_lab::Vector;

// heap-allocated 1D array (vector)
let u_data = vec![1.0, 2.0, 3.0];
let u = Vector::from(&u_data);
assert_eq!(
    format!("{}", &u),
    "┌   ┐\n\
     │ 1 │\n\
     │ 2 │\n\
     │ 3 │\n\
     └   ┘"
);

// heap-allocated 1D array (slice)
let v_data: &[f64] = &[10.0, 20.0, 30.0];
let v = Vector::from(&v_data);
assert_eq!(
    format!("{}", &v),
    "┌    ┐\n\
     │ 10 │\n\
     │ 20 │\n\
     │ 30 │\n\
     └    ┘"
);

// stack-allocated (fixed-size) 2D array
let w_data = [100.0, 200.0, 300.0];
let w = Vector::from(&w_data);
assert_eq!(
    format!("{}", &w),
    "┌     ┐\n\
     │ 100 │\n\
     │ 200 │\n\
     │ 300 │\n\
     └     ┘"
);

pub fn linspace(start: f64, stop: f64, count: usize) -> Self

Returns evenly spaced numbers over a specified closed interval

Example

use russell_lab::Vector;
let x = Vector::linspace(2.0, 3.0, 5);
let correct = "┌      ┐\n\
               │    2 │\n\
               │ 2.25 │\n\
               │  2.5 │\n\
               │ 2.75 │\n\
               │    3 │\n\
               └      ┘";
assert_eq!(format!("{}", x), correct);

pub fn mapped_linspace<F>(
    start: f64,
    stop: f64,
    count: usize,
    function: F
) -> Self where
    F: Fn(f64) -> f64, 

Returns a mapped linear-space; evenly spaced numbers modified by a function

Example

use russell_lab::Vector;
let x = Vector::mapped_linspace(0.0, 4.0, 5, |v| v * v);
assert_eq!(
    format!("{}", x),
    "┌    ┐\n\
     │  0 │\n\
     │  1 │\n\
     │  4 │\n\
     │  9 │\n\
     │ 16 │\n\
     └    ┘",
);

pub fn dim(&self) -> usize

Returns the dimension (size) of this vector

Example

use russell_lab::Vector;
let u = Vector::from(&[1.0, 2.0, 3.0]);
assert_eq!(u.dim(), 3);

pub fn scale(&mut self, alpha: f64)

Scales this vector

u := alpha * u

Example

use russell_lab::Vector;
let mut u = Vector::from(&[1.0, 2.0, 3.0]);
u.scale(0.5);
let correct = "┌     ┐\n\
               │ 0.5 │\n\
               │   1 │\n\
               │ 1.5 │\n\
               └     ┘";
assert_eq!(format!("{}", u), correct);

pub fn fill(&mut self, value: f64)

Fills this vector with a given value

u[i] := value

Example

use russell_lab::Vector;
let mut u = Vector::new(3);
u.fill(8.8);
let correct = "┌     ┐\n\
               │ 8.8 │\n\
               │ 8.8 │\n\
               │ 8.8 │\n\
               └     ┘";
assert_eq!(format!("{}", u), correct);

pub fn as_data(&self) -> &Vec<f64>

Returns an access to the underlying data

Example

use russell_lab::Vector;
let u = Vector::from(&[1.0, 2.0, 3.0]);
assert_eq!(u.as_data(), &[1.0, 2.0, 3.0]);

pub fn as_mut_data(&mut self) -> &mut Vec<f64>

Returns a mutable access to the underlying data

Example

use russell_lab::Vector;
let mut u = Vector::from(&[1.0, 2.0, 3.0]);
let data = u.as_mut_data();
data[1] = 2.2;
assert_eq!(data, &[1.0, 2.2, 3.0]);

pub fn get(&self, i: usize) -> f64

Returns the i-th component

Example

use russell_lab::Vector;
let u = Vector::from(&[1.0, 2.0]);
assert_eq!(u.get(1), 2.0);

pub fn set(&mut self, i: usize, value: f64)

Change the i-th component

Example

use russell_lab::Vector;
let mut u = Vector::from(&[1.0, 2.0]);
u.set(1, -2.0);
let correct = "┌    ┐\n\
               │  1 │\n\
               │ -2 │\n\
               └    ┘";
assert_eq!(format!("{}", u), correct);

pub fn map<F>(&mut self, function: F) where
    F: Fn(f64) -> f64, 

Applies a function over all components of this vector

u := map(function(ui))

Example

use russell_lab::Vector;
let mut u = Vector::from(&[1.0, 2.0, 3.0]);
u.map(|x| x * x);
let correct = "┌   ┐\n\
               │ 1 │\n\
               │ 4 │\n\
               │ 9 │\n\
               └   ┘";
assert_eq!(format!("{}", u), correct);

pub fn map_with_index<F>(&mut self, function: F) where
    F: Fn(usize, f64) -> f64, 

Applies a function (with index) over all components of this vector

u := map(function(i, ui))

Example

use russell_lab::Vector;
let mut u = Vector::from(&[1.0, 2.0, 3.0]);
u.map_with_index(|i, x| x * x + (i as f64));
let correct = "┌    ┐\n\
               │  1 │\n\
               │  5 │\n\
               │ 11 │\n\
               └    ┘";
assert_eq!(format!("{}", u), correct);

pub fn get_copy(&self) -> Self

Returns a copy of this vector

Example

use russell_lab::Vector;
let mut u = Vector::from(&[1.0, 2.0, 3.0]);
let u_copy = u.get_copy();
u.set(1, 5.0);
let u_correct = "┌   ┐\n\
                 │ 1 │\n\
                 │ 5 │\n\
                 │ 3 │\n\
                 └   ┘";
let u_copy_correct = "┌   ┐\n\
                      │ 1 │\n\
                      │ 2 │\n\
                      │ 3 │\n\
                      └   ┘";
assert_eq!(format!("{}", u), u_correct);
assert_eq!(format!("{}", u_copy), u_copy_correct);

pub fn get_mapped<F>(&self, function: F) -> Self where
    F: Fn(f64) -> f64, 

Returns a mapped version of this vector

Example

use russell_lab::Vector;
let mut u = Vector::from(&[1.0, 2.0, 3.0]);
let v = u.get_mapped(|v| 4.0 - v);
u.set(1, 100.0);
assert_eq!(
    format!("{}", u),
    "┌     ┐\n\
     │   1 │\n\
     │ 100 │\n\
     │   3 │\n\
     └     ┘",
);
assert_eq!(
    format!("{}", v),
    "┌   ┐\n\
     │ 3 │\n\
     │ 2 │\n\
     │ 1 │\n\
     └   ┘",
);

pub fn norm(&self, kind: EnumVectorNorm) -> f64

Returns the vector norm

Computes one of:

One:  1-norm (taxicab or sum of abs values)

      ‖u‖_1 := sum_i |uᵢ|

Euc:  Euclidean-norm

      ‖u‖_2 = sqrt(Σ_i uᵢ⋅uᵢ)

Max:  max-norm (inf-norm)

      ‖u‖_max = max_i ( |uᵢ| ) == ‖u‖_∞

Example

use russell_lab::{EnumVectorNorm, Vector};
let u = Vector::from(&[2.0, -2.0, 2.0, -2.0, -3.0]);
assert_eq!(u.norm(EnumVectorNorm::One), 11.0);
assert_eq!(u.norm(EnumVectorNorm::Euc), 5.0);
assert_eq!(u.norm(EnumVectorNorm::Max), 3.0);

Trait Implementations

impl Display for Vector

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Generates a string representation of the Vector

Example

use russell_lab::Vector;
let u = Vector::from(&[4.0, 3.0, 1.0, 0.0, -4.04]);
assert_eq!(
    format!("{}", u),
    "┌       ┐\n\
     │     4 │\n\
     │     3 │\n\
     │     1 │\n\
     │     0 │\n\
     │ -4.04 │\n\
     └       ┘"
);

impl Index<usize> for Vector

Allows to access Vector components using indices

Example

use russell_lab::Vector;
let u = Vector::from(&[-3.0, 1.2, 2.0]);
assert_eq!(u[0], -3.0);
assert_eq!(u[1],  1.2);
assert_eq!(u[2],  2.0);

type Output = f64

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl IndexMut<usize> for Vector

Allows to change Vector components using indices

Example

use russell_lab::Vector;
let mut u = Vector::from(&[-3.0, 1.2, 2.0]);
u[0] -= 10.0;
u[1] += 10.0;
u[2] += 20.0;
assert_eq!(u[0], -13.0);
assert_eq!(u[1],  11.2);
assert_eq!(u[2],  22.0);

fn index_mut(&mut self, index: usize) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl IntoIterator for Vector

Allows to iterate over Vector components (move version)

Example

use russell_lab::Vector;
let u = Vector::from(&[10.0, 20.0, 30.0]);
for (i, v) in u.into_iter().enumerate() {
    assert_eq!(v, (10 * (i + 1)) as f64);
}

type Item = f64

The type of the elements being iterated over.

type IntoIter = IntoIter<Self::Item>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for &'a Vector

Allows to iterate over Vector components (borrow version)

Example

use russell_lab::Vector;
let u = Vector::from(&[10.0, 20.0, 30.0]);
let mut x = 10.0;
for v in &u {
    assert_eq!(*v, x);
    x += 10.0;
}

type Item = &'a f64

The type of the elements being iterated over.

type IntoIter = Iter<'a, f64>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for &'a mut Vector

Allows to iterate over Vector components (mutable version)

Example

use russell_lab::Vector;
let mut u = Vector::from(&[10.0, 20.0, 30.0]);
let mut x = 100.0;
for v in &mut u {
    *v *= 10.0;
    assert_eq!(*v, x);
    x += 100.0;
}

type Item = &'a mut f64

The type of the elements being iterated over.

type IntoIter = IterMut<'a, f64>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.