166 type hinting

.gitignore

@@ -127,6 +127,7 @@ venv/
 ENV/
 env.bak/
 venv.bak/
+venv38/
 
 # Spyder project settings
 .spyderproject

opensquirrel/__init__.py

@@ -1,3 +1,5 @@
 from opensquirrel.circuit import Circuit
 from opensquirrel.circuit_builder import CircuitBuilder
 from opensquirrel.default_gates import default_gate_aliases
+
+__all__ = ["Circuit", "CircuitBuilder", "default_gate_aliases"]

opensquirrel/circuit.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
-from typing import Callable, Dict
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING, Any, Literal
 
 import numpy as np
+from numpy.typing import NDArray
 
 from opensquirrel.decomposer import general_decomposer
 from opensquirrel.decomposer.general_decomposer import Decomposer
@@ -13,6 +15,9 @@
 from opensquirrel.mapper import IdentityMapper, Mapper
 from opensquirrel.register_manager import RegisterManager
 
+if TYPE_CHECKING:
+    from typing import Self
+
 
 class Circuit:
     """The Circuit class is the only interface to access OpenSquirrel's features.
@@ -38,7 +43,7 @@ class Circuit:
         <BLANKLINE>
     """
 
-    def __init__(self, register_manager: RegisterManager, ir: IR):
+    def __init__(self, register_manager: RegisterManager, ir: IR) -> None:
         """Create a circuit object from a register manager and an IR."""
         self.register_manager = register_manager
         self.ir = ir
@@ -56,10 +61,10 @@ def __eq__(self, other):
     def from_string(
         cls,
         cqasm3_string: str,
-        gate_set: [Callable[..., Gate]] = default_gate_set,
-        gate_aliases: Dict[str, Callable[..., Gate]] = default_gate_aliases,
-        measurement_set: [Callable[..., Measure]] = default_measurement_set,
-    ):
+        gate_set: list[Callable[..., Gate]] = default_gate_set,
+        gate_aliases: Mapping[str, Callable[..., Gate]] = default_gate_aliases,
+        measurement_set: list[Callable[..., Measure]] = default_measurement_set,
+    ) -> Self:
         """Create a circuit object from a cQasm3 string. All the gates in the circuit need to be defined in
         the `gates` argument.
 
@@ -91,7 +96,7 @@ def qubit_register_size(self) -> int:
     def qubit_register_name(self) -> str:
         return self.register_manager.qubit_register_name
 
-    def merge_single_qubit_gates(self):
+    def merge_single_qubit_gates(self) -> None:
         """Merge all consecutive 1-qubit gates in the circuit.
 
         Gates obtained from merging other gates become anonymous gates.
@@ -100,7 +105,7 @@ def merge_single_qubit_gates(self):
 
         general_merger.merge_single_qubit_gates(self)
 
-    def decompose(self, decomposer: Decomposer):
+    def decompose(self, decomposer: Decomposer) -> None:
         """Generic decomposition pass. It applies the given decomposer function to every gate in the circuit."""
         general_decomposer.decompose(self.ir, decomposer)
 
@@ -112,14 +117,14 @@ def map(self, mapper: Mapper) -> None:
 
         remap_ir(self, mapper.get_mapping())
 
-    def replace(self, gate_generator: Callable[..., Gate], f):
+    def replace(self, gate_generator: Callable[..., Gate], f: Callable[..., list[Gate]]) -> None:
         """Manually replace occurrences of a given gate with a list of gates.
         `f` is a callable that takes the arguments of the gate that is to be replaced
         and returns the decomposition as a list of gates.
         """
         general_decomposer.replace(self.ir, gate_generator, f)
 
-    def export(self, fmt: ExportFormat = None) -> None:
+    def export(self, fmt: Literal[ExportFormat.QUANTIFY_SCHEDULER] | None = None) -> Any:
         if fmt == ExportFormat.QUANTIFY_SCHEDULER:
             from opensquirrel.exporter import quantify_scheduler_exporter
 

opensquirrel/circuit_builder.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 import inspect
-from typing import Callable, Dict
+from collections.abc import Callable, Mapping
+from functools import partial
+from typing import TYPE_CHECKING, Any
 
 from opensquirrel.circuit import Circuit
 from opensquirrel.default_gates import default_gate_aliases, default_gate_set
@@ -10,6 +12,9 @@
 from opensquirrel.ir import IR, Comment, Gate, Qubit
 from opensquirrel.register_manager import RegisterManager
 
+if TYPE_CHECKING:
+    from typing import Self
+
 
 class CircuitBuilder(GateLibrary, MeasurementLibrary):
     """
@@ -41,40 +46,43 @@ class CircuitBuilder(GateLibrary, MeasurementLibrary):
     def __init__(
         self,
         qubit_register_size: int,
-        gate_set: [Callable[..., Gate]] = default_gate_set,
-        gate_aliases: Dict[str, Callable[..., Gate]] = default_gate_aliases,
-        measurement_set: List[Callable[..., Measure]] = default_measurement_set,
+        gate_set: list[Callable[..., Gate]] = default_gate_set,
+        gate_aliases: Mapping[str, Callable[..., Gate]] = default_gate_aliases,
+        measurement_set: list[Callable[..., Measure]] = default_measurement_set,
     ):
         GateLibrary.__init__(self, gate_set, gate_aliases)
         MeasurementLibrary.__init__(self, measurement_set)
         self.register_manager = RegisterManager(qubit_register_size)
         self.ir = IR()
 
-    def __getattr__(self, attr):
-        def add_comment(comment_string: str) -> CircuitBuilder:
-            self.ir.add_comment(Comment(comment_string))
-            return self
+    def __getattr__(self, attr: Any) -> Callable[..., Self]:
+        if attr == "comment":
+            return self._add_comment
+
+        return partial(self._add_instruction, attr)
 
-        def add_instruction(*args: tuple) -> CircuitBuilder:
-            if any(attr == measure.__name__ for measure in self.measurement_set):
-                generator_f = MeasurementLibrary.get_measurement_f(self, attr)
-                _check_generator_f_args(generator_f, args)
-                self.ir.add_measurement(generator_f(*args))
-            else:
-                generator_f = GateLibrary.get_gate_f(self, attr)
-                _check_generator_f_args(generator_f, args)
-                self.ir.add_gate(generator_f(*args))
-            return self
+    def _add_comment(self, comment_string: str) -> Self:
+        self.squirrel_ir.add_comment(Comment(comment_string))
+        return self
 
-        def _check_generator_f_args(generator_f, args):
-            for i, par in enumerate(inspect.signature(generator_f).parameters.values()):
-                if not isinstance(args[i], par.annotation):
-                    raise TypeError(
-                        f"Wrong argument type for instruction `{attr}`, got {type(args[i])} but expected"
-                        f" {par.annotation}"
-                    )
+    def _add_instruction(self, attr: str, *args: Any) -> Self:
+        if any(attr == measure.__name__ for measure in self.measurement_set):
+            generator_f = MeasurementLibrary.get_measurement_f(self, attr)
+            self._check_generator_f_args(generator_f, attr, args)
+            self.ir.add_measurement(generator_f(*args))
+        else:
+            generator_f = GateLibrary.get_gate_f(self, attr)
+            self._check_generator_f_args(generator_f, args)
+            self.ir.add_gate(generator_f(*args))
+        return self
 
-        return add_comment if attr == "comment" else add_instruction
+    @staticmethod
+    def _check_generator_f_args(generator_f, attr, args) -> None:
+        for i, par in enumerate(inspect.signature(generator_f).parameters.values()):
+            if not isinstance(args[i], par.annotation):
+                raise TypeError(
+                    f"Wrong argument type for instruction `{attr}`, got {type(args[i])} but expected {par.annotation}"
+                )
 
     def to_circuit(self) -> Circuit:
         return Circuit(self.register_manager, self.ir)

opensquirrel/circuit_matrix_calculator.py

@@ -1,27 +1,32 @@
 import numpy as np
+from numpy.typing import NDArray
 
 from opensquirrel.circuit import Circuit
 from opensquirrel.ir import IR, Comment, Gate, IRVisitor
 from opensquirrel.utils.matrix_expander import get_matrix
 
 
 class _CircuitMatrixCalculator(IRVisitor):
-    def __init__(self, qubit_register_size):
+    def __init__(self, qubit_register_size: int) -> None:
         self.qubit_register_size = qubit_register_size
         self.matrix = np.eye(1 << self.qubit_register_size, dtype=np.complex128)
 
-    def visit_gate(self, gate: Gate):
+    def visit_gate(self, gate: Gate) -> None:
         big_matrix = get_matrix(gate, qubit_register_size=self.qubit_register_size)
         self.matrix = big_matrix @ self.matrix
 
-    def visit_comment(self, comment: Comment):
+    def visit_comment(self, comment: Comment) -> None:
         pass
 
 
-def get_circuit_matrix(circuit: Circuit):
+def get_circuit_matrix(circuit: Circuit) -> NDArray[np.complex128]:
     """Compute the (large) unitary matrix corresponding to the circuit.
-    This matrix has 4**n elements, where n is the number of qubits.
-    Result is stored as a numpy array of complex numbers.
+
+    This matrix has 4**n elements, where n is the number of qubits. Result is stored as a numpy array of complex
+    numbers.
+
+    Returns:
+        Matrix representation of the circuit.
     """
     impl = _CircuitMatrixCalculator(circuit.qubit_register_size)
 

opensquirrel/common.py

@@ -1,8 +1,11 @@
+from __future__ import annotations
+
 import cmath
 import math
-from typing import Tuple
+from collections.abc import Iterable
 
 import numpy as np
+from numpy.typing import ArrayLike, NDArray
 
 ATOL = 0.0000001
 
@@ -16,7 +19,8 @@ def normalize_angle(x: float) -> float:
     return t
 
 
-def normalize_axis(axis: np.ndarray):
+def normalize_axis(axis: ArrayLike) -> NDArray[np.float_]:
+    axis = np.asarray(axis, dtype=np.float_)
     norm = np.linalg.norm(axis)
     axis /= norm
     return axis
@@ -27,7 +31,7 @@ def normalize_axis(axis: np.ndarray):
 Z = np.array([[1, 0], [0, -1]])
 
 
-def can1(axis: Tuple[float, float, float], angle: float, phase: float = 0) -> np.ndarray:
+def can1(axis: Iterable[float], angle: float, phase: float = 0) -> NDArray[np.complex_]:
     nx, ny, nz = axis
     norm = math.sqrt(nx**2 + ny**2 + nz**2)
     assert norm > 0.00000001
@@ -40,10 +44,10 @@ def can1(axis: Tuple[float, float, float], angle: float, phase: float = 0) -> np
         math.cos(angle / 2) * np.identity(2) - 1j * math.sin(angle / 2) * (nx * X + ny * Y + nz * Z)
     )
 
-    return result
+    return np.asarray(result, dtype=np.complex_)
 
 
-def are_matrices_equivalent_up_to_global_phase(matrix_a: np.ndarray, matrix_b: np.ndarray) -> bool:
+def are_matrices_equivalent_up_to_global_phase(matrix_a: NDArray[np.complex_], matrix_b: NDArray[np.complex_]) -> bool:
     first_non_zero = next(
         (i, j) for i in range(matrix_a.shape[0]) for j in range(matrix_a.shape[1]) if abs(matrix_a[i, j]) > ATOL
     )

opensquirrel/decomposer/cnot_decomposer.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import math
 
 from opensquirrel.common import ATOL
@@ -17,8 +19,7 @@ class CNOTDecomposer(Decomposer):
     Source of the math: https://threeplusone.com/pubs/on_gates.pdf, chapter 7.5 "ABC decomposition"
     """
 
-    @staticmethod
-    def decompose(g: Gate) -> [Gate]:
+    def decompose(self, g: Gate) -> list[Gate]:
         if not isinstance(g, ControlledGate):
             # Do nothing:
             # - BlochSphereRotation's are only single-qubit,
@@ -37,7 +38,7 @@ def decompose(g: Gate) -> [Gate]:
         # See https://threeplusone.com/pubs/on_gates.pdf
 
         # Try special case first, see https://arxiv.org/pdf/quant-ph/9503016.pdf lemma 5.5
-        controlled_rotation_times_x = general_merger.compose_bloch_sphere_rotations(X(target_qubit), g.target_gate)
+        controlled_rotation_times_x = general_merger.compose_bloch_sphere_rotations(X(target_qubit), g.target_gate)  # type: ignore[arg-type]
         theta0_with_x, theta1_with_x, theta2_with_x = get_zyz_decomposition_angles(
             controlled_rotation_times_x.angle, controlled_rotation_times_x.axis
         )

opensquirrel/decomposer/general_decomposer.py

@@ -1,14 +1,16 @@
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
-from typing import Callable, List
+from collections.abc import Callable, Iterable
 
 from opensquirrel.common import are_matrices_equivalent_up_to_global_phase
 from opensquirrel.ir import IR, Gate
 
 
 class Decomposer(ABC):
-    @staticmethod
+
     @abstractmethod
-    def decompose(gate: Gate) -> [Gate]:
+    def decompose(self, gate: Gate) -> list[Gate]:
         raise NotImplementedError()
 
 
@@ -51,17 +53,18 @@ def decompose(ir: IR, decomposer: Decomposer):
 
 
 class _GenericReplacer(Decomposer):
-    def __init__(self, gate_generator: Callable[..., Gate], replacement_function):
+    def __init__(self, gate_generator: Callable[..., Gate], replacement_function: Callable[..., list[Gate]]) -> None:
         self.gate_generator = gate_generator
         self.replacement_function = replacement_function
 
-    def decompose(self, g: Gate) -> [Gate]:
+    def decompose(self, g: Gate) -> list[Gate]:
         if g.is_anonymous or g.generator != self.gate_generator:
             return [g]
-        return self.replacement_function(*g.arguments)
+        arguments = tuple() if g.arguments is None else g.arguments
+        return self.replacement_function(*arguments)
 
 
-def replace(ir: IR, gate_generator: Callable[..., Gate], f):
+def replace(ir: IR, gate_generator: Callable[..., Gate], f: Callable[..., list[Gate]]):
     """Does the same as decomposer, but only applies to a given gate."""
     generic_replacer = _GenericReplacer(gate_generator, f)
 

opensquirrel/decomposer/mckay_decomposer.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from math import atan2, cos, pi, sin, sqrt
 
 from opensquirrel.common import ATOL, normalize_angle
@@ -7,8 +9,8 @@
 
 
 class McKayDecomposer(Decomposer):
-    @staticmethod
-    def decompose(g: Gate) -> [Gate]:
+
+    def decompose(self, g: Gate) -> list[Gate]:
         """Return the McKay decomposition of a 1-qubit gate as a list of gates.
                 gate   ---->    Rz.Rx(pi/2).Rz.Rx(pi/2).Rz
 

opensquirrel/decomposer/zyz_decomposer.py

@@ -1,5 +1,7 @@
+from __future__ import annotations
+
 import math
-from typing import Tuple
+from collections.abc import Iterable
 
 from opensquirrel.common import ATOL
 from opensquirrel.decomposer.general_decomposer import Decomposer
@@ -8,7 +10,7 @@
 from opensquirrel.utils.identity_filter import filter_out_identities
 
 
-def get_zyz_decomposition_angles(alpha: float, axis: Tuple[float, float, float]) -> Tuple[float, float, float]:
+def get_zyz_decomposition_angles(alpha: float, axis: Iterable[float]) -> tuple[float, float, float]:
     """
     Gives the angles used in the Z-Y-Z decomposition of the Bloch sphere rotation
     characterized by a rotation around `axis` of angle `alpha`.
@@ -31,6 +33,7 @@ def get_zyz_decomposition_angles(alpha: float, axis: Tuple[float, float, float])
     if abs(alpha - math.pi) < ATOL:
         # alpha == pi, math.tan(alpha / 2) is not defined.
 
+        p: float
         if abs(nz) < ATOL:
             theta2 = math.pi
             p = 0
@@ -74,8 +77,7 @@ def get_zyz_decomposition_angles(alpha: float, axis: Tuple[float, float, float])
 
 
 class ZYZDecomposer(Decomposer):
-    @staticmethod
-    def decompose(g: Gate) -> [Gate]:
+    def decompose(self, g: Gate) -> list[Gate]:
         if not isinstance(g, BlochSphereRotation):
             # Only decomposer single-qubit gates.
             return [g]