\HeaderA{canonical.permutation}{Canonical permutation of a graph}{canonical.permutation}
\keyword{graphs}{canonical.permutation}
\begin{Description}\relax
The canonical permutation brings every isomorphic graphs
into the same (labeled) graphs.
\end{Description}
\begin{Usage}
\begin{verbatim}
canonical.permutation(graph, sh="fm")
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{graph}] The input graph, treated as undirected.
\item[\code{sh}] Type of the heuristics to use for the BLISS
algorithm. See details for possible values.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{canonical.permutation} computes a permutation which brings the
graph into canonical form, as defined by the BLISS algorithm.
All isomorphic graphs have the same canonical form.

See the paper below for the details about BLISS. This and more
information is available at
\url{http://www.tcs.hut.fi/Software/bliss/index.html}.

The possible values for the \code{sh} argument are:
\Itemize{
\item[f] First non-singleton cell.
\item[fl] First largest non-singleton cell.
\item[fs] First smallest non-singleton cell.
\item[fm] First maximally non-trivially connectec non-singleton
cell.
\item[flm] Largest maximally non-trivially connected non-singleton
cell.
\item[fsm] Smallest maximally non-trivially connected non-singleton
cell.
}
See the paper in references for details about these.
\end{Details}
\begin{Value}
A list with the following members:
\begin{ldescription}
\item[\code{labeling}] The canonical parmutation which takes the input
graph into canonical form. A numeric vector, the first element is
the new label of vertex 0, the second element for vertex 1, etc. 
\item[\code{info}] Some information about the BLISS computation. A named
list with the following members:
\Itemize{
\item[nof\_nodes] The number of nodes in the search tree.
\item[nof\_leaf\_nodes] The number of leaf nodes in the search
tree.
\item[nof\_bad\_nodes] Number of bad nodes.
\item[nof\_canupdates] Number of canrep updates.
\item[max\_level] Maximum level.
\item[group\_size] The size of the automorphism group of the
input graph, as a string. This number is exact if igraph was
compiled with the GMP library, and approximate otherwise.
}

\end{ldescription}
\end{Value}
\begin{Author}\relax
Tommi Junttila for BLISS, Gabor Csardi
\email{csardi@rmki.kfki.hu} for the igraph and R interfaces.
\end{Author}
\begin{References}\relax
Tommi Junttila and Petteri Kaski: Engineering an Efficient Canonical
Labeling Tool for Large and Sparse Graphs, \emph{Proceedings of the
Ninth Workshop on Algorithm Engineering and Experiments and the
Fourth Workshop on Analytic Algorithms and Combinatorics.} 2007.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{permute.vertices}{permute.vertices}} to apply a permutation to a
graph, \code{\LinkA{graph.isomorphic}{graph.isomorphic}} for deciding graph isomorphism,
possibly based on canonical labels.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Calculate the canonical form of a random graph
g1 <- erdos.renyi.game(10, 20, type="gnm")
cp1 <- canonical.permutation(g1)
cf1 <- permute.vertices(g1, cp1$labeling)

## Do the same with a random permutation of it
g2 <- permute.vertices(g1, sample(vcount(g1))-1)
cp2 <- canonical.permutation(g2)
cf2 <- permute.vertices(g2, cp2$labeling)

## Check that they are the same
el1 <- get.edgelist(cf1)
el2 <- get.edgelist(cf2)
el1 <- el1[ order(el1[,1], el1[,2]), ]
el2 <- el2[ order(el2[,1], el2[,2]), ]
all(el1 == el2)
\end{ExampleCode}
\end{Examples}

