full automorphism support (#73)

* full automorphism support

* more tests

* document generator behavior on order=1 groups

* nicer autg printing; doctests

Author: mxhbl

docs/Project.toml

@@ -1,5 +1,6 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 
 [compat]
 Documenter = "1.15"

docs/make.jl

@@ -1,6 +1,6 @@
-using Documenter, NautyGraphs
+using Documenter, NautyGraphs, Graphs
 
-DocMeta.setdocmeta!(NautyGraphs, :DocTestSetup, :(using NautyGraphs); recursive=true)
+DocMeta.setdocmeta!(NautyGraphs, :DocTestSetup, :(using NautyGraphs, Graphs); recursive=true)
 
 makedocs(sitename="NautyGraphs.jl";
     pages = [

docs/src/groups.md

@@ -1,3 +1,87 @@
 # Graph automorphism groups
-To obtain information about a graph's automorphism group, use `nauty(g)`. This will return the canonical permutation as well as an `AutomorphismGroup` object.
-Right now, the recorded properties of the automorphism group are very limited and only include the group size and orbits, but this will change in the future.
+
+Use `automorphism_group(g)` to get a graph's [`AutomorphismGroup`](@ref).
+It reports the group's [`order`](@ref), its vertex [`orbits`](@ref) and a set of [`generators`](@ref), and leaves `g` untouched.
+
+```jldoctest groups
+julia> using NautyGraphs, Graphs
+
+julia> g = NautyGraph(smallgraph(:petersen));
+
+julia> autg = automorphism_group(g)
+AutomorphismGroup
+  order       120
+  vertices    10
+  orbits      1
+  generators  4
+
+julia> order(autg)
+120
+
+julia> orbit_partition(autg)
+1-element Vector{Vector{Int64}}:
+ [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+```
+
+Generators are permutations in one-based form: generator `p` maps vertex `i` to `p[i]`.
+Together they generate the whole group, so its `order` is generally much larger than the number of generators.
+
+The identity belongs to every automorphism group and is never listed as a generator.
+A graph with no symmetry therefore comes back with an empty generating set, not with a single identity permutation.
+
+```jldoctest groups
+julia> frucht = automorphism_group(NautyGraph(smallgraph(:frucht)))
+AutomorphismGroup
+  order       1
+  vertices    12
+  orbits      12
+  generators  0
+
+julia> generators(frucht)
+Vector{Int32}[]
+```
+
+
+`orbits(autg)` labels every vertex with the smallest vertex it can be mapped to, so two vertices share an orbit exactly if they carry the same label.
+`orbit_partition(autg)` turns that labelling into one vector per orbit, at the cost of an allocation per orbit.
+
+## Computing less
+
+`automorphism_group` computes everything nauty can report.
+When that is more than you need, call [`nauty`](@ref) directly and switch the expensive parts off.
+It returns the canonical permutation alongside the group, so nothing has to be recomputed:
+
+```jldoctest groups
+julia> canonperm, autg = nauty(g; generators=true);
+
+julia> order(autg)
+120.0
+```
+
+The orbits and an approximate order come for free with every run.
+The generators and the exact order each cost an extra callback into Julia, so they are opt-in:
+
+| keyword | what it adds | cost |
+| --- | --- | --- |
+| none | orbits, `order` as a `Float64` | free |
+| `generators=true` | the generating permutations | one callback per generator |
+| `exact_order=true` | `order` as an exact `BigInt` | one callback per search-tree level |
+| `canonize=true` | canonizes `g` in place | rewrites the group into the new numbering |
+
+Without `exact_order=true`, `order(autg)` is a `Float64`: it carries about 16 significant digits, is exact up to roughly `10^12`, and overflows to `Inf` past `10^308`.
+Ask for the exact order whenever you need to count with it, for example when dividing by ``|\mathrm{Aut}(g)|``.
+
+!!! warning "`canonize` renumbers the group as well"
+
+    Nauty reports the automorphism group in terms of `g`'s vertex numbering on input.
+    With `canonize=true` that numbering is replaced, so the returned orbits and generators are rewritten to match the canonized `g` and no longer refer to the graph as it was passed in.
+
+## Working with the group
+
+NautyGraphs deliberately does not implement group theory beyond what nauty reports.
+To enumerate elements, test membership or build stabilizer chains, hand the generators to a group theory package:
+
+```julia
+using PermutationGroups
+group = PermGroup([Perm(p) for p in generators(autg)])
+```

src/NautyGraphs.jl

@@ -15,6 +15,14 @@ include("sparsenautygraph.jl")
 include("nauty.jl")
 include("graphs_api_extensions.jl")
 
+function __init__()
+    _GENERATOR_CALLBACK[] = @cfunction(_record_generator, Cvoid,
+            (Cint, Ptr{Cint}, Ptr{Cint}, Cint, Cint, Cint))
+    _LEVEL_CALLBACK[] = @cfunction(_record_level, Cvoid,
+            (Ptr{Cint}, Ptr{Cint}, Cint, Ptr{Cint}, Ptr{Cvoid}, Cint, Cint, Cint, Cint, Cint, Cint))
+    return
+end
+
 export
     add_edge!,
     rem_edge!,
@@ -40,7 +48,12 @@ export
     DenseNautyGraph,
     SparseNautyGraph,
     AutomorphismGroup,
-    labels, 
+    automorphism_group,
+    order,
+    orbits,
+    orbit_partition,
+    generators,
+    labels,
     label, 
     setlabels!,
     setlabel!,

src/graphs_api_extensions.jl

@@ -40,10 +40,8 @@ function count_isomorph(g1::AbstractGraph, g2::AbstractGraph, ::NautyAlg{true};
 end
 
 function _count_isomorph(g1, g2)
-    _, autg = nauty(g1; canonize=true)
-    if g1 ≃ g2
-        return autg.n
-    else
-        return zero(autg.n)
-    end
+    g1 ≃ g2 || return big(0)
+    # the number of isomorphisms is the order of the automorphism group, so it has to be exact
+    _, autg = nauty(g1; exact_order=true)
+    return order(autg)
 end