qilisdk 0.1.8__cp313-cp313-macosx_10_13_x86_64.whl

qilisdk/noise/parameter_perturbation.py

@@ -0,0 +1,45 @@
+# 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 abstractmethod
+
+from .noise_abc import NoiseABC
+from .protocols import AttachmentScope, HasAllowedScopes
+
+
+class ParameterPerturbation(NoiseABC, HasAllowedScopes):
+    """Base class for noise that perturbs a numeric parameter."""
+
+    @abstractmethod
+    def perturb(self, value: float) -> float:
+        """Return a perturbed version of a parameter value.
+
+        Args:
+            value (float): The original parameter value.
+
+        Returns:
+            The perturbed parameter value.
+        """
+        ...
+
+    @classmethod
+    def allowed_scopes(cls) -> frozenset[AttachmentScope]:
+        """Return the attachment scopes supported by this perturbation type.
+
+        Returns:
+            The set of scopes where this perturbation can be attached.
+        """
+        return frozenset({AttachmentScope.GLOBAL, AttachmentScope.PER_GATE_TYPE})

qilisdk/noise/pauli_channel.py

@@ -0,0 +1,115 @@
+# 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
+
+import numpy as np
+
+from qilisdk.core import QTensor
+
+from .noise import Noise
+from .protocols import AttachmentScope, HasAllowedScopes, SupportsStaticKraus, SupportsTimeDerivedLindblad
+from .representations import KrausChannel, LindbladGenerator
+from .utils import _check_probability, _identity, _sigma_x, _sigma_y, _sigma_z
+
+
+class PauliChannel(Noise, SupportsStaticKraus, SupportsTimeDerivedLindblad, HasAllowedScopes):
+    """General single-qubit Pauli channel.
+
+    Channel:
+        E(rho) = pI * rho + pX * X rho X + pY * Y rho Y + pZ * Z rho Z
+        where pI = 1 - (pX + pY + pZ).
+    """
+
+    def __init__(self, *, pX: float = 0.0, pY: float = 0.0, pZ: float = 0.0) -> None:
+        """Args:
+            pX (float): Probability of X error.
+            pY (float): Probability of Y error.
+            pZ (float): Probability of Z error.
+
+        Raises:
+            ValueError: If any probability is outside [0, 1] or pX + pY + pZ > 1.
+        """
+        self._pX = _check_probability(pX, "pX")
+        self._pY = _check_probability(pY, "pY")
+        self._pZ = _check_probability(pZ, "pZ")
+        if self._pX + self._pY + self._pZ > 1.0 + 1e-12:
+            raise ValueError("pX + pY + pZ must be <= 1.")
+
+    @property
+    def pX(self) -> float:
+        """Return the probability of an X error.
+
+        Returns:
+            float: Probability for the X Pauli error.
+        """
+        return self._pX
+
+    @property
+    def pY(self) -> float:
+        """Return the probability of a Y error.
+
+        Returns:
+            float: Probability for the Y Pauli error.
+        """
+        return self._pY
+
+    @property
+    def pZ(self) -> float:
+        """Return the probability of a Z error.
+
+        Returns:
+            float: Probability for the Z Pauli error.
+        """
+        return self._pZ
+
+    def as_kraus(self) -> KrausChannel:
+        pI = max(0.0, 1.0 - (self._pX + self._pY + self._pZ))
+        operators = []
+        if pI > 0:
+            operators.append(np.sqrt(pI) * _identity())
+        if self._pX > 0:
+            operators.append(np.sqrt(self._pX) * _sigma_x())
+        if self._pY > 0:
+            operators.append(np.sqrt(self._pY) * _sigma_y())
+        if self._pZ > 0:
+            operators.append(np.sqrt(self._pZ) * _sigma_z())
+        return KrausChannel([QTensor(operator) for operator in operators])
+
+    def as_lindblad_from_duration(self, *, duration: float) -> LindbladGenerator:
+        if duration <= 0:
+            raise ValueError("Duration must be positive.")
+        rates = []
+        operators = []
+        if self._pX > 0:
+            rates.append(self._pX / duration)
+            operators.append(QTensor(_sigma_x()))
+        if self._pY > 0:
+            rates.append(self._pY / duration)
+            operators.append(QTensor(_sigma_y()))
+        if self._pZ > 0:
+            rates.append(self._pZ / duration)
+            operators.append(QTensor(_sigma_z()))
+        return LindbladGenerator(operators, rates)
+
+    @classmethod
+    def allowed_scopes(cls) -> frozenset[AttachmentScope]:
+        return frozenset(
+            {
+                AttachmentScope.GLOBAL,
+                AttachmentScope.PER_QUBIT,
+                AttachmentScope.PER_GATE_TYPE,
+                AttachmentScope.PER_GATE_TYPE_PER_QUBIT,
+            }
+        )

qilisdk/noise/phase_flip.py

@@ -0,0 +1,45 @@
+# Copyright 2026 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 .pauli_channel import PauliChannel
+from .protocols import SupportsStaticKraus
+from .utils import _check_probability
+
+
+class PhaseFlip(PauliChannel, SupportsStaticKraus):
+    """Single-qubit Pauli channel configured with an X-axis error.
+
+    Applies an X error with the given probability and the identity otherwise.
+    """
+
+    def __init__(self, *, probability: float) -> None:
+        """Args:
+            probability (float): Probability of applying the Pauli-X error.
+
+        Raises:
+            ValueError: If probability is outside [0, 1].
+        """
+        self._probability = _check_probability(probability, "probability")
+        super().__init__(pZ=probability)
+
+    @property
+    def probability(self) -> float:
+        """Return the probability of applying the Pauli-X error.
+
+        Returns:
+            float: The error probability.
+        """
+        return self._probability

qilisdk/noise/protocols.py

@@ -0,0 +1,107 @@
+# Copyright 2026 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 enum import Enum
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from .representations import KrausChannel, LindbladGenerator
+
+
+class AttachmentScope(str, Enum):
+    """Scope describing where a noise or perturbation can be attached.
+
+    Attributes:
+        GLOBAL: Applies to all operations or parameters.
+        PER_QUBIT: Applies only to a specific qubit.
+        PER_GATE_TYPE: Applies only to a specific gate type.
+    """
+
+    GLOBAL = "global"
+    PER_QUBIT = "per_qubit"
+    PER_GATE_TYPE = "per_gate_type"
+    PER_GATE_TYPE_PER_QUBIT = "per_gate_type_per_qubit"
+
+
+@runtime_checkable
+class HasAllowedScopes(Protocol):
+    """Protocol for types that declare their allowed attachment scopes."""
+
+    @classmethod
+    def allowed_scopes(cls) -> frozenset[AttachmentScope]:
+        """Return the attachment scopes supported by the type.
+
+        Returns:
+            The set of scopes where the type can be attached.
+        """
+        ...
+
+
+@runtime_checkable
+class SupportsTimeDerivedKraus(Protocol):
+    """Protocol for types that produce duration-dependent Kraus channels."""
+
+    def as_kraus_from_duration(self, *, duration: float) -> KrausChannel:
+        """Return a Kraus channel derived for a specific duration.
+
+        Args:
+            duration (float): Duration over which the noise acts.
+
+        Returns:
+            The Kraus channel for the given duration.
+        """
+        ...
+
+
+@runtime_checkable
+class SupportsStaticKraus(Protocol):
+    """Protocol for types that expose a fixed Kraus channel."""
+
+    def as_kraus(self) -> KrausChannel:
+        """Return the static Kraus channel for this noise.
+
+        Returns:
+            The Kraus channel representation.
+        """
+        ...
+
+
+@runtime_checkable
+class SupportsStaticLindblad(Protocol):
+    """Protocol for types that expose a fixed Lindblad generator."""
+
+    def as_lindblad(self) -> LindbladGenerator:
+        """Return the Lindblad generator for this noise.
+
+        Returns:
+            The Lindblad generator representation.
+        """
+        ...
+
+
+@runtime_checkable
+class SupportsTimeDerivedLindblad(Protocol):
+    """Protocol for types that expose a Lindblad generator derived from time."""
+
+    def as_lindblad_from_duration(self, *, duration: float) -> LindbladGenerator:
+        """Return the Lindblad generator for this noise.
+
+        Args:
+            duration (float): Duration over which the noise acts.
+
+        Returns:
+            The Lindblad generator representation.
+        """
+        ...

qilisdk/noise/readout_assignment.py

@@ -0,0 +1,60 @@
+# Copyright 2026 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 .noise import Noise
+from .protocols import AttachmentScope, HasAllowedScopes
+from .utils import _check_probability
+
+
+class ReadoutAssignment(Noise, HasAllowedScopes):
+    """Classical readout assignment error model for measurement outcomes."""
+
+    def __init__(self, *, p01: float, p10: float) -> None:
+        """Args:
+            p01 (float): Probability to report "1" when the state is |0>.
+            p10 (float): Probability to report "0" when the state is |1>.
+
+        Raises:
+            ValueError: If any probability is outside [0, 1].
+        """
+        self._p01 = _check_probability(p01, "p01")
+        self._p10 = _check_probability(p10, "p10")
+
+    @property
+    def p01(self) -> float:
+        """Return the probability of reporting "1" for a |0> state.
+
+        Returns:
+            The p01 probability.
+        """
+        return self._p01
+
+    @property
+    def p10(self) -> float:
+        """Return the probability of reporting "0" for a |1> state.
+
+        Returns:
+            The p10 probability.
+        """
+        return self._p10
+
+    @classmethod
+    def allowed_scopes(cls) -> frozenset[AttachmentScope]:
+        """Return the attachment scopes supported by this perturbation type.
+
+        Returns:
+            The set of scopes where this perturbation can be attached.
+        """
+        return frozenset({AttachmentScope.GLOBAL, AttachmentScope.PER_QUBIT})

qilisdk/noise/representations.py

@@ -0,0 +1,149 @@
+# Copyright 2026 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, Self
+
+import numpy as np
+
+from .noise import Noise
+from .protocols import AttachmentScope
+
+if TYPE_CHECKING:
+    from qilisdk.analog import Hamiltonian
+    from qilisdk.core import QTensor
+
+
+class KrausChannel(Noise):
+    """Kraus operator representation of a quantum channel."""
+
+    def __init__(self, operators: list[QTensor]) -> None:
+        """Args:
+        operators (list[QTensor]): Kraus operators defining the channel."""
+        self._operators: list[QTensor] = operators
+
+    @property
+    def operators(self) -> list[QTensor]:
+        """Return the Kraus operators defining the channel.
+
+        Returns:
+            list[QTensor]: The Kraus operators for this channel.
+        """
+        return self._operators
+
+    def as_kraus(self) -> Self:
+        return self
+
+    @classmethod
+    def allowed_scopes(cls) -> frozenset[AttachmentScope]:
+        """
+        Return the allowed attachment scopes for this noise representation.
+
+        Returns:
+            frozenset[AttachmentScope]: Allowed attachment scopes.
+        """
+        return frozenset(
+            {
+                AttachmentScope.GLOBAL,
+                AttachmentScope.PER_QUBIT,
+                AttachmentScope.PER_GATE_TYPE,
+                AttachmentScope.PER_GATE_TYPE_PER_QUBIT,
+            }
+        )
+
+
+class LindbladGenerator(Noise):
+    """Lindblad generator representation for Markovian noise."""
+
+    def __init__(
+        self,
+        jump_operators: list[QTensor],
+        rates: list[float] | None = None,
+        hamiltonian: Hamiltonian | None = None,
+    ) -> None:
+        """
+        Args:
+            jump_operators (list[QTensor]): Jump operators defining dissipation.
+            rates (list[float] | None): Optional rates for each jump operator.
+            hamiltonian (Hamiltonian | None): Optional Hamiltonian term for coherent evolution.
+
+        Raises:
+            ValueError: If rates are provided and their length does not match jump_operators.
+        """
+        if rates is not None and len(rates) != len(jump_operators):
+            raise ValueError("Length of rates must match length of jump_operators.")
+        self._jump_operators = jump_operators
+        self._rates = rates
+        self._hamiltonian = hamiltonian
+
+    @property
+    def jump_operators(self) -> list[QTensor]:
+        """Return the jump operators defining dissipation.
+
+        Returns:
+            list[QTensor]: Jump operators for this generator.
+        """
+        return self._jump_operators
+
+    @property
+    def jump_operators_with_rates(self) -> list[QTensor]:
+        """Return the jump operators defining dissipation, scaled by their rates.
+
+        Raises:
+            ValueError: If the rate list is provided but its length does not match jump_operators.
+
+        Returns:
+            list[QTensor]: Jump operators for this generator.
+        """
+        if self._rates is None:
+            return self._jump_operators
+        if len(self._rates) != len(self._jump_operators):
+            raise ValueError("Length of rates must match length of jump_operators.")
+        return [self._jump_operators[i] * np.sqrt(self._rates[i]) for i in range(len(self._jump_operators))]
+
+    @property
+    def rates(self) -> list[float] | None:
+        """Return the rates for each jump operator, if provided.
+
+        Returns:
+            list[float] | None: Rates for each jump operator.
+        """
+        return self._rates
+
+    @property
+    def hamiltonian(self) -> Hamiltonian | None:
+        """Return the optional coherent Hamiltonian term.
+
+        Returns:
+            QTensor | None: The Hamiltonian term if provided.
+        """
+        return self._hamiltonian
+
+    def as_lindblad(self) -> LindbladGenerator:
+        """Return this instance as a Lindblad generator representation.
+
+        Returns:
+            The current LindbladGenerator instance.
+        """
+        return self
+
+    @classmethod
+    def allowed_scopes(cls) -> frozenset[AttachmentScope]:
+        """
+        Return the allowed attachment scopes for this noise representation.
+
+        Returns:
+            frozenset[AttachmentScope]: Allowed attachment scopes.
+        """
+        return frozenset({AttachmentScope.GLOBAL, AttachmentScope.PER_QUBIT})

qilisdk/noise/utils.py

@@ -0,0 +1,90 @@
+# Copyright 2026 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
+
+import numpy as np
+
+
+def _check_probability(p: float, name: str = "p") -> float:
+    """Validate a probability value in the [0, 1] range.
+
+    Args:
+        p (float): Probability value to validate.
+        name (str): Name used in error messages.
+
+    Returns:
+        The validated probability as a float.
+
+    Raises:
+        ValueError: If the probability is outside [0, 1].
+    """
+    p = float(p)
+    if not (0.0 <= p <= 1.0):
+        raise ValueError(f"{name} must be in [0, 1].")
+    return p
+
+
+def _identity() -> np.ndarray:
+    """Return the 2x2 identity matrix.
+
+    Returns:
+        The identity matrix as a complex-valued NumPy array.
+    """
+    return np.array([[1.0, 0.0], [0.0, 1.0]], dtype=complex)
+
+
+def _sigma_x() -> np.ndarray:
+    """Return the Pauli-X matrix.
+
+    Returns:
+        The Pauli-X matrix as a complex-valued NumPy array.
+    """
+    return np.array([[0.0, 1.0], [1.0, 0.0]], dtype=complex)
+
+
+def _sigma_y() -> np.ndarray:
+    """Return the Pauli-Y matrix.
+
+    Returns:
+        The Pauli-Y matrix as a complex-valued NumPy array.
+    """
+    return np.array([[0.0, -1.0j], [1.0j, 0.0]], dtype=complex)
+
+
+def _sigma_z() -> np.ndarray:
+    """Return the Pauli-Z matrix.
+
+    Returns:
+        The Pauli-Z matrix as a complex-valued NumPy array.
+    """
+    return np.array([[1.0, 0.0], [0.0, -1.0]], dtype=complex)
+
+
+def _sigma_minus() -> np.ndarray:
+    """Return the lowering (sigma-) operator.
+
+    Returns:
+        The sigma- matrix as a complex-valued NumPy array.
+    """
+    return np.array([[0.0, 1.0], [0.0, 0.0]], dtype=complex)
+
+
+def _sigma_plus() -> np.ndarray:
+    """Return the raising (sigma+) operator.
+
+    Returns:
+        The sigma+ matrix as a complex-valued NumPy array.
+    """
+    return np.array([[0.0, 0.0], [1.0, 0.0]], dtype=complex)

qilisdk/optimizers/__init__.py

@@ -0,0 +1,17 @@
+# 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 .scipy_optimizer import SciPyOptimizer
+
+__all__ = ["SciPyOptimizer"]

qilisdk/optimizers/optimizer.py

@@ -0,0 +1,39 @@
+# 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 Callable
+
+from .optimizer_result import OptimizerResult
+
+
+class Optimizer(ABC):
+    @abstractmethod
+    def optimize(
+        self,
+        cost_function: Callable[[list[float]], float],
+        init_parameters: list[float],
+        bounds: list[tuple[float, float]],
+        store_intermediate_results: bool = False,
+    ) -> OptimizerResult:
+        """optimize the cost function and return the optimal parameters.
+
+        Args:
+            cost_function (Callable[[list[float]], float]): a function that takes in a list of parameters and returns the cost.
+            init_parameters (list[float]): the list of initial parameters. Note: the length of this list determines the number of parameters the optimizer will consider.
+            bounds (list[float, float]): a list of the variable value bounds.
+
+        Returns:
+            list[float]: the optimal set of parameters that minimize the cost function.
+        """