Add ABADecomposer class.

.github/workflows/tests.yaml

@@ -23,7 +23,7 @@ jobs:
       - name: Install tox
         run: pip install tox
       - name: run tox lint and type
-        run: tox -e lint #,type
+        run: tox -e lint,type
   unit-test:
     name: Unit testing
     needs: lint

.gitignore

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

CONTRIBUTING.md

@@ -0,0 +1,68 @@
+We recommend working on a feature branch and pull request from there.
+
+## Requirements
+
+- `poetry`,
+- `PyCharm` (recommended).
+
+## Creating a feature branch
+
+Make sure your environment contains all the updated versions of the dependencies.
+
+From an OpenSquirrel checkout:
+
+```
+$ poetry shell
+$ poetry install
+```
+
+And that you base your feature branch off an updated `develop`.
+
+From a `poetry` shell (started from an OpenSquirrel checkout):
+
+```
+$ git checkout develop
+$ git fetch origin
+$ git pull
+$ git branch <feature branch name>
+```
+
+## Before creating the pull request
+
+Make sure the tests and the following linters pass.
+From a `poetry` shell (started from an OpenSquirrel checkout):
+
+```
+$ pytest -vv
+$ mypy . --strict
+$ poetry run isort .
+$ poetry run black .
+```
+
+## Setting the Python interpreter (PyCharm)
+
+You can choose the Python interpreter from the `poetry` environment.
+
+- Go to `Settings` > `Project: OpenSquirrel` > `Python Interpreter`.
+- Click on `Add Interpeter`, and then select `Add Local Interpreter`.
+- Select `Poetry Environment`, and then `Existing environment`.
+- Click on `...` to navigate to the `Interpreter` binary.
+
+## Running/Debugging tests (PyCharm)
+
+To run/debug all tests:
+
+- Right-click on the `test` folder of the Project tree.
+- Click `Run 'pytest' in test` or `Debug 'pytest' in test`.
+
+This will also create a `Run/Debug Configuration`.
+
+### Troubleshooting
+
+If breakpoints are not hit during debugging:
+
+- Go to `Run/Debug Configurations`.
+- Add `--no-cov` in the `Additional arguments` text box.
+
+This issue may be due to the code coverage module _hijacking_ the tracing mechanism
+(check [this link](https://stackoverflow.com/a/56235965/260313) for a more detailed explanation).

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,16 +1,15 @@
 from __future__ import annotations
 
-from typing import Callable, Dict
-
-import numpy as np
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING, Any, Literal
 
 from opensquirrel.decomposer import general_decomposer
 from opensquirrel.decomposer.general_decomposer import Decomposer
 from opensquirrel.default_gates import default_gate_aliases, default_gate_set
 from opensquirrel.default_measurements import default_measurement_set
 from opensquirrel.exporter.export_format import ExportFormat
 from opensquirrel.ir import IR, Gate, Measure
-from opensquirrel.mapper import IdentityMapper, Mapper
+from opensquirrel.mapper import Mapper
 from opensquirrel.register_manager import RegisterManager
 
 
@@ -38,7 +37,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
@@ -49,17 +48,19 @@ def __repr__(self) -> str:
 
         return writer.circuit_to_string(self)
 
-    def __eq__(self, other):
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, Circuit):
+            return False
         return self.register_manager == other.register_manager and self.ir == other.ir
 
     @classmethod
     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,
+    ) -> Circuit:
         """Create a circuit object from a cQasm3 string. All the gates in the circuit need to be defined in
         the `gates` argument.
 
@@ -91,7 +92,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 +101,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 +113,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,15 +1,20 @@
 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
 from opensquirrel.default_measurements import default_measurement_set
 from opensquirrel.instruction_library import GateLibrary, MeasurementLibrary
-from opensquirrel.ir import IR, Comment, Gate, Qubit
+from opensquirrel.ir import IR, Comment, Gate, Measure
 from opensquirrel.register_manager import RegisterManager
 
+if TYPE_CHECKING:
+    from typing import Self
+
 
 class CircuitBuilder(GateLibrary, MeasurementLibrary):
     """
@@ -41,40 +46,48 @@ 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.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):
+    def _add_instruction(self, attr: str, *args: Any) -> Self:
+        if any(attr == measure.__name__ for measure in self.measurement_set):
+            generator_f_measure = MeasurementLibrary.get_measurement_f(self, attr)
+            self._check_generator_f_args(generator_f_measure, attr, args)
+            self.ir.add_measurement(generator_f_measure(*args))
+        else:
+            generator_f_gate = GateLibrary.get_gate_f(self, attr)
+            self._check_generator_f_args(generator_f_gate, attr, args)
+            self.ir.add_gate(generator_f_gate(*args))
+        return self
+
+    @staticmethod
+    def _check_generator_f_args(generator_f: Callable[..., Gate | Measure], attr: str, args: tuple[Any, ...]) -> None:
+        for i, par in enumerate(inspect.signature(generator_f).parameters.values()):
+            if isinstance(par.annotation, str):
+                if args[i].__class__.__name__ != par.annotation:
                     raise TypeError(
-                        f"Wrong argument type for instruction `{attr}`, got {type(args[i])} but expected"
-                        f" {par.annotation}"
+                        f"Wrong argument type for instruction `{attr}`, got {type(args[i])} but expected {par.annotation}"
                     )
-
-        return add_comment if attr == "comment" else add_instruction
+            elif 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,38 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
 import numpy as np
+from numpy.typing import NDArray
 
-from opensquirrel.circuit import Circuit
-from opensquirrel.ir import IR, Comment, Gate, IRVisitor
+from opensquirrel.ir import Comment, Gate, IRVisitor
 from opensquirrel.utils.matrix_expander import get_matrix
 
+if TYPE_CHECKING:
+    from opensquirrel.circuit import Circuit
+
 
 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
     )