## static-math

Fast mathematical operations with static arrays, without `unsafe` code

### 14 releases

 0.2.3 Aug 5, 2021 Jul 31, 2021 Sep 13, 2020 Jun 28, 2020

#245 in Math

390KB
9K SLoC

# Static Math in Rust programming language

"Simple things should be simple, complex things should be possible" Alan Kay.

• This crate take advantage of the static arrays in Rust for fast operations in stack memory.

• We use a tuple to indexing elements: `m[(i, j)]` allowing nice interface with the `match` feature of Rust

• No `unsafe` code ☑️

• Could be optimize more with the use of SIMD

• This crate could be used in an `no-std` environment.

by enabling the feature `no-std`, for example in your `Cargo.toml`:

``````[dependencies.static-math]
default-features = false
version = "0.2.0"
features = ["no-std"]
``````
• You can visualize the matrices

``````inverse:
|-0.54    0.58    0.67    -0.08   -0.17    -1.18|
|2.16     -1.53   -2.44   0.44    0.32      3.77|
|0.21     -0.42   -0.39   0.15    0.20      0.62|
|0.70     -0.24   -0.53   0.20    -0.21     0.73|
|0.85     -0.47   -0.83   0.11    0.11      1.20|
|-3.91    2.47    4.17    -0.87   -0.31    -6.08|
``````
• The determinant of the matrices are evaluated "in-place" without loops and code bifurcations

• The use cases can be: Robotics, Game programming, Simulations ...etc.

The matrix types `Mnn` (where `n=2..6`) implements the Methods from the `LinearAlgebra` trait:

• `det()`: Determinant of the matrix

• `inverse()`: Inverse of the matrix

• `qr()`: QR decomposition of the matrix

• `norm2()`: norm of the matrix

• `transpose()`: transpose of the matrix

• `trace()`: trace of the matrix

• `shape()`: shape of the matrix

• We have implemented `Quaternion`s (and all the most used methods)

• We have implemented `DualQuaternion`s (and all the most used methods in Robotics and graphics like Screw Linear Interpolation)

• We have implemented in the `transformations.rs` module a wide variety of functions used in Robotics (which conforms to the screw theory)

## Benchmarks

Using the criterion crate:

https://github.com/bheisler/criterion.rs

run with: `cargo bench`

Others benches comparing the performance with others crates are in this repo: https://github.com/bitshifter/mathbench-rs

NOTE: this is the only crate that not have unsafe code

with the following results:

benchmark glam cgmath nalgebra euclid vek pathfinder static-math ultraviolet
euler 2d x10000 7.555 us 7.521 us 16.38 us 11.86 us 7.513 us 9.806 us 11.83 us 7.499 us
euler 3d x10000 16.2 us 25.04 us 106.3 us 25.05 us 25.16 us 16.76 us 25.03 us 25.05 us
matrix2 determinant 2.0332 ns 2.0311 ns 2.0250 ns N/A 2.0209 ns 2.0323 ns 2.0254 ns N/A
matrix2 inverse 2.6114 ns 3.0331 ns 2.9792 ns N/A N/A 2.7550 ns 3.0132 ns N/A
matrix2 mul matrix2 2.6047 ns 2.5346 ns 2.5426 ns N/A 8.7573 ns 2.5381 ns 2.6028 ns 2.9668 ns
matrix2 mul vector2 x1 2.6592 ns 2.6104 ns 2.6214 ns N/A 4.2512 ns 2.0663 ns 2.8674 ns 2.6172 ns
matrix2 mul vector2 x100 245.2897 ns 233.7149 ns 238.7395 ns N/A 399.3148 ns 218.4107 ns 260.6645 ns 234.7099 ns
matrix2 return self 2.4740 ns 2.5994 ns 2.5968 ns N/A 2.5969 ns 2.4607 ns 2.5928 ns 2.5974 ns
matrix2 transpose 2.0852 ns 2.0814 ns 2.3426 ns N/A 2.1053 ns N/A 2.0829 ns N/A
matrix3 determinant 3.3675 ns 3.4261 ns 3.3780 ns N/A 3.4479 ns N/A 3.4375 ns N/A
matrix3 inverse 11.4209 ns 8.3701 ns 9.4315 ns N/A N/A N/A 9.1710 ns 20.1731 ns
matrix3 mul matrix3 5.8501 ns 6.5350 ns 9.8196 ns N/A 47.9203 ns N/A 9.5170 ns 6.5211 ns
matrix3 mul vector3 x1 3.9266 ns 4.3876 ns 4.3333 ns N/A 16.0858 ns N/A 4.4220 ns 4.3304 ns
matrix3 mul vector3 x100 0.4372 us 0.4416 us 0.4594 us N/A 1.59 us N/A 0.454 us 0.4425 us
matrix3 return self 4.8566 ns 4.8401 ns 4.8226 ns N/A 4.8340 ns N/A 4.8303 ns 4.8383 ns
matrix3 transpose 5.7688 ns 5.6980 ns 8.1508 ns N/A 5.6910 ns N/A 5.6936 ns 5.6766 ns
matrix4 determinant 8.3724 ns 11.1604 ns 52.8697 ns 16.0723 ns 17.5301 ns N/A 16.1402 ns N/A
matrix4 inverse 21.3281 ns 38.5833 ns 64.5172 ns 61.2347 ns 275.5253 ns N/A 48.0641 ns 37.1436 ns
matrix4 mul matrix4 7.5043 ns 8.3723 ns 9.4094 ns 10.1761 ns 90.7185 ns N/A 20.6424 ns 8.4072 ns
matrix4 mul vector4 x1 3.3645 ns 3.7273 ns 3.7251 ns N/A 24.2185 ns N/A 6.1311 ns 3.7524 ns
matrix4 mul vector4 x100 0.6105 us 0.6237 us 0.6202 us N/A 2.402 us N/A 0.7044 us 0.6202 us
matrix4 return self 6.8863 ns 7.1298 ns 6.6961 ns N/A 6.7079 ns N/A 6.6772 ns 6.7079 ns
matrix4 transpose 5.7312 ns 10.1612 ns 14.9424 ns N/A 10.2015 ns N/A 10.1996 ns 10.2391 ns
rotation3 inverse 2.1867 ns 2.9086 ns 2.8853 ns 2.9092 ns 2.8987 ns N/A N/A 2.9064 ns
rotation3 mul rotation3 3.3422 ns 4.3602 ns 7.0680 ns 7.7111 ns 8.9616 ns N/A N/A 18.4088 ns
rotation3 mul vector3 6.6977 ns 6.7831 ns 6.9924 ns 6.9801 ns 32.8778 ns N/A N/A 13.5267 ns
rotation3 return self 2.4622 ns 2.5983 ns 2.6021 ns N/A 2.5989 ns N/A N/A 2.5980 ns
transform point2 x1 3.8946 ns 2.8843 ns 4.6543 ns 3.2271 ns 17.0089 ns 2.3608 ns N/A N/A
transform point2 x100 0.4265 us 0.3677 us 0.4632 us 0.322 us 1.712 us 0.3206 us N/A N/A
transform point3 x1 4.9958 ns 6.3712 ns 6.6426 ns 6.1114 ns 24.8255 ns 3.1011 ns N/A N/A
transform point3 x100 0.6261 us 0.7418 us 0.7447 us 0.7296 us 2.507 us 0.6295 us N/A N/A
transform vector2 x1 2.7159 ns N/A 3.9917 ns 2.8070 ns 16.8257 ns N/A N/A N/A
transform vector2 x100 0.3463 us N/A 0.4018 us 0.2893 us 1.709 us N/A N/A N/A
transform vector3 x1 3.9868 ns 5.5573 ns 8.4892 ns 4.4068 ns 25.0274 ns N/A N/A N/A
transform vector3 x100 0.5905 us 0.6584 us 0.8936 us 0.6365 us 2.513 us N/A N/A N/A
transform2 inverse N/A N/A 9.4094 ns 4.6388 ns N/A 3.9983 ns N/A N/A
transform2 mul transform2 N/A N/A 9.8173 ns 6.2162 ns N/A 3.8699 ns N/A N/A
transform2 return self N/A N/A 4.8447 ns 3.5091 ns N/A 4.1391 ns N/A N/A
transform3 inverse N/A N/A 65.3982 ns 52.6160 ns N/A 32.0466 ns N/A N/A
transform3 mul transform3d N/A N/A 10.9731 ns 9.9741 ns N/A 7.6754 ns N/A N/A
transform3 return self N/A N/A 7.1596 ns 6.6096 ns N/A 7.0148 ns N/A N/A
vector3 cross 2.4542 ns 3.5894 ns 3.2434 ns 3.4923 ns 3.5150 ns N/A 3.2947 ns 7.1968 ns
vector3 dot 2.1001 ns 2.3025 ns 2.2986 ns 2.3030 ns 2.3084 ns N/A 2.3072 ns 3.7322 ns
vector3 length 2.1722 ns 2.1747 ns 2.3414 ns 2.1716 ns 2.2151 ns N/A 2.2063 ns 3.4787 ns
vector3 normalize 4.4248 ns 4.3266 ns 8.1124 ns 8.0704 ns 8.0747 ns N/A N/A 8.0778 ns
vector3 return self 2.4642 ns 2.9591 ns 2.9586 ns N/A 2.9579 ns N/A 2.9633 ns 2.9572 ns

## TODOS:

• `Quaternion` type and methods
• `expm()`: Exponential matrix implementation
• Eigenvalues
• QR decomposition

~800KB
~18K SLoC