GraphState

graphqomb.graphstate module

Graph State classes for Measurement-based Quantum Computing.

This module provides:

• BaseGraphState: Abstract base class for Graph State.

• GraphState: Minimal implementation of Graph State.

• LocalCliffordExpansion: Local Clifford expansion.

• ExpansionMaps: Expansion maps for local clifford operators.

• compose: Function to compose two graph states sequentially.

• bipartite_edges: Function to create a complete bipartite graph between two sets of nodes.

• odd_neighbors: Function to get odd neighbors of a node.

Graph State Classes

class graphqomb.graphstate.BaseGraphState

Abstract base class for Graph State.

abstract property input_node_indices: dict[int, int]

Return map of input nodes to logical qubit indices.

Returns:

qubit indices map of input nodes.

Return type:

dict[int, int]

abstract property output_node_indices: dict[int, int]

Return map of output nodes to logical qubit indices.

Returns:

qubit indices map of output nodes.

Return type:

dict[int, int]

abstract property physical_nodes: set[int]

Return set of physical nodes.

Returns:

set of physical nodes.

Return type:

set[int]

abstract property physical_edges: set[tuple[int, int]]

Return set of physical edges.

Returns:

set of physical edges.

Return type:

set[tuple[int, int]`

abstract property meas_bases: MappingProxyType

Return measurement bases.

Returns:

measurement bases of each physical node.

Return type:

types.MappingProxyType[int, MeasBasis]

abstractmethod add_physical_node(coordinate=None)

Add a physical node to the graph state.

Parameters:

coordinate (tuple[float, …] | None, optional) – coordinate tuple (2D or 3D), by default None

Returns:

The node index internally generated

Return type:

int

abstractmethod add_physical_edge(node1, node2)

Add a physical edge to the graph state.

Parameters:

• node1 (int) – node index

• node2 (int) – node index

abstractmethod register_input(node, q_index)

Mark the node as an input node.

Parameters:

• node (int) – node index

• q_index (int) – logical qubit index

abstractmethod register_output(node, q_index)

Mark the node as an output node.

Parameters:

• node (int) – node index

• q_index (int) – logical qubit index

abstractmethod assign_meas_basis(node, meas_basis)

Assign the measurement basis of the node.

Parameters:

• node (int) – node index

• meas_basis (MeasBasis) – measurement basis

abstractmethod neighbors(node)

Return the neighbors of the node.

Parameters:

node (int) – node index

Returns:

set of neighboring nodes

Return type:

set[int]

abstractmethod check_canonical_form()

Check if the graph state is in canonical form.

abstract property coordinates: dict[int, tuple[float, ...]]

Return node coordinates.

Returns:

mapping from node index to coordinate tuple (2D or 3D)

Return type:

dict[int, tuple[float, …]]

class graphqomb.graphstate.GraphState

Bases: BaseGraphState

Minimal implementation of GraphState.

__init__()

property input_node_indices: dict[int, int]

Return map of input nodes to logical qubit indices.

Returns:

qubit indices map of input nodes.

Return type:

dict[int, int]

property output_node_indices: dict[int, int]

Return map of output nodes to logical qubit indices.

Returns:

qubit indices map of output nodes.

Return type:

dict[int, int]

property physical_nodes: set[int]

Return set of physical nodes.

Returns:

set of physical nodes.

Return type:

set[int]

property physical_edges: set[tuple[int, int]]

Return set of physical edges.

Returns:

set of physical edges.

Return type:

set[tuple[int, int]

property meas_bases: MappingProxyType

Return measurement bases.

Returns:

measurement bases of each physical node.

Return type:

types.MappingProxyType[int, MeasBasis]

property local_cliffords: dict[int, LocalClifford]

Return local clifford nodes.

Returns:

local clifford nodes.

Return type:

dict[int, LocalClifford]

property coordinates: dict[int, tuple[float, ...]]

Return node coordinates.

Returns:

mapping from node index to coordinate tuple (2D or 3D)

Return type:

dict[int, tuple[float, …]]

set_coordinate(node, coord)

Set coordinate for a node.

Parameters:

• node (int) – node index

• coord (tuple[float, …]) – coordinate tuple (2D or 3D)

add_physical_node(coordinate=None)

Add a physical node to the graph state.

Parameters:

coordinate (tuple[float, …] | None, optional) – coordinate tuple (2D or 3D), by default None

Returns:

The node index internally generated.

Return type:

int

add_physical_edge(node1, node2)

Add a physical edge to the graph state.

Parameters:

• node1 (int) – node index

• node2 (int) – node index

Raises:

ValueError –

1. If the node does not exist. 2. If the edge already exists. 3. If the edge is a self-loop.

remove_physical_node(node)

Remove a physical node from the graph state.

Parameters:

node (int) – node index to be removed

Raises:

ValueError – If the input node is specified

remove_physical_edge(node1, node2)

Remove a physical edge from the graph state.

Parameters:

• node1 (int) – node index

• node2 (int) – node index

Raises:

ValueError – If the edge does not exist.

register_input(node, q_index)

Mark the node as an input node.

Parameters:

• node (int) – node index

• q_index (int) – logical qubit index

Raises:

ValueError – If the node is already registered as an input node.

register_output(node, q_index)

Mark the node as an output node.

Parameters:

• node (int) – node index

• q_index (int) – logical qubit index

Raises:

ValueError –

1. If the node is already registered as an output node. 2. If the invalid q_index specified. 3. If the q_index already exists in output qubit indices.

assign_meas_basis(node, meas_basis)

Set the measurement basis of the node.

Parameters:

• node (int) – node index

• meas_basis (MeasBasis) – measurement basis

apply_local_clifford(node, lc)

Apply a local clifford to the node.

Parameters:

• node (int) – node index

• lc (LocalClifford) – local clifford operator

neighbors(node)

Return the neighbors of the node.

Parameters:

node (int) – node index

Returns:

set of neighboring nodes

Return type:

set[int]

check_canonical_form()

Check if the graph state is in canonical form.

The definition of canonical form is: 1. No Clifford operators applied. 2. All non-output nodes have measurement basis

Raises:

ValueError – If the graph state is not in canonical form.

expand_local_cliffords()

Expand local Clifford operators applied on the input and output nodes.

Returns:

A tuple of dictionaries mapping input and output node indices to the new node indices created.

Return type:

ExpansionMaps

classmethod from_graph(nodes, edges, inputs=None, outputs=None, meas_bases=None, coordinates=None)

Create a graph state from nodes and edges with arbitrary node types.

This factory method allows creating a graph state from any hashable node type (e.g., strings, tuples, custom objects). The method internally maps external node identifiers to integer indices used by GraphState.

Parameters:

• nodes (collections.abc.Iterable[NodeT]) – Nodes to add to the graph. Can be any hashable type.

• edges (collections.abc.Iterable[tuple[NodeT, NodeT]]) – Edges as pairs of node identifiers.

• inputs (collections.abc.Sequence[NodeT] | None, optional) – Input nodes in order. Qubit indices are assigned sequentially (0, 1, 2, …). Default is None (no inputs).

• outputs (collections.abc.Sequence[NodeT] | None, optional) – Output nodes in order. Qubit indices are assigned sequentially (0, 1, 2, …). Default is None (no outputs).

• meas_bases (collections.abc.Mapping[NodeT, MeasBasis] | None, optional) – Measurement bases for nodes. Nodes not specified can be set later. Default is None (no bases assigned initially).

• coordinates (collections.abc.Mapping[NodeT, tuple[float, …]] | None, optional) – Coordinates for nodes (2D or 3D). Default is None (no coordinates).

Returns:

• Created GraphState instance

• Mapping from external node IDs to internal integer indices

Return type:

tuple[GraphState, dict[NodeT, int]]

Raises:

ValueError – If duplicate nodes, invalid edges, or invalid input/output nodes.

classmethod from_base_graph_state(base, copy_local_cliffords=True)

Create a new GraphState from an existing BaseGraphState instance.

This method creates a complete copy of the graph structure, including nodes, edges, input/output registrations, and measurement bases. Useful for creating mutable copies or converting between GraphState implementations.

Parameters:

• base (BaseGraphState) – The source graph state to copy from.

• copy_local_cliffords (bool, optional) – Whether to copy local Clifford operators if the source is a GraphState. If True and the source has local Cliffords, they are copied. If False, local Cliffords are not copied (canonical form only). Default is True.

Returns:

• Created GraphState instance

• Mapping from source node indices to new node indices

Return type:

tuple[GraphState, dict[int, int]]

Functions

graphqomb.graphstate.compose(graph1, graph2)

Compose two graph states sequentially.

Qubits with matching indices are automatically connected. Graph2 is connected after graph1. All other qubit indices are preserved from their original graphs.

Parameters:

• graph1 (BaseGraphState) – first graph state

• graph2 (BaseGraphState) – second graph state

Returns:

composed graph state, node map for graph1, node map for graph2

Return type:

tuple[GraphState, dict[int, int], dict[int, int]]

Raises:

ValueError –

1. If the graph states are not in canonical form. 2. If there are qindex conflicts (same qindex used in both graphs but not for connection).

graphqomb.graphstate.bipartite_edges(node_set1, node_set2)

Return a set of edges for the complete bipartite graph between two sets of nodes.

Parameters:

• node_set1 (collections.abc.Set[int]) – set of nodes

• node_set2 (collections.abc.Set[int]) – set of nodes

Returns:

set of edges for the complete bipartite graph

Return type:

set[tuple[int, int]

Raises:

ValueError – If the two sets of nodes are not disjoint.

graphqomb.graphstate.odd_neighbors(nodes, graphstate)

Return the odd neighbors of a set of nodes in the graph state.

Parameters:

• nodes (collections.abc.Set[int]) – set of nodes

• graphstate (BaseGraphState) – graph state

Returns:

set of odd neighbors

Return type:

set[int]

Auxiliary Classes

class graphqomb.graphstate.LocalCliffordExpansion

Local Clifford expansion map for each input/output node.

node1: int

Alias for field number 0

node2: int

Alias for field number 1

static __new__(_cls, node1, node2, node3)

Create new instance of LocalCliffordExpansion(node1, node2, node3)

node3: int

Alias for field number 2

class graphqomb.graphstate.ExpansionMaps

Expansion maps for inputs and outputs with Local Clifford.

static __new__(_cls, input_node_map, output_node_map)

Create new instance of ExpansionMaps(input_node_map, output_node_map)

input_node_map: dict[int, LocalCliffordExpansion]

Alias for field number 0

output_node_map: dict[int, LocalCliffordExpansion]

Alias for field number 1