qilisdk 0.1.8__cp312-cp312-macosx_11_0_arm64.whl

qilisdk/noise/bit_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 BitFlip(PauliChannel, SupportsStaticKraus):
+    """Single-qubit Pauli channel configured with a Z-axis error.
+
+    Applies a Z error with the given probability and the identity otherwise.
+    """
+
+    def __init__(self, *, probability: float) -> None:
+        """
+        Args:
+            probability (float): Probability of applying the Pauli-Z error.
+
+        Raises:
+            ValueError: If probability is outside [0, 1].
+        """
+        self._probability = _check_probability(probability, "probability")
+        super().__init__(pX=probability)
+
+    @property
+    def probability(self) -> float:
+        """Return the probability of applying the Pauli-Z error.
+
+        Returns:
+            float: The error probability.
+        """
+        return self._probability

qilisdk/noise/dephasing.py

@@ -0,0 +1,69 @@
+# 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
+
+from qilisdk.core import QTensor
+
+from .noise import Noise
+from .protocols import AttachmentScope, HasAllowedScopes, SupportsStaticLindblad, SupportsTimeDerivedKraus
+from .representations import KrausChannel, LindbladGenerator
+from .utils import _identity, _sigma_z
+
+
+class Dephasing(Noise, SupportsTimeDerivedKraus, SupportsStaticLindblad, HasAllowedScopes):
+    """Pure dephasing (Tphi) noise model for single qubits.
+
+    This model supports both Lindblad and time-derived Kraus forms, with
+    coherences decaying as exp(-t / Tphi).
+    """
+
+    def __init__(self, *, t_phi: float) -> None:
+        """Args:
+            t_phi (float): Dephasing time constant (must be > 0).
+
+        Raises:
+            ValueError: If t_phi is not positive.
+        """
+        if t_phi <= 0:
+            raise ValueError("t_phi must be > 0.")
+        self._t_phi = float(t_phi)
+
+    @property
+    def t_phi(self) -> float:
+        """Return the dephasing time constant.
+
+        Returns:
+            The t_phi value.
+        """
+        return self._t_phi
+
+    def as_lindblad(self) -> LindbladGenerator:
+        gamma = 1.0 / self._t_phi
+        rate = gamma / 2.0
+        L = QTensor(_sigma_z())
+        return LindbladGenerator(jump_operators=[L], rates=[rate])
+
+    def as_kraus_from_duration(self, *, duration: float) -> KrausChannel:
+        if duration < 0:
+            raise ValueError("duration must be >= 0.")
+        gamma = float(np.exp(-duration / self._t_phi))
+        K0 = np.sqrt((1.0 + gamma) / 2.0) * _identity()
+        K1 = np.sqrt((1.0 - gamma) / 2.0) * _sigma_z()
+        return KrausChannel([QTensor(K0), QTensor(K1)])
+
+    @classmethod
+    def allowed_scopes(cls) -> frozenset[AttachmentScope]:
+        return frozenset({AttachmentScope.GLOBAL, AttachmentScope.PER_QUBIT})

qilisdk/noise/depolarizing.py

@@ -0,0 +1,44 @@
+# 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 .utils import _check_probability
+
+
+class Depolarizing(PauliChannel):
+    """Single-qubit depolarizing noise channel.
+
+    This channel mixes the state with the maximally mixed state by
+    configuring pX = pY = pZ = p / 3, which implies pI = 1 - p.
+    """
+
+    def __init__(self, *, probability: float) -> None:
+        """Args:
+            probability (float): Depolarizing probability in the range [0, 1].
+
+        Raises:
+            ValueError: If probability is outside [0, 1].
+        """
+        self._probability = _check_probability(probability, "probability")
+        super().__init__(pX=self._probability / 3.0, pY=self._probability / 3.0, pZ=self._probability / 3.0)
+
+    @property
+    def probability(self) -> float:
+        """Return the depolarizing probability.
+
+        Returns:
+            float: The depolarizing probability.
+        """
+        return self._probability

qilisdk/noise/gaussian_perturbation.py

@@ -0,0 +1,69 @@
+# 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
+
+from .parameter_perturbation import ParameterPerturbation
+
+
+class GaussianPerturbation(ParameterPerturbation):
+    """Gaussian-distributed parameter perturbation.
+
+    Each call to ``perturb`` adds a random offset drawn from N(mean, std^2).
+    """
+
+    def __init__(
+        self,
+        *,
+        mean: float = 0.0,
+        std: float,
+        seed: int = 42,
+    ) -> None:
+        """Args:
+            mean (float): Mean of the Gaussian offset.
+            std (float): Standard deviation of the Gaussian offset (must be >= 0).
+            seed (int): Seed for the random number generator.
+
+        Raises:
+            ValueError: If std is negative.
+        """
+        if std < 0:
+            raise ValueError("std must be >= 0")
+        self._mean = float(mean)
+        self._std = float(std)
+        self._rng = np.random.default_rng(seed)
+
+    @property
+    def mean(self) -> float:
+        """Return the mean of the Gaussian offset.
+
+        Returns:
+            The mean value.
+        """
+        return self._mean
+
+    @property
+    def std(self) -> float:
+        """Return the standard deviation of the Gaussian offset.
+
+        Returns:
+            The standard deviation value.
+        """
+        return self._std
+
+    def perturb(self, value: float) -> float:
+        delta = self._rng.normal(self._mean, self._std)
+        return value + delta

qilisdk/noise/noise.py

@@ -0,0 +1,20 @@
+# 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_abc import NoiseABC
+
+
+class Noise(NoiseABC):
+    """Base class for state noise sources that can be attached to a model."""

qilisdk/noise/noise_abc.py

@@ -0,0 +1,31 @@
+# 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 abc import ABC
+
+from .protocols import AttachmentScope, HasAllowedScopes
+
+
+class NoiseABC(ABC, HasAllowedScopes):
+    """Base class for all noise and perturbation types."""
+
+    @classmethod
+    def allowed_scopes(cls) -> frozenset[AttachmentScope]:
+        """Return the attachment scopes supported by this noise type.
+
+        Returns:
+            The set of scopes where this noise can be attached.
+        """
+        return frozenset({AttachmentScope.GLOBAL})

qilisdk/noise/noise_config.py

@@ -0,0 +1,77 @@
+# 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
+
+if TYPE_CHECKING:
+    from qilisdk.digital import Gate
+
+
+class NoiseConfig:
+    """Configuration options for noise models."""
+
+    def __init__(self) -> None:
+        """
+        Initialize a NoiseConfig with default settings.
+        """
+        self._gate_times: dict[type[Gate], float] = {}
+        self._default_gate_time: float = 1.0
+
+    def get_gate_time(self, gate_type: type[Gate]) -> float:
+        """Get the execution time for a specific gate type.
+
+        Args:
+            gate_type (type[Gate]): The type of the gate to query.
+
+        Returns:
+            float: The execution time for the gate. If not specified, returns the default gate time.
+        """
+        return self._gate_times.get(gate_type, self._default_gate_time)
+
+    @property
+    def default_gate_time(self) -> float:
+        """Return the default execution time for gates.
+
+        Returns:
+            The default gate time.
+        """
+        return self._default_gate_time
+
+    def set_gate_time(self, gate_type: type[Gate], time: float) -> None:
+        """Update the execution time for a specific gate type.
+
+        Args:
+            gate_type (type[Gate]): The type of the gate to update.
+            time (float): The new execution time for the gate.
+
+        Raises:
+            ValueError: If the provided time is not positive.
+        """
+        if time <= 0:
+            raise ValueError("Execution time must be positive.")
+        self._gate_times[gate_type] = time
+
+    def set_default_gate_time(self, time: float) -> None:
+        """Set the default execution time for gates not explicitly specified.
+
+        Args:
+            time (float): The new default execution time.
+
+        Raises:
+            ValueError: If the provided time is not positive.
+        """
+        if time <= 0:
+            raise ValueError("Default execution time must be positive.")
+        self._default_gate_time = time

qilisdk/noise/noise_model.py

@@ -0,0 +1,259 @@
+# 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 collections import defaultdict
+from typing import TypeAlias, TypeVar, overload
+
+from qilisdk.digital import Gate
+
+from .noise import Noise
+from .noise_config import NoiseConfig
+from .parameter_perturbation import ParameterPerturbation
+from .protocols import AttachmentScope
+
+Qubit: TypeAlias = int
+GateType: TypeAlias = type[Gate]
+ParameterName: TypeAlias = str
+
+TNoise = TypeVar("TNoise", bound=Noise)
+TParameterPerturbation = TypeVar("TParameterPerturbation", bound=ParameterPerturbation)
+
+
+class NoiseModel:
+    """Container for noise sources and parameter perturbations.
+
+    Stores global, per-qubit, and per-gate noise along with parameter-level
+    perturbations for later application in backends.
+    """
+
+    def __init__(self, noise_config: NoiseConfig | None = None) -> None:
+        # configuration
+        if noise_config is not None:
+            self._noise_config = noise_config
+        else:
+            self._noise_config = NoiseConfig()
+
+        # noises
+        self._global_noise: list[Noise] = []
+        self._per_qubit_noise: dict[Qubit, list[Noise]] = defaultdict(list)
+        self._per_gate_noise: dict[GateType, list[Noise]] = defaultdict(list)
+        self._per_gate_per_qubit_noise: dict[tuple[GateType, Qubit], list[Noise]] = defaultdict(list)
+
+        # parameter perturbations
+        self._global_perturbations: dict[ParameterName, list[ParameterPerturbation]] = defaultdict(list)
+        self._per_gate_perturbations: dict[tuple[GateType, ParameterName], list[ParameterPerturbation]] = defaultdict(
+            list
+        )
+
+    @property
+    def noise_config(self) -> NoiseConfig:
+        """Return the noise configuration.
+
+        Returns:
+            NoiseConfig: The noise configuration instance.
+        """
+        return self._noise_config
+
+    @property
+    def global_noise(self) -> list[Noise]:
+        """Return the list of globally applied noise sources.
+
+        Returns:
+            list[Noise]: Noise sources applied to all operations.
+        """
+        return self._global_noise
+
+    @property
+    def per_qubit_noise(self) -> dict[Qubit, list[Noise]]:
+        """Return the per-qubit noise mapping.
+
+        Returns:
+            dict[int, list[Noise]]: Noise sources keyed by qubit index.
+        """
+        return self._per_qubit_noise
+
+    @property
+    def per_gate_noise(self) -> dict[GateType, list[Noise]]:
+        """Return the per-gate-type noise mapping.
+
+        Returns:
+            dict[type[Gate], list[Noise]]: Noise sources keyed by gate type.
+        """
+        return self._per_gate_noise
+
+    @property
+    def per_gate_per_qubit_noise(self) -> dict[tuple[GateType, Qubit], list[Noise]]:
+        """Return the per-gate-type and per-qubit noise mapping.
+
+        Returns:
+            dict[tuple[type[Gate], int], list[Noise]]: Noise sources keyed by gate type and qubit index.
+        """
+        return self._per_gate_per_qubit_noise
+
+    @property
+    def global_perturbations(self) -> dict[ParameterName, list[ParameterPerturbation]]:
+        """Return the global parameter perturbation mapping.
+
+        Returns:
+            dict[str, list[ParameterPerturbation]]: Perturbations keyed by parameter name.
+        """
+        return self._global_perturbations
+
+    @property
+    def per_gate_perturbations(self) -> dict[tuple[GateType, ParameterName], list[ParameterPerturbation]]:
+        """Return the per-gate-type parameter perturbation mapping.
+
+        Returns:
+            dict[tuple[type[Gate], str], list[ParameterPerturbation]]: Perturbations keyed by gate type and parameter.
+        """
+        return self._per_gate_perturbations
+
+    # Overloads (typing)
+    # -----------------------
+
+    # Noise: global/per_qubit/per_gate_type
+    @overload
+    def add(self, noise: TNoise) -> None: ...
+    @overload
+    def add(self, noise: TNoise, *, qubits: list[Qubit]) -> None: ...
+    @overload
+    def add(self, noise: TNoise, *, gate: GateType) -> None: ...
+
+    # ParameterPerturbation: global/per_gate_type
+    @overload
+    def add(self, noise: TParameterPerturbation, *, parameter: ParameterName) -> None: ...
+    @overload
+    def add(self, noise: TParameterPerturbation, *, gate: GateType, parameter: ParameterName) -> None: ...
+
+    # -----------------------
+    # Implementation
+    # -----------------------
+
+    def add(
+        self,
+        noise: Noise | ParameterPerturbation,
+        *,
+        qubits: list[Qubit] | None = None,
+        gate: GateType | None = None,
+        parameter: ParameterName | None = None,
+    ) -> None:
+        """Attach a noise source or parameter perturbation to the model.
+
+        Args:
+            noise (Noise | ParameterPerturbation): The noise or parameter perturbation instance to attach.
+            qubits (list[int] | None): Target qubit index or indices for per-qubit noise attachments.
+            gate (type[Gate] | None): Target gate type for per-gate noise or perturbation attachments.
+            parameter (str | None): Target parameter name for perturbation attachments.
+
+        Raises:
+            ValueError: If the noise/perturbation does not allow the inferred scope.
+        """
+        if isinstance(noise, ParameterPerturbation):
+            if qubits is not None:
+                raise ValueError(f"{noise.__class__.__name__} cannot be applied to specific qubits.")
+            self._add_parameter_perturbation(
+                noise=noise,
+                gate=gate,
+                parameter=parameter,
+            )
+        else:
+            self._add_noise(
+                noise=noise,
+                qubits=qubits,
+                gate=gate,
+                parameter=parameter,
+            )
+
+    @staticmethod
+    def _check_scope_allowed(
+        noise: Noise | ParameterPerturbation,
+        scope: AttachmentScope,
+    ) -> None:
+        """Check if the noise/perturbation allows the given scope.
+
+        Args:
+            noise (Noise | ParameterPerturbation): The noise or parameter perturbation instance to check.
+            scope (AttachmentScope): The scope to check.
+        Raises:
+            ValueError: If the noise/perturbation does not allow the given scope.
+        """
+        if scope not in noise.allowed_scopes():
+            raise ValueError(f"{noise.__class__.__name__} cannot be added with scope '{scope.value}'.")
+
+    def _add_noise(
+        self,
+        noise: Noise,
+        *,
+        qubits: list[Qubit] | None = None,
+        gate: GateType | None = None,
+        parameter: ParameterName | None = None,
+    ) -> None:
+        """Attach a noise source to the model.
+
+        Args:
+            noise (Noise): The noise instance to attach.
+            qubits (list[int] | None): Target qubit index or indices for per-qubit noise attachments.
+            gate (type[Gate] | None): Target gate type for per-gate noise attachments.
+            parameter (str | None): Target parameter name for perturbation attachments.
+
+        Raises:
+            ValueError: If the noise does not allow the inferred scope.
+        """
+        if parameter is not None:
+            raise ValueError(f"{noise.__class__.__name__} cannot be applied to parameters.")
+        if qubits is None and gate is None:
+            self._check_scope_allowed(noise, AttachmentScope.GLOBAL)
+            self.global_noise.append(noise)
+            return
+        if qubits is not None and gate is None:
+            self._check_scope_allowed(noise, AttachmentScope.PER_QUBIT)
+            for q in qubits:
+                self.per_qubit_noise[q].append(noise)
+            return
+        if qubits is None and gate is not None:
+            self._check_scope_allowed(noise, AttachmentScope.PER_GATE_TYPE)
+            self.per_gate_noise[gate].append(noise)
+            return
+        if qubits is not None and gate is not None:
+            self._check_scope_allowed(noise, AttachmentScope.PER_GATE_TYPE_PER_QUBIT)
+            for q in qubits:
+                self.per_gate_per_qubit_noise[gate, q].append(noise)
+
+    def _add_parameter_perturbation(
+        self,
+        noise: ParameterPerturbation,
+        *,
+        gate: GateType | None = None,
+        parameter: ParameterName | None = None,
+    ) -> None:
+        """Attach a parameter perturbation to the model.
+
+        Args:
+            noise (ParameterPerturbation): The parameter perturbation instance to attach.
+            gate (type[Gate] | None): Target gate type for per-gate perturbation attachments.
+            parameter (str | None): Target parameter name for perturbation attachments.
+
+        Raises:
+            ValueError: If the perturbation does not allow the inferred scope.
+        """
+        if parameter is None:
+            raise ValueError(f"{noise.__class__.__name__} requires a parameter name.")
+        if gate is None:
+            self._check_scope_allowed(noise, AttachmentScope.GLOBAL)
+            self.global_perturbations[parameter].append(noise)
+            return
+        self._check_scope_allowed(noise, AttachmentScope.PER_GATE_TYPE)
+        self.per_gate_perturbations[gate, parameter].append(noise)

qilisdk/noise/offset_perturbation.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 __future__ import annotations
+
+from .parameter_perturbation import ParameterPerturbation
+
+
+class OffsetPerturbation(ParameterPerturbation):
+    """Parameter perturbation that adds a constant offset."""
+
+    def __init__(self, *, offset: float) -> None:
+        """Args:
+        offset (float): Additive bias applied to the parameter value.
+        """
+        self._offset = float(offset)
+
+    @property
+    def offset(self) -> float:
+        """Return the constant offset applied to parameter values.
+
+        Returns:
+            float: The additive offset.
+        """
+        return self._offset
+
+    def perturb(self, value: float) -> float:
+        return value + self._offset