# 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§

- 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>`

, `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 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)`

.

`.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 before`self`

.

`.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 before`self`

.

`.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.

Getting started Vectors and matrices