spin-pulse 1.0__py3-none-any.whl

spin_pulse/__init__.py

@@ -0,0 +1,41 @@
+# --------------------------------------------------------------------------------------
+# This code is part of SpinPulse.
+#
+# (C) Copyright Quobly 2025.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+# --------------------------------------------------------------------------------------
+"""
+:mod:`SpinPulse` is an open-source python package for simulating silicon based spin qubits at the pulse-level.
+
+Modules
+----------------
+:mod:`spin_pulse.transpilation`
+    The `transpilation` module provides a set of classes that enable the simulation of quantum circuits defined in `Qiskit` on silicon-based spin-qubit hardware models.
+
+:mod:`spin_pulse.environment`
+    The `environment` module provides a set of classes for defining and configuring a quantum experimental environment tailored to spin-qubit systems.
+
+:mod:`spin_pulse.characterization`
+    The `characterization` module provides a set of functions for characterizing spin-qubit control operations and quantifying noise strength.
+
+"""
+
+from .environment.experimental_environment import ExperimentalEnvironment
+from .transpilation.dynamical_decoupling import DynamicalDecoupling
+from .transpilation.hardware_specs import HardwareSpecs, Shape
+from .transpilation.pulse_circuit import PulseCircuit
+
+__all__ = [
+    "DynamicalDecoupling",
+    "ExperimentalEnvironment",
+    "HardwareSpecs",
+    "PulseCircuit",
+    "Shape",
+]

spin_pulse/characterization/__init__.py

@@ -0,0 +1,16 @@
+# --------------------------------------------------------------------------------------
+# This code is part of SpinPulse.
+#
+# (C) Copyright Quobly 2025.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+# --------------------------------------------------------------------------------------
+"""This module provides a set of functions for characterizing spin-qubit control operations and quantifying noise intensity.
+It includes methods for performing Ramsey experiments, comparing quantum circuits, and computing average quantum channels.
+"""

spin_pulse/characterization/average_superop.py

@@ -0,0 +1,219 @@
+# --------------------------------------------------------------------------------------
+# This code is part of SpinPulse.
+#
+# (C) Copyright Quobly 2025.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+# --------------------------------------------------------------------------------------
+"""
+Utilities to analyze and visualize quantum super-Operators.
+"""
+
+import itertools
+
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+import numpy as np
+import qiskit as qi
+from qiskit.quantum_info import (
+    Chi,
+    Operator,
+    Pauli,
+    SuperOp,
+)
+
+
+def compare_circuits(circ1: qi.QuantumCircuit, circ2: qi.QuantumCircuit):
+    """
+    Compare two quantum circuits by plotting the matrix elements of their
+    corresponding unitary operators.
+
+    This function converts both circuits into unitary matrices using
+    qiskit.quantum_info.Operator.
+    The global phase is removed before comparison. Three scatter plots are
+    generated: real parts, imaginary parts, and absolute values of the matrix
+    elements. A diagonal reference line is shown, and the squared distance
+    between the two matrices is displayed.
+
+    Parameters:
+        circ1 (qiskit.QuantumCircuit): First circuit to compare.
+        circ2 (qiskit.QuantumCircuit): Second circuit to compare.
+
+    Notes:
+        The global phase is aligned using the matrix element with maximum magnitude.
+        This function is useful to visually validate the equivalence of two circuits
+        after transformations such as transpilation or pulse compilation.
+
+    """
+    data1 = (Operator.from_circuit(circ1).data).flatten()
+    data2 = (Operator.from_circuit(circ2).data).flatten()
+    i_phase = np.argmax(abs(data1))
+    phase1 = np.angle(data1[i_phase])
+    data1 *= np.exp(-1j * phase1)
+    phase2 = np.angle(data2[i_phase])
+    data2 *= np.exp(-1j * phase2)
+    plt.plot(np.real(data1), np.real(data2), "o", label="real")
+    plt.plot(np.imag(data1), np.imag(data2), "x", label="imag")
+    plt.plot(np.abs(data1), np.abs(data2), "*", label="abs")
+
+    a = np.max(abs(data1))
+    plt.plot([-a, a], [-a, a], "--k")
+    plt.text(-a, a, f"distance  {np.sum(np.abs(data1 - data2) ** 2)}")
+    plt.xlabel("circ 1 matrix elements")
+    plt.ylabel("circ 2 matrix elements")
+    plt.legend(loc=0)
+
+
+def plot_chi_matrix(superop: dict[str, SuperOp], threshold=None) -> plt.Figure:
+    """Plot the chi-matrix elements for one or multiple quantum superop.
+
+    The chi-matrix is computed for each channel and plotted as bar plots
+    (real and imaginary parts). If a threshold is provided, only elements
+    with absolute value greater than the threshold (from the first channel)
+    are shown.
+
+    Channels whose key contains the substring ``"analytical"`` are plotted
+    with transparent bars and line styles, while the others are plotted as
+    semi-transparent filled bars.
+
+    Parameters:
+        superop (dict[str, qiskit.quantum_info.SuperOp or qiskit.quantum_info.Channel]):
+            Dictionary mapping labels to quantum super-Operator. Each value must
+            be compatible with ``qiskit.quantum_info.Choi``/``Chi`` so that
+            ``Chi(superop[key]).data`` returns the chi-matrix.
+        threshold (float | None): If not ``None``, only chi-matrix elements with
+            absolute value greater than ``threshold`` (as determined from the
+            first channel in ``superop``) are included in the plot.
+
+    Returns:
+        matplotlib.figure.Figure: The figure object containing the chi-matrix plot.
+
+    """
+    n_qb = int(np.log2(next(iter(superop.values())).data.shape[0]) / 2)
+    mpl.rcParams["font.size"] = 22
+    fig = plt.figure(figsize=(10, 5))
+    # Generate Pauli basis labels
+    paulis = ["I", "X", "Y", "Z"]
+    pauli_labels = ["".join(p) for p in itertools.product(paulis, repeat=n_qb)]
+    full_labels = [f"${p1}.{p2}$" for p1 in pauli_labels for p2 in pauli_labels]
+
+    counter = 0
+    lines_style = ["-", "--", ":", "-."]
+
+    x = np.arange(len(full_labels))
+
+    for index, key in enumerate(superop.keys()):
+        chi_matrix = Chi(superop[key]).data
+
+        # Flatten matrix into list of values and labels
+        values = chi_matrix.flatten()
+
+        if threshold is not None and index == 0:
+            indices = [i for i in range(len(values)) if np.abs(values[i]) > threshold]
+            x = np.array(range(len(indices)))
+            full_labels = [full_labels[i] for i in indices]
+        if threshold is not None:
+            values = values[indices]
+
+        if "analytical" in key:
+            plt.bar(
+                x,
+                np.real(values),
+                tick_label=full_labels,
+                label=f"{key}" + " (real)",
+                facecolor="none",
+                edgecolor="tab:blue",
+                linestyle=lines_style[counter % len(lines_style)],
+                linewidth=1.0,
+            )
+            plt.bar(
+                x,
+                np.imag(values),
+                tick_label=full_labels,
+                label=f"{key}" + " (imag)",
+                facecolor="none",
+                edgecolor="tab:orange",
+                linestyle=lines_style[counter % len(lines_style)],
+                linewidth=1.0,
+            )
+            counter += 1
+
+        else:
+            plt.bar(
+                x,
+                np.real(values),
+                alpha=0.3,
+                tick_label=full_labels,
+                label=f"{key}" + " (real)",
+            )
+            plt.bar(
+                x,
+                np.imag(values),
+                alpha=0.3,
+                tick_label=full_labels,
+                label=f"{key}" + " (imag)",
+            )
+
+    plt.xticks(rotation=90)
+    plt.ylabel(r"$\chi$")
+    plt.legend()
+    plt.grid(True, axis="y", linestyle="--", alpha=0.5)
+    plt.tight_layout()
+    return fig
+
+
+def get_superop_from_paulidict(pauli_dict: dict[str, complex]) -> SuperOp:
+    r"""Return the SuperOp corresponding to a Pauli decomposition given as
+    a dictionary.
+
+    The input is a mapping from tensor-product Pauli labels (e.g., "IXZ",
+    "ZZ", "I") to complex coefficients. For an n-qubit system, each label
+    must be a string of length n, with characters drawn from
+    ``{"I", "X", "Y", "Z"}``.
+
+    The function builds the operator
+
+    .. math::
+
+        O = \sum_{P} c_P P,
+
+    where :math:`P` runs over Pauli strings and :math:`c_P` are the provided
+    coefficients, and then wraps it as a ``qiskit.quantum_info.SuperOp``.
+
+    Parameters:
+        pauli_dict (dict[str, complex]): Dictionary mapping Pauli labels
+            (e.g., "IX", "ZZI") to complex coefficients.
+
+    Returns:
+        qiskit.quantum_info.SuperOp: The resulting quantum channel represented
+        as a ``SuperOp`` acting on the corresponding Hilbert space dimension.
+
+    """
+    keys = list(pauli_dict.keys())
+
+    # Validate that all keys are even in Pauli matrices
+    for i in range(len(keys)):
+        if len(keys[i]) % 2 != 0:
+            raise ValueError(
+                "All Pauli keys must have an even number of single-qubit Pauli matrices "
+                f"(got {len(keys[i])})."
+            )
+    # Validate that all keys have the same length
+    for i in range(1, len(keys)):
+        if len(keys[i - 1]) != len(keys[i]):
+            raise ValueError(
+                "All keys must have the same length "
+                f"(got {len(keys[i - 1])} and {len(keys[i])})."
+            )
+
+    super_ops = []
+    for label, coeff in pauli_dict.items():
+        P = Pauli(label)
+        super_ops.append(coeff * SuperOp(P.to_matrix()))
+    return sum(super_ops)

spin_pulse/characterization/ramsey.py

@@ -0,0 +1,120 @@
+# --------------------------------------------------------------------------------------
+# This code is part of SpinPulse.
+#
+# (C) Copyright Quobly 2025.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+# --------------------------------------------------------------------------------------
+"""Helper functions to carry out Ramsey experiments."""
+
+import numpy as np
+import qiskit as qi
+from qiskit.quantum_info import Operator
+from tqdm import tqdm
+
+from ..environment.experimental_environment import ExperimentalEnvironment
+from ..transpilation.hardware_specs import HardwareSpecs
+from ..transpilation.pulse_circuit import PulseCircuit
+
+
+def get_ramsey_circuit(
+    duration: int,
+    hardware_specs: HardwareSpecs,
+    exp_env: ExperimentalEnvironment | None = None,
+):
+    """Construct a pulse-level Ramsey experiment.
+
+    This function builds a single-qubit Ramsey sequence consisting of a
+    Hadamard gate, an idle period of a specified duration, and a second
+    Hadamard gate. The circuit is transpiled into the hardware native gate
+    set and converted into a PulseCircuit. If an experimental environment is
+    provided, noise time traces are attached to the resulting pulse-level
+    circuit.
+
+    Parameters:
+        duration (int): Duration of the free-evolution period (in the discrete
+            time unit used by the hardware model).
+        hardware_specs (HardwareSpecs): Hardware configuration used to
+            transpile the logical Ramsey sequence into native instructions, and
+            to generate the pulse sequences of the PulseCircuit.
+        exp_env (ExperimentalEnvironment | None): Optional noise environment
+            from which time traces are created and attached to the PulseCircuit.
+
+    Returns:
+        PulseCircuit: Pulse-level representation of the Ramsey experiment,
+        optionally including noise time traces.
+
+    """
+    qreg = qi.QuantumRegister(1)
+    circ = qi.QuantumCircuit(qreg)
+    circ.h(0)
+    circ.delay(int(duration))
+
+    circ.h(0)
+    isa_circ = hardware_specs.gate_transpile(circ)
+    pulse_circuit = PulseCircuit.from_circuit(isa_circ, hardware_specs, exp_env=exp_env)
+    return pulse_circuit
+
+
+def get_contrast(pulse_circuit: PulseCircuit) -> float:
+    """Compute the population contrast of a Ramsey experiment.
+
+    The pulse-level circuit is converted back to a unitary qiskit.QuantumCircuit,
+    and the resulting unitary matrix is applied to the input state 0.
+    The contrast is defined as the population difference between state 0
+    and state 1, that is: C = P0 - P1
+
+    Parameters:
+        pulse_circuit (PulseCircuit): Pulse-level Ramsey circuit.
+
+    Returns:
+        float: Population contrast.
+
+    """
+
+    circ = pulse_circuit.to_circuit()
+    unitary = Operator(circ).to_matrix()
+    statevector = unitary[:, 0]
+    return np.abs(statevector[0]) ** 2 - np.abs(statevector[1]) ** 2
+
+
+def get_average_ramsey_contrast(
+    hardware_specs: HardwareSpecs,
+    exp_env: ExperimentalEnvironment,
+    durations: list[int],
+):
+    """Compute the average Ramsey contrast over multiple noise realizations.
+
+    For each free-evolution duration given, a Ramsey pulse circuit is constructed
+    and its population contrast is computed by averaging over multiple noise
+    realizations drawn from the experimental environment. After each duration,
+    the environment time traces are regenerated to ensure independence
+    between samples.
+
+    Parameters:
+        hardware_specs (HardwareSpecs): Hardware configuration used to
+            construct pulse-level Ramsey circuits.
+        exp_env (ExperimentalEnvironment): Noise environment providing time
+            traces for each sample.
+        durations (list[int]): List of free-evolution durations for which the
+            Ramsey contrast is evaluated.
+
+    Returns:
+        np.ndarray: Array containing the average Ramsey contrast for each
+            duration in ``durations``.
+
+    """
+    nbp = len(durations)
+    average_contrast = np.zeros(nbp)
+    for j in tqdm(range(nbp)):
+        ramsey_circ = get_ramsey_circuit(durations[j], hardware_specs)
+        average_contrast[j] = ramsey_circ.averaging_over_samples(get_contrast, exp_env)
+        # regenerate new time traces for the next duration
+        exp_env.generate_time_traces()
+    return average_contrast

spin_pulse/environment/__init__.py

@@ -0,0 +1,23 @@
+# --------------------------------------------------------------------------------------
+# This code is part of SpinPulse.
+#
+# (C) Copyright Quobly 2025.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+# --------------------------------------------------------------------------------------
+"""
+The `environment` module provides a set of classes for defining and configuring a quantum experimental environment tailored to spin-qubit systems.
+
+    - :mod:`spin_pulse.environment.experimental_environment`, defines the `Environment` class that contains a quantum experimental environment with configurable noise models.
+
+    The submodule :mod:`spin_pulse.environment.noise` provides a set of noise classes for simulating different noise processes:
+        - QUASISTATIC: Quasistatic noise generated by `QuasistaticNoiseTimeTrace`.
+        - PINK: Pink (1/f) noise generated by `PinkNoiseTimeTrace`.
+        - WHITE: White Gaussian noise generated by `WhiteNoiseTimeTrace`.
+"""

spin_pulse/environment/experimental_environment.py

@@ -0,0 +1,158 @@
+# --------------------------------------------------------------------------------------
+# This code is part of SpinPulse.
+#
+# (C) Copyright Quobly 2025.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+# --------------------------------------------------------------------------------------
+"""Description of the noisy environment associated to a hardware."""
+
+from ..transpilation.hardware_specs import HardwareSpecs
+from .noise import (
+    NoiseType,
+    PinkNoiseTimeTrace,
+    QuasistaticNoiseTimeTrace,
+    WhiteNoiseTimeTrace,
+)
+
+
+class ExperimentalEnvironment:
+    """
+    Contain a quantum experimental environment with configurable noise models.
+
+    Attributes:
+        - hardware_specs (class): HardwareSpecs class, that defines the hardware settings.
+        - noise_type (NoiseType): Type of noise to simulate. Must be "pink", "white", or "quasistatic".
+        - T2S (float): Characteristic time of individual qubits.
+        - TJS (float or None): Characteristic time of coupled two-qubit system at maximal J coupling without noise on the qubit's frequency.
+        - duration (int): Total duration of the simulation.
+        - segment_duration (int): Duration of each noise segment; used to partition the time trace.
+        - only_idle (bool): Flag to apply noise only to idle qubits.
+        - time_traces (list[float]): List of time traces for each qubit.
+        - time_traces_coupling (list[float]): List of time traces for coupling noise for each pair of qubits (if TJS is set).
+        - seed (int or None): seed integer for random number generation. If not specified, no seed used.
+
+    """
+
+    # noise_generator (class): Noise generator class based on noise_type. :no-index:
+
+    noise_generator: (
+        type[WhiteNoiseTimeTrace]
+        | type[QuasistaticNoiseTimeTrace]
+        | type[PinkNoiseTimeTrace]
+    )
+
+    def __init__(
+        self,
+        hardware_specs: HardwareSpecs,
+        noise_type: NoiseType = NoiseType.PINK,
+        T2S: float = 100.0,
+        TJS: float | None = None,
+        duration: int = 2**10,
+        only_idle: bool = False,
+        segment_duration: int = 2**10,
+        seed: int | None = None,
+    ):
+        """
+        Initialize the ExperimentalEnvironment with specified noise characteristics and simulation parameters.
+
+        Parameters:
+            hardware_specs (class): HardwareSpecs class, that defines the hardware settings.
+            noise_type (NoiseType): Type of noise to simulate. Must be "pink", "white", or "quasistatic".
+            T2S (float): Characteristic time of individual qubits.
+            TJS (float or None): Characteristic time of coupled two-qubit system at maximal J coupling with no noise on the qubit's frequency.
+            duration (int): Total duration of the simulation.
+            only_idle (bool): Flag to apply noise only to idle qubits.
+            segment_duration (int): Duration of each noise segment; used to partition the time trace.
+            seed (int or None): seed integer for random number generation. If not specified, no seed used.
+        Raises:
+            ValueError: If an invalid noise_type is provided.
+
+        """
+
+        self.hardware_specs: HardwareSpecs = hardware_specs
+        self.noise_type: NoiseType = noise_type
+        self.T2S: float = T2S
+        self.TJS: float | None = TJS
+        self.duration: int = duration
+        self.segment_duration: int = segment_duration
+        self.seed: int | None = seed
+        match noise_type:
+            case NoiseType.PINK:
+                self.noise_generator = PinkNoiseTimeTrace
+            case NoiseType.WHITE:
+                self.noise_generator = WhiteNoiseTimeTrace
+            case NoiseType.QUASISTATIC:
+                self.noise_generator = QuasistaticNoiseTimeTrace
+            case _:
+                raise ValueError("unknown noise type")
+
+        self.only_idle = only_idle
+        self.generate_time_traces()
+
+    def generate_time_traces(self):
+        """
+        Generate noise time traces for each qubit's frequency and J coupling to each pair of qubits if TJS is defined.
+
+        Behavior:
+            For each qubit, instantiate a noise generator using the selected noise_type.
+            The generator uses T2S, duration, and segment_duration to produce a time trace.
+            If TJS is provided, generate additional time traces for J coupling noise for each pair of qubits.
+
+        Effects:
+            Populate self.time_traces with one noise trace per qubit.
+            If TJS is set, populate self.time_traces_coupling with one trace per pair of qubits (n-1 traces for n qubits).
+        """
+        self.time_traces = []
+        for _ in range(self.hardware_specs.num_qubits):
+            time_trace = self.noise_generator(
+                self.T2S, self.duration, self.segment_duration, seed=self.seed
+            )
+            self.time_traces.append(time_trace)
+
+        if self.TJS is not None:
+            self.time_traces_coupling = []
+            for _ in range(self.hardware_specs.num_qubits - 1):
+                time_trace = self.noise_generator(
+                    self.TJS, self.duration, self.segment_duration, seed=self.seed
+                )
+                self.time_traces_coupling.append(time_trace)
+
+    def __str__(self):
+        """
+        Return a string representation of the ExperimentalEnvironment instance.
+
+        Includes:
+            Number of qubits
+            Noise type
+            T2S and TJS values
+            Duration and segment duration
+            Whether noise is only appplied to idle qubits
+            The J coupling value set in HardwareSpecs
+            The total number of generated time traces
+            The total number of generated coupling time traces if there exists some
+        """
+        summary = [
+            "ExperimentalEnvironment:",
+            f"  Qubits: {self.hardware_specs.num_qubits}",
+            f"  Noise Type: {self.noise_type}",
+            f"  T2S (qubit dephasing): {self.T2S}",
+            f"  TJS (coupling dephasing): {self.TJS if self.TJS is not None else 'None'}",
+            f"  Duration: {self.duration}",
+            f"  Segment Duration: {self.segment_duration}",
+            f"  Only Idle: {self.only_idle}",
+            f"  J Coupling: {self.hardware_specs.J_coupling if self.hardware_specs.J_coupling is not None else 'None'}",
+            f"  Time Traces Generated: {len(self.time_traces)}",
+            f"  Seed: {self.seed}",
+        ]
+        if hasattr(self, "time_traces_coupling"):
+            summary.append(
+                f"  Coupling Time Traces Generated: {len(self.time_traces_coupling)}"
+            )
+        return "\n".join(summary)

spin_pulse/environment/noise/__init__.py

@@ -0,0 +1,32 @@
+# --------------------------------------------------------------------------------------
+# This code is part of SpinPulse.
+#
+# (C) Copyright Quobly 2025.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+# --------------------------------------------------------------------------------------
+"""
+This modules provides a set of noise classes for simulating different noise processes:
+    - QUASISTATIC: Quasistatic noise generated by `QuasistaticNoiseTimeTrace` from :mod:`spin_pulse.environment.noise.quasistatic`.
+    - PINK: Pink (1/f) noise generated by `PinkNoiseTimeTrace` from :mod:`spin_pulse.environment.noise.pink`.
+    - WHITE: White Gaussian noise generated by `WhiteNoiseTimeTrace` from :mod:`spin_pulse.environment.noise.white`.
+"""
+
+from .noise_time_trace import NoiseTimeTrace, NoiseType
+from .pink import PinkNoiseTimeTrace
+from .quasistatic import QuasistaticNoiseTimeTrace
+from .white import WhiteNoiseTimeTrace
+
+__all__ = [
+    "NoiseTimeTrace",
+    "NoiseType",
+    "PinkNoiseTimeTrace",
+    "QuasistaticNoiseTimeTrace",
+    "WhiteNoiseTimeTrace",
+]