qilisdk 0.1.8__cp312-cp312-macosx_11_0_arm64.whl

qilisdk/cost_functions/__init__.py

@@ -0,0 +1,18 @@
+# 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 .model_cost_function import ModelCostFunction
+from .observable_cost_function import ObservableCostFunction
+
+__all__ = ["ModelCostFunction", "ObservableCostFunction"]

qilisdk/cost_functions/cost_function.py

@@ -0,0 +1,77 @@
+# 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 __future__ import annotations
+
+from abc import ABC
+from typing import TYPE_CHECKING, Callable, TypeVar, cast, overload
+
+from qilisdk.functionals.functional_result import FunctionalResult
+from qilisdk.functionals.sampling_result import SamplingResult
+from qilisdk.functionals.time_evolution_result import TimeEvolutionResult
+
+if TYPE_CHECKING:
+    from qilisdk.core.types import Number
+
+TResult = TypeVar("TResult", bound=FunctionalResult)
+
+
+class CostFunction(ABC):
+    """
+    Base class that maps functional results into scalar costs.
+    """
+
+    def __init__(self) -> None:
+        self._handlers: dict[type[FunctionalResult], Callable[[FunctionalResult], Number]] = {
+            SamplingResult: lambda f: self._compute_cost_sampling(cast("SamplingResult", f)),
+            TimeEvolutionResult: lambda f: self._compute_cost_time_evolution(cast("TimeEvolutionResult", f)),
+        }
+
+    @overload
+    def compute_cost(self, results: SamplingResult) -> Number: ...
+
+    @overload
+    def compute_cost(self, results: TimeEvolutionResult) -> Number: ...
+
+    @overload
+    def compute_cost(self, results: FunctionalResult) -> Number: ...
+
+    def compute_cost(self, results: TResult) -> Number:
+        """
+        Dispatch to the appropriate cost implementation based on the result type.
+
+        Args:
+            results (FunctionalResult): Output of a functional execution.
+
+        Returns:
+            Number: Scalar cost extracted from the results.
+
+        Raises:
+            NotImplementedError: If the concrete cost function does not support the given result type.
+        """
+        try:
+            handler = self._handlers[type(results)]
+        except KeyError as exc:
+            raise NotImplementedError(
+                f"{type(self).__qualname__} does not support {type(results).__qualname__}"
+            ) from exc
+
+        return handler(results)
+
+    def _compute_cost_sampling(self, results: SamplingResult) -> Number:
+        """Compute the cost associated with a :class:`SamplingResult`."""
+        raise NotImplementedError
+
+    def _compute_cost_time_evolution(self, results: TimeEvolutionResult) -> Number:
+        """Compute the cost associated with a :class:`TimeEvolutionResult`."""
+        raise NotImplementedError

qilisdk/cost_functions/model_cost_function.py

@@ -0,0 +1,152 @@
+# 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 __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from qilisdk.core.model import QUBO, Model
+from qilisdk.core.qtensor import QTensor, expect_val, ket
+from qilisdk.cost_functions.cost_function import CostFunction
+from qilisdk.settings import get_settings
+
+if TYPE_CHECKING:
+    from qilisdk.core.types import Number
+    from qilisdk.functionals.sampling_result import SamplingResult
+    from qilisdk.functionals.time_evolution_result import TimeEvolutionResult
+
+
+class ModelCostFunction(CostFunction):
+    """
+    Evaluate the cost of functional results with respect to a :class:`~qilisdk.core.model.Model`.
+
+    Example:
+        .. code-block:: python
+
+            from qilisdk.core import BinaryVariable, Model, LEQ
+            from qilisdk.cost_functions import ModelCostFunction
+
+            model = Model("demo")
+            x0, x1 = BinaryVariable("x0"), BinaryVariable("x1")
+            model.set_objective(x0 + x1)
+            model.add_constraint("limit", LEQ(x0 + x1, 1))
+            cost_fn = ModelCostFunction(model)
+    """
+
+    def __init__(self, model: Model) -> None:
+        """
+        Args:
+            model (Model): Classical model describing objective and constraints.
+        """
+        super().__init__()
+        self._model = model
+
+    @property
+    def model(self) -> Model:
+        """Return the underlying optimisation model."""
+        return self._model
+
+    def _compute_cost_time_evolution(self, results: TimeEvolutionResult) -> Number:
+        """
+        Compute the expectation value of the model objective using a time-evolution result.
+
+        Evaluates the model on each computational basis state with probability extracted from the final state.
+
+        Returns:
+            Number: Expectation value of the model objective.
+
+        Raises:
+            ValueError: If the final state is not provided in the results.
+        """
+        if results.final_state is None:
+            raise ValueError(
+                "can't compute cost using Models from time evolution results when the state is not provided."
+            )
+
+        if isinstance(self.model, QUBO):
+            ham = self.model.to_hamiltonian()
+            total_cost = complex(
+                np.real_if_close(expect_val(QTensor(ham.to_matrix()), results.final_state), tol=get_settings().atol)
+            )
+            if abs(total_cost.imag) < get_settings().atol:
+                return total_cost.real
+            return total_cost
+
+        total_cost = complex(0.0)
+
+        if results.final_state.is_density_matrix(tol=1e-5):
+            rho = results.final_state.dense()
+            n = results.final_state.nqubits
+            for i in range(rho.shape[0]):
+                state = [int(b) for b in f"{i:0{n}b}"]
+                _ket_state = ket(*state)
+                _prob = complex(
+                    np.real_if_close(
+                        np.trace((_ket_state @ _ket_state.adjoint()).dense() @ rho), tol=get_settings().atol
+                    )
+                )
+                variable_map = {v: int(state[i]) for i, v in enumerate(self.model.variables())}
+                evaluate_results = self.model.evaluate(variable_map)
+                total_cost += sum(v for v in evaluate_results.values()) * _prob
+            if abs(total_cost.imag) < get_settings().atol:
+                return total_cost.real
+            return total_cost
+
+        dense_state = None
+        if results.final_state.is_ket():
+            dense_state = results.final_state.dense().T[0]
+        elif results.final_state.is_bra():
+            dense_state = results.final_state.dense()[0]
+
+        if dense_state is None:
+            raise ValueError("The final state is invalid.")
+
+        n = len(self.model.variables())
+
+        for i, prob in enumerate(dense_state):
+            state = [int(b) for b in f"{i:0{n}b}"]
+            variable_map = {v: state[i] for i, v in enumerate(self.model.variables())}
+            evaluate_results = self.model.evaluate(variable_map)
+            total_cost += sum(v for v in evaluate_results.values()) * np.abs(prob**2)
+
+        total_cost = complex(np.real_if_close(total_cost, tol=get_settings().atol))
+        if abs(total_cost.imag) < get_settings().atol:
+            return total_cost.real
+        return total_cost
+
+    def _compute_cost_sampling(self, results: SamplingResult) -> Number:
+        """
+        Compute the model cost by averaging over sampled bitstrings.
+
+        Each sample is mapped onto the model variables and evaluated using ``model.evaluate``.
+
+        Returns:
+            Number: Average cost of the model objective over all samples.
+
+        Raises:
+            ValueError: If the number of model variables does not match the sample size.
+        """
+        total_cost = complex(0.0)
+        for sample, prob in results.get_probabilities():
+            bit_configuration = [int(i) for i in sample]
+            if len(self.model.variables()) != len(bit_configuration):
+                raise ValueError("Mapping samples to the model's variables is ambiguous.")
+            variable_map = {v: bit_configuration[i] for i, v in enumerate(self.model.variables())}
+            evaluate_results = self.model.evaluate(variable_map)
+            total_cost += sum(v for v in evaluate_results.values()) * prob
+
+        if abs(total_cost.imag) < get_settings().atol:
+            return total_cost.real
+        return total_cost

qilisdk/cost_functions/observable_cost_function.py

@@ -0,0 +1,112 @@
+# 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 __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from qilisdk.analog.hamiltonian import Hamiltonian, PauliOperator
+from qilisdk.core.qtensor import QTensor, expect_val, ket, tensor_prod
+from qilisdk.cost_functions.cost_function import CostFunction
+from qilisdk.settings import get_settings
+
+if TYPE_CHECKING:
+    from qilisdk.core.types import Number
+    from qilisdk.functionals.sampling_result import SamplingResult
+    from qilisdk.functionals.time_evolution_result import TimeEvolutionResult
+
+
+class ObservableCostFunction(CostFunction):
+    """
+    Compute costs by taking expectation values of observables.
+
+    Example:
+        .. code-block:: python
+
+            from qilisdk.analog.hamiltonian import Z
+            from qilisdk.cost_functions import ObservableCostFunction
+
+            cost_fn = ObservableCostFunction(Z(0))
+    """
+
+    def __init__(self, observable: QTensor | Hamiltonian | PauliOperator) -> None:
+        """
+        Args:
+            observable (QTensor | Hamiltonian | PauliOperator): Quantum observable whose expectation value defines the cost.
+
+        Raises:
+            ValueError: If the provided observable type is unsupported.
+        """
+        super().__init__()
+        if isinstance(observable, QTensor):
+            self._observable = observable
+        elif isinstance(observable, Hamiltonian):
+            self._observable = QTensor(observable.to_matrix())
+        elif isinstance(observable, PauliOperator):
+            self._observable = QTensor(observable.matrix)
+        else:
+            raise ValueError(
+                f"Observable needs to be of type QTensor, Hamiltonian, or PauliOperator but {type(observable)} was provided"
+            )
+
+    @property
+    def observable(self) -> QTensor:
+        """Return the observable in ``QTensor`` form."""
+        return self._observable
+
+    def _compute_cost_time_evolution(self, results: TimeEvolutionResult) -> Number:
+        """
+        Returns:
+            Number: the expectation value of ``observable`` given a final quantum state.
+
+        Raises:
+            ValueError: If the final state is not provided in the results.
+
+        """
+        if results.final_state is None:
+            raise ValueError(
+                "can't compute cost using Observables from time evolution results when the state is not provided."
+            )
+        total_cost = complex(
+            np.real_if_close(expect_val(self._observable, results.final_state), tol=get_settings().atol)
+        )
+        if abs(total_cost.imag) < get_settings().atol:
+            return total_cost.real
+        return total_cost
+
+    def _compute_cost_sampling(self, results: SamplingResult) -> Number:
+        """
+        Estimate the observable expectation value using measured bitstring probabilities.
+
+        Returns:
+            Number: the expectation value of ``observable`` estimated from sampled bitstrings.
+
+        Raises:
+            ValueError: If the number of qubits in the observable does not match the sample size
+        """
+        total_cost = complex(0.0)
+        nqubits = self._observable.nqubits
+        for sample, prob in results.get_probabilities():
+            state = tensor_prod([ket(int(i)) for i in sample])
+            if nqubits != state.nqubits:
+                raise ValueError(
+                    f"The samples provided have {state.nqubits} qubits but the observable has {nqubits} qubits"
+                )
+            evaluate_results = complex(np.real_if_close(expect_val(self._observable, state), tol=get_settings().atol))
+            total_cost += evaluate_results * prob
+
+        if abs(total_cost.imag) < get_settings().atol:
+            return total_cost.real
+        return total_cost

qilisdk/digital/__init__.py

@@ -0,0 +1,67 @@
+# 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 .ansatz import QAOA, HardwareEfficientAnsatz, TrotterizedTimeEvolution
+from .circuit import Circuit
+from .gates import (
+    CNOT,
+    CZ,
+    RX,
+    RY,
+    RZ,
+    SWAP,
+    U1,
+    U2,
+    U3,
+    Adjoint,
+    Controlled,
+    Exponential,
+    Gate,
+    H,
+    I,
+    M,
+    S,
+    T,
+    X,
+    Y,
+    Z,
+)
+
+__all__ = [
+    "CNOT",
+    "CZ",
+    "QAOA",
+    "RX",
+    "RY",
+    "RZ",
+    "SWAP",
+    "U1",
+    "U2",
+    "U3",
+    "Adjoint",
+    "Circuit",
+    "Controlled",
+    "Exponential",
+    "Gate",
+    "H",
+    "HardwareEfficientAnsatz",
+    "I",
+    "M",
+    "S",
+    "T",
+    "TrotterizedTimeEvolution",
+    "X",
+    "Y",
+    "Z",
+]