♻️ make qiskit an optional dependency

Signed-off-by: burgholzer <burgholzer@me.com>

Author: burgholzer

docs/source/library/VerifyCompilation.rst

@@ -22,4 +22,5 @@ Compilation Flow Profile Generation
 QCEC provides dedicated compilation flow profiles for IBM Qiskit which can be used to efficiently verify the results of compilation flow results :cite:p:`burgholzer2020verifyingResultsIBM`.
 These profiles are generated from IBM Qiskit using the :func:`.generate_profile` method.
 
+    .. currentmodule:: mqt.qcec.compilation_flow_profiles
     .. autofunction:: generate_profile

pyproject.toml

@@ -43,10 +43,16 @@ dependencies = [
     "mqt.core>=3.0.0b4",
     "importlib_resources>=5.0; python_version < '3.10'",
     "typing_extensions>=4.2; python_version < '3.11'", # used for typing.Unpack
-    "qiskit[qasm3-import]>=1.0.0",
+    "numpy>=2.1; python_version >= '3.13'",
+    "numpy>=1.26; python_version >= '3.12'",
+    "numpy>=1.24; python_version >= '3.11'",
+    "numpy>=1.22",
 ]
 dynamic = ["version"]
 
+[project.optional-dependencies]
+qiskit = ["qiskit[qasm3-import]>=1.0.0"]
+
 [project.urls]
 Homepage = "https://github.com/cda-tum/mqt-qcec"
 Documentation = "https://mqt.readthedocs.io/projects/qcec"
@@ -310,7 +316,7 @@ build = [
 ]
 docs = [
   "furo>=2024.8.6",
-  "qiskit[visualization]>=1.0.0",
+  "qiskit[qasm3-import,visualization]>=1.0.0",
   "setuptools-scm>=8.1",
   "sphinx-autoapi>=3.4.0",
   "sphinx-copybutton>=0.5.2",
@@ -321,12 +327,11 @@ docs = [
   "ipykernel>=6.29.5",
   "nbsphinx>=0.9.6",
   "sphinx-autodoc-typehints>=2.3.0",
-  "mqt-core[qiskit]>=3.0.0b1",
 ]
 test = [
   "pytest>=8.3.4",
   "pytest-cov>=6",
-  "mqt-core[qiskit]>=3.0.0b1",
+  "qiskit[qasm3-import]>=1.0.0",
 ]
 dev = [
   {include-group = "build"},

src/mqt/qcec/__init__.py

@@ -7,7 +7,7 @@
 from __future__ import annotations
 
 from ._version import version as __version__
-from .compilation_flow_profiles import AncillaMode, generate_profile
+from .compilation_flow_profiles import AncillaMode
 from .pyqcec import (
     ApplicationScheme,
     Configuration,
@@ -26,7 +26,6 @@
     "EquivalenceCriterion",
     "StateType",
     "__version__",
-    "generate_profile",
     "verify",
     "verify_compilation",
 ]

src/mqt/qcec/_compat/optional.py

@@ -0,0 +1,95 @@
+"""Optional dependency tester.
+
+Inspired by Qiskit's LazyDependencyManager
+https://github.com/Qiskit/qiskit/blob/f13673b05edf98263f80a174d2e13a118b4acda7/qiskit/utils/lazy_tester.py#L44
+"""
+
+from __future__ import annotations
+
+import contextlib
+import importlib
+import typing
+import warnings
+
+
+class OptionalDependencyTester:
+    """A manager for optional dependencies to assert their availability.
+
+    This class is used to lazily test for the availability of optional dependencies.
+    It can be used in Boolean contexts to check if the dependency is available.
+    """
+
+    def __init__(self, module: str, *, msg: str | None = None) -> None:
+        """Construct a new optional dependency tester.
+
+        Args:
+            module: the name of the module to test for.
+            msg: an extra message to include in the error raised if this is required.
+        """
+        self._module = module
+        self._bool: bool | None = None
+        self._msg = msg
+
+    def _is_available(self) -> bool:
+        """Test the availability of the module.
+
+        Returns:
+            ``True`` if the module is available, ``False`` otherwise.
+        """
+        try:
+            importlib.import_module(self._module)
+        except ImportError as exc:  # pragma: no cover
+            warnings.warn(
+                f"Module '{self._module}' failed to import with: {exc!r}",
+                category=UserWarning,
+                stacklevel=2,
+            )
+            return False
+        else:
+            return True
+
+    def __bool__(self) -> bool:
+        """Check if the dependency is available.
+
+        Returns:
+            ``True`` if the dependency is available, ``False`` otherwise.
+        """
+        if self._bool is None:
+            self._bool = self._is_available()
+        return self._bool
+
+    def require_now(self, feature: str) -> None:
+        """Eagerly attempt to import the dependency and raise an exception if it cannot be imported.
+
+        Args:
+            feature: the feature that is requiring this dependency.
+
+        Raises:
+            ImportError: if the dependency cannot be imported.
+        """
+        if self:
+            return
+        message = f"The '{self._module}' library is required to {feature}."
+        if self._msg:
+            message += f" {self._msg}."
+        raise ImportError(message)
+
+    @contextlib.contextmanager
+    def disable_locally(self) -> typing.Generator[None, None, None]:
+        """Create a context during which the value of the dependency manager will be ``False``.
+
+        Yields:
+            None
+        """
+        previous = self._bool
+        self._bool = False
+        try:
+            yield
+        finally:
+            self._bool = previous
+
+
+HAS_QISKIT = OptionalDependencyTester(
+    "qiskit",
+    msg="Please install the `mqt.qcec[qiskit]` extra or a compatible version of Qiskit to use functionality related to its functionality.",
+)

src/mqt/qcec/compilation_flow_profiles.py

@@ -7,11 +7,12 @@
 from typing import TYPE_CHECKING, Any
 
 import numpy as np
-from qiskit import QuantumCircuit, transpile
-from qiskit import __version__ as qiskit_version
+
+from ._compat.optional import HAS_QISKIT
 
 if TYPE_CHECKING:
     from numpy.typing import NDArray
+    from qiskit.circuit import QuantumCircuit
 
 
 @unique
@@ -154,8 +155,10 @@ def __str__(self) -> str:
 multi_controlled_gates_v_chain = [mcx_v_chain]
 
 
-def create_general_gate(qubits: int, params: int, controls: int, identifier: str) -> QuantumCircuit:
+def __create_general_gate(qubits: int, params: int, controls: int, identifier: str) -> QuantumCircuit:
     """Create a ``QuantumCircuit`` containing a single gate ``identifier`` with the given number of ``qubits``, ``params``, and ``controls``."""
+    from qiskit.circuit import QuantumCircuit
+
     required_qubits = qubits + controls
     qc = QuantumCircuit(required_qubits)
     gate_identifier = "c" * controls + identifier
@@ -167,7 +170,7 @@ def create_general_gate(qubits: int, params: int, controls: int, identifier: str
     return qc
 
 
-def create_multi_controlled_gate(
+def __create_multi_controlled_gate(
     qubits: int,
     params: int,
     controls: int,
@@ -176,6 +179,8 @@ def create_multi_controlled_gate(
     identifier: str,
 ) -> QuantumCircuit:
     """Create a ``QuantumCircuit`` containing a single multi-controlled gate ``identifier`` with the given number of ``qubits``, ``params``, and ``controls`` using ``ancilla_qubits`` ancilla qubits and the given ancilla ``mode``."""
+    from qiskit.circuit import QuantumCircuit
+
     required_qubits = qubits + controls
 
     # special handling for v-chain mode which is indicated by the ancilla_qubits being None
@@ -208,12 +213,14 @@ def create_multi_controlled_gate(
     return qc
 
 
-def compute_cost(
+def __compute_cost(
     qc: QuantumCircuit,
     basis_gates: list[str],
     optimization_level: int = 1,
 ) -> int:
     """Compute the cost of a circuit by transpiling the circuit to a given ``basis_gates`` gate set and a certain ``optimization_level``."""
+    from qiskit import transpile
+
     transpiled_circuit = transpile(
         qc, basis_gates=basis_gates, optimization_level=optimization_level, seed_transpiler=12345
     )
@@ -228,7 +235,7 @@ class GateType(Enum):
     MULTI_CONTROLLED = 2
 
 
-def create_gate_profile_data(
+def __create_gate_profile_data(
     gate_collection: list[dict[str, Any]],
     gate_type: GateType,
     basis_gates: list[str] | None = None,
@@ -254,9 +261,9 @@ def create_gate_profile_data(
                 qc = None
                 # create the gate
                 if gate_type == GateType.GENERAL:
-                    qc = create_general_gate(qubits, params, control, gate)
+                    qc = __create_general_gate(qubits, params, control, gate)
                 elif gate_type == GateType.MULTI_CONTROLLED:
-                    qc = create_multi_controlled_gate(
+                    qc = __create_multi_controlled_gate(
                         qubits,
                         params,
                         control,
@@ -265,14 +272,14 @@ def create_gate_profile_data(
                         gate,
                     )
                 # compute the cost
-                cost = compute_cost(qc, basis_gates, optimization_level)
+                cost = __compute_cost(qc, basis_gates, optimization_level)
 
                 # add the cost to the profile data
                 profile_data[gate, control] = cost
     return profile_data
 
 
-def add_special_case_data(
+def __add_special_case_data(
     profile_data: dict[tuple[str, int], int],
     special_cases: dict[str, Any] | None = None,
 ) -> None:
@@ -292,19 +299,17 @@ def add_special_case_data(
                 profile_data.setdefault((gate, nc), cost)
 
 
-def generate_profile_name(optimization_level: int = 1, mode: AncillaMode = AncillaMode.NO_ANCILLA) -> str:
-    """Generate a profile name based on the given optimization level and ancilla mode."""
-    return "qiskit_O" + str(optimization_level) + "_" + str(mode) + ".profile"
-
-
-def write_profile_data_to_file(profile_data: dict[tuple[str, int], int], filename: Path) -> None:
+def __write_profile_data_to_file(profile_data: dict[tuple[str, int], int], filename: Path) -> None:
     """Write the profile data to a file."""
+    HAS_QISKIT.require_now("generate compilation flow profiles")
+    from qiskit import __version__ as qiskit_version
+
     with Path(filename).open("w+", encoding="utf-8") as f:
         f.write(f"# {filename}, Qiskit version: {qiskit_version}\n")
         f.writelines(f"{gate} {controls} {cost}\n" for (gate, controls), cost in profile_data.items())
 
 
-def check_recurrence(seq: list[int], order: int = 2) -> list[int] | None:
+def __check_recurrence(seq: list[int], order: int = 2) -> list[int] | None:
     """Determine a recurrence relation with a given ``order`` in ``sequence`` and return the corresponding coefficients or ``None`` if no relation was determined."""
     if len(seq) < (2 * order + 1):
         return None
@@ -325,7 +330,7 @@ def check_recurrence(seq: list[int], order: int = 2) -> list[int] | None:
     return list(coefficients)
 
 
-def find_continuation(
+def __find_continuation(
     profile_data: dict[tuple[str, int], int],
     gate: str,
     cutoff: int = 5,
@@ -345,7 +350,7 @@ def find_continuation(
 
     coeffs = None
     for order in range(1, max_order + 1):
-        coeffs = check_recurrence(sequence, order)
+        coeffs = __check_recurrence(sequence, order)
         if coeffs is not None:
             break
 
@@ -371,6 +376,11 @@ def find_continuation(
 default_profile_path = Path(__file__).resolve().parent.joinpath("profiles")
 
 
+def generate_profile_name(optimization_level: int = 1, mode: AncillaMode = AncillaMode.NO_ANCILLA) -> str:
+    """Generate a profile name based on the given optimization level and ancilla mode."""
+    return "qiskit_O" + str(optimization_level) + "_" + str(mode) + ".profile"
+
+
 def generate_profile(
     optimization_level: int = 1,
     mode: AncillaMode = AncillaMode.NO_ANCILLA,
@@ -392,34 +402,34 @@ def generate_profile(
         filepath = default_profile_path
 
     # generate general profile data
-    profile = create_gate_profile_data(general_gates, GateType.GENERAL, optimization_level=optimization_level)
+    profile = __create_gate_profile_data(general_gates, GateType.GENERAL, optimization_level=optimization_level)
 
     # add multi-controlled gates
     profile.update(
-        create_gate_profile_data(
+        __create_gate_profile_data(
             multi_controlled_gates,
             GateType.MULTI_CONTROLLED,
             optimization_level=optimization_level,
         )
     )
-    find_continuation(profile, gate="p", max_control=max_controls)
+    __find_continuation(profile, gate="p", max_control=max_controls)
 
     gate_collection = gate_collection_for_mode[mode]
 
     # add multi-controlled gates with specific mode
     profile.update(
-        create_gate_profile_data(
+        __create_gate_profile_data(
             gate_collection,
             GateType.MULTI_CONTROLLED,
             optimization_level=optimization_level,
         )
     )
-    find_continuation(profile, gate="x", max_control=max_controls)
+    __find_continuation(profile, gate="x", max_control=max_controls)
 
     # add special case data
-    add_special_case_data(profile)
+    __add_special_case_data(profile)
 
     # write profile data to file
     filename = generate_profile_name(optimization_level=optimization_level, mode=mode)
     filepath = filepath.joinpath(filename)
-    write_profile_data_to_file(profile, filepath)
+    __write_profile_data_to_file(profile, filepath)