Constructors for decorated graphs

[JoeyT1994]

We should think about having construction methods for decorated graphs.

E.g. given a named graph g we have some function like

decorate_graph(g::NamedGraph, edge_map::Function)

where edge_map::Function is a map which takes an edge of g e and outputs the namedgraph which will then be inserted along e in the original graph g,

For example something like

g = named_grid((L,L))
g_dec = decorate_graph(g::NamedGraph, e -> named_grid((1)))

would build the L x L Lieb lattice by inserting a single vertex along the edges of the regular square lattice.

Obviously we would have to think about how to name the new vertices that have been added to g and also how to specify which vertices of the inserted graph connect to src(e) and dst(e) (perhaps by defaulting to the first vertex of the decorated graph with additional specification if desired).

[mtfishman]

We could have a naming convention like (e, v) where e is the edge where the edge decoration graph is being inserted and v is the name of the vertex of the edge decoration graph. Or it is just up to the user to specify names based on the edge input, for example:

g = named_grid((L,L))
function edge_decoration_graph(e)
  g_e = named_graph()
  add_vertex!(g_e, src(e))
  add_vertex!(g_e, (e, 1))
  add_vertex!(g_e, dst(e))
  add_edge!(g_e, src(e), (e, 1))
  add_edge!(g_e, (e, 1), dst(e))
  return g_e
end
g_dec = decorate_graph(g::NamedGraph; edge_decoration=edge_decoration_graph)

but the convention of automatically adding an edge from src(e) to the first vertex and an edge from the last vertex to dst(e) could make sense, obviously that makes defining the edge decoration graphs simpler.

Also a complementary functionality would be to replace the vertices of a graph with a vertex decoration graph, for example:

function vertex_decoration_graph(v)
  g_v = named_graph()
  # ...
end
g_dec = decorate_graph(g::NamedGraph; vertex_decoration=vertex_decoration_graph)

[JoeyT1994]

I think that naming convention makes the most sense and we should have that as default. Also having vertex replacement makes sense too

[JoeyT1994]

I just realised that with this we would create the 127-qubit IBM heavy hex lattice as follows:

g_hex = hexagonal_lattice_graph(3, 5)
g_heavy_hex = decorate_graph(g_hex; edge_decoration=e -> named_grid((1)))
#Line of code that adds two additional qubits to the top right and top left of the lattice

hexagonal_lattice_graph(m::Int64, n::Int64) is a function I added in PR #35 that creates an m by n lattice of hexagons. Inserting an extra vertex on each edge creates the heavy hex geometry (with loops of size 12).

Super neat when code comes together like that.

[mtfishman]

Closed by #37.