libgraph v0.5.0 Graph
This module defines a directed graph data structure, which supports both acyclic and cyclic forms. It also defines the API for creating, manipulating, and querying that structure.
This is intended as a replacement for :digraph
, which requires the use of 3 ETS tables at a minimum,
but up to 6 at a time during certain operations (such as get_short_path/3
). In environments where many
graphs are in memory at a time, this can be dangerous, as it is easy to hit the system limit for max ETS tables,
which will bring your node down. This graph implementation does not use ETS, so it can be used freely without
concern for hitting this limit.
As far as memory usage is concerned, Graph
should be fairly compact in memory, but if you want to do a rough
comparison between the memory usage for a graph between libgraph
and digraph
, use :digraph.info/1
and
Graph.info/1
on the two graphs, and both contain memory usage information. Keep in mind we don’t have a precise
way to measure the memory usage of a term in memory, whereas ETS is able to give a precise answer, but we do have
a fairly good way to estimate the usage of a term, and we use that method within libgraph
.
The Graph struct is composed of a map of vertex ids to vertices, a map of vertex ids to their out neighbors, a map of vertex ids to their in neighbors (both in and out neighbors are represented as MapSets), a map of vertex ids to vertex labels (which are only stored if a non-nil label was provided), and a map of edge ids (which are a tuple of the source vertex id to destination vertex id) to a map of edge metadata (label/weight).
The reason we use several different maps to represent the graph, particularly the inverse index of in/out neighbors, is that it allows us to perform very efficient queries on the graph without having to store vertices multiple times, it is also more efficient to use maps with small keys, particularly integers or binaries. The use of several maps does mean we use more space in memory, but because the bulk of those maps are just integers, it’s about as compact as we can make it while still remaining performant.
There are benchmarks provided with this library which compare it directly to :digraph
for some common operations,
and thus far, libgraph
is equal to or outperforms :digraph
in all of them.
The only bit of data I have not yet evaluated is how much garbage is generated when querying/manipulating the graph
between libgraph
and digraph
, but I suspect the use of ETS means that digraph
is able to keep that to a minimum.
Until I verify if that’s the case, I would assume that libgraph
has higher memory requirements, but better performance,
and is able to side-step the ETS limit. If your requirements, like mine, mean that you are dynamically constructing and querying
graphs concurrently, I think libgraph
is the better choice - however if you either need the APIs of :digraph
that I have
not yet implemented, or do not have the same use case, I would stick to :digraph
for now.
Link to this section Summary
Functions
Gets the shortest path between a
and b
Like add_edge/3
or add_edge/4
, but takes a Graph.Edge
struct created with
Graph.Edge.new/2
or Graph.Edge.new/3
Adds an edge connecting a
to b
. If either a
or b
do not exist in the graph,
they are automatically added. Adding the same edge more than once does not create multiple edges,
each edge is only ever stored once
Like add_edge/3
, but takes a list of Graph.Edge
structs, and adds an edge to the graph for each pair
Adds a new vertex to the graph. If the vertex is already present in the graph, the add is a no-op
Like add_vertex/2
, but takes a list of vertices to add to the graph
Returns the root vertex of the arborescence, if one exists, otherwise nil
Returns a list of connected components, where each component is a list of vertices
Removes an edge connecting a
to b
. If no such vertex exits, or the edge does not exist,
it is effectively a no-op
Like delete_edge/3
, but takes a list of vertex pairs, and deletes the corresponding
edge from the graph, if it exists
Removes a vertex from the graph, as well as any edges which refer to that vertex. If the vertex does not exist in the graph, it is a no-op
Like delete_vertex/2
, but takes a list of vertices to delete from the graph
Gets the shortest path between a
and b
Returns the label for the given vertex. If no label was assigned, it returns nil
Return a list of all the edges, where each edge is expressed as a tuple
of {A, B}
, where the elements are the vertices involved, and implying the
direction of the edge to be from A
to B
Builds a list of paths between vertex a
and vertex b
See dijkstra/1
Returns the in-degree of vertex v
of graph g
Returns a list of Graph.Edge
structs representing the in edges to vertex v
Returns a list of vertices which all have edges coming in to the given vertex v
Returns a map of summary information about this graph
Returns true if and only if the graph g
is acyclic
Returns true if the graph is an aborescence, a directed acyclic graph, where the root, a vertex, of the arborescence has a unique path from itself to every other vertex in the graph
Returns true if the graph g
is not acyclic
Returns true if graph g1
is a subgraph of g2
Returns true if and only if the graph g
is a tree
Updates the label for the given vertex
Returns a list of vertices from graph g
which are included in a loop, where a loop is a cycle of length 1
Maps a function over all the vertices in a graph using a depth-first traversal
Creates a new graph
Returns the number of edges in the graph
Returns the number of vertices in the graph
Returns the out-degree of vertex v
of graph g
Returns a list of Graph.Edge
structs representing the out edges from vertex v
Returns a list of vertices which the given vertex v
has edges going to
Returns all vertices of graph g
. The order is given by a depth-first traversal of the graph,
collecting visited vertices in postorder. More precisely, the vertices visited while searching from an
arbitrarily chosen vertex are collected in postorder, and all those collected vertices are placed before
the subsequently visited vertices
Returns all vertices of graph g
. The order is given by a depth-first traversal of the graph,
collecting visited vertices in preorder
Returns an unsorted list of vertices from the graph, such that for each vertex in the list (call it v
),
there is a path in the graph from some vertex of vs
to v
Returns an unsorted list of vertices from the graph, such that for each vertex in the list (call it v
),
there is a path in the graph of length one or more from some vertex of vs
to v
Returns an unsorted list of vertices from the graph, such that for each vertex in the list (call it v
),
there is a path from v
to some vertex of vs
Returns an unsorted list of vertices from the graph, such that for each vertex in the list (call it v
),
there is a path of length one or more from v
to some vertex of vs
Applies a reducer over all the vertices in a graph using a depth-first traversal. The reducer function receives the current vertex, and the accumulator, and must return a new accumulator
Replaces vertex
with new_vertex
in the graph
Splits the edge between v1
and v2
by inserting a new vertex, v3
, deleting
the edge between v1
and v2
, and inserting an edge from v1
to v3
and from
v3
to v2
Returns a list of strongly connected components, where each component is a list of vertices
Builds a maximal subgraph of g
which includes all of the vertices in vs
and the edges which connect them
Converts the given Graph to DOT format, which can then be converted to
a number of other formats via Graphviz, e.g. dot -Tpng out.dot > out.png
Returns a topological ordering of the vertices of graph g
, if such an ordering exists, otherwise it returns false.
For each vertex in the returned list, no out-neighbors occur earlier in the list
The transposition of a graph is another graph with the direction of all the edges reversed
Updates the metadata (weight/label) for an edge using the provided options
Returns the label for the given vertex. If no label was assigned, it returns nil
Returns a list of all the vertices in the graph
Walks the graph by starting with a depth-first traversal, the walk function receives the current vertex, it’s out-neighbors and in-neighbors (as lists of Edge structs), and the accumulator. You can return one of the following to control the walk
See Graph.Reducer.walk/4
Link to this section Types
walker_fun :: (vertex, [vertex], [vertex], term -> {:next, term}) | {:next, vertex, term} | {:skip, term} | {:halt, term}
Link to this section Functions
Gets the shortest path between a
and b
.
The A algorithm is very much like Dijkstra’s algorithm, except in addition to edge weights, A
also considers a heuristic function for determining the lower bound of the cost to go from vertex
v
to b
. The lower bound must be less than the cost of the shortest path from v
to b
, otherwise
it will do more harm than good. Dijkstra’s algorithm can be reframed as A* where lower_bound(v)
is always 0.
This function puts the heuristics in your hands, so you must provide the heuristic function, which should take
a single parameter, v
, which is the vertex being currently examined. Your heuristic should then determine what the
lower bound for the cost to reach b
from v
is, and return that value.
Example
iex> g = Graph.new |> Graph.add_edges([{:a, :b}, {:b, :c}, {:c, :d}, {:b, :d}])
...> Graph.a_star(g, :a, :d, fn _ -> 0 end)
[:a, :b, :d]
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c, :d])
...> g = Graph.add_edges(g, [{:a, :c}, {:b, :c}, {:b, :d}])
...> Graph.a_star(g, :a, :d, fn _ -> 0 end)
nil
Like add_edge/3
or add_edge/4
, but takes a Graph.Edge
struct created with
Graph.Edge.new/2
or Graph.Edge.new/3
.
Example
iex> g = Graph.new |> Graph.add_edge(Graph.Edge.new(:a, :b))
...> [:a, :b] = Graph.vertices(g)
...> Graph.edges(g)
[%Graph.Edge{v1: :a, v2: :b}]
add_edge(t, vertex, vertex, Graph.Edge.edge_opts) :: t | {:error, {:invalid_edge_option, term}}
Adds an edge connecting a
to b
. If either a
or b
do not exist in the graph,
they are automatically added. Adding the same edge more than once does not create multiple edges,
each edge is only ever stored once.
Edges have a default weight of 1, and an empty (nil) label. You can change this by passing options to this function, as shown below.
Example
iex> g = Graph.new |> Graph.add_edge(:a, :b)
...> [:a, :b] = Graph.vertices(g)
...> Graph.edges(g)
[%Graph.Edge{v1: :a, v2: :b, label: nil, weight: 1}]
iex> g = Graph.new |> Graph.add_edge(:a, :b, label: :foo, weight: 2)
...> [:a, :b] = Graph.vertices(g)
...> Graph.edges(g)
[%Graph.Edge{v1: :a, v2: :b, label: :foo, weight: 2}]
add_edges(t, [Graph.Edge.t]) :: t | {:error, {:invalid_edge, term}}
Like add_edge/3
, but takes a list of Graph.Edge
structs, and adds an edge to the graph for each pair.
See the docs for Graph.Edge.new/2
or Graph.Edge.new/3
for more info.
Examples
iex> alias Graph.Edge
...> edges = [Edge.new(:a, :b), Edge.new(:b, :c, weight: 2)]
...> g = Graph.new |> Graph.add_vertices([:a, :b, :c]) |> Graph.add_edges(edges)
...> Graph.edges(g)
[%Graph.Edge{v1: :a, v2: :b}, %Graph.Edge{v1: :b, v2: :c, weight: 2}]
iex> Graph.new |> Graph.add_vertices([:a, :b, :c]) |> Graph.add_edges([:a, :b])
{:error, {:invalid_edge, :a}}
Adds a new vertex to the graph. If the vertex is already present in the graph, the add is a no-op.
You can provide an optional label for the vertex, aside from the variety of uses this has for working with graphs, labels will also be used when exporting a graph in DOT format.
Example
iex> g = Graph.new |> Graph.add_vertex(:a, :mylabel) |> Graph.add_vertex(:a)
...> [:a] = Graph.vertices(g)
...> Graph.vertex_label(g, :a)
:mylabel
Like add_vertex/2
, but takes a list of vertices to add to the graph.
Example
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :a])
...> Graph.vertices(g)
[:a, :b]
Returns the root vertex of the arborescence, if one exists, otherwise nil.
Returns a list of connected components, where each component is a list of vertices.
A connected component is a maximal subgraph such that there is a path between each pair of vertices, considering all edges undirected.
A subgraph is a graph whose vertices and edges are a subset of the vertices and edges of the source graph.
A maximal subgraph is a subgraph with property P
where all other subgraphs which contain the same vertices
do not have that same property P
.
Example
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c, :d])
...> g = Graph.add_edges(g, [{:a, :b}, {:a, :c}, {:b, :c}, {:c, :d}, {:c, :a}])
...> Graph.components(g)
[[:d, :b, :c, :a]]
Removes an edge connecting a
to b
. If no such vertex exits, or the edge does not exist,
it is effectively a no-op.
Example
iex> g = Graph.new |> Graph.add_edge(:a, :b) |> Graph.delete_edge(:a, :b)
...> [:a, :b] = Graph.vertices(g)
...> Graph.edges(g)
[]
Like delete_edge/3
, but takes a list of vertex pairs, and deletes the corresponding
edge from the graph, if it exists.
Examples
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c]) |> Graph.add_edge(:a, :b)
...> g = Graph.delete_edges(g, [{:a, :b}])
...> Graph.edges(g)
[]
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c]) |> Graph.add_edge(:a, :b)
...> Graph.delete_edges(g, [:a])
{:error, {:invalid_edge, :a}}
Removes a vertex from the graph, as well as any edges which refer to that vertex. If the vertex does not exist in the graph, it is a no-op.
Example
iex> g = Graph.new |> Graph.add_vertex(:a) |> Graph.add_vertex(:b) |> Graph.add_edge(:a, :b)
...> [:a, :b] = Graph.vertices(g)
...> [%Graph.Edge{v1: :a, v2: :b}] = Graph.edges(g)
...> g = Graph.delete_vertex(g, :b)
...> [:a] = Graph.vertices(g)
...> Graph.edges(g)
[]
Like delete_vertex/2
, but takes a list of vertices to delete from the graph.
Example
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c]) |> Graph.delete_vertices([:a, :b])
...> Graph.vertices(g)
[:c]
Gets the shortest path between a
and b
.
As indicated by the name, this uses Dijkstra’s algorithm for locating the shortest path, which means that edge weights are taken into account when determining which vertices to search next. By default, all edges have a weight of 1, so vertices are inspected at random; which causes this algorithm to perform a naive depth-first search of the graph until a path is found. If your edges are weighted however, this will allow the algorithm to more intelligently navigate the graph.
Example
iex> g = Graph.new |> Graph.add_edges([{:a, :b}, {:b, :c}, {:c, :d}, {:b, :d}])
...> Graph.dijkstra(g, :a, :d)
[:a, :b, :d]
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c, :d])
...> g = Graph.add_edges(g, [{:a, :c}, {:b, :c}, {:b, :d}])
...> Graph.dijkstra(g, :a, :d)
nil
Returns the label for the given vertex. If no label was assigned, it returns nil.
Example
iex> g = Graph.new |> Graph.add_edge(:a, :b, label: :my_edge)
...> Graph.edge_label(g, :a, :b)
:my_edge
Return a list of all the edges, where each edge is expressed as a tuple
of {A, B}
, where the elements are the vertices involved, and implying the
direction of the edge to be from A
to B
.
NOTE: You should be careful when using this on dense graphs, as it produces lists with whatever you’ve provided as vertices, with likely many copies of each. I’m not sure if those copies are shared in-memory as they are unchanged, so it should be fairly compact in memory, but I have not verified that to be sure.
Example
iex> g = Graph.new |> Graph.add_vertex(:a) |> Graph.add_vertex(:b) |> Graph.add_vertex(:c)
...> g = g |> Graph.add_edge(:a, :c) |> Graph.add_edge(:b, :c)
...> Graph.edges(g)
[%Graph.Edge{v1: :a, v2: :c}, %Graph.Edge{v1: :b, v2: :c}]
Builds a list of paths between vertex a
and vertex b
.
The algorithm used here is a depth-first search, which evaluates the whole graph until all paths are found. Order is guaranteed to be deterministic, but not guaranteed to be in any meaningful order (i.e. shortest to longest).
Example
iex> g = Graph.new |> Graph.add_edges([{:a, :b}, {:b, :c}, {:c, :d}, {:b, :d}, {:c, :a}])
...> Graph.get_paths(g, :a, :d)
[[:a, :b, :c, :d], [:a, :b, :d]]
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c, :d])
...> g = Graph.add_edges(g, [{:a, :c}, {:b, :c}, {:b, :d}])
...> Graph.get_paths(g, :a, :d)
[]
See dijkstra/1
.
Returns the in-degree of vertex v
of graph g
.
The in-degree of a vertex is the number of edges directed inbound towards that vertex.
Example
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c]) |> Graph.add_edge(:a, :b)
...> Graph.in_degree(g, :b)
1
Returns a list of Graph.Edge
structs representing the in edges to vertex v
.
Returns a list of vertices which all have edges coming in to the given vertex v
.
info(t) :: %{num_edges: non_neg_integer, num_vertices: non_neg_integer}
Returns a map of summary information about this graph.
NOTE: The size_in_bytes
value is an estimate, not a perfectly precise value, but
should be close enough to be useful.
Example
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c, :d])
...> g = g |> Graph.add_edges([{:a, :b}, {:b, :c}])
...> Graph.info(g)
%{num_vertices: 4, num_edges: 2, size_in_bytes: 952}
Returns true if and only if the graph g
is acyclic.
Returns true if the graph is an aborescence, a directed acyclic graph, where the root, a vertex, of the arborescence has a unique path from itself to every other vertex in the graph.
Returns true if the graph g
is not acyclic.
Returns true if graph g1
is a subgraph of g2
.
A graph is a subgraph of another graph if it’s vertices and edges are a subset of that graph’s vertices and edges.
Example
iex> g1 = Graph.new |> Graph.add_vertices([:a, :b, :c, :d]) |> Graph.add_edge(:a, :b) |> Graph.add_edge(:b, :c)
...> g2 = Graph.new |> Graph.add_vertices([:b, :c]) |> Graph.add_edge(:b, :c)
...> Graph.is_subgraph?(g2, g1)
true
Returns true if and only if the graph g
is a tree.
Updates the label for the given vertex.
If no such vertex exists in the graph, {:error, {:invalid_vertex, v}}
is returned.
Example
iex> g = Graph.new |> Graph.add_vertex(:a, :foo)
...> :foo = Graph.vertex_label(g, :a)
...> g = Graph.label_vertex(g, :a, :bar)
...> Graph.vertex_label(g, :a)
:bar
Returns a list of vertices from graph g
which are included in a loop, where a loop is a cycle of length 1.
Example
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c]) |> Graph.add_edge(:a, :a)
...> Graph.loop_vertices(g)
[:a]
Maps a function over all the vertices in a graph using a depth-first traversal
You can perform a breadth-first traversal instead by passing the option algorithm: :breadth_first
.
Example
iex> g = Graph.new |> Graph.add_vertices([1, 2, 4]) |> Graph.add_edge(1, 2) |> Graph.add_edge(2, 4)
...> Graph.map(g, fn v -> v * 2 end)
[2, 4, 8]
Creates a new graph.
Returns the number of edges in the graph
Example
iex> g = Graph.add_edges(Graph.new, [{:a, :b}, {:b, :c}, {:a, :a}])
...> Graph.num_edges(g)
3
Returns the number of vertices in the graph
Example
iex> g = Graph.add_vertices(Graph.new, [:a, :b, :c])
...> Graph.num_vertices(g)
3
Returns the out-degree of vertex v
of graph g
.
The out-degree of a vertex is the number of edges directed outbound from that vertex.
Example
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c]) |> Graph.add_edge(:a, :b)
...> Graph.out_degree(g, :a)
1
Returns a list of Graph.Edge
structs representing the out edges from vertex v
.
Returns a list of vertices which the given vertex v
has edges going to.
Returns all vertices of graph g
. The order is given by a depth-first traversal of the graph,
collecting visited vertices in postorder. More precisely, the vertices visited while searching from an
arbitrarily chosen vertex are collected in postorder, and all those collected vertices are placed before
the subsequently visited vertices.
Example
Our example code constructs a graph which looks like so:
:a
:b
/ :c :d
/
:e
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c, :d, :e])
...> g = Graph.add_edges(g, [{:a, :b}, {:b, :c}, {:b, :d}, {:c, :e}])
...> Graph.postorder(g)
[:e, :c, :d, :b, :a]
Returns all vertices of graph g
. The order is given by a depth-first traversal of the graph,
collecting visited vertices in preorder.
Example
Our example code constructs a graph which looks like so:
:a
:b
/ :c :d
/
:e
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c, :d, :e])
...> g = Graph.add_edges(g, [{:a, :b}, {:b, :c}, {:b, :d}, {:c, :e}])
...> Graph.preorder(g)
[:a, :b, :c, :e, :d]
Returns an unsorted list of vertices from the graph, such that for each vertex in the list (call it v
),
there is a path in the graph from some vertex of vs
to v
.
As paths of length zero are allowed, the vertices of vs
are also included in the returned list.
Example
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c, :d])
...> g = Graph.add_edges(g, [{:a, :b}, {:a, :c}, {:b, :c}, {:c, :d}])
...> Graph.reachable(g, [:a])
[:d, :c, :b, :a]
Returns an unsorted list of vertices from the graph, such that for each vertex in the list (call it v
),
there is a path in the graph of length one or more from some vertex of vs
to v
.
As a consequence, only those vertices of vs
that are included in some cycle are returned.
Example
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c, :d])
...> g = Graph.add_edges(g, [{:a, :b}, {:a, :c}, {:b, :c}, {:c, :d}])
...> Graph.reachable_neighbors(g, [:a])
[:d, :c, :b]
Returns an unsorted list of vertices from the graph, such that for each vertex in the list (call it v
),
there is a path from v
to some vertex of vs
.
As paths of length zero are allowed, the vertices of vs
are also included in the returned list.
Example
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c, :d])
...> g = Graph.add_edges(g, [{:a, :b}, {:a, :c}, {:b, :c}, {:c, :d}])
...> Graph.reaching(g, [:d])
[:b, :a, :c, :d]
Returns an unsorted list of vertices from the graph, such that for each vertex in the list (call it v
),
there is a path of length one or more from v
to some vertex of vs
.
As a consequence, only those vertices of vs
that are included in some cycle are returned.
Example
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c, :d]) …> g = Graph.add_edges(g, [{:a, :b}, {:a, :c}, {:b, :c}, {:c, :a}, {:b, :d}]) …> Graph.reaching_neighbors(g, [:b]) [:b, :c, :a]
reduce(t, term, reducer_fun, opts :: [walk_opt]) :: term
Applies a reducer over all the vertices in a graph using a depth-first traversal. The reducer function receives the current vertex, and the accumulator, and must return a new accumulator.
You can perform a breadth-first traversal instead by passing the option algorithm: :breadth_first
.
Example
iex> g = Graph.new |> Graph.add_vertices([1, 2, 4]) |> Graph.add_edge(1, 2) |> Graph.add_edge(2, 4)
...> Graph.reduce(g, 0, fn v, acc -> acc + v end)
7
Replaces vertex
with new_vertex
in the graph.
Example
iex> g = Graph.new |> Graph.add_vertices([:a, :b]) |> Graph.add_edge(:a, :b)
...> [:a, :b] = Graph.vertices(g)
...> g = Graph.replace_vertex(g, :a, :c)
...> [:b, :c] = Graph.vertices(g)
...> Graph.edges(g)
[%Graph.Edge{v1: :c, v2: :b}]
Splits the edge between v1
and v2
by inserting a new vertex, v3
, deleting
the edge between v1
and v2
, and inserting an edge from v1
to v3
and from
v3
to v2
.
The two resulting edges from the split will share the same weight and label.
Example
iex> g = Graph.new |> Graph.add_vertices([:a, :c]) |> Graph.add_edge(:a, :c, weight: 2)
...> g = Graph.split_edge(g, :a, :c, :b)
...> Graph.edges(g)
[%Graph.Edge{v1: :a, v2: :b, weight: 2}, %Graph.Edge{v1: :b, v2: :c, weight: 2}]
Returns a list of strongly connected components, where each component is a list of vertices.
A strongly connected component is a maximal subgraph such that there is a path between each pair of vertices.
See components/1
for the definitions of subgraph and maximal subgraph if you are unfamiliar with the
terminology.
Example
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c, :d])
...> g = Graph.add_edges(g, [{:a, :b}, {:a, :c}, {:b, :c}, {:c, :d}, {:c, :a}])
...> Graph.strong_components(g)
[[:d], [:b, :c, :a]]
Builds a maximal subgraph of g
which includes all of the vertices in vs
and the edges which connect them.
See the test suite for example usage.
Converts the given Graph to DOT format, which can then be converted to
a number of other formats via Graphviz, e.g. dot -Tpng out.dot > out.png
.
If labels are set on a vertex, then those labels are used in the DOT output in place of the vertex itself. If no labels were set, then the vertex is stringified if it’s a primitive type and inspected if it’s not, in which case the inspect output will be quoted and used as the vertex label in the DOT file.
Edge labels and weights will be shown as attributes on the edge definitions, otherwise they use the same labelling scheme for the involved vertices as described above.
NOTE: Currently this function assumes graphs are directed graphs, but in the future it will support undirected graphs as well.
Example
> g = Graph.new |> Graph.add_vertices([:a, :b, :c, :d])
> g = Graph.add_edges([{:a, :b}, {:b, :c}, {:b, :d}, {:c, :d}])
> g = Graph.label_vertex(g, :a, :start)
> g = Graph.label_vertex(g, :d, :finish)
> g = Graph.update_edge(g, :b, :d, weight: 3)
> IO.puts(Graph.to_dot(g))
strict digraph {
start
b
c
finish
start -> b
b -> c
b -> finish [weight=3]
c -> finish
}
Returns a topological ordering of the vertices of graph g
, if such an ordering exists, otherwise it returns false.
For each vertex in the returned list, no out-neighbors occur earlier in the list.
Example
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c, :d])
...> g = Graph.add_edges(g, [{:a, :b}, {:a, :c}, {:b, :c}, {:c, :d}])
...> Graph.topsort(g)
[:a, :b, :c, :d]
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c, :d])
...> g = Graph.add_edges(g, [{:a, :b}, {:a, :c}, {:b, :c}, {:c, :d}, {:c, :a}])
...> Graph.topsort(g)
false
The transposition of a graph is another graph with the direction of all the edges reversed.
Example
iex> g = Graph.new |> Graph.add_vertices([:a, :b, :c]) |> Graph.add_edge(:a, :b) |> Graph.add_edge(:b, :c)
...> g |> Graph.transpose |> Graph.edges
[%Graph.Edge{v1: :b, v2: :a}, %Graph.Edge{v1: :c, v2: :b}]
update_edge(t, vertex, vertex, Graph.Edge.edge_opts) :: t | {:error, :no_such_edge}
Updates the metadata (weight/label) for an edge using the provided options.
Example
iex> g = Graph.new |> Graph.add_edge(:a, :b)
...> [%Graph.Edge{v1: :a, v2: :b, label: nil, weight: 1}] = Graph.edges(g)
...> %Graph{} = g = Graph.update_edge(g, :a, :b, weight: 2, label: :foo)
...> Graph.edges(g)
[%Graph.Edge{v1: :a, v2: :b, label: :foo, weight: 2}]
Returns the label for the given vertex. If no label was assigned, it returns nil.
Example
iex> g = Graph.new |> Graph.add_vertex(:a) |> Graph.label_vertex(:a, :my_label)
...> Graph.vertex_label(g, :a)
:my_label
Returns a list of all the vertices in the graph.
NOTE: You should be careful when using this on large graphs, as the list it produces contains every vertex on the graph. I have not yet verified whether Erlang ensures that they are a shared reference with the original, or copies, but if the latter it could result in running out of memory if the graph is too large.
Example
iex> g = Graph.new |> Graph.add_vertex(:a) |> Graph.add_vertex(:b)
...> Graph.vertices(g)
[:a, :b]
Walks the graph by starting with a depth-first traversal, the walk function receives the current vertex, it’s out-neighbors and in-neighbors (as lists of Edge structs), and the accumulator. You can return one of the following to control the walk:
{:next, acc}
, continues the depth-first traversal, passing along the accumulator{:next, v, acc}
, continues the traversal fromv
, passing along the accumulator{:skip, acc}
, skips traversal of the current vertex’s out-neighbors, passing along the accumulator{:halt, acc}
, stops the traversal, returning the accumulator
You can use this function to implement your own traversals of the graph, and as a foundation for reducers of your own design.
NOTE: If you take control over the direction of the traversal, take care that you handle cycles correctly, or you may end up following cycles indefinitely.
Options
walk/3
can also be provided with an options list, the current options available are:
algorithm: :breadth_first | :depth_first
, performs the traversal using the selected algorithm. The default is:depth_first
.
See Graph.Reducer.walk/4
.