.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Graph::Nauty 3pm"
.TH Graph::Nauty 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Graph::Nauty \- Perl bindings for Nauty
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 7
\&  use Graph::Nauty qw(
\&      are_isomorphic
\&      automorphism_group_size
\&      canonical_order
\&      orbits
\&  );
\&  use Graph::Undirected;
\&
\&  my $A = Graph::Undirected\->new;
\&  my $B = Graph::Undirected\->new;
\&
\&  # Create graphs here
\&
\&  # Get the size of the automorphism group:
\&  print automorphism_group_size( $A );
\&
\&  # Get automorphism group orbits:
\&  print orbits( $A );
\&
\&  # Check whether two graphs are isomorphs:
\&  print are_isomorphic( $A, $B );
\&
\&  # Get canonical order of vertices:
\&  print canonical_order( $A );
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Graph::Nauty provides an interface to Nauty, a set of procedures for
determining the automorphism group of a vertex-coloured graph, and for
testing graphs for isomorphism.
.PP
Currently Graph::Nauty only supports
Graph::Undirected, that is, it does not handle
directed graphs. Both colored vertices and edges are accounted for when
determining equivalence classes.
.SS "Vertex color"
.IX Subsection "Vertex color"
As Graph supports any data types as graph vertices, not much
can be inferred about them automatically. For now, Graph::Nauty by
default stringifies every vertex (using Perl \f(CW""\fR operator) and splits
them into equivalence classes. If different behavior is needed, a custom
anonymous subroutine can be passed inside an option hash:
.PP
.Vb 1
\&  print orbits( $A, sub { return length $_[0] } );
.Ve
.PP
Subroutine gets a vertex as its 0th parameter, and is expected to return
a string, or anything stringifiable.
.PP
In subroutines where the order of returned vertices is important, a
second anonymous subroutine can be passed to order vertices inside each
of the equivalence classes:
.PP
.Vb 1
\&  print orbits( $A, sub { return length $_[0] }, sub { return "$_[0]" } );
.Ve
.PP
If an ordering subroutine is not given, stringification (Perl \f(CW""\fR
operator) is used by default.
.SS "Edge color"
.IX Subsection "Edge color"
Edge colors are generated from Graph edge attributes. Complete
hash of each edge's attributes is stringified (deterministically) and
used to divide edges into equivalence classes.
.SS "Working storage size"
.IX Subsection "Working storage size"
Nauty needs working storage, which it does not allocate by itself.
Graph::Nauty follows the advice of the Nauty user guide by allocating
the recommended amount of memory, but for certain graphs this might not
be enough, still. To control that, \f(CW$Graph::Nauty::worksize\fR could be
used to set the size of memory in the units of Nauty's \f(CW\*(C`setword\*(C'\fR.
.SH INSTALLING
.IX Header "INSTALLING"
Building and installing Graph::Nauty from source requires shared library
and C headers for Nauty, which can be downloaded from
<https://users.cecs.anu.edu.au/~bdm/nauty/>. Both the library and C
headers have to be installed to locations visible by Perl's C compiler.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For the description of Nauty refer to <http://pallini.di.uniroma1.it>.
.SH AUTHOR
.IX Header "AUTHOR"
Andrius Merkys, <mailto:merkys@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2020 by Andrius Merkys
.PP
Graph::Nauty is distributed under the BSD\-3\-Clause license.