Dimensionality

A periodic graph g of type PeriodicGraph{N} has dimension N, which means that its unit cell is repeated across N independent axes. However, this number may be larger than the actual number of independent axes necessary to describe the repeating unit of the graph, which we will call the dimensionality. For example, consider an infinite set of identical 2-periodic graphs stacked across a third dimension: the resulting graph is of dimension 3, but its dimensionality is 2 (or below) because all the topological information is stored in the 2-periodic subgraph.

The connected components of g can be separated and sorted by dimensionality using the dimensionality function:

PeriodicGraphs.dimensionality — Function

dimensionality(g::PeriodicGraph{N}) where N

Determine the actual dimension of each connected component of g. Return a dictionary where each entry n => [(l1,m1), (l2,m2), ...] means that li is a list of vertices that form a connected component of dimension n, and that component is present mi times per unit cell.

In other words, the connected component li has a periodicity that can only be expressed in a unit cell mi times larger than the current one. See also split_catenation.

Examples

julia> dimensionality(PeriodicGraph("2   1 1  1 0   2 2  -1 1   3 3  1 0   3 3  0 1"))
Dict{Int64, Vector{Tuple{Vector{Int64}, Int64}}} with 2 entries:
  2 => [([3], 1)]
  1 => [([1], 1), ([2], 1)]

julia> dimensionality(PeriodicGraph("1   1 1  2"))
Dict{Int64, Vector{Tuple{Vector{Int64}, Int64}}} with 1 entry:
  1 => [([1], 2)]

source

See also split_catenation to split connected components in a more detailed fashion, when multiple components can share the same vertex indices:

PeriodicGraphs.split_catenation — Function

split_catenation(graph::PeriodicGraph{N}) where N

Return a list of tuples (subgraph, vmaps, mat, dim) where subgraph is a connected component of the input graph. Each sublist vmap in vmaps is a distinct mapping of the vertices of the graph into those of the corresponding subgraph. The union of all the vertices in all the vmaps, repeated with the according periodicity, exactly covers all the vertices of the input graph, without repetition. dim is the dimensionality of these connected components, and mat is the transformation matrix between the input cell and the component's cell.

Each sublist contains connected components that share the same vertex indices.

Example

julia> g = PeriodicGraph("2    1 1  3 0   1 1  0 1   2 3  1 0   3 2  1 0");

julia> dimensionality(g)
Dict{Int64, Vector{Tuple{Vector{Int64}, Int64}}} with 2 entries:
  2 => [([1], 3)]
  1 => [([2, 3], 2)]

julia> splits = split_catenation(g);

julia> last.(splits) # One 2-dimensional catenation (vertex 1), one 1-dimensional (vertices 2 and 3)
2-element Vector{Int64}:
 2
 1

julia> subgraph, vmaps, mat, dim = last(splits);  # the 1-dimensional connected components

julia> vmaps  # first sublist takes vertex 2 from the reference unit cell, second one takes vertex 3.
2-element Vector{PeriodicGraphs.OffsetVertexIterator{2}}:
 [(2, (0,0)), (3, (-1,0))]
 [(2, (1,0)), (3, (0,0))]

julia> subgraph  # the subgraph consists in only the two relevant two vertices
PeriodicGraph2D(2, PeriodicEdge2D[(1, 2, (0,0)), (1, 2, (1,0))])

julia> mat  # the new cell is twice as large as the initial one
2×2 SMatrix{2, 2, Int64, 4} with indices SOneTo(2)×SOneTo(2):
 2  0
 0  1

source

To transpose a graph from one dimension N to another D, call the type constructor PeriodicGraph{D} directly on g::PeriodicGraph{N}. This can be useful to manipulate a graph of dimensionality D as a graph of actual dimension D, which often reduces computational costs.

PeriodicGraphs.PeriodicGraph — Method

PeriodicGraph{D}(graph::PeriodicGraph{N}) where {D,N}

Return a graph that has the same structural information as the input graph but embedded in D dimensions instead of N. It will fail if the dimensionality of the graph is greater than D.

Note

The behaviour is undefined if D < N and there are multiple non-identical connected components. In particular, the function is expected to fail if these components do not share the same orientation.

source

For example, the following function extracts the list of 1-dimensional components from a given PeriodicGraph:

julia> function extract_1D_components(g::PeriodicGraph{D}) where D
           d = dimensionality(g)
           components1D = get(d, 1, Vector{Int}[])
           return [PeriodicGraph1D(g[l]) for l in components1D]
       end
extract_1D_components (generic function with 1 method)

Let's test it on the following 2-periodic graph, which has one 0D component (vertices 4 and 5), two 1D components (vertex 3 alone and vertices 6 and 7 together) and one 2D component (vertices 1 and 2):

julia> g = PeriodicGraph2D("2   1 2 0 0  2 1 1 0  2 1 0 1
                                3 3 1 0
                                4 5 0 0
                                6 7 1 0  7 6 1 0
                           ")
PeriodicGraph2D(7, PeriodicEdge2D[(1, 2, (-1,0)), (1, 2, (0,-1)), (1, 2, (0,0)), (3, 3, (1,0)), (4, 5, (0,0)), (6, 7, (-1,0)), (6, 7, (1,0))])

julia> extract_1D_components(g)
2-element Vector{PeriodicGraph1D}:
 PeriodicGraph1D(1, PeriodicEdge1D[(1, 1, (1,))])
 PeriodicGraph1D(2, PeriodicEdge1D[(1, 2, (-1,)), (1, 2, (1,))])

The first subgraph corresponds to g[[3]] and the second to g[[6,7]], both converted to PeriodicGraph1D.

The dimension of a graph can also be reduced with loss of information through the slice_graph function.