adctoolbox 0.1.0__py3-none-any.whl

adctoolbox/__init__.py

@@ -0,0 +1,42 @@
+"""
+ADCToolbox: A comprehensive toolbox for ADC testing and characterization.
+
+This package provides tools for analyzing both analog and digital aspects of
+Analog-to-Digital Converters, including spectrum analysis, error characterization,
+calibration algorithms, and more.
+
+Submodules:
+-----------
+- common: Common utility functions (alias, find_bin, find_fin, sine_fit, etc.)
+- aout: Analog output / time-domain analysis (spectrum, error analysis, etc.)
+- dout: Digital output / code-level analysis (calibration, overflow detection, etc.)
+- oversampling: Oversampling and noise transfer function tools
+- utils: Utility functions and reporting tools
+- data_generation: Test data generation utilities
+
+Usage:
+------
+>>> from adctoolbox.aout import spec_plot
+>>> from adctoolbox.common import sine_fit
+>>> from adctoolbox.dout import fg_cal_sine
+"""
+
+__version__ = '0.1.0'
+
+# Expose submodules for convenience
+from . import common
+from . import aout
+from . import dout
+from . import oversampling
+from . import utils
+from . import data_generation
+
+__all__ = [
+    'common',
+    'aout',
+    'dout',
+    'oversampling',
+    'utils',
+    'data_generation',
+    '__version__',
+]

adctoolbox/aout/__init__.py

@@ -0,0 +1,23 @@
+"""Analog output (time-domain) analysis tools."""
+
+from .spec_plot import spec_plot
+from .spec_plot_phase import spec_plot_phase
+from .spec_plot_2tone import spec_plot_2tone
+from .err_envelope_spectrum import err_envelope_spectrum
+from .err_auto_correlation import err_auto_correlation
+from .err_hist_sine import err_hist_sine
+from .err_pdf import err_pdf
+from .tom_decomp import tom_decomp
+from .inl_sine import inl_sine
+
+__all__ = [
+    'spec_plot',
+    'spec_plot_phase',
+    'spec_plot_2tone',
+    'err_envelope_spectrum',
+    'err_auto_correlation',
+    'err_hist_sine',
+    'err_pdf',
+    'tom_decomp',
+    'inl_sine',
+]

adctoolbox/aout/err_auto_correlation.py

@@ -0,0 +1,58 @@
+import numpy as np
+import matplotlib.pyplot as plt
+
+
+def err_auto_correlation(err_data, MaxLag=100, Normalize=True):
+    """
+    Compute and plot autocorrelation function (ACF) of error signal.
+
+    Parameters:
+        err_data: Error signal (1D array)
+        MaxLag: Maximum lag in samples (default: 100)
+        Normalize: Normalize ACF so ACF[0] = 1 (default: True)
+
+    Returns:
+        acf: Autocorrelation values
+        lags: Lag indices (-MaxLag to +MaxLag)
+    """
+    fig = None
+    # Ensure column data
+    e = np.asarray(err_data).flatten()
+    N = len(e)
+
+    # Subtract mean
+    e = e - np.mean(e)
+
+    # Preallocate
+    lags = np.arange(-MaxLag, MaxLag + 1)
+    acf = np.zeros_like(lags, dtype=float)
+
+    # Compute autocorrelation manually (consistent with MATLAB implementation)
+    for k in range(len(lags)):
+        lag = lags[k]
+        if lag >= 0:
+            x1 = e[:N-lag] if lag > 0 else e
+            x2 = e[lag:N] if lag > 0 else e
+        else:
+            lag2 = -lag
+            x1 = e[lag2:N]
+            x2 = e[:N-lag2]
+        acf[k] = np.mean(x1 * x2)
+
+    # Normalize if required
+    if Normalize:
+        acf = acf / acf[lags == 0]
+
+    # Plot with larger fonts to match MATLAB
+    fig = plt.figure()
+    plt.plot(lags, acf, linewidth=2)
+    plt.grid(True)
+    plt.xlabel("Lag (samples)", fontsize=14)
+    plt.ylabel("Autocorrelation", fontsize=14)
+    plt.gca().tick_params(labelsize=14)
+
+    # Close figure to prevent memory leak
+    if fig is not None:
+        plt.close(fig)
+
+    return acf, lags

adctoolbox/aout/err_envelope_spectrum.py

@@ -0,0 +1,33 @@
+import numpy as np
+import matplotlib.pyplot as plt
+from scipy.signal import hilbert
+from .spec_plot import spec_plot
+
+
+def err_envelope_spectrum(err_data, Fs=1):
+    """
+    Compute envelope spectrum using Hilbert transform.
+
+    Parameters:
+        err_data: Error signal (1D array)
+        Fs: Sampling frequency (default: 1)
+
+    Returns:
+        None (generates plot via spec_plot)
+    """
+    # Ensure column data
+    e = np.asarray(err_data).flatten()
+
+    # Envelope extraction via Hilbert transform
+    env = np.abs(hilbert(e))
+
+    # Use spec_plot for spectrum analysis (spec_plot will handle closing its own figure)
+    spec_plot(env, Fs=Fs, label=0)
+
+    # Update labels with larger fonts to match MATLAB
+    plt.grid(True)
+    plt.xlabel("Frequency (Hz)", fontsize=14)
+    plt.ylabel("Envelope Spectrum (dB)", fontsize=14)
+    plt.gca().tick_params(labelsize=14)
+
+    # Note: spec_plot already closes its figure, so no need to close here

adctoolbox/aout/err_hist_sine.py

@@ -0,0 +1,274 @@
+"""
+Error histogram analysis for ADC output.
+
+Matches MATLAB errHistSine.m exactly for jitter detection.
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+
+def err_hist_sine(data, bin=100, fin=0, disp=1, mode=0, erange=None):
+    """
+    Error histogram analysis - matches MATLAB errHistSine.m exactly.
+
+    Args:
+        data: ADC output data (1D array)
+        bin: Number of bins (default: 100)
+        fin: Normalized frequency (0-1), 0 = auto detect (default: 0)
+        disp: Display plots (1=yes, 0=no) (default: 1)
+        mode: 0=phase domain, >=1=code domain (default: 0)
+        erange: Error range filter [min, max] (default: None)
+
+    Returns:
+        emean: Mean error per bin
+        erms: RMS error per bin
+        phase_code: Phase positions (deg) or code positions
+        anoi: Amplitude noise (reference noise)
+        pnoi: Phase noise (phase jitter in radians)
+        err: Raw error signal
+        xx: x-axis values corresponding to raw error
+    """
+    fig = None
+    # Ensure data is row vector
+    data = np.asarray(data).flatten()
+    N = len(data)
+
+    # Sine fit to get ideal signal and error
+    from ..common.sine_fit import sine_fit
+    if fin == 0:
+        data_fit, fin, mag, dc, phi = sine_fit(data)
+    else:
+        data_fit, _, mag, dc, phi = sine_fit(data, fin)
+
+    # MATLAB line 38: err = data_fit - data
+    err = data_fit - data
+
+    if mode >= 1:
+        # Code mode (not used for jitter detection)
+        xx = data
+        dat_min = np.min(data)
+        dat_max = np.max(data)
+        bin_wid = (dat_max - dat_min) / bin
+        phase_code = dat_min + np.arange(1, bin+1) * bin_wid - bin_wid/2
+
+        enum = np.zeros(bin)
+        esum = np.zeros(bin)
+        erms = np.zeros(bin)
+
+        for ii in range(N):
+            b = min(int(np.floor((data[ii] - dat_min) / bin_wid)), bin-1)
+            esum[b] += err[ii]
+            enum[b] += 1
+
+        enum = np.maximum(enum, 1)
+        emean = esum / enum
+
+        for ii in range(N):
+            b = min(int(np.floor((data[ii] - dat_min) / bin_wid)), bin-1)
+            erms[b] += (err[ii] - emean[b])**2
+
+        erms = np.sqrt(erms / enum)
+
+        anoi = np.nan
+        pnoi = np.nan
+
+        if erange is not None:
+            eid = (xx >= erange[0]) & (xx <= erange[1])
+            xx = xx[eid]
+            err = err[eid]
+
+        # Plotting for code mode
+        if disp:
+            fig = plt.figure(figsize=(10, 8))
+            ax1 = plt.subplot(2, 1, 1)
+            ax2 = plt.subplot(2, 1, 2)
+
+            ax1.plot(data, err, 'r.', markersize=2)
+            ax1.plot(phase_code, emean, 'b-', linewidth=2)
+            ax1.set_xlim([dat_min, dat_max])
+            ax1.set_ylim([np.min(err), np.max(err)])
+            ax1.set_ylabel('error')
+            ax1.set_xlabel('code')
+            ax1.grid(True, alpha=0.3)
+
+            if erange is not None:
+                ax1.plot(xx, err, 'm.', markersize=2)
+
+            ax2.bar(phase_code, erms, width=bin_wid*0.8, color='skyblue')
+            ax2.set_xlim([dat_min, dat_max])
+            ax2.set_ylim([0, np.max(erms)*1.1])
+            ax2.set_xlabel('code')
+            ax2.set_ylabel('RMS error')
+            ax2.grid(True, alpha=0.3)
+
+            plt.tight_layout()
+
+            # Close figure to prevent memory leak
+            if fig is not None:
+                plt.close(fig)
+
+    else:
+        # Phase mode (MATLAB lines 93-188) - THIS IS CRITICAL FOR JITTER DETECTION
+
+        # MATLAB line 94: xx = mod(phi/pi*180 + (0:length(data)-1)*fin*360,360);
+        xx = np.mod(phi/np.pi*180 + np.arange(N)*fin*360, 360)
+
+        # MATLAB line 95: phase_code = (0:bin-1)/bin*360;
+        phase_code = np.arange(bin) / bin * 360
+
+        enum = np.zeros(bin)
+        esum = np.zeros(bin)
+        erms = np.zeros(bin)
+
+        # MATLAB lines 101-105: binning
+        for ii in range(N):
+            # MATLAB line 102: b = mod(round(xx(ii)/360*bin),bin)+1;
+            b = int(np.mod(np.round(xx[ii]/360*bin), bin))
+            esum[b] += err[ii]
+            enum[b] += 1
+
+        # MATLAB line 106: emean = esum./enum (allows NaN for empty bins)
+        with np.errstate(divide='ignore', invalid='ignore'):
+            emean = esum / enum  # Will create NaN for empty bins (enum=0)
+
+        # MATLAB lines 107-111: RMS calculation
+        for ii in range(N):
+            b = int(np.mod(np.round(xx[ii]/360*bin), bin))
+            erms[b] += (err[ii] - emean[b])**2
+
+        # MATLAB line 111: erms = sqrt(erms./enum)
+        with np.errstate(divide='ignore', invalid='ignore'):
+            erms = np.sqrt(erms / enum)  # Will create NaN for empty bins
+
+        # ========== CRITICAL: Amplitude/Phase Noise Decomposition ==========
+        # MATLAB lines 114-147
+
+        # MATLAB line 114: asen = abs(cos(phase_code/360*2*pi)).^2;
+        asen = np.abs(np.cos(phase_code/360*2*np.pi))**2
+
+        # MATLAB line 115: psen = abs(sin(phase_code/360*2*pi)).^2;
+        psen = np.abs(np.sin(phase_code/360*2*np.pi))**2
+
+        # MATLAB line 117: tmp = linsolve([asen',psen',ones(bin,1)], erms'.^2);
+        # Filter out NaN values (empty bins) before least squares fit
+        valid_mask = ~np.isnan(erms)
+        A = np.column_stack([asen[valid_mask], psen[valid_mask], np.ones(np.sum(valid_mask))])
+        b_vec = erms[valid_mask]**2
+
+        # Use non-negative least squares to ensure non-negative variance components
+        # This avoids numerical issues with rank-deficient systems (asen + psen = 1)
+        try:
+            from scipy.optimize import nnls
+            tmp, _ = nnls(A, b_vec)
+        except ImportError:
+            # Fallback to pseudoinverse if scipy not available
+            tmp = np.linalg.pinv(A) @ b_vec
+
+        # MATLAB line 119-121
+        anoi = np.sqrt(tmp[0]) if tmp[0] >= 0 else 0
+        pnoi = np.sqrt(tmp[1]) / mag if tmp[1] >= 0 else 0
+        ermsbl = tmp[2]
+
+        # Handle edge cases where fit failed
+        if not np.isfinite(anoi):
+            anoi = 0
+        if not np.isfinite(pnoi):
+            pnoi = 0
+
+        # Filter error range if specified
+        if erange is not None:
+            eid = (xx >= erange[0]) & (xx <= erange[1])
+            xx = xx[eid]
+            err = err[eid]
+
+        # Plotting for phase mode
+        if disp:
+            fig = plt.figure(figsize=(10, 8))
+            ax1 = plt.subplot(2, 1, 1)
+            ax2 = plt.subplot(2, 1, 2)
+
+            # Top subplot: data and error vs phase
+            ax1_left = ax1
+            ax1_left.plot(xx, data, 'k.', markersize=2, label='data')
+            ax1_left.set_xlim([0, 360])
+            ax1_left.set_ylim([np.min(data), np.max(data)])
+            ax1_left.set_ylabel('data', color='k')
+            ax1_left.tick_params(axis='y', labelcolor='k')
+
+            ax1_right = ax1.twinx()
+            ax1_right.plot(xx, err, 'r.', markersize=2, alpha=0.5)
+            ax1_right.plot(phase_code, emean, 'b-', linewidth=2, label='error')
+            ax1_right.set_xlim([0, 360])
+            ax1_right.set_ylim([np.min(err), np.max(err)])
+            ax1_right.set_ylabel('error', color='r')
+            ax1_right.tick_params(axis='y', labelcolor='r')
+
+            ax1.legend(['data', 'error'], loc='upper right')
+            ax1.set_xlabel('phase(deg)')
+            ax1.grid(True, alpha=0.3)
+
+            if erange is not None:
+                ax1_right.plot(xx, err, 'm.', markersize=2)
+
+            # Bottom subplot: RMS error with fitted curves
+            ax2.bar(phase_code, erms, width=360/bin*0.8, color='skyblue', alpha=0.7)
+            ax2.plot(phase_code, np.sqrt(anoi**2 * asen + ermsbl), 'b-', linewidth=2)
+            ax2.plot(phase_code, np.sqrt(pnoi**2 * psen * mag**2 + ermsbl), 'r-', linewidth=2)
+            ax2.set_xlim([0, 360])
+            ax2.set_ylim([0, np.max(erms)*1.2])
+
+            # Add text labels (MATLAB lines 183-184)
+            ax2.text(10, np.max(erms)*1.15,
+                    f'Normalized Amplitude Noise RMS = {anoi/mag:.2e}',
+                    color='b', fontsize=10)
+            ax2.text(10, np.max(erms)*1.05,
+                    f'Phase Noise RMS = {pnoi:.2e} rad',
+                    color='r', fontsize=10)
+
+            ax2.set_xlabel('phase(deg)')
+            ax2.set_ylabel('RMS error')
+            ax2.grid(True, alpha=0.3)
+
+            plt.tight_layout()
+
+            # Close figure to prevent memory leak
+            if fig is not None:
+                plt.close(fig)
+
+    return emean, erms, phase_code, anoi, pnoi, err, xx
+
+
+if __name__ == "__main__":
+    import os
+
+    # Test with jitter
+    N = 2**14
+    Fs = 10e9
+    Fin = 200e6
+    J = int(np.round(Fin / Fs * N))
+    fin_norm = J / N
+    Fin_actual = J / N * Fs
+
+    # Generate jittered signal
+    Tj = 100e-15  # 100 fs jitter
+    phase_noise_rms = 2 * np.pi * Fin_actual * Tj
+
+    Ts = 1 / Fs
+    theta = 2 * np.pi * Fin_actual * np.arange(N) * Ts
+    phase_jitter = np.random.randn(N) * phase_noise_rms
+
+    data = np.sin(theta + phase_jitter) * 0.49 + 0.5 + np.random.randn(N) * 0.00001
+
+    print(f"[Test] [Set jitter] = {Tj*1e15:.2f} fs")
+
+    # Test errHistSine
+    emean, erms, phase_code, anoi, pnoi, err, xx = errHistSine(data, bin=99, fin=fin_norm, disp=0)
+
+    # Convert pnoi to jitter (MATLAB line 47)
+    jitter_calc = pnoi / (2 * np.pi * Fin_actual)
+
+    print(f"[Test] [Calculated jitter] = {jitter_calc*1e15:.2f} fs")
+    print(f"[Test] [anoi] = {anoi:.6e}")
+    print(f"[Test] [pnoi] = {pnoi:.6e} rad")
+    print(f"[Test] [Ratio] = {jitter_calc/Tj:.2f}")

adctoolbox/aout/err_pdf.py

@@ -0,0 +1,74 @@
+import numpy as np
+import matplotlib.pyplot as plt
+
+
+def err_pdf(err_data, Resolution=12, FullScale=1):
+    """
+    Compute error probability density function using Kernel Density Estimation (KDE).
+
+    Parameters:
+        err_data: Error signal (1D array)
+        Resolution: ADC resolution in bits (default: 12)
+        FullScale: Full-scale range (default: 1)
+
+    Returns:
+        noise_lsb: Error in LSB units (1D array)
+        mu: Mean of error distribution
+        sigma: Standard deviation of error distribution
+        KL_divergence: KL divergence from Gaussian distribution
+        x: Sample points for PDF
+        fx: KDE-estimated PDF values
+        gauss_pdf: Fitted Gaussian PDF values
+    """
+    fig = None
+    # Convert error to LSB units
+    lsb = FullScale / (2**Resolution)
+    noise_lsb = np.asarray(err_data).flatten() / lsb
+    n = noise_lsb
+    N = len(n)
+
+    # Silverman's rule for bandwidth
+    h = 1.06 * np.std(n) * N**(-1/5)
+
+    # Determine x-axis range
+    max_abs_noise = np.max(np.abs(n))
+    xlim_range = max(0.5, max_abs_noise)
+    x = np.linspace(-xlim_range, xlim_range, 200)
+    fx = np.zeros_like(x)
+
+    # KDE computation (manual implementation for consistency with MATLAB)
+    for i in range(len(x)):
+        u = (x[i] - n) / h
+        fx[i] = np.mean(np.exp(-0.5 * u**2)) / (h * np.sqrt(2*np.pi))
+
+    # Gaussian fit
+    mu = np.mean(n)
+    sigma = np.std(n)
+    gauss_pdf = (1/(sigma*np.sqrt(2*np.pi))) * np.exp(-(x - mu)**2 / (2*sigma**2))
+
+    # KL divergence calculation
+    dx = x[1] - x[0]
+    p = fx + np.finfo(float).eps
+    q = gauss_pdf + np.finfo(float).eps
+    KL_divergence = np.sum(p * np.log(p / q)) * dx
+
+    # Plotting with larger fonts to match MATLAB
+    fig = plt.figure()
+    plt.plot(x, fx, linewidth=2, label='KDE Estimate')
+    label_str = f"Gaussian Fit (KL = {KL_divergence:.4f}, μ={mu:.2f}, σ={sigma:.2f})"
+    plt.plot(x, gauss_pdf, '--r', linewidth=2, label=label_str)
+    plt.xlabel("Noise (LSB)", fontsize=18)
+    plt.ylabel("PDF", fontsize=18)
+    plt.legend(loc="upper left", fontsize=18)
+    plt.grid(True)
+
+    # Set y-axis limits
+    y_max = max(np.max(fx), np.max(gauss_pdf)) * 1.3
+    plt.ylim([0, y_max])
+    plt.gca().tick_params(labelsize=18)
+
+    # Close figure to prevent memory leak
+    if fig is not None:
+        plt.close(fig)
+
+    return noise_lsb, mu, sigma, KL_divergence, x, fx, gauss_pdf

adctoolbox/aout/inl_sine.py

@@ -0,0 +1,111 @@
+import numpy as np
+
+def inl_sine(data, clip=0.01):
+    """
+    Calculate ADC INL (Integral Nonlinearity) and DNL (Differential Nonlinearity) using sine histogram method
+
+    This function estimates INL and DNL by applying an arccosine transform to the histogram
+    of ADC output data. The basic principle: for an ideal sinusoidal input, the cumulative
+    distribution function (CDF) of ADC output codes should follow an arcsine function.
+    By applying an arccosine transform to the cumulative histogram, we obtain the ideal
+    linear code distribution, allowing calculation of nonlinearity errors.
+
+    Parameters
+    ----------
+    data : ndarray
+        ADC output data (1D array)
+    clip : float, optional
+        Clipping ratio to exclude outliers at data edges, default is 0.01 (1%)
+
+    Returns
+    -------
+    INL : ndarray
+        Integral nonlinearity error (in LSB units)
+    DNL : ndarray
+        Differential nonlinearity error (in LSB units)
+    code : ndarray
+        Corresponding output code values
+
+    Notes
+    -----
+    INL represents the maximum deviation of the actual transfer characteristic from the ideal line
+    DNL represents the deviation of adjacent code step sizes from the ideal step size (1 LSB)
+    """
+    
+    # Ensure data is a column vector (transpose if needed)
+    data = np.asarray(data)
+    if data.ndim == 1:
+        data = data.reshape(-1, 1)
+
+    S = data.shape
+    if S[0] < S[1]:  # If rows < columns, transpose
+        data = data.T
+
+    # Flatten to 1D array
+    data = data.flatten()
+
+    # Calculate data range and apply clipping
+    # Clipping excludes data points in the saturation region, which cause statistical bias
+    max_data = np.ceil(np.max(data))
+    min_data = np.floor(np.min(data))
+
+    # Clip both ends of the data range by clip ratio
+    max_data = round(max_data - clip * (max_data - min_data) / 2)
+    min_data = round(min_data + clip * (max_data - min_data) / 2)
+
+    # Generate code value range
+    code = np.arange(min_data, max_data + 1)
+
+    # Restrict data to clipped range
+    data = np.clip(data, min_data, max_data)
+
+    # Calculate histogram - count occurrences of each code
+    # DCC: Digital Code Count, count for each code
+    # MATLAB's hist(data, code) uses code values as bin centers
+    # For consecutive integers, bins are [code[i]-0.5, code[i]+0.5)
+    bins = np.append(code - 0.5, code[-1] + 0.5)
+    DCC, _ = np.histogram(data, bins=bins)
+
+    # Calculate cumulative distribution function (CDF) and apply arccosine transform
+    # Theory: for ideal sine wave, CDF should follow arcsine function
+    # Use -cos(π * CDF) transform to linearize it
+    # cumsum(DCC)/sum(DCC) calculates normalized CDF (range 0 to 1)
+    cumulative_prob = np.cumsum(DCC) / np.sum(DCC)
+    DCC = -np.cos(np.pi * cumulative_prob)
+
+    # Calculate differential: difference between adjacent codes
+    # DNL is the deviation of each code step size from ideal 1 LSB
+    DNL = DCC[1:] - DCC[:-1]
+
+    # Update code range (differential reduces by one point)
+    code = code[:-1]
+
+    # Apply edge clipping again to DNL and code values
+    # This excludes edge effects, as statistics at edges may be inaccurate
+    clip_points = int(np.floor(clip * (max_data - min_data + 1) / 2))
+
+    if clip_points > 0:
+        code = code[clip_points:-clip_points]
+        DNL = DNL[clip_points:-clip_points]
+
+    # DNL normalization processing
+    # 1. First normalize so sum equals 1 (probability normalization)
+    DNL = DNL / np.sum(DNL)
+
+    # 2. Scale to actual code range (in LSB units)
+    # Ideally, each code step size should be 1 LSB
+    num_codes = max_data - min_data - clip_points * 2 + 1
+    DNL = DNL * num_codes - 1
+
+    # 3. Remove mean (removes gain error influence)
+    # This way DNL reflects only nonlinearity, excluding overall gain error
+    DNL = DNL - np.mean(DNL)
+
+    # Calculate INL: cumulative sum of DNL
+    # INL represents deviation of each code point from ideal line
+    # Obtained by integrating (accumulating) DNL
+    INL = np.cumsum(DNL)
+
+    return INL, DNL, code
+
+