maplant / al-jabr

Extremely generic linear algebra libary for Rust

al-jabr

An n-dimensional linear algebra and mathematics library for computer graphics and other applications, designed to be roughly compatible with cgmath.

The library provides:

• vectors: Vector2, Vector3, Vector4 and Vector<T, const N: usize>
• points: Point2, Point3, Point4 and Point<T, const N: usize>
• matrices: Matrix2, Matrix3, Matrix4 and Matrix<T, const N: usize, const M: usize>
• a quaternion type: Quaternion
• orthonormal (rotation) matrices: Orthonormal

al-jabr supports Vectors and Matrices of any size and will provide implementations for any mathematic operations that are supported by their scalars. Additionally, al-jabr can leverage Rust's type system to ensure that operations are only applied to values that are the correct size. al-jabr can do this while remaining no-std compatible.

For more information and a guide on getting started, check out the documentation.

Cargo Features

• The mint feature (off by default) adds a dependency to the mint crate and provides support for converting between al-jabr types and mint types.
• The serde feature (off by default) adds serialization/deserialization support from the serde crate.
• The rand feature (off by default) allows you to create random points, vectors, and matrices by sampling from a random number source.
• The swizzle feature (off by default) enables swizzle functions for vectors.

Contributions

Pull request of any nature are welcome.

Support

Contact the author at [email protected] or file an issue on github.

al-jabr's Issues

Should we rename aljabar to al-jabr?

As far as I can tell, Aljabar doesn't really fit as a name because it doesn't actually refer to the origins of the term algebra. Here are some pros and cons I can come up with for renaming:

Pros:

• More respectful to the linguistic origins of the term
• Allows us to go back to an earlier version number

Cons:

• less easily discoverable (via google) than original name

Avoid use of mem::uninitialized

https://github.com/maplant/aljabar/blob/4c60bb838f2480b4a454703e7f1f278a1cc748c3/src/lib.rs#L224-L225

You should use MaybeUninit instead. Calling mem::uninitialized is undefined behavior for uninhabited types like ! of enum Void {}. It is also undefined behavior for bool, as the uninitialized content may have a different value than 0 or 1, which are the only valid values for a bool. Also mem::uninitialized is deprecated in favor of MaybeUninit see docs.

Aljabar fails to build on rustc-1.39-nightly

I have been informed and can confirm that aljabar no longer builds on rustc-1.39-nightly.
I am investigating the cause of this and the minimal reproducible source but for now, you will have to use 1.38.

Rust makes no guarantees that experimental features will work, so this is to be expected. In the mean time I should probably set up continuous integration to at least display something on the github page.

Higher-dimensional tensors

I notice that you have vectors and matrices. Would you be willing to accept PRs adding a few more dimensions? We can leave Vector and Matrix and make them aliases of something like Tensor1 and Tensor2. Then we can start to add operations like higher-dimensional convolution and such.

If this is outside the scope of aljabar, I don't mind creating a new crate, but I figure this is a good place for collective const generics experimentation on linear algebra, so I wanted to see if this is of interest.

`swap_columns` and `swap_rows` are unsound

Both functions are built with the same structure and safety reasoning, so I'll focus on swap_columns.

pub fn swap_columns(&mut self, a: usize, b: usize) {
    let a: *mut MaybeUninit<Vector<T, { N }>> = unsafe { mem::transmute(&mut self.0[a]) };
    let b: *mut MaybeUninit<Vector<T, { N }>> = unsafe { mem::transmute(&mut self.0[b]) };
    // The following should return a MaybeUninit<T>, which will not be dropped.
    unsafe { a.replace(b.replace(a.replace(MaybeUninit::uninit()))) };
}

Take the case of calling swap_columns with a=b. This leads to code equivalent to

pub fn swap_columns(&mut self, a: usize) {
    let a: *mut MaybeUninit<Vector<T, { N }>> = unsafe { mem::transmute(&mut self.0[a]) };
    unsafe { a.replace(a.replace(a.replace(MaybeUninit::uninit()))) };
}

Going through the replace calls one by one. I'll refer to the parameter/return value as tmp.

a = val; tmp = uninit
a = uninit; tmp = val // first call
a = val; tmp = uninit // second call
a = uninit; tmp = val // third call

Thus the function would conclude a being uninitialised memory.

aljabar fails to build on latest version of rustc

Aljabar fails to build with the following errors:

error: constant expression depends on a generic parameter
   --> src/vector.rs:173:30
    |
173 |     pub fn truncate(self) -> (TruncatedVector<T, { N }>, T) {
    |                              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |
    = note: this may fail depending on what value the parameter takes

error: constant expression depends on a generic parameter
   --> src/vector.rs:201:36
    |
201 |     pub fn extend(self, new: T) -> ExtendedVector<T, { N }> {
    |                                    ^^^^^^^^^^^^^^^^^^^^^^^^
    |
    = note: this may fail depending on what value the parameter takes

error: aborting due to 2 previous errors

It's not a huge concern, as some earlier versions of the compiler do support this just mine, but the decision to make these functions illegal have ramifications for their future existence in this crate.

My inclination is to wait a while, and maybe these functions will just end up being compilable.

A side pretty big issue is that now it's impossible to view the documentation on docs.rs for the time being.

Type-enforced row/column majorness?

Have you considered raising the row/column majorness of vectors and matrices to the type level? I was thinking about how aljabar hardcodes matrices as column-major, and was wondering about 0-overhead ways of supporting whichever the user chooses (so, not using an enum or flag discriminant at runtime).

I've put a sketch of what the type definitions might look like in the cunningly-named aljabr repo here.

The important bits are:

/// Marker for a row-major matrix.
pub struct RowM;
/// Marker for a column-major matrix.
pub struct ColM;
/// Marker for a row vector.
pub struct RowV;
/// Marker for a column vector.
pub struct ColV;

pub struct Vector<T: Copy, M, const N: usize> {
    _major: PhantomData<M>,
    elements: [T; N]
}

pub struct Matrix<T: Copy, M, const Major: usize, const Minor: usize> {
    _major: PhantomData<M>,
    elements: [[T; Minor]; Major]
}

In this example, Vector's M parameter would be either RowV or ColV and Matrix's M parameter would be either RowM or ColM.

I'm not convinced this is actually a good idea yet, but its seemed interesting so far.

add no_std compatibility

or declare that no_std compatibility is not a goal.

const generics enables us to use arrays as pseudo-allocations without actually using an allocator, it might be worth exploiting that.

if thats not a goal then i will probably write a lib myself, which is fine too.

Docs

Hey, I was passing by and I didn't see any examples. It would be pretty nice if you guys show what it can do so we can have an idea of it's capabilities without having to go town first. 🙂

What should be the `indexed_map` equivalent for `Matrix`?

indexed_map is a method @hovind generously added and finds useful, so my assumption is that users would find an equivalent method for Matrix useful as well. However, it is unclear whether or not we should just choose an ordering for the indices (i.e. (row, column) vs. (column, row)), or give users the option to choose.

Is a license of GPL3 too restrictive?

While I would urge reconsideration of any use of this library in production code, I am aware that a GPL3 license can be a bit too restrictive. If someone would prefer a different license I would be happy to switch to that