### 1 unstable release

0.1.0 | Jan 24, 2022 |
---|

#**1248** in Math

**Apache-2.0**

390KB

7K
SLoC

A robust and generalized library for Geometric Algebra in Rust.

# What is Geometric Algebra?

Geometric algebra is an extension of linear algebra where vectors are extended
with a multiplication operation called the *geometric product*, which
produces new kinds of operations and vector-like objects that are useful in
simplifying and generalizing a number of tricky systems in math and physics.

For instance:

- In physics, using "bivectors" geometric algebra provides a consistent and
clean way of representing angular velocities in
*any*dimension, which normally isn't possible in the standard system of angles and vectors. - Geometric algebra unifies the rotational actions of Complex numbers and Quaternions into a single object called a Rotor that works in all dimensions.
- Using "unit blades", geometric algebra gives a compact and efficient way to represent vector and affine spaces that's easier to work with than sets of basis vectors.

For more information and an in depth explanation, I *highly* recommend
*Geometric Algebra for Computer Science* by Leo Durst, Daniel Frontijne, and
Stephann Mann. A lot of inspiration for this library comes from that book, and
the concepts are explained in a way that's easy to follow and visual without
falling *too* deep into overly abstract math.

# Usage

This crate is split up into a number of modules each representing a different interpretation of the underlying algebra:

contains the most raw form of Geometric algebra defined purely algebraically. This is primarily used as the core all the other systems are built upon, but it is useful as well for various physical quantities (like position and angular velocity) and abstract mathematical objects`algebra`

interprets the structs in`subspace`

as weighted vector spaces and orthogonal transformation (like rotations and reflections) in ℝ`algebra`^{n}

(planned) interprets the structs in`homogenous`

as affine spaces and their operations in ℝ`algebra`^{n-1}using homogeneous coordinates

Additionally, the module

contains the core components common
to all subsystems.`wedged ::`base

## Nomenclature and Conventions

Naming in geometric algebra can vary slightly across authors, so the particular conventions have been chosen:

- in

, a`wedged`

refers to an object constructed from the wedge product of vectors whereas a`SimpleBlade`

refers to`Blade`*any*object of a particular grade - a

is used exclusively for objects with unit norm that encode rotations whereas`Rotor`

is used for a general object from the even subalgebra`Even`

s refer to a general element in the algebra`Multivector`- The operators

/`*`

,`Mul`

/`^`

, and`BitXor`

/`%`

are used for the geometric, wedge, and generalized dot products respectively`Rem`

Additionally, most structs in this crate support indexing where each component
is ordered according to a particular basis convention chosen for this crate.
See the docs on

For more information.`BasisBlade`

## Generic programming

In order to generalize code for different scalar types and dimensions,

makes heavy use of generics. The system is based upon the
system in `wedged`

, and, to increase interoperability, reuses a lot of its
components.`nalgebra`

The system is designed such that a number of different levels of abstraction are possible:

### No Generics

`
``use` `wedged``::``algebra``::``*``;`
`let` v1 `=` `Vec3``::`new`(``1.``0``,` `0.``0``,` `0.``0``)``;`
`let` v2 `=` `Vec3``::`new`(``0.``0``,` `1.``0``,` `0.``0``)``;`
`let` plane `=` v1 `^` v2`;`
`let` cross `=` plane`.``dual``(``)``;`
`assert_eq!``(`plane`,` `BiVec3``::`new`(``0.``0``,``0.``0``,``1.``0``)``)``;`
`assert_eq!``(`cross`,` `Vec3``::`new`(``0.``0``,``0.``0``,``1.``0``)``)``;`

When not using generics, things act much like you would expect from a vector library.

### Generic Scalar

`
``use` `wedged``::``algebra``::``*``;`
`use` `wedged``::``base``::``ops``::``*``;`
`fn` `midpoint``<`T`:``Clone``+`ClosedAdd`+`ClosedDiv`+`One`>``(``v1``:``Vec3``<`T`>`, `v2``:``Vec3``<`T`>``)`` ``->` `Vec3``<`T`>` `{`
`let` two `=` `T``::`one`(``)` `+` `T``::`one`(``)``;`
`(`v1 `+` v2`)` `/` two
`}`
`fn` `cross``<`T`:`RefRing`>``(``v1``:``Vec3``<`T`>`, `v2``:``Vec3``<`T`>``)`` ``->` `Vec3``<`T`>` `{`
`(`v1 `^` v2`)``.``dual``(``)`
`}`
`let` v1 `=` `Vec3``::`new`(``1.``0``,` `0.``0``,` `0.``0``)``;`
`let` v2 `=` `Vec3``::`new`(``0.``0``,` `1.``0``,` `0.``0``)``;`
`assert_eq!``(``cross``(`v1`,`v2`)``,` `Vec3``::`new`(``0.``0``,``0.``0``,``1.``0``)``)``;`
`assert_eq!``(``midpoint``(`v1`,`v2`)``,` `Vec3``::`new`(``0.``5``,``0.``5``,``0.``0``)``)``;`
`let` v1 `=` `Vec3``::`new`(``1.``0``f32``,` `0.``0``,` `0.``0``)``;`
`let` v2 `=` `Vec3``::`new`(``0.``0``f32``,` `1.``0``,` `0.``0``)``;`
`assert_eq!``(``cross``(`v1`,`v2`)``,` `Vec3``::`new`(``0.``0``f32``,``0.``0``,``1.``0``)``)``;`
`assert_eq!``(``midpoint``(`v1`,`v2`)``,` `Vec3``::`new`(``0.``5``f32``,``0.``5``,``0.``0``)``)``;`

For generic scalars,

structs implement traits and functions based on
what their scalars implement. For instance:`wedged`

- Structural traits like

,`Index`

, and`AsRef``<``[`T`]``>`

are always implemented`Borrow``<``[`T`]``>` - Basic traits like

,`Clone`

traits,`fmt`

,`PartialEq`

,`Eq`

, and`Hash`

are all implemented if the scalar implements them`Default`

is implemented if the scalar is`Copy`

the struct isn't a`Copy`

dimension`Dynamic`- Additive operations like

,`Add`

, and`Sub`

as well as scalar operations like`Neg`

and`Mul`

. are implemented if the scalar has them. The assign variants and operations between references are implemented as well if the scalars implement them.`Div` - Traits for the geometric (

), wedge (`Mul`

), and dot (`BitXor`

) products are implemented if the scalar has addition, subtraction, negation, zero and multiplication between references`Rem` - anything involving a norm, constructing a rotation, etc, requires
`nalgebra`real_field`::` `Div`*usually*has the same requirements as

, but is only implemented on a few specific structs (like`Mul`

and`Rotor`

)`Versor`

In order to make managing these requirements easier, a number of trait aliases
are included in

that combine common groupings of operations
together`wedged ::`

`base`ops

`::`### Generic Dimension

`
``use` `wedged``::``base``::``*``;`
`use` `wedged``::``algebra``::``*``;`
`fn` `point_velocity``<`T,N`:`Dim`>``(``p``:``VecN``<`T,N`>`, `angular_vel``:` `BiVecN``<`T,N`>``)`` ``->` `VecN``<`T,N`>` `where`
T`:``AllocBlade``<`N,U1`>`+`AllocBlade``<`N,U2`>`+RefRing
`{`
p `%` angular_vel
`}`
`let` p `=` `Vec2``::`new`(``2.``0``,``0.``0``)``;`
`let` av `=` `BiVec2``::`new`(``3.``0``)``;`
`assert_eq!``(``point_velocity``(`p`,` av`)``,` `Vec2``::`new`(``0.``0``,``6.``0``)``)``;`
`let` p `=` `Vec3``::`new`(``0.``0``,``2.``0``,``0.``0``)``;`
`let` av `=` `BiVec3``::`new`(``3.``0``,``0.``0``,``0.``0``)``;`
`assert_eq!``(``point_velocity``(`p`,` av`)``,` `Vec3``::`new`(``0.``0``,``0.``0``,``6.``0``)``)``;`

For a generic dimension, for every

struct
used in the function or trait, the scalar must have the corresponding `wedged`

trait bound for that struct. These are all included in `Alloc *`

`wedged``::``base``::`alloc

,
and there is one for each subset of the geometric algebra.For example, for a scalar

and dimension `T`

, using a `N`

requires `VecN`

bound, using an `T :AllocBlade<N,U1>`

`Even`

needs a `T``:``AllocEven``<`N`>`

bound, etc.Finally, even if a non-generic scalar is used, these are still required inside a where clause on the function or trait.

### Generic Dimension and Grade

`
``use` `wedged``::``base``::``*``;`
`use` `wedged``::``algebra``::``*``;`
`fn` `project``<`T,N`:`Dim,G`:`Dim`>``(``v``:``VecN``<`T,N`>`, `b``:``Blade``<`T,N,G`>``)`` ``->` `VecN``<`T,N`>` `where`
U1`:` `DimSymSub``<`G`>`,
`DimSymDiff``<`U1,G`>``:` `DimSymSub``<`G,Output=U1`>`,
T`:``AllocBlade``<`N,U1`>` + `AllocBlade``<`N,G`>` + `AllocBlade``<`N,DimSymDiff`<`U1,G`>``>` + RefDivRing
`{`
`let` l `=` b`.``norm_sqrd``(``)``;`
`(`v `%` `&`b`)` `%` b`.``reverse``(``)``/`l
`}`
`let` v `=` `Vec3``::`new`(``1.``0``,` `2.``0``,` `0.``0``)``;`
`let` line `=` `Vec3``::`new`(``0.``0``,` `1.``0``,` `0.``0``)``;`
`let` plane `=` `BiVec3``::`new`(``0.``0``,` `1.``0``,` `0.``0``)``;`
`assert_eq!``(``project``(`v`,`line`)``,` `Vec3``::`new`(``0.``0``,` `2.``0``,` `0.``0``)``)``;`
`assert_eq!``(``project``(`v`,`plane`)``,` `Vec3``::`new`(``1.``0``,` `0.``0``,` `0.``0``)``)``;`

Using a generic grade follows nearly the same rules as for generic dimensions but with an added generic for the grade. However, with grade altering operations like the wedge or dot products are used, additional bounds are required to allow the compiler to add or subtract the grades of the two blades.

For instance:

- The wedge

product requires`^``G1``:``DimAdd``<`G2`>` - The dot

product requires`%``G1``:``DimSymSub``<`G2`>`

#### Dependencies

~4MB

~91K SLoC