qilisdk 0.1.0__py3-none-any.whl

qilisdk/digital/__init__.py

@@ -0,0 +1,66 @@
+# 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 .circuit import Circuit
+from .digital_backend import DigitalBackend, DigitalSimulationMethod
+from .digital_result import DigitalResult
+from .gates import (
+    CNOT,
+    CZ,
+    RX,
+    RY,
+    RZ,
+    U1,
+    U2,
+    U3,
+    Adjoint,
+    BasicGate,
+    Controlled,
+    Exponential,
+    Gate,
+    H,
+    M,
+    S,
+    T,
+    X,
+    Y,
+    Z,
+)
+
+__all__ = [
+    "CNOT",
+    "CZ",
+    "RX",
+    "RY",
+    "RZ",
+    "U1",
+    "U2",
+    "U3",
+    "Adjoint",
+    "BasicGate",
+    "Circuit",
+    "Controlled",
+    "DigitalBackend",
+    "DigitalResult",
+    "DigitalSimulationMethod",
+    "Exponential",
+    "Gate",
+    "H",
+    "M",
+    "S",
+    "T",
+    "X",
+    "Y",
+    "Z",
+]

qilisdk/digital/ansatz.py

@@ -0,0 +1,143 @@
+# 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 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,
+        }
+
+    @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))

qilisdk/digital/circuit.py

@@ -0,0 +1,106 @@
+# 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.
+import numpy as np
+
+from qilisdk.yaml import yaml
+
+from .exceptions import ParametersNotEqualError, QubitOutOfRangeError
+from .gates import Gate
+
+
+@yaml.register_class
+class Circuit:
+    def __init__(self, nqubits: int) -> None:
+        """
+        Initialize a Circuit instance with a specified number of qubits.
+
+        Args:
+            nqubits (int): The number of qubits in the circuit.
+        """
+        self._nqubits: int = nqubits
+        self._gates: list[Gate] = []
+        self._init_state: np.ndarray = np.zeros(nqubits)
+        self._parameterized_gates: list[Gate] = []
+
+    @property
+    def nqubits(self) -> int:
+        """
+        Retrieve the number of qubits in the circuit.
+
+        Returns:
+            int: The total number of qubits.
+        """
+        return self._nqubits
+
+    @property
+    def nparameters(self) -> int:
+        """
+        Retrieve the total number of parameters required by all parameterized gates in the 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])
+
+    @property
+    def gates(self) -> list[Gate]:
+        """
+        Retrieve the list of gates in the circuit.
+
+        Returns:
+            list[Gate]: A list of gates that have been added to the circuit.
+        """
+        return self._gates
+
+    def get_parameter_values(self) -> list[float]:
+        """
+        Retrieve the parameter values from all parameterized gates in the 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]
+
+    def set_parameter_values(self, values: list[float]) -> None:
+        """
+        Set new parameter values for all parameterized gates in the circuit.
+
+        Args:
+            values (list[float]): A list containing new parameter values to assign to the parameterized gates.
+
+        Raises:
+            ParametersNotEqualError: If the number of provided values does not match the expected number of parameters.
+        """
+        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
+
+    def add(self, gate: Gate) -> None:
+        """
+        Add a quantum gate to the circuit.
+
+        Args:
+            gate (Gate): The quantum gate to add to the circuit.
+
+        Raises:
+            QubitOutOfRangeError: If any qubit index used by the gate is not within the circuit's qubit range.
+        """
+        if any(qubit >= self.nqubits for qubit in gate.qubits):
+            raise QubitOutOfRangeError
+        if gate.is_parameterized:
+            self._parameterized_gates.append(gate)
+        self._gates.append(gate)

qilisdk/digital/digital_algorithm.py

@@ -0,0 +1,20 @@
+# 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 qilisdk.common.algorithm import Algorithm
+
+
+class DigitalAlgorithm(Algorithm):
+    """
+    Abstract base class for digital quantum algorithms.
+    """

qilisdk/digital/digital_backend.py

@@ -0,0 +1,90 @@
+# 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 enum import Enum
+
+from qilisdk.digital.circuit import Circuit
+from qilisdk.digital.digital_result import DigitalResult
+
+
+class DigitalSimulationMethod(str, Enum):
+    """
+    Enumeration of available simulation methods for the CUDA backend.
+    """
+
+    STATE_VECTOR = "state_vector"
+    TENSOR_NETWORK = "tensor_network"
+    MATRIX_PRODUCT_STATE = "matrix_product_state"
+
+
+class DigitalBackend(ABC):
+    """
+    Abstract base class for digital quantum circuit backends.
+
+    This abstract class defines the interface for a digital backend capable of executing a
+    quantum circuit. Subclasses must implement the execute method to run the circuit with a
+    specified number of measurement shots and return a DigitalResult encapsulating the measurement
+    outcomes.
+    """
+
+    def __init__(
+        self, digital_simulation_method: DigitalSimulationMethod = DigitalSimulationMethod.STATE_VECTOR
+    ) -> None:
+        """
+        Initialize the DigitalBackend.
+
+        Args:
+            simulation_method (DigitalSimulationMethod, optional): The simulation method to use.
+                Options include STATE_VECTOR, TENSOR_NETWORK, or MATRIX_PRODUCT_STATE.
+                Defaults to STATE_VECTOR.
+        """
+        self._digital_simulation_method = digital_simulation_method
+
+    @property
+    def digital_simulation_method(self) -> DigitalSimulationMethod:
+        """
+        Get the simulation method currently configured for the backend.
+
+        Returns:
+            SimulationMethod: The simulation method to be used for circuit execution.
+        """
+        return self._digital_simulation_method
+
+    @digital_simulation_method.setter
+    def digital_simulation_method(self, value: DigitalSimulationMethod) -> None:
+        """
+        Set the simulation method for the backend.
+
+        Args:
+            value (SimulationMethod): The simulation method to set. Options include
+                STATE_VECTOR, TENSOR_NETWORK, or MATRIX_PRODUCT_STATE.
+        """
+        self._digital_simulation_method = value
+
+    @abstractmethod
+    def execute(self, circuit: Circuit, nshots: int = 1000) -> DigitalResult:
+        """
+        Execute the provided quantum circuit and return the measurement results.
+
+        This method should run the given circuit for the specified number of measurement shots and
+        produce a DigitalResult instance containing the raw measurement samples and any computed
+        probabilities.
+
+        Args:
+            circuit (Circuit): The quantum circuit to be executed.
+            nshots (int, optional): The number of measurement shots to perform. Defaults to 1000.
+
+        Returns:
+            DigitalResult: The result of executing the circuit, including measurement samples and probabilities.
+        """

qilisdk/digital/digital_result.py

@@ -0,0 +1,145 @@
+# 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.
+import heapq
+import operator
+from pprint import pformat
+
+from qilisdk.common import Result
+from qilisdk.yaml import yaml
+
+
+@yaml.register_class
+class DigitalResult(Result):
+    """
+    Class representing the result of a quantum circuit measurement.
+
+    DigitalResult encapsulates the outcome of a digital measurement performed on a quantum circuit.
+    It includes the total number of measurement shots, the measurement samples and measurement probabilities.
+
+    Attributes:
+        nshots (int): The number of measurement shots performed in the experiment.
+        nqubits (int): The number of qubits measured.
+        samples (dict[str, int]): A dictionary where keys are bitstrings representing measurement outcomes and values are the number of times each outcome was observed.
+    """
+
+    def __init__(self, nshots: int, samples: dict[str, int]) -> None:
+        """
+        Initializes a DigitalResult instance.
+
+        Args:
+            nshots (int): The total number of measurement shots performed.
+            samples (dict[str, int]): A dictionary mapping bitstring outcomes to their occurrence counts.
+                All keys (bitstrings) must have the same length, which determines the number of qubits.
+
+        Raises:
+            ValueError: If the samples dictionary is empty or if not all bitstring keys have the same length.
+        """
+        self._nshots = nshots
+        self._samples = samples
+
+        # Ensure samples is not empty and is correct.
+        if not samples:
+            raise ValueError("The samples dictionary is empty.")
+        bitstrings = list(samples.keys())
+        nqubits = len(bitstrings[0])
+        if not all(len(bitstring) == nqubits for bitstring in bitstrings):
+            raise ValueError("Not all bitstring keys have the same length.")
+
+        # Assign nqubits to attribute
+        self._nqubits = nqubits
+
+        # Calculate probabilities
+        self._probabilities = {
+            bitstring: counts / self._nshots if self._nshots > 0 else 0.0 for bitstring, counts in self._samples.items()
+        }
+
+    @property
+    def nshots(self) -> int:
+        """
+        Gets the number of measurement shots.
+
+        Returns:
+            int: The total number of measurement shots performed.
+        """
+        return self._nshots
+
+    @property
+    def nqubits(self) -> int:
+        """
+        Gets the number of qubits involved in the measurement.
+
+        Returns:
+            int: The number of qubits measured.
+        """
+        return self._nqubits
+
+    @property
+    def samples(self) -> dict[str, int]:
+        """
+        Gets the raw measurement samples.
+
+        Returns:
+            dict[str, int]: A dictionary where keys are bitstrings representing measurement outcomes
+            and values are the number of times each outcome was observed.
+        """
+        return dict(self._samples)
+
+    @property
+    def probabilities(self) -> dict[str, float]:
+        """
+        Gets the probabilities for each measurement outcome.
+
+        Returns:
+            dict[str, float]: A dictionary mapping each bitstring outcome to its corresponding probability.
+        """
+        return dict(self._probabilities)
+
+    def get_probability(self, bitstring: str) -> float:
+        """
+        Computes the probability of a specific measurement outcome.
+
+        Args:
+            bitstring (str): The bitstring representing the measurement outcome of interest.
+
+        Returns:
+            float: The probability of the specified bitstring occurring.
+        """
+        return self._probabilities.get(bitstring, 0.0)
+
+    def get_probabilities(self, n: int | None = None) -> list[tuple[str, float]]:
+        """
+        Returns the n most probable bitstrings along with their probabilities.
+
+        Parameters:
+            n (int): The number of most probable bitstrings to return.
+
+        Returns:
+            list[tuple[str, float]]: A list of tuples (bitstring, probability) sorted in descending order by probability.
+        """
+        if n is None:
+            n = len(self._probabilities)
+        return heapq.nlargest(n, self._probabilities.items(), key=operator.itemgetter(1))
+
+    def __repr__(self) -> str:
+        """
+        Returns a string representation of the DigitalResult instance for debugging purposes.
+
+        The representation includes the class name, the number of measurement shots, and a formatted
+        display of the measurement samples.
+
+        Returns:
+            str: A string representation of the DigitalResult instance for debugging.
+        """
+        class_name = self.__class__.__name__
+        return f"{class_name}(\n  nshots={self.nshots},\n  samples={pformat(self.samples)}\n)"

qilisdk/digital/exceptions.py

@@ -0,0 +1,31 @@
+# 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.
+
+
+class QubitOutOfRangeError(Exception): ...
+
+
+class GateHasNoMatrixError(Exception): ...
+
+
+class GateNotParameterizedError(Exception): ...
+
+
+class ParametersNotEqualError(Exception): ...
+
+
+class InvalidParameterNameError(Exception): ...
+
+
+class UnsupportedGateError(Exception): ...