=pod

=head1 NAME

Graph - graph data structures and algorithms

=head1 SYNOPSIS

	use Graph;
	my $g0 = Graph->new;             # A directed graph.

	use Graph::Directed;
	my $g1 = Graph::Directed->new;   # A directed graph.

	use Graph::Undirected;
	my $g2 = Graph::Undirected->new; # An undirected graph.

        $g->add_edge(...);
        $g->has_edge(...)
        $g->any_edge(...)
        $g->delete_edge(...);

        $g->add_vertex(...);
        $g->has_vertex(...);
        $g->delete_vertex(...);

        $g->vertices(...)
        $g->edges(...)

        # And many, many more, see below.

=head1 DESCRIPTION

=head2 Non-Description

This module is not for B<drawing> or B<rendering> any sort of
I<graphics> or I<images>, business, visualization, or otherwise.

=head2 Description

Instead, this module is for creating I<abstract data structures>
called graphs, and for doing various operations on those.

=head2 Perl 5.6.0 minimum

The implementation depends on a Perl feature called "weak references"
and Perl 5.6.0 was the first to have those.

=head2 Constructors

=over 4

=item new

Create an empty graph.

=item Graph->new(%options)

The options are a hash with option names as the hash keys and the option
values as the hash values.

The following options are available:

=over 8

=item directed

A boolean option telling that a directed graph should be created.
Often somewhat redundant because a directed graph is the default
for the Graph class or one could simply use the C<new()> constructor
of the Graph::Directed class.

You can test the directness of a graph with $g->is_directed() and
$g->is_undirected().

=item undirected

A boolean option telling that an undirected graph should be created.
One could also use the C<new()> constructor the Graph::Undirected class
instead.

Note that while often it is possible to think of undirected graphs as
bidirectional graphs, or as directed graphs with edges going both ways,
in this module directed graphs and undirected graphs are two different
things that often behave differently.

You can test the directness of a graph with $g->is_directed() and
$g->is_undirected().

=item refvertexed

=item refvertexed_stringified

If you want to use references (including Perl objects) as vertices,
use C<refvertexed>.

Note that using C<refvertexed> means that internally the memory
address of the reference (for example, a Perl object) is used as the
"identifier" of the vertex, not the stringified form of the reference,
even if you have defined your own stringification using C<overload>.

This avoids the problem of the stringified references potentially
being identical (because they are identical in value, for example)
even if the references are different.  If you really want to use
references B<and> their stringified forms as the identities, use the
C<refvertexed_stringified>.  But please do B<not> stringify different
objects to the same stringified value.

=item unionfind

If the graph is undirected, you can specify the C<unionfind> parameter
to use the so-called union-find scheme to speed up the computation of
I<connected components> of the graph (see L</is_connected>,
L</connected_components>, L</connected_component_by_vertex>,
L</connected_component_by_index>, and L</same_connected_components>).
If C<unionfind> is used, adding edges (and vertices) becomes slower,
but connectedness queries become faster.  You B<must not> delete edges or
vertices of an unionfind graph, only add them.  You can test a graph for
"union-findness" with

=item has_union_find

Returns true if the graph was created with a true C<unionfind> parameter.

=item vertices

An array reference of vertices to add.

=item edges

An array reference of array references of edge vertices to add.

=back

=item copy

=item copy_graph

    my $c = $g->copy_graph;

Create a shallow copy of the structure (vertices and edges) of the
graph.  If you want a deep copy that includes attributes, see
L</deep_copy>.  The copy will have the same directedness as the
original.

Also the following vertex/edge attributes are copied:

  refvertexed/countvertexed/multivertexed
  hyperedged/countedged/multiedged

B<NOTE>: You can get an even shallower copy of a graph by

    my $c = $g->new;

This will copy only the graph properties (directed, and so forth),
but none of the vertices or edges.

As of 0.9712, you can also copy the graph properties of an existing
object, I<but> with overrides:

    my $c = $g->new(multiedged => 0);

=item deep_copy

=item deep_copy_graph

    my $c = $g->deep_copy_graph;

Create a deep copy of the graph (vertices, edges, and attributes) of
the graph.  If you want a shallow copy that does not include
attributes, see L</copy>.

Note that copying code references only works with Perls 5.8 or later,
and even then only if B::Deparse can reconstruct your code.  This
functionality uses either Storable or Data::Dumper behind the scenes,
depending on which is available (Storable is preferred).

If your vertices are references, the copied graph will have its
connections fixed up. Support for this is new as of 0.9723, so please
report any problems.

=item undirected_copy

=item undirected_copy_graph

    my $c = $g->undirected_copy_graph;

Create an undirected shallow copy (vertices and edges) of the directed graph
so that for any directed edge (u, v) there is an undirected edge (u, v).

=item undirected_copy_clear_cache

    @path = $g->undirected_copy_clear_cache;

See L</"Clearing cached results">.

=item directed_copy

=item directed_copy_graph

    my $c = $g->directed_copy_graph;

Create a directed shallow copy (vertices and edges) of the undirected graph
so that for any undirected edge (u, v) there are two directed edges (u, v)
and (v, u).

=item transpose

=item transpose_graph

    my $t = $g->transpose_graph;

Create a directed shallow transposed copy (vertices and edges) of the
directed graph so that for any directed edge (u, v) there is a directed
edge (v, u).

You can also transpose a single edge with

=over 8

=item transpose_edge

    $g->transpose_edge($u, $v)

=back

=item complete_graph

=item complete

    my $c = $g->complete_graph;

Create a complete graph that has the same vertices as the original graph.
A complete graph has an edge between every pair of vertices.

=item complement_graph

=item complement

    my $c = $g->complement_graph;

Create a complement graph that has the same vertices as the original graph.
A complement graph has an edge (u,v) if and only if the original
graph does not have edge (u,v).

=item subgraph

   my $c = $g->subgraph(\@src, \@dst);
   my $c = $g->subgraph(\@src);

Creates a subgraph of a given graph.  The created subgraph has the
same graph properties (directedness, and so forth) as the original
graph, but none of the attributes (graph, vertex, or edge).

A vertex is added to the subgraph if it is in the original graph.

An edge is added to the subgraph if there is an edge in the original
graph that starts from the C<src> set of vertices and ends in the
C<dst> set of vertices.

You can leave out C<dst> in which case C<dst> is assumed to be the same:
this is called a I<vertex-induced subgraph>.

=back

See also L</random_graph> for a random constructor.

=head2 Basics

=over 4

=item add_vertex

    $g->add_vertex($v)

Add the vertex to the graph.  Returns the graph.

By default idempotent, but a graph can be created I<countvertexed>.

A vertex is also known as a I<node>.

Adding C<undef> as vertex is not allowed.

Note that unless you have isolated vertices (or I<countvertexed>
vertices), you do not need to explicitly use C<add_vertex> since
L</add_edge> will implicitly add its vertices.

=item add_edge

    $g->add_edge($u, $v)

Add the edge to the graph.  Implicitly first adds the vertices if the
graph does not have them.  Returns the graph.

By default idempotent, but a graph can be created I<countedged>.

An edge is also known as an I<arc>.

For a hypergraph, the interface is different: if undirected, give a list
of one or more vertices. If directed, give a list of two array-refs of
vertices. As conceptually these are sets, the ordering of the contents
is not important.

=item has_vertex

    $g->has_vertex($v)

Return true if the vertex exists in the graph, false otherwise.

=item has_edge

    $g->has_edge($u, $v)

Return true if the edge exactly as specified exists in the graph,
false otherwise.

Hyperedges which contain all the given vertices (in the right places
if directed), but which also have others will not match.

=item any_edge

    $g->any_edge($u, $v)

Return true if any edge in the graph connects the first vertex to the second,
false otherwise. Note this is a different question from C<has_edge>. It
will give the same result as checking the first vertex's L</successors>
to see if any match the second one, but in a more efficient way.

=item delete_vertex

    $g->delete_vertex($v)

Delete the vertex from the graph.  Returns the graph, even if the
vertex did not exist in the graph.

If the graph has been created I<multivertexed> or I<countvertexed>
and a vertex has been added multiple times, the vertex will require
at least an equal number of deletions to become completely deleted.

=item delete_vertices

    $g->delete_vertices($v1, $v2, ...)

Delete the vertices from the graph.  Returns the graph, even if none
of the vertices existed in the graph.

If the graph has been created I<multivertexed> or I<countvertexed>
and a vertex has been added multiple times, the vertex will require
at least an equal number of deletions to become completely deleted.

=item delete_edge

    $g->delete_edge($u, $v)

Delete the edge from the graph.  Returns the graph, even
if the edge did not exist in the graph.

If the graph has been created I<multiedged> or I<countedged>
and an edge has been added multiple times, the edge will require
at least an equal number of deletions to become completely deleted.

=item delete_edges

    $g->delete_edges($u1, $v1, $u2, $v2, ...)

Delete the edges from the graph.  Returns the graph, even if none
of the edges existed in the graph.

If the graph has been created I<multiedged> or I<countedged>
and an edge has been added multiple times, the edge will require
at least an equal number of deletions to become completely deleted.

=back

=head2 Displaying

Graphs have stringification overload, so you can do things like

    print "The graph is $g\n"

One-way (directed, unidirected) edges are shown as '-', two-way
(undirected, bidirected) edges are shown as '='.  If you want to,
you can call the stringification via the method

=over 4

=item stringify

=back

=head2 Boolean

Graphs have boolifying overload, so you can do things like

    if ($g) { print "The graph is: $g\n" }

which works even if the graph is empty.  In fact, the boolify
always returns true.  If you want to test for example for vertices,
test for vertices.

=over 4

=item boolify

=back

=head2 Comparing

Testing for equality can be done either by the overloaded C<eq>
operator

    $g eq "a-b,a-c,d"

or by the method

=over 4

=item eq

    $g->eq("a-b,a-c,d")

=back

The equality testing compares the stringified forms, and therefore it
assumes total equality, not isomorphism: all the vertices must be
named the same, and they must have identical edges between them.

For unequality there are correspondingly the overloaded C<ne>
operator and the method

=over 4

=item ne

    $g->ne("a-b,a-c,d")

=back

See also L</Isomorphism>.

=head2 Paths and Cycles

Paths and cycles are simple extensions of edges: paths are edges
starting from where the previous edge ended, and cycles are paths
returning back to the start vertex of the first edge.

=over 4

=item add_path

   $g->add_path($a, $b, $c, ..., $x, $y, $z)

Add the edges $a-$b, $b-$c, ..., $x-$y, $y-$z to the graph.
Returns the graph.

=item has_path

   $g->has_path($a, $b, $c, ..., $x, $y, $z)

Return true if the graph has all the edges $a-$b, $b-$c, ..., $x-$y, $y-$z,
false otherwise.

=item delete_path

   $g->delete_path($a, $b, $c, ..., $x, $y, $z)

Delete all the edges $a-$b, $b-$c, ..., $x-$y, $y-$z
(regardless of whether they exist or not).  Returns the graph.

=item add_cycle

   $g->add_cycle($a, $b, $c, ..., $x, $y, $z)

Add the edges $a-$b, $b-$c, ..., $x-$y, $y-$z, and $z-$a to the graph.
Returns the graph.

=item has_cycle

=item has_this_cycle

   $g->has_cycle($a, $b, $c, ..., $x, $y, $z)

Return true if the graph has all the edges $a-$b, $b-$c, ..., $x-$y, $y-$z,
and $z-$a, false otherwise.

B<NOTE:> This does not I<detect> cycles, see L</has_a_cycle> and
L</find_a_cycle>.

=item delete_cycle

   $g->delete_cycle($a, $b, $c, ..., $x, $y, $z)

Delete all the edges $a-$b, $b-$c, ..., $x-$y, $y-$z, and $z-$a
(regardless of whether they exist or not).  Returns the graph.

=item has_a_cycle

   $g->has_a_cycle

Returns true if the graph has a cycle, false if not.

=item find_a_cycle

   $g->find_a_cycle

Returns a cycle if the graph has one (as a list of vertices), an empty
list if no cycle can be found.

Note that this just returns the vertices of I<a cycle>: not any
particular cycle, just the first one it finds.  A repeated call
might find the same cycle, or it might find a different one, and
you cannot call this repeatedly to find all the cycles.

=back

=head2 Graph Types

=over 4

=item is_simple_graph

    $g->is_simple_graph

Return true if the graph has no multiedges, false otherwise.

=item is_pseudo_graph

    $g->is_pseudo_graph

Return true if the graph has any multiedges or any self-loops,
false otherwise.

=item is_multi_graph

    $g->is_multi_graph

Return true if the graph has any multiedges but no self-loops,
false otherwise.

=item is_directed_acyclic_graph

=item is_dag

    $g->is_directed_acyclic_graph
    $g->is_dag

Return true if the graph is directed and acyclic, false otherwise.

=item is_cyclic

    $g->is_cyclic

Return true if the graph is cyclic (contains at least one cycle).
(This is identical to C<has_a_cycle>.)

To find at least one such cycle, see L</find_a_cycle>.

=item is_acyclic

Return true if the graph is acyclic (does not contain any cycles).

=back

To find a cycle, use L</find_a_cycle>.

=head2 Transitivity

=over 4

=item is_transitive

    $g->is_transitive

Return true if the graph is transitive, false otherwise.

=item TransitiveClosure_Floyd_Warshall

=item transitive_closure

    $tcg = $g->TransitiveClosure_Floyd_Warshall

Return the transitive closure graph of the graph.

=item transitive_closure_matrix_clear_cache

    $g->transitive_closure_matrix_clear_cache

See L</"Clearing cached results">.

=back

You can query the reachability from $u to $v with

=over 4

=item is_reachable

    $tcg->is_reachable($u, $v)

=back

See L<Graph::TransitiveClosure> for more information about creating
and querying transitive closures.

With

=over 4

=item transitive_closure_matrix

   $tcm = $g->transitive_closure_matrix;

=back

you can (create if not existing and) query the transitive closure
matrix that underlies the transitive closure graph.  See
L<Graph::TransitiveClosure::Matrix> for more information.

=head2 Mutators

=over 4

=item add_vertices

    $g->add_vertices('d', 'e', 'f')

Add zero or more vertices to the graph.  Returns the graph.

=item add_edges

    $g->add_edges(['d', 'e'], ['f', 'g'])
    $g->add_edges(qw(d e f g));

Add zero or more edges to the graph.  The edges are specified as
a list of array references, or as a list of vertices where the
even (0th, 2nd, 4th, ...) items are start vertices and the odd
(1st, 3rd, 5th, ...) are the corresponding end vertices.
Returns the graph.

For a hypergraph, each item in this list must be an array-ref of arguments
suitable for C<add_edge> - so for undirected, of vertices;
for directed, of two array-refs of vertices.

=item rename_vertex

    $g->rename_vertex('d', 'e')

Renames a vertex. It retains all of its edges. Throws exception if
doesn't exist.

Returns the graph.

=item rename_vertices

    $g->rename_vertices(sub { uc $_[0] })

Calls a function for each vertex-name, renaming it to the return value.

Returns the graph.

=item ingest

    $g->ingest($g2)

Ingests all the vertices and edges of the given graph, including
attributes. Returns the ingesting graph.

=back

=head2 Accessors

=over 4

=item is_directed

=item directed

    $g->is_directed()
    $g->directed()

Return true if the graph is directed, false otherwise.

=item is_undirected

=item undirected

    $g->is_undirected()
    $g->undirected()

Return true if the graph is undirected, false otherwise.

=item is_refvertexed

=item is_refvertexed_stringified

=item refvertexed

=item refvertexed_stringified

Return true if the graph can handle references (including Perl objects)
as vertices.

=item vertices

    my $V = $g->vertices
    my @V = $g->vertices

In scalar context, return the number of vertices in the graph.
In list context, return the vertices, in no particular order.

=item has_vertices

    $g->has_vertices()

Return true if the graph has any vertices, false otherwise.

=item edges

    my $E = $g->edges
    my @E = $g->edges

In scalar context, return the number of edges in the graph.
In list context, return the edges, in no particular order.
I<The edges are returned as anonymous arrays listing the vertices.>

=item has_edges

    $g->has_edges()

Return true if the graph has any edges, false otherwise.

=item is_connected

    $g->is_connected

For an undirected graph, return true if the graph is connected, false
otherwise.  Being connected means that from every vertex it is possible
to reach every other vertex.

If the graph has been created with a true C<unionfind> parameter,
the time complexity is (essentially) O(V), otherwise O(V log V).

See also L</connected_components>, L</connected_component_by_index>,
L</connected_component_by_vertex>, and L</same_connected_components>,
and L</biconnectivity>.

For directed graphs, see L</is_strongly_connected>
and L</is_weakly_connected>.

=item connected_components

    @cc = $g->connected_components()

For an undirected graph, returns the vertices of the connected
components of the graph as a list of anonymous arrays.  The ordering
of the anonymous arrays or the ordering of the vertices inside the
anonymous arrays (the components) is undefined.

For directed graphs, see L</strongly_connected_components>
and L</weakly_connected_components>.

=item connected_component_by_vertex

    $i = $g->connected_component_by_vertex($v)

For an undirected graph, return an index identifying the connected
component the vertex belongs to, the indexing starting from zero.

For the inverse, see L</connected_component_by_index>.

If the graph has been created with a true C<unionfind> parameter,
the time complexity is (essentially) O(1), otherwise O(V log V).

See also L</biconnectivity>.

For directed graphs, see L</strongly_connected_component_by_vertex>
and L</weakly_connected_component_by_vertex>.

=item connected_component_by_index

    @v = $g->connected_component_by_index($i)

For an undirected graph, return the vertices of the ith connected
component, the indexing starting from zero.  The order of vertices is
undefined, while the order of the connected components is same as from
connected_components().

For the inverse, see L</connected_component_by_vertex>.

For directed graphs, see L</strongly_connected_component_by_index>
and L</weakly_connected_component_by_index>.

=item same_connected_components

    $g->same_connected_components($u, $v, ...)

For an undirected graph, return true if the vertices are in the same
connected component.

If the graph has been created with a true C<unionfind> parameter,
the time complexity is (essentially) O(1), otherwise O(V log V).

For directed graphs, see L</same_strongly_connected_components>
and L</same_weakly_connected_components>.

=item connected_graph

    $cg = $g->connected_graph

For an undirected graph, return its connected graph.

=item connectivity_clear_cache

    $g->connectivity_clear_cache

See L</"Clearing cached results">.

See L</"Connected Graphs and Their Components"> for further discussion.

=item biconnectivity

    my ($ap, $bc, $br) = $g->biconnectivity

For an undirected graph, return the various biconnectivity components
of the graph: the articulation points (cut vertices), biconnected
components, and bridges.

Note: currently only handles connected graphs.

=item is_biconnected

   $g->is_biconnected

For an undirected graph, return true if the graph is biconnected
(if it has no articulation points, also known as cut vertices).

=item is_edge_connected

   $g->is_edge_connected

For an undirected graph, return true if the graph is edge-connected
(if it has no bridges).

Note: more precisely, this would be called is_edge_biconnected,
since there is a more general concept of being k-connected. 

=item is_edge_separable

   $g->is_edge_separable

For an undirected graph, return true if the graph is edge-separable
(if it has bridges).

Note: more precisely, this would be called is_edge_biseparable,
since there is a more general concept of being k-connected. 

=item articulation_points

=item cut_vertices

   $g->articulation_points

For an undirected graph, return the articulation points (cut vertices)
of the graph as a list of vertices.  The order is undefined.

=item biconnected_components

   $g->biconnected_components

For an undirected graph, return the biconnected components of the
graph as a list of anonymous arrays of vertices in the components.
The ordering of the anonymous arrays or the ordering of the vertices
inside the anonymous arrays (the components) is undefined.  Also note
that one vertex can belong to more than one biconnected component.

=item biconnected_component_by_vertex

   $i = $g->biconnected_component_by_index($v)

For an undirected graph, return the indices identifying the biconnected
components the vertex belongs to, the indexing starting from zero.
The order of of the components is undefined.

For the inverse, see L</connected_component_by_index>.

For directed graphs, see L</strongly_connected_component_by_index>
and L</weakly_connected_component_by_index>.

=item biconnected_component_by_index

   @v = $g->biconnected_component_by_index($i)

For an undirected graph, return the vertices in the ith biconnected
component of the graph as an anonymous arrays of vertices in the
component.  The ordering of the vertices within a component is
undefined.  Also note that one vertex can belong to more than one
biconnected component.

=item same_biconnected_components

    $g->same_biconnected_components($u, $v, ...)

For an undirected graph, return true if the vertices are in the same
biconnected component.

=item biconnected_graph

    $bcg = $g->biconnected_graph

For an undirected graph, return its biconnected graph.

See L</"Connected Graphs and Their Components"> for further discussion.

=item bridges

   $g->bridges

For an undirected graph, return the bridges of the graph as a list of
anonymous arrays of vertices in the bridges.  The order of bridges and
the order of vertices in them is undefined.

=item biconnectivity_clear_cache

    $g->biconnectivity_clear_cache

See L</"Clearing cached results">.

=item strongly_connected

=item is_strongly_connected

    $g->is_strongly_connected

For a directed graph, return true if the directed graph is strongly
connected, false if not.

See also L</is_weakly_connected>.

For undirected graphs, see L</is_connected>, or L</is_biconnected>.

=item strongly_connected_component_by_vertex

    $i = $g->strongly_connected_component_by_vertex($v)

For a directed graph, return an index identifying the strongly
connected component the vertex belongs to, the indexing starting from
zero.

For the inverse, see L</strongly_connected_component_by_index>.

See also L</weakly_connected_component_by_vertex>.

For undirected graphs, see L</connected_components> or
L</biconnected_components>.

=item strongly_connected_component_by_index

    @v = $g->strongly_connected_component_by_index($i)

For a directed graph, return the vertices of the ith connected
component, the indexing starting from zero.  The order of vertices
within a component is undefined, while the order of the connected
components is as from strongly_connected_components().

For the inverse, see L</strongly_connected_component_by_vertex>.

For undirected graphs, see L</weakly_connected_component_by_index>.

=item same_strongly_connected_components

    $g->same_strongly_connected_components($u, $v, ...)

For a directed graph, return true if the vertices are in the same
strongly connected component.

See also L</same_weakly_connected_components>.

For undirected graphs, see L</same_connected_components> or
L</same_biconnected_components>.

=item strong_connectivity_clear_cache

    $g->strong_connectivity_clear_cache

See L</"Clearing cached results">.

=item weakly_connected

=item is_weakly_connected

    $g->is_weakly_connected

For a directed graph, return true if the directed graph is weakly
connected, false if not.

Weakly connected graph is also known as I<semiconnected> graph.

See also L</is_strongly_connected>.

For undirected graphs, see L</is_connected> or L</is_biconnected>.

=item weakly_connected_components

    @wcc = $g->weakly_connected_components()

For a directed graph, returns the vertices of the weakly connected
components of the graph as a list of anonymous arrays.  The ordering
of the anonymous arrays or the ordering of the vertices inside the
anonymous arrays (the components) is undefined.

See also L</strongly_connected_components>.

For undirected graphs, see L</connected_components> or
L</biconnected_components>.

=item weakly_connected_component_by_vertex

    $i = $g->weakly_connected_component_by_vertex($v)

For a directed graph, return an index identifying the weakly connected
component the vertex belongs to, the indexing starting from zero.

For the inverse, see L</weakly_connected_component_by_index>.

For undirected graphs, see L</connected_component_by_vertex>
and L</biconnected_component_by_vertex>.

=item weakly_connected_component_by_index

    @v = $g->weakly_connected_component_by_index($i)

For a directed graph, return the vertices of the ith weakly connected
component, the indexing starting zero.  The order of vertices within
a component is undefined, while the order of the weakly connected
components is same as from weakly_connected_components().

For the inverse, see L</weakly_connected_component_by_vertex>.

For undirected graphs, see L<connected_component_by_index>
and L<biconnected_component_by_index>.

=item same_weakly_connected_components

    $g->same_weakly_connected_components($u, $v, ...)

Return true if the vertices are in the same weakly connected component.

=item weakly_connected_graph

    $wcg = $g->weakly_connected_graph

For a directed graph, return its weakly connected graph.

For undirected graphs, see L</connected_graph> and L</biconnected_graph>.

=item strongly_connected_components

   my @scc = $g->strongly_connected_components;

For a directed graph, return the strongly connected components as a
list of anonymous arrays.  The elements in the anonymous arrays are
the vertices belonging to the strongly connected component; both the
elements and the components are in no particular order.

Note that strongly connected components can have single-element
components even without self-loops: if a vertex is any of I<isolated>,
I<sink>, or a I<source>, the vertex is alone in its own strong component.

See also L</weakly_connected_components>.

For undirected graphs, see L</connected_components>,
or see L</biconnected_components>.

=item strongly_connected_graph

   my $scg = $g->strongly_connected_graph;

See L</"Connected Graphs and Their Components"> for further discussion.

Strongly connected graphs are also known as I<kernel graphs>.

See also L</weakly_connected_graph>.

For undirected graphs, see L</connected_graph>, or L</biconnected_graph>.

=item is_sink_vertex

    $g->is_sink_vertex($v)

Return true if the vertex $v is a sink vertex, false if not.  A sink
vertex is defined as a vertex with predecessors but no successors:
this definition means that isolated vertices are not sink vertices.
If you want also isolated vertices, use is_successorless_vertex().

=item is_source_vertex

    $g->is_source_vertex($v)

Return true if the vertex $v is a source vertex, false if not.  A source
vertex is defined as a vertex with successors but no predecessors:
the definition means that isolated vertices are not source vertices.
If you want also isolated vertices, use is_predecessorless_vertex().

=item is_successorless_vertex

    $g->is_successorless_vertex($v)

Return true if the vertex $v has no successors (no edges
leaving the vertex), false if it has.

Isolated vertices will return true: if you do not want this,
use is_sink_vertex().

=item is_successorful_vertex

    $g->is_successorful_vertex($v)

Return true if the vertex $v has successors, false if not.

=item is_predecessorless_vertex

    $g->is_predecessorless_vertex($v)

Return true if the vertex $v has no predecessors (no edges
entering the vertex), false if it has.

Isolated vertices will return true: if you do not want this,
use is_source_vertex().

=item is_predecessorful_vertex

    $g->is_predecessorful_vertex($v)

Return true if the vertex $v has predecessors, false if not.

=item is_isolated_vertex

    $g->is_isolated_vertex($v)

Return true if the vertex $v is an isolated vertex: no successors
and no predecessors.

=item is_interior_vertex

    $g->is_interior_vertex($v)

Return true if the vertex $v is an interior vertex: both successors
and predecessors.

=item is_exterior_vertex

    $g->is_exterior_vertex($v)

Return true if the vertex $v is an exterior vertex: has either no
successors or no predecessors, or neither.

=item is_self_loop_vertex

    $g->is_self_loop_vertex($v)

Return true if the vertex $v is a self loop vertex: has an edge
from itself to itself.

For an undirected hypergraph, only true if an edge has the vertex as
its sole participant.

=item sink_vertices

    @v = $g->sink_vertices()

Return the sink vertices of the graph.
In scalar context return the number of sink vertices.
See L</is_sink_vertex> for the definition of a sink vertex.

=item source_vertices

    @v = $g->source_vertices()

Return the source vertices of the graph.
In scalar context return the number of source vertices.
See L</is_source_vertex> for the definition of a source vertex.

=item successorful_vertices

    @v = $g->successorful_vertices()

Return the successorful vertices of the graph.
In scalar context return the number of successorful vertices.

=item successorless_vertices

    @v = $g->successorless_vertices()

Return the successorless vertices of the graph.
In scalar context return the number of successorless vertices.

=item successors

    @s = $g->successors($v)

Return the immediate successor vertices of the vertex.

See also L</all_successors>, L</all_neighbours>, and L</all_reachable>.

=item all_successors

    @s = $g->all_successors(@v)

For a directed graph, returns all successor vertices of the argument
vertices, recursively.

For undirected graphs, see L</all_neighbours> and L</all_reachable>.

See also L</successors>, L</successors_by_radius>.

=item successors_by_radius

    @s = $g->successors_by_radius(@v, $radius)

For a directed graph, returns all successor vertices of the argument
vertices, recursively.

For undirected graphs, see L</all_neighbours> and L</all_reachable>.

See also L</successors>, L</successors_by_radius>.

=item neighbors

=item neighbours

    @n = $g->neighbours($v)

Return the neighboring/neighbouring vertices.  Also known as the
I<adjacent vertices>.

See also L</all_neighbours> L</all_reachable>, and L</neighbours_by_radius>.

=item all_neighbors

=item all_neighbours

   @n = $g->all_neighbours(@v)

Return the neighboring/neighbouring vertices of the argument vertices,
recursively.  For a directed graph, recurses up predecessors and down
successors.  For an undirected graph, returns all the vertices
reachable from the argument vertices: equivalent to C<all_reachable>.

See also L</neighbours>, L</all_reachable>, and L</neighbours_by_radius>.

=item neighbors_by_radius

=item neighbours_by_radius

   @n = $g->neighbours_by_radius(@v, $radius)

Return the neighboring/neighbouring vertices of the argument vertices,
recursively, out to the given radius.

=item all_reachable

    @r = $g->all_reachable(@v)

Return all the vertices reachable from the argument vertices,
recursively. For a directed graph, equivalent to C<all_successors>.
For an undirected graph, equivalent to C<all_neighbours>.  The argument
vertices are not included in the results unless there are explicit
self-loops.

See also L</neighbours>, L</all_neighbours>, L</all_successors>, and
L</reachable_by_radius>.

=item reachable_by_radius

    @r = $g->reachable_by_radius(@v, $radius)

Return all the vertices reachable from the argument vertices,
recursively, out to the given radius.

=item predecessorful_vertices

    @v = $g->predecessorful_vertices()

Return the predecessorful vertices of the graph.
In scalar context return the number of predecessorful vertices.

=item predecessorless_vertices

    @v = $g->predecessorless_vertices()

Return the predecessorless vertices of the graph.
In scalar context return the number of predecessorless vertices.

=item predecessors

    @p = $g->predecessors($v)

Return the immediate predecessor vertices of the vertex.

See also L</all_predecessors>, L</all_neighbours>, and L</all_reachable>.

=item all_predecessors

    @p = $g->all_predecessors(@v)

For a directed graph, returns all predecessor vertices of the argument
vertices, recursively.

For undirected graphs, see L</all_neighbours> and L</all_reachable>.

See also L</predecessors>, L</predecessors_by_radius>.

=item predecessors_by_radius

    @p = $g->predecessors_by_radius(@v, $radius)

For a directed graph, returns all predecessor vertices of the argument
vertices, recursively, out to the given radius.

=item isolated_vertices

    @v = $g->isolated_vertices()

Return the isolated vertices of the graph.
In scalar context return the number of isolated vertices.
See L</is_isolated_vertex> for the definition of an isolated vertex.

=item interior_vertices

    @v = $g->interior_vertices()

Return the interior vertices of the graph.
In scalar context return the number of interior vertices.
See L</is_interior_vertex> for the definition of an interior vertex.

=item exterior_vertices

    @v = $g->exterior_vertices()

Return the exterior vertices of the graph.
In scalar context return the number of exterior vertices.
See L</is_exterior_vertex> for the definition of an exterior vertex.

=item self_loop_vertices

    @v = $g->self_loop_vertices()

Return the self-loop vertices of the graph.
In scalar context return the number of self-loop vertices.
See L</is_self_loop_vertex> for the definition of a self-loop vertex.

=item as_hashes

    ($nodes, $edges) = $g->as_hashes

Return hash-refs which map vertices to their attributes, and for edges,
a two-level hash mapping the predecessor to its successors, mapped to
the attributes.

If C<multivertexed> is true, the vertices hash will have the second-level
values be the multivertex's ID, and the third level will be attributes
as above.

If C<multiedged> is true, similar will be true for the edges hash.

For a hypergraph, the edges will instead be an array-ref of hashes with
a key of C<attributes>, value a hash-ref (if C<multiedged>, two-level
as above). Then with values of array-refs of vertex-names, for undirected:

=over

=item vertices

=back

And directed:

=over

=item predecessors

=item successors

=back

=back

=head2 Connected Graphs and Their Components

In this discussion I<connected graph> refers to any of
I<connected graphs>, I<biconnected graphs>, and I<strongly
connected graphs>.

B<NOTE>: if the vertices of the original graph are Perl objects,
(in other words, references, so you must be using C<refvertexed>) 
the vertices of the I<connected graph> are NOT by default usable
as Perl objects because they are blessed into a package with
a rather unusable name.

By default, the vertex names of the I<connected graph> are formed from
the names of the vertices of the original graph by (alphabetically
sorting them and) concatenating their names with C<+>.  The vertex
attribute C<subvertices> is also used to store the list (as an array
reference) of the original vertices.  To change the 'supercomponent'
vertex names and the whole logic of forming these supercomponents
use the C<super_component>) option to the method calls:

  $g->connected_graph(super_component => sub { ... })
  $g->biconnected_graph(super_component => sub { ... })
  $g->strongly_connected_graph(super_component => sub { ... })

The subroutine reference gets the 'subcomponents' (the vertices of the
original graph) as arguments, and it is supposed to return the new
supercomponent vertex, the "stringified" form of which is used as the
vertex name.

=head2 Degree

A vertex has a degree based on the number of incoming and outgoing edges.
This really makes sense only for directed graphs.

=over 4

=item degree

=item vertex_degree

    $d = $g->degree($v)
    $d = $g->vertex_degree($v)

For directed graphs: the in-degree minus the out-degree at the vertex.

For undirected graphs: the number of edges at the vertex  (identical to
C<in_degree()>, C<out_degree()>).

=item in_degree

    $d = $g->in_degree($v)

For directed graphs: the number of incoming edges at the vertex.

For undirected graphs: the number of edges at the vertex (identical to
C<out_degree()>, C<degree()>, C<vertex_degree()>).

=item out_degree

    $o = $g->out_degree($v)

For directed graphs: The number of outgoing edges at the vertex.

For undirected graphs: the number of edges at the vertex (identical to
C<in_degree()>, C<degree()>, C<vertex_degree()>).

=back

Related methods are

=over 4

=item edges_at

    @e = $g->edges_at($v)

The union of edges from, and edges to, the vertex.

=item edges_from

    @e = $g->edges_from($v)

The edges leaving the vertex.

=item edges_to

    @e = $g->edges_to($v)

The edges entering the vertex.

=back

=head2 Counted Vertices

I<Counted vertices> are vertices with more than one instance, normally
adding vertices is idempotent.  To enable counted vertices on a graph,
give the C<countvertexed> parameter a true value

    use Graph;
    my $g = Graph->new(countvertexed => 1);

To find out how many times the vertex has been added:

=over 4

=item get_vertex_count

    my $c = $g->get_vertex_count($v);

Return the count of the vertex, or undef if the vertex does not exist.

=back

=head2 Multiedges, Multivertices, Multigraphs

I<Multiedges> are edges with more than one "life", meaning that one
has to delete them as many times as they have been added.  Normally
adding edges is idempotent (in other words, adding edges more than
once makes no difference).

There are two kinds or degrees of creating multiedges and multivertices.
The two kinds are mutually exclusive.

The weaker kind is called I<counted>, in which the edge or vertex has
a count on it: add operations increase the count, and delete
operations decrease the count, and once the count goes to zero, the
edge or vertex is deleted.  If there are attributes, they all are
attached to the same vertex.  You can think of this as the graph
elements being I<refcounted>, or I<reference counted>, if that sounds
more familiar.

The stronger kind is called (true) I<multi>, in which the edge or vertex
really has multiple separate identities, so that you can for example
attach different attributes to different instances.

To enable multiedges on a graph:

    use Graph;
    my $g0 = Graph->new(countedged => 1);
    my $g0 = Graph->new(multiedged => 1);

Similarly for vertices

    use Graph;
    my $g1 = Graph->new(countvertexed => 1);
    my $g1 = Graph->new(multivertexed => 1);

You can test for these by

=over 4

=item is_countedged

=item countedged

    $g->is_countedged
    $g->countedged

Return true if the graph is countedged.

=item is_countvertexed

=item countvertexed

    $g->is_countvertexed
    $g->countvertexed

Return true if the graph is countvertexed.

=item is_multiedged

=item multiedged

    $g->is_multiedged
    $g->multiedged

Return true if the graph is multiedged.

=item is_multivertexed

=item multivertexed

    $g->is_multivertexed
    $g->multivertexed

Return true if the graph is multivertexed.

=back

A multiedged (either the weak kind or the strong kind) graph is
a I<multigraph>, for which you can test with C<is_multi_graph()>.

B<NOTE>: The various graph algorithms do not in general work well with
multigraphs (they often assume I<simple graphs>, that is, no
multiedges or loops), and no effort has been made to test the
algorithms with multigraphs.

vertices() and edges() will return the multiple elements: if you want
just the unique elements, use

=over 4

=item unique_vertices

=item unique_edges

    @uv = $g->unique_vertices; # unique
    @mv = $g->vertices;        # possible multiples
    @ue = $g->unique_edges;
    @me = $g->edges;

=back

If you are using (the stronger kind of) multielements, you should use
the I<by_id> variants:

=over 4

=item add_vertex_by_id

=item has_vertex_by_id

=item delete_vertex_by_id

=item add_edge_by_id

=item has_edge_by_id

=item delete_edge_by_id

=back

    $g->add_vertex_by_id($v, $id)
    $g->has_vertex_by_id($v, $id)
    $g->delete_vertex_by_id($v, $id)

    $g->add_edge_by_id($u, $v, $id)
    $g->has_edge_by_id($u, $v, $id)
    $g->delete_edge_by_id($u, $v, $id)

These interfaces only apply to multivertices and multiedges.
When you delete the last vertex/edge in a multivertex/edge, the whole
vertex/edge is deleted.  You can use add_vertex()/add_edge() on
a multivertex/multiedge graph, in which case an id is generated
automatically.  To find out which the generated id was, you need
to use

=over 4

=item add_vertex_get_id

=item add_edge_get_id

=back

    $idv = $g->add_vertex_get_id($v)
    $ide = $g->add_edge_get_id($u, $v)

To return all the ids of vertices/edges in a multivertex/multiedge, use

=over 4

=item get_multivertex_ids

=item get_multiedge_ids

=back

    $g->get_multivertex_ids($v)
    $g->get_multiedge_ids($u, $v)

The ids are returned in random order.

To find out how many times the edge has been added (this works for
either kind of multiedges):

=over 4

=item get_edge_count

    my $c = $g->get_edge_count($u, $v);

Return the count (the "countedness") of the edge, or undef if the
edge does not exist.

=back

The following multi-entity utility functions exist, mirroring
the non-multi vertices and edges:

=over 4

=item add_weighted_edge_by_id

=item add_weighted_edges_by_id

=item add_weighted_path_by_id

=item add_weighted_vertex_by_id

=item add_weighted_vertices_by_id

=item delete_edge_weight_by_id

=item delete_vertex_weight_by_id

=item get_edge_weight_by_id

=item get_vertex_weight_by_id

=item has_edge_weight_by_id

=item has_vertex_weight_by_id

=item set_edge_weight_by_id

=item set_vertex_weight_by_id

=back

=head2 Topological Sort

=over 4

=item topological_sort

=item toposort

    my @ts = $g->topological_sort;

Return the vertices of the graph sorted topologically.  Note that
there may be several possible topological orderings; one of them
is returned.

If the graph contains a cycle, a fatal error is thrown, you
can either use C<eval> to trap that, or supply the C<empty_if_cyclic>
argument with a true value

    my @ts = $g->topological_sort(empty_if_cyclic => 1);

in which case an empty array is returned if the graph is cyclic.

=back

=head2 Minimum Spanning Trees (MST)

Minimum Spanning Trees or MSTs are tree subgraphs derived from an
undirected graph.  MSTs "span the graph" (covering all the vertices)
using as lightly weighted (hence the "minimum") edges as possible.

=over 4

=item MST_Kruskal

    $mstg = $g->MST_Kruskal;

Returns the Kruskal MST of the graph.

=item MST_Prim

    $mstg = $g->MST_Prim(%opt);

Returns the Prim MST of the graph.

You can choose the first vertex with $opt{ first_root }.

=item MST_Dijkstra

=item minimum_spanning_tree

    $mstg = $g->MST_Dijkstra;
    $mstg = $g->minimum_spanning_tree;

Aliases for MST_Prim.

=back

=head2 Single-Source Shortest Paths (SSSP)

Single-source shortest paths, also known as Shortest Path Trees
(SPTs).  For either a directed or an undirected graph, return a (tree)
subgraph that from a single start vertex (the "single source") travels
the shortest possible paths (the paths with the lightest weights) to
all the other vertices.  Note that the SSSP is neither reflexive (the
shortest paths do not include the zero-length path from the source
vertex to the source vertex) nor transitive (the shortest paths do not
include transitive closure paths).  If no weight is defined for an
edge, 1 (one) is assumed.

=over 4

=item SPT_Dijkstra

    $sptg = $g->SPT_Dijkstra($root)
    $sptg = $g->SPT_Dijkstra(%opt)

Return as a graph the the single-source shortest paths of the graph
using Dijkstra's algorithm.  The graph cannot contain negative edges
(negative edges cause the algorithm to abort with an error message
C<Graph::SPT_Dijkstra: edge ... is negative>).

You can choose the first vertex of the result with either a single
vertex argument or with $opt{ first_root }, otherwise a random vertex
is chosen.

B<NOTE>: note that all the vertices might not be reachable from the
selected (explicit or random) start vertex.

B<NOTE>: after the first reachable tree from the first start vertex
has been finished, and if there still are unvisited vertices,
SPT_Dijkstra will keep on selecting unvisited vertices.

The next roots (in case the first tree doesn't visit all the vertices)
can be chosen by setting one of the following options to true:
C<next_root>, C<next_alphabetic>, C<next_numeric>, C<next_random>.

The C<next_root> is the most customizable: the value needs to be
a subroutine reference which will receive the graph and the unvisited
vertices as hash reference.  If you want to only visit the first tree,
use C<next_root => sub { undef }>.  The rest of these options are
booleans.  If none of them are true, a random unvisited vertex will be
selected.

The first start vertex is available as the graph attribute
C<SPT_Dijkstra_root>).

The result weights of vertices can be retrieved from the result graph by

	my $w = $sptg->get_vertex_attribute($v, 'weight');

The predecessor vertex of a vertex in the result graph
can be retrieved by

	my $u = $sptg->get_vertex_attribute($v, 'p');

("A successor vertex" cannot be retrieved as simply because a single
vertex can have several successors.  You can first find the
C<neighbors()> vertices and then remove the predecessor vertex.)

If you want to find the shortest path between two vertices,
see L</SP_Dijkstra>.

=item SSSP_Dijkstra

=item single_source_shortest_paths

Aliases for SPT_Dijkstra.

=item SP_Dijkstra

    @path = $g->SP_Dijkstra($u, $v)

Return the vertices in the shortest path in the graph $g between the
two vertices $u, $v.  If no path can be found, an empty list is returned.

Uses SPT_Dijkstra().

=item SPT_Dijkstra_clear_cache

    $g->SPT_Dijkstra_clear_cache

See L</"Clearing cached results">.

=item SPT_Bellman_Ford

    $sptg = $g->SPT_Bellman_Ford(%opt)

Return as a graph the single-source shortest paths of the graph using
Bellman-Ford's algorithm.  The graph can contain negative edges but
not negative cycles (negative cycles cause the algorithm to abort
with an error message C<Graph::SPT_Bellman_Ford: negative cycle exists>).

You can choose the start vertex of the result with either a single
vertex argument or with $opt{ first_root }, otherwise a random vertex
is chosen.

B<NOTE>: note that all the vertices might not be reachable from the
selected (explicit or random) start vertex.

The start vertex is available as the graph attribute
C<SPT_Bellman_Ford_root>).

The result weights of vertices can be retrieved from the result graph by

	my $w = $sptg->get_vertex_attribute($v, 'weight');

The predecessor vertex of a vertex in the result graph
can be retrieved by

	my $u = $sptg->get_vertex_attribute($v, 'p');

("A successor vertex" cannot be retrieved as simply because a single
vertex can have several successors.  You can first find the
C<neighbors()> vertices and then remove the predecessor vertex.)

If you want to find the shortest path between two vertices,
see L</SP_Bellman_Ford>.

=item SSSP_Bellman_Ford

Alias for SPT_Bellman_Ford.

=item SP_Bellman_Ford

    @path = $g->SP_Bellman_Ford($u, $v)

Return the vertices in the shortest path in the graph $g between the
two vertices $u, $v.  If no path can be found, an empty list is returned.

Uses SPT_Bellman_Ford().

=item SPT_Bellman_Ford_clear_cache

    $g->SPT_Bellman_Ford_clear_cache

See L</"Clearing cached results">.

=back

=head2 All-Pairs Shortest Paths (APSP)

For either a directed or an undirected graph, return the APSP object
describing all the possible paths between any two vertices of the
graph.  If no weight is defined for an edge, 1 (one) is assumed.

Note that weight of 0 (zero) does not mean do not use this edge, it
means essentially the opposite: an edge that has zero cost, an edge
that makes the vertices the same.

=over 4

=item APSP_Floyd_Warshall

=item all_pairs_shortest_paths

    my $apsp = $g->APSP_Floyd_Warshall(...);

Return the all-pairs shortest path object computed from the graph
using the Floyd-Warshall algorithm, of class L<Graph::TransitiveClosure>.

The length of a path between two vertices is the sum of weight attribute
of the edges along the shortest path between the two vertices.  If no
weight attribute name is specified explicitly

    $g->APSP_Floyd_Warshall(attribute_name => 'height');

the attribute C<weight> is assumed.

B<If an edge has no defined weight attribute, the value of one is
assumed when getting the attribute.>

Once computed, you can query the APSP object with

=over 8

=item path_length

    my $l = $apsp->path_length($u, $v);

Return the length of the shortest path between the two vertices.

=item path_vertices

    my @v = $apsp->path_vertices($u, $v);

Return the list of vertices along the shortest path.

=item path_successor

   my $u = $apsp->path_successor($u, $v);

Returns the successor of vertex $u in the all-pairs shortest path to $v.

=item all_paths

    my @paths = $apsp->all_paths($u, $v);

Return list of array-refs with all the paths from $u to $v.

=item average_path_length

    my $apl = $g->average_path_length; # All vertex pairs.

    my $apl = $g->average_path_length($u); # From $u.
    my $apl = $g->average_path_length($u, undef); # From $u.

    my $apl = $g->average_path_length($u, $v); # From $u to $v.

    my $apl = $g->average_path_length(undef, $v); # To $v.

Return the average (shortest) path length over all the non-zero paths
between vertex pairs of the graph's transitive closure. Depending on
the arguments, this can be from a vertex, between two vertices, or to
a vertex. An undefined (or not-given) vertex will match all.

=item longest_path

    my @lp = $g->longest_path;
    my $lp = $g->longest_path;

In scalar context return the I<longest shortest> path length over all
the vertex pairs of the graph.  In list context return the vertices
along a I<longest shortest> path.  Note that there might be more than
one such path; this interface returns a random one of them.

B<NOTE>: this returns the I<longest shortest> path, B<not> the I<longest> path.

=item diameter

=item graph_diameter

    my $gd = $g->diameter;

The longest path over all the vertex pairs is known as the
I<graph diameter>.

For an unconnected graph, single-vertex, or empty graph, returns C<undef>.

=item shortest_path

    my @sp = $g->shortest_path;
    my $sp = $g->shortest_path;

In scalar context return the shortest length over all the vertex pairs
of the graph.  In list context return the vertices along a shortest
path.  Note that there might be more than one such path; this
interface returns a random one of them.

For an unconnected, single-vertex, or empty graph, returns C<undef>
or an empty list.

=item radius

    my $gr = $g->radius;

The I<shortest longest> path over all the vertex pairs is known as the
I<graph radius>.  See also L</diameter>.

For an unconnected, single-vertex, or empty graph, returns Infinity.

=item center_vertices

=item centre_vertices

    my @c = $g->center_vertices;
    my @c = $g->center_vertices($delta);

The I<graph center> is the set of vertices for which the I<vertex
eccentricity> is equal to the I<graph radius>.  The vertices are
returned in random order.  By specifying a delta value you can widen
the criterion from strict equality (handy for non-integer edge weights).

For an unconnected, single-vertex, or empty graph, returns an empty list.

=item vertex_eccentricity

    my $ve = $g->vertex_eccentricity($v);

The longest path to a vertex is known as the I<vertex eccentricity>.

If the graph is unconnected, single-vertex, or empty graph, returns Inf.

=back

You can walk through the matrix of the shortest paths by using

=over 4

=item for_shortest_paths

    $n = $g->for_shortest_paths($callback)

The number of shortest paths is returned (this should be equal to V*V).
The $callback is a sub reference that receives four arguments:
the transitive closure object from Graph::TransitiveClosure, the two
vertices, and the index to the current shortest paths (0..V*V-1).

=back

=back

=head2 Clearing cached results

For many graph algorithms there are several different but equally valid
results.  (Pseudo)Randomness is used internally by the Graph module to
for example pick a random starting vertex, and to select random edges
from a vertex.

For efficiency the computed result is often cached to avoid
recomputing the potentially expensive operation, and this also gives
additional determinism (once a correct result has been computed, the
same result will always be given).

However, sometimes the exact opposite is desirable, and the possible
alternative results are wanted (within the limits of the pseudorandomness:
not all the possible solutions are guaranteed to be returned, usually only
a subset is returned).  To undo the caching, the following methods are
available:

=over 4

=item *

connectivity_clear_cache

Affects L</connected_components>, L</connected_component_by_vertex>,
L</connected_component_by_index>, L</same_connected_components>,
L</connected_graph>, L</is_connected>, L</is_weakly_connected>,
L</weakly_connected_components>, L</weakly_connected_component_by_vertex>,
L</weakly_connected_component_by_index>, L</same_weakly_connected_components>,
L</weakly_connected_graph>.

=item *

biconnectivity_clear_cache

Affects L</biconnected_components>,
L</biconnected_component_by_vertex>,
L</biconnected_component_by_index>, L</is_edge_connected>,
L</is_edge_separable>, L</articulation_points>, L</cut_vertices>,
L</is_biconnected>, L</biconnected_graph>,
L</same_biconnected_components>, L</bridges>.

=item *

strong_connectivity_clear_cache

Affects L</strongly_connected_components>,
L</strongly_connected_component_by_vertex>,
L</strongly_connected_component_by_index>,
L</same_strongly_connected_components>, L</is_strongly_connected>,
L</strongly_connected>, L</strongly_connected_graph>.

=item *

SPT_Dijkstra_clear_cache

Affects L</SPT_Dijkstra>, L</SSSP_Dijkstra>, L</single_source_shortest_paths>,
L</SP_Dijkstra>.

=item *

SPT_Bellman_Ford_clear_cache

Affects L</SPT_Bellman_Ford>, L</SSSP_Bellman_Ford>, L</SP_Bellman_Ford>.

=back

Note that any such computed and cached results are of course always
automatically discarded whenever the graph is modified.

=head2 Random

You can either ask for random elements of existing graphs or create
random graphs.

=over 4

=item random_vertex

    my $v = $g->random_vertex;

Return a random vertex of the graph, or undef if there are no vertices.

=item random_edge

    my $e = $g->random_edge;

Return a random edge of the graph as an array reference having the
vertices as elements, or undef if there are no edges.

=item random_successor

    my $v = $g->random_successor($v);

Return a random successor of the vertex in the graph, or undef if there
are no successors.

=item random_predecessor

    my $u = $g->random_predecessor($v);

Return a random predecessor of the vertex in the graph, or undef if there
are no predecessors.

=item random_graph

    my $g = Graph->random_graph(%opt);

Construct a random graph.  The I<%opt> B<must> contain the C<vertices>
argument

    vertices => vertices_def

where the I<vertices_def> is one of

=over 8

=item *

an array reference where the elements of the array reference are the
vertices

=item *

a number N in which case the vertices will be integers 0..N-1

=back

=back

The %opt may have either of the argument C<edges> or the argument
C<edges_fill>.  Both are used to define how many random edges to
add to the graph; C<edges> is an absolute number, while C<edges_fill>
is a relative number (relative to the number of edges in a complete
graph, C).  The number of edges can be larger than C, but only if the
graph is countedged.  The random edges will not include self-loops.
If neither C<edges> nor C<edges_fill> is specified, an C<edges_fill>
of 0.5 is assumed.

If you want repeatable randomness (what is an oxymoron?)
you can use the C<random_seed> option:

    $g = Graph->random_graph(vertices => 10, random_seed => 1234);

As this uses the standard Perl srand(), the usual caveat applies:
use it sparingly, and consider instead using a single srand() call
at the top level of your application.

The default random distribution of edges is flat, that is, any pair of
vertices is equally likely to appear.  To define your own distribution,
use the C<random_edge> option:

    $g = Graph->random_graph(vertices => 10, random_edge => \&d);

where C<d> is a code reference receiving I<($g, $u, $v, $p)> as
parameters, where the I<$g> is the random graph, I<$u> and I<$v> are
the vertices, and the I<$p> is the probability ([0,1]) for a flat
distribution.  It must return a probability ([0,1]) that the vertices
I<$u> and I<$v> have an edge between them.  Note that returning one
for a particular pair of vertices doesn't guarantee that the edge will
be present in the resulting graph because the required number of edges
might be reached before that particular pair is tested for the
possibility of an edge.  Be very careful to adjust also C<edges>
or C<edges_fill> so that there is a possibility of the filling process
terminating.

B<NOTE>: a known problem with randomness in openbsd pre-perl-5.20 is that
using a seed does not give you deterministic randomness. This affects any
Perl code, not just Graph.

=head2 Attributes

You can attach free-form attributes (key-value pairs, in effect a full
Perl hash) to each vertex, edge, and the graph itself.

Note that attaching attributes does slow down some other operations
on the graph by a factor of three to ten.  For example adding edge
attributes does slow down anything that walks through all the edges.

For vertex attributes:

=over 4

=item set_vertex_attribute

    $g->set_vertex_attribute($v, $name, $value)

Set the named vertex attribute.

If the vertex does not exist, the set_...() will create it, and the
other vertex attribute methods will return false or empty.

B<NOTE: any attributes beginning with an underscore/underline (_)
are reserved for the internal use of the Graph module.>

=item get_vertex_attribute

    $value = $g->get_vertex_attribute($v, $name)

Return the named vertex attribute.

=item has_vertex_attribute

    $g->has_vertex_attribute($v, $name)

Return true if the vertex has an attribute, false if not.

=item delete_vertex_attribute

    $g->delete_vertex_attribute($v, $name)

Delete the named vertex attribute.

=item set_vertex_attributes

    $g->set_vertex_attributes($v, $attr)

Set all the attributes of the vertex from the anonymous hash $attr.

B<NOTE>: any attributes beginning with an underscore (C<_>) are
reserved for the internal use of the Graph module.

=item get_vertex_attributes

    $attr = $g->get_vertex_attributes($v)

Return all the attributes of the vertex as an anonymous hash, or C<undef>
if no such vertex.

=item get_vertex_attribute_names

    @name = $g->get_vertex_attribute_names($v)

Return the names of vertex attributes.

=item get_vertex_attribute_values

    @value = $g->get_vertex_attribute_values($v)

Return the values of vertex attributes.

=item has_vertex_attributes

    $g->has_vertex_attributes($v)

Return true if the vertex has any attributes, false if not.

=item delete_vertex_attributes

    $g->delete_vertex_attributes($v)

Delete all the attributes of the named vertex.

=back

If you are using multivertices, use the I<by_id> variants:

=over 4

=item set_vertex_attribute_by_id

=item get_vertex_attribute_by_id

=item has_vertex_attribute_by_id

=item delete_vertex_attribute_by_id

=item set_vertex_attributes_by_id

=item get_vertex_attributes_by_id

=item get_vertex_attribute_names_by_id

=item get_vertex_attribute_values_by_id

=item has_vertex_attributes_by_id

=item delete_vertex_attributes_by_id

    $g->set_vertex_attribute_by_id($v, $id, $name, $value)
    $g->get_vertex_attribute_by_id($v, $id, $name)
    $g->has_vertex_attribute_by_id($v, $id, $name)
    $g->delete_vertex_attribute_by_id($v, $id, $name)
    $g->set_vertex_attributes_by_id($v, $id, $attr)
    $g->get_vertex_attributes_by_id($v, $id)
    $g->get_vertex_attribute_values_by_id($v, $id)
    $g->get_vertex_attribute_names_by_id($v, $id)
    $g->has_vertex_attributes_by_id($v, $id)
    $g->delete_vertex_attributes_by_id($v, $id)

=back

For edge attributes:

=over 4

=item set_edge_attribute

    $g->set_edge_attribute($u, $v, $name, $value)

Set the named edge attribute.

If the edge does not exist, the set_...() will create it, and the other
edge attribute methods will return false or empty.

B<NOTE>: any attributes beginning with an underscore (C<_>) are
reserved for the internal use of the Graph module.

=item get_edge_attribute

    $value = $g->get_edge_attribute($u, $v, $name)

Return the named edge attribute.

=item has_edge_attribute

    $g->has_edge_attribute($u, $v, $name)

Return true if the edge has an attribute, false if not.

=item delete_edge_attribute

    $g->delete_edge_attribute($u, $v, $name)

Delete the named edge attribute.

=item set_edge_attributes

    $g->set_edge_attributes($u, $v, $attr)

Set all the attributes of the edge from the anonymous hash $attr.

B<NOTE>: any attributes beginning with an underscore (C<_>) are
reserved for the internal use of the Graph module.

=item get_edge_attributes

    $attr = $g->get_edge_attributes($u, $v)

Return all the attributes of the edge as an anonymous hash, or C<undef>
if no such edge.

=item get_edge_attribute_names

    @name = $g->get_edge_attribute_names($u, $v)

Return the names of edge attributes.

=item get_edge_attribute_values

    @value = $g->get_edge_attribute_values($u, $v)

Return the values of edge attributes.

=item has_edge_attributes

    $g->has_edge_attributes($u, $v)

Return true if the edge has any attributes, false if not.

=item delete_edge_attributes

    $g->delete_edge_attributes($u, $v)

Delete all the attributes of the named edge.

=back

If you are using multiedges, use the I<by_id> variants:

=over 4

=item set_edge_attribute_by_id

=item get_edge_attribute_by_id

=item has_edge_attribute_by_id

=item delete_edge_attribute_by_id

=item set_edge_attributes_by_id

=item get_edge_attributes_by_id

=item get_edge_attribute_names_by_id

=item get_edge_attribute_values_by_id

=item has_edge_attributes_by_id

=item delete_edge_attributes_by_id

    $g->set_edge_attribute_by_id($u, $v, $id, $name, $value)
    $g->get_edge_attribute_by_id($u, $v, $id, $name)
    $g->has_edge_attribute_by_id($u, $v, $id, $name)
    $g->delete_edge_attribute_by_id($u, $v, $id, $name)
    $g->set_edge_attributes_by_id($u, $v, $id, $attr)
    $g->get_edge_attributes_by_id($u, $v, $id)
    $g->get_edge_attribute_values_by_id($u, $v, $id)
    $g->get_edge_attribute_names_by_id($u, $v, $id)
    $g->has_edge_attributes_by_id($u, $v, $id)
    $g->delete_edge_attributes_by_id($u, $v, $id)

=back

For graph attributes:

=over 4

=item set_graph_attribute

    $g->set_graph_attribute($name, $value)

Set the named graph attribute.

B<NOTE>: any attributes beginning with an underscore (C<_>) are
reserved for the internal use of the Graph module.

=item get_graph_attribute

    $value = $g->get_graph_attribute($name)

Return the named graph attribute.

=item has_graph_attribute

    $g->has_graph_attribute($name)

Return true if the graph has an attribute, false if not.

=item delete_graph_attribute

    $g->delete_graph_attribute($name)

Delete the named graph attribute.

=item set_graph_attributes

    $g->get_graph_attributes($attr)

Set all the attributes of the graph from the anonymous hash $attr.

B<NOTE>: any attributes beginning with an underscore (C<_>) are
reserved for the internal use of the Graph module.

=item get_graph_attributes

    $attr = $g->get_graph_attributes()

Return all the attributes of the graph as an anonymous hash.

=item get_graph_attribute_names

    @name = $g->get_graph_attribute_names()

Return the names of graph attributes.

=item get_graph_attribute_values

    @value = $g->get_graph_attribute_values()

Return the values of graph attributes.

=item has_graph_attributes

    $g->has_graph_attributes()

Return true if the graph has any attributes, false if not.

=item delete_graph_attributes

    $g->delete_graph_attributes()

Delete all the attributes of the named graph.

=back

=head2 Weighted

As convenient shortcuts the following methods add, query, and
manipulate the attribute C<weight> with the specified value to the
respective Graph elements.

=over 4

=item add_weighted_edge

    $g->add_weighted_edge($u, $v, $weight)

=item add_weighted_edges

    $g->add_weighted_edges($u1, $v1, $weight1, ...)

=item add_weighted_path

    $g->add_weighted_path($v1, $weight1, $v2, $weight2, $v3, ...)

=item add_weighted_vertex

    $g->add_weighted_vertex($v, $weight)

=item add_weighted_vertices

    $g->add_weighted_vertices($v1, $weight1, $v2, $weight2, ...)

=item delete_edge_weight

    $g->delete_edge_weight($u, $v)

=item delete_vertex_weight

    $g->delete_vertex_weight($v)

=item get_edge_weight

    $g->get_edge_weight($u, $v)

=item get_vertex_weight

    $g->get_vertex_weight($v)

=item has_edge_weight

    $g->has_edge_weight($u, $v)

=item has_vertex_weight

    $g->has_vertex_weight($v)

=item set_edge_weight

    $g->set_edge_weight($u, $v, $weight)

=item set_vertex_weight

    $g->set_vertex_weight($v, $weight)

=back

=head2 Isomorphism

Two graphs being I<isomorphic> means that they are structurally the
same graph, the difference being that the vertices might have been
I<renamed> or I<substituted>.  For example in the below example $g0
and $g1 are isomorphic: the vertices C<b c d> have been renamed as
C<z x y>.

	$g0 = Graph->new;
	$g0->add_edges(qw(a b a c c d));
	$g1 = Graph->new;
	$g1->add_edges(qw(a x x y a z));

In the general case determining isomorphism is I<NP-hard>, in other
words, really hard (time-consuming), no other ways of solving the problem
are known than brute force check of of all the possibilities (with possible
optimization tricks, of course, but brute force still rules at the end of
the day).

A B<very rough guess> at whether two graphs B<could> be isomorphic
is possible via the method

=over 4

=item could_be_isomorphic

    $g0->could_be_isomorphic($g1)    

=back

If the graphs do not have the same number of vertices and edges, false
is returned.  If the distribution of I<in-degrees> and I<out-degrees>
at the vertices of the graphs does not match, false is returned.
Otherwise, true is returned.

What is actually returned is the maximum number of possible isomorphic
graphs between the two graphs, after the above sanity checks have been
conducted.  It is basically the product of the factorials of the
absolute values of in-degrees and out-degree pairs at each vertex,
with the isolated vertices ignored (since they could be reshuffled and
renamed arbitrarily).  Note that for large graphs the product of these
factorials can overflow the maximum presentable number (the floating
point number) in your computer (in Perl) and you might get for example
I<Infinity> as the result.

=head2 Miscellaneous

=over 4

=item betweenness

    %b = $g->betweenness

Returns a map of vertices to their Freeman's betweennesses:

  C_b(v) = \sum_{s \neq v \neq t \in V} \frac{\sigma_{s,t}(v)}{\sigma_{s,t}}

It is described in:

    Freeman, A set of measures of centrality based on betweenness, http://arxiv.org/pdf/cond-mat/0309045

and based on the algorithm from:

    "A Faster Algorithm for Betweenness Centrality"

=item clustering_coefficient

    $gamma = $g->clustering_coefficient()
    ($gamma, %clustering) = $g->clustering_coefficient()

Returns the clustering coefficient gamma as described in

    Duncan J. Watts and Steven Strogatz, Collective dynamics of 'small-world' networks, https://web.archive.org/web/20120616204225/http://audiophile.tam.cornell.edu/SS_nature_smallworld.pdf

In scalar context returns just the average gamma, in list context
returns the average gamma and a hash of vertices to clustering
coefficients.

Returns an empty list (and therefore undefined in scalar context) if
the graph has no vertices.

=item subgraph_by_radius

    $s = $g->subgraph_by_radius(@v, $radius);

Returns a subgraph representing the ball of $radius around the given vertices
(breadth-first search).

=back

The "expect" methods can be used to test a graph and croak if the
graph call is not as expected.

=over 4

=item expect_acyclic

=item expect_dag

=item expect_directed

=item expect_hyperedged

=item expect_multiedge

=item expect_multiedged

=item expect_multivertex

=item expect_multivertexed

=item expect_no_args

=item expect_non_multiedge

=item expect_non_multiedged

=item expect_non_multivertex

=item expect_non_multivertexed

=item expect_non_unionfind

=item expect_undirected

=back

In many algorithms it is useful to have a value representing the
infinity.  The Graph provides (and itself uses):

=over 4

=item Infinity

(Not exported, use Graph::Infinity explicitly)

=back

=head2 Size Requirements

A graph takes up at least 1172 bytes of memory.

A vertex takes up at least 100 bytes of memory.

An edge takes up at least 400 bytes of memory.

(A Perl scalar value takes 16 bytes, or 12 bytes if it's a reference.)

These size approximations are B<very> approximate and optimistic
(they are based on total_size() of Devel::Size).  In real life many
factors affect these numbers, for example how Perl is configured.
The numbers are for a 32-bit platform and for Perl 5.8.8.

Roughly, the above numbers mean that in a megabyte of memory you can
fit for example a graph of about 1000 vertices and about 2500 edges.

=head2 Hyperedges, hypergraphs

B<BEWARE>: this is a rather thinly tested feature, and the theory
is even less so.  Do not expect this to stay as it is (or at all)
in future releases.

B<NOTE>: most usual graph algorithms (and basic concepts) break
horribly (or at least will look funny) with these hyperthingies.
Caveat emptor.

Hyperedges are edges that connect a number of vertices different
from the usual two.

Hypergraphs are graphs with hyperedges.

To enable hyperness when constructing Graphs use the C<hyperedged>
attribute:

   my $h = Graph->new(hyperedged => 1);

To test for hyperness of a graph use the

=over 4

=item is_hyperedged

=item hyperedged

    $g->is_hyperedged
    $g->hyperedged

=back

Edges in hypergraphs are either directed or undirected, as with simple
graphs. If undirected, the edge is a blob of 0 or more vertices. For
directed, the set of heads and set of tails are also possibly empty. In
general, hypergraphs are simply generalisations of simple-graph ideas,
with some of the arbitrary limitations removed.

For more information on directed hypergraphs, see
L<Directed Hypergraphs and Applications, Gallo-Longo-Pallottino-Nguyen|https://doi.org/10.1016/0166-218X%2893%2990045-P>.
It defines hyperarcs (directed edges in a hypergraph) as ordered pairs
of subsets of V, and hyperedges (undirected) as single subsets of
V. Since sets are unordered and elements within them are unique, this
implies that the only valuable use for hypergraphs is where in a given
connection entity (edge or arc), each vertex only appears at most once.
Additionally, how the C<hyper> property of edges works may
change. The underpinning notion is that each edge will be considered
an entry in an incidence matrix (dimensions |V| x |E|), with values of
either (0, 1=participating) for undirected (hyperedges), or (-1=tail,
0, 1=head) for directed (hyperarcs) against each vertex.

An extension to this is that to extend directed multigraphs with
self-loops (aka "quivers") to hypergraphs, the incidence-matrix values
will instead be a bitfield, with bit 0 being participation in the tail,
and bit 1 in the head.

=head2 DIAGNOSTICS

=over 4

=item *

Graph::...Map...: arguments X expected Y ...

If you see these (more user-friendly error messages should have been
triggered above and before these) please report any such occurrences,
but in general you should be happy to see these since it means that an
attempt to call something with a wrong number of arguments was caught
in time.

=item *

Graph::add_edge: graph is not hyperedged ...

Maybe you used add_weighted_edge() with only the two vertex arguments.

=item *

Not an ARRAY reference at lib/Graph.pm ...

One possibility is that you have code based on Graph 0.2xxxx that
assumes Graphs being blessed hash references, possibly also assuming
that certain hash keys are available to use for your own purposes.
In Graph 0.50 none of this is true.  Please do not expect any
particular internal implementation of Graphs.  Use inheritance
and graph/vertex/edge attributes instead.

Another possibility is that you meant to have objects (blessed
references) as graph vertices, but forgot to use C<refvertexed>
(see L</refvertexed>) when creating the graph.

=item *

Deep recursion on subroutine "Graph::_biconnectivity_dfs" at ...

If you have more than 100 vertices, the recursive algorithm will
trigger Perl's recursion protection. If you set environment variable
C<GRAPH_ALLOW_RECURSION> to a true value, this protection will be
disabled, e.g.:

    $ GRAPH_ALLOW_RECURSION=1 perl -Ilib util/grand.pl --test=bcc 101

=back

=head1 ACKNOWLEDGEMENTS

All bad terminology, bugs, and inefficiencies are naturally mine, all
mine, and not the fault of the below.

Thanks to Nathan Goodman and Andras Salamon for bravely betatesting my
pre-0.50 code.  If they missed something, that was only because of my
fiendish code.

The following literature for algorithms and some test cases:

=over 4

=item *

Algorithms in C, Third Edition, Part 5, Graph Algorithms, Robert Sedgewick, Addison Wesley

=item *

Introduction to Algorithms, First Edition, Cormen-Leiserson-Rivest, McGraw Hill

=item *

Graphs, Networks and Algorithms, Dieter Jungnickel, Springer

=back

=head1 SEE ALSO

Persistent/Serialized graphs?  You want to read/write Graphs?  See the
L<Graph::Reader> and L<Graph::Writer> in CPAN.

=head1 AUTHOR

Jarkko Hietaniemi F<jhi@iki.fi>

Now being maintained by Neil Bowers E<lt>neilb@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (c) 1998-2014 Jarkko Hietaniemi.  All rights reserved.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut
