Update docstring for QuantumProgram and add various type hints (#135)

src/benchq/algorithms/gsee.py

@@ -2,19 +2,22 @@
 
 import numpy as np
 from orquestra.integrations.cirq.conversions import to_openfermion
+from orquestra.quantum.operators import PauliRepresentation
 
 from ..conversions import openfermion_to_pyliqtr
 from ..data_structures import AlgorithmImplementation, ErrorBudget
 from ..problem_embeddings import get_qsp_program
 
 
-def _n_block_encodings(hamiltonian, precision):
+def _n_block_encodings(hamiltonian: PauliRepresentation, precision: float):
     pyliqtr_operator = openfermion_to_pyliqtr(to_openfermion(hamiltonian))
 
     return int(np.ceil(np.pi * (pyliqtr_operator.alpha) / (precision)))
 
 
-def qpe_gsee_algorithm(hamiltonian, precision, failure_tolerance):
+def qpe_gsee_algorithm(
+    hamiltonian: PauliRepresentation, precision: float, failure_tolerance: float
+):
     warnings.warn("This is experimental implementation, use at your own risk.")
     n_block_encodings = _n_block_encodings(hamiltonian, precision)
     program = get_qsp_program(hamiltonian, n_block_encodings)

src/benchq/data_structures/algorithm_implementation.py

@@ -1,5 +1,7 @@
 from dataclasses import dataclass
-from typing import Generic, TypeVar, Union
+from typing import Generic, TypeVar
+
+from orquestra.quantum.circuits import Circuit
 
 from .error_budget import ErrorBudget
 from .graph_partition import GraphPartition
@@ -15,6 +17,8 @@ class AlgorithmImplementation(Generic[T]):
     n_calls: int
 
 
-def get_algorithm_implementation_from_circuit(circuit, error_budget, n_calls=1):
+def get_algorithm_implementation_from_circuit(
+    circuit: Circuit, error_budget: ErrorBudget, n_calls: int = 1
+):
     quantum_program = get_program_from_circuit(circuit)
     return AlgorithmImplementation(quantum_program, error_budget, n_calls)

src/benchq/data_structures/hardware_architecture_models.py

@@ -39,7 +39,7 @@ def surface_code_cycle_time_in_seconds(self) -> float:
 @runtime_checkable
 class DetailedArchitectureModel(BasicArchitectureModel, Protocol):
     """DetailedArchitectureModel extends basic one, with the ability to
-    calculate detailed hardware estimates"""
+    calculate detailed hardware estimates."""
 
     def get_hardware_resource_estimates(self, resource_info: ResourceInfo):
         pass
@@ -142,7 +142,7 @@ def power_consumed_per_ELU_in_kW(
         # Value reported by IonQ
         return 5.0
 
-    def num_communication_qubits_per_ELU(self, code_distance):
+    def num_communication_qubits_per_ELU(self, code_distance: int):
         # Lookup table generated from simulations of the 3-3-9s protocol by
         # Hudson Leone of UTS
         qubit_count_lookup_table = {
@@ -193,7 +193,7 @@ def num_communication_qubits_per_ELU(self, code_distance):
                 f"Distance should be between 3 and 35. Got {code_distance}"
             )
 
-    def num_communication_ports_per_ELU(self, code_distance):
+    def num_communication_ports_per_ELU(self, code_distance: int):
         # Computes the number of physical ports (optical fibers) going from the
         # ELU to the quantum switch.
         num_communication_ions_per_elu = self.num_communication_qubits_per_ELU(
@@ -209,7 +209,7 @@ def num_communication_ports_per_ELU(self, code_distance):
 
         return num_ports, second_switch_per_elu_necessary
 
-    def functional_designation_of_chains_within_ELU(self, code_distance):
+    def functional_designation_of_chains_within_ELU(self, code_distance: int):
         # Functional designation of chains within the ELU
         memory_qubits = code_distance
         computational_qubits = 2 * code_distance**2
@@ -218,9 +218,9 @@ def functional_designation_of_chains_within_ELU(self, code_distance):
 
     def num_optical_cross_connect_layers(
         self,
-        num_elus,
-        num_communication_qubits_per_elu,
-        num_communication_ports_per_elu,
+        num_elus: int,
+        num_communication_qubits_per_elu: int,
+        num_communication_ports_per_elu: int,
     ):
         # Description of accounting of optical cross-connect and switch architecture:
         # Need to ensure that each ELU can be connected with its nearest neighbor in
@@ -241,7 +241,7 @@ def num_optical_cross_connect_layers(
         return num_OXC_layers
 
     def num_ELUs_per_optical_cross_connect(
-        self, code_distance, num_communication_qubits
+        self, code_distance: int, num_communication_qubits: int
     ):
         warnings.warn("This output parameter has yet to be implemented.")
         num_ELUs_per_OXC = None

src/benchq/data_structures/quantum_program.py

@@ -7,30 +7,25 @@
 
 
 class QuantumProgram:
-    """Simple structure describing a quantum program consisting of multiple circuits
-
-    Params:
-        circuits: a sequence of circuits, each representing
-        steps: number of steps in the circuit.
-
-    """
+    """A quantum circuit represented as a sequence of subroutine invocations."""
 
     def __init__(
         self,
         subroutines: Sequence[Circuit],
         steps: int,
         calculate_subroutine_sequence: Callable[[int], Sequence[int]],
     ) -> None:
-        """An object which abbreviates repeated subcircuits within a quantum circuit.
-        Each one of these subcircuits is called a subroutine and the subroutine_sequence
-        is a list of indices which specify the order in which the subroutines.
+        """Initializer for the QuantumProgram class.
 
         Args:
-            subroutines (Sequence[Circuit]): a list of integers labeled 0 through the
-                number of subroutines showing how the subroutines are ordered.
-            subroutine_sequence (Sequence[int]): _description_
-            steps (int): _description_
-            calculate_multiplicities (Callable[[int], Sequence[int]]): _description_
+            subroutines: The circuits which are used in the program. All subroutines
+                must act on the same number of qubits.
+            steps: The number of repetitions of the main repeated part of the circuit.
+            calculate_subroutine_sequence: A function which takes the number of steps
+                and returns a list containing the indices of the subroutines to be used.
+
+        Raises:
+            ValueError: If the subroutines do not all act on the same number of qubits.
         """
         if not all(
             subroutine.n_qubits == subroutines[0].n_qubits for subroutine in subroutines
@@ -106,7 +101,7 @@ def from_circuit(circuit: Circuit) -> "QuantumProgram":
         )
 
 
-def get_program_from_circuit(circuit):
+def get_program_from_circuit(circuit: Circuit):
     return QuantumProgram(
         [circuit], steps=1, calculate_subroutine_sequence=lambda x: [0]
     )