# `vqm` Rust Crate<br> [](https://opensource.org/licenses/Apache-2.0) 
A **vector**, **quaternion**, and **matrix** (**VQM**) library targeted at embedded systems and robotics.
(In particular stabilized vehicles including self-balancing robots and aircraft).
This crate is `no_std`, that it does not link to the standard library and so does not depend on an operating system
and uses no allocation. This means it is suitable for embedded system.
## Overview
Vectors have 2D, 3D, and 4D versions.
Matrices have 2x2, 3x3, 4x4, and 9x9 versions. The 9x9 matrix implementation has been added to support Kalman filters
and is incomplete.
Each type has versions for `f32` and `f64`. So we have:
1. 2D vectors: `Vector2df32`, `Vector2df64`
2. 3D vectors: `Vector3df32`, `Vector3df64`
3. 4D vectors: `Vector4df32`, `Vector4df64`
4. [quaternions](https://en.wikipedia.org/wiki/Quaternion): `Quaternionf32`, `Quaternionf64`
5. 2x2 matrices: `Matrix2x2f32`, `Matrix2x2f64`
6. 3x3 matrices: `Matrix3x3f32`, `Matrix3x3f64`
7. 4x4 matrices: `Matrix4x4f32`, `Matrix4x4f64`
8. 9x9 matrices: `Matrix9x9f32`, `Matrix9x9f64` - partial implementation with special functions for Kalman filters.
The 3D vector additionally has `i16` and `i32` versions: `Vector3di16` and `Vector3di32`.
(Under the hood, types are implemented using generics, so `Vector3df32` is actually `Vector3d<f32>`,
but that is transparent to the user.)
## Mathematical methods and constants
This crate also provides implementations of the trigonometric methods normally provided by the standard library, namely:
`sin`, `cos`, `sin_cos`, `tan`, `asin`, `acos`, `atan2`. The are provided in `method_call` syntax, ie `x.sin()`.
The methods `sqrt` and `sqrt_reciprocal` are also provided.
The `MathConstants` trait provides a the standard mathematical constants in a form that can be used in generic code
ie `T:PI`.
## SIMD support
**SIMD** support can be enabled with the `simd` feature.
It is currently experimental and many of the implementations are naive "placeholder" implementations to be optimized at a later date.
These placeholder implementations may be slower than the non-SIMD code, so if you used SIMD make sure you benchmark to show
that you are indeed getting a performance improvement.
This uses [portable simd](https://doc.rust-lang.org/core/simd/index.html), which requires the nightly compiler, since it is still
unstable in rust.
This can be invoked using `rustup`, eg:
```sh
rustup run nightly cargo build --features simd --target thumbv8m.main-none-eabi
```
## Struct alignment
By default `Vector3df32` is aligned to a 16-byte boundary, and `Matrix3x3f32` is aligned to a 32-byte boundary.
This can be turned off using the `no_align` feature flag:
```sh
cargo build -features no_align
```
If `no_align` is used then SIMD support is not available.
## Architecture
See [ARCHITECTURE.md] for details on `vqm`'s internals.
[ARCHITECTURE.md]: ARCHITECTURE.md
## Original implementation
I originally implemented this crate as a C++ library:
[Library-VectorQuaternionMatrix](https://github.com/martinbudden/Library-VectorQuaternionMatrix).
The capabilities of this crate now exceed those of the original library.
## License
Licensed under either of:
* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
at your option.