Updated Documenter documentation for Quaternions.jl extension

brainandforce · Nov 11, 2024 · a1dbc56 · a1dbc56
1 parent 5d67a17
commit a1dbc56
Show file tree

Hide file tree

Showing 5 changed files with 59 additions and 5 deletions.
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,3 +1,4 @@
 [deps]
 CliffordNumbers = "3998ac73-6bd4-4031-8035-f167dd3ed523"
+Quaternions = "94ee1d12-ae83-5a48-8b1c-48b8ff168ae0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,4 +1,5 @@
 using CliffordNumbers
+using Quaternions
 using Documenter
 
 import CliffordNumbers.BaseNumber

diff --git a/docs/src/api/extensions.md b/docs/src/api/extensions.md
@@ -0,0 +1,11 @@
+# Extensions
+
+## [Quaternions.jl]
+
+```@docs
+(::Type{H})(::AbstractCliffordNumber{VGA(3)}) where H<:Quaternion
+Quaternions.slerp(::AbstractCliffordNumber{VGA(3)}, ::AbstractCliffordNumber{VGA(3)}, ::Real)
+Quaternions.slerp(::AbstractCliffordNumber{VGA(3)}, ::Quaternion, ::Real)
+```
+
+[Quaternions.jl]:   https://github.com/JuliaGeometry/Quaternions.jl
diff --git a/docs/src/extensions.md b/docs/src/extensions.md
@@ -3,9 +3,48 @@
 CliffordNumbers.jl provides some extensions to allow for interoperability with other packages which
 we anticipate to be commonly used alongside it.
 
-!!! note
-    Extensions require Julia 1.9; support for previous versions will be dropped with the 0.2.0
-    release of CliffordNumbers.jl.
+## [Quaternions.jl]
+
+[Quaternions.jl] provides the `Quaternion` type.
+
+This extension treats `Quaternion{T}` as identical to `EvenCliffordNumber{VGA(3),T,4}`, and each 
+type can be constructed from the other. This also extends to `AbstractCliffordNumber{VGA(3)}`.
+
+```julia-repl
+julia> q = Quaternion(0, 1, 2, 3)
+Quaternion{Int64}(0, 1, 2, 3)
+
+julia> e = EvenCliffordNumber{VGA(3)}(q)
+4-element EvenCliffordNumber{VGA(3), Int64}:
+1e₁e₂ + 2e₁e₃ + 3e₂e₃
+
+julia> Quaternion(e)
+Quaternion{Int64}(0, 1, 2, 3)
+
+julia> KVector{2,VGA(3)}(q)
+3-element KVector{2, VGA(3), Int64}:
+1e₁e₂ + 2e₁e₃ + 3e₂e₃
+```
+However, conversion can fail if the target type cannot contain the result:
+```
+julia> convert(KVector{2,VGA(3)}, q)
+ERROR: InexactError: convert(KVector{2, VGA(3)}, EvenCliffordNumber{VGA(3), Int64}(0, 1, 2, 3))
+...
+```
+
+Promotion attempts to preserve the semantics of CliffordNumbers.jl, and therefore prefers to return
+an `AbstractCliffordNumber{VGA(3)}`.
+
+```julia-repl
+julia> promote_type(EvenCliffordNumber{VGA(3),Int}, QuaternionF64)
+EvenCliffordNumber{VGA(3), Float64, 4}
+
+julia> promote_type(KVector{2,VGA(3),Int}, QuaternionF64)
+EvenCliffordNumber{VGA(3), Float64, 4}
+
+julia> promote_type(KVector{1,VGA(3),Int}, QuaternionF64)
+CliffordNumber{VGA(3), Float64, 8}
+```
 
 ## [Unitful.jl]
 
@@ -34,4 +73,5 @@ julia> KVector{1, VGA(3)}(1, 2, 3) * 1.5u"m"
 
 Supported operations include the geometric product and wedge product.
 
+[Quaternions.jl]:   https://github.com/JuliaGeometry/Quaternions.jl
 [Unitful.jl]: https://github.com/PainterQubits/Unitful.jl
diff --git a/ext/CliffordNumbersQuaternionsExt.jl b/ext/CliffordNumbersQuaternionsExt.jl
@@ -28,6 +28,9 @@ function convert(::Type{C}, q::Quaternion) where C<:AbstractCliffordNumber{VGA(3
 end
 
 #---Conversion to quaternions----------------------------------------------------------------------#
+
+(::Type{H})(c::EvenCliffordNumber{VGA(3)}) where H<:Quaternion = H(Tuple(c)...)
+
 """
     Quaternion(c::AbstractCliffordNumber{VGA(3)})
     Quaternion{T}(c::AbstractCliffordNumber{VGA(3)})
@@ -39,8 +42,6 @@ Any odd-grade coefficients of `c` are lost.
 If loss of odd-grade coefficients should throw an error, use `convert(Quaternion, c)` or
 `convert(Quaternion{T}, c)` instead of the constructor.
 """
-(::Type{H})(c::EvenCliffordNumber{VGA(3)}) where H<:Quaternion = H(Tuple(c)...)
-
 function (::Type{H})(c::AbstractCliffordNumber{VGA(3)}) where H<:Quaternion
     return H(EvenCliffordNumber{VGA(3)}(c))
 end