qilisdk 0.1.4__py3-none-any.whl → 0.1.5__py3-none-any.whl

qilisdk/digital/ansatz.py

@@ -1,160 +1,203 @@
-# Copyright 2025 Qilimanjaro Quantum Tech
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-from abc import ABC, abstractmethod
-from typing import Any, ClassVar, Literal, Union
-
-from qilisdk.digital.circuit import Circuit
-from qilisdk.digital.gates import CNOT, CZ, U1, U2, U3, M
-from qilisdk.yaml import yaml
-
-
-class Ansatz(ABC):
-    _ONE_QUBIT_GATES: ClassVar[dict[str, type[Union[U1, U2, U3]]]] = {
-        "U1": U1,
-        "U2": U2,
-        "U3": U3,
-    }
-    _TWO_QUBITS_GATES: ClassVar[dict[str, type[Union[CNOT, CZ]]]] = {
-        "CZ": CZ,
-        "CNOT": CNOT,
-    }
-
-    def __init__(self, nqubits: int, layers: int = 1) -> None:
-        self.nqubits = nqubits
-        self.layers = layers
-
-    @property
-    def nparameters(self) -> int:
-        """
-        Retrieve the total number of parameters required by all parameterized gates in the ansatz's circuit.
-
-        Returns:
-            int: The total count of parameters from all parameterized gates.
-        """
-        raise NotImplementedError
-
-    def get_circuit(self, parameters: list[float]) -> Circuit:
-        """Get the underlying circuit with the given list of parameters.
-
-        Args:
-            params (list[float]): the list of parameters for the unitary gates.
-
-        Raises:
-            ValueError: if the number of parameters provided are less than the parameters expected by the ansatz.
-
-        Returns:
-            Circuit: The underlying circuit with the updated parameters.
-        """
-        if len(parameters) != self.nparameters:
-            raise ValueError(f"Expecting {self.nparameters} but received {len(parameters)}")
-
-        return self._construct_circuit(parameters=list(parameters))
-
-    @abstractmethod
-    def _construct_circuit(self, parameters: list[float]) -> Circuit: ...
-
-
-@yaml.register_class
-class HardwareEfficientAnsatz(Ansatz):
-    def __init__(
-        self,
-        n_qubits: int,
-        layers: int = 1,
-        connectivity: Literal["Circular", "Linear", "Full"] | list[tuple[int, int]] = "Linear",
-        structure: Literal["grouped", "interposed"] = "grouped",
-        one_qubit_gate: Literal["U1", "U2", "U3"] = "U1",
-        two_qubit_gate: Literal["CZ", "CNOT"] = "CZ",
-    ) -> None:
-        super().__init__(n_qubits, layers)
-
-        # Define chip topology
-        if isinstance(connectivity, list):
-            self.connectivity = connectivity
-        elif connectivity == "Full":
-            self.connectivity = [(i, j) for i in range(self.nqubits) for j in range(i + 1, self.nqubits)]
-        elif connectivity == "Circular":
-            self.connectivity = [(i, i + 1) for i in range(self.nqubits - 1)] + [(self.nqubits - 1, 0)]
-        elif connectivity == "Linear":
-            self.connectivity = [(i, i + 1) for i in range(self.nqubits - 1)]
-        else:
-            raise ValueError(f"Unrecognized connectivity type ({connectivity}).")
-
-        self.gate_types: dict[str, str] = {"one_qubit_gate": one_qubit_gate, "two_qubit_gates": two_qubit_gate}
-        self.one_qubit_gate: type[Union[U1, U2, U3]] = self._ONE_QUBIT_GATES[one_qubit_gate]
-        self.two_qubit_gate: type[Union[CNOT, CZ]] = self._TWO_QUBITS_GATES[two_qubit_gate]
-
-        if structure not in {"grouped", "interposed"}:
-            raise ValueError(f"provided structure {structure} is not supported.")
-        self.structure = structure
-
-        self.construct_layer_handlers = {
-            "interposed": self._construct_layer_interposed,
-            "grouped": self._construct_layer_grouped,
-        }
-
-    def __getstate__(self) -> dict[str, Any]:
-        state = self.__dict__.copy()
-        # Exclude the mapping that contains bound methods (not serializable).
-        state.pop("construct_layer_handlers", None)
-        return state
-
-    def __setstate__(self, state) -> None:  # noqa: ANN001
-        """
-        Restore the object's state after deserialization and reinitialize any attributes that were omitted.
-        """
-        self.__dict__.update(state)
-        # Reconstruct the mapping with the proper bound methods.
-        self.construct_layer_handlers = {
-            "interposed": self._construct_layer_interposed,
-            "grouped": self._construct_layer_grouped,
-        }
-
-    @property
-    def nparameters(self) -> int:
-        """
-        Retrieve the total number of parameters required by all parameterized gates in the ansatz's circuit.
-
-        Returns:
-            int: The total count of parameters from all parameterized gates.
-        """
-        return self.nqubits * (self.layers + 1) * len(self.one_qubit_gate.PARAMETER_NAMES)
-
-    def _construct_circuit(self, parameters: list[float]) -> Circuit:
-        self._circuit = Circuit(self.nqubits)
-        # Add initial layer of unitaries
-        for i in range(self.nqubits):
-            self._circuit.add(self.one_qubit_gate(i, **dict(zip(self.one_qubit_gate.PARAMETER_NAMES, parameters))))
-
-        construct_layer_handler = self.construct_layer_handlers[self.structure]
-        for _ in range(self.layers):
-            construct_layer_handler(parameters)
-        self._circuit.add(M(*list(range(self.nqubits))))
-
-        return self._circuit
-
-    def _construct_layer_interposed(self, parameters: list[float]) -> None:
-        for i in range(self.nqubits):
-            self._circuit.add(
-                self.one_qubit_gate(i, **{name: parameters.pop() for name in self.one_qubit_gate.PARAMETER_NAMES})
-            )
-            for p, j in self.connectivity:
-                self._circuit.add(self.two_qubit_gate(p, j))
-
-    def _construct_layer_grouped(self, parameters: list[float]) -> None:
-        for i in range(self.nqubits):
-            self._circuit.add(
-                self.one_qubit_gate(i, **{name: parameters.pop() for name in self.one_qubit_gate.PARAMETER_NAMES})
-            )
-        for i, j in self.connectivity:
-            self._circuit.add(self.two_qubit_gate(i, j))
+# Copyright 2025 Qilimanjaro Quantum Tech
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from abc import ABC
+from typing import Iterator, Literal, Type
+
+from qilisdk.digital.circuit import Circuit
+from qilisdk.digital.gates import CNOT, CZ, U1, U2, U3
+from qilisdk.yaml import yaml
+
+Connectivity = Literal["circular", "linear", "full"] | list[tuple[int, int]]
+Structure = Literal["grouped", "interposed"]
+
+
+class Ansatz(Circuit, ABC):
+    """Abstract template for parameterised digital circuits."""
+
+    def __init__(self, nqubits: int) -> None:
+        """
+        Args:
+            nqubits (int): Number of logical qubits in the circuit.
+        """
+        super().__init__(nqubits=nqubits)
+
+
+@yaml.register_class
+class HardwareEfficientAnsatz(Ansatz):
+    """
+    Hardware-efficient ansatz with `(layers + 1)` single-qubit blocks and ``layers``
+    entangling blocks.
+
+    Example:
+        .. code-block:: python
+
+            from qilisdk.digital.ansatz import HardwareEfficientAnsatz
+            from qilisdk.digital.gates import U3, CNOT
+
+            ansatz = HardwareEfficientAnsatz(
+                nqubits=4,
+                layers=3,
+                connectivity="linear",
+                structure="grouped",
+                one_qubit_gate=U3,
+                two_qubit_gate=CNOT,
+            )
+            ansatz.draw()
+
+    Notes:
+        ``structure="grouped"`` applies full single-qubit layers followed by entanglers,
+        while ``structure="interposed"`` alternates single-qubit updates with entanglers
+        per qubit. No measurements are added automatically.
+    """
+
+    def __init__(
+        self,
+        nqubits: int,
+        layers: int = 1,
+        connectivity: Connectivity = "linear",
+        structure: Structure = "grouped",
+        one_qubit_gate: Type[U1 | U2 | U3] = U1,
+        two_qubit_gate: Type[CZ | CNOT] = CZ,
+    ) -> None:
+        """
+        Args:
+            nqubits (int): Number of qubits in the circuit.
+            layers (int, optional): Number of entangling layers. Defaults to 1.
+            connectivity (Connectivity, optional): Topology used for two-qubit gates.
+                Accepts ``"linear"``, ``"circular"``, ``"full"``, or an explicit list of edges.
+                Defaults to ``"linear"``.
+            structure (Structure, optional): Layout of single- and two-qubit gates within each layer.
+                ``"grouped"`` applies all single-qubit gates before the entangler block; ``"interposed"``
+                interleaves them per qubit. Defaults to ``"grouped"``.
+            one_qubit_gate (Type[U1 | U2 | U3], optional): Parameterised single-qubit gate class. Defaults to :class:`U1`.
+            two_qubit_gate (Type[CZ | CNOT], optional): Entangling gate class. Defaults to :class:`CZ`.
+
+        Raises:
+            ValueError: If ``layers`` is negative or the connectivity definition is invalid.
+        """
+        super().__init__(nqubits)
+
+        if layers < 0:
+            raise ValueError("layers must be >= 0")
+
+        self._layers = int(layers)
+        self._connectivity = tuple(self._normalize_connectivity(connectivity))
+        self._structure: Structure = "grouped" if structure.lower() == "grouped" else "interposed"
+        self._one_qubit_gate: type[U1 | U2 | U3] = one_qubit_gate
+        self._two_qubit_gate: type[CZ | CNOT] = two_qubit_gate
+
+        self._build_circuit()
+
+    @property
+    def layers(self) -> int:
+        """Number of entangling layers."""
+        return self._layers
+
+    @property
+    def connectivity(self) -> tuple[tuple[int, int], ...]:
+        """Entangling edges as an immutable tuple of (control, target) pairs."""
+        return self._connectivity
+
+    @property
+    def structure(self) -> Structure:
+        """Declared structure ('grouped' or 'interposed')."""
+        return self._structure
+
+    @property
+    def one_qubit_gate(self) -> type[U1 | U2 | U3]:
+        """Single-qubit gate class used for parameterized layers (U1, U2, or U3)."""
+        return self._one_qubit_gate
+
+    @property
+    def two_qubit_gate(self) -> type[CZ | CNOT]:
+        """Two-qubit entangling gate class (CZ or CNOT)."""
+        return self._two_qubit_gate
+
+    def _normalize_connectivity(self, connectivity: Connectivity) -> list[tuple[int, int]]:
+        """
+        Returns:
+            list[tuple[int, int]]: a validated list of entangling edges derived from ``connectivity``.
+
+        Raises:
+            ValueError: If ``connectivity`` is invalid.
+        """
+        if isinstance(connectivity, list):
+            edges = connectivity
+        else:
+            kind = connectivity.lower()
+            if kind == "full":
+                edges = [(i, j) for i in range(self.nqubits) for j in range(i + 1, self.nqubits)]
+            elif kind == "circular":
+                edges = (
+                    []
+                    if self.nqubits < 2  # noqa: PLR2004
+                    else [(i, i + 1) for i in range(self.nqubits - 1)] + [(self.nqubits - 1, 0)]
+                )
+            elif kind == "linear":
+                edges = [(i, i + 1) for i in range(self.nqubits - 1)]
+            else:
+                raise ValueError(f"Unrecognized connectivity: {connectivity!r}")
+
+        # basic validation
+        for a, b in edges:
+            if not (0 <= a < self.nqubits and 0 <= b < self.nqubits):
+                raise ValueError(f"Edge {(a, b)} out of range for {self.nqubits} qubits.")
+            if a == b:
+                raise ValueError(f"Self-edge {(a, b)} is not allowed.")
+        return edges
+
+    def _parameter_blocks(self) -> Iterator[dict[str, float]]:
+        """Yield dictionaries initialised for each parameterised single-qubit gate in build order."""
+        names = tuple(self.one_qubit_gate.PARAMETER_NAMES)
+        blocks = (self.layers + 1) * self.nqubits
+
+        zero = dict.fromkeys(names, 0.0)
+        for _ in range(blocks):
+            # fresh dict each time
+            yield dict(zero)
+
+    def _apply_single_qubit(self, qubit: int, parameter_iterator: Iterator[dict[str, float]]) -> None:
+        """Apply one parameterised single-qubit gate to ``qubit`` using the next parameter block."""
+        params = next(parameter_iterator)
+        self.add(self.one_qubit_gate(qubit, **params))
+
+    def _apply_single_qubit_block(self, parameter_iterator: Iterator[dict[str, float]]) -> None:
+        """Apply a parameterised gate to every qubit using successive parameter blocks."""
+        for qubit in range(self.nqubits):
+            params = next(parameter_iterator)
+            self.add(self.one_qubit_gate(qubit, **params))
+
+    def _apply_entanglers(self) -> None:
+        """Append the entangling block across all connectivity edges."""
+        for i, j in self.connectivity:
+            self.add(self.two_qubit_gate(i, j))
+
+    def _build_circuit(self) -> None:
+        """Populate the circuit according to the current structure and connectivity settings."""
+        # Parameter iterator covering all single-qubit blocks, in order
+        parameter_iterator = iter(self._parameter_blocks())
+
+        # U(0)
+        self._apply_single_qubit_block(parameter_iterator)
+
+        # For each remaining layer: U -> E
+        if self.structure == "grouped":
+            for _ in range(self.layers):
+                self._apply_single_qubit_block(parameter_iterator)
+                self._apply_entanglers()
+        else:
+            for _ in range(self.layers):
+                for q in range(self.nqubits):
+                    self._apply_single_qubit(q, parameter_iterator)
+                    self._apply_entanglers()

qilisdk/digital/circuit.py

@@ -11,8 +11,12 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+
 import numpy as np
 
+from qilisdk.common.parameterizable import Parameterizable
+from qilisdk.common.variables import Parameter, RealNumber
+from qilisdk.utils.visualization import CircuitStyle
 from qilisdk.yaml import yaml
 
 from .exceptions import ParametersNotEqualError, QubitOutOfRangeError
@@ -20,7 +24,7 @@ from .gates import Gate
 
 
 @yaml.register_class
-class Circuit:
+class Circuit(Parameterizable):
     def __init__(self, nqubits: int) -> None:
         """
         Initialize a Circuit instance with a specified number of qubits.
@@ -31,7 +35,7 @@ class Circuit:
         self._nqubits: int = nqubits
         self._gates: list[Gate] = []
         self._init_state: np.ndarray = np.zeros(nqubits)
-        self._parameterized_gates: list[Gate] = []
+        self._parameters: dict[str, Parameter] = {}
 
     @property
     def nqubits(self) -> int:
@@ -51,7 +55,7 @@ class Circuit:
         Returns:
             int: The total count of parameters from all parameterized gates.
         """
-        return len([value for gate in self._gates if gate.is_parameterized for value in gate.parameter_values])
+        return len(self._parameters)
 
     @property
     def gates(self) -> list[Gate]:
@@ -70,7 +74,25 @@ class Circuit:
         Returns:
             list[float]: A list of parameter values from each parameterized gate.
         """
-        return [value for gate in self._gates if gate.is_parameterized for value in gate.parameter_values]
+        return [param.value for param in self._parameters.values()]
+
+    def get_parameter_names(self) -> list[str]:
+        """
+        Retrieve the parameter values from all parameterized gates in the circuit.
+
+        Returns:
+            list[float]: A list of parameter values from each parameterized gate.
+        """
+        return list(self._parameters.keys())
+
+    def get_parameters(self) -> dict[str, float]:
+        """
+        Retrieve the parameter names and values from all parameterized gates in the circuit.
+
+        Returns:
+            dict[str, float]: A dictionary of the parameters with their current values.
+        """
+        return {label: param.value for label, param in self._parameters.items()}
 
     def set_parameter_values(self, values: list[float]) -> None:
         """
@@ -84,10 +106,33 @@ class Circuit:
         """
         if len(values) != self.nparameters:
             raise ParametersNotEqualError
-        k = 0
-        for i, gate in enumerate(self._parameterized_gates):
-            gate.set_parameter_values(values[i + k : i + k + gate.nparameters])
-            k += gate.nparameters - 1
+        for i, parameter in enumerate(self._parameters.values()):
+            parameter.set_value(values[i])
+
+    def set_parameters(self, parameter_dict: dict[str, RealNumber]) -> None:
+        """Set the parameter values by their label. No need to provide the full list of parameters.
+
+        Args:
+            parameter_dict (dict[str, RealNumber]): A dictionary with the labels of the parameters to be modified and their new value.
+
+        Raises:
+            ValueError: if the label provided doesn't correspond to a parameter defined in this circuit.
+        """
+        for label, param in parameter_dict.items():
+            if label not in self._parameters:
+                raise ValueError(f"Parameter {label} is not defined in this circuit.")
+            self._parameters[label].set_value(param)
+
+    def get_parameter_bounds(self) -> dict[str, tuple[float, float]]:
+        return {k: v.bounds for k, v in self._parameters.items()}
+
+    def set_parameter_bounds(self, ranges: dict[str, tuple[float, float]]) -> None:
+        for label, bound in ranges.items():
+            if label not in self._parameters:
+                raise ValueError(
+                    f"The provided parameter label {label} is not defined in the list of parameters in this object."
+                )
+            self._parameters[label].set_bounds(bound[0], bound[1])
 
     def add(self, gate: Gate) -> None:
         """
@@ -102,5 +147,32 @@ class Circuit:
         if any(qubit >= self.nqubits for qubit in gate.qubits):
             raise QubitOutOfRangeError
         if gate.is_parameterized:
-            self._parameterized_gates.append(gate)
+            param_base_label = f"{gate.name}({','.join(map(str, gate.qubits))})"
+            for label, parameter in gate.parameters.items():
+                if label == parameter.label:
+                    parameter_label = param_base_label + f"_{label}_{len(self._parameters)}"
+                else:
+                    parameter_label = parameter.label
+                self._parameters[parameter_label] = gate.parameters[label]
         self._gates.append(gate)
+
+    def draw(self, style: CircuitStyle = CircuitStyle(), filepath: str | None = None) -> None:
+        """
+        Render this circuit with Matplotlib and optionally save it to a file.
+
+        The circuit is rendered using the provided style configuration. If ``filepath`` is
+        given, the resulting figure is saved to disk (the output format is inferred
+        from the file extension, e.g. ``.png``, ``.pdf``, ``.svg``).
+
+        Args:
+            style (CircuitStyle): Visual style configuration applied to the plot.
+                If not provided, the default :class:`CircuitStyle` is used.
+            filepath (str | None): Destination file path for the rendered figure.
+                If ``None``, the figure is not saved.
+        """
+        from qilisdk.utils.visualization.circuit_renderers import MatplotlibCircuitRenderer  # noqa: PLC0415
+
+        renderer = MatplotlibCircuitRenderer(self, style=style)
+        renderer.plot()
+        if filepath:
+            renderer.save(filepath)

qilisdk/digital/exceptions.py

@@ -13,19 +13,25 @@
 # limitations under the License.
 
 
-class QubitOutOfRangeError(Exception): ...
+class QubitOutOfRangeError(Exception):
+    """Raised when a qubit index is outside the defined circuit range."""
 
 
-class GateHasNoMatrixError(Exception): ...
+class GateHasNoMatrixError(Exception):
+    """Raised when a gate lacks an associated matrix representation."""
 
 
-class GateNotParameterizedError(Exception): ...
+class GateNotParameterizedError(Exception):
+    """Raised when attempting to set parameters on a non-parameterized gate."""
 
 
-class ParametersNotEqualError(Exception): ...
+class ParametersNotEqualError(Exception):
+    """Raised when parameterized gates receive mismatched parameter values."""
 
 
-class InvalidParameterNameError(Exception): ...
+class InvalidParameterNameError(Exception):
+    """Raised when an unknown parameter name is supplied to a gate."""
 
 
-class UnsupportedGateError(Exception): ...
+class UnsupportedGateError(Exception):
+    """Raised when a gate is not supported by the target backend."""