Skip to content

Safe and fast mathematical operations with static arrays in the Rust programming language

Notifications You must be signed in to change notification settings

elsuizo/static-math

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

MIT Documentation crates.io

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

  • You could index the rows of the matrix with simply: m[i]

  • 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 Quaternions (and all the most used methods)

  • We have implemented DualQuaternions (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 16.23 us 16.13 us 9.954 us 16.18 us 16.2 us 10.42 us 9.97 us 16.17 us
euler 3d x10000 15.95 us 32.11 us 32.13 us 32.13 us 32.13 us 16.27 us 32.16 us 32.11 us
matrix2 determinant 2.0386 ns 2.0999 ns 2.1018 ns N/A 2.0997 ns 2.0987 ns 2.0962 ns 2.1080 ns
matrix2 inverse 2.8226 ns 8.4418 ns 7.6303 ns N/A N/A 3.3459 ns 9.4636 ns 5.8796 ns
matrix2 mul matrix2 2.6036 ns 5.0007 ns 4.8172 ns N/A 9.3814 ns 2.5516 ns 4.7274 ns 4.9428 ns
matrix2 mul vector2 x1 2.4904 ns 2.6144 ns 2.8714 ns N/A 4.2139 ns 2.0839 ns 2.8873 ns 2.6250 ns
matrix2 mul vector2 x100 227.5271 ns 243.3579 ns 265.1698 ns N/A 400.6940 ns 219.7127 ns 267.8780 ns 243.9880 ns
matrix2 return self 2.4235 ns 2.8841 ns 2.8756 ns N/A 2.8754 ns 2.4147 ns 2.8717 ns 2.8697 ns
matrix2 transpose 2.2887 ns 3.0645 ns 7.9154 ns N/A 2.9635 ns N/A 3.0637 ns 3.0652 ns
matrix3 determinant 3.9129 ns 3.8107 ns 3.8191 ns N/A 3.8180 ns N/A 3.8151 ns 8.9368 ns
matrix3 inverse 17.5373 ns 18.6931 ns 12.3183 ns N/A N/A N/A 12.8195 ns 21.9098 ns
matrix3 mul matrix3 9.9578 ns 13.3648 ns 7.8154 ns N/A 35.5802 ns N/A 6.4938 ns 10.0527 ns
matrix3 mul vector3 x1 4.8090 ns 4.9339 ns 4.5046 ns N/A 12.5518 ns N/A 4.8002 ns 4.8118 ns
matrix3 mul vector3 x100 0.4836 us 0.4808 us 0.4755 us N/A 1.247 us N/A 0.4816 us 0.4755 us
matrix3 return self 5.4421 ns 5.4469 ns 5.4526 ns N/A 5.4656 ns N/A 5.4718 ns 5.4043 ns
matrix3 transpose 9.9567 ns 10.0794 ns 10.9704 ns N/A 9.9257 ns N/A 10.7350 ns 10.5334 ns
matrix4 determinant 6.2050 ns 11.1041 ns 69.2549 ns 17.1809 ns 18.5233 ns N/A 16.5331 ns 8.2704 ns
matrix4 inverse 16.4386 ns 47.0674 ns 71.8174 ns 64.1356 ns 284.3703 ns N/A 52.6993 ns 41.1780 ns
matrix4 mul matrix4 7.7715 ns 26.7308 ns 8.6500 ns 10.4414 ns 86.1501 ns N/A 21.7985 ns 26.8056 ns
matrix4 mul vector4 x1 3.0303 ns 7.7400 ns 3.4091 ns N/A 21.0968 ns N/A 6.2971 ns 6.2537 ns
matrix4 mul vector4 x100 0.6136 us 0.9676 us 0.627 us N/A 2.167 us N/A 0.7893 us 0.8013 us
matrix4 return self 7.1741 ns 6.8838 ns 7.5030 ns N/A 7.0410 ns N/A 6.7768 ns 6.9508 ns
matrix4 transpose 6.6826 ns 12.4966 ns 15.3265 ns N/A 12.6386 ns N/A 15.2657 ns 12.3396 ns
ray-sphere intersection x10000 56.2 us 55.7 us 15.32 us 55.45 us 56.02 us N/A N/A 50.94 us
rotation3 inverse 2.3113 ns 3.1752 ns 3.3292 ns 3.3311 ns 3.1808 ns N/A 8.7109 ns 3.6535 ns
rotation3 mul rotation3 3.6584 ns 7.5255 ns 7.4808 ns 8.1393 ns 14.1636 ns N/A 6.8044 ns 7.6386 ns
rotation3 mul vector3 x1 6.4950 ns 7.6808 ns 7.5784 ns 7.5746 ns 18.2547 ns N/A 7.2727 ns 8.9732 ns
rotation3 mul vector3 x100 0.6465 us 0.7844 us 0.7573 us 0.7533 us 1.769 us N/A 0.7317 us 0.9416 us
rotation3 return self 2.4928 ns 2.8740 ns 2.8687 ns N/A 2.8724 ns N/A 4.7868 ns 2.8722 ns
transform point2 x1 2.7854 ns 2.8878 ns 4.4207 ns 2.8667 ns 11.9427 ns 2.3601 ns N/A 4.1770 ns
transform point2 x100 0.3316 us 0.3574 us 0.4445 us 0.3008 us 1.212 us 0.3184 us N/A 0.4332 us
transform point3 x1 2.9619 ns 10.6812 ns 6.1037 ns 7.7051 ns 13.2607 ns 3.0934 ns N/A 6.8419 ns
transform point3 x100 0.6095 us 1.27 us 0.8064 us 0.7674 us 1.446 us 0.6189 us N/A 0.8899 us
transform vector2 x1 2.4944 ns N/A 3.7174 ns 2.6273 ns 11.9424 ns N/A N/A 3.0458 ns
transform vector2 x100 0.3125 us N/A 0.3871 us 0.2817 us 1.213 us N/A N/A 0.3649 us
transform vector3 x1 2.8091 ns 7.7343 ns 5.5064 ns 4.4810 ns 15.4097 ns N/A N/A 4.8819 ns
transform vector3 x100 0.6035 us 0.9439 us 0.7573 us 0.6327 us 1.63 us N/A N/A 0.6703 us
transform2 inverse 9.0256 ns N/A 12.2614 ns 9.4803 ns N/A 8.9047 ns N/A N/A
transform2 mul transform2 4.5111 ns N/A 8.1434 ns 5.8677 ns N/A 3.8513 ns N/A N/A
transform2 return self 4.1707 ns N/A 5.4356 ns 4.2775 ns N/A 4.1117 ns N/A N/A
transform3 inverse 10.9869 ns N/A 71.4437 ns 56.0136 ns N/A 23.0392 ns N/A N/A
transform3 mul transform3d 6.5903 ns N/A 8.5673 ns 10.1802 ns N/A 7.6587 ns N/A N/A
transform3 return self 7.1828 ns N/A 7.2619 ns 7.2407 ns N/A 7.3214 ns N/A N/A
vector3 cross 2.4257 ns 3.6842 ns 3.7945 ns 3.6821 ns 3.8323 ns N/A 3.8622 ns 3.6927 ns
vector3 dot 2.1055 ns 2.3179 ns 2.3174 ns 2.3190 ns 2.3195 ns N/A 2.3204 ns 2.3160 ns
vector3 length 2.5020 ns 2.5002 ns 2.5986 ns 2.5013 ns 2.5021 ns N/A 2.5036 ns 2.5017 ns
vector3 normalize 4.0454 ns 5.8411 ns 8.4069 ns 8.0679 ns 8.8137 ns N/A N/A 5.8440 ns
vector3 return self 2.4087 ns 3.1021 ns 3.1061 ns N/A 3.1052 ns N/A 3.1136 ns 3.1071 ns

TODOS:

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