Type Alias Vector

pub type Vector<T, D, S> = Matrix<T, D, U1, S>;

A matrix with one column and D rows.

Aliased Type

struct Vector<T, D, S> {
    pub data: S,
    /* private fields */
}

Fields

data: S

The data storage that contains all the matrix components. Disappointed?

Well, if you came here to see how you can access the matrix components, you may be in luck: you can access the individual components of all vectors with compile-time dimensions <= 6 using field notation like this: vec.x, vec.y, vec.z, vec.w, vec.a, vec.b. Reference and assignation work too:

let mut vec = Vector3::new(1.0, 2.0, 3.0);
vec.x = 10.0;
vec.y += 30.0;
assert_eq!(vec.x, 10.0);
assert_eq!(vec.y + 100.0, 132.0);

Similarly, for matrices with compile-time dimensions <= 6, you can use field notation like this: mat.m11, mat.m42, etc. The first digit identifies the row to address and the second digit identifies the column to address. So mat.m13 identifies the component at the first row and third column (note that the count of rows and columns start at 1 instead of 0 here. This is so we match the mathematical notation).

For all matrices and vectors, independently from their size, individual components can be accessed and modified using indexing: vec[20], mat[(20, 19)]. Here the indexing starts at 0 as you would expect.

Implementations

impl<T, D: Dim, S> Vector<T, D, S>

where T: Scalar + Zero + ClosedAddAssign + ClosedMulAssign, S: StorageMut<T, D>,

BLAS functions

pub fn axcpy<D2: Dim, SB>(&mut self, a: T, x: &Vector<T, D2, SB>, c: T, b: T)

where SB: Storage<T, D2>, ShapeConstraint: DimEq<D, D2>,

Computes self = a * x * c + b * self.

If b is zero, self is never read from.

Example

let mut vec1 = Vector3::new(1.0, 2.0, 3.0);
let vec2 = Vector3::new(0.1, 0.2, 0.3);
vec1.axcpy(5.0, &vec2, 2.0, 5.0);
assert_eq!(vec1, Vector3::new(6.0, 12.0, 18.0));

pub fn axpy<D2: Dim, SB>(&mut self, a: T, x: &Vector<T, D2, SB>, b: T)

where T: One, SB: Storage<T, D2>, ShapeConstraint: DimEq<D, D2>,

Computes self = a * x + b * self.

If b is zero, self is never read from.

Example

let mut vec1 = Vector3::new(1.0, 2.0, 3.0);
let vec2 = Vector3::new(0.1, 0.2, 0.3);
vec1.axpy(10.0, &vec2, 5.0);
assert_eq!(vec1, Vector3::new(6.0, 12.0, 18.0));

pub fn gemv<R2: Dim, C2: Dim, D3: Dim, SB, SC>( &mut self, alpha: T, a: &Matrix<T, R2, C2, SB>, x: &Vector<T, D3, SC>, beta: T, )

where T: One, SB: Storage<T, R2, C2>, SC: Storage<T, D3>, ShapeConstraint: DimEq<D, R2> + AreMultipliable<R2, C2, D3, U1>,

Computes self = alpha * a * x + beta * self, where a is a matrix, x a vector, and alpha, beta two scalars.

If beta is zero, self is never read.

Example

let mut vec1 = Vector2::new(1.0, 2.0);
let vec2 = Vector2::new(0.1, 0.2);
let mat = Matrix2::new(1.0, 2.0,
                       3.0, 4.0);
vec1.gemv(10.0, &mat, &vec2, 5.0);
assert_eq!(vec1, Vector2::new(10.0, 21.0));

pub fn sygemv<D2: Dim, D3: Dim, SB, SC>( &mut self, alpha: T, a: &SquareMatrix<T, D2, SB>, x: &Vector<T, D3, SC>, beta: T, )

where T: One, SB: Storage<T, D2, D2>, SC: Storage<T, D3>, ShapeConstraint: DimEq<D, D2> + AreMultipliable<D2, D2, D3, U1>,

Computes self = alpha * a * x + beta * self, where a is a symmetric matrix, x a vector, and alpha, beta two scalars.

For hermitian matrices, use .hegemv instead. If beta is zero, self is never read. If self is read, only its lower-triangular part (including the diagonal) is actually read.

Examples

let mat = Matrix2::new(1.0, 2.0,
                       2.0, 4.0);
let mut vec1 = Vector2::new(1.0, 2.0);
let vec2 = Vector2::new(0.1, 0.2);
vec1.sygemv(10.0, &mat, &vec2, 5.0);
assert_eq!(vec1, Vector2::new(10.0, 20.0));


// The matrix upper-triangular elements can be garbage because it is never
// read by this method. Therefore, it is not necessary for the caller to
// fill the matrix struct upper-triangle.
let mat = Matrix2::new(1.0, 9999999.9999999,
                       2.0, 4.0);
let mut vec1 = Vector2::new(1.0, 2.0);
vec1.sygemv(10.0, &mat, &vec2, 5.0);
assert_eq!(vec1, Vector2::new(10.0, 20.0));

pub fn hegemv<D2: Dim, D3: Dim, SB, SC>( &mut self, alpha: T, a: &SquareMatrix<T, D2, SB>, x: &Vector<T, D3, SC>, beta: T, )

where T: SimdComplexField, SB: Storage<T, D2, D2>, SC: Storage<T, D3>, ShapeConstraint: DimEq<D, D2> + AreMultipliable<D2, D2, D3, U1>,

Computes self = alpha * a * x + beta * self, where a is an hermitian matrix, x a vector, and alpha, beta two scalars.

If beta is zero, self is never read. If self is read, only its lower-triangular part (including the diagonal) is actually read.

Examples

let mat = Matrix2::new(Complex::new(1.0, 0.0), Complex::new(2.0, -0.1),
                       Complex::new(2.0, 1.0), Complex::new(4.0, 0.0));
let mut vec1 = Vector2::new(Complex::new(1.0, 2.0), Complex::new(3.0, 4.0));
let vec2 = Vector2::new(Complex::new(0.1, 0.2), Complex::new(0.3, 0.4));
vec1.sygemv(Complex::new(10.0, 20.0), &mat, &vec2, Complex::new(5.0, 15.0));
assert_eq!(vec1, Vector2::new(Complex::new(-48.0, 44.0), Complex::new(-75.0, 110.0)));


// The matrix upper-triangular elements can be garbage because it is never
// read by this method. Therefore, it is not necessary for the caller to
// fill the matrix struct upper-triangle.

let mat = Matrix2::new(Complex::new(1.0, 0.0), Complex::new(99999999.9, 999999999.9),
                       Complex::new(2.0, 1.0), Complex::new(4.0, 0.0));
let mut vec1 = Vector2::new(Complex::new(1.0, 2.0), Complex::new(3.0, 4.0));
let vec2 = Vector2::new(Complex::new(0.1, 0.2), Complex::new(0.3, 0.4));
vec1.sygemv(Complex::new(10.0, 20.0), &mat, &vec2, Complex::new(5.0, 15.0));
assert_eq!(vec1, Vector2::new(Complex::new(-48.0, 44.0), Complex::new(-75.0, 110.0)));

pub fn gemv_tr<R2: Dim, C2: Dim, D3: Dim, SB, SC>( &mut self, alpha: T, a: &Matrix<T, R2, C2, SB>, x: &Vector<T, D3, SC>, beta: T, )

where T: One, SB: Storage<T, R2, C2>, SC: Storage<T, D3>, ShapeConstraint: DimEq<D, C2> + AreMultipliable<C2, R2, D3, U1>,

Computes self = alpha * a.transpose() * x + beta * self, where a is a matrix, x a vector, and alpha, beta two scalars.

If beta is zero, self is never read.

Example

let mat = Matrix2::new(1.0, 3.0,
                       2.0, 4.0);
let mut vec1 = Vector2::new(1.0, 2.0);
let vec2 = Vector2::new(0.1, 0.2);
let expected = mat.transpose() * vec2 * 10.0 + vec1 * 5.0;

vec1.gemv_tr(10.0, &mat, &vec2, 5.0);
assert_eq!(vec1, expected);

pub fn gemv_ad<R2: Dim, C2: Dim, D3: Dim, SB, SC>( &mut self, alpha: T, a: &Matrix<T, R2, C2, SB>, x: &Vector<T, D3, SC>, beta: T, )

where T: SimdComplexField, SB: Storage<T, R2, C2>, SC: Storage<T, D3>, ShapeConstraint: DimEq<D, C2> + AreMultipliable<C2, R2, D3, U1>,

Computes self = alpha * a.adjoint() * x + beta * self, where a is a matrix, x a vector, and alpha, beta two scalars.

For real matrices, this is the same as .gemv_tr. If beta is zero, self is never read.

Example

let mat = Matrix2::new(Complex::new(1.0, 2.0), Complex::new(3.0, 4.0),
                       Complex::new(5.0, 6.0), Complex::new(7.0, 8.0));
let mut vec1 = Vector2::new(Complex::new(1.0, 2.0), Complex::new(3.0, 4.0));
let vec2 = Vector2::new(Complex::new(0.1, 0.2), Complex::new(0.3, 0.4));
let expected = mat.adjoint() * vec2 * Complex::new(10.0, 20.0) + vec1 * Complex::new(5.0, 15.0);

vec1.gemv_ad(Complex::new(10.0, 20.0), &mat, &vec2, Complex::new(5.0, 15.0));
assert_eq!(vec1, expected);

impl<T, D: Dim, S: RawStorage<T, D>> Vector<T, D, S>

pub unsafe fn vget_unchecked(&self, i: usize) -> &T

Gets a reference to the i-th element of this column vector without bound checking.

Safety

i must be less than D.

impl<T, D: Dim, S: RawStorageMut<T, D>> Vector<T, D, S>

pub unsafe fn vget_unchecked_mut(&mut self, i: usize) -> &mut T

Gets a mutable reference to the i-th element of this column vector without bound checking.

Safety

i must be less than D.

impl<T: Scalar + Zero, D: DimAdd<U1>, S: RawStorage<T, D>> Vector<T, D, S>

pub fn to_homogeneous(&self) -> OVector<T, DimSum<D, U1>>

where DefaultAllocator: Allocator<DimSum<D, U1>>,

Computes the coordinates in projective space of this vector, i.e., appends a 0 to its coordinates.

pub fn from_homogeneous<SB>( v: Vector<T, DimSum<D, U1>, SB>, ) -> Option<OVector<T, D>>

where SB: RawStorage<T, DimSum<D, U1>>, DefaultAllocator: Allocator<D>,

Constructs a vector from coordinates in projective space, i.e., removes a 0 at the end of self. Returns None if this last component is not zero.

impl<T: Scalar, D: DimAdd<U1>, S: RawStorage<T, D>> Vector<T, D, S>

pub fn push(&self, element: T) -> OVector<T, DimSum<D, U1>>

where DefaultAllocator: Allocator<DimSum<D, U1>>,

Constructs a new vector of higher dimension by appending element to the end of self.

impl<T: Scalar + Field, S: RawStorage<T, U3>> Vector<T, U3, S>

pub fn cross_matrix(&self) -> OMatrix<T, U3, U3>

Computes the matrix M such that for all vector v we have M * v == self.cross(&v).

impl<T: Scalar, D, S: RawStorage<T, D>> Vector<T, D, S>

where D: DimName + ToTypenum,

Swizzling

pub fn xx(&self) -> Vector2<T>

where D::Typenum: Cmp<U0, Output = Greater>,

Builds a new vector from components of self.

pub fn xxx(&self) -> Vector3<T>

where D::Typenum: Cmp<U0, Output = Greater>,

Builds a new vector from components of self.

pub fn xy(&self) -> Vector2<T>

where D::Typenum: Cmp<U1, Output = Greater>,

Builds a new vector from components of self.

pub fn yx(&self) -> Vector2<T>

where D::Typenum: Cmp<U1, Output = Greater>,

Builds a new vector from components of self.

pub fn yy(&self) -> Vector2<T>

where D::Typenum: Cmp<U1, Output = Greater>,

Builds a new vector from components of self.

pub fn xxy(&self) -> Vector3<T>

where D::Typenum: Cmp<U1, Output = Greater>,

Builds a new vector from components of self.

pub fn xyx(&self) -> Vector3<T>

where D::Typenum: Cmp<U1, Output = Greater>,

Builds a new vector from components of self.

pub fn xyy(&self) -> Vector3<T>

where D::Typenum: Cmp<U1, Output = Greater>,

Builds a new vector from components of self.

pub fn yxx(&self) -> Vector3<T>

where D::Typenum: Cmp<U1, Output = Greater>,

Builds a new vector from components of self.

pub fn yxy(&self) -> Vector3<T>

where D::Typenum: Cmp<U1, Output = Greater>,

Builds a new vector from components of self.

pub fn yyx(&self) -> Vector3<T>

where D::Typenum: Cmp<U1, Output = Greater>,

Builds a new vector from components of self.

pub fn yyy(&self) -> Vector3<T>

where D::Typenum: Cmp<U1, Output = Greater>,

Builds a new vector from components of self.

pub fn xz(&self) -> Vector2<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn yz(&self) -> Vector2<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn zx(&self) -> Vector2<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn zy(&self) -> Vector2<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn zz(&self) -> Vector2<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn xxz(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn xyz(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn xzx(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn xzy(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn xzz(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn yxz(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn yyz(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn yzx(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn yzy(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn yzz(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn zxx(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn zxy(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn zxz(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn zyx(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn zyy(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn zyz(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn zzx(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn zzy(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

pub fn zzz(&self) -> Vector3<T>

where D::Typenum: Cmp<U2, Output = Greater>,

Builds a new vector from components of self.

impl<T: Scalar + Zero + One + ClosedAddAssign + ClosedSubAssign + ClosedMulAssign, D: Dim, S: Storage<T, D>> Vector<T, D, S>

Interpolation

pub fn lerp<S2: Storage<T, D>>( &self, rhs: &Vector<T, D, S2>, t: T, ) -> OVector<T, D>

where DefaultAllocator: Allocator<D>,

Returns self * (1.0 - t) + rhs * t, i.e., the linear blend of the vectors x and y using the scalar value a.

The value for a is not restricted to the range [0, 1].

Examples:

let x = Vector3::new(1.0, 2.0, 3.0);
let y = Vector3::new(10.0, 20.0, 30.0);
assert_eq!(x.lerp(&y, 0.1), Vector3::new(1.9, 3.8, 5.7));

pub fn slerp<S2: Storage<T, D>>( &self, rhs: &Vector<T, D, S2>, t: T, ) -> OVector<T, D>

where T: RealField, DefaultAllocator: Allocator<D>,

Computes the spherical linear interpolation between two non-zero vectors.

The result is a unit vector.

Examples:

let v1 =Vector2::new(1.0, 2.0);
let v2 = Vector2::new(2.0, -3.0);

let v = v1.slerp(&v2, 1.0);

assert_eq!(v, v2.normalize());

impl<T: Scalar, D: Dim, S: RawStorage<T, D>> Vector<T, D, S>

Find the min and max components (vector-specific methods)

pub fn icamax(&self) -> usize

where T: ComplexField,

Computes the index of the vector component with the largest complex or real absolute value.

Examples:

let vec = Vector3::new(Complex::new(11.0, 3.0), Complex::new(-15.0, 0.0), Complex::new(13.0, 5.0));
assert_eq!(vec.icamax(), 2);

pub fn argmax(&self) -> (usize, T)

where T: PartialOrd,

Computes the index and value of the vector component with the largest value.

Examples:

let vec = Vector3::new(11, -15, 13);
assert_eq!(vec.argmax(), (2, 13));

pub fn imax(&self) -> usize

where T: PartialOrd,

Computes the index of the vector component with the largest value.

Examples:

let vec = Vector3::new(11, -15, 13);
assert_eq!(vec.imax(), 2);

pub fn iamax(&self) -> usize

where T: PartialOrd + Signed,

Computes the index of the vector component with the largest absolute value.

Examples:

let vec = Vector3::new(11, -15, 13);
assert_eq!(vec.iamax(), 1);

pub fn argmin(&self) -> (usize, T)

where T: PartialOrd,

Computes the index and value of the vector component with the smallest value.

Examples:

let vec = Vector3::new(11, -15, 13);
assert_eq!(vec.argmin(), (1, -15));

pub fn imin(&self) -> usize

where T: PartialOrd,

Computes the index of the vector component with the smallest value.

Examples:

let vec = Vector3::new(11, -15, 13);
assert_eq!(vec.imin(), 1);

pub fn iamin(&self) -> usize

where T: PartialOrd + Signed,

Computes the index of the vector component with the smallest absolute value.

Examples:

let vec = Vector3::new(11, -15, 13);
assert_eq!(vec.iamin(), 0);

impl<T: RealField, D1: Dim, S1: Storage<T, D1>> Vector<T, D1, S1>

pub fn convolve_full<D2, S2>( &self, kernel: Vector<T, D2, S2>, ) -> OVector<T, DimDiff<DimSum<D1, D2>, U1>>

where D1: DimAdd<D2>, D2: DimAdd<D1, Output = DimSum<D1, D2>>, DimSum<D1, D2>: DimSub<U1>, S2: Storage<T, D2>, DefaultAllocator: Allocator<DimDiff<DimSum<D1, D2>, U1>>,

Returns the convolution of the target vector and a kernel.

Arguments

• kernel - A Vector with size > 0

Errors

Inputs must satisfy vector.len() >= kernel.len() > 0.

pub fn convolve_valid<D2, S2>( &self, kernel: Vector<T, D2, S2>, ) -> OVector<T, DimDiff<DimSum<D1, U1>, D2>>

where D1: DimAdd<U1>, D2: Dim, DimSum<D1, U1>: DimSub<D2>, S2: Storage<T, D2>, DefaultAllocator: Allocator<DimDiff<DimSum<D1, U1>, D2>>,

Returns the convolution of the target vector and a kernel.

The output convolution consists only of those elements that do not rely on the zero-padding.

Arguments

• kernel - A Vector with size > 0

Errors

Inputs must satisfy self.len() >= kernel.len() > 0.

pub fn convolve_same<D2, S2>(&self, kernel: Vector<T, D2, S2>) -> OVector<T, D1>

where D2: Dim, S2: Storage<T, D2>, DefaultAllocator: Allocator<D1>,

Returns the convolution of the target vector and a kernel.

The output convolution is the same size as vector, centered with respect to the ‘full’ output.

Arguments

• kernel - A Vector with size > 0

Errors

Inputs must satisfy self.len() >= kernel.len() > 0.