Merge branch 'documentation' of github.com:tqsd/EQSN_python

Author: benjione

eqsn/gates.py

@@ -67,6 +67,9 @@ def stop_all(self):
     def X_gate(self, q_id):
         """
         Applies the Pauli X gate to the Qubit with q_id.
+
+        Args:
+            q_id(String): ID of the Qubit to apply the gate to.
         """
         x = np.array([[0, 1], [1, 0]], dtype=np.csingle)
         q = self.shared_dict.get_queues_for_ids([q_id])[0]
@@ -75,6 +78,9 @@ def X_gate(self, q_id):
     def Y_gate(self, q_id):
         """
         Applies the Pauli Y gate to the Qubit with q_id.
+
+        Args:
+            q_id(String): ID of the Qubit to apply the gate to.
         """
         x = np.array([[0, 0 - 1j], [0 + 1j, 0]], dtype=np.csingle)
         q = self.shared_dict.get_queues_for_ids([q_id])[0]
@@ -83,6 +89,9 @@ def Y_gate(self, q_id):
     def Z_gate(self, q_id):
         """
         Applies the Pauli Z gate to the Qubit with q_id.
+
+        Args:
+            q_id(String): ID of the Qubit to apply the gate to.
         """
         x = np.array([[1, 0], [0, -1]], dtype=np.csingle)
         q = self.shared_dict.get_queues_for_ids([q_id])[0]
@@ -91,6 +100,9 @@ def Z_gate(self, q_id):
     def H_gate(self, q_id):
         """
         Applies the Hadamard gate to the Qubit with q_id.
+
+        Args:
+            q_id(String): ID of the Qubit to apply the gate to.
         """
         x = (1 / 2.0) ** 0.5 * np.array([[1, 1], [1, -1]], dtype=np.csingle)
         q = self.shared_dict.get_queues_for_ids([q_id])[0]
@@ -99,6 +111,9 @@ def H_gate(self, q_id):
     def T_gate(self, q_id):
         """
         Applies the T gate to the Qubit with q_id.
+
+        Args:
+            q_id(String): ID of the Qubit to apply the gate to.
         """
         x = np.array(
             [[1, 0], [0, (0.7071067811865476 + 0.7071067811865475j)]],
@@ -109,6 +124,9 @@ def T_gate(self, q_id):
     def S_gate(self, q_id):
         """
         Applies the S gate to the Qubit with q_id.
+
+        Args:
+            q_id(String): ID of the Qubit to apply the gate to.
         """
         x = np.array([[1, 0], [0, 1j]], dtype=np.csingle)
         q = self.shared_dict.get_queues_for_ids([q_id])[0]
@@ -117,14 +135,21 @@ def S_gate(self, q_id):
     def K_gate(self, q_id):
         """
         Applies the K gate to the Qubit with q_id.
+
+        Args:
+            q_id(String): ID of the Qubit to apply the gate to.
         """
         x = 0.5 * np.array([[1+1j, 1-1j], [-1+1j, -1-1j]], dtype=np.csingle)
         q = self.shared_dict.get_queues_for_ids([q_id])[0]
         q.put([SINGLE_GATE, x, q_id])
 
     def RX_gate(self, q_id, rad):
         """
-        Applies the T gate to the Qubit with q_id.
+        Applies a rotational X gate to the Qubit with q_id.
+
+        Args:
+            q_id(String): ID of the Qubit to apply the gate to.
+            rad(int): Rotational degrees in rad.
         """
         mid = np.cos(rad / 2)
         other = -1j * np.sin(rad / 2)
@@ -134,7 +159,11 @@ def RX_gate(self, q_id, rad):
 
     def RY_gate(self, q_id, rad):
         """
-        Applies the T gate to the Qubit with q_id.
+        Applies a rotational Y gate to the Qubit with q_id.
+
+        Args:
+            q_id(String): ID of the Qubit to apply the gate to.
+            rad(int): Rotational degrees in rad.
         """
         mid = np.cos(rad / 2)
         other = np.sin(rad / 2)
@@ -144,7 +173,11 @@ def RY_gate(self, q_id, rad):
 
     def RZ_gate(self, q_id, rad):
         """
-        Applies the T gate to the Qubit with q_id.
+        Applies a rotational Z gate to the Qubit with q_id.
+
+        Args:
+            q_id(String): ID of the Qubit to apply the gate to.
+            rad(int): Rotational degrees in rad.
         """
         top = np.exp(-1j * (rad / 2))
         bot = np.exp(1j * (rad / 2))
@@ -155,6 +188,10 @@ def RZ_gate(self, q_id, rad):
     def custom_gate(self, q_id, gate):
         """
         Applies a custom gate to the qubit with q_id.
+
+        Args:
+            q_id(String): Id of the Qubit to apply the gate on.
+            gate(np.ndarray): unitary 2x2 matrix, of the gate.
         """
         q = self.shared_dict.get_queues_for_ids([q_id])[0]
         q.put([SINGLE_GATE, gate, q_id])
@@ -216,18 +253,45 @@ def cphase_gate(self, applied_to_id, controlled_by_id):
         q.put([CONTROLLED_GATE, x, applied_to_id, controlled_by_id])
 
     def give_statevector_for(self, q_id):
+        """
+        Gives the statevector and Qubits of a Qubit and all other Qubits with
+        which the qubit is entangled.
+
+        Args:
+            q_id(String): Qubit id of the Qubit to get the statevector from.
+
+        Returns:
+            Tuple. Tuple of a lists and vector, where the first list are the qubits of
+            the statevector and the second list is the statevector.
+        """
         ret = self.manager.Queue()
         q = self.shared_dict.get_queues_for_ids([q_id])[0]
         q.put([GIVE_STATEVECTOR, q_id, ret])
         qubits, vector = ret.get()
         return qubits, vector
 
     def custom_two_qubit_gate(self, q_id1, q_id2, gate):
+        """
+        Applies a two Qubit gate to two Qubits.
+
+        Args:
+            q_id1(String): ID of the first Qubit of the gate.
+            q_id2(String): ID of the second Qubit of the gate.
+            gate(np.ndarray): 4x4 unitary matrix gate.
+        """
         self.merge_qubits(q_id1, q_id2)
         q = self.shared_dict.get_queues_for_ids([q_id1])[0]
         q.put([DOUBLE_GATE, gate, q_id1, q_id2])
 
     def custom_controlled_gate(self, applied_to_id, controlled_by_id, gate):
+        """
+        Applies a custom controlled gate to a Qubit.
+
+        Args:
+            applied_to_id(String): ID of the qubit to apply the gate to.
+            controlled_by_id(String): ID of the qubit which controls the gate.
+            gate(np.ndarray): Unitary 2x2 matrix which should be applied.
+        """
         self.merge_qubits(applied_to_id, controlled_by_id)
         q = self.shared_dict.get_queues_for_ids([applied_to_id])[0]
         q.put([CONTROLLED_GATE, gate, applied_to_id, controlled_by_id])

eqsn/process_picker.py

@@ -5,17 +5,25 @@ class ProcessPicker(object):
     __instance = None
 
     @staticmethod
-    def get_instance(cpu_count, process_queue_list):
+    def get_instance(amount_processes, process_queue_list):
+        """
+        Gets the existing instance of the Process Picker class. If none exists,
+        a new object o the class is created.
+
+        Args:
+            cpu_count(int): The amount of CPU cores.
+            process_queue_list(List): A List of all Processes.
+        """
         if ProcessPicker.__instance is None:
-            return ProcessPicker(cpu_count, process_queue_list)
+            return ProcessPicker(amount_processes, process_queue_list)
         return ProcessPicker.__instance
 
-    def __init__(self, cpu_count, process_queue_list):
+    def __init__(self, amount_processes, process_queue_list):
         if ProcessPicker.__instance is not None:
             raise ValueError(
                 "Use get instance to get the Process picker class.")
         ProcessPicker.__instance = self
-        self.amount_processes = cpu_count
+        self.amount_processes = amount_processes
         self.pointer = 0
         self.process_queue_list = process_queue_list
 
@@ -29,4 +37,7 @@ def get_next_process_queue(self):
         return res_q
 
     def stop_process_picker(self):
+        """
+        Released the process picker object.
+        """
         ProcessPicker.__instance = None

eqsn/qubit_thread.py

@@ -18,6 +18,11 @@
 
 
 class QubitThread(object):
+    """
+    The Qubit thread is the smallest object in EQSN.
+    It consists of a statevector and the Qubit IDs of the state vector.
+    Most operations here can be applid asynchronously.
+    """
 
     def __init__(self, q_id, queue):
         """
@@ -42,15 +47,15 @@ def __init__(self, q_id, queue):
 
         logging.debug("Qubit thread with qubit %s has been created.", q_id)
 
-    def apply_single_gate(self, mat, q_id):
+    def apply_single_gate(self, gate, q_id):
         """
         Applys a single gate to a qubit.
 
         Args:
-            mat (np.array): 2x2 unitary array.
+            gate (np.array): 2x2 unitary array.
             id (String): Qubit on which the gate should be applied to.
         """
-        apply_mat = mat
+        apply_mat = gate
         nr = self.qubits.index(q_id)
         total_amount = len(self.qubits)
         before = nr
@@ -62,11 +67,17 @@ def apply_single_gate(self, mat, q_id):
         self.qubit = np.dot(apply_mat, self.qubit)
 
     def give_statevector(self, channel):
+        """
+        Sends the Qubit IDs and their state vectors over a channel.
+
+        Args:
+            channel(Queue): Channel to return the requested data to.
+        """
         channel.put((dp(self.qubits), dp(self.qubit)))
 
     def apply_controlled_gate(self, mat, q_id1, q_id2):
         """
-        Apply a controlled gate to
+        Applies a controlled gate to q_id1
         """
         first_mat = 1
         second_mat = 1
@@ -111,7 +122,11 @@ def apply_controlled_gate(self, mat, q_id1, q_id2):
 
     def merge_accept(self, channel):
         """
-        Receive another process to merge it with this one.
+        Receive the statevector and qubit information of another
+        thread with this thread and merge the vectors.
+
+        Args:
+            channel(Queue): channel to receive qubit ids and statevectors from.
         """
         ids = channel.get()
         vector = channel.get()
@@ -122,6 +137,11 @@ def merge_accept(self, channel):
     def merge_send(self, channel, chanel2):
         """
         Send own process data to another process and suicide.
+
+        Args:
+            channel(Queue): Channel to send own data to other Qubit Thread.
+            channel2(Queue): Channel to send qubit ids to parent, to update
+                             the qubit ids in its dictionary.
         """
         channel.put(dp(self.qubits))
         channel.put(dp(self.qubit))
@@ -132,6 +152,9 @@ def swap_qubits(self, q_id1, q_id2):
         """
         Swaps the position of qubit q_id1 with q_id2
         in the statevector.
+
+        q_id1(String): Qubit id of one of the qubits to swap.
+        q_id2(String): Qubit id of the other qubit to swap.
         """
         def cnot(q_id1, q_id2):
             mat = np.asarray([[0, 1], [1, 0]])
@@ -150,7 +173,15 @@ def cnot(q_id1, q_id2):
         i2 = self.qubits.index(q_id2)
         self.qubits[i1], self.qubits[i2] = self.qubits[i2], self.qubits[i1]
 
-    def apply_two_qubit_gate(self, mat, q_id1, q_id2):
+    def apply_two_qubit_gate(self, gate, q_id1, q_id2):
+        """
+        Applies a two qubit gate to the statevector.
+
+        Args:
+            gate(np.ndarray): 4x4 unitary matrix
+            q_id1(String): First qubit id.
+            q_id2(String): Second qubit id.
+        """
         # Bring the qubits in the right order
         i2 = self.qubits.index(q_id2)
         if i2 > 0:
@@ -159,7 +190,7 @@ def apply_two_qubit_gate(self, mat, q_id1, q_id2):
         else:
             self.swap_qubits(q_id1, self.qubits[0])
             self.swap_qubits(q_id2, self.qubits[1])
-        apply_mat = mat
+        apply_mat = gate
         nr1 = self.qubits.index(q_id1)
         total_amount = len(self.qubits)
         before = nr1
@@ -170,9 +201,13 @@ def apply_two_qubit_gate(self, mat, q_id1, q_id2):
             apply_mat = np.kron(apply_mat, np.eye(2 ** after))
         self.qubit = np.dot(apply_mat, self.qubit)
 
-    def measure_non_destructive(self, q_id, ret_channel):
+    def measure_non_destructive(self, q_id, channel):
         """
         Perform a non destructive measurement on qubit with the id.
+
+        Args:
+            q_id(String): ID of the Qubit to measure.
+            channel(Queue): Channel to transmit measurement result to.
         """
         # determine probability for |1>
         measure_vec = np.array([1, 0], dtype=np.csingle)
@@ -194,11 +229,11 @@ def measure_non_destructive(self, q_id, ret_channel):
         reduction_mat = None
         if meas_res == 0:
             # |0> has been measured
-            ret_channel.put(0)
+            channel.put(0)
             reduction_mat = np.array([[1, 0], [0, 0]], dtype=np.csingle)
         else:
             # |1> has been measured
-            ret_channel.put(1)
+            channel.put(1)
             reduction_mat = np.array([[0, 0], [0, 1]], dtype=np.csingle)
         if before > 0:
             reduction_mat = np.kron(
@@ -212,9 +247,13 @@ def measure_non_destructive(self, q_id, ret_channel):
         norm = np.linalg.norm(self.qubit)
         self.qubit = self.qubit / norm
 
-    def measure(self, q_id, ret_channel):
+    def measure(self, q_id, channel):
         """
         Perform a destructive measurement on qubit with the id.
+
+        Args:
+            q_id(String): ID of the Qubit to measure.
+            channel(Queue): Channel to transmit measurement result to.
         """
         # determine probability for |1>
         measure_vec = np.array([1, 0], dtype=np.csingle)
@@ -236,11 +275,11 @@ def measure(self, q_id, ret_channel):
         reduction_mat = None
         if meas_res == 0:
             # |0> has been measured
-            ret_channel.put(0)
+            channel.put(0)
             reduction_mat = np.array([1, 0], dtype=np.csingle)
         else:
             # |1> has been measured
-            ret_channel.put(1)
+            channel.put(1)
             reduction_mat = np.array([0, 1], dtype=np.csingle)
         if before > 0:
             reduction_mat = np.kron(
@@ -278,6 +317,7 @@ def run(self):
             elif item[0] == MERGE_ACCEPT:
                 self.merge_accept(item[1])
             elif item[0] == MERGE_SEND:
+                # After merge, this thread is not needed anymore
                 self.merge_send(item[1], item[2])
                 return
             elif item[0] == MEASURE_NON_DESTRUCTIVE: