clustersim.simulator package¶

class clustersim.simulator.ClusterState(num_nodes=0)¶

Bases: object

Adapter class containing a GraphRegister object.

Parameters:: num_nodes (int)

CX(control, qubit)¶

Parameters:

control (int)
qubit (int)

CZ(control, qubit)¶

Parameters:

control (int)
qubit (int)

H(qubit)¶

Parameters:: qubit (int)

I(qubit)¶

Parameters:: qubit (int)

M(qubit, force=-1)¶

Shorthand for MZ

Parameters:

qubit (int)
force (int)

MX(qubit, force=-1)¶

Parameters:

qubit (int)
force (int)

MY(qubit, force=-1)¶

Parameters:

qubit (int)
force (int)

MZ(qubit, force=-1)¶

Parameters:

qubit (int)
force (int)

S(qubit)¶

Parameters:: qubit (int)

SH(qubit)¶

Parameters:: qubit (int)

S_DAG(qubit)¶

Parameters:: qubit (int)

X(qubit)¶

Parameters:: qubit (int)

Y(qubit)¶

Parameters:: qubit (int)

Z(qubit)¶

Parameters:: qubit (int)

add_edge(qubit1, qubit2)¶

add_node(vop='IA')¶

Add a node.

By default, the vertex operator corresponds to the |+> state. To add |0>, set vop to “YC”.

Parameters:: vop (str) – Vertex operator. Defaults to “IA” (|+>).

property adjacency_list¶

property adjacency_matrix¶

apply_VOP(qubit, vop)¶

Apply vertex operators.

Parameters:

qubit (int) – which vertex operator to apply
vop (tuple[int, int] | int | str)

draw(label_func=<function ClusterState.<lambda>>, **kwargs)¶

Return type:: None

duplicate(targets=None)¶

Generate a copy of the selection and return a larger object.

Parameters:: targets (list[int] | None) – The qubits to copy. Defaults to all qubits.
Return type:: ClusterState

edge_local_complementation(edge)¶

Apply an edge local complementation.

Parameters:: edge (tuple[int, int]) – _description_

classmethod from_cytoscape(data)¶

Load a simulator from cytoscape.

Return type:: ClusterState

classmethod from_json(json_data)¶

Create a ClusterState from JSON data in various formats.

Parameters:: json_data (str | dict) – A python dict, a JSON string, a path to a JSON file, or a file-like object.
Returns:: The reconstructed cluster state.
Return type:: ClusterState

classmethod from_networkx(graph)¶

Parameters:: graph (Graph)
Return type:: ClusterState

classmethod from_rustworkx(graph)¶

Create a graph state from rustworkx.

Parameters:: graph (PyGraph | PyDiGraph) – rustworkx graph.
Returns:: class object
Return type:: ClusterState

classmethod from_string(string, return_log=False)¶

Create a cluster state from a string representation of operations.

Parameters:

string (str)
return_log (bool)

Return type:

ClusterState | tuple[ClusterState, str]

fusion_gate(qubit1, qubit2, fusion_type='XXZZ', mode='success', force=0)¶

Apply a fusion gate.

For more details, see https://arxiv.org/pdf/2312.02377.

Parameters:

qubit1 (int) – which qubit to apply
qubit2 (int) – which qubit to apply
fusion_type (str) – “XXZZ”, “XZZX”, “XYYZ”
mode (str, optional) – Either “success”, “failure”, or “random”. Defaults to “success”.
force (int) – Force the measurements according to the following mapping: - 0 : Qubit 1 = 0, Qubit 2 = 0 - 1 : Qubit 1 = 0, Qubit 2 = 1 - 2 : Qubit 1 = 1, Qubit 2 = 0 - 3 : Qubit 1 = 1, Qubit 2 = 1 - -1 : Random measurement

local_complementation(qubit)¶

Apply a local complementation.

Parameters:: qubit (int) – which qubit to apply

local_complementation_rewrite(qubit)¶

Apply a local complementation. This does not change the graph state.

This is because we apply local Cliffords to cancel out the state.

Parameters:: qubit (int) – which qubit to apply

measure(qubit, force=-1, basis='Z')¶

Measure a node in the graph state.

Parameters:

qubit (int) – The qubit to measure, which is an integer from 0 to n-1.
force (int) – Whether to force the measurement outcome.
basis (str) – The basis to measure in, which is either ‘X’, ‘Y’ or ‘Z’.

property num_nodes¶

classmethod random_graph(num_nodes, p=0.5, local_cliffords=False)¶

Generate a random graph.

Parameters:

num_nodes (int) – number of nodes
p (float) – Probability of generating an edge. Defaults to 0.5.
local_cliffords (bool) – Randomize local cliffords. Defaults to False.

Return type:

ClusterState

remove_edge(qubit1, qubit2)¶

remove_node(qubits)¶

Parameters:: qubits (int | list[int])

property stabilizers¶

subgraph(targets=None)¶

Generate a copy and return a larger object.

This does not copy any edges out of the selection.

Parameters:: targets (list[int] | None) – The qubits to copy. Defaults to all qubits.
Return type:: ClusterState

to_cytoscape(export_elements=False)¶: Export to cytoscape.

to_json()¶

Convert the graph state to a JSON-serializable format.

Return type:: str | None
Returns:: A JSON-serializable representation of the graph state.

to_networkx(options={'neighbors': False, 'stabilizer': False, 'vop': True})¶

Export data from the underlying state.

Turning off vop = True may lead to unintended behaviour when recreating the state.

Parameters:: options (dict, optional) – Default options. Defaults to {“stabilizer” : False, “vop”: True}.
Returns:: networkx representation
Return type:: nx.Graph

to_rustworkx(options={'neighbors': False, 'stabilizer': False, 'vop': True})¶

Export data from the underlying state.

Turning off vop = True may lead to unintended behaviour when recreating the state.

Parameters:: options (dict, optional) – Default options. Defaults to {“stabilizer” : False, “vop”: True}.
Returns:: rustworkx representation
Return type:: rx.PyGraph

toggle_edge(qubit1, qubit2)¶

property vertex_operators¶

class clustersim.simulator.FrontendClusterState(num_nodes=0, cluster_state=None, positions=None, groups=None)¶

Bases: object

Adapter and wrapper class that extends ClusterState with 2D layout and frontend metadata, such as node 2D positions, compound parent groups, custom styling, persistent node values, and snapshot-based Undo/Redo capability.

Parameters:

num_nodes (int)
cluster_state (Optional[ClusterState])
positions (Union[List[Dict[str, float]], Dict[int, Dict[str, float]], None])
groups (Optional[Dict[str, Dict[str, Any]]])

CX(control, qubit)¶

Parameters:

control (Union[int, str])
qubit (Union[int, str])

Return type:

None

CZ(control, qubit)¶

Parameters:

control (Union[int, str])
qubit (Union[int, str])

Return type:

None

H(qubit)¶

Parameters:: qubit (Union[int, str])
Return type:: None

I(qubit)¶

Parameters:: qubit (Union[int, str])
Return type:: None

M(qubit, force=-1)¶

Parameters:

qubit (Union[int, str])
force (int)

Return type:

int

MX(qubit, force=-1)¶

Parameters:

qubit (Union[int, str])
force (int)

Return type:

int

MY(qubit, force=-1)¶

Parameters:

qubit (Union[int, str])
force (int)

Return type:

int

MZ(qubit, force=-1)¶

Parameters:

qubit (Union[int, str])
force (int)

Return type:

int

S(qubit)¶

Parameters:: qubit (Union[int, str])
Return type:: None

SH(qubit)¶

Parameters:: qubit (Union[int, str])
Return type:: None

S_DAG(qubit)¶

Parameters:: qubit (Union[int, str])
Return type:: None

X(qubit)¶

Parameters:: qubit (Union[int, str])
Return type:: None

Y(qubit)¶

Parameters:: qubit (Union[int, str])
Return type:: None

Z(qubit)¶

Parameters:: qubit (Union[int, str])
Return type:: None

add_edge(qubit1, qubit2)¶

Parameters:

qubit1 (Union[int, str])
qubit2 (Union[int, str])

Return type:

None

add_group(group_id, label=None, style=None, value=None)¶

Add or update a compound parent group container.

Parameters:

group_id (str)
label (Optional[str])
style (Optional[Dict[str, Any]])
value (Optional[str])

Return type:

None

add_node(vop='IA', position=None, group=None, value=None, label=None)¶

Add a new quantum node to ClusterState and initialize its frontend metadata.

Parameters:

vop (str)
position (Optional[Dict[str, float]])
group (Optional[str])
value (Optional[Any])
label (Optional[str])

Return type:

int

property adjacency_list: List[List[int]]¶

apply_VOP(qubit, vop)¶

Parameters:

qubit (Union[int, str])
vop (Union[Tuple[int, int], int, str])

Return type:

None

expand_selection(selected_items)¶

Expand selected items (which may contain group container IDs, qubit indices, or Cytoscape node dicts) into a deduplicated list of valid qubit indices. If a group container ID is present, it is expanded to all of its child qubits.

Parameters:: selected_items (List[Union[int, str, Dict[str, Any]]])
Return type:: List[int]

classmethod from_cytoscape_elements(elements)¶

Reconstruct FrontendClusterState from a list of Cytoscape elements.

Parameters:: elements (List[Dict[str, Any]])
Return type:: FrontendClusterState

classmethod from_dict(data)¶

Create FrontendClusterState from a dictionary.

Parameters:: data (Dict[str, Any])
Return type:: FrontendClusterState

classmethod from_json(json_str)¶

Deserialize FrontendClusterState from JSON string.

Parameters:: json_str (str)
Return type:: FrontendClusterState

fusion_gate(qubit1, qubit2, fusion_type='XXZZ', mode='success', force=0)¶

Parameters:

qubit1 (Union[int, str])
qubit2 (Union[int, str])
fusion_type (str)
mode (str)
force (int)

Return type:

None

get_group(qubit)¶

Parameters:: qubit (Union[int, str])
Return type:: Optional[str]

get_group_children(group_id)¶

Return list of qubit indices that belong to the specified group.

Parameters:: group_id (str)
Return type:: List[int]

get_position(qubit)¶

Parameters:: qubit (Union[int, str])
Return type:: Dict[str, float]

get_value(qubit)¶

Parameters:: qubit (Union[int, str])
Return type:: Any

local_complementation(qubit)¶

Parameters:: qubit (Union[int, str])
Return type:: None

local_complementation_rewrite(qubit)¶

Parameters:: qubit (Union[int, str])
Return type:: None

measure(qubit, force=-1, basis='Z')¶

Parameters:

qubit (Union[int, str])
force (int)
basis (str)

Return type:

int

property num_nodes: int¶

push_state()¶

Push current snapshot onto the undo stack and clear the redo stack.

Return type:: None

redo()¶

Restore the next state from the redo stack.

Returns:: True if redo was successful, False if redo stack was empty.
Return type:: bool

remove_edge(qubit1, qubit2)¶

Parameters:

qubit1 (Union[int, str])
qubit2 (Union[int, str])

Return type:

None

remove_group(group_id, unassign_children=True)¶

Remove a compound group container.

Parameters:

group_id (str)
unassign_children (bool)

Return type:

None

remove_node(qubits)¶

Remove one or more nodes. Translates string IDs, qubit indices, or values to valid qubit indices. ClusterState automatically relabels remaining nodes contiguously from 0 to N-1. FrontendClusterState transfers metadata (position, group, persistent value, style) from old node indices to their new contiguous indices.

Parameters:: qubits (Union[int, str, List[Union[int, str]]])
Return type:: List[int]

resolve_qubit(identifier)¶

Translate a Cytoscape node ID, qubit index, or persistent value into a valid ClusterState qubit index (0..N-1).

Parameters:: identifier (Union[int, str])
Return type:: Optional[int]

set_group(qubit, group_id)¶

Parameters:

qubit (Union[int, str])
group_id (Optional[str])

Return type:

None

set_position(qubit, position)¶

Parameters:

qubit (Union[int, str])
position (Dict[str, float])

Return type:

None

set_value(qubit, value)¶

Parameters:

qubit (Union[int, str])
value (Any)

Return type:

None

snapshot()¶

Create a complete serializable snapshot of the current state.

Return type:: Dict[str, Any]

property stabilizers: List[str]¶

to_cytoscape_elements()¶

Export complete 2D layout and quantum state to Cytoscape elements list.

Return type:: List[Dict[str, Any]]

to_dict()¶

Convert FrontendClusterState to a serializable dictionary.

Return type:: Dict[str, Any]

to_json()¶

Serialize FrontendClusterState to JSON string.

Return type:: str

toggle_edge(qubit1, qubit2)¶

Parameters:

qubit1 (Union[int, str])
qubit2 (Union[int, str])

Return type:

None

undo()¶

Restore the previous state from the undo stack.

Returns:: True if undo was successful, False if undo stack was empty.
Return type:: bool

property vertex_operators: List[str]¶

Submodules¶

clustersim.simulator.cluster_state module¶

class clustersim.simulator.cluster_state.ClusterState(num_nodes=0)¶

Bases: object

Adapter class containing a GraphRegister object.

Parameters:: num_nodes (int)

CX(control, qubit)¶

Parameters:

control (int)
qubit (int)

CZ(control, qubit)¶

Parameters:

control (int)
qubit (int)

H(qubit)¶

Parameters:: qubit (int)

I(qubit)¶

Parameters:: qubit (int)

M(qubit, force=-1)¶

Shorthand for MZ

Parameters:

qubit (int)
force (int)

MX(qubit, force=-1)¶

Parameters:

qubit (int)
force (int)

MY(qubit, force=-1)¶

Parameters:

qubit (int)
force (int)

MZ(qubit, force=-1)¶

Parameters:

qubit (int)
force (int)

S(qubit)¶

Parameters:: qubit (int)

SH(qubit)¶

Parameters:: qubit (int)

S_DAG(qubit)¶

Parameters:: qubit (int)

X(qubit)¶

Parameters:: qubit (int)

Y(qubit)¶

Parameters:: qubit (int)

Z(qubit)¶

Parameters:: qubit (int)

add_edge(qubit1, qubit2)¶

add_node(vop='IA')¶

Add a node.

By default, the vertex operator corresponds to the |+> state. To add |0>, set vop to “YC”.

Parameters:: vop (str) – Vertex operator. Defaults to “IA” (|+>).

property adjacency_list¶

property adjacency_matrix¶

apply_VOP(qubit, vop)¶

Apply vertex operators.

Parameters:

qubit (int) – which vertex operator to apply
vop (tuple[int, int] | int | str)

draw(label_func=<function ClusterState.<lambda>>, **kwargs)¶

Return type:: None

duplicate(targets=None)¶

Generate a copy of the selection and return a larger object.

Parameters:: targets (list[int] | None) – The qubits to copy. Defaults to all qubits.
Return type:: ClusterState

edge_local_complementation(edge)¶

Apply an edge local complementation.

Parameters:: edge (tuple[int, int]) – _description_

classmethod from_cytoscape(data)¶

Load a simulator from cytoscape.

Return type:: ClusterState

classmethod from_json(json_data)¶

Create a ClusterState from JSON data in various formats.

Parameters:: json_data (str | dict) – A python dict, a JSON string, a path to a JSON file, or a file-like object.
Returns:: The reconstructed cluster state.
Return type:: ClusterState

classmethod from_networkx(graph)¶

Parameters:: graph (Graph)
Return type:: ClusterState

classmethod from_rustworkx(graph)¶

Create a graph state from rustworkx.

Parameters:: graph (PyGraph | PyDiGraph) – rustworkx graph.
Returns:: class object
Return type:: ClusterState

classmethod from_string(string, return_log=False)¶

Create a cluster state from a string representation of operations.

Parameters:

string (str)
return_log (bool)

Return type:

ClusterState | tuple[ClusterState, str]

fusion_gate(qubit1, qubit2, fusion_type='XXZZ', mode='success', force=0)¶

Apply a fusion gate.

For more details, see https://arxiv.org/pdf/2312.02377.

Parameters:

qubit1 (int) – which qubit to apply
qubit2 (int) – which qubit to apply
fusion_type (str) – “XXZZ”, “XZZX”, “XYYZ”
mode (str, optional) – Either “success”, “failure”, or “random”. Defaults to “success”.
force (int) – Force the measurements according to the following mapping: - 0 : Qubit 1 = 0, Qubit 2 = 0 - 1 : Qubit 1 = 0, Qubit 2 = 1 - 2 : Qubit 1 = 1, Qubit 2 = 0 - 3 : Qubit 1 = 1, Qubit 2 = 1 - -1 : Random measurement

local_complementation(qubit)¶

Apply a local complementation.

Parameters:: qubit (int) – which qubit to apply

local_complementation_rewrite(qubit)¶

Apply a local complementation. This does not change the graph state.

This is because we apply local Cliffords to cancel out the state.

Parameters:: qubit (int) – which qubit to apply

measure(qubit, force=-1, basis='Z')¶

Measure a node in the graph state.

Parameters:

qubit (int) – The qubit to measure, which is an integer from 0 to n-1.
force (int) – Whether to force the measurement outcome.
basis (str) – The basis to measure in, which is either ‘X’, ‘Y’ or ‘Z’.

property num_nodes¶

classmethod random_graph(num_nodes, p=0.5, local_cliffords=False)¶

Generate a random graph.

Parameters:

num_nodes (int) – number of nodes
p (float) – Probability of generating an edge. Defaults to 0.5.
local_cliffords (bool) – Randomize local cliffords. Defaults to False.

Return type:

ClusterState

remove_edge(qubit1, qubit2)¶

remove_node(qubits)¶

Parameters:: qubits (int | list[int])

property stabilizers¶

subgraph(targets=None)¶

Generate a copy and return a larger object.

This does not copy any edges out of the selection.

Parameters:: targets (list[int] | None) – The qubits to copy. Defaults to all qubits.
Return type:: ClusterState

to_cytoscape(export_elements=False)¶: Export to cytoscape.

to_json()¶

Convert the graph state to a JSON-serializable format.

Return type:: str | None
Returns:: A JSON-serializable representation of the graph state.

to_networkx(options={'neighbors': False, 'stabilizer': False, 'vop': True})¶

Export data from the underlying state.

Turning off vop = True may lead to unintended behaviour when recreating the state.

Parameters:: options (dict, optional) – Default options. Defaults to {“stabilizer” : False, “vop”: True}.
Returns:: networkx representation
Return type:: nx.Graph

to_rustworkx(options={'neighbors': False, 'stabilizer': False, 'vop': True})¶

Export data from the underlying state.

Turning off vop = True may lead to unintended behaviour when recreating the state.

Parameters:: options (dict, optional) – Default options. Defaults to {“stabilizer” : False, “vop”: True}.
Returns:: rustworkx representation
Return type:: rx.PyGraph

toggle_edge(qubit1, qubit2)¶

property vertex_operators¶