qbraid.transpiler.ConversionGraph

class ConversionGraph(conversions=None, require_native=False, include_isolated=True, edge_bias=None, nodes=None)[source]

Class for coordinating conversions between different quantum software programs

Initialize a ConversionGraph instance.

Parameters:

  • conversions (list[Conversion], optional) – List of conversion edges. If None, default conversion edges are used.

  • require_native (bool) – If True, only include “native” conversion functions. Defaults to False.

  • include_isolated (bool) – If True, includes all registered program type aliases, even those that are not connected to any other nodes in the graph. Defaults to True.

  • edge_bias (float, optional) – Factor used to fine-tune the edge weight calculations and modify the decision thresholds for pathfinding. Defaults to 0.25 to prioritize shorter paths. For example, a bias of 0.25 slightly favors a single conversion at weight 0.78 over two conversions at weight 1.0. Only used if conversions is None.

  • nodes (list[str], optional) – List of nodes to include in the graph. If nodes is None and conversions is None, all nodes connected by registered conversions are included. If nodes is None and conversions is specified, only nodes connected by the specified conversions are included. Isolated nodes included iff include_isolated is True.

__init__(conversions=None, require_native=False, include_isolated=True, edge_bias=None, nodes=None)[source]

Initialize a ConversionGraph instance.

Parameters:

  • conversions (list[Conversion], optional) – List of conversion edges. If None, default conversion edges are used.

  • require_native (bool) – If True, only include “native” conversion functions. Defaults to False.

  • include_isolated (bool) – If True, includes all registered program type aliases, even those that are not connected to any other nodes in the graph. Defaults to True.

  • edge_bias (float, optional) – Factor used to fine-tune the edge weight calculations and modify the decision thresholds for pathfinding. Defaults to 0.25 to prioritize shorter paths. For example, a bias of 0.25 slightly favors a single conversion at weight 0.78 over two conversions at weight 1.0. Only used if conversions is None.

  • nodes (list[str], optional) – List of nodes to include in the graph. If nodes is None and conversions is None, all nodes connected by registered conversions are included. If nodes is None and conversions is specified, only nodes connected by the specified conversions are included. Isolated nodes included iff include_isolated is True.

Methods

__init__([conversions, require_native, ...])

Initialize a ConversionGraph instance.

add_child(parent, obj, edge, /)

Add a new child node to the graph.

add_conversion(edge[, overwrite])

Add a new conversion function as an edge in the graph.

add_edge(parent, child, edge, /)

Add an edge between 2 nodes.

add_edges_from(obj_list, /)

Add new edges to the graph.

add_edges_from_no_data(obj_list, /)

Add new edges to the graph without python data.

add_node(obj, /)

Add a new node to the graph.

add_nodes_from(obj_list, /)

Add new nodes to the graph.

add_parent(child, obj, edge, /)

Add a new parent node to the graph.

adj(node, /)

Get the index and data for the neighbors of a node.

adj_direction(node, direction, /)

Get the index and data for either the parents or children of a node.

all_paths(source, target)

Return string representations of all conversion paths between two nodes.

can_contract_without_cycle(nodes, /)

Check if contracting the specified nodes can occur without introducing cycles.

clear()

Clear all nodes and edges

clear_edges()

Clears all edges, leaves nodes intact

closest_source(target, sources)

Determine the closest source from a list of possible sources based on the shortest conversion path and weights.

closest_target(source, targets)

Determine the closest target from a list of possible targets based on the shortest conversion path and weights.

compose(other, node_map, /[, node_map_func, ...])

Add another PyDiGraph object into this PyDiGraph

contract_nodes(nodes, obj, /[, check_cycle, ...])

Substitute a set of nodes with a single new node.

conversions()

Get the list of conversion edges.

copy()

Create a copy of this graph, returning a new instance of ConversionGraph.

create_conversion_graph()

Create a directed graph from a list of conversion functions.

edge_index_map()

Get an edge index map

edge_indices()

Return a list of all edge indices.

edge_indices_from_endpoints(node_a, node_b)

Return a list of indices of all directed edges between specified nodes

edge_list()

Get edge list

edge_subgraph(edge_list, /)

Return a new PyDiGraph object for an edge induced subgraph of this graph

edges()

Return a list of all edge data.

extend_from_edge_list(edge_list, /)

Extend graph from an edge list

extend_from_weighted_edge_list(edge_list, /)

Extend graph from a weighted edge list

filter_edges(filter_function)

Filters a graph's edges by some criteria conditioned on a edge's data payload and returns those edges' indices.

filter_nodes(filter_function)

Filters a graph's nodes by some criteria conditioned on a node's data payload and returns those nodes' indices.

find_adjacent_node_by_edge(node, predicate, /)

Find any adjacent (successor) node connected with an edge that matches the condition

find_node_by_weight(obj, /)

Find node within this graph given a specific weight

find_predecessor_node_by_edge(node, predicate, /)

Find any predecessor node connected with an edge that matches the condition

find_predecessors_by_edge(node, filter_fn, /)

Return a list of data associated with the predecessors of the given node, where the edges connecting from those nodes satisfy the provided filter function.

find_shortest_conversion_path(source, target)

Find the shortest conversion path between two nodes in a graph.

find_successor_node_by_edge(node, predicate, /)

Find any successor node connected with an edge that matches the condition

find_successors_by_edge(node, filter_fn, /)

Return a list of data associated with the successors of the given node, where the edges connecting to those nodes satisfy the provided filter function.

find_top_shortest_conversion_paths(source, ...)

Find the top shortest conversion paths between two nodes in a graph.

from_adjacency_matrix(matrix, /[, null_value])

Create a new PyDiGraph object from an adjacency matrix with matrix elements of type float

from_complex_adjacency_matrix(matrix, /[, ...])

Create a new PyDiGraph object from an adjacency matrix with matrix elements of type complex

get_all_edge_data(node_a, node_b, /)

Return the edge data for all the edges between 2 nodes.

get_edge_data(node_a, node_b, /)

Return the edge data for an edge between 2 nodes.

get_edge_data_by_index(edge_index, /)

Return the edge data for the edge by its given index

get_edge_endpoints_by_index(edge_index, /)

Return the edge endpoints for the edge by its given index

get_node_data(node, /)

Return the node data for a given node index

get_node_experiment_types()

Get the experiment type of each node in the graph.

get_sorted_closest_sources(target, sources)

Sorts a list of sources from closest to least close based on conversion paths from the target.

get_sorted_closest_targets(source, targets)

Sorts a list of targets from closest to least close based on conversion paths from the source.

has_edge(node_a, node_b)

Check if an edge exists between two nodes in the graph.

has_node(node)

Check if a node exists in the graph.

has_parallel_edges()

Detect if the graph has parallel edges or not

has_path(source, target)

Check if a conversion between two languages is supported.

in_degree(node, /)

Get the degree of a node for inbound edges.

in_edge_indices(node, /)

Return the list of incoming edge indices to a provided node

in_edges(node, /)

Get the index and edge data for all parents of a node.

incident_edge_index_map(node, /[, all_edges])

Return the index map of edges incident to a provided node

incident_edges(node, /[, all_edges])

Return the list of edge indices incident to a provided node

insert_node_on_in_edges(node, ref_node, /)

Insert a node between a reference node and all its predecessor nodes

insert_node_on_in_edges_multiple(node, ...)

Insert a node between a list of reference nodes and all their predecessors

insert_node_on_out_edges(node, ref_node, /)

Insert a node between a reference node and all its successor nodes

insert_node_on_out_edges_multiple(node, ...)

Insert a node between a list of reference nodes and all their successors

is_symmetric()

Check if the graph is symmetric

load_default_conversions([bias])

Create a list of default conversion nodes using predefined conversion functions.

make_symmetric([edge_payload_fn])

Make edges in graph symmetric

merge_nodes(u, v, /)

Merge two nodes in the graph.

neighbors(node, /)

Return a list of node indices of neighbors (i.e. successors) in a directed graph.

neighbors_undirected(node, /)

Get the direction-agnostic neighbors (i.e. successors and predecessors) of a node.

node_indexes()

Return a list of all node indices.

node_indices()

Return a list of all node indices.

nodes()

Return a list of all node data.

num_edges()

Return the number of edges in the graph

num_nodes()

Return the number of nodes in the graph

out_degree(node, /)

Get the degree of a node for outbound edges.

out_edge_indices(node, /)

Return the list of outgoing edge indices from a provided node

out_edges(node, /)

Get the index and edge data for all children of a node.

plot(**kwargs)

Plot the conversion graph.

predecessor_indices(node, /)

Return a list of predecessor node indices in a directed graph

predecessors(node, /)

Return a list of data of all node predecessors in a directed graph

read_edge_list(path, /[, comment, ...])

Read an edge list file and create a new PyDiGraph object from the contents

remove_conversion(source, target)

Safely remove a conversion from the graph.

remove_edge(parent, child, /)

Remove an edge between 2 nodes.

remove_edge_from_index(edge, /)

Remove an edge identified by the provided index

remove_edges_from(index_list, /)

Remove edges from the graph.

remove_node(node, /)

Remove a node from the graph.

remove_node_retain_edges(node, /[, ...])

Remove a node from the graph and add edges from all predecessors to all successors

remove_node_retain_edges_by_id(node, /)

Remove a node from the graph and add edges from predecessors to successors in cases where an incoming and outgoing edge have the same weight by Python object identity.

remove_node_retain_edges_by_key(node, /[, ...])

Remove a node from the graph and add edges from predecessors to successors in cases where an incoming and outgoing edge have the same weight by Python object equality.

remove_nodes_from(index_list, /)

Remove nodes from the graph.

reset([conversions])

Reset the graph to its default state.

reverse()

Reverse the direction of all edges in the graph, in place.

shortest_path(source, target)

Return string representation of the shortest conversion path between two nodes.

subgraph(experiment_type)

Filter the graph to include only nodes with the specified experiment type(s).

subgraph_with_nodemap(nodes, /[, preserve_attrs])

Return a new PyDiGraph object for a subgraph of this graph and a NodeMap object that maps the nodes of the subgraph to the nodes of the original graph.

substitute_node_with_subgraph(node, other, ...)

Substitute a node with a PyDigraph object

successor_indices(node, /)

Return a list of successor node indices in a directed graph

successors(node, /)

Return a list of data of all node successors in a directed graph

to_dot([node_attr, edge_attr, graph_attr, ...])

Generate a dot file from the graph

to_undirected([multigraph, weight_combo_fn])

Generate a new PyGraph object from this graph

update_edge(source, target, edge, /)

Update an edge's weight/payload in place

update_edge_by_index(edge_index, edge, /)

Update an edge's weight/data payload in place by the edge index

weighted_edge_list()

Get edge list with weights

write_edge_list(path, /[, deliminator, ...])

Write an edge list file from the PyDiGraph object

Attributes

attrs

check_cycle

Whether cycle checking is enabled for the DiGraph/DAG.

multigraph

Whether the graph is a multigraph (allows multiple edges between nodes) or not