Spectrum Analysis (spectrum)

The spectrum module provides FFT-based spectrum analysis tools.

Single-Tone Spectrum

adctoolbox.analyze_spectrum(data, fs=1.0, osr=1, max_scale_range=None, win_type='hann', side_bin=None, max_harmonic=5, nf_method=0, assumed_sig_pwr_dbfs=nan, coherent_averaging=False, create_plot: bool = True, show_title=True, show_label=True, plot_harmonics_up_to=3, ax=None)

Spectral analysis and plotting. (Wrapper function for modular core and plotting)

This function first calculates all metrics and then conditionally plots the spectrum.

For the Virtuoso/ADE-Explorer dark-theme stem plot variant, see analyze_spectrum_virtuoso (separate function with its own defaults — rectangular window, dark-theme plotter).

参数:

• data -- Input data (N,) or (M, N)

• fs -- Sampling frequency

• max_scale_range -- Full scale range for normalization. Can be: scalar (direct range), tuple/list [min, max], or None (auto-detect)

• win_type -- Window function type ('hann', 'hamming', 'boxcar')

• side_bin -- Number of side bins around fundamental. None triggers waveform-based auto detection in compute_spectrum; pass an explicit integer to force a fixed signal-lobe width.

• osr -- Oversampling ratio

• max_harmonic -- Number of harmonics for THD calculation

• nf_method -- Noise floor method (0=auto default, 1=median, 2=trimmed mean, 3=exclude, 4=legacy wide exclude)

• assumed_sig_pwr_dbfs -- Pre-defined signal level in dBFS

• create_plot -- Plot the spectrum (True) or not (False)

• show_title -- Display auto-generated title (True) or not (False)

• show_label -- Add labels and annotations (True) or not (False)

• plot_harmonics_up_to -- Number of harmonics to mark on the plot

• ax -- Optional matplotlib axes object. If None and create_plot=True, a new figure is created.

返回:

Dictionary with performance metrics:

• enob: Effective Number of Bits

• sndr_dbc: Signal-to-Noise and Distortion Ratio (dBc)

• sfdr_dbc: Spurious-Free Dynamic Range (dBc)

• snr_dbc: Signal-to-Noise Ratio (dBc)

• thd_dbc: Total Harmonic Distortion (dBc)

• sig_pwr_dbfs: Signal power (dBFS)

• noise_floor_dbfs: Noise floor (dBFS)

• nsd_dbfs_hz: Noise Spectral Density (dBFS/Hz)

返回类型:

dict

adctoolbox.analyze_spectrum_virtuoso(data, fs=1.0, osr=1, max_scale_range=None, win_type='rectangular', side_bin=None, max_harmonic=5, nf_method=0, assumed_sig_pwr_dbfs=nan, coherent_averaging=False, create_plot: bool = True, show_title=True, show_label=True, plot_harmonics_up_to=3, ax=None)

Same as analyze_spectrum, but defaults are tuned for Cadence Virtuoso / ADE-Explorer aesthetics:

• win_type defaults to 'rectangular' (one stem = one bin, no main-lobe smearing — matches what ADE Explorer renders by default).

• Plot rendered by plot_spectrum_virtuoso (black canvas, red stems, yellow/cyan annotation markers, fine dotted grid).

All other parameters and the returned metric dict are identical to analyze_spectrum. Pass win_type='hann' explicitly if you want Hann metrics with the Virtuoso plot style.

adctoolbox.extract_freq_components(din, bands)

Extract signal components within specified frequency bands.

参数:

• din (np.ndarray) -- Input data matrix (N x M or M x N). Must be real-valued.

• bands (np.ndarray) -- Frequency bands matrix (P x 2), each row [low_freq, high_freq]. Frequencies normalized: 0 = DC, 0.5 = Nyquist.

返回:

Output data with only components in specified bands.

返回类型:

np.ndarray

adctoolbox.quick_sndr(data, fs=1.0, win_type='hann', side_bin=None, max_scale_range=None)

SNDR + ENOB from a single 1-D capture (same SNDR definition as analyze_spectrum).

参数:

• data -- Time-domain samples, shape (N,)

• fs -- Sample rate (Hz)

• win_type -- Window name ('hann', 'rectangular', ...)

• side_bin -- Side bins around fundamental. None uses the window's coherent default fast path. "auto" uses waveform-based side-bin detection matching compute_spectrum(..., side_bin=None); this adds an extra ideal-tone FFT pass and assumes a dominant single-tone capture. For multi-tone, strongly distorted, or very noisy captures, pass an explicit integer.

• max_scale_range -- Optional full-scale range for input normalization

返回:

{'sndr_dbc': float, 'enob': float}

返回类型:

dict

adctoolbox.sweep_performance_vs_osr(data: ndarray, osr: ndarray | None = None, harmonic: int = 5, create_plot: bool = True, ax: Axes | None = None, logscale: bool = True, smooth: int | None = None) → dict

Sweep ADC performance metrics versus oversampling ratio.

参数:

• data (np.ndarray) -- Input signal (1D), typically ADC output samples.

• osr (np.ndarray, optional) -- OSR values to evaluate. Default: N/2 / (N/2, N/2-1, ..., 1).

• harmonic (int, default=5) -- Number of harmonics to mark on plot.

• create_plot (bool, default=True) -- If True, create performance plot(s).

• ax (plt.Axes, optional) -- Axes for main performance plot. If None and create_plot, creates 2-subplot figure (performance + slope).

• logscale (bool, default=True) -- Use logarithmic OSR axis, matching MATLAB perfosr default.

• smooth (int, optional) -- Half-width used for local SNDR slope estimation. Default matches the local MATLAB-style heuristic.

返回:

'osr': OSR values 'sndr': SNDR in dB at each OSR 'sfdr': Fast residual-spectrum single-bin SFDR estimate in dB at each OSR 'enob': ENOB in bits at each OSR

返回类型:

dict

adctoolbox.spectrum.compute_spectrum(data: ndarray, fs: float = 1.0, max_scale_range: float | list[float] | tuple[float | None | list[float]] = None, win_type: str = 'hann', side_bin: int | None = None, osr: int = 1, max_harmonic: int = 5, nf_method: int = 0, assumed_sig_pwr_dbfs: float | None = None, coherent_averaging: bool = False, cutoff_freq: float = 0, verbose: int = 0) → dict[str, ndarray | float | dict]

Calculate spectrum metrics aligned with MATLAB plotspec.m.

参数:

• data -- Input ADC data, shape (N,) or (M, N)

• fs -- Sampling frequency in Hz

• max_scale_range -- Full scale range for normalization

• win_type -- Window type: 'boxcar', 'hann', 'hamming', etc.

• side_bin -- Side bins around fundamental; None triggers auto detection

• osr -- Oversampling ratio

• max_harmonic -- Maximum harmonic order for THD (5 => H2..H5)

• nf_method -- 0=auto (default), 1=median, 2=trimmed mean, 3=exclude harmonics, 4=legacy wide harmonic exclusion

• assumed_sig_pwr_dbfs -- Override signal power in dBFS

• coherent_averaging -- Use coherent FFT averaging when True

• cutoff_freq -- High-pass cutoff in Hz

• verbose -- Verbosity level

adctoolbox.spectrum.plot_spectrum(compute_results, show_title=True, show_label=True, plot_harmonics_up_to=3, ax=None)

Pure spectrum plotting using pre-computed analysis results.

参数:

• compute_results -- Dictionary containing 'metrics' and 'plot_data' from compute_spectrum

• show_label -- Add labels and annotations (True) or not (False)

• plot_harmonics_up_to -- Number of harmonics to highlight

• show_title -- Display auto-generated title (True) or not (False)

• ax -- Optional matplotlib axes object

adctoolbox.spectrum.plot_spectrum_virtuoso(compute_results, show_title=True, show_label=True, plot_harmonics_up_to=3, ax=None, baseline_db=None)

Virtuoso/ADE-Explorer style spectrum plot with annotations.

参数:

• compute_results (dict) -- Output of compute_spectrum.

• show_title (bool) -- Show auto-generated plot title.

• show_label (bool) -- Add fundamental marker, spur marker, harmonics markers, and the metric text block. Set False for a bare-stem look.

• plot_harmonics_up_to (int) -- Highlight harmonics up to this order (HD2..HDk).

• ax (matplotlib.axes.Axes, optional) -- Target axes. If None, uses current axes. Axes + figure facecolor will be set to black.

• baseline_db (float, optional) -- Bottom of stem bars in dB. None → adaptive (min(spec) - 5).

Polar Spectrum Plots

adctoolbox.analyze_spectrum_polar(data: ndarray, max_code: float | None = None, harmonic: int = 5, osr: int = 1, cutoff_freq: float = 0, fs: float = 1.0, win_type: str = 'boxcar', create_plot: bool = True, ax=None, fixed_radial_range: float | None = None) → dict[str, Any]

Polar phase spectrum analysis and plotting. (Wrapper function for modular core and plotting)

This function calculates coherent spectrum with phase alignment and optionally plots it in polar format.

参数:

• data -- Input ADC data, shape (N,) or (M, N)

• max_code -- Maximum code level for normalization. If None, uses (max - min)

• harmonic -- Number of harmonics to mark on polar plot

• osr -- Oversampling ratio

• cutoff_freq -- High-pass cutoff frequency in Hz

• fs -- Sampling frequency in Hz

• win_type -- Window function type ('boxcar', 'hann', 'hamming')

• create_plot -- Plot the polar spectrum (True) or not (False)

• ax -- Optional matplotlib polar axes object. If None and create_plot=True, uses current axes.

• fixed_radial_range -- Fixed radial range in dB. If None, auto-scales.

返回:

Full results dictionary from compute_spectrum with coherent_averaging=True

返回类型:

dict

adctoolbox.spectrum.plot_spectrum_polar(analysis_results, show_metrics=True, harmonic=5, fixed_radial_range=None, ax=None)

Pure polar spectrum plotting using pre-computed coherent spectrum results.

参数:

• analysis_results -- Dictionary containing output from compute_spectrum(coherent_averaging=True)

• show_metrics -- Display metrics annotations (True) or not (False)

• harmonic -- Number of harmonics to mark on the plot

• fixed_radial_range -- Fixed radial range in dB. If None, auto-scales.

• ax -- Optional matplotlib polar axes object