Quick reference§

Free functions are noted with a leading :: while methods start with a dot. Most types are type aliases. Refer to the API documentation for details about the functions arguments and type parameters.

Matrices and vectors
Geometry
- Points and transformations
- Projections
Data storages and allocators

Serialization with serde can be enabled by enabling the serde-serialize feature.

Matrices and vectors§

Within this reference, N is the scalar type, R, C and D are type-level integers.
Matrices are stored in column-major order.
Vectors are type aliases for matrices with only one column or one row.
Overloaded operators: *, /, +, - (binary and unary), and corresponding assignement operators.
Comparison operators ==, >=, <=, >, <, using column-major lexicographic ordering.
Mutable and non-mutable indexing: the_vector[usize] and the_matrix[(usize, usize)].
All angles are in radian.

Matrix<...> Generic matrix type.
Matrix1<N> .. Matrix6<N>, MatrixN<N, D> Statically-sized square matrix.
Matrix1x2<N> .. Matrix6x5<N>, MatrixMN<N, R, C> Statically-sized rectangular matrix.
DMatrix<N> Dynamically-sized matrix.

Vector1<N> .. Vector6<N>, VectorN<N, D> Statically-sized column vector.
DVector<N> Dynamically-sized column vector.

RowVector1<N> .. RowVector6<N>, RowVectorN<N, D> Statically-sized row vector.
RowDVector<N> Dynamically-sized row vector.

Unit<T> Wrapper that ensures the underlying value of type T is normalized.

MatrixSlice1<N> .. MatrixSlice6<N>, MatrixSliceN<N, D> Statically-sized square matrix slice.
MatrixSlice1x2<N> .. MatrixSlice6x5<N>, MatrixSliceMN<N, R, C> Statically-sized rectangular matrix slice.
MatrixSlice1xX<N> .. MatrixSlice6xX<N> Rectangular matrix slice with a dynamic number of columns.
MatrixSliceXx1<N> .. MatrixSliceXx6<N> Rectangular matrix slice with a dynamic number of rows.
DMatrixSlice<N> Dynamically-sized matrix slice.

Add Mut before the dimension numbers for mutable slice types, e.g., MatrixSliceMut1x2<N>, DMatrixSliceMut<N>.

VectorSlice1<N> .. VectorSlice6<N>, VectorSliceN<N, D> Statically-sized column vector.
DVectorSlice<N> Dynamically-sized column vector.

Add Mut before the dimension numbers for mutable slice types, e.g., VectorSliceMut3<N>, DVectorSliceMut<N>.

Construction§

The exact number of argument, and the existence of some constructors depend on the result matrix type. For example, dynamically-sized or 2D vectors do not have a ::z() constructors. In the following “Low-dimensional” means with dimensions 1 to 6 for vectors and 1x1 to 6x6 for matrices.

::x(), ::y(), ::z(), ::w(), ::a(), ::b() Low-dimensional vector with one component set to 1 and others to 0.
::x_axis() .. ::b_axis() Low-dimensional vector wrapped in Unit<...>.
::new(x, y, .. b) Low-dimensional vector constructed from its components values.
::new(m11, m12, .. m66) Low-dimensional matrix constructed from its components values.

In the following, ellipsis ... are either no arguments, one usize argument (the number of rows or the number of columns), or two usize arguments (the number of rows and columns), depending on the number of dimensions unknown at compile-time of the matrix being created.

::new_uninitialized(...) [unsafe] Matrix with uninitialized components.
::identity(...) The identity matrix.
::zeros(...) Matrix filled with zeros.
::new_random(...) Matrix filled with random values.
::from_distribution(..., distr, rng) Matrix with values generated by rng following the distribution distr.
::repeat(..., value) Matrix filled with the given value.
::from_element(..., value) Same as .from_element.
::from_iterator(..., iterator) Matrix filled with the content of the given iterator.
::from_row_slice(..., array) Matrix filled with the content of array given in row-major order.
::from_column_slice(..., array) Matrix filled with the content of array given in column-major order.
::from_fn(..., closure) Matrix filled with the result of a closure called for each entry.
::from_diagonal(..., vector) Diagonal square matrix with the given diagonal vector.
::from_diagonal_element(..., value) Diagonal square matrix with the diagonal filled with one value.
::from_partial_diagonal(..., &[values]) Rectangular matrix with diagonal filled with the given values.
::from_rows(..., &[vectors]) Matrix formed by the concatenation of the given rows.
::from_columns(..., &[vectors]) Matrix formed by the concatenation of the given columns.

Zero::zero() Matrix filled with zeroes.
One::one() The identity matrix.
Bounded::min_value() Matrix filled with the min value of the scalar type.
Bounded::max_value() Matrix filled with the max value of the scalar type.
Rand::rand(rng) Matrix filled with random values.

Common methods§

.len() The number of components.
.shape() The number of rows and columns.
.nrows() The number of rows.
.ncols() The number of columns.
.strides() Number of skipped original rows/columns in-between each row/column of a slice.

.iter() An iterator through the matrix components in column-major order.
.iter_mut() A mutable iterator through the matrix components in column-major order.
.get_unchecked(i, j) [unsafe] Component at row i and column j. No bound checking.
.get_unchecked_mut(i, j) [unsafe] Mutable component at row i and column j. No bound checking.
.swap_unchecked(i, j) [unsafe] Swaps two components. No bound checking.
.as_slice() Reference to the internal column-major array of component.
.as_mut_slice() Mutable reference to the internal column-major array of component.

.upper_triangle() Extracts the upper triangle, including the diagonal.
.lower_triangle() Extracts the lower triangle, including the diagonal.
.swap_rows(id_row1, id_row2) Swaps two rows.
.swap_columns(id_col1, id_col2) Swaps two columns.

.copy_from(matrix) Copies the content of another matrix with the same shape.
.fill(value) Sets all components to value.
.fill_diagonal(value) Fills the matrix diagonal with a single value.
.fill_lower_triangle(value) Fills some sub-diagonals below the main diagonal with a value.
.fill_upper_triangle(value) Fills some sub-diagonals above the main diagonal with a value.
.map(f) Applies f to each component and stores the results on a new matrix.
.apply(f) Applies in-place f to each component of the matrix.
.zip_map(m2, f) Applies f to pairs of components from self and m2 into a new matrix.

.relative_eq(abolutes_eps, relative_eps) Componentwise approximate matrix equality.
.component_mul(rhs) Componentwise multiplication (aka. Hadamard product).
.component_mul_assign(rhs) In-place componentwise multiplication (aka. Hadamard product).
.component_div(rhs) Componentwise division.
.component_div_assign(rhs) In-place componentwise division.

.transpose() Matrix transposition.
.transpose_mut() In-place matrix transposition.
.transpose_to(output) Transposes a matrix to the given output.
.conjugate_transpose() Complex matrix transposed conjugate.
.conjugate_transpose_mut() In-place complex matrix transposed conjugate.
.conjugate_transpose_to(output) Conjugate-transposes a complex matrix to the given output matrix.
.try_inverse() Matrix inverse. Returns None if it fails.
.try_inverse_mut() In-place matrix inverse. Returns false if it fails.

.diagonal() The matrix diagonal.
.abs() The absolute value of this matrix components.
.determinant() The matrix determinant.
.trace() The trace of this matrix.
.norm() The L2 norm.
.norm_squared() The squared L2 norm.
.normalize() Normalization using the L2 norm.
.normalize_mut() In-place normalization using the L2 norm.
.try_normalize() Normalization. Returns None if the norm is too small.
.try_normalize_mut() In-place normalization. Returns None if the norm is too small.

.dot(rhs) Vector dot product.
.tr_dot(rhs) Vector dot product between self.transpose() and rhs.
.perp(rhs) 2D cross product, i.e., determinant of the matrix formed by two 2D column vectors.
.cross(rhs) 3D cross product.
.kronecker(rhs) Matrix tensor (kronecker) product.
.angle(rhs) Smallest angle between two vectors.

.is_square() Tests if self is square.
.is_identity() Tests if self is the identity matrix.
.is_orthogonal() Tests if self.transpose() * self is the identity.
.is_special_orthogonal() Tests if self.is_orthogonal() and has a determinant equal to 1.
.is_invertible() Tests if self is invertible.

Slicing§

Slice are references to sub-matrices. They do not own their data and cannot be converted to arrays as their data buffer may not be contiguous in memory. Mutable slices are obtained using the same methods suffixed by _mut, e.g., .row_mut(i). They can also be constructed from a data array &[N] using the constructors of matrix slice type aliases, e.g., MatrixSlice3::from_slice(data).

.row(i) A matrix row.
.rows(i, nrows) Several consecutive rows.
.rows_with_step(i, nrows, step) Several non-consecutive rows.
.fixed_rows::<D>(i) A compile-time number of consecutive rows.
.fixed_rows_with_step::<D>(i, step) A compile-time number of non-consecutive rows.

.column(j) A matrix column.
.columns(j, ncols) Several consecutive columns.
.columns_with_step(j, ncols, step) Several non-consecutive columns.
.fixed_columns::<D>(j) A compile-time number of consecutive columns.
.fixed_columns_with_step::<D>(j, step) A compile-time number of non-consecutive columns.

.slice((i, j), (nrows, ncols)) Consecutive rows and columns.
.slice_with_steps((i, j), (nrows, ncols), (rstep, cstep) Non consecutive rows and columns.
.fixed_slice::<R, C>((i, j)) Compile-time number of consecutive rows and columns.
.fixed_slice_with_steps::<R, C>((i, j), (rstep, cstep)) Compile-time number of non consecutive rows and columns.

Resizing§

The dimension of a matrix can be modified by inserting or removing rows or columns and by changing its dimensions. The input is always consumed to produce the output. Inserted rows/columns are filled by a user-provided value.

.remove_row(i) Removes one row.
.remove_rows(i, nrows) Removes several consecutive rows.
.remove_fixed_rows::<D>(i) Removes a compile-time number of consecutive rows.

.remove_column(j) Removes one column.
.remove_columns(j, ncols) Removes several consecutive columns.
.remove_fixed_columns::<D>(j) Removes a compile-time number of consecutive columns.

.insert_row(i, val) Adds one row filled with val.
.insert_rows(i, nrows, val) Adds several consecutive rows filled with val.
.insert_fixed_rows::<D>(i, val) Adds a compile-time number of consecutive rows filled with val.

.insert_column(j, val) Adds one column.
.insert_columns(j, ncols, val) Adds several consecutive columns.
.insert_fixed_columns::<D>(j, val) Adds a compile-time number of consecutive columns.

.resize(nrows, ncols, val) Resizes the output matrix to nrows rows and ncols columns.
.fixed_resize<R, C>(val) Resizes the output matrix to R rows and C columns.

Resizing methods keep the original component values, i.e., self[(i, j)] == output[(i, j)]. Additional rows and columns are filled with val.

Blas operations§

nalgebra implements some Blas operations in pure Rust. In the following, the variables $\mathbf{v}$ and $\mathbf{V}$ designs the self argument.

.iamax() Returns the index of the vector component with the greatest absolute value.
.iamax_full() Returns the index of the matrix component with the greatest absolute value.
.dot(x) Computes the scalar product $\left<\mathbf{v}, \mathbf{x}\right>$ .
.axpy(alpha, x, beta) Computes $\mathbf{v} = \alpha \mathbf{x} + \beta \mathbf{v}$ .
.gemv(alpha, A, x, beta) Computes $V = \alpha A \mathbf{x} + \beta V$ with a matrix and vector $a$ and $\mathbf{x}$ .
.ger(alpha, x, y, beta) Computes $V = \alpha \mathbf{x}^T \mathbf{y} + \beta V$ where $\mathbf{x}$ and $\mathbf{y}$ are vectors.
.gemm(alpha, A, B, beta) Computes $V = \alpha A B + \beta V$ where $A$ and $B$ are matrices.
.gemv_symm(...) Is the same as .gemv except that self is assumed symmetric.
.ger_symm(...) Is the same as .ger except that self is assumed symmetric.
.gemv_tr(...) Is the same as .gemv except that the transpose of A is considered.

Other operations that work like blas operations (i.e., in-place and real coefficients) are implemented:

.imax() Returns the index of the vector component with the greatest (signed) value.
.imin() Returns the index of the vector component with the greatest (signed) value.
.iamin() Returns the index of the vector component with the smallest absolute value.
.cmpy(alpha, a, b, beta) Computes the component-wise multiplication: $\mathbf{v}_i = \alpha \mathbf{a}_i * \mathbf{b}_i + \beta \mathbf{v}_i$ .
.cdpy(alpha, a, b, beta) Computes the component-wise division: $\mathbf{v}_i = \alpha \mathbf{a}_i / \mathbf{b}_i + \beta \mathbf{v}_i$ .
.quadform(alpha, M, B, beta) Computes the quadratic form $V = \alpha B^TMB + \beta V$ .
.quadform_tr(alpha, A, M, beta) Computes the quadratic form $V = \alpha AMA^T + \beta V$ .

Decompositions§

All matrix decompositions are implemented in Rust and operate on Real matrices only. Refer to Lapack integration for lapack-based decompositions.

.bidiagonalize() Bidiagonalization of a general matrix.
.symmetric_tridiagonalize() Tridiagonalization of a general matrix.
.cholesky() Cholesky factorization of a Symmetric-Definite-Positive square matrix.
.qr() QR decomposition.
.lu() LU decomposition with partial (row) pivoting.
.full_piv_lu() LU decomposition with full pivoting.
.hessenberg() Hessenberg form computation for a square matrix.
.real_schur() Real Schur decomposition of a square matrix.
.symmetric_eigen() Eigenvalue and eigenvectors computation of a symmetric matrix.
.svd() Singular Value Decomposition.

Iterative methods may take extra parameters to control their convergence: an error tolenence eps (set to machine epsilon by default) and maximum number of iteration (set to infinite by default):

.try_real_schur(eps, max_niter) Real Schur decomposition of a square matrix.
.try_symmetric_eigen(eps, max_niter) Eigenvalue and eigenvectors computation of a symmetric matrix.
.try_svd(eps, max_niter) Singular Value Decomposition.

Lapack integration§

Lapack-based decompositions are available using the nalgebra-lapack crate. Refer the the dedicated section for details regarding its use and the choice of backend (OpenBLAS, netlib, or Accelerate) The following factorization are implemented:

Cholesky::new(matrix) Cholesky factorization of a Symmetric-Definite-Positive matrix.
QR::new(matrix) QR decomposition.
LU::new(matrix) LU decomposition with partial (row) pivoting.
Hessenberg::new(matrix) Hessenberg form computation.
RealSchur::new(matrix) Real Schur decomposition of a square matrix.
Eigen::new(matrix, compute_left, compute_right) Eigendecomposition of a symmetric matrix.
SymmetricEigen::new(matrix) Eigendecomposition of a symmetric matrix.
SVD::new(matrix) Singular Value Decomposition.

Computer graphics§

Those are constructors and methods useful for the computer graphics community that work with homogeneous matrix coordinates, e.g., 4x4 matrices for 3D transformations. Homogeneous matrix coordinates are expected to be multiplied by homogeneous vectors (the vector goes on the right-hand-side of the operator).

::new_scaling(factor) An uniform scaling matrix.
::new_nonuniform_scaling(vector) A nonuniform scaling matrix.
::new_translation(vector) A translation matrix.
::new_rotation(angle) A 2D rotation matrix from an angle.
::new_rotation(axisangle) A 3D rotation matrix from an axis multiplied by an angle.
::new_rotation_wrt_point(axiangle, point) An 3D isometry matrix that lets the given point invariant.
::from_scaled_axis(axisangle) A 3D rotation matrix from an axis multiplied by an angle.
::from_euler_angles(roll, pitch, yaw) A 3D rotation matrix from euler angles (roll → pitch → yaw).
::from_axis_angle(axis, angle) A 3D rotation matrix from an axis and an angle.
::new_orthographic(left, right, top, bottom, znear, zfar) A 3D orthographic projection matrix.
::new_perspective(aspect, fovy, znear, zfar) A 3D perspective projection matrix.
::new_observer_frame(eye, target, up) 3D local coordinate system of a player looking toward target.
::look_at_rh(eye, target, up) A 3D right-handed look-at matrix.
::look_at_lh(eye, target, up) A 3D left-handed look-at matrix.

.append_scaling(factor) Applies an uniform scaling after self.
.append_scaling_mut(factor) Applies in-place an uniform scaling after self.
.prepend_scaling(factor) Applies an uniform scaling beforeself.
.prepend_scaling_mut(factor) Applies in-place an uniform scaling before self.
.append_nonuniform_scaling(vector) Applies a non-uniform scaling after self.
.append_nonuniform_scaling_mut(vector) Applies in-place a non-uniform scaling after self.
.prepend_nonuniform_scaling(vector) Applies a non-uniform scaling beforeself.
.prepend_nonuniform_scaling_mut(vector) Applies in-place a non-uniform scaling before self.
.append_translation(vector) Applies a translation after self.
.append_translation_mut(vector) Applies in-place a translation after self.
.prepend_translation(vector) Applies a translation before self.
.prepend_translation_mut(vector) Applies in-place a translation before self.

Geometry§

Most geometric entities are just wrappers for a matrix (or a vector).
Points have a very different semantic than vectors.
Transformation types are preferred over raw matrices as they allow optimization because of their intrinsic properties.
Use .to_homogeneous() pour obtain the corresponding homogeneous raw matrix of any geometric entity.
Transformations of different types can be multiplied together. The result type is automatically inferred.
Transforming a point or vector can be done by multiplication. The transformation goes on the left-hand-side.
In the following, notations like Transform2/3<N> means “either Transform2<N> or Transform3<N>”.

Point2/3<N> A location in space.
Quaternion<N> A general quaternion.
Rotation2/3<N> A rotation matrix.
UnitComplex<N> A 2D rotation represented as a unit complex number.
UnitQuaternion<N> A 3D rotation represented as a unit quaternion.
Translation2/3<N> A translation (stored as a vector).
Isometry2/3<N> A 2D/3D isometry containing an unit complex/quaternion.
Similarity2/3<N> A 2D/3D similarity containing an unit complex/quaternion.
Affine2/3<N> An affine transformation stored as an homogeneous matrix.
Projective2/3<N> An invertible transformation stored as an homogeneous matrix.
Transform2/3<N> A general transformation stored as an homogeneous matrix.

Projections§

Projections follow the behavior expected by Computer Graphics community, i.e., they are invertible transformation from a convex shape to a unit cube centered at the origin.

Perspective3<N> 3D perspective projection matrix using homogeneous coordinates.
Orthographic3<N> 3D orthographic projection matrix using homogeneous coordinates.

Base types§

Base types are generic wrt. the dimension and/or the data storage type. They should not be used directly, prefer type aliases shown in the previous section instead.

Point<N> A location in space.
Rotation<N, Dim> A rotation matrix.
Translation<N, Dim> A translation vector.
Isometry<N, Dim, Rotation> An isometry containing an abstract rotation type.
Similarity<N, Dim, Rotation> A similarity containing an abstract rotation type.
Transform<N, Dim, Affine> An affine transformation stored as an homogeneous matrix.
Transform<N, Dim, Projective> An invertible transformation stored as an homogeneous matrix.
Transform<N, Dim, General> A general transformation stored as an homogeneous matrix.
Perspective<N> A 3D perspective projection matrix.
Orthographic<N> A 3D orthographic projection matrix.

Data storage and allocators§

Data storages provide access to a matrix shape and its components.
The last type parameter of the generic Matrix<...> type is the data storage.
Allocators provide a way to allocate a data storage type that depends on whether the matrix shape is statically known. The Allocator trait should not be implemented manually by the user. Only one implementor exists: DefaultAllocator.

Traits§

Storage<...> Implemented by buffers that may store matrix elements non-contiguously.
StorageMut<...> Implemented by mutable buffers that may store matrix elements non-contiguously.
ContiguousStorage<...> Implemented by buffers storing matrix components contiguously.
ContiguousStorageMut<...> Implemented by mutable buffers storing matrix components contiguously.

Implementors§

MatrixArray<...> A stack-allocated owned data storage.
MatrixVec<...> A heap-allocated owned data storage.
MatrixSlice<...> A non-mutable reference to a piece of another data storage.
MatrixSliceMut<...> A mutable reference to a piece of another data storage.
DefaultAllocator<...> Allocates MatrixArray for statically sized matrices, and MatrixVec otherwise.