From 5a56d0b97eed274ea4eae38ad4fd62a9b2395103 Mon Sep 17 00:00:00 2001 From: Brandon Flores Date: Tue, 27 Feb 2024 12:58:35 -0600 Subject: [PATCH] Huge update to README --- README.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 88 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 30a5233..eded0fc 100644 --- a/README.md +++ b/README.md @@ -9,13 +9,95 @@ A simple, fully static multivector implementation for Julia. While not the most allows for fast prototyping and implementation of geometric algebras and multivectors of arbitrary dimension or metric signature. -Currently, the package exports the `CliffordNumber{Cl,T}` type, which represents an element of the -Clifford algebra `Cl` with elements of type `T`, which have `L` elements. Future releases will -include more storage-efficient data structures for common, sparser elements such as k-vectors and -blades. +# Clifford numbers -Currently supported operations are addition (`+`), subtraction and negation (`-`), the geometric -product (`*`), and the Hodge star (`⋆`). +## Types + +This package exports `AbstractCliffordNumber{Q,T}` and its subtypes, which describe the behavior of +multivectors with quadratic form `Q` and scalar type `T<:Union{Real,Complex}`. This is a subtype of +`Number`, and therefore acts as a scalar. + +`AbstractCliffordNumber{Q,T}` includes the following concrete subtypes: + * `CliffordNumber{Q,T,L}`, which represents the coefficients associated with all basis blades. + * `EvenCliffordNumber{Q,T,L}` and `OddCliffordNumber{Q,T,L}`, which represents multivectors with +only basis blades of even or odd grade being nonzero. These are especially important when dealing +with physically realizable Euclidean transformations (rotations and translations). + * `KVector{K,Q,T,L}`, which represents multivectors with only basis blades of grade `K` being +zero. This is especially useful for representing common vectors and bivectors. + +## Promotion + +The type promotion system is heavily leveraged to minimize the memory footprint needed to represent +the results of various operations. Promotion can convert the numeric types associated with two +`AbstractCliffordNumber{Q}` instances (for instance, the sum of `KVector{1,APS,Int}` and +`KVector{1,APS,Float64}` is `KVector{1,APS,Float64}`), but it can also leverage grade information to +promote to smaller types: the sum of `KVector{1,APS,Int}` and `KVector{3,APS,Int}` is an +`OddCliffordNumber{APS,Int}`, but the sum of `KVector{1,APS,Int}` and `KVector{2,APS,Int}` are +`CliffordNumber{APS,Int}`. + +## Indexing + +Although `AbstractCliffordNumber` instances are scalars, the `BitIndex{Q}` type can be used to +retrieve coefficients associated with specific basis blades. The full set of `BitIndex{Q}` types for +some `x::AbstractCliffordNumber` can be generated with `BitIndices(x)`, and this is a binary ordered +vector of `BitIndex{Q}` objects. + +Mathematical operations are defined generically by working with the `BitIndex{Q}` objects associated +with an `AbstractCliffordNumber{Q,T}`. Elementwise operations on each element of a `BitIndices` +instance returns a `TransformedBitIndices`, a wrapper which lazily associates a function + +## Operations + +The following mathematical operations are supported by this package: + * Addition (`+`), subtraction and negation (`-`) + * The geometric product (`*`) + * Left (`/`) and right (`\`) division, including rational division (`//`) + * The reverse (`~`), grade involution, and Clifford conjugation + * The modulus and absolute value (with `abs2` and `abs`) + * The wedge product (`∧`) + * The left (`⨼`) and right (`⨽`) contractions + * The dot product and the Hestenes dot product + * The commutator product (`×`) + * Exponentiation + +Some of the names or implementations of various operations may change in the near future. + +Note that `AbstractCliffordNumber{Q,T}` is a scalar type, so dotted operators do not apply any +operations to each coefficient individually. However, they can be used to perform elementwise +operations on collections of Clifford numbers. + +# Features to be added or improved + +## Type system + + * A `StaticMultivector{Q,T,L}` type, allowing for non-static implementations. + * `numeric_type` will likely be renamed to `scalartype`. + +## Relationships between Clifford algebras + + * Determining the even subalgebra associated with some Clifford algebra. + * Converting even multivectors of an algebra to multivectors in the even subalgebra. + +## Metric signatures + * A better API for metric signatures. The `QuadraticForm{P,Q,R}` type is limited in that the +positive-squaring, negative-squaring, and zero-squaring basis blades are listed in that specific +order. + +## Mathematical operations + + * The implementation of the reverse operation: should we overload `Base.reverse`, `Base.conj`, +or do something else? What about other grade automorphisms? + * Better numerical accuracy and stability for some operations. In particular, properly leveraging +`sinpi`, `cospi`, `hypot`, and other methods with better numerical accuracy and stability +internally. + +## Interoperability + + * How do we handle the dot product of this package and the dot product of the `LinearAlgebra` +standard library? This package has no dependencies, but the semantics should be compatible as much +as possible. + * Secondarily, `StaticArrays.similar_type` and `CliffordNumbers.similar_type` have essentially +identical behavior. [docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg [docs-stable-url]: https://brainandforce.github.io/CliffordNumbers.jl/stable