ts-geometric-algebra

Ts-geometric-algebra is a Clifford Algebra Generator for TypeScript and JavaScript. It generates Geometric Algebras of any signature and is mostly combatible with Ganja.js. There is no operator overloading or inline functions yet due to lack of support in TypeScript.

(Mathematically, an algebra generated by ts-geometric-algebra is a graded exterior (Grassmann) algebra with a non-metric outer product, extended (Clifford) with geometric and contraction inner products, a Poincare duality operator and the main involutions and morphisms.)

(Technically, ts-geometric-algebra is a code generator producing classes that reificate algebraic literals.)

(Practically, ts-geometric-algebra enables algebraic operations over reals, complex numbers, dual numbers, hyperbolic numbers, vectors, spacetime events, quaternions, dual quaternions, biquaternions or any other Clifford Algebra with full type support from TypeScript.)

Discourse and Discord

Visit bivector.net for our forum and chat - the perfect place for questions and support.

Using ts-geometric-algebra for the first time

Install ts-geometric-algebra using npm :

1npm install ts-geometric-algebra

And require it in your script :

1const Algebra = require('ts-geometric-algebra').default;

The Algebra Function

To create an Algebra, call the Algebra function specifying the metric signature (number of positive, negative and zero dimensions). The result is an ES6 class implementing the requested clifford algebra.

1function Algebra( p, q, r );
2  // p    = number of positive dimensions.
3  // q    = optional number of negative dimensions.
4  // r    = optional number of zero dimensions.

An extended syntax is also available that allows you to further tweak the created Algebra.

1function Algebra( p, q, r, {baseType, metric, mulTable, disableUnroll} )
2  // p        = number of positive dimensions.
3  // q        = optional number of negative dimensions.
4  // r        = optional number of zero dimensions.
5  // baseType = Float32Array or similar
6  // metric   = basis vector inner products in custom order, must agree with p, q and r
7  // mulTable = Custom signs for the Caley table
8  // disableUnroll = (boolean) prevent loop unrolling of performance critical methods
9

Here are some examples :

1// Basic
2const Hyper   = Algebra(1);         // Hyperbolic numbers.
3const Complex = Algebra(0, 1);      // Complex numbers.
4const Dual    = Algebra(0, 0, 1);   // Dual numbers.
5const H       = Algebra(0, 2);      // Quaternions.
6
7// Clifford
8const Cl2 = Algebra(2);             // Clifford algebra for 2D vector space.
9const Cl3 = Algebra(3);             // Clifford algebra for 3D vector space.
10const TimeSpace = Algebra(1, 3);    // Clifford algebra for timespace vectors.
11
12// Geometric
13const PGA2D = Algebra(2, 0, 1);     // Projective Euclidean 2D plane. (dual)
14const PGA3D = Algebra(3, 0, 1);     // Projective Euclidean 3D space. (dual)
15const CGA2D = Algebra(3, 1);        // Conformal 2D space.
16const CGA3D = Algebra(4, 1);        // Conformal 3D space.
17
18// High-Dimensional GA
19const DCGA3D = Algebra(6, 2);       // Double Conformal 3D Space.
20const TCGA3D = Algebra(9, 3);       // Triple Conformal 3D Space.
21const DCGSTA = Algebra(4, 8);       // Double Conformal Geometric Space Time Algebra.
22const QCGA   = Algebra(9, 6);       // Quadric Conformal Geometric Algebra.

You can now use these classes to generate algebraic elements. Those elements will have all of the expected properties. (norm, blade access, dot, wedge, mul, dual, inverse, etc ...)

Unlike Ganja.js you must use them in a 'classic' programming style syntax like the example below.

1const Complex = Algebra(0, 1);       // Complex numbers.
2const a = Complex.fromGanja([3, 2]); // 3 + 2i
3const b = Complex.fromGanja([1, 4]); // 1 + 4i
4return a.mul(b);                     // returns [-5, 14]

Altough not as pretty or fun as Ganja.js you have the full advantage of types and autocompletion.

Methods

Object oriented	Ganja Equivalent	Explanation
x.equals(y)	N/A	Strict equality
x.closeTo(y, tol?)	N/A	Equality within given tolerance
x.hasNaN()	N/A	Check for Not-a-Numbers
x.hasInfinity()	N/A	Check for (negative) infinity
x.isNil(tol?)	N/A	Equal or close to zero
x.isGrade(g, tol?)	N/A	Only has components of grade g
x.s	x.s	Scalar part (get/set)
x.ps	N/A	Pseudoscalar part (get/set)
x.getAt(...idx)	N/A	Metric-aware coefficient of the product of basis factors defined by idx
x.setAt(...idx, a)	N/A	Set coefficient of product of basis factors idx as a
x.norm()	x.Length	Conjugate norm (metric-aware)
x.vnorm()	x.VLength	Vector norm (ignores metric) {x.length is array length}
x.taxicabNorm()	N/A	L1 norm (ignores metric)
x.maxNorm()	N/A	Linfinity norm (ignores metric)
x.neg()	N/A	Negation (additive inverse)
x.cwAbs()	N/A	Component-wise absolute value
x.involute()	x.Involute	Negation of basis factors
x.rev()	x.Reverse	Reversal of basis factors {x.reverse is array reversal}
x.conjugate()	x.Conjugate	Conjugation (combined involution and reversal)
x.adjugate()	N/A	Unscaled multiplicative inverse (suitable for int base class)
x.inverse()	x.Inverse	Multiplicative inverse
x.square()	x.Mul(x)	Multiplicative squaring (**)
x.normalize(a?)	x.Normalize	x with norm set to a (default 1)
x.rotorNormalize()	N/A	Normalize rotor x
x.sqrt()	N/A	Square root. Currently reliable only in dimensions < 2
x.rotorSqrt()	N/A	Rotor square root. Available in certain metrics.
x.exp()	x.Exp	Exponential function
x.bivectorExp()	x.Exp	Bivector exponential function (optimized)
x.log()	x.Log	(Motor) Logarithm. Generic exp inverse available only in dimensions < 2
x.rotorLog()	x.Log	Rotor Logarithm
x.clone()	x.Scale(1)	Independent copy
x.dual()	x.Dual (*)	Metric independent dual: x.mul(x.dual()) = Cl.pseudoscalar()
x.undual()	N/A	Inverse of x.dual()
x.scale(a)	x.Scale(a)	Scalar multiplication
x.pow(n)	x.Pow(n)	Multiply x with itself n times
x.applyWeights(ws)	N/A	Replace each basis factor with a weighted copy for every weight in ws
x.negateGrades(...gs)	x.Map(...gs)	Negate the given grades
x.add(y)	x.Add(y)	Component-wise addition (**)
x.sub(y)	x.Sub(y)	Component-wise subtraction (**)
x.mul(y)	x.Mul(y)	Geometric product of x and y (**)
x.lmul(y)	y.Mul(x)	Geometric product from the left (**)
x.div(y)	x.Div(y)	Geometric division from the right
x.ldiv(y)	y.Inverse.Mul(x)	Left inverse product
x.ldivs(y)	x.Inverse.Mul(y)	Geometric division from the left
x.wedge(y)	x.Wedge(y)	Wedge (outer) product. Metric independent (**)
x.lwedge(y)	y.Wedge(x)	Wedge product from the left (**)
x.vee(y)	x.Vee(y)	Vee (dual) product. Metric indepentend. x.vee(y) = y.dual().wedge(x.dual()).undual() (**)
x.lvee(y)	y.Vee(x)	Vee product from the left (**)
x.rotorMean(y)	N/A	Geometric mean of rotors x and y
x.contract(y, ctn)	N/A	Contract x by y using criterion ctn
x.dot(y)	x.Dot(y)	Dot product. Symmetric criterion (**)
x.dotL(y)	x.LDot(y)	Left contraction of x by y (**)
x.ldotL(y)	y.LDot(x)	Left contraction of y by x (**)
x.dotR(y)	N/A	Right contraction of x by y
x.ldotR(y)	N/A	Right contraction of y by x
x.dotS(y)	N/A	Scalar product. Nil criterion
x.imag()	N/A	Filter out grade 0
x.even()	x.Even()	Filter out odd grades
x.grade(n)	x.Grade(n)	Keep only grade n components
x.vector()	x.Vector	Array of vector components
x.vector(n)	N/A	Array of n-vector components
x.rotor()	N/A	Array of components of even grade
x.ganja()	x	Array of all components in lexicographic order
x.invScale(y, t?)	N/A	Ratio of weights between coincident x and y. Returs NaN if non-coincidence exteeds threshold t.
x.grades(t?)	N/A	Array of grades present in x exceeding threshold t (default 0)
x.meetJoin(y, t?)	N/A	True (of threshold t) meet and join of blades x and y
x.star(y)	N/A	Scalar product with number result
Cl.zero()	Cl.Scalar(0)	Zero element
Cl.scalar(a?)	Cl.Scalar(a)	Scalar element of size a (default 1)
Cl.pseudoscalar(a?)	N/A	Pseudoscalar element of size a (default 1)
Cl.basisBlade(...idx)	N/A	Unit basis blade given by the product of the given basis factors
Cl.fromVector(vs)	Cl.Vector(...vs)	Vector element with given components (from an array)
Cl.fromVector(vs, 2)	Cl.Bivector(...vs)	Bivector element with given components (lexicographic order)
Cl.fromVector(vs, 3)	Cl.Trivector(...vs)	Trivector element with given components
Cl.fromVector(vs, g)	Cl.nVector(g, ...vs)	g-vector element with given components
Cl.fromRotor(vs)	N/A	Even grade element with given components
Cl.fromGanja(vs)	new Cl(vs)	New element with components given in lexicographic order
Cl.dimensions	-->	Math.log(Cl.describe().basis.length)/Math.LN2 number of dimensions
Cl.size	-->	Cl.describe().basis.length algebra size
Cl.metric	-->	Cl.describe().metric.slice(1, n+1) basis vector metric
Cl.mulTable	-->	Similar to Cl.describe().mulTable but signs only
new Cl(vs)	N/A	Not recommended, use fromGanja instead. New element with components given in bit field order

(*) Only in degenerate metrics (**) Loop unrolled for maximum performance

Dual Zoo

Object oriented	Function Oriented	Ganja Equivalent	Explanation
x.podge()	podge(x)	x.Mul(ps)	Right-multiplication by Cl.pseudoscalar()
x.unpodge()	unpodge(x)	x.Div(ps)	Right-division by Cl.pseudoscalar()
x.podgeL()	podgeL(x)	ps.Mul(x)	Left-multiplication by Cl.pseudoscalar()
x.unpodgeL()	unpodgeL(x)	ps.Inverse.Mul(x)	Left-division by Cl.pseudoscalar()
x.star()	star(x)	N/A	Non-degenerate x.podge()
x.unstar()	unstar(x)	N/A	Inverse of x.star()
x.starL(x)	starL(x)	x.Dual (*)	Non-degenerate x.podgeL()
x.unstarL(x)	unstarL(x)	N/A	Inverse of x.starL()
x.hodge()	hodge(x)	N/A	Hodge dual
x.unhodge()	unhodge(x)	N/A	Inverse of x.hodge()
x.hodgeL()	hodgeL(x)	N/A	Left Hodge dual
x.unhodgeL()	unhodgeL(x)	N/A	Inverse of x.hodgeL()

(*) Only in non-degenerate metrics

Rotor operation availability

Metric (pqr)	Available operations
p+q+r <= 2	(all)
400	rotorSqrt, rotorNormalize
310	rotorSqrt, rotorNormalize
301	rotorLog, rotorSqrt, rotorNormalize
410	rotorSqrt, rotorNormalize

Functions

Function Oriented	Ganja Equivalent	Explanation
equals(x, y)	N/A	Strict equality
closeTo(x, y, tol?)	N/A	Equality within given tolerance
hasNaN(x)	N/A	Check for Not-a-Numbers
hasInfinity(x)	N/A	Check for (negative) infinity
isNil(x, tol?)	N/A	Equal or close to zero
isGrade(x, g, tol?)	N/A	Only has components of grade g
norm(x)	x.Length	Conjugate norm (metric-aware)
vnorm(x)	x.VLength	Vector norm (ignores metric) {x.length is array length}
taxicabNorm(x)	N/A	L1 norm (ignores metric)
maxNorm(x)	N/A	Linfinity norm (ignores metric)
neg(x)	N/A	Negation (additive inverse)
cwAbs(x)	N/A	Component-wise absolute value
involute(x)	x.Involute	Negation of basis factors
rev(x)	x.Reverse	Reversal of basis factors {x.reverse is array reversal}
conjugate(x)	x.Conjugate	Conjugation (combined involution and reversal)
adjugate(x)	x.Inverse	Unscaled multiplicative inverse
inverse(x)	x.Inverse	Multiplicative inverse
square(x)	x.Mul(x)	Multiplicative squaring (**)
normalize(x, a?)	x.Normalize	x with norm set to a (default 1)
rotorNormalize(x)	N/A	Normalize rotor x
sqrt(x)	N/A	Square root. Currently reliable only in dimensions < 2
rotorSqrt(x)	N/A	Rotor square root. Available in certain metrics.
exp(x)	x.Exp	Exponential function
bivectorExp(x)	x.Exp	Bivector exponential function (optimized)
log(x)	x.Log	(Motor) Logarithm. Generic exp inverse available only in dimensions < 2
rotorLog(x)	x.Log	Rotor Logarithm
clone(x)	x.Scale(1)	Independent copy
dual(x)	x.Dual (*)	Metric independent dual: x.mul(x.dual()) = Cl.pseudoscalar()
undual(x)	N/A	Inverse of x.dual()
scale(x, a)	x.Scale(a)	Scalar multiplication
pow(x, n)	x.Pow(n)	Multiply x with itself n times
applyWeights(x, ws)	N/A	Replace each basis factor with a weighted copy for every weight in ws
negateGrades(x, ...gs)	x.Map(...gs)	Negate the given grades
add(...args)	x.Add(y)	Component-wise addition (**)
sub(x, y)	x.Sub(y)	Component-wise subtraction (**)
mul(...args)	x.Mul(y)	Geometric product of x and y (**)
div(x, y)	x.Div(y)	Geometric division from the right
ldivs(x, y)	x.Inverse.Mul(y)	Geometric division from the left
wedge(...args)	x.Wedge(y)	Wedge (outer) product. Metric independent (**)
vee(...args)	x.Vee(y)	Vee (dual) product. Metric indepentend. vee(x, y) = undual(dual(y), dual(x)) (**)
rotorMean(x, y)	N/A	Geometric mean of rotors x and y
contract(x, y, ctn)	N/A	Contract x by y using criterion ctn
dot(x, y)	x.Dot(y)	Dot product. Symmetric criterion (**)
dotL(x, y)	x.LDot(y)	Left contraction of x by y (**)
dotR(x, y)	N/A	Right contraction of x by y
dotS(x, y)	N/A	Scalar product. Nil criterion
imag(x)	N/A	Filter out grade 0
even(x)	x.Even()	Filter out odd grades
grade(x, n)	x.Grade(n)	Keep only grade n components
invScale(x, y, t?)	N/A	Ratio of weights between coincident x and y. Returs NaN if non-coincidence exteeds threshold t.
grades(x, t?)	N/A	Array of grades present in x exceeding threshold t (default 0)
meetJoin(x, y, t?)	N/A	True (of threshold t) meet and join of blades x and y
star(x, y)	N/A	Scalar product with number result

(*) Only in degenerate metrics (**) Loop unrolled for maximum performance

The functions equals, closeTo, add, sub, mul, div, ldivs, wedge, vee also work on the number type.

Linear equation solver

You can solver equations of the form (for the moment pretending that javascript has scalar multiplication of arrays)

x = coeffs[0] * basis[0] + coeffs[1] * basis[1] + ... + coeffs[n-1] * basis[n-1]

for the unknown coefficients coeffs.

1const coeffs = vLinSolve(x, basis);

This comes with the added cost of algebra creation on each call. If you need to do a lot of solving create your algebra beforehand.

1import {Algebra, linSolve} from 'ts-geometric-algebra';
2const Grassmann = Algebra(0, 0, 3);
3const x = Grassmann.fromVector([1, 2, 3]);
4const basis = [
5  Grassmann.fromVector([1, 1, 1]),
6  Grassmann.fromVector([0, 1, -1]),
7  Grassmann.fromVector([-1, 2, -2])
8];
9const coeffs = linSolve(x, basis);  // [ 2.5, -3.5, 1.5 ]

Octonions

While all generated geometric algebras are associative it's possible to produce non-associative algebras using custom multiplication tables. This package comes with a pre-configured table for Octonions and monkey-patches conjugate, inverse, sqrt, exp and log to work correctly.

1import {makeOctonion} from 'ts-geometric-algebra';
2const O = makeOctonion();
3const e1 = Octonion.basisBlade(0);
4const e2 = Octonion.basisBlade(1);
5const e4 = Octonion.basisBlade(2);
6
7e1.mul(e2).mul(e4)  // [0, 0, 0, 0, 0, 0, +1]
8e1.mul(e2.mul(e4))  // [0, 0, 0, 0, 0, 0, -1]