Algebra.Graph.Class

Alga is a library for algebraic construction and manipulation of graphs in Haskell. See this paper for the motivation behind the library, the underlying theory, and implementation details.

This module defines the core type class Graph, a few graph subclasses, and basic polymorphic graph construction primitives. Functions that cannot be implemented fully polymorphically and require the use of an intermediate data type are not included. For example, to compute the number of vertices in a Graph expression you will need to use a concrete data type, such as Algebra.Graph.Fold. Other useful Graph instances are defined in Algebra.Graph, Algebra.Graph.AdjacencyMap and Algebra.Graph.Relation.

See Algebra.Graph.HigherKinded.Class for the higher-kinded version of the core graph type class.

The core type class

class Graph g where

The core type class for constructing algebraic graphs, characterised by the following minimal set of axioms. In equations we use + and * as convenient shortcuts for overlay and connect, respectively.

• overlay is commutative and associative:

        x + y == y + x
  x + (y + z) == (x + y) + z

• connect is associative and has empty as the identity:

    x * empty == x
    empty * x == x
  x * (y * z) == (x * y) * z

• connect distributes over overlay:

  x * (y + z) == x * y + x * z
  (x + y) * z == x * z + y * z

• connect can be decomposed:

  x * y * z == x * y + x * z + y * z

The following useful theorems can be proved from the above set of axioms.

• overlay has empty as the identity and is idempotent:

    x + empty == x
    empty + x == x
        x + x == x

• Absorption and saturation of connect:

  x * y + x + y == x * y
      x * x * x == x * x

The core type class Graph corresponds to unlabelled directed graphs. Undirected, Reflexive, Transitive and Preorder graphs can be obtained by extending the minimal set of axioms.

When specifying the time and memory complexity of graph algorithms, n will denote the number of vertices in the graph, m will denote the number of edges in the graph, and s will denote the size of the corresponding Graph expression.

Minimal complete definition

empty, vertex, overlay, connect

Associated Types

type Vertex g

The type of graph vertices.

Methods

empty :: g

Construct the empty graph.

vertex :: Vertex g -> g

Construct the graph with a single vertex.

overlay :: g -> g -> g

Overlay two graphs.

connect :: g -> g -> g

Connect two graphs.

Instances

Graph ()

Defined in Algebra.Graph.Class

Associated Types

type Vertex () :: *

Methods

empty :: ()

vertex :: Vertex () -> ()

overlay :: () -> () -> ()

connect :: () -> () -> ()

Graph AdjacencyIntMap

Defined in Algebra.Graph.Class

Associated Types

type Vertex AdjacencyIntMap :: *

Methods

empty :: AdjacencyIntMap

vertex :: Vertex AdjacencyIntMap -> AdjacencyIntMap

overlay :: AdjacencyIntMap -> AdjacencyIntMap -> AdjacencyIntMap

connect :: AdjacencyIntMap -> AdjacencyIntMap -> AdjacencyIntMap

Graph g => Graph (Maybe g)

Defined in Algebra.Graph.Class

Associated Types

type Vertex (Maybe g) :: *

Methods

empty :: Maybe g

vertex :: Vertex (Maybe g) -> Maybe g

overlay :: Maybe g -> Maybe g -> Maybe g

connect :: Maybe g -> Maybe g -> Maybe g

Ord a => Graph (AdjacencyMap a)

Defined in Algebra.Graph.Class

Associated Types

type Vertex (AdjacencyMap a) :: *

Methods

empty :: AdjacencyMap a

vertex :: Vertex (AdjacencyMap a) -> AdjacencyMap a

overlay :: AdjacencyMap a -> AdjacencyMap a -> AdjacencyMap a

connect :: AdjacencyMap a -> AdjacencyMap a -> AdjacencyMap a

Ord a => Graph (Relation a)

Defined in Algebra.Graph.Class

Associated Types

type Vertex (Relation a) :: *

Methods

empty :: Relation a

vertex :: Vertex (Relation a) -> Relation a

overlay :: Relation a -> Relation a -> Relation a

connect :: Relation a -> Relation a -> Relation a

Graph (Graph a)

Defined in Algebra.Graph.Class

Associated Types

type Vertex (Graph a) :: *

Methods

empty :: Graph a

vertex :: Vertex (Graph a) -> Graph a

overlay :: Graph a -> Graph a -> Graph a

connect :: Graph a -> Graph a -> Graph a

Graph (Fold a)

Defined in Algebra.Graph.Class

Associated Types

type Vertex (Fold a) :: *

Methods

empty :: Fold a

vertex :: Vertex (Fold a) -> Fold a

overlay :: Fold a -> Fold a -> Fold a

connect :: Fold a -> Fold a -> Fold a

Ord a => Graph (PreorderRelation a)

Defined in Algebra.Graph.Relation.InternalDerived

Associated Types

type Vertex (PreorderRelation a) :: *

Methods

empty :: PreorderRelation a

vertex :: Vertex (PreorderRelation a) -> PreorderRelation a

overlay :: PreorderRelation a -> PreorderRelation a -> PreorderRelation a

connect :: PreorderRelation a -> PreorderRelation a -> PreorderRelation a

Ord a => Graph (TransitiveRelation a)

Defined in Algebra.Graph.Relation.InternalDerived

Associated Types

type Vertex (TransitiveRelation a) :: *

Methods

empty :: TransitiveRelation a

vertex :: Vertex (TransitiveRelation a) -> TransitiveRelation a

overlay :: TransitiveRelation a -> TransitiveRelation a -> TransitiveRelation a

connect :: TransitiveRelation a -> TransitiveRelation a -> TransitiveRelation a

Ord a => Graph (SymmetricRelation a)

Defined in Algebra.Graph.Relation.InternalDerived

Associated Types

type Vertex (SymmetricRelation a) :: *

Methods

empty :: SymmetricRelation a

vertex :: Vertex (SymmetricRelation a) -> SymmetricRelation a

overlay :: SymmetricRelation a -> SymmetricRelation a -> SymmetricRelation a

connect :: SymmetricRelation a -> SymmetricRelation a -> SymmetricRelation a

Ord a => Graph (ReflexiveRelation a)

Defined in Algebra.Graph.Relation.InternalDerived

Associated Types

type Vertex (ReflexiveRelation a) :: *

Methods

empty :: ReflexiveRelation a

vertex :: Vertex (ReflexiveRelation a) -> ReflexiveRelation a

overlay :: ReflexiveRelation a -> ReflexiveRelation a -> ReflexiveRelation a

connect :: ReflexiveRelation a -> ReflexiveRelation a -> ReflexiveRelation a

Graph g => Graph (a -> g)

Defined in Algebra.Graph.Class

Associated Types

type Vertex (a -> g) :: *

Methods

empty :: a -> g

vertex :: Vertex (a -> g) -> a -> g

overlay :: (a -> g) -> (a -> g) -> a -> g

connect :: (a -> g) -> (a -> g) -> a -> g

(Graph g, Graph h) => Graph (g, h)

Defined in Algebra.Graph.Class

Associated Types

type Vertex (g, h) :: *

Methods

empty :: (g, h)

vertex :: Vertex (g, h) -> (g, h)

overlay :: (g, h) -> (g, h) -> (g, h)

connect :: (g, h) -> (g, h) -> (g, h)

Dioid e => Graph (Graph e a)

Defined in Algebra.Graph.Labelled

Associated Types

type Vertex (Graph e a) :: *

Methods

empty :: Graph e a

vertex :: Vertex (Graph e a) -> Graph e a

overlay :: Graph e a -> Graph e a -> Graph e a

connect :: Graph e a -> Graph e a -> Graph e a

(Graph g, Graph h, Graph i) => Graph (g, h, i)

Defined in Algebra.Graph.Class

Associated Types

type Vertex (g, h, i) :: *

Methods

empty :: (g, h, i)

vertex :: Vertex (g, h, i) -> (g, h, i)

overlay :: (g, h, i) -> (g, h, i) -> (g, h, i)

connect :: (g, h, i) -> (g, h, i) -> (g, h, i)

Undirected graphs

class Graph g => Undirected g

The class of undirected graphs that satisfy the following additional axiom.

• connect is commutative:

  x * y == y * x

Instances

Undirected ()

Defined in Algebra.Graph.Class

Undirected g => Undirected (Maybe g)

Defined in Algebra.Graph.Class

Ord a => Undirected (SymmetricRelation a)

Defined in Algebra.Graph.Relation.InternalDerived

Undirected g => Undirected (a -> g)

Defined in Algebra.Graph.Class

(Undirected g, Undirected h) => Undirected (g, h)

Defined in Algebra.Graph.Class

(Undirected g, Undirected h, Undirected i) => Undirected (g, h, i)

Defined in Algebra.Graph.Class

Reflexive graphs

class Graph g => Reflexive g

The class of reflexive graphs that satisfy the following additional axiom.

• Each vertex has a self-loop:

  vertex x == vertex x * vertex x

Note that by applying the axiom in the reverse direction, one can always remove all self-loops resulting in an irreflexive graph. This type class can therefore be also used in the context of irreflexive graphs.

Instances

Reflexive ()

Defined in Algebra.Graph.Class

Reflexive g => Reflexive (Maybe g)

Defined in Algebra.Graph.Class

Ord a => Reflexive (PreorderRelation a)

Defined in Algebra.Graph.Relation.InternalDerived

Ord a => Reflexive (ReflexiveRelation a)

Defined in Algebra.Graph.Relation.InternalDerived

Reflexive g => Reflexive (a -> g)

Defined in Algebra.Graph.Class

(Reflexive g, Reflexive h) => Reflexive (g, h)

Defined in Algebra.Graph.Class

(Reflexive g, Reflexive h, Reflexive i) => Reflexive (g, h, i)

Defined in Algebra.Graph.Class

Transitive graphs

class Graph g => Transitive g

The class of transitive graphs that satisfy the following additional axiom.

• The closure axiom: graphs with equal transitive closures are equal.

  y /= empty ==> x * y + x * z + y * z == x * y + y * z

By repeated application of the axiom one can turn any graph into its transitive closure or transitive reduction.

Instances

Transitive ()

Defined in Algebra.Graph.Class

Transitive g => Transitive (Maybe g)

Defined in Algebra.Graph.Class

Ord a => Transitive (PreorderRelation a)

Defined in Algebra.Graph.Relation.InternalDerived

Ord a => Transitive (TransitiveRelation a)

Defined in Algebra.Graph.Relation.InternalDerived

Transitive g => Transitive (a -> g)

Defined in Algebra.Graph.Class

(Transitive g, Transitive h) => Transitive (g, h)

Defined in Algebra.Graph.Class

(Transitive g, Transitive h, Transitive i) => Transitive (g, h, i)

Defined in Algebra.Graph.Class

Preorders

class (Reflexive g, Transitive g) => Preorder g

The class of preorder graphs that are both reflexive and transitive.

Instances

Preorder ()

Defined in Algebra.Graph.Class

Preorder g => Preorder (Maybe g)

Defined in Algebra.Graph.Class

Ord a => Preorder (PreorderRelation a)

Defined in Algebra.Graph.Relation.InternalDerived

Preorder g => Preorder (a -> g)

Defined in Algebra.Graph.Class

(Preorder g, Preorder h) => Preorder (g, h)

Defined in Algebra.Graph.Class

(Preorder g, Preorder h, Preorder i) => Preorder (g, h, i)

Defined in Algebra.Graph.Class

Basic graph construction primitives

edge :: Graph g => Vertex g -> Vertex g -> g

Construct the graph comprising a single edge. Complexity: O(1) time, memory and size.

edge x y == connect (vertex x) (vertex y)

vertices :: Graph g => [Vertex g] -> g

Construct the graph comprising a given list of isolated vertices. Complexity: O(L) time, memory and size, where L is the length of the given list.

vertices []  == empty
vertices [x] == vertex x

overlays :: Graph g => [g] -> g

Overlay a given list of graphs. Complexity: O(L) time and memory, and O(S) size, where L is the length of the given list, and S is the sum of sizes of the graphs in the list.

overlays []    == empty
overlays [x]   == x
overlays [x,y] == overlay x y
overlays       == foldr overlay empty

connects :: Graph g => [g] -> g

Connect a given list of graphs. Complexity: O(L) time and memory, and O(S) size, where L is the length of the given list, and S is the sum of sizes of the graphs in the list.

connects []    == empty
connects [x]   == x
connects [x,y] == connect x y
connects       == foldr connect empty

edges :: Graph g => [(Vertex g, Vertex g)] -> g

Construct the graph from a list of edges. Complexity: O(L) time, memory and size, where L is the length of the given list.

edges []      == empty
edges [(x,y)] == edge x y

Relations on graphs

isSubgraphOf :: (Graph g, Eq g) => g -> g -> Bool

The isSubgraphOf function takes two graphs and returns True if the first graph is a subgraph of the second. Here is the current implementation:

isSubgraphOf x y = overlay x y == y

The complexity therefore depends on the complexity of equality testing of the specific graph instance.

isSubgraphOf empty         x             == True
isSubgraphOf (vertex x)    empty         == False
isSubgraphOf x             (overlay x y) == True
isSubgraphOf (overlay x y) (connect x y) == True
isSubgraphOf (path xs)     (circuit xs)  == True

Standard families of graphs

path :: Graph g => [Vertex g] -> g

The path on a list of vertices. Complexity: O(L) time, memory and size, where L is the length of the given list.

path []    == empty
path [x]   == vertex x
path [x,y] == edge x y

circuit :: Graph g => [Vertex g] -> g

The circuit on a list of vertices. Complexity: O(L) time, memory and size, where L is the length of the given list.

circuit []    == empty
circuit [x]   == edge x x
circuit [x,y] == edges [(x,y), (y,x)]

clique :: Graph g => [Vertex g] -> g

The clique on a list of vertices. Complexity: O(L) time, memory and size, where L is the length of the given list.

clique []         == empty
clique [x]        == vertex x
clique [x,y]      == edge x y
clique [x,y,z]    == edges [(x,y), (x,z), (y,z)]
clique (xs ++ ys) == connect (clique xs) (clique ys)

biclique :: Graph g => [Vertex g] -> [Vertex g] -> g

The biclique on two lists of vertices. Complexity: O(L1 + L2) time, memory and size, where L1 and L2 are the lengths of the given lists.

biclique []      []      == empty
biclique [x]     []      == vertex x
biclique []      [y]     == vertex y
biclique [x1,x2] [y1,y2] == edges [(x1,y1), (x1,y2), (x2,y1), (x2,y2)]
biclique xs      ys      == connect (vertices xs) (vertices ys)

star :: Graph g => Vertex g -> [Vertex g] -> g

The star formed by a centre vertex connected to a list of leaves. Complexity: O(L) time, memory and size, where L is the length of the given list.

star x []    == vertex x
star x [y]   == edge x y
star x [y,z] == edges [(x,y), (x,z)]
star x ys    == connect (vertex x) (vertices ys)

starTranspose :: Graph g => Vertex g -> [Vertex g] -> g

The star transpose formed by a list of leaves connected to a centre vertex. Complexity: O(L) time, memory and size, where L is the length of the given list.

starTranspose x []    == vertex x
starTranspose x [y]   == edge y x
starTranspose x [y,z] == edges [(y,x), (z,x)]
starTranspose x ys    == connect (vertices ys) (vertex x)
starTranspose x ys    == transpose (star x ys)

tree :: Graph g => Tree (Vertex g) -> g

The tree graph constructed from a given Tree data structure. Complexity: O(T) time, memory and size, where T is the size of the given tree (i.e. the number of vertices in the tree).

tree (Node x [])                                         == vertex x
tree (Node x [Node y [Node z []]])                       == path [x,y,z]
tree (Node x [Node y [], Node z []])                     == star x [y,z]
tree (Node 1 [Node 2 [], Node 3 [Node 4 [], Node 5 []]]) == edges [(1,2), (1,3), (3,4), (3,5)]

forest :: Graph g => Forest (Vertex g) -> g

The forest graph constructed from a given Forest data structure. Complexity: O(F) time, memory and size, where F is the size of the given forest (i.e. the number of vertices in the forest).

forest []                                                  == empty
forest [x]                                                 == tree x
forest [Node 1 [Node 2 [], Node 3 []], Node 4 [Node 5 []]] == edges [(1,2), (1,3), (4,5)]
forest                                                     == overlays . map tree