File nprmeas_core.h¶

FileList > inc > nprmeas > nprmeas_core.h

NPRMeasure — notched-noise Noise Power Ratio. More...

#include "clib_common.h"
#include "jm_perf.h"
#include "measure/measure_core.h"
#include "psd/psd_core.h"
#include <complex.h>

Classes¶

Type	Name
struct	nprmeas_state_t NPRMeasure state: owned window, FFT plan and one-sided power scratch.

Public Functions¶

Type	Name
npr_meas_t	nprmeas_analyze (nprmeas_state_t * state, const float * x, size_t n_in, double active_lo, double active_hi, double notch_lo, double notch_hi, double guard_hz) NPR of a notched-noise capture.
nprmeas_state_t *	nprmeas_create (size_t n, double fs, double full_scale, size_t bits, double dynamic_range_db) Create an NPRMeasure analyser (auto Kaiser window).
void	nprmeas_destroy (nprmeas_state_t * state) Destroy an NPRMeasure analyser.
void	nprmeas_reset (nprmeas_state_t * state) Reset the analyser (a no-op: each analyze() call is independent).
size_t	nprmeas_spectrum_dbfs (nprmeas_state_t * state, const float * x, size_t x_len, float * out, size_t max_out) DC-centred dBFS magnitude spectrum of a capture (length nfft).
size_t	nprmeas_spectrum_dbfs_max_out (nprmeas_state_t * state) Capacity (== nfft) of the spectrum_dbfs output buffer.

Detailed Description¶

Drive the system with band-limited noise containing a deep notch; NPR is the ratio of the mean in-band noise PSD to the mean PSD that folds into the notch (distortion + quantisation + intermodulation). The band/notch geometry is an analyze() argument, so one estimator can sweep several notch placements.

Lifecycle: create -> [analyze]* -> destroy

Public Functions Documentation¶

function nprmeas_analyze¶

NPR of a notched-noise capture.

npr_meas_t nprmeas_analyze (
    nprmeas_state_t * state,
    const float * x,
    size_t n_in,
    double active_lo,
    double active_hi,
    double notch_lo,
    double notch_hi,
    double guard_hz
)

Parameters:

state The analyser.
x Real time-domain capture.
n_in Number of input samples.
active_lo Active noise band lower edge (Hz).
active_hi Active noise band upper edge (Hz).
notch_lo Notch lower edge (Hz).
notch_hi Notch upper edge (Hz).
guard_hz Keep-out around the notch edges (Hz).

Returns:

the NPR metric record (by value).

>>> from doppler.measure import NPRMeasure
>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> n = 1 << 15
>>> F = np.fft.rfft(rng.standard_normal(n))
>>> f = np.fft.rfftfreq(n)
>>> F[(f < 0.05) | (f > 0.45)] = 0  # band-limit to [0.05,0.45]
>>> F[(f >= 0.20) & (f <= 0.25)] *= 10**(-50/20)   # notch 50 dB deep
>>> x = np.fft.irfft(F, n)
>>> x = (0.3*x/np.std(x)).astype(np.float32)
>>> r = NPRMeasure(n=n, fs=1.0).analyze(
...     x, 0.05, 0.45, 0.20, 0.25, 0.01)
>>> 45 < r.npr_db < 55, r.notch_psd_dbfs < r.inband_psd_dbfs
(True, True)

function nprmeas_create¶

Create an NPRMeasure analyser (auto Kaiser window).

nprmeas_state_t * nprmeas_create (
    size_t n,
    double fs,
    double full_scale,
    size_t bits,
    double dynamic_range_db
)

The window is always Kaiser; its shape is auto-selected so the sidelobes sit below the requested dynamic range (see measure_resolve_dr()). The chosen window also sets a minimum notch keep-out so active-band noise cannot leak into the notch average through the window skirt.

Parameters:

n Capture/frame length (>= 2).
fs Sample rate (Hz, > 0).
full_scale Amplitude that equals 0 dBFS (> 0). Ignored if bits > 0.
bits ADC depth: bits>0 sets the 0-dBFS reference to 2^(bits-1) and, unless overridden, the dynamic-range target.
dynamic_range_db Explicit sidelobe/dynamic-range target (dB); used when > 0, else derived from bits.

Returns:

Heap state, or NULL on bad args / allocation failure.

function nprmeas_destroy¶

Destroy an NPRMeasure analyser.

void nprmeas_destroy (
    nprmeas_state_t * state
)

Parameters:

state May be NULL.

function nprmeas_reset¶

Reset the analyser (a no-op: each analyze() call is independent).

void nprmeas_reset (
    nprmeas_state_t * state
)

Every analyze() / spectrum_dbfs() call re-windows and re-transforms its own capture from scratch, so nothing is carried between calls to clear. The method exists only so NPRMeasure honours the same reset() contract as every other doppler object, letting a generic pipeline reset each stage uniformly.

Parameters:

state The analyser (left unchanged).

>>> from doppler.measure import NPRMeasure
>>> m = NPRMeasure(n=8192, fs=1.0)
>>> m.reset()            # stateless: provided only for API uniformity
>>> m.reset() is None    # returns nothing; safe to call anytime
True

function nprmeas_spectrum_dbfs¶

DC-centred dBFS magnitude spectrum of a capture (length nfft).

size_t nprmeas_spectrum_dbfs (
    nprmeas_state_t * state,
    const float * x,
    size_t x_len,
    float * out,
    size_t max_out
)

The same windowed, zero-padded PSD the NPR metrics are read off, laid out DC-centred (fftshifted) and normalised to dBFS for an analyzer-display backdrop. Use it to see the notch and the active band that analyze() integrates over.

Parameters:

state The analyser.
x Real time-domain capture (length x_len).
x_len Number of input samples.
out Destination buffer (length >= max_out).
max_out Capacity of out (== nfft).

Returns:

DC-centred dBFS magnitude spectrum, one value per FFT bin (nfft).

>>> from doppler.measure import NPRMeasure
>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> x = (0.3*rng.standard_normal(8192)).astype(np.float32)  # noise
>>> s = NPRMeasure(n=8192, fs=1.0).spectrum_dbfs(x)  # DC-centred dBFS
>>> s.shape                                          # zero-padded nfft
(16384,)
>>> round(float(np.median(s)), 0)   # broadband floor, below 0 dBFS
-48.0

function nprmeas_spectrum_dbfs_max_out¶

Capacity (== nfft) of the spectrum_dbfs output buffer.

size_t nprmeas_spectrum_dbfs_max_out (
    nprmeas_state_t * state
)

The documentation for this class was generated from the following file native/inc/nprmeas/nprmeas_core.h