# nalgebra

nalgebra is a low-dimensional linear algebra library written for Rust targeting:

• general-purpose linear algebra (still lacks a lot of features…).
• real time computer graphics.
• real time computer physics.

An on-line version of this documentation is available here.

## Using nalgebra

All the functionality of nalgebra is grouped in one place: the root module `nalgebra::`. This module re-exports everything and includes free functions for all traits methods doing out-of-place modifications.

• You can import the whole prelude using:
`use nalgebra::*;`

The preferred way to use nalgebra is to import types and traits explicitly, and call free-functions using the `na::` prefix:

```extern crate nalgebra as na;
use na::{Vec3, Rot3, Rotation};

fn main() {
let     a = Vec3::new(1.0f64, 1.0, 1.0);
let mut b = Rot3::new(na::zero());

b.append_rotation_mut(&a);

assert!(na::approx_eq(&na::rotation(&b), &a));
}```

## Features

nalgebra is meant to be a general-purpose, low-dimensional, linear algebra library, with an optimized set of tools for computer graphics and physics. Those features include:

• Vectors with static sizes: `Vec0`, `Vec1`, `Vec2`, `Vec3`, `Vec4`, `Vec5`, `Vec6`.
• Points with static sizes: `Pnt0`, `Pnt1`, `Pnt2`, `Pnt3`, `Pnt4`, `Pnt5`, `Pnt6`.
• Square matrices with static sizes: `Mat1`, `Mat2`, `Mat3`, `Mat4`, `Mat5`, `Mat6`.
• Rotation matrices: `Rot2`, `Rot3`, `Rot4`.
• Quaternions: `Quat`, `UnitQuat`.
• Isometries: `Iso2`, `Iso3`, `Iso4`.
• 3D projections for computer graphics: `Persp3`, `PerspMat3`, `Ortho3`, `OrthoMat3`.
• Dynamically sized vector: `DVec`.
• Dynamically sized (square or rectangular) matrix: `DMat`.
• A few methods for data analysis: `Cov`, `Mean`.
• Almost one trait per functionality: useful for generic programming.

## nalgebra in use

Here are some projects using nalgebra. Feel free to add your project to this list if you happen to use nalgebra!

• nphysics: a real-time physics engine.
• ncollide: a collision detection library.
• kiss3d: a minimalistic graphics engine.
• nrays: a ray tracer.

## Macros

 assert_approx_eq! Asserts approximate equality of two values with the `ApproxEq` trait. assert_approx_eq_eps! Asserts approximate equality within a given tolerance of two values with the `ApproxEq` trait. assert_approx_eq_ulps! Asserts approximate equality within a given tolerance of two values with the `ApproxEq` trait, with tolerance specified in ULPs.

## Structs

 DMat Matrix with dimensions unknown at compile-time. DVec Heap allocated, dynamically sized vector. DVec1 Stack-allocated, dynamically sized vector with a maximum size of 1. DVec2 Stack-allocated, dynamically sized vector with a maximum size of 2. DVec3 Stack-allocated, dynamically sized vector with a maximum size of 3. DVec4 Stack-allocated, dynamically sized vector with a maximum size of 4. DVec5 Stack-allocated, dynamically sized vector with a maximum size of 5. DVec6 Stack-allocated, dynamically sized vector with a maximum size of 6. Identity Special identity matrix. All its operation are no-ops. Iso2 Two dimensional isometry. Iso3 Three dimensional isometry. Iso4 Four dimensional isometry. Mat1 Square matrix of dimension 1. Mat2 Square matrix of dimension 2. Mat3 Square matrix of dimension 3. Mat4 Square matrix of dimension 4. Mat5 Square matrix of dimension 5. Mat6 Square matrix of dimension 6. Ortho3 A 3D orthographic projection stored without any matrix. OrthoMat3 A 3D orthographic projection stored as a 4D matrix. Persp3 A 3D perspective projection stored without any matrix. PerspMat3 A 3D perspective projection stored as a 4D matrix. Pnt0 Point of dimension 0. Pnt1 Point of dimension 1. Pnt2 Point of dimension 2. Pnt3 Point of dimension 3. Pnt4 Point of dimension 4. Pnt5 Point of dimension 5. Pnt6 Point of dimension 6. Quat A quaternion. Rot2 Two dimensional rotation matrix. Rot3 Three dimensional rotation matrix. Rot4 Four dimensional rotation matrix. UnitQuat A unit quaternion that can represent a 3D rotation. Vec0 Vector of dimension 0. Vec1 Vector of dimension 1. Vec2 Vector of dimension 2. Vec3 Vector of dimension 3. Vec4 Vector of dimension 4. Vec5 Vector of dimension 5. Vec6 Vector of dimension 6.

## Enums

 POrdering Result of a partial ordering.

## Traits

 Absolute Trait of objects having an absolute value. This is useful if the object does not have the same type as its absolute value. AbsoluteRotate Composition of a rotation and an absolute value. ApproxEq Trait for testing approximate equality Axpy Trait of objects implementing the `y = ax + y` operation. BaseFloat Basic floating-point number numeric trait. BaseNum Basic integral numeric trait. Basis Traits of objects which can form a basis (typically vectors). Bounded Types that have maximum and minimum value. Cast Traits of objects which can be created from an object of type `T`. Col Trait to access columns of a matrix or vector. ColSlice Trait to access part of a column of a matrix Cov Trait for computing the covariance of a set of data. Cross Trait of elements having a cross product. CrossMatrix Trait of elements having a cross product operation which can be expressed as a matrix. Det Trait of objects having a determinant. Typically used by square matrices. Diag Trait to get the diagonal of square matrices. Dim Trait of objects having a spacial dimension known at compile time. Dot Traits of objects having a dot product. EigenQR Trait for computing the eigenvector and eigenvalues of a square matrix usin the QR algorithm. Eye Trait for constructing the identity matrix FloatPnt Trait of points with components implementing the `BaseFloat` trait. FloatVec Trait of vector with components implementing the `BaseFloat` trait. FromHomogeneous Traits of objects which can be build from an homogeneous coordinate form. Indexable This is a workaround of current Rust limitations. Inv Trait of objects having an inverse. Typically used to implement matrix inverse. Iterable This is a workaround of current Rust limitations. IterableMut This is a workaround of current Rust limitations. Mat Trait of matrices. Mean Trait for computing the covariance of a set of data. Norm Traits of objects having an euclidian norm. NumPnt Trait grouping most common operations on points. NumVec Trait grouping most common operations on vectors. Orig The zero element of a vector space, seen as an element of its embeding affine space. Outer Traits of objects having an outer product. POrd Pointwise ordering operations. PntAsVec Trait that relates a point of an affine space to a vector of the associated vector space. Repeat Trait for constructiong an object repeating a value. Rotate Trait of objects able to rotate other objects. Rotation Trait of object which can represent a rotation, and to which new rotations can be appended. A rotation is assumed to be an isometry without translation and without reflexion. RotationMatrix Trait of transformation having a rotation extractable as a rotation matrix. This can typically be implemented by quaternions to convert them to a rotation matrix. RotationTo Trait of object that can be rotated to be superimposed with another one of the same nature. RotationWithTranslation Various composition of rotation and translation. Row Trait to access rows of a matrix or a vector. RowSlice Trait to access part of a row of a matrix Shape The shape of an indexable object. SquareMat Trait implemented by square matrices. ToHomogeneous Traits of objects which can be put in homogeneous coordinates form. Transform Trait of objects able to transform other objects. Transformation Trait of object which represent a transformation, and to which new transformations can be appended. Translate Trait of objects able to translate other objects. This is typically implemented by vectors to translate points. Translation Trait of object which represent a translation, and to wich new translation can be appended. Transpose Trait of objects which can be transposed. UniformSphereSample Trait of vectors able to sample a unit sphere.

## Functions

 abs Computes a component-wise absolute value. absolute_rotate Applies a rotation using the absolute values of its components. angle_between Computes the angle of the rotation needed to transfom `a` to `b`. append_rotation Applies the rotation `v` to a copy of `m`. append_rotation_wrt_center Rotates a copy of `m` by `amount` using `m.translation()` as the pivot point. append_rotation_wrt_point Rotates a copy of `m` by `amount` using `center` as the pivot point. append_transformation Gets a transformed copy of `m`. append_translation Applies the translation `v` to a copy of `m`. approx_eq Tests approximate equality. approx_eq_eps Tests approximate equality using a custom epsilon. canonical_basis Computes the canonical basis for a given dimension. canonical_basis_element Gets the (0-based) i-th element of the canonical basis of V. cast Converts an object from one type to another. center Returns the center of two points. cholesky Cholesky decomposition G of a square symmetric positive definite matrix A, such that A = G * GT clamp Change the input value to ensure it is on the range `[min, max]`. cov Computes the covariance of a set of observations. cross Computes the cross product of two vectors. cross_matrix Given a vector, computes the matrix which, when multiplied by another vector, computes a cross product. det Computes the determinant of a square matrix. diag Gets the diagonal of a square matrix. dim Gets the dimension an object lives in. dist Returns the distance between two points. dot Computes the dot product of two vectors. eigen_qr Computes the eigenvalues and eigenvectors of a square matrix usin the QR algorithm. from_homogeneous Converts a matrix or vector from homogeneous coordinates. householder_matrix Get the householder matrix corresponding to a reflexion to the hyperplane defined by `vec`. It can be a reflexion contained in a subspace. identity Create a special identity object. inf Returns the infimum of `a` and `b`. inv Gets an inverted copy of a matrix. inv_rotate Applies an inverse rotation to a vector. inv_rotation Gets the inverse rotation applicable by `m`. inv_transform Applies an inverse transformation to a vector. inv_transformation Gets the inverse transformation applicable by `m`. inv_translate Applies an inverse translation to a point. inv_translation Gets the inverse translation applicable by `m`. is_zero Tests is a value is iqual to zero. max Same as `cmp::max`. mean Computes the mean of a set of observations. min Same as `cmp::min`. new_identity Construct the identity matrix for a given dimension norm Computes the L2 norm of a vector. normalize Gets the normalized version of a vector. one Create a one-valued value. orig Returns the trivial origin of an affine space. orthonormal_subspace_basis Computes the basis of the orthonormal subspace of a given vector. outer Computes the outer product of two vectors. partial_clamp Clamp `value` between `min` and `max`. Returns `None` if `value` is not comparable to `min` or `max`. partial_cmp Compare `a` and `b` using a partial ordering relation. partial_ge Returns `true` iff `a` and `b` are comparable and `a >= b`. partial_gt Returns `true` iff `a` and `b` are comparable and `a > b`. partial_le Returns `true` iff `a` and `b` are comparable and `a <= b`. partial_lt Returns `true` iff `a` and `b` are comparable and `a < b`. partial_max Return the maximum of `a` and `b` if they are comparable. partial_min Return the minimum of `a` and `b` if they are comparable. prepend_rotation Pre-applies the rotation `v` to a copy of `m`. qr QR decomposition using Householder reflections. repeat Create an object by repeating a value. rotate Applies a rotation to a vector. rotation Gets the rotation applicable by `m`. rotation_between Computes the rotation needed to transform `a` to `b`. sample_sphere Samples the unit sphere living on the dimension as the samples types. shape Gets the indexable range of an object. sqdist Returns the squared distance between two points. sqnorm Computes the squared L2 norm of a vector. sup Returns the supremum of `a` and `b`. to_homogeneous Converts a matrix or vector to homogeneous coordinates. to_rot_mat Builds a rotation matrix from `r`. transform Applies a transformation to a vector. transformation Gets the transformation applicable by `m`. translate Applies a translation to a point. translation Gets the translation applicable by `m`. transpose Gets a transposed copy of a matrix. zero Create a zero-valued value.