sqil-core 0.1.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

sqil_core/utils/_analysis.py

@@ -1,4 +1,5 @@
 import numpy as np
+from scipy.signal import argrelextrema, find_peaks
 
 
 def remove_offset(data: np.ndarray, avg: int = 3) -> np.ndarray:
@@ -211,6 +212,90 @@ def line_between_2_points(
     return slope, intercept
 
 
+def soft_normalize(data: np.ndarray) -> np.ndarray:
+    """
+    Apply soft normalization to a 1D or 2D array with optional NaNs.
+
+    This function performs z-score normalization followed by a smooth
+    non-linear compression using a hyperbolic tangent (tanh) function.
+    It is designed to reduce the effect of outliers while preserving
+    the dynamic range of typical data values. The result is rescaled to [0, 1].
+
+    For 2D arrays, normalization is done row-wise, but compression is
+    based on a global threshold across all non-NaN entries.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Input data, must be a 1D or 2D NumPy array. Can contain NaNs.
+
+    Returns
+    -------
+    np.ndarray
+        Normalized data, same shape as input, with values scaled to [0, 1].
+        NaNs are preserved.
+
+    Raises
+    ------
+    ValueError
+        If `data` is not 1D or 2D.
+
+    Notes
+    -----
+    - Z-score normalization is done using nanmean and nanstd.
+    - Outliers are compressed using a tanh centered at a scaled threshold.
+    - Output values are guaranteed to be in [0, 1] range, except NaNs.
+    - Rows with zero standard deviation are flattened to 0.5.
+    """
+
+    if data.ndim not in [1, 2]:
+        raise ValueError("Input must be 1D or 2D")
+
+    data = np.array(data, dtype=np.float64)
+    nan_mask = np.isnan(data)
+
+    if data.ndim == 1:
+        mean = np.nanmean(data)
+        std = np.nanstd(data)
+        std = 1.0 if std == 0 else std
+        abs_z = np.abs((data - mean) / std)
+    else:
+        mean = np.nanmean(data, axis=1, keepdims=True)
+        std = np.nanstd(data, axis=1, keepdims=True)
+        std = np.where(std == 0, 1.0, std)
+        abs_z = np.abs((data - mean) / std)
+
+    # Flatten over all values for global thresholding
+    flat_abs_z = abs_z[~nan_mask]
+    if flat_abs_z.size == 0:
+        return np.full_like(data, 0.5)
+
+    threshold = 4.0 * np.mean(flat_abs_z)
+    alpha = 1.0 / (4.0 * np.std(flat_abs_z)) if np.std(flat_abs_z) != 0 else 1.0
+
+    compressed = np.tanh(alpha * (abs_z - threshold))
+
+    # Rescale to [0, 1]
+    compressed[nan_mask] = np.nan
+    min_val = np.nanmin(compressed)
+    max_val = np.nanmax(compressed)
+    if max_val == min_val:
+        rescaled = np.full_like(compressed, 0.5)
+    else:
+        rescaled = (compressed - min_val) / (max_val - min_val)
+
+    rescaled[nan_mask] = np.nan
+    return rescaled
+
+
+def find_closest_index(arr, target):
+    """
+    Find the index of the element in `arr` closest to the `target` value.
+    """
+
+    return np.abs(arr - target).argmin()
+
+
 def compute_snr_peaked(
     x_data: np.ndarray,
     y_data: np.ndarray,
@@ -290,3 +375,144 @@ def compute_snr_peaked(
     snr = signal / noise_std if noise_std > 0 else np.inf  # Avoid division by zero
 
     return snr
+
+
+def find_first_minima_idx(data):
+    """
+    Find the index of the first local minimum in a 1D array.
+
+    Parameters
+    ----------
+    data : array-like
+        1D sequence of numerical values.
+
+    Returns
+    -------
+    int or None
+        Index of the first local minimum, or None if no local minimum is found.
+
+    Notes
+    -----
+    A local minimum is defined as a point that is smaller than its immediate neighbors.
+    Uses `scipy.signal.argrelextrema` to detect local minima.
+
+    Examples
+    --------
+    >>> data = [3, 2, 4, 1, 5]
+    >>> find_first_minima_idx(data)
+    1
+    """
+    data = np.array(data)
+    minima_indices = argrelextrema(data, np.less)[0]
+
+    # Check boundaries for minima (optional)
+    if data.size < 2:
+        return None
+
+    if len(minima_indices) > 0:
+        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/utils/_const.py

@@ -4,7 +4,7 @@ _EXP_UNIT_MAP = {
     -15: "p",
     -12: "f",
     -9: "n",
-    -6: r"\mu",
+    -6: r"\mu ",
     -3: "m",
     0: "",
     3: "k",
@@ -14,36 +14,101 @@ _EXP_UNIT_MAP = {
     15: "P",
 }
 
-_PARAM_METADATA = {
-    "current": {"name": "Current", "symbol": "I", "unit": "A", "scale": 1e3},
-    "ro_freq": {
+PARAM_METADATA = {
+    "readout_resonator_frequency": {
         "name": "Readout frequency",
         "symbol": "f_{RO}",
         "unit": "Hz",
         "scale": 1e-9,
+        "precision": 5,
     },
-    "ro_power": {
-        "name": "Readout power",
-        "symbol": "P_{RO}",
+    "readout_range_out": {
+        "name": "Readout power offset",
+        "symbol": "P_0^{RO}",
         "unit": "dBm",
         "scale": 1,
     },
-    "qu_freq": {
-        "name": "Qubit frequency",
-        "symbol": "f_q",
+    "readout_amplitude": {
+        "name": "Readout amplitude",
+        "symbol": "A_{RO}",
+        "unit": "",
+        "scale": 1,
+    },
+    "readout_length": {
+        "name": "Readout length",
+        "symbol": "T_{RO}",
+        "unit": "s",
+        "scale": 1e6,
+    },
+    "readout_lo_frequency": {
+        "name": "Internal readout LO frequency",
+        "symbol": "f_{LO-int}^{RO}",
+        "unit": "Hz",
+        "scale": 1e-9,
+    },
+    "readout_external_lo_frequency": {
+        "name": "External LO frequency",
+        "symbol": "f_{LO}^{Ext}",
+        "unit": "Hz",
+        "scale": 1e-9,
+    },
+    "readout_external_lo_power": {
+        "name": "External LO power",
+        "symbol": "P_{LO}^{Ext}",
+        "unit": "dBm",
+        "scale": 1,
+    },
+    "readout_kappa_tot": {"symbol": r"\kappa_{tot}", "unit": "Hz", "scale": "MHz"},
+    "resonance_frequency_ge": {
+        "name": "Readout frequency",
+        "symbol": "f_{ge}",
+        "unit": "Hz",
+        "scale": 1e-9,
+        "precision": 5,
+    },
+    "resonance_frequency_ef": {
+        "name": "Readout frequency",
+        "symbol": "f_{ef}",
         "unit": "Hz",
         "scale": 1e-9,
+        "precision": 5,
+    },
+    "spectroscopy_amplitude": {
+        "name": "Spectroscopy amplitude",
+        "symbol": "A_{sp}",
+        "unit": "",
+        "scale": 1,
+    },
+    "ge_drive_amplitude_pi": {
+        "name": "Drive amplitude pi ge",
+        "symbol": r"A_{\pi}^{ge}",
+        "unit": "",
+        "scale": 1,
+    },
+    "ge_drive_length": {
+        "name": "Drive length ge",
+        "symbol": r"T_{\pi}^{ge}",
+        "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,
     },
-    "qu_power": {"name": "Qubit power", "symbol": "P_q", "unit": "dBm", "scale": 1},
-    "vna_bw": {"name": "VNA bandwidth", "symbol": "BW_{VNA}", "unit": "Hz", "scale": 1},
-    "vna_avg": {"name": "VNA averages", "symbol": "avg_{VNA}", "unit": "", "scale": 1},
-    "index": {"name": "Index", "symbol": "idx", "unit": "", "scale": 1},
 }
 
 ONE_TONE_PARAMS = np.array(
-    ["current", "ro_power", "vna_bw", "vna_avg", "qu_power", "qu_freq"]
+    [
+        "readout_amplitude",
+        "readout_length",
+        "readout_external_lo_frequency",
+        "readout_external_lo_power",
+    ]
 )
 
-TWO_TONE_PARAMS = np.array(
-    ["ro_freq", "ro_power", "current", "vna_bw", "vna_avg", "qu_power"]
-)
+TWO_TONE_PARAMS = np.array(["spectroscopy_amplitude"])

sqil_core/utils/_formatter.py

@@ -1,10 +1,12 @@
+import json
 from decimal import ROUND_DOWN, Decimal
 
+import attrs
 import numpy as np
 from scipy.stats import norm
 from tabulate import tabulate
 
-from ._const import _EXP_UNIT_MAP, _PARAM_METADATA
+from ._const import _EXP_UNIT_MAP, PARAM_METADATA
 
 
 def _cut_to_significant_digits(number, n):
@@ -88,13 +90,13 @@ def get_name_and_unit(param_id: str) -> str:
     str
         Name and [unit]
     """
-    meta = _PARAM_METADATA[param_id]
+    meta = PARAM_METADATA[param_id]
     scale = meta["scale"] if "scale" in meta else 1
     exponent = -(int(f"{scale:.0e}".split("e")[1]) // 3) * 3
     return f"{meta['name']} [{_EXP_UNIT_MAP[exponent]}{meta['unit']}]"
 
 
-def print_fit_params(param_names, params, std_errs=None, perc_errs=None):
+def format_fit_params(param_names, params, std_errs=None, perc_errs=None):
     matrix = [param_names, params]
 
     headers = ["Param", "Fitted value"]
@@ -111,58 +113,7 @@ def print_fit_params(param_names, params, std_errs=None, perc_errs=None):
     data = [matrix[:, i] for i in range(len(params))]
 
     table = tabulate(data, headers=headers, tablefmt="github")
-    print(table + "\n")
-
-
-def print_fit_metrics(fit_quality, keys: list[str] | None = None):
-    if keys is None:
-        keys = fit_quality.keys() if fit_quality else []
-
-    # Print fit quality parameters
-    for key in keys:
-        value = fit_quality[key]
-        quality = ""
-        # Evaluate reduced Chi-squared
-        if key == "red_chi2":
-            key = "reduced χ²"
-            if value <= 0.5:
-                quality = "GREAT (or overfitting)"
-            elif (value > 0.9) and (value <= 1.1):
-                quality = "GREAT"
-            elif (value > 0.5) and (value <= 2):
-                quality = "GOOD"
-            elif (value > 2) and (value <= 5):
-                quality = "MEDIUM"
-            elif value > 5:
-                quality = "BAD"
-        # Evaluate R-squared
-        elif key == "r2":
-            # Skip if complex
-            if isinstance(value, complex):
-                continue
-            key = "R²"
-            if value < 0:
-                quality = "BAD - a horizontal line would be better"
-            elif value > 0.97:
-                quality = "GREAT"
-            elif value > 0.95:
-                quality = "GOOD"
-            elif value > 0.80:
-                quality = "MEDIUM"
-            else:
-                quality = "BAD"
-        # Normalized mean absolute error NMAE and
-        # normalized root mean square error NRMSE
-        elif (key == "nmae") or (key == "nrmse"):
-            if value < 0.1:
-                quality = "GREAT"
-            elif value < 0.2:
-                quality = "GOOD"
-            else:
-                quality = "BAD"
-
-        # Print result
-        print(f"{key}\t{value:.3e}\t{quality}")
+    return table + "\n"
 
 
 def _sigma_for_confidence(confidence_level: float) -> float:
@@ -186,3 +137,124 @@ def _sigma_for_confidence(confidence_level: float) -> float:
     sigma_multiplier = norm.ppf(1 - alpha / 2)
 
     return sigma_multiplier
+
+
+class ParamInfo:
+    """Parameter information for items of param_dict
+
+    Attributes:
+        id (str): QPU key
+        value (any): the value of the parameter
+        name (str): full name of the parameter (e.g. Readout frequency)
+        symbol (str): symbol of the parameter in Latex notation (e.g. f_{RO})
+        unit (str): base unit of measurement (e.g. Hz)
+        scale (int): the scale that should be generally applied to raw data (e.g. 1e-9 to take raw Hz to GHz)
+    """
+
+    def __init__(self, id, value=None, metadata=None):
+        self.id = id
+        self.value = value
+
+        if metadata is not None:
+            meta = metadata
+        elif id in PARAM_METADATA:
+            meta = PARAM_METADATA[id]
+        else:
+            meta = {}
+
+        self.name = meta.get("name", None)
+        self.symbol = meta.get("symbol", id)
+        self.unit = meta.get("unit", "")
+        self.scale = meta.get("scale", 1)
+        self.precision = meta.get("precision", 3)
+
+        if self.name is None:
+            self.name = self.id[0].upper() + self.id[1:].replace("_", " ")
+
+    def to_dict(self):
+        """Convert ParamInfo to a dictionary."""
+        return {
+            "id": self.id,
+            "value": self.value,
+            "name": self.name,
+            "symbol": self.symbol,
+            "unit": self.unit,
+            "scale": self.scale,
+            "precision": self.precision,
+        }
+
+    @property
+    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):
+        # if self.unit == "":
+        #     return self.unit
+        exponent = -(int(f"{self.scale:.0e}".split("e")[1]) // 3) * 3
+        unit = f"{_EXP_UNIT_MAP[exponent]}{self.unit}"
+        return unit
+
+    @property
+    def symbol_and_value(self, latex=True):
+        sym = f"${self.symbol}$" if latex else self.symbol
+        equal = f"$=$" if latex else " = "
+        val = format_number(self.value, self.precision, self.unit, latex=latex)
+        return f"{sym}{equal}{val}"
+
+    def __str__(self):
+        """Return a JSON-formatted string of the object."""
+        return json.dumps(self.to_dict())
+
+    def __eq__(self, other):
+        if isinstance(other, ParamInfo):
+            return (self.id == other.id) & (self.value == other.value)
+        if isinstance(other, (int, float, complex, str)):
+            return self.value == other
+        return False
+
+    def __bool__(self):
+        return bool(self.id)
+
+
+ParamDict = dict[str, ParamInfo]
+
+
+def param_info_from_schema(key, metadata) -> ParamInfo:
+    metadata_id = metadata.get("param_id")
+    if metadata_id is not None:
+        return ParamInfo(metadata_id)
+    return ParamInfo(key, metadata=metadata)
+
+
+def enrich_qubit_params(qubit) -> ParamDict:
+    qubit_params = attrs.asdict(qubit.parameters)
+    res = {}
+    for key, value in qubit_params.items():
+        res[key] = ParamInfo(key, value)
+    return res
+
+
+def get_relevant_exp_parameters(
+    qubit_params: ParamDict, exp_param_ids: list, sweep_ids: list, only_keys=True
+):
+    # Filter out sweeps
+    filtered = [id for id in exp_param_ids if id not in sweep_ids]
+
+    # Filter special cases
+    # No external LO frequency => external Lo info is irrelevant
+    if (["readout_external_lo_frequency"] in exp_param_ids) and (
+        not qubit_params.get("readout_external_lo_frequency").value
+    ):
+        parms_to_exclude = [
+            "readout_external_lo_frequency",
+            "readout_external_lo_power",
+        ]
+        filtered = [id for id in filtered if id not in parms_to_exclude]
+
+    result = {key: value for key, value in qubit_params.items() if key in filtered}
+
+    return list(result.keys()) if only_keys else result