pygsti.baseobjs.qubitgraph
Defines the QubitGraph class and supporting functions
Module Contents
Classes
A directed or undirected graph data structure used to represent geometrical layouts of qubits or qubit gates. |
- class pygsti.baseobjs.qubitgraph.QubitGraph(qubit_labels, initial_connectivity=None, initial_edges=None, directed=True, direction_names=None)
Bases:
pygsti.baseobjs.nicelyserializable.NicelySerializableA directed or undirected graph data structure used to represent geometrical layouts of qubits or qubit gates.
Qubits are nodes in the graph (and can be labeled), and edges represent the ability to perform one or more types of gates between qubits (equivalent, usually, to geometrical proximity).
Parameters
- qubit_labelslist
A list of string or integer labels of the qubits. The length of this list equals the number of qubits (nodes) in the graph.
- initial_connectivitynumpy.ndarray, optional
A (nqubits, nqubits) boolean or integer array giving the initial connectivity of the graph. If an integer array, then 0 indicates no edge and positive integers indicate present edges in the “direction” given by the positive integer. For example 1 may corresond to “left” and 2 to “right”. Names must be associated with these directions using direction_names. If a boolean array, if there’s an edge from qubit i to j then initial_connectivity[i,j]=True (integer indices of qubit labels are given by their position in qubit_labels). When directed=False, only the upper triangle is used.
- initial_edgeslist
A list of (qubit_label1, qubit_label2) 2-tuples or (qubit_label1, qubit_label2, direction) 3-tuples specifying which edges are initially present. direction can either be a positive integer, similar to those used in initial_connectivity (in which case direction_names must be specified) or a string labeling the direction, e.g. “left”.
- directedbool, optional
Whether the graph is directed or undirected. Directions can only be used when directed=True.
- direction_namesiterable, optional
A list (or tuple, etc) of string-valued direction names such as “left” or “right”. These strings label the directions referenced by index in either initial_connectivity or initial_edges, and this argument is required whenever such indices are used.
Initialize a new QubitGraph.
Can specify at most one of initial_connectivity and initial_edges.
Parameters
- qubit_labelslist
A list of string or integer labels of the qubits. The length of this list equals the number of qubits (nodes) in the graph.
- initial_connectivitynumpy.ndarray, optional
A (nqubits, nqubits) boolean or integer array giving the initial connectivity of the graph. If an integer array, then 0 indicates no edge and positive integers indicate present edges in the “direction” given by the positive integer. For example 1 may corresond to “left” and 2 to “right”. Names must be associated with these directions using direction_names. If a boolean array, if there’s an edge from qubit i to j then initial_connectivity[i,j]=True (integer indices of qubit labels are given by their position in qubit_labels). When directed=False, only the upper triangle is used.
- initial_edgeslist
A list of (qubit_label1, qubit_label2) 2-tuples or (qubit_label1, qubit_label2, direction) 3-tuples specifying which edges are initially present. direction can either be a positive integer, similar to those used in initial_connectivity (in which case direction_names must be specified) or a string labeling the direction, e.g. “left”.
- directedbool, optional
Whether the graph is directed or undirected. Directions can only be used when directed=True.
- direction_namesiterable, optional
A list (or tuple, etc) of string-valued direction names such as “left” or “right”. These strings label the directions referenced by index in either initial_connectivity or initial_edges, and this argument is required whenever such indices are used.
- property node_names
All the node labels of this graph.
These correpond to integer indices where appropriate, e.g. for
shortest_path_distance_matrix().Returns
tuple
- classmethod common_graph(num_qubits=0, geometry='line', directed=True, qubit_labels=None, all_directions=False)
Create a QubitGraph that is one of several standard types of graphs.
Parameters
- num_qubitsint, optional
The number of qubits (nodes in the graph).
- geometry{“line”,”ring”,”grid”,”torus”}
The type of graph. What these correspond to should be self-evident.
- directedbool, optional
Whether the graph is directed or undirected.
- qubit_labelsiterable, optional
The labels for the qubits. Must be of length num_qubits. If None, then the integers from 0 to num_qubits-1 are used.
- all_directionsbool, optional
Whether to include edges with all directions. Typically it only makes sense to set this to True when directed=True also.
Returns
QubitGraph
- map_qubit_labels(mapper)
Creates a new QubitGraph whose qubit (node) labels are updated according to the mapping function mapper.
Parameters
- mapperdict or function
A dictionary whose keys are the existing self.node_names values and whose value are the new labels, or a function which takes a single (existing qubit-label) argument and returns a new qubit label.
Returns
QubitProcessorSpec
- add_edges(edges)
Add edges (list of tuple pairs) to graph.
Parameters
- edgeslist
A list of (qubit_label1, qubit_label2) 2-tuples.
Returns
None
- add_edge(node1, node2, direction=None)
Add an edge between the qubits labeled by node1 and node2.
Parameters
- node1str or int
Qubit (node) label.
- node2str or int
Qubit (node) label.
- directionstr or int, optional
Either a direction name or a direction indicex
Returns
None
- remove_edge(node1, node2)
Add an edge between the qubits labeled by node1 and node2.
Parameters
- node1str or int
Qubit (node) label.
- node2str or int
Qubit (node) label.
Returns
None
- edges(double_for_undirected=False, include_directions=False)
Get a list of the edges in this graph as 2-tuples of node/qubit labels).
When undirected, the index of the 2-tuple’s first label will always be less than its second unless double_for_undirected == True, in which case both directed edges are included. The edges are sorted (by label index) in ascending order.
Parameters
- double_for_undirectedbool, optional
Whether, for the case of an undirected graph, two 2-tuples, giving both edge directions, should be included in the returned list.
- include_directionsbool, optional
Whether to include direction labels. If True and directions are present, a list of (node1, node2, direction_name) 3-tuples is returned instead of the usual (node1, node2) 2-tuples.
Returns
list
- radius(base_nodes, max_hops)
Find all the nodes reachable in max_hops from any node in base_nodes.
Get a (sorted) array of node labels that can be reached from traversing at most max_hops edges starting from a node (vertex) in base_nodes.
Parameters
- base_nodesiterable
A list of node/qubit labels giving the possible starting locations.
- max_hopsint
The maximum number of hops (see above).
Returns
- list
A list of the node labels reachable from base_nodes in at most max_hops edge traversals.
- connected_combos(possible_nodes, size)
Computes the number of different connected subsets of possible_nodes containing size nodes.
Parameters
- possible_nodeslist
A list of node (qubit) labels.
- sizeint
The size of the connected subsets being sought (counted).
Returns
int
- is_connected(node1, node2)
Is node1 connected to node2 (does there exist a path of any length between them?)
Parameters
- node1str or int
Qubit (node) label.
- node2str or int
Qubit (node) label.
Returns
bool
- has_edge(edge)
Is edge an edge in this graph.
Note that if this graph is undirected, either node order in edge will return True.
Parameters
- edgetuple
(node1,node2) tuple specifying the edge.
Returns
bool
- is_directly_connected(node1, node2)
Is node1 directly connected to node2 (does there exist an edge between them?)
Parameters
- node1str or int
Qubit (node) label.
- node2str or int
Qubit (node) label.
Returns
bool
- is_connected_graph()
Computes whether this graph is connected (there exist paths between every pair of nodes).
Returns
bool
- is_connected_subgraph(nodes)
Do a give set of nodes form a connected subgraph?
That is, does there exist a path from every node in nodes to every other node in nodes using only the edges between the nodes in nodes.
Parameters
- nodeslist
A list of node (qubit) labels.
Returns
bool
- find_all_connected_sets()
Finds all subgraphs (connected sets of vertices) up to the full graph size.
Graph edges are treated as undirected.
Returns
- dict
A dictionary with integer keys. The value of key k is a list of all the subgraphs of length k. A subgraph is given as a tuple of sorted vertex labels.
- shortest_path(node1, node2)
Get the shortest path between two nodes (qubits).
Parameters
- node1str or int
Qubit (node) label.
- node2str or int
Qubit (node) label.
Returns
- list
A list of the node labels to traverse.
- shortest_path_edges(node1, node2)
Like
shortest_path(), but returns a list of (nodeA,nodeB) tuples.These tuples define a path from node1 to node2, so the first tuple’s nodeA == node1 and the final tuple’s nodeB == node2.
Parameters
- node1str or int
Qubit (node) label.
- node2str or int
Qubit (node) label.
Returns
- list
A list of the edges (2-tuples of node labels) to traverse.
- shortest_path_intersect(node1, node2, nodes_to_intersect)
Check whether the shortest path between node1 and node2 contains any of the nodes in nodes_to_intersect.
Parameters
- node1str or int
Qubit (node) label.
- node2str or int
Qubit (node) label.
- nodes_to_intersectlist
A list of node labels.
Returns
- bool
True if the shortest path intersects any node in nodeToIntersect.
- shortest_path_distance(node1, node2)
Get the distance of the shortest path between node1 and node2.
Parameters
- node1str or int
Qubit (node) label.
- node2str or int
Qubit (node) label.
Returns
int
- shortest_path_distance_matrix()
Returns a matrix of shortest path distances.
This matrix is indexed by the integer-index of each node label (as specified to __init__). The list of index-ordered node labels is given by
node_names().Returns
- numpy.ndarray
A boolean array of shape (n,n) where n is the number of nodes in this graph.
- shortest_path_predecessor_matrix()
Returns a matrix of predecessors used to construct the shortest path between two nodes.
This matrix is indexed by the integer-index of each node label (as specified to __init__). The list of index-ordered node labels is given by
node_names().Returns
- numpy.ndarray
A boolean array of shape (n,n) where n is the number of nodes in this graph.
- subgraph(nodes_to_keep, reset_nodes=False)
Return a graph that includes only nodes_to_keep and the edges between them.
Parameters
- nodes_to_keeplist
A list of node labels defining the subgraph to return.
- reset_nodesbool, optional
If True, nodes of returned subgraph are relabelled to be the integers starting at 0 (in 1-1 correspondence with the ordering in nodes_to_keep).
Returns
QubitGraph
- resolve_relative_nodelabel(relative_nodelabel, target_labels)
Resolve a “relative nodelabel” into an actual node in this graph.
Relative node labels can use “@” to index elements of target_labels and can contain “+<dir>” directives to move along directions defined in this graph.
Parameters
- relative_nodelabelint or str
An absolute or relative node-label. For example: 0, “@0”, “@0+right”, “@1+left+up”
- target_labelslist or tuple
A list of (absolute) node labels present in this graph that may be referred to using the “@” syntax within relative_nodelabel.
Returns
int or str
- move_in_directions(start_node, directions)
The node you end up on after moving in directions from start_node.
Parameters
- start_nodestr or int
Qubit (node) label.
- directionsiterable
A sequence of direction names.
Returns
- str or int or None
The ending node label or None if the directions were invalid.
- move_in_direction(start_node, direction)
Get the node that is one step in direction of start_node.
Parameters
- start_nodeint or str
the starting point (a node label of this graph)
- directionstr or int
the name of a direction or its index within this graphs .directions member.
Returns
- str or int or None
the node in the given direction or None if there is no node in that direction (e.g. if you reach the end of a chain).