Edit on GitHub

Group elements

GroupsCore defines abstract type GroupElement, which all implementations of group elements should subtype.

Obligatory methods

Base.parent — Method
parent(g::GroupElement)

Return the parent object of the group element.

source
Base.:== — Method
==(g::GEl, h::GEl) where {GEl <: GroupElement}

Return the best effort equality for group elements.

If ==(g, h) returns truethen the mathematical equalityg == hholds. However==(g, h)may returnfalseeven ifgandh` represent mathematically equal group elements.

For example, in a finitely presented group, == may return the equality of words.

Note

This function may not return due to unsolvable word problem.

source
GroupsCore.isfiniteorder — Method
isfiniteorder(g::GroupElement)

Return true if g is of finite order, possibly without computing it.

Note

If finiteness of a group can be decided based on its type there is no need to extend isfiniteorder for its elements.

source

As well as the two arithmetic operations:

Base.inv(::GroupElement)
Base.:(*)(::GEl, ::GEl) where {GEl <: GroupElement}

A note on deepcopy

The elements which are not of isbitstype should extend

Base.deepcopy_internal(g::GroupElement, ::IdDict)

according to Base.deepcopy docstring. Due to our assumption on parents of group elements (acting as local singleton objects), a group element and its deepcopy should have identical (i.e. ===) parents.

Implemented methods

Using the obligatory methods we implement the rest of the functions in GroupsCore. For starters, the first of these are:

Base.:(^)(::GroupElement, ::Integer)
Base.:(/)(::GEl, ::GEl) where {GEl <: GroupElement}
Base.one(::GroupElement)

and

GroupsCore.order — Method
order([::Type{T} = BigInt, ]g::GroupElement) where T

Return the order of g as an instance of T. If g is of infinite order GroupsCore.InfiniteOrder exception will be thrown.

Warning

Only arbitrary sized integers are required to return a mathematically correct answer.

source
Base.conj — Function
conj(g::GEl, h::GEl) where {GEl <: GroupElement}

Return the conjugation of g by h, i.e. inv(h)*g*h.

source
GroupsCore.commutator — Function
commutator(g::GEl, h::GEl, k::GEl...) where {GEl <: GroupElement}

Return the left associative iterated commutator $[[g, h], ...]$, where $[g, h] = g^{-1} h^{-1} g h$.

source

Moreover we provide basic implementation which should be altered for performance reasons:

Base.:(^)(g::GroupElement, n::Integer)
Groups.Core.order([::Type{T}], g::GroupElement) where T
Base.hash(::GroupElement, ::UInt)

Mutable API

Warning

Work-in-progress. Mutable API is considered private and hence may change between versions without warning.

For the purpose of mutable arithmetic the following methods may be overloaded to provide more tailored versions for a given type and reduce the allocations. These functions should be used when writing libraries, in performance critical sections. However one should only use the returned value and there are no guarantees on in-place modifications actually happening.

All of these functions (possibly) alter only the first argument, and must unalias their arguments when necessary.

GroupsCore.inv! — Function
inv!(out::GEl, g::GEl) where {GEl <: GroupElement}

Return inv(g), possibly modifying out. Aliasing of g with out is allowed.

source
GroupsCore.mul! — Function
mul!(out::GEl, g::GEl, h::GEl) where {GEl <: GroupElement}

Return g*h, possibly modifying out. Aliasing of g or h with out is allowed.

source
GroupsCore.div_left! — Function
div_left!(out::GEl, g::GEl, h::GEl) where {GEl <: GroupElement}

Return inv(h)*g, possibly modifying out. Aliasing of g or h with out is allowed.

source
GroupsCore.div_right! — Function
div_right!(out::GEl, g::GEl, h::GEl) where {GEl <: GroupElement}

Return g*inv(h), possibly modifying out. Aliasing of g or h with out is allowed.

source
GroupsCore.conj! — Function
conj!(out::GEl, g::GEl, h::GEl) where {GEl <: GroupElement}

Return inv(h)*g*h, possibly modifying out. Aliasing of g or h with out is allowed.

source
GroupsCore.commutator! — Function
commutator!(out::GEl, g::GEl, h::GEl) where {GEl <: GroupElement}

Return inv(g)*inv(h)*g*h, possibly modifying out. Aliasing of g or h with out is allowed.

source