Rename MultiQubitGateManager to GateManager and update docstrings

Author: Takishima

docs/projectq.cengines.rst

@@ -6,7 +6,7 @@ The ProjectQ compiler engines package.
 .. autosummary::
 	projectq.cengines.AutoReplacer
 	projectq.cengines.BasicEngine
-	projectq.cengines.BasicMapper
+	projectq.cengines.BasicMapperEngine
 	projectq.cengines.CommandModifier
 	projectq.cengines.CompareEngine
 	projectq.cengines.DecompositionRule
@@ -37,9 +37,9 @@ Module contents
 Helper sub-modules
 ------------------
 
-Multi-qubit gate sub-module
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Gate manager sub-module
+^^^^^^^^^^^^^^^^^^^^^^^
 
-.. automodule:: projectq.cengines._multi_qubit_gate_manager
+.. automodule:: projectq.cengines._gate_manager
     :members:
     :imported-members:

projectq/cengines/_multi_qubit_gate_manager.py renamed to projectq/cengines/_gate_manager.py

@@ -22,14 +22,30 @@
 """
 
 import networkx as nx
-import statistics
 import math
 from projectq.ops import (AllocateQubitGate, DeallocateQubitGate)
 
 # ==============================================================================
 
 
 def _topological_sort(dag):
+    """
+    Returns a generator of nodes in topologically sorted order.
+
+    A topological sort is a nonunique permutation of the nodes such that an
+    edge from u to v implies that u appears before v in the topological sort
+    order.
+
+    Args:
+        dag (networkx.DiGraph): A Directed Acyclic Graph (DAG)
+
+    Returns:
+        An iterable of node names in topological sorted order.
+
+    Note:
+        This implementation is based on
+        :py:func:`networkx.algorithms.dag.topological_sort`
+    """
     indegree_map = {}
     zero_indegree = []
     for node, degree in dag.in_degree():
@@ -50,6 +66,18 @@ def _topological_sort(dag):
 
 # Coffaman-Graham algorithm with infinite width
 def _coffman_graham_ranking(dag):
+    """
+    Apply the Coffman-Grapham layering algorithm to a DAG (with infinite width)
+
+    Args:
+        dag (networkx.DiGraph): A Directed Acyclic Graph (DAG)
+
+    Returns:
+        A list of layers (Python list of lists).
+
+    Note:
+        This function does not limit the width of any layers.
+    """
     layers = [[]]
     levels = {}
 
@@ -86,7 +114,7 @@ def _sum_distance_over_gates(node_list, mapping, distance_matrix):
         gate_list (list): List of 2-qubit gates
         mapping (dict): Current mapping
         distance_matrix (dict): Distance matrix within the hardware coupling
-                                graph
+            graph
 
     Returns:
         Sum of all pair-wise distances between qubits
@@ -118,10 +146,10 @@ def nearest_neighbours_cost_fun(gates_dag, mapping, distance_matrix, swap,
         gates_dag (CommandDAG): Direct acyclic graph of future quantum gates
         mapping (dict): Current mapping
         distance_matrix (dict): Distance matrix within the hardware coupling
-                                graph
+            graph
         swap (tuple): Candidate swap (not used by this function)
         opts (dict): Miscellaneous parameters for cost function (not used by
-                     this function)
+            this function)
 
     Returns:
         Score of current swap operations
@@ -159,7 +187,7 @@ def look_ahead_parallelism_cost_fun(gates_dag, mapping, distance_matrix, swap,
         gates_dag (CommandDAG): Direct acyclic graph of future quantum gates
         mapping (dict): Current mapping
         distance_matrix (dict): Distance matrix within the hardware coupling
-                                graph
+            graph
         swap (tuple): Candidate swap operation
         opts (dict): Miscellaneous parameters for cost function
 
@@ -237,8 +265,8 @@ class DecayManager(object):
     """
     Class managing the decay information about a list of backend qubit IDs
 
-    User should call the :py:meth:`step` method each time a swap gate is added and
-    :py:meth:`remove_decay` once a 2-qubit gate is executed.
+    User should call the :py:meth:`step` method each time a swap gate is added
+    and :py:meth:`remove_decay` once a 2-qubit gate is executed.
     """
     def __init__(self, delta, max_lifetime):
         """
@@ -247,7 +275,7 @@ def __init__(self, delta, max_lifetime):
         Args:
             delta (float): Decay parameter
             max_lifetime (int): Maximum lifetime of decay information for a
-                                particular qubit
+                particular qubit
         """
         self._delta = delta
         self._cutoff = max_lifetime
@@ -389,7 +417,9 @@ def size(self):
         Return the size of the DAG (ie. number of nodes)
 
         Note:
-            This need not be the number of commands stored within the DAG.
+            This may not be equal to the number of commands stored within the
+            DAG as some nodes might store more than one gate if they are
+            compatible.
         """
         return self._dag.number_of_nodes()
 
@@ -521,7 +551,7 @@ def calculate_qubit_interaction_subgraphs(self, max_order=2):
 
         Args:
             max_order (int): Maximum degree of the nodes in the resulting
-                             graph
+                graph
 
         Returns:
             A list of list of graph nodes corresponding to all the connected
@@ -607,7 +637,7 @@ def remove_command(self, cmd):
 # ==============================================================================
 
 
-class MultiQubitGateManager(object):
+class GateManager(object):
     """
     Class managing qubit interactions
     """
@@ -689,16 +719,15 @@ def generate_swaps(self,
         Args:
             mapping (dict): Current mapping
             cost_fun (function): Cost function to rank swap candidates
-                                 Must accept the following parameters:
-                                 - dag (_GatesDAG)
-                                 - new_mapping (dict)
-                                 - distance_matrix (dict)
-                                 - swap_candidate (tuple)
+                Must accept the following parameters:
+                - dag (_GatesDAG)
+                - new_mapping (dict)
+                - distance_matrix (dict)
+                - swap_candidate (tuple)
             max_steps (int): (optional) Maximum number of swap steps to
-                             attempt before giving up
+                attempt before giving up
             opts (dict): (optional) Extra parameters for cost function call
 
-
         .. seealso::
            :py:meth:`nearest_neighbours_cost_fun`
            :py:meth:`look_ahead_parallelism_cost_fun`
@@ -851,7 +880,7 @@ def calculate_qubit_interaction_subgraphs(self, max_order=2):
 
         Args:
             max_order (int): Maximum degree of the nodes in the resulting
-                             interaction graph
+                interaction graph
 
         Returns:
             A list of list of graph nodes corresponding to all the connected
@@ -873,11 +902,11 @@ def _generate_one_swap_step(self, mapping, cost_fun, opts):
         Args:
             mapping (dict): Current mapping
             cost_fun (function): Cost function to rank swap candidates
-                                 Must accept the following parameters:
-                                   - dag (_GatesDAG)
-                                   - new_mapping (dict)
-                                   - distance_matrix (dict)
-                                   - swap_candidate (tuple)
+                Must accept the following parameters:
+                - dag (_GatesDAG)
+                - new_mapping (dict)
+                - distance_matrix (dict)
+                - swap_candidate (tuple)
 
         Returns:
             Tuple with (logical_id0, backend_id0, logical_id1, backend_id1)

projectq/cengines/_multi_qubit_gate_manager_test.py renamed to projectq/cengines/_gate_manager_test.py

@@ -21,7 +21,7 @@
 from projectq.ops import (Allocate, Command, Deallocate, X, H)
 from projectq.types import WeakQubitRef
 
-from projectq.cengines import _multi_qubit_gate_manager as multi
+from projectq.cengines import _gate_manager as gatemgr
 
 # ==============================================================================
 
@@ -31,8 +31,8 @@ def dagnode_to_string(self):
     return '{} {}'.format(self.__class__.__name__, tuple(self.logical_ids))
 
 
-multi._DAGNodeBase.__str__ = dagnode_to_string
-multi._DAGNodeBase.__repr__ = dagnode_to_string
+gatemgr._DAGNodeBase.__str__ = dagnode_to_string
+gatemgr._DAGNodeBase.__repr__ = dagnode_to_string
 
 Command.__repr__ = Command.__str__
 
@@ -118,17 +118,17 @@ def grid33_graph():
 
 @pytest.fixture
 def decay_manager():
-    return multi.DecayManager(0.001, 5)
+    return gatemgr.DecayManager(0.001, 5)
 
 
 @pytest.fixture
 def command_dag():
-    return multi.CommandDAG()
+    return gatemgr.CommandDAG()
 
 
 @pytest.fixture
 def qubit_manager():
-    return multi.MultiQubitGateManager(generate_grid_graph(3, 3))
+    return gatemgr.GateManager(generate_grid_graph(3, 3))
 
 
 # ==============================================================================
@@ -612,18 +612,18 @@ def test_qubit_manager_valid_and_invalid_graphs(simple_graph):
     graph = nx.Graph()
     graph.add_nodes_from('abcd')
     with pytest.raises(RuntimeError):
-        multi.MultiQubitGateManager(graph=graph)
+        gatemgr.GateManager(graph=graph)
 
     graph.add_edges_from([('a', 'b'), ('b', 'c'), ('c', 'd'), ('d', 'a')])
     with pytest.raises(RuntimeError):
-        multi.MultiQubitGateManager(graph=graph)
+        gatemgr.GateManager(graph=graph)
 
     graph = deepcopy(simple_graph)
     graph.remove_edge(0, 1)
     with pytest.raises(RuntimeError):
-        multi.MultiQubitGateManager(graph=graph)
+        gatemgr.GateManager(graph=graph)
 
-    manager = multi.MultiQubitGateManager(graph=simple_graph)
+    manager = gatemgr.GateManager(graph=simple_graph)
     dist = manager.distance_matrix
 
     assert dist[0][1] == 1
@@ -693,7 +693,7 @@ def test_qubit_manager_generate_one_swap_step(qubit_manager):
     mapping = {i: i for i in range(9)}
     (logical_id0, backend_id0, logical_id1,
      backend_id1) = manager._generate_one_swap_step(
-         mapping, multi.nearest_neighbours_cost_fun, {})
+         mapping, gatemgr.nearest_neighbours_cost_fun, {})
 
     assert logical_id0 in (0, 8)
     if logical_id0 == 0:
@@ -704,7 +704,7 @@ def test_qubit_manager_generate_one_swap_step(qubit_manager):
     mapping = {0: 0, 8: 8}
     (logical_id0, backend_id0, logical_id1,
      backend_id1) = manager._generate_one_swap_step(
-         mapping, multi.nearest_neighbours_cost_fun, {})
+         mapping, gatemgr.nearest_neighbours_cost_fun, {})
 
     assert logical_id1 == -1
     if logical_id0 == 0:
@@ -721,7 +721,7 @@ def test_qubit_manager_generate_one_swap_step(qubit_manager):
     mapping = {i: i for i in range(9)}
     (logical_id0, backend_id0, logical_id1,
      backend_id1) = manager._generate_one_swap_step(
-         mapping, multi.nearest_neighbours_cost_fun, {})
+         mapping, gatemgr.nearest_neighbours_cost_fun, {})
 
     # In this case, the only swap that does not increases the overall distance
     # is (0, 1)
@@ -739,7 +739,7 @@ def test_qubit_manager_generate_swaps(qubit_manager):
     mapping = {i: i for i in range(9)}
 
     swaps, all_qubits = manager.generate_swaps(
-        mapping, multi.nearest_neighbours_cost_fun)
+        mapping, gatemgr.nearest_neighbours_cost_fun)
 
     assert not swaps
     assert not all_qubits
@@ -751,14 +751,14 @@ def test_qubit_manager_generate_swaps(qubit_manager):
 
     with pytest.raises(RuntimeError):
         manager.generate_swaps(mapping,
-                               multi.nearest_neighbours_cost_fun,
+                               gatemgr.nearest_neighbours_cost_fun,
                                max_steps=2)
 
     # ----------------------------------
 
     mapping = {i: i for i in range(9)}
     swaps, _ = manager.generate_swaps(mapping,
-                                      multi.nearest_neighbours_cost_fun)
+                                      gatemgr.nearest_neighbours_cost_fun)
 
     # Make sure the original mapping was not modified
     assert mapping == {i: i for i in range(9)}
@@ -775,7 +775,7 @@ def test_qubit_manager_generate_swaps(qubit_manager):
 
     mapping = {i: i for i in range(9)}
     swaps, _ = manager.generate_swaps(mapping,
-                                      multi.look_ahead_parallelism_cost_fun,
+                                      gatemgr.look_ahead_parallelism_cost_fun,
                                       opts={'W': 0.5})
     reverse_mapping = {v: k for k, v in mapping.items()}
     for id0, id1 in swaps:
@@ -794,7 +794,7 @@ def test_qubit_manager_generate_swaps(qubit_manager):
     assert manager.size() == 2
 
     swaps, all_qubits = manager.generate_swaps(
-        mapping, multi.look_ahead_parallelism_cost_fun, opts={
+        mapping, gatemgr.look_ahead_parallelism_cost_fun, opts={
             'W': 0.5,
         })
 
@@ -913,7 +913,7 @@ def test_qubit_manager_generate_swaps_change_mapping(qubit_manager):
     mapping = {i: i for i in range(9)}
 
     swaps, all_qubits = qubit_manager.generate_swaps(
-        mapping, multi.look_ahead_parallelism_cost_fun, {'W': 0.5})
+        mapping, gatemgr.look_ahead_parallelism_cost_fun, {'W': 0.5})
 
     reverse_mapping = {v: k for k, v in mapping.items()}
     for bqb0, bqb1 in swaps:
@@ -939,7 +939,7 @@ def test_qubit_manager_generate_swaps_change_mapping(qubit_manager):
     mapping = {i: i for i in range(9)}
 
     swaps, all_qubits = qubit_manager.generate_swaps(
-        mapping, multi.look_ahead_parallelism_cost_fun, {'W': 0.5})
+        mapping, gatemgr.look_ahead_parallelism_cost_fun, {'W': 0.5})
 
     reverse_mapping = {v: k for k, v in mapping.items()}
     for bqb0, bqb1 in swaps:
@@ -954,7 +954,7 @@ def test_qubit_manager_generate_swaps_change_mapping(qubit_manager):
 
 
 def test_qubit_manager_str():
-    qubit_manager = multi.MultiQubitGateManager(generate_grid_graph(3, 3))
+    qubit_manager = gatemgr.GateManager(generate_grid_graph(3, 3))
 
     qb, allocate_cmds = allocate_all_qubits_cmd(9)
     cmd_list = [
@@ -979,7 +979,7 @@ def test_qubit_manager_str():
         qubit_manager.get_executable_commands(mapping)
 
         swaps, all_qubits = qubit_manager.generate_swaps(
-            mapping, multi.look_ahead_parallelism_cost_fun, {'W': 0.5})
+            mapping, gatemgr.look_ahead_parallelism_cost_fun, {'W': 0.5})
 
         reverse_mapping = {v: k for k, v in mapping.items()}
         for bqb0, bqb1 in swaps: