Adds functionality for automorphisms of simplicial complexes (oscar-s…

…ystem#3498)

* adds functionality for automorphisms of simplicial complexes

* adds docs + missing docs for the other recently added functions

* adjustments to the docs

* adds n_facets + uses combinatorial symmetries from polymake

* acts on_simplicial_complex

* fixes for docstrings

* fixes require check

docs/src/Combinatorics/simplicialcomplexes.md

@@ -46,6 +46,7 @@ complex_projective_plane()
 
 ```@docs
 n_vertices(K::SimplicialComplex)
+n_facets(K::SimplicialComplex)
 dim(K::SimplicialComplex)
 f_vector(K::SimplicialComplex)
 h_vector(K::SimplicialComplex)
@@ -98,6 +99,10 @@ stanley_reisner_ring(R::MPolyRing, K::SimplicialComplex)
 
 ```@docs
 is_isomorphic(K1::SimplicialComplex, K2::SimplicialComplex)
+connected_sum(K1::SimplicialComplex, K2::SimplicialComplex, f1::Int=0, f2::Int=0)
+deletion(K::SimplicialComplex, face::Union{<:AbstractSet{Int},<:AbstractVector{Int}})
+automorphism_group(K::SimplicialComplex; action=:on_vertices)
+on_simplicial_complex(K::SimplicialComplex, g::PermGroupElem)
 ```
 
 ## Saving and loading

src/Combinatorics/SimplicialComplexes.jl

@@ -120,6 +120,13 @@ julia> n_vertices(torus())
 """
 n_vertices(K::SimplicialComplex) = pm_object(K).N_VERTICES::Int
 
+@doc raw"""
+     n_facets(K::SimplicialComplex)
+
+Return the number of facets of the abstract simplicial complex `K`.
+"""
+n_facets(K::SimplicialComplex) = pm_object(K).N_FACETS::Int
+
 @doc raw"""
     facets(K::SimplicialComplex)
 
@@ -624,3 +631,63 @@ function deletion(K::SimplicialComplex, face::Union{<:AbstractSet{Int},<:Abstrac
   zero_based = Polymake.to_zero_based_indexing(face)
   return SimplicialComplex(Polymake.topaz.deletion(pm_object(K), zero_based))
 end
+
+@doc raw"""
+    automorphism_group(K::SimplicialComplex; action=:on_vertices)
+
+Given a simplicial complex `K` return its automorphism group as a `PermGroup`.
+The group can be returned as a subgroup of the permutation group of the vertices
+by passing `:on_vertices` to the `action` keyword argument or on the facets
+ by passing `:on_facets`.
+
+# Examples
+```jldoctest
+julia> K = simplicial_complex([[1, 2, 3], [2, 3, 4]])
+Abstract simplicial complex of dimension 2 on 4 vertices
+
+julia> automorphism_group(K)
+Permutation group of degree 4
+```
+"""
+function automorphism_group(K::SimplicialComplex; action=:on_vertices)
+  pm_K = Oscar.pm_object(K)
+  Polymake.topaz.combinatorial_symmetries(pm_K)
+  if action == :on_vertices
+    gens_G = Polymake.to_one_based_indexing(pm_K.GROUP.RAYS_ACTION.GENERATORS)
+    n = n_vertices(K)
+    return permutation_group(n, cperm.(gens_G))
+  elseif action == :on_facets
+    gens_G = Polymake.to_one_based_indexing(pm_K.GROUP.FACETS_ACTION.GENERATORS)
+    n = n_facets(K)
+    return permutation_group(n, cperm.(gens_G))
+  else
+    error("unsupported keyword passed to action")
+  end
+end
+
+@doc raw"""
+    on_simplicial_complex(K::SimplicialComplex, g::PermGroupElem)
+
+Given a simplicial complex `K` return the simplicial complex corresponding
+to a permutation on it's vertices given by `g`.
+
+# Examples
+```jldoctest
+julia> K = simplicial_complex([[1, 2, 3], [2, 3, 4]])
+Abstract simplicial complex of dimension 2 on 4 vertices
+
+julia> G = automorphism_group(K)
+Permutation group of degree 4
+
+julia> g = collect(G)[2]
+(1,2)(3,4)
+
+julia> on_simplicial_complex(K, g)
+Abstract simplicial complex of dimension 2 on 4 vertices
+```
+"""
+function on_simplicial_complex(K::SimplicialComplex, g::PermGroupElem)
+  @req degree(parent(g)) == n_vertices(K) "g needs to be an element of the permutation group on the vertices"
+  new_facets = on_sets_sets(Set(facets(K)), g)
+  simplicial_complex(collect(new_facets))
+end

src/exports.jl

@@ -1092,6 +1092,7 @@ export on_indeterminates
 export on_lines
 export on_sets
 export on_sets_sets
+export on_simplicial_complex
 export on_subgroups
 export on_tuples
 export one!

test/Combinatorics/SimplicialComplexes.jl

@@ -65,4 +65,17 @@
     K2 = simplicial_complex([[1, 2], [2, 3]])
     @test is_isomorphic(K1, K2)
   end
+
+  @testset "automorphism groups" begin
+    K = simplicial_complex([[1, 2], [2, 3]])
+    G = automorphism_group(K)
+    @test G == permutation_group(3, cperm.([[1, 2, 3], [1, 3, 2]]))
+
+    g = collect(G)[2]
+    G_K = on_simplicial_complex(K, g)
+    @test facets(simplicial_complex([[1, 3], [2, 3]])) == facets(G_K)
+
+    G = automorphism_group(K; action=:on_facets)
+    @test G == permutation_group(2, [cperm([1, 2])])
+  end
 end