sqil-core 1.0.0__tar.gz → 1.1.0__tar.gz

{sqil_core-1.0.0 → sqil_core-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sqil-core
-Version: 1.0.0
+Version: 1.1.0
 Summary: The codebase of the SQIL group in EPFL
 Author: Andrea Duina
 Requires-Python: >=3.10,<4.0

{sqil_core-1.0.0 → sqil_core-1.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "sqil-core"
-version = "v1.0.0"
+version = "v1.1.0"
 description = "The codebase of the SQIL group in EPFL"
 authors = ["Andrea Duina"]
 readme = "README.md"

{sqil_core-1.0.0 → sqil_core-1.1.0}/sqil_core/experiment/_analysis.py

@@ -17,6 +17,36 @@ if TYPE_CHECKING:
 
 
 class AnalysisResult:
+    """
+    Container for storing and managing results from a quantum measurement analysis.
+
+    Attributes
+    ----------
+    updated_params : dict[str, dict]
+        Dictionary containing the updated parameters for each qubit.
+    figures : dict[str, matplotlib.figure.Figure]
+        Dictionary of matplotlib figures.
+    fits : dict[str, FitResult]
+        Dictionary of fit results.
+    extra_data : dict[str, np.ndarray]
+        Dictionary of auxiliary computed arrays (e.g., processed IQ data, FFT results).
+
+    Methods
+    -------
+    add_exp_info_to_figures(dir_path)
+        Annotates each figure with experiment ID and cooldown name from directory path.
+    save_figures(dir_path)
+        Saves all figures as PNG and interactive HTML using mpld3.
+    aggregate_fit_summaries()
+        Aggregates human-readable summaries from all fit results.
+    save_fits(dir_path)
+        Saves aggregated fit summaries to a markdown file.
+    save_extra_data(dir_path)
+        Saves extra data arrays into an HDF5 file.
+    save_all(dir_path)
+        Runs all save methods and annotates figures with experimental metadata.
+    """
+
     updated_params: dict[str, dict] = {}
     figures: dict[str, Figure] = {}
     fits: dict[str, FitResult] = {}

{sqil_core-1.0.0 → sqil_core-1.1.0}/sqil_core/fit/__init__.py

@@ -11,6 +11,7 @@ from ._fit import (
     fit_decaying_oscillations,
     fit_gaussian,
     fit_lorentzian,
+    fit_many_decaying_oscillations,
     fit_oscillations,
     fit_qubit_relaxation_qp,
     fit_skewed_lorentzian,

{sqil_core-1.0.0 → sqil_core-1.1.0}/sqil_core/fit/_fit.py

@@ -11,12 +11,14 @@ from sqil_core.utils._utils import fill_gaps, has_at_least_one, make_iterable
 
 from ._core import FitResult, fit_input, fit_output
 from ._guess import (
+    decaying_exp_guess,
     decaying_oscillations_bounds,
     decaying_oscillations_guess,
     gaussian_bounds,
     gaussian_guess,
     lorentzian_bounds,
     lorentzian_guess,
+    many_decaying_oscillations_guess,
     oscillations_bounds,
     oscillations_guess,
 )
@@ -347,19 +349,9 @@ def fit_decaying_exp(
     """
     x, y = x_data, y_data
 
-    # Default initial guess if not provided
-    if guess is None:
-        max_y = np.max(y)
-        min_y = np.min(y)
-        half = 0.5 * (max_y + min_y)
-
-        if y[0] > y[-1]:
-            tau0_idx = np.argmax(y < half)
-        else:
-            tau0_idx = np.argmax(y > half)
-
-        b0 = x[tau0_idx] if tau0_idx != 0 else 0.5 * (x[0] + x[-1])
-        guess = [y[0] - y[-1], b0, y[-1]]
+    # Default intial guess if not provided
+    if has_at_least_one(guess, None):
+        guess = fill_gaps(guess, decaying_exp_guess(x_data, y_data))
 
     # Default bounds if not provided
     if bounds is None:
@@ -619,6 +611,55 @@ def fit_decaying_oscillations(
     return best_fit, metadata
 
 
+@fit_output
+def fit_many_decaying_oscillations(
+    x_data: np.ndarray, y_data: np.ndarray, n: int, guess=None
+):
+    """
+    Fits a sum of `n` exponentially decaying oscillations to the given data.
+
+    Each component of the model is of the form:
+        A_i * exp(-x / tau_i) * cos(2π * T_i * x + phi_i)
+
+    Parameters
+    ----------
+    x_data : np.ndarray
+        1D array of x-values (e.g., time).
+    y_data : np.ndarray
+        1D array of y-values (e.g., signal amplitude).
+    n : int
+        Number of decaying oscillation components to fit.
+    guess : list or None, optional
+        Optional initial parameter guess. If None, a guess is automatically generated
+        using `many_decaying_oscillations_guess`.
+
+    Returns
+    -------
+    FitResult
+    """
+
+    if has_at_least_one(guess, None):
+        guess = fill_gaps(guess, many_decaying_oscillations_guess(x_data, y_data, n))
+
+    res = curve_fit(
+        _models.many_decaying_oscillations,
+        x_data,
+        y_data,
+        p0=guess,
+        # maxfev=10000,
+        full_output=True,
+    )
+
+    metadata = {
+        "param_names": [f"{p}{i}" for i in range(n) for p in ("A", "tau", "phi", "T")]
+        + ["y0"],
+        "predict": lambda x: _models.many_decaying_oscillations(x, *res[0]),
+        "model_name": f"many_decaying_oscillations({n})",
+    }
+
+    return res, metadata
+
+
 @fit_input
 @fit_output
 def fit_oscillations(

{sqil_core-1.0.0 → sqil_core-1.1.0}/sqil_core/fit/_guess.py

@@ -2,6 +2,8 @@ import numpy as np
 from numpy.fft import rfft, rfftfreq
 from scipy.signal import hilbert
 
+from sqil_core.utils import compute_fft, get_peaks
+
 
 def estimate_peak(
     x_data: np.ndarray, y_data: np.ndarray
@@ -213,6 +215,12 @@ def decaying_oscillations_guess(x_data, y_data, num_init=10):
     except Exception:
         tau = np.ptp(x_data)
 
+    # Rough estimate of y0 with a local min or mean of last N points
+    N_tail = max(3, int(0.1 * len(y_data)))
+    tail_mean = np.mean(y_data[-N_tail:])
+    y0_decay = min(np.min(y_data), tail_mean)
+    y0_candidates.append(y0_decay)
+
     return [A, tau, y0_candidates, phi_candidates, T]
 
 
@@ -230,3 +238,67 @@ def decaying_oscillations_bounds(x_data, y_data, guess):
     lower.insert(1, tau_min)
     upper.insert(1, tau_max)
     return (lower, upper)
+
+
+def many_decaying_oscillations_guess(x_data, y_data, n):
+    offset = np.mean(y_data)
+    y_centered = y_data - offset
+
+    freqs, fft_mag = compute_fft(x_data, y_centered)
+    peak_freqs, peak_mags = get_peaks(freqs, fft_mag)
+
+    if len(peak_freqs) < n:
+        raise ValueError(
+            f"Not enough frequency peaks found to initialize {n} oscillations."
+        )
+
+    guess = []
+    signal_duration = x_data[-1] - x_data[0]
+
+    for i in range(n):
+        A = peak_mags[i]
+        tau = signal_duration / (2 + i)  # Increasing τ for later oscillations
+        phi = 0.0  # Can be refined
+        T = peak_freqs[i]
+        guess.extend([A, tau, phi, T])
+
+    guess.append(offset)
+    return guess
+
+
+def decaying_exp_guess(x_data: np.ndarray, y_data: np.ndarray) -> list[float]:
+    """
+    Robust initial guess for decaying exponential even if the full decay isn't captured.
+    """
+    x = np.asarray(x_data)
+    y = np.asarray(y_data)
+
+    # Rough estimate of y0 with a local min or mean of last N points
+    N_tail = max(3, int(0.1 * len(y)))
+    tail_mean = np.mean(y[-N_tail:])
+    y0 = min(np.min(y), tail_mean)
+
+    # Amplitude
+    A = y[0] - y0
+    A = np.clip(A, 1e-12, None)
+
+    # Ensure sign consistency
+    if np.abs(np.max(y) - y0) > np.abs(A):
+        A = np.max(y) - y0
+
+    # Estimate tau using log-linear fit of the first ~30% of data
+    N_fit = max(5, int(0.3 * len(x)))
+    y_fit = y[:N_fit] - y0
+    mask = y_fit > 0  # log() only valid on positive values
+
+    if np.count_nonzero(mask) > 1:
+        x_fit = x[:N_fit][mask]
+        log_y = np.log(y_fit[mask])
+        slope, intercept = np.polyfit(x_fit, log_y, 1)
+        tau = -1 / slope if slope < 0 else (x[-1] - x[0]) / 3
+    else:
+        tau = (x[-1] - x[0]) / 3
+
+    tau = max(tau, np.finfo(float).eps)
+
+    return [A, tau, y0]

{sqil_core-1.0.0 → sqil_core-1.1.0}/sqil_core/fit/_models.py

@@ -74,6 +74,24 @@ def decaying_oscillations(x, A, tau, y0, phi, T):
     return A * np.exp(-x / tau) * np.cos(2.0 * np.pi * (x - phi) / T) + y0
 
 
+def many_decaying_oscillations(t, *params):
+    r"""
+    f(x) = SUM_i A_i * exp(-x / τ_i) * cos(2π * (x - φ_i) / T_i) + y0
+
+    $$f(x) = \sum_i A_i \cdot e^{-x/\tau_i} \cdot \cos\left(\frac{2\pi (x - \phi_i)}{T_i}\right) + y_0$$
+    """
+    n = (len(params) - 1) // 4  # Each oscillation has 4 params: A, tau, phi, T
+    offset = params[-1]
+    result = np.zeros_like(t)
+    for i in range(n):
+        A = params[4 * i]
+        tau = params[4 * i + 1]
+        phi = params[4 * i + 2]
+        T = params[4 * i + 3]
+        result += A * np.exp(-t / tau) * np.cos(2 * np.pi * T * t + phi)
+    return result + offset
+
+
 def oscillations(x, A, y0, phi, T):
     r"""
     f(x) = A * cos(2π * (x - φ) / T) + y0

{sqil_core-1.0.0 → sqil_core-1.1.0}/sqil_core/utils/__init__.py

@@ -1,8 +1,10 @@
 from ._analysis import (
+    compute_fft,
     compute_snr_peaked,
     estimate_linear_background,
     find_closest_index,
     find_first_minima_idx,
+    get_peaks,
     line_between_2_points,
     linear_interpolation,
     remove_linear_background,
@@ -52,6 +54,8 @@ __all__ = [
     "find_closest_index",
     "compute_snr_peaked",
     "find_first_minima_idx",
+    "compute_fft",
+    "get_peaks",
     # Const
     "PARAM_METADATA",
     "ONE_TONE_PARAMS",

{sqil_core-1.0.0 → sqil_core-1.1.0}/sqil_core/utils/_analysis.py

@@ -1,5 +1,5 @@
 import numpy as np
-from scipy.signal import argrelextrema
+from scipy.signal import argrelextrema, find_peaks
 
 
 def remove_offset(data: np.ndarray, avg: int = 3) -> np.ndarray:
@@ -413,3 +413,106 @@ def find_first_minima_idx(data):
         return minima_indices[0]
 
     return None
+
+
+def compute_fft(x_data, y_data):
+    """
+    Computes the Fast Fourier Transform (FFT) of a signal and returns the positive frequency spectrum.
+
+    Parameters
+    ----------
+    x_data : np.ndarray
+        Time or independent variable array, assumed to be uniformly spaced.
+    y_data : np.ndarray
+        Signal data corresponding to `x_data`. Can be real or complex.
+
+    Returns
+    -------
+    positive_freqs : np.ndarray
+        Array of positive frequency components corresponding to the FFT.
+    fft_magnitude : np.ndarray
+        Magnitude of the FFT at the positive frequencies.
+
+    Notes
+    -----
+    - The signal is centered by subtracting its mean before computing the FFT, which removes the DC component.
+    - Only the positive frequency half of the FFT spectrum is returned, assuming a real-valued input signal.
+    - If `y_data` is complex, returned FFT values still reflect magnitude only.
+    - The input `x_data` must be uniformly spaced for the frequency axis to be accurate.
+
+    Examples
+    --------
+    >>> t = np.linspace(0, 1, 1000)
+    >>> y = np.sin(2 * np.pi * 50 * t)
+    >>> freqs, spectrum = compute_fft(t, y)
+    """
+
+    # Subtract DC offset to focus on oscillations
+    y_data_centered = y_data - np.mean(y_data)
+
+    # Calculate time step (assumes uniform spacing)
+    dt = x_data[1] - x_data[0]
+    N = len(x_data)
+
+    # Compute FFT and frequency axis
+    fft_vals = np.fft.fft(y_data_centered)
+    freqs = np.fft.fftfreq(N, dt)
+
+    # Take only positive frequencies
+    positive_freqs = freqs[: N // 2]
+    fft_magnitude = np.abs(fft_vals[: N // 2])
+
+    return positive_freqs, fft_magnitude
+
+
+def get_peaks(x_data, y_data, prominence: float | None = None, sort=True):
+    """
+    Detects and returns peaks in a 1D signal based on prominence.
+
+    Parameters
+    ----------
+    x_data : np.ndarray
+        1D array of x-values corresponding to `y_data` (e.g., frequency or time axis).
+    y_data : np.ndarray
+        1D array of y-values representing the signal in which to find peaks.
+    prominence : float or None, optional
+        Minimum prominence of peaks to detect. If None, defaults to 5% of the maximum
+        value in `y_data`.
+    sort : bool, optional
+        If True, peaks are sorted in descending order of magnitude. Default is True.
+
+    Returns
+    -------
+    peak_freqs : np.ndarray
+        x-values at which peaks occur.
+    peak_magnitudes : np.ndarray
+        y-values (magnitudes) at the detected peaks.
+
+    Notes
+    -----
+    - Uses `scipy.signal.find_peaks` for detection.
+
+    Examples
+    --------
+    >>> x = np.linspace(0, 10, 1000)
+    >>> y = np.sin(2 * np.pi * x) + 0.1 * np.random.randn(1000)
+    >>> freqs, mags = get_peaks(x, np.abs(y))
+    >>> print(freqs[:3], mags[:3])  # Show top 3 peak locations and magnitudes
+    """
+
+    if prominence is None:
+        prominence = 0.05 * np.max(y_data)
+
+    # Find peaks
+    peaks, properties = find_peaks(y_data, prominence=prominence)
+
+    # Get the corresponding frequencies and magnitudes
+    peak_freqs = x_data[peaks]
+    peak_magnitudes = y_data[peaks]
+
+    if sort:
+        sorted_indices = np.argsort(peak_magnitudes)[::-1]
+        peak_freqs = peak_freqs[sorted_indices]
+        peak_magnitudes = peak_magnitudes[sorted_indices]
+
+    return peak_freqs, peak_magnitudes

{sqil_core-1.0.0 → sqil_core-1.1.0}/sqil_core/utils/_const.py

@@ -91,6 +91,15 @@ PARAM_METADATA = {
         "unit": "s",
         "scale": 1e9,
     },
+    "ge_T1": {"name": "T1", "symbol": "T_1", "unit": "s", "scale": 1e6},
+    "ge_T2": {"name": "T2", "symbol": "T_2", "unit": "s", "scale": 1e6},
+    "ge_T2_star": {"name": "T2*", "symbol": "T_2^*", "unit": "s", "scale": 1e6},
+    "reset_delay_length": {
+        "name": "Reset delay",
+        "symbol": "T_{reset}",
+        "unit": "s",
+        "scale": 1e6,
+    },
 }
 
 ONE_TONE_PARAMS = np.array(

{sqil_core-1.0.0 → sqil_core-1.1.0}/sqil_core/utils/_formatter.py

@@ -184,10 +184,11 @@ class ParamInfo:
         }
 
     @property
-    def name_and_unit(self):
-        return self.name + (
-            f" [{self.rescaled_unit}]" if self.unit or self.scale != 1 else ""
-        )
+    def name_and_unit(self, latex=True):
+        unit = f"[{self.rescaled_unit}]" if self.unit or self.scale != 1 else ""
+        if unit == "":
+            return unit
+        return self.name + rf" ${unit}$" if latex else rf" {unit}"
 
     @property
     def rescaled_unit(self):