thd

Builtin index · Signal processing

result = thd(x)

Input: x · Output: result

What it is

x: a length-N real vector (the sampled record).

Overloads

One call shape — this function is not overloaded.

Code	Input	Output	Description
`result = thd(x)`	`x` vectornot documented yet	`result` number	Returns a single number, dB below the fundamental. Total harmonic distortion — every non-fundamental component counts, so a two-tone signal reads as distorted. See the full form under [ADC signal-quality metrics](#adc-signal-quality-metrics-thd-snr-sinad-sfdr-enob) above for the `tones=`/`freqs=`/`bins=`/`fs=`/`leak=` keyword options shared by this whole family.

Examples

From the documentation, and run by the build -- the output and the figure below are what the engine actually produced. Simplest first.

t = (0 to 999) / 1000
pure = sin(2 * pi * 31 * t)

clipped = distort(pure, "clip", 0.4)
soft = distort(pure, "soft", 0.4)
print("clip {thd(clipped):.1f} dB, soft {thd(soft):.1f} dB, below the fundamental")

output

clip -15.6 dB, soft -9.8 dB, below the fundamental

from noise

fs = 1000
n = 0:1:1023
t = n / fs
f0 = 99 * fs / 1024          # exactly 99 cycles in the record -- coherent sampling

clean = sin(2*pi*f0*t)
x = clean + 0.01 * sin(2*pi*3*f0*t) + 0.001 * randn(1024, seed=3)

r = sinad(x)     # full breakdown: r.sinad, r.enob, r.snr, r.thd, r.sfdr

print("THD  = {thd(x)} dB")
print("SNR  = {snr(x)} dB")
print("SINAD = {r.sinad} dB, ENOB = {r.enob} bits, SFDR = {sfdr(x)} dB")
print("ENOB (from thd/sinad breakdown) = {enob(x)} bits")

# closed-form estimates: what an ideal N-bit converter would show for a

# signal of a given crest factor, no record needed -- the number sinad(x)

# above is checked against. Signature is (bits, crest_factor).

est_sinad = sinad_estimate(12, sqrt(2))    # 12-bit ADC, sine-wave crest factor

est_enob  = enob_estimate(12, sqrt(2))
print("ideal 12-bit ADC: SINAD = {est_sinad} dB, ENOB = {est_enob} bits")

output

THD  = -39.98542 dB
SNR  = 56.858996 dB
SINAD = 39.897111 dB, ENOB = 6.335068 bits, SFDR = 39.986015 dB
ENOB (from thd/sinad breakdown) = 6.335068 bits
ideal 12-bit ADC: SINAD = 74 dB, ENOB = 12 bits

from signal-processing

How it works

Real-optimized half-spectrum FFT (NumPy/MATLAB rfft/irfft convention: a real signal's spectrum is Hermitian-symmetric, so only the non-negative-frequency half is returned/needed). sinad(x) / sinad(x, fs=, tones=, bins=, leak=) -- signal-to-noise-and-distortion of a sampled record, plus the SNR, THD, SFDR and ENOB that come with it. With no excitation named, the largest non-DC bin is taken as the fundamental: the single-tone case. Name the tones for a multisine, in Hz via tones= (with fs=) or directly as bin indices via bins= -- treating a multisine as one tone counts every other tone as noise and reads tens of dB low, which is the whole reason the excitation set is a parameter. leak= widens each tone by that many bins either side, for a record that is not exactly coherent. It defaults to 0 because widening hides close-in noise inside the signal and flatters the answer; that has to be the caller's decision.

From the note above this builtin in the interpreter, where the reasoning was written down as it was built.