#  Copyright (c) 1997-2021
#  Ewgenij Gawrilow, Michael Joswig, and the polymake team
#  Technische Universität Berlin, Germany
#  https://polymake.org
#
#  This program is free software; you can redistribute it and/or modify it
#  under the terms of the GNU General Public License as published by the
#  Free Software Foundation; either version 2, or (at your option) any
#  later version: http://www.gnu.org/licenses/gpl.txt.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#-------------------------------------------------------------------------------

REQUIRE_EXTENSION bundled:graph_compare

CREDIT graph_compare = bundled:graph_compare

# @category Comparing
# true if //IncidenceMatrix1// and //IncidenceMatrix2// are isomorphic.
# @param IncidenceMatrix IncidenceMatrix1
# @param IncidenceMatrix IncidenceMatrix2
# @return Bool
# @depends bliss or nauty
# @example [application polytope]
# Compare the incidence matrices of the 2-dimensional cube and cross polytope:
# > $I1 = cube(2)->VERTICES_IN_FACETS;
# > $I2 = cross(2)->VERTICES_IN_FACETS;
# > print isomorphic($I1,$I2);
# | true
user_function isomorphic(IncidenceMatrix, IncidenceMatrix) : c++ (include => "polymake/graph/compare.h");

# @category Comparing
# true if //graph1// and //graph2// are isomorphic.
# @param GraphAdjacency graph1
# @param GraphAdjacency graph2
# @return Bool
# @depends bliss or nauty
# @example [application polytope]
# Compare the vertex-edge graph of the square with the cycle graph on 4 nodes:
# > $g1 = cube(2)->GRAPH->ADJACENCY;
# > $g2 = cycle_graph(4)->ADJACENCY;
# > print isomorphic($g1,$g2);
# | true
user_function isomorphic(GraphAdjacency, GraphAdjacency) : c++ (include => "polymake/graph/compare.h");

# @category Comparing
# Find the node permutation mapping //graph1// to //graph2//.
# @param GraphAdjacency graph1
# @param GraphAdjacency graph2
# @return Array<Int> permutation of node indexes, or undef if graphs are not isomorphic
# @depends bliss or nauty
user_function find_node_permutation(GraphAdjacency, GraphAdjacency) : c++ (include => "polymake/graph/compare.h");


# @category Comparing
# Find the permutations mapping the non-symmetric incidence matrix //m1// to //m2//.
# @param IncidenceMatrix<NonSymmetric> m1
# @param IncidenceMatrix<NonSymmetric> m2
# @return Pair<Array<Int>,Array<Int>> ''first'' permutation applied to the rows, ''second'' applied to the columns,
#         or undef if matrices are not isomorphic
# @depends bliss or nauty
# @example
# > $m1 = new IncidenceMatrix([1,2],[5,3]);
# > $m2 = new IncidenceMatrix([4,3],[1,5]);
# > print find_row_col_permutation($m1,$m2);
# | <1 0> <0 1 4 3 5 2>
user_function find_row_col_permutation(IncidenceMatrix<NonSymmetric>, IncidenceMatrix<NonSymmetric>) \
   : c++ (include => "polymake/graph/compare.h");


# @category Comparing
# Find the automorphism group of the graph.
# @param GraphAdjacency graph
# @return Array<Array<Int>> each element encodes a node permutation.
# @depends bliss or nauty
# @example [application polytope]
# We first create the vertex-edge graph of the square and then print its automorphism group:
# > $g=new GraphAdjacency(cube(2)->GRAPH->ADJACENCY);
# > print automorphisms($g);
# | 0 2 1 3
# | 1 0 3 2
# These two permutations generate the group of all node permutations
# that preserve vertex-edge connectivity.
user_function automorphisms(GraphAdjacency) : c++ (include => "polymake/graph/compare.h");

function automorphisms(GraphAdjacency, *) : c++ (include => "polymake/graph/compare.h");

# @category Comparing
# Find the order of the automorphism group of the graph.
# @param GraphAdjacency graph
# @return Int the order of the automorphism group
# @depends bliss or nauty
# @example
# > print n_automorphisms(cycle_graph(5)->ADJACENCY);
# | 2
user_function n_automorphisms(GraphAdjacency) : c++ (include => "polymake/graph/GraphIso.h");


# @category Comparing
# Find the automorphism group of the non-symmetric incidence matrix.
# @param IncidenceMatrix<NonSymmetric> m
# @return Array<Pair<Array<Int>,Array<Int>>> each element encodes a permutation of its rows (''first'') and columns (''second'').
# @depends bliss or nauty
# @example [application polytope]
# The group of combinatorial automorphisms of the 3-cube coincides with
# the group of (bipartite) graph automorphisms of the vertex/facet incidences.
# To print this group, type this:
# > print automorphisms(cube(3)->VERTICES_IN_FACETS);
# | (<0 1 4 5 2 3> <0 1 4 5 2 3 6 7>)
# | (<2 3 0 1 4 5> <0 2 1 3 4 6 5 7>)
# | (<1 0 2 3 4 5> <1 0 3 2 5 4 7 6>)
# This means that the group is generated by three elements, one per line in the output.
# Each is written as a pair of permutations. The first gives the action on the facets,
# the second the action on the vertices.
user_function automorphisms(IncidenceMatrix<NonSymmetric>) : c++ (include => "polymake/graph/compare.h");


# @category Comparing
# Find the automorphism group of the symmetric incidence matrix.
# @param IncidenceMatrix<Symmetric> m
# @return Array<Array<Int>> each element encodes a permutation of its rows (=columns).
# @depends bliss or nauty
user_function automorphisms(IncidenceMatrix<Symmetric>) : c++ (include => "polymake/graph/compare.h");


# @category Comparing
# Find a canonical representation of a graph //g//.
# Warning: This representation can depend on the extension (bliss/nauty) used, its version and configuration, as well as the hardware!
# @param GraphAdjacency g
# @return GraphAdjacency
# @depends bliss or nauty
user_function canonical_form(GraphAdjacency) : c++ (include => "polymake/graph/compare.h");

# @category Comparing
# Compute a hash for a graph //g// independent of the node ordering.
# Warning: This hash can depend on the extension (bliss/nauty) used, its version and configuration, as well as the hardware!
# Nauty requires an integer key //k// as input, bliss will ignore the key.
# @param GraphAdjacency g
# @param Int k a key for the hash computation, default value 2922320
# @return Int
# @depends bliss or nauty
user_function canonical_hash(GraphAdjacency; $=2922320) : c++ (include => "polymake/graph/compare.h");

# @category Comparing
# Compute a hash for an incidence matrix //I// independent of the row ordering.
# Warning: This hash can depend on the extension (bliss/nauty) used, its version and configuration, as well as the hardware!
# Nauty requires an integer key //k// as input, bliss will ignore the key.
# @param IncidenceMatrix M
# @param Int k a key for the hash computation, default value 2922320
# @return Int
# @depends bliss or nauty
user_function canonical_hash(IncidenceMatrix; $=2922320) : c++ (include => "polymake/graph/compare.h");


object Graph {

# @notest  Rule defined "in stock" - currently without use
rule NodePerm.PERMUTATION : NodePerm.ADJACENCY, ADJACENCY {
   $this->NodePerm->PERMUTATION = find_node_permutation($this->NodePerm->ADJACENCY, $this->ADJACENCY)
      // die "no permutation";
}
weight 5.10;

}


# Local Variables:
# mode: perl
# cperl-indent-level:3
# indent-tabs-mode:nil
# End:
