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.

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

Matrices and vectors§


Matrix<...> Generic matrix type.
Matrix1<N> .. Matrix6<N>, MatrixN<N, D> Statically-sized square matrix.
Matrix1x2<N> .. Matrix6x5<N>, MatrixNM<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.


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.
::new_random(...) Matrix filled with random values.
::identity(...) The identity matrix.
::zeros(...) Matrix filled with zeros.
::from_element(..., value) Matrix filled with the given value.
::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 bellow 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).

.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 and 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 .
.axpy(alpha, x, beta) Computes .
.gemv(alpha, A, x, beta) Computes with a matrix and vector and .
.ger(alpha, x, y, beta) Computes where and are vectors.
.gemm(alpha, A, B, beta) Computes where and 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.


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§

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§

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.


Getting started Vectors and matrices