BlockGraph#

class tqec.computation.BlockGraph(name='')[source]#

Bases: ComputationGraph[Cube, Pipe]

Block graph representation of a logical computation.

A block graph consists of building blocks that fully define the boundary conditions and topological structures of a logical computation. It corresponds to the commonly used 3D spacetime diagram representation of a surface code logical computation.

The graph contains two categories of blocks:

1. Cube: The fundamental building blocks of the computation. A cube represents a block of quantum operations within a specific spacetime volume. These operations preserve or manipulate the quantum information encoded in the logical qubits. Cubes are represented as nodes in the graph.

2. Pipe: Connects cubes to form the topological structure representing the logical computation. A pipe occupies no spacetime volume and only replaces the operations within the cubes it connects. Pipes are represented as edges in the graph.

Methods

__init__([name])

add_edge(u, v[, kind])

Add an edge to the graph.

add_node(node[, check_conflict])

Add a node to the graph.

copy()

Create a data-independent copy of the graph.

edges_at(position)

Get the edges incident to a position.

find_correlation_surfaces()

Get the ~tqec.computation.correlation.CorrelationSurface from the corresponding ZXGraph of the block graph.

from_dae_file(filename[, graph_name])

Construct a block graph from a COLLADA DAE file.

get_degree(position)

Get the degree of a node in the graph, i.e. the number of edges incident to it.

get_edge(pos1, pos2)

Get the edge by its endpoint positions.

has_edge_between(pos1, pos2)

Check if there is an edge between two positions.

rotate([rotation_axis, ...])

Rotate the graph around an axis by num_90_degree_rotation * 90 degrees and return a new rotated graph.

shift_min_z_to_zero()

Shift the whole graph in the z direction to make the minimum z equal zero.

to_dae_file(file_path[, pipe_length, ...])

Write the block graph to a Collada DAE file.

to_zx_graph([name])

Convert the block graph to a ZXGraph.

validate()

Check the validity of the block graph to represent a logical computation.

view_as_html([write_html_filepath, ...])

View COLLADA model in html with the help of three.js.

Attributes

edges

The list of edges in the graph.

leaf_nodes

Get the leaf nodes of the graph, i.e. the nodes with degree 1.

name

Name of the graph.

nodes

The list of nodes in the graph.

num_edges

Number of edges in the graph.

num_nodes

Number of nodes in the graph.

num_ports

Number of ports in the graph.

ports

Mapping from port labels to their positions.

Detailed methods

Parameters:

name (str)

__init__(name='')#
Parameters:

name (str)

Return type:

None

add_edge(u, v, kind=None)[source]#

Add an edge to the graph. If the nodes of the edge do not exist in the graph, the nodes will be created and added to the graph.

Parameters:

  • u (Cube) – The cube on one end of the edge.

  • v (Cube) – The cube on the other end of the edge.

  • kind (PipeKind | None) – The kind of the pipe connecting the cubes. If None, the kind will be automatically determined based on the cubes it connects to make the boundary conditions consistent. Default is None.

Raises:

TQECException – For each node in the edge, if there is already a node which is not equal to it at the same position, or the node is a port but there is already a different port with the same label in the graph.

Return type:

None

add_node(node, check_conflict=True)#

Add a node to the graph.

Parameters:

  • node (_NODE) – The node to add to the graph.

  • check_conflict (bool) –

    Whether to check for conflicts before adding the node. If set to True, either one of the following two circumstances will raise an exception:

    1. There is already a node which is not equal to this one at the same position.

    2. The node is a port but there is already a different port with the same label in the graph.

    Otherwise, an existing node at the same position will be overwritten. Defaults to True.

Raises:

TQECException – If check_conflict is True and there is a conflict when adding the node.

Return type:

None

copy()#

Create a data-independent copy of the graph.

Return type:

Self

edges_at(position)#

Get the edges incident to a position.

Parameters:

position (Position3D)

Return type:

list[_EDGE]

find_correlation_surfaces()[source]#

Get the ~tqec.computation.correlation.CorrelationSurface from the corresponding ZXGraph of the block graph.

Returns:

The list of correlation surfaces.

Return type:

list[CorrelationSurface]

static from_dae_file(filename, graph_name='')[source]#

Construct a block graph from a COLLADA DAE file.

Parameters:

  • filename (str | Path) – The input .dae file path.

  • graph_name (str) – The name of the block graph. Default is an empty string.

Returns:

The BlockGraph object constructed from the DAE file.

Return type:

BlockGraph

get_degree(position)#

Get the degree of a node in the graph, i.e. the number of edges incident to it.

Parameters:

position (Position3D)

Return type:

int

get_edge(pos1, pos2)#

Get the edge by its endpoint positions. If there is no edge between the given positions, an exception will be raised.

Parameters:

  • pos1 (Position3D) – The first endpoint position.

  • pos2 (Position3D) – The second endpoint position.

Returns:

The edge between the two positions.

Raises:

TQECException – If there is no edge between the given positions.

Return type:

_EDGE

has_edge_between(pos1, pos2)#

Check if there is an edge between two positions.

Parameters:

  • pos1 (Position3D) – The first endpoint position.

  • pos2 (Position3D) – The second endpoint position.

Returns:

True if there is an edge between the two positions, False otherwise.

Return type:

bool

rotate(rotation_axis=Direction3D.Y, num_90_degree_rotation=1, counterclockwise=True)[source]#

Rotate the graph around an axis by num_90_degree_rotation * 90 degrees and return a new rotated graph.

Parameters:

  • rotation_axis (Direction3D) – The axis around which to rotate the graph.

  • num_90_degree_rotation (int) – The number of 90-degree rotations to apply to the graph.

  • counterclockwise (bool) – Whether to rotate the graph counterclockwise. If set to False, the graph will be rotated clockwise. Defaults to True.

Returns:

A data-independent copy of the graph rotated by the given number of 90-degree rotations.

Return type:

BlockGraph

shift_min_z_to_zero()[source]#

Shift the whole graph in the z direction to make the minimum z equal zero.

Returns:

A new graph with the minimum z position of the cubes equal to zero. The new graph will share no data with the original graph.

Return type:

BlockGraph

to_dae_file(file_path, pipe_length=2.0, pop_faces_at_direction=None, show_correlation_surface=None)[source]#

Write the block graph to a Collada DAE file.

Parameters:

  • file_path (str | Path) – The output file path.

  • pipe_length (float) – The length of the pipes. Default is 2.0.

  • pop_faces_at_direction (SignedDirection3D | None) – Remove the faces at the given direction for all the blocks. This is useful for visualizing the internal structure of the blocks. Default is None.

  • show_correlation_surface (CorrelationSurface | None) – The correlation surface to show in the block graph. Default is None.

Return type:

None

to_zx_graph(name=None)[source]#

Convert the block graph to a ZXGraph.

The conversion process is as follows:

  1. For each cube in the block graph, convert it to a ZX node by calling to_zx_node().

  2. For each pipe in the block graph, add an edge to the ZX graph with the corresponding endpoints and Hadamard flag.

Parameters:

  • block_graph – The block graph to be converted to a ZX graph.

  • name (str | None) – The name of the new ZX graph. If None, the name of the block graph will be used.

Returns:

The ZXGraph object converted from the block graph.

Return type:

ZXGraph

validate()[source]#

Check the validity of the block graph to represent a logical computation.

Refer to the Fig.9 in arXiv:2404.18369. Currently, we ignore the b) and e), only check the following conditions:

  • No fanout: ports can only have one pipe connected to them.

  • Time-like Y: Y cubes can only have time-like pipes connected to them.

  • No 3D corner: a cube cannot have pipes in all three directions.

  • Match color at passthrough: two pipes in a “pass-through” should have the same color orientation.

  • Match color at turn: two pipes in a “turn” should have the matching colors on faces that are touching.

Raises:

TQECException – If the above conditions are not satisfied.

Return type:

None

view_as_html(write_html_filepath=None, pipe_length=2.0, pop_faces_at_direction=None, show_correlation_surface=None)[source]#

View COLLADA model in html with the help of three.js.

This can display a COLLADA model interactively in IPython compatible environments.

Parameters:

  • write_html_filepath (str | pathlib.Path | None) – The output html file path to write the generated html content if provided. Default is None.

  • pipe_length (float) – The length of the pipes. Default is 2.0.

  • pop_faces_at_direction (SignedDirection3D | None) – Remove the faces at the given direction for all the blocks. This is useful for visualizing the internal structure of the blocks. Default is None.

  • show_correlation_surface (CorrelationSurface | None) – The correlation surface to show in the block graph. Default is None.

Returns:

A helper class to display the 3D model, which implements the _repr_html_ method and can be directly displayed in IPython compatible environments.

Return type:

_ColladaHTMLViewer