Crate vee

Expand description

$V_{EE}$ – Vector Expression Emitter: Geometric Algebra Code Generator

The goal of this crate is to generate optimized code for geometric algebra flavors. Currently, this crate implements the symbolic reduction of multivector expressions up to polynomials with rational coefficients. In contrast, rational polynomials and hence polynomial division is not required for lower dimensional geometric algebra flavors as the inverse of a multivector is given by multiplying it with the inverse of its mixed-grade norm, i.e., a Study number for dimensions $D < 6$.¹ See the examples below where the symbolic expressions are generated in text form. The next releases will implement code forms (e.g., Rust code in various profiles based on SIMD using lav with and without generics or arbitrary precision types using rug). Currently, the planed-based pistachio flavor – Projective Geometric Algebra (PGA) – is implemented for $D \equiv N + 1 \le 8$ in all three metrics, i.e., elliptic, hyperbolic, and parabolic (Euclidean).² The 5D, 6D, and 7D PGAs (i.e., $N = 5$, $N = 6$, and $N = 7$) are incomplete as there are no inverses based on Study numbers but they provide dimension-agnostic insights regarding duality and the choice of basis blades. The PGA is especially of interest for computer graphics, game engines, and physics simulations as it the most compact flavor (i.e., a one-up flavor) unifying the established but scattered frameworks, e.g., homogeneous coordinates, Plücker coordinates, (dual) quaternions, and screw theory. Even without any knowledge of geometric algebra, an API can be more intuitive as it unifies the positional and directional aspects of geometric entities (e.g., planes, lines, points) and the linear and angular aspects of rigid-body dynamics in a dimension-agnostic way with closed-form (i.e., non-iterative) solutions up to 4D (e.g., PgaP2, PgaP3, PgaP4).³

§Operators

Following table lists the common operators shared between flavors. The code for the first three will be manually written based on Study numbers whereas the code for the remaining ones will be automatically generated based on Multivector.

\gdef\e{
  \boldsymbol e
}
\gdef\I{
  \boldsymbol I
}
\gdef\norm{
  \| a \| \equiv \sqrt{a \tilde a}
}
\gdef\unit{
  \hat a \equiv \dfrac{a}{\| a \|}
}
\gdef\inv{
  a^{-1} \equiv \dfrac{\tilde a}{\| a \|^2}
}
\gdef\rev{
  \tilde a \equiv \sum_s (-1)^{s \choose 2} \lang a \rang_s
}
\gdef\pol{
  a^{\perp} \equiv a\I
}
\gdef\not{
  a^* \equiv \sum_s \lang a \rang_s^*
    : \lang a \rang_s^* = \sum_i \alpha_i a_i^*
      : a_i a_i^* = \I
}
\gdef\unnot{
  a_* \equiv a^{***} \therefore (a^*)_* = a^{****} = a
}
\gdef\neg{
  -a \equiv (-1)a
}
\gdef\add{
  a + b \equiv \sum_s \lang a \rang_s + \sum_t \lang b \rang_t
}
\gdef\sub{
  a - b \equiv \sum_s \lang a \rang_s - \sum_t \lang b \rang_t
}
\gdef\mul{
  ab \equiv \sum_{s,t} \lang a \rang_s \lang b \rang_t
}
\gdef\div{
  \dfrac{a}{b} \equiv ab^{-1}
}
\gdef\rem{
  a \times b \equiv \frac{1}{2}(ab - ba)
}
\gdef\bitor{
  a \mid b \equiv \sum_{s,t}
    \lang
      \lang a \rang_s
      \lang b \rang_t
    \rang_{\|s - t\|}
}
\gdef\bitxor{
  a \wedge b \equiv \sum_{s,t}
    \lang
      \lang a \rang_s
      \lang b \rang_t
    \rang_{s + t}
}
\gdef\bitand{
  a \vee b \equiv {(a^* \wedge b^*)}_*
}
\gdef\shl{
  a \looparrowleft b
    \equiv \sum_{s,t} (-1)^{st} \lang b \rang_t \lang a \rang_s \lang \tilde b \rang_t
}
\gdef\shr{
  a \curvearrowright b \equiv (a \mid b) \tilde b
}
\gdef\from{
  \lang a \rang_b \equiv \sum_{s \in \{t|b = \sum_t \lang b \rang_t\}} \lang a \rang_s
}

Operator	Name	Formula
`a.norm()`	Norm (mixed grade)	$`\norm`$
`a.unit()`	Unit (orthonormal)	$`\unit`$
`a.inv()`	Inverse	$`\inv`$
`a.rev()`	Reverse	$`\rev`$
`a.pol()`	Polarity	$`\pol`$
`!a`	Dual (right complement)	$`\not`$
`!!!a`	Undual (left complement)	$`\unnot`$
`-a`	Negation (orientation)	$`\neg`$
`B::from(a)`	Selection (mixed grade)	$`\from`$
`a + b`, `a += b`	Sum	$`\add`$
`a - b`, `a -= b`	Difference	$`\sub`$
`a * b`, `a *= b`	Product (geometric)	$`\mul`$
`a / b`, `a /= b`	Quotient (geometric)	$`\div`$
`a << b`, `a <<= b`	Reflection ($`a`$ by $`b`$)	$`\shl`$
`a >> b`, `a >>= b`	Projection ($`a`$ onto $`b`$)	$`\shr`$
`a % b`	Commutator	$`\rem`$
`a \| b`	Contraction (symmetric)	$`\bitor`$
`a ^ b`	Meet (progressive)	$`\bitxor`$
`a & b`	Join (regressive)	$`\bitand`$

§Examples

Generates the expression for rotating a plane in PgaP3, i.e., Parabolic (Euclidean) 3D PGA. The Multivector::pin() method pins symbols of Multivector::plane() with the combining x below (i.e., the Unicode combining diacritical mark "◌͓") to distinguish them from the symbols of Multivector::rotator().

use vee::{format_eq, PgaP3 as Vee};

format_eq!(Vee::plane().pin() << Vee::rotator(), [
    "+(+[+1vv+1xx+1yy+1zz]W͓)e0",
    "+(+[+2vz+2xy]y͓+[-2vy+2xz]z͓+[+1vv+1xx-1yy-1zz]x͓)e1",
    "+(+[+2vx+2yz]z͓+[-2vz+2xy]x͓+[+1vv-1xx+1yy-1zz]y͓)e2",
    "+(+[+2vy+2xz]x͓+[-2vx+2yz]y͓+[+1vv-1xx-1yy+1zz]z͓)e3",
]);

The symbols are assigned to basis blades such that lowercase symbols are dual to their corresponding uppercase symbols. For blades containing $\e_0$, uppercase symbols are used. The Multivector::swp() method swaps lowercase and uppercase symbols. This is useful for testing duality equivalences.

use vee::{format_eq, PgaP3 as Vee};

format_eq!(Vee::plane(), "We0+xe1+ye2+ze3");
format_eq!(Vee::point(), "we123+Xe032+Ye013+Ze021");

assert_ne!(!Vee::plane(), Vee::point());
assert_eq!(!Vee::plane(), Vee::point().swp());

S. De Keninck and M. Roelfs, “Normalization, square roots, and the exponential and logarithmic maps in geometric algebras of less than 6D”, Mathematical Methods in the Applied Sciences 47, 1425–1441. ↩
M. Roelfs and S. De Keninck, “Graded Symmetry Groups: Plane and Simple”, Advances in Applied Clifford Algebras 33. ↩
L. Dorst and S. De Keninck, “Physical Geometry by Plane-Based Geometric Algebra”, Advanced Computational Applications of Geometric Algebra, 43–76. ↩

Modules§

pga: Planed-Based Pistachio Flavor – Projective Geometric Algebra (PGA)

Structs§

Monomial: Uniquely reduced form of a symbolic monomial expression.
Multivector: Uniquely reduced form of a symbolic multivector expression.
Polynomial: Uniquely reduced form of a symbolic polynomial expression.

Traits§

Algebra: A geometric algebra defined by a flavor’s basis (i.e., all its basis blades).

Type Aliases§

PgaE0: Multivector for Elliptic 0D PGA.
PgaE1: Multivector for Elliptic 1D PGA.
PgaE2: Multivector for Elliptic 2D PGA.
PgaE3: Multivector for Elliptic 3D PGA.
PgaE4: Multivector for Elliptic 4D PGA (experimental).
PgaE5: Multivector for Elliptic 5D PGA (experimental, no inverse).
PgaE6: Multivector for Elliptic 6D PGA (experimental, no inverse).
PgaE7: Multivector for Elliptic 7D PGA (experimental, no inverse).
PgaH0: Multivector for Hyperbolic 0D PGA.
PgaH1: Multivector for Hyperbolic 1D PGA.
PgaH2: Multivector for Hyperbolic 2D PGA.
PgaH3: Multivector for Hyperbolic 3D PGA.
PgaH4: Multivector for Hyperbolic 4D PGA (experimental).
PgaH5: Multivector for Hyperbolic 5D PGA (experimental, no inverse).
PgaH6: Multivector for Hyperbolic 6D PGA (experimental, no inverse).
PgaH7: Multivector for Hyperbolic 7D PGA (experimental, no inverse).
PgaP0: Multivector for Parabolic (Euclidean) 0D PGA.
PgaP1: Multivector for Parabolic (Euclidean) 1D PGA.
PgaP2: Multivector for Parabolic (Euclidean) 2D PGA.
PgaP3: Multivector for Parabolic (Euclidean) 3D PGA.
PgaP4: Multivector for Parabolic (Euclidean) 4D PGA (experimental).
PgaP5: Multivector for Parabolic (Euclidean) 5D PGA (experimental, no inverse).
PgaP6: Multivector for Parabolic (Euclidean) 6D PGA (experimental, no inverse).
PgaP7: Multivector for Parabolic (Euclidean) 7D PGA (experimental, no inverse).

Crate vee

Crate vee Copy item path

§Operators

§Examples

Modules§

Structs§

Traits§

Type Aliases§

Crate vee