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

sqil_core/utils/__init__.py

@@ -1,6 +1,63 @@
-from .analysis import *
-from .formatter import *
-from .read import *
+from ._analysis import (
+    compute_snr_peaked,
+    estimate_linear_background,
+    line_between_2_points,
+    linear_interpolation,
+    remove_linear_background,
+    remove_offset,
+)
+from ._const import ONE_TONE_PARAMS, TWO_TONE_PARAMS
+from ._formatter import (
+    format_number,
+    get_name_and_unit,
+    print_fit_metrics,
+    print_fit_params,
+)
+from ._plot import (
+    build_title,
+    get_x_id_by_plot_dim,
+    guess_plot_dimension,
+    reset_plot_style,
+    set_plot_style,
+)
+from ._read import (
+    ParamDict,
+    ParamInfo,
+    extract_h5_data,
+    get_measurement_id,
+    get_sweep_param,
+    read_json,
+    read_param_dict,
+)
 
-__all__ = []
-__all__.extend(name for name in dir() if not name.startswith("_"))
+__all__ = [
+    # Analysis
+    "remove_offset",
+    "estimate_linear_background",
+    "remove_linear_background",
+    "linear_interpolation",
+    "line_between_2_points",
+    "compute_snr_peaked",
+    # Const
+    "ONE_TONE_PARAMS",
+    "TWO_TONE_PARAMS",
+    # Formatter
+    "format_number",
+    "get_name_and_unit",
+    "print_fit_params",
+    "print_fit_metrics",
+    # Plot
+    "set_plot_style",
+    "reset_plot_style",
+    "get_x_id_by_plot_dim",
+    "build_title",
+    "guess_plot_dimension",
+    # Read
+    "extract_h5_data",
+    "read_json",
+    "ParamInfo",
+    "ParamDict",
+    "read_param_dict",
+    "get_sweep_param",
+    "get_measurement_id",
+]

sqil_core/utils/_analysis.py

@@ -0,0 +1,292 @@
+import numpy as np
+
+
+def remove_offset(data: np.ndarray, avg: int = 3) -> np.ndarray:
+    """Removes the initial offset from a data matrix or vector by subtracting
+    the average of the first `avg` points. After applying this function,
+    the first point of each column of the data will be shifted to (about) 0.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Input data, either a 1D vector or a 2D matrix
+    avg : int, optional
+        The number of initial points to average when calculating
+        the offset, by default 3
+
+    Returns
+    -------
+    np.ndarray
+       The input data with the offset removed
+    """
+    is1D = len(data.shape) == 1
+    if is1D:
+        return data - np.mean(data[0:avg])
+    return data - np.mean(data[:, 0:avg], axis=1).reshape(data.shape[0], 1)
+
+
+def estimate_linear_background(
+    x: np.ndarray,
+    data: np.ndarray,
+    points_cut: float = 0.1,
+    cut_from_back: bool = False,
+) -> list:
+    """
+    Estimates the linear background for a given data set by fitting a linear model to a subset of the data.
+
+    This function performs a linear regression to estimate the background (offset and slope) from the
+    given data by selecting a portion of the data as specified by the `points_cut` parameter. The linear
+    fit is applied to either the first or last `points_cut` fraction of the data, depending on the `cut_from_back`
+    flag. The estimated background is returned as the coefficients of the linear fit.
+
+    Parameters
+    ----------
+    x : np.ndarray
+        The independent variable data.
+    data : np.ndarray
+        The dependent variable data, which can be 1D or 2D (e.g., multiple measurements or data points).
+    points_cut : float, optional
+        The fraction of the data to be considered for the linear fit. Default is 0.1 (10% of the data).
+    cut_from_back : bool, optional
+        Whether to use the last `points_cut` fraction of the data (True) or the first fraction (False).
+        Default is False.
+
+    Returns
+    -------
+    list
+        The coefficients of the linear fit: a list with two elements, where the first is the offset (intercept)
+        and the second is the slope.
+
+    Notes
+    -----
+    - If `data` is 2D, the fit is performed on each column of the data separately.
+    - The function assumes that `x` and `data` have compatible shapes.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.linspace(0, 10, 100)
+    >>> data = 3 * x + 2 + np.random.normal(0, 1, size=(100,))
+    >>> coefficients = estimate_linear_background(x, data, points_cut=0.2)
+    >>> print("Estimated coefficients:", coefficients)
+    """
+    is1D = len(data.shape) == 1
+    points = data.shape[0] if is1D else data.shape[1]
+    cut = int(points * points_cut)
+
+    # Consider just the cut points
+    if not cut_from_back:
+        x_data = x[0:cut] if is1D else x[:, 0:cut]
+        y_data = data[0:cut] if is1D else data[:, 0:cut]
+    else:
+        x_data = x[-cut:] if is1D else x[:, -cut:]
+        y_data = data[-cut:] if is1D else data[:, -cut:]
+
+    ones_column = np.ones_like(x_data[0, :]) if not is1D else np.ones_like(x_data)
+    X = np.vstack([ones_column, x_data[0, :] if not is1D else x_data]).T
+    # Linear fit
+    coefficients, residuals, _, _ = np.linalg.lstsq(
+        X, y_data if is1D else y_data.T, rcond=None
+    )
+
+    return coefficients.T
+
+
+def remove_linear_background(
+    x: np.ndarray, data: np.ndarray, points_cut=0.1
+) -> np.ndarray:
+    """Removes a linear background from the input data (e.g. the phase background
+    of a spectroscopy).
+
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Input data. Can be a 1D vector or a 2D matrix.
+
+    Returns
+    -------
+    np.ndarray
+        The input data with the linear background removed. The shape of the
+        returned array matches the input `data`.
+    """
+    coefficients = estimate_linear_background(x, data, points_cut)
+
+    # Remove background over the whole array
+    is1D = len(data.shape) == 1
+    ones_column = np.ones_like(x[0, :]) if not is1D else np.ones_like(x)
+    X = np.vstack([ones_column, x[0, :] if not is1D else x]).T
+    return data - (X @ coefficients.T).T
+
+
+def linear_interpolation(
+    x: float | np.ndarray, x1: float, y1: float, x2: float, y2: float
+) -> float | np.ndarray:
+    """
+    Performs linear interpolation to estimate the value of y at a given x.
+
+    This function computes the interpolated y-value for a given x using two known points (x1, y1) and (x2, y2)
+    on a straight line. It supports both scalar and array inputs for x, enabling vectorized operations.
+
+    Parameters
+    ----------
+    x : float or np.ndarray
+        The x-coordinate(s) at which to interpolate.
+    x1 : float
+        The x-coordinate of the first known point.
+    y1 : float
+        The y-coordinate of the first known point.
+    x2 : float
+        The x-coordinate of the second known point.
+    y2 : float
+        The y-coordinate of the second known point.
+
+    Returns
+    -------
+    float or np.ndarray
+        The interpolated y-value(s) at x.
+
+    Notes
+    -----
+    - If x1 and x2 are the same, the function returns y1 to prevent division by zero.
+    - Assumes that x lies between x1 and x2 for meaningful interpolation.
+
+    Examples
+    --------
+    >>> linear_interpolation(3, 2, 4, 6, 8)
+    5.0
+    >>> x_vals = np.array([3, 4, 5])
+    >>> linear_interpolation(x_vals, 2, 4, 6, 8)
+    array([5., 6., 7.])
+    """
+    if x1 == x2:
+        return y1
+    return y1 + (x - x1) * (y2 - y1) / (x2 - x1)
+
+
+def line_between_2_points(
+    x1: float, y1: float, x2: float, y2: float
+) -> tuple[float, float]:
+    """
+    Computes the equation of a line passing through two points.
+
+    Given two points (x1, y1) and (x2, y2), this function returns the y-intercept and slope of the line
+    connecting them. If x1 and x2 are the same, the function returns y1 as the intercept and a slope of 0
+    to avoid division by zero.
+
+    Parameters
+    ----------
+    x1 : float
+        The x-coordinate of the first point.
+    y1 : float
+        The y-coordinate of the first point.
+    x2 : float
+        The x-coordinate of the second point.
+    y2 : float
+        The y-coordinate of the second point.
+
+    Returns
+    -------
+    tuple[float, float]
+        A tuple containing:
+        - The y-intercept (float), which is y1.
+        - The slope (float) of the line passing through the points.
+
+    Notes
+    -----
+    - If x1 and x2 are the same, the function assumes a vertical line and returns a slope of 0.
+    - The returned y-intercept is based on y1 for consistency in edge cases.
+
+    Examples
+    --------
+    >>> line_between_2_points(1, 2, 3, 4)
+    (2, 1.0)
+    >>> line_between_2_points(2, 5, 2, 10)
+    (5, 0)
+    """
+    if x1 == x2:
+        return np.inf, y1
+    slope = (y2 - y1) / (x2 - x1)
+    intercept = y1 - slope * x1
+    return slope, intercept
+
+
+def compute_snr_peaked(
+    x_data: np.ndarray,
+    y_data: np.ndarray,
+    x0: float,
+    fwhm: float,
+    noise_region_factor: float = 2.5,
+    min_points: int = 20,
+) -> float:
+    """
+    Computes the Signal-to-Noise Ratio (SNR) for a peaked function (e.g., Lorentzian, Gaussian)
+    based on the provided fit parameters. The SNR is calculated by comparing the signal strength
+    at the peak (x0) with the noise level estimated from a region outside the peak.
+
+    Parameters
+    ----------
+    x_data : np.ndarray
+        Array of x values (independent variable), typically representing frequency or position.
+
+    y_data : np.ndarray
+        Array of y values (dependent variable), representing the measured values (e.g., intensity, amplitude).
+
+    x0 : float
+        The location of the peak (center of the distribution), often the resonance frequency or peak position.
+
+    fwhm : float
+        The Full Width at Half Maximum (FWHM) of the peak. This defines the width of the peak and helps determine
+        the region for noise estimation.
+
+    noise_region_factor : float, optional, default=2.5
+        The factor used to define the width of the noise region as a multiple of the FWHM. The noise region is
+        considered outside the interval `(x0 - noise_region_factor * fwhm, x0 + noise_region_factor * fwhm)`.
+
+    min_points : int, optional, default=20
+        The minimum number of data points required in the noise region to estimate the noise level. If the number
+        of points in the noise region is smaller than this threshold, a warning is issued.
+
+    Returns
+    -------
+    float
+        The computed Signal-to-Noise Ratio (SNR), which is the ratio of the signal strength at `x0` to the
+        standard deviation of the noise. If the noise standard deviation is zero, the SNR is set to infinity.
+
+    Notes
+    -----
+    - The function assumes that the signal has a clear peak at `x0` and that the surrounding data represents noise.
+    - If the noise region contains fewer than `min_points` data points, a warning is raised suggesting the adjustment of `noise_region_factor`.
+
+    Example
+    -------
+    >>> x_data = np.linspace(-10, 10, 1000)
+    >>> y_data = np.exp(-(x_data**2))  # Example Gaussian
+    >>> x0 = 0
+    >>> fwhm = 2.0
+    >>> snr = compute_snr_peaked(x_data, y_data, x0, fwhm)
+    >>> print(snr)
+    """
+
+    # Signal strength at x0
+    signal = y_data[np.argmin(np.abs(x_data - x0))]
+
+    # Define noise region (outside noise_region_factor * FWHM)
+    noise_mask = (x_data < (x0 - noise_region_factor * fwhm)) | (
+        x_data > (x0 + noise_region_factor * fwhm)
+    )
+    noise_data = y_data[noise_mask]
+
+    # Check if there are enough data points for noise estimation
+    if len(noise_data) < min_points:
+        Warning(
+            f"Only {len(noise_data)} points found in the noise region. Consider reducing noise_region_factor."
+        )
+
+    # Compute noise standard deviation
+    noise_std = np.std(noise_data)
+
+    # Compute SNR
+    snr = signal / noise_std if noise_std > 0 else np.inf  # Avoid division by zero
+
+    return snr

sqil_core/utils/{const.py → _const.py}

@@ -1,38 +1,49 @@
-EXP_UNIT_MAP = {
-    -15: "p",
-    -12: "f",
-    -9: "n",
-    -6: "\mu",
-    -3: "m",
-    0: "",
-    3: "k",
-    6: "M",
-    9: "G",
-    12: "T",
-    15: "P",
-}
-
-PARAM_METADATA = {
-    "current": {"name": "Current", "symbol": "I", "unit": "A", "scale": 1e3},
-    "ro_freq": {
-        "name": "Readout frequency",
-        "symbol": "f_{RO}",
-        "unit": "Hz",
-        "scale": 1e-9,
-    },
-    "ro_power": {
-        "name": "Readout power",
-        "symbol": "P_{RO}",
-        "unit": "dBm",
-        "scale": 1,
-    },
-    "qu_freq": {
-        "name": "Qubit frequency",
-        "symbol": "f_q",
-        "unit": "Hz",
-        "scale": 1e-9,
-    },
-    "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},
-}
+import numpy as np
+
+_EXP_UNIT_MAP = {
+    -15: "p",
+    -12: "f",
+    -9: "n",
+    -6: r"\mu",
+    -3: "m",
+    0: "",
+    3: "k",
+    6: "M",
+    9: "G",
+    12: "T",
+    15: "P",
+}
+
+_PARAM_METADATA = {
+    "current": {"name": "Current", "symbol": "I", "unit": "A", "scale": 1e3},
+    "ro_freq": {
+        "name": "Readout frequency",
+        "symbol": "f_{RO}",
+        "unit": "Hz",
+        "scale": 1e-9,
+    },
+    "ro_power": {
+        "name": "Readout power",
+        "symbol": "P_{RO}",
+        "unit": "dBm",
+        "scale": 1,
+    },
+    "qu_freq": {
+        "name": "Qubit frequency",
+        "symbol": "f_q",
+        "unit": "Hz",
+        "scale": 1e-9,
+    },
+    "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"]
+)
+
+TWO_TONE_PARAMS = np.array(
+    ["ro_freq", "ro_power", "current", "vna_bw", "vna_avg", "qu_power"]
+)

sqil_core/utils/_formatter.py

@@ -0,0 +1,188 @@
+from decimal import ROUND_DOWN, Decimal
+
+import numpy as np
+from scipy.stats import norm
+from tabulate import tabulate
+
+from ._const import _EXP_UNIT_MAP, _PARAM_METADATA
+
+
+def _cut_to_significant_digits(number, n):
+    """Cut a number to n significant digits."""
+    if number == 0:
+        return 0  # Zero has no significant digits
+    d = Decimal(str(number))
+    shift = d.adjusted()  # Get the exponent of the number
+    rounded = d.scaleb(-shift).quantize(
+        Decimal("1e-{0}".format(n - 1)), rounding=ROUND_DOWN
+    )
+    return float(rounded.scaleb(shift))
+
+
+def format_number(
+    num: float | np.ndarray, precision: int = 3, unit: str = "", latex: bool = True
+) -> str:
+    """Format a number (or an array of numbers) in a nice way for printing.
+
+    Parameters
+    ----------
+    num : float | np.ndarray
+        Input number (or array). Should not be rescaled,
+        e.g. input values in Hz, NOT GHz
+    precision : int
+        The number of digits of the output number. Must be >= 3.
+    unit : str, optional
+        Unit of measurement, by default ''
+    latex : bool, optional
+        Include Latex syntax, by default True
+
+    Returns
+    -------
+    str
+        Formatted number
+    """
+    # Handle arrays
+    if isinstance(num, (list, np.ndarray)):
+        return [format_number(n, precision, unit, latex) for n in num]
+
+    # Return if not a number
+    if not isinstance(num, (int, float, complex)):
+        return num
+
+    # Format number
+    exp_form = f"{num:.12e}"
+    base, exponent = exp_form.split("e")
+    # Make exponent a multiple of 3
+    base = float(base) * 10 ** (int(exponent) % 3)
+    exponent = (int(exponent) // 3) * 3
+    # Apply precision to the base
+    if precision < 3:
+        precision = 3
+    base_precise = _cut_to_significant_digits(
+        base, precision + 1
+    )  # np.round(base, precision - (int(exponent) % 3))
+    base_precise = np.round(
+        base_precise, precision - len(str(base_precise).split(".")[0])
+    )
+    if int(base_precise) == float(base_precise):
+        base_precise = int(base_precise)
+
+    # Build string
+    if unit:
+        res = f"{base_precise}{'~' if latex else ' '}{_EXP_UNIT_MAP[exponent]}{unit}"
+    else:
+        res = f"{base_precise}" + (f" x 10^{{{exponent}}}" if exponent != 0 else "")
+    return f"${res}$" if latex else res
+
+
+def get_name_and_unit(param_id: str) -> str:
+    """Get the name and unit of measurement of a prameter, e.g. Frequency [GHz].
+
+    Parameters
+    ----------
+    param : str
+        Parameter ID, as defined in the param_dict.json file.
+
+    Returns
+    -------
+    str
+        Name and [unit]
+    """
+    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):
+    matrix = [param_names, params]
+
+    headers = ["Param", "Fitted value"]
+    if std_errs is not None:
+        headers.append("STD error")
+        std_errs = [f"{n:.3e}" for n in std_errs]
+        matrix.append(std_errs)
+    if perc_errs is not None:
+        headers.append("% Error")
+        perc_errs = [f"{n:.2f}" for n in perc_errs]
+        matrix.append(perc_errs)
+
+    matrix = np.array(matrix)
+    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}")
+
+
+def _sigma_for_confidence(confidence_level: float) -> float:
+    """
+    Calculates the sigma multiplier (z-score) for a given confidence level.
+
+    Parameters
+    ----------
+    confidence_level : float
+        The desired confidence level (e.g., 0.95 for 95%, 0.99 for 99%).
+
+    Returns
+    -------
+    float
+        The sigma multiplier to use for the confidence interval.
+    """
+    if not (0 < confidence_level < 1):
+        raise ValueError("Confidence level must be between 0 and 1 (exclusive).")
+
+    alpha = 1 - confidence_level
+    sigma_multiplier = norm.ppf(1 - alpha / 2)
+
+    return sigma_multiplier