diff --git a/Project.toml b/Project.toml index f35039c..9a7d77b 100644 --- a/Project.toml +++ b/Project.toml @@ -6,7 +6,6 @@ version = "0.4.2" [deps] AbstractAlgebra = "c3fe647b-3220-5bb0-a1ea-a7954cac585d" LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e" -Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a" [compat] AbstractAlgebra = "^0.9.0" diff --git a/src/DirectPower.jl b/src/DirectPower.jl index 567444e..8274465 100644 --- a/src/DirectPower.jl +++ b/src/DirectPower.jl @@ -6,9 +6,9 @@ export DirectPowerGroup, DirectPowerGroupElem # ############################################################################### -@doc doc""" +""" DirectPowerGroup(G::Group, n::Int) <: Group -Implements `n`-fold direct product of `G`. The group operation is +Return `n`-fold direct product of `G`. The group operation is `*` distributed component-wise, with component-wise identity as neutral element. """ struct DirectPowerGroup{N, T<:Group} <: Group @@ -70,11 +70,11 @@ Base.getindex(g::DirectPowerGroupElem, i::Int) = g.elts[i] # ############################################################################### -@doc doc""" +""" (G::DirectPowerGroup)(a::Vector, check::Bool=true) -> Constructs element of the $n$-fold direct product group `G` by coercing each -> element of vector `a` to `G.group`. If `check` flag is set to `false` neither -> check on the correctness nor coercion is performed. +Constructs element of the `n`-fold direct product group `G` by coercing each +element of vector `a` to `G.group`. If `check` flag is set to `false` neither +check on the correctness nor coercion is performed. """ function (G::DirectPowerGroup{N})(a::Vector, check::Bool=true) where N if check @@ -131,20 +131,12 @@ end # ############################################################################### -@doc doc""" - ==(g::DirectPowerGroup, h::DirectPowerGroup) -> Checks if two direct product groups are the same. -""" function (==)(G::DirectPowerGroup{N}, H::DirectPowerGroup{M}) where {N,M} N == M || return false G.group == H.group || return false return true end -@doc doc""" - ==(g::DirectPowerGroupElem, h::DirectPowerGroupElem) -> Checks if two direct product group elements are the same. -""" (==)(g::DirectPowerGroupElem, h::DirectPowerGroupElem) = g.elts == h.elts ############################################################################### @@ -153,11 +145,6 @@ end # ############################################################################### -@doc doc""" - *(g::DirectPowerGroupElem, h::DirectPowerGroupElem) -> Return the direct-product group operation of elements, i.e. component-wise -> operation as defined by `operations` field of the parent object. -""" function *(g::DirectPowerGroupElem{N}, h::DirectPowerGroupElem{N}, check::Bool=true) where N if check parent(g) == parent(h) || throw(DomainError( @@ -168,10 +155,6 @@ end ^(g::DirectPowerGroupElem, n::Integer) = Base.power_by_squaring(g, n) -@doc doc""" - inv(g::DirectPowerGroupElem) -> Return the inverse of the given element in the direct product group. -""" function inv(g::DirectPowerGroupElem{N}) where {N} return DirectPowerGroupElem(ntuple(i-> inv(g.elts[i]), N)) end diff --git a/src/Groups.jl b/src/Groups.jl index 4312ac2..3b79d37 100644 --- a/src/Groups.jl +++ b/src/Groups.jl @@ -11,7 +11,6 @@ import Base: findfirst, findnext, findlast, findprev, replace import Base: deepcopy_internal using LinearAlgebra -using Markdown export gens, FreeGroup, Aut, SAut @@ -32,17 +31,11 @@ include("findreplace.jl") include("DirectPower.jl") include("WreathProducts.jl") - ############################################################################### # # String I/O # -@doc doc""" - show(io::IO, W::GWord) -> The actual string produced by show depends on the eltype of `W.symbols`. - -""" function Base.show(io::IO, W::GWord) if length(W) == 0 print(io, "(id)") @@ -64,16 +57,17 @@ end # Misc # -@doc doc""" +""" gens(G::AbstractFPGroups) -> returns vector of generators of `G`, as its elements. +Return vector of generators of `G`, as its elements. """ AbstractAlgebra.gens(G::AbstractFPGroup) = G.(G.gens) -@doc doc""" - metric_ball(S::Vector{GroupElem}, center=Id; radius=2, op=*) +""" + metric_ball(S::AbstractVector{<:GroupElem} + [, center=one(first(S)); radius=2, op=*]) Compute metric ball as a list of elements of non-decreasing length, given the -word-length metric on group generated by `S`. The ball is centered at `center` +word-length metric on the group generated by `S`. The ball is centered at `center` (by default: the identity element). `radius` and `op` keywords specify the radius and multiplication operation to be used. """ @@ -90,12 +84,12 @@ function generate_balls(S::AbstractVector{T}, center::T=one(first(S)); return c.*B, sizes end -@doc doc""" - image(A::GWord, homomorphism; kwargs...) -Evaluate homomorphism `homomorphism` on a GWord `A`. -`homomorphism` needs implement - > `hom(s; kwargs...)`, -where `hom(;kwargs...)` evaluates the value at the identity element. +""" + image(w::GWord, homomorphism; kwargs...) +Evaluate homomorphism `homomorphism` on a group word (element) `w`. +`homomorphism` needs to implement +> `hom(w; kwargs...)`, +where `hom(;kwargs...)` returns the value at the identity element. """ function image(w::GWord, hom; kwargs...) return reduce(*, diff --git a/src/WreathProducts.jl b/src/WreathProducts.jl index 3754892..a6d4ab2 100644 --- a/src/WreathProducts.jl +++ b/src/WreathProducts.jl @@ -8,18 +8,17 @@ import AbstractAlgebra: AbstractPermutationGroup, AbstractPerm # ############################################################################### -@doc doc""" +""" WreathProduct(N, P) <: Group -> Implements Wreath product of a group `N` by permutation group $P = S_n$, -> usually written as $N \wr P$. -> The multiplication inside wreath product is defined as -> > `(n, σ) * (m, τ) = (n*σ(m), στ)` -> where `σ(m)` denotes the action (from the right) of the permutation group on -> `n-tuples` of elements from `N` +Return the wreath product of a group `N` by permutation group `P`, usually +written as `N ≀ P`. The multiplication inside wreath product is defined as +> `(n, σ) * (m, τ) = (n*σ(m), στ)` +where `σ(m)` denotes the action (from the right) of the permutation group on +`n-tuples` of elements from `N` # Arguments: -* `N::Group` : the single factor of the group $N$ -* `P::Generic.PermGroup` : full `PermutationGroup` +* `N::Group` : the single factor of the `DirectPower` group `N` +* `P::AbstractPermutationGroup` acting on `DirectPower` of `N` """ struct WreathProduct{N, T<:Group, PG<:AbstractPermutationGroup} <: Group N::DirectPowerGroup{N, T} @@ -71,25 +70,25 @@ function (G::WreathProduct{N})(g::WreathProductElem{N}) where {N} return WreathProductElem(n, p) end -@doc doc""" +""" (G::WreathProduct)(n::DirectPowerGroupElem, p::Generic.Perm) -> Creates an element of wreath product `G` by coercing `n` and `p` to `G.N` and -> `G.P`, respectively. +Create an element of wreath product `G` by coercing `n` and `p` to `G.N` and +`G.P`, respectively. """ (G::WreathProduct)(n::DirectPowerGroupElem, p::Generic.Perm) = WreathProductElem(n,p) Base.one(G::WreathProduct) = WreathProductElem(one(G.N), one(G.P), false) -@doc doc""" +""" (G::WreathProduct)(p::Generic.Perm) -> Returns the image of permutation `p` in `G` via embedding `p -> (id,p)`. +Return the image of permutation `p` in `G` via embedding `p → (id,p)`. """ (G::WreathProduct)(p::Generic.Perm) = G(one(G.N), p) -@doc doc""" +""" (G::WreathProduct)(n::DirectPowerGroupElem) -> Returns the image of `n` in `G` via embedding `n -> (n,())`. This is the -> embedding that makes the sequence `1 -> N -> G -> P -> 1` exact. +Return the image of `n` in `G` via embedding `n → (n, ())`. This is the +embedding that makes the sequence `1 → N → G → P → 1` exact. """ (G::WreathProduct)(n::DirectPowerGroupElem) = G(n, one(G.P)) @@ -149,14 +148,12 @@ end (p::Generic.Perm)(n::DirectPowerGroupElem) = DirectPowerGroupElem(n.elts[p.d]) -@doc doc""" +""" *(g::WreathProductElem, h::WreathProductElem) -> Return the wreath product group operation of elements, i.e. -> +Return the group operation of wreath product elements, i.e. > `g*h = (g.n*g.p(h.n), g.p*h.p)`, -> -> where `g.p(h.n)` denotes the action of `g.p::Generic.Perm` on -> `h.n::DirectPowerGroupElem` via standard permutation of coordinates. +where `g.p(h.n)` denotes the action of `g.p::Generic.Perm` on +`h.n::DirectPowerGroupElem` via standard permutation of coordinates. """ function *(g::WreathProductElem, h::WreathProductElem) return WreathProductElem(g.n*g.p(h.n), g.p*h.p, false) @@ -164,9 +161,9 @@ end ^(g::WreathProductElem, n::Integer) = Base.power_by_squaring(g, n) -@doc doc""" +""" inv(g::WreathProductElem) -> Returns the inverse of element of a wreath product, according to the formula +Return the inverse of element of a wreath product, according to the formula > `g^-1 = (g.n, g.p)^-1 = (g.p^-1(g.n^-1), g.p^-1)`. """ function inv(g::WreathProductElem) diff --git a/src/freereduce.jl b/src/freereduce.jl index 884dd34..715bc30 100644 --- a/src/freereduce.jl +++ b/src/freereduce.jl @@ -40,11 +40,10 @@ end reduce!(w::GWord) = freereduce!(w) -@doc doc""" +""" reduce(w::GWord) -> performs reduction/simplification of a group element (word in generators). -> The default reduction is the free group reduction -> More specific procedures should be dispatched on `GWord`s type parameter. - +performs reduction/simplification of a group element (word in generators). +The default reduction is the reduction in the free group reduction. +More specific procedures should be dispatched on `GWord`s type parameter. """ reduce(w::GWord) = reduce!(deepcopy(w)) diff --git a/src/types.jl b/src/types.jl index 1de0a34..e3a93bf 100644 --- a/src/types.jl +++ b/src/types.jl @@ -1,31 +1,31 @@ abstract type AbstractFPGroup <: Group end -@doc doc""" +""" ::GSymbol -> Represents a syllable. -> Abstract type which all group symbols of AbstractFPGroups should subtype. Each -> concrete subtype should implement fields: -> * `id` which is the `Symbol` representation/identification of a symbol -> * `pow` which is the (multiplicative) exponent of a symbol. +Represents a syllable. Abstract type which all group symbols of +`AbstractFPGroups` should subtype. Each concrete subtype should implement fields: + * `id` which is the `Symbol` representation/identification of a symbol + * `pow` which is the (multiplicative) exponent of a symbol. """ abstract type GSymbol end abstract type GWord{T<:GSymbol} <: GroupElem end -@doc doc""" +""" W::GroupWord{T} <: GWord{T<:GSymbol} <:GroupElem -> Basic representation of element of a finitely presented group. `W.symbols` -> fieldname contains particular group symbols which multiplied constitute a -> group element, i.e. a word in generators. -> As reduction (inside group) of such word may be time consuming we provide -> `savedhash` and `modified` fields as well: -> hash (used e.g. in the `unique` function) is calculated by reducing the word, -> setting `modified` flag to `false` and computing the hash which is stored in -> `savedhash` field. -> whenever word `W` is changed `W.modified` is set to `false`; -> Future comparisons don't perform reduction (and use `savedhash`) as long as -> `modified` flag remains `false`. +Basic representation of element of a finitely presented group. +* `syllables(W)` return particular group syllables which multiplied constitute `W` +group as a word in generators. +* `parent(W)` return the parent group. +As the reduction (inside the parent group) of word to normal form may be time +consuming, we provide a shortcut that is useful in practice: +`savehash!(W, h)` and `ismodified(W)` functions. +When computing `hash(W)`, a reduction to normal form is performed and a +persistent hash is stored inside `W`, setting `ismodified(W)` flag to `false`. +This hash can be accessed by `savedhash(W)`. +Future comparisons of `W` try not to perform reduction and use the stored hash as shortcut. Only when hashes collide reduction is performed. Whenever word `W` is +changed, `ismodified(W)` returns `false` and stored hash is invalidated. """ mutable struct GroupWord{T} <: GWord{T}