Digital Output Analysis (dout)

The dout module provides tools for analyzing digital ADC outputs and bit-weighted architectures.

Weight Calibration

adctoolbox.calibrate_weight_sine(bits: ndarray | list[ndarray], freq: float | ndarray | None = None, force_search: bool = False, nominal_weights: ndarray | None = None, harmonic_order: int = 1, learning_rate: float = 0.5, reltol: float = 1e-12, max_iter: int = 100, verbose: int = 0) → dict[source]

FGCalSine — Foreground calibration using a sinewave input

This function estimates per-bit weights and a DC offset for an ADC by fitting the weighted sum of raw bit columns to a sine series at a given (or estimated) normalized frequency Fin/Fs. It optionally performs a coarse and fine frequency search to refine the input tone frequency.

Implementation uses a unified pipeline where single-dataset calibration is treated as a special case of multi-dataset calibration (N=1).

Parameters:

  • bits (ndarray or list of ndarrays) – Binary data as matrix (N rows by M cols, N is data points, M is bitwidth). Each row is one sample; each column is a bit/segment. Can also be a list of arrays for multi-dataset calibration.

  • freq (float, array-like, or None, optional) – Normalized frequency Fin/Fs. Default is None (triggers auto frequency search). - None: Automatic frequency search - float: Single frequency for all datasets - array-like: Per-dataset frequencies for multi-dataset mode

  • force_search (bool, optional) – Force fine frequency search even when frequency is provided. Default is False. Set to True to refine provided frequencies.

  • nominal_weights (array-like, optional) – Nominal bit weights (only effective when rank is deficient). Default is 2^(M-1) down to 2^0.

  • harmonic_order (int, optional) – Number of harmonic terms to exclude in calibration. Default is 1 (fundamental only, no harmonic exclusion). Higher values exclude more harmonics from the error term.

  • learning_rate (float, optional) – Adaptive learning rate for frequency updates (0..1), default is 0.5.

  • reltol (float, optional) – Relative error tolerance for convergence, default is 1e-12.

  • max_iter (int, optional) – Maximum iterations for fine frequency search, default is 100.

  • verbose (int, optional) – Print frequency search progress (1) or not (0), default is 0.

Returns:

Dictionary with keys: - weight : ndarray

The calibrated weights, normalized by the magnitude of sinewave.

  • offsetfloat

    The calibrated DC offset, normalized by the magnitude of sinewave.

  • calibrated_signalndarray or list of ndarrays

    The signal after calibration (single array for single dataset, list of arrays for multi-dataset).

  • idealndarray or list of ndarrays

    The best fitted sinewave (single array for single dataset, list of arrays for multi-dataset).

  • errorndarray or list of ndarrays

    The residue errors after calibration, excluding distortion (single array for single dataset, list of arrays for multi-dataset).

  • refined_frequencyfloat or ndarray

    The refined frequency from calibration (float for single dataset, array for multi-dataset).

Return type:

dict

Overflow Detection

Bit Activity

ENOB Analysis

adctoolbox.dout.analyze_enob_sweep(bits: ndarray, freq: float | None = None, harmonic_order: int = 1, osr: int = 1, win_type: str = 'hamming', create_plot: bool = True, ax=None, title: str | None = None, verbose: bool = False) → tuple[ndarray, ndarray][source]

Sweep ENOB vs number of bits used for calibration.

Incrementally adds bits (MSB to LSB) and measures ENOB after calibration to understand diminishing returns and optimal bit count.

Parameters:

  • bits (np.ndarray) – Binary matrix (N samples x M bits, MSB to LSB order)

  • freq (float, optional) – Normalized frequency (0-0.5). If None, auto-detect from data

  • harmonic_order (int, default=1) – Harmonic order for calibrate_weight_sine

  • osr (int, default=1) – Oversampling ratio for spectrum analysis

  • win_type (str, default='hamming') – Window function: ‘boxcar’, ‘hann’, ‘hamming’

  • create_plot (bool, default=True) – If True, plot ENOB sweep curve

  • ax (plt.Axes, optional) – Axes to plot on. If None, uses current axes (plt.gca())

  • title (str, optional) – Title for the plot. If None, uses default title

  • verbose (bool, default=False) – If True, print progress messages

Returns:

  • enob_sweep: ENOB for each bit count (length M)

  • n_bits_vec: Bit counts from 1 to M

Return type:

tuple[np.ndarray, np.ndarray]

Notes

What to look for in the plot: - Increasing trend: More bits improve resolution - Plateau: Additional bits don’t help (noise/distortion limited) - Decrease: Extra bits add noise/calibration errors

Visualization