mp-dsp-python

Python integration layer for the mixed-precision-dsp C++ library, providing nanobind bindings, matplotlib visualizations, and Jupyter notebooks for the full DSP domain.

Why

The mixed-precision-dsp library is a C++20 header-only DSP library covering signals, windows, quantization, IIR/FIR filtering, spectral analysis, signal conditioning, estimation (Kalman/LMS/RLS), image processing, and numerical analysis — all parameterized on arithmetic type for mixed-precision research.

DSP researchers work in Python. Jupyter notebooks, matplotlib, SciPy, and NumPy are the standard tools for prototyping, analysis, and publication-quality visualization. This repository bridges the gap: C++ does the mixed-precision math across the full DSP domain; Python orchestrates experiments and presents results.

Without this layer, every mixed-precision experiment requires writing a C++ application, exporting CSV, and hand-crafting plotting scripts. With mp-dsp-python, the entire sw::dsp library is accessible from a single import mpdsp statement.

import mpdsp
import numpy as np
import matplotlib.pyplot as plt

# Signal generation
signal = mpdsp.sine(length=2000, frequency=440, sample_rate=44100)
noise = mpdsp.gaussian_noise(length=2000, stddev=0.1)
noisy = signal + noise

# Windowing
window = mpdsp.hamming(2000)
windowed = noisy * window

# Spectral analysis
freqs, psd = mpdsp.psd(windowed, sample_rate=44100)
plt.semilogy(freqs, psd)

# IIR filtering with mixed precision
filt = mpdsp.butterworth_lowpass(order=4, sample_rate=44100, cutoff=1000)
ref    = filt.process(signal, dtype="reference")      # double/double/double
posit  = filt.process(signal, dtype="posit_full")      # double/posit<32,2>/posit<16,1>
print(f"SQNR: {mpdsp.sqnr_db(ref, posit):.1f} dB")

# Image processing
img = mpdsp.checkerboard(256, 256, block_size=8)
edges = mpdsp.canny(img, low_threshold=0.1, high_threshold=0.3, sigma=1.0)
mpdsp.write_pgm("edges.pgm", edges)

# Estimation
kf = mpdsp.KalmanFilter(state_dim=2, meas_dim=1)
# ... configure and run

# Analysis
margin = filt.stability_margin()
poles = filt.poles()
sensitivity = filt.worst_case_sensitivity()

What

Full DSP Domain Coverage

mp-dsp-python exposes every module of the C++ library to Python. The 2026-08-02 bindings-gap roadmap (epic #100) closed 18 sub-issues across 5 phases, bringing coverage from ~65% to ~93% of the v0.6.0 surface — see docs/gap_analysis_2026-08-02.md for the module-by-module state. For the complete enumeration of every public name with signatures and one-line descriptions, see docs/api_reference.md.

Mixed-Precision Type Dispatch

Every processing function that operates on data accepts a dtype parameter selecting the arithmetic configuration. Python never sees C++ template types — it passes a string key and gets back float64 NumPy arrays.

# Same API, different arithmetic — IIR/FIR filters
result_f32  = filt.process(signal, dtype="gpu_baseline")    # float state+sample
result_p16  = filt.process(signal, dtype="posit_full")      # posit<32,2> / posit<16,1>
result_half = filt.process(signal, dtype="half")            # cfloat<16,5> throughout

# Image processing — convolve2d, separable_filter, gaussian_blur,
# box_blur, sobel_x/y, prewitt_x/y, gradient_magnitude, canny, rgb_to_gray
edges_ref = mpdsp.canny(img, 0.1, 0.3, dtype="reference")
edges_p8  = mpdsp.canny(img, 0.1, 0.3, dtype="tiny_posit")

# Quantization — adc, measure_sqnr_db
quantized = mpdsp.adc(signal, dtype="half")

# Conditioning — PeakEnvelope, RMSEnvelope, Compressor, AGC
comp = mpdsp.Compressor(sample_rate=44100, threshold_db=-12.0, ratio=4.0,
                        attack_ms=5.0, release_ms=50.0, dtype="posit_full")

# Estimation — KalmanFilter, LMSFilter, NLMSFilter, RLSFilter
kf = mpdsp.KalmanFilter(2, 1, dtype="cf24")

Spectral primitives (fft, ifft, psd, welch, periodogram, spectrogram) all accept dtype=; inputs and outputs stay double/ complex128 at the Python layer while the internal arithmetic runs at the selected precision. Signal generators are intentionally reference- precision (they aren't part of a mixed-precision datapath). Window functions accept dtype= for cases where the window itself is part of a precision study.

Pre-Instantiated Configurations

Posit taxonomy grid — posit<N, es> single-type configs for N ∈ {8, 16, 32}, es ∈ {0, 1, 2}. All three scalars (coefficient, state, sample) use the same posit type, so these cells cleanly compare ES-vs-precision tradeoff at fixed bit width:

Query the live set at runtime with mpdsp.available_dtypes() (18 entries). Sample-scalar bit width per config is available via mpdsp.bits_of(dtype) — useful for labeling the x-axis of precision-vs-cost plots. For posit grid cells the ES dimension doesn't affect bit width, so every posit_N_* reports N; plotting a full sweep gives 3 points stacked vertically at each width showing ES's effect on SQNR.

Coefficients are designed in double by default — design-time precision is what keeps an IIR cascade well-conditioned (see the educational guide). The classical IIR families (Butterworth, Chebyshev, Bessel, Legendre, Elliptic) design in double unconditionally; dtype= on those filters selects the processing path only.

The designers that do expose a coeff_dtype= knob — the seven rbj_* biquads and the FIR/Remez designers — offer it to measure what design-time precision costs, not to recommend spending it. The result is still stored in double, so the knob isolates the arithmetic used to compute the coefficients from the arithmetic used to hold them. Its dual is IIRFilter.pole_displacement(dtype), which quantizes an already-designed cascade: coeff_dtype asks what computing in T costs, pole_displacement asks what storing in T costs.

For algorithms that don't have a design/runtime split (FFT, convolution, Kalman), all three scalars use the target configuration.

Visualization Toolkit

Beyond bindings, mp-dsp-python provides matplotlib helpers and Jupyter notebooks tailored to mixed-precision DSP research:

Interactive Filter Designer

A Streamlit dashboard at scripts/plot_dashboard.py exposes every IIR family (Butterworth, Chebyshev I/II, Bessel, Legendre, Elliptic, RBJ biquads) with live magnitude/phase plots, pole-zero diagrams, impulse and step response, and a side-by-side mixed-precision comparison across all 7 arithmetic configurations — modeled on Vinnie Falco's classic DSPFilters demo, with the mixed-precision angle that is the whole point of this library.

pip install mpdsp[dashboard]
streamlit run scripts/plot_dashboard.py

Full walkthrough (install paths for local / SSH-tunnel / LAN, tab-by-tab tour, mixed-precision interpretation guide, export conventions) in docs/dashboard.md.

How

Repository Structure

mp-dsp-python/
├── CMakeLists.txt                  # nanobind + sw::dsp + Universal + MTL5
├── src/
│   ├── bindings.cpp                # nanobind module definition
│   ├── types.hpp                   # ArithConfig enum + dispatch table
│   ├── types_bindings.cpp          # TransferFunction, structured biquad types
│   ├── _binding_helpers.hpp        # Shared marshalling + dispatch helpers
│   ├── BINDING_PATTERNS.md         # Contributor notes on binding conventions
│   ├── signal_bindings.cpp         # signals + windows + WAV I/O
│   ├── filter_bindings.cpp         # IIR/FIR design, filtfilt, remez, overlap
│   ├── spectral_bindings.cpp      # FFT, PSD, welch, spectrogram
│   ├── spectrum_bindings.cpp      # analyzer stack (RealtimeSpectrum, RBW/VBW, ...)
│   ├── conditioning_bindings.cpp  # envelope, compressor, AGC, RationalResampler
│   ├── estimation_bindings.cpp    # Kalman + EKF + UKF + LMS/NLMS/RLS
│   ├── acquisition_bindings.cpp   # NCO, CIC, halfband, polyphase
│   ├── instrument_bindings.cpp    # scope measurements, PeakDetectDecimator, TriggerRingBuffer
│   ├── image_bindings.cpp         # 2D convolution, morphology, edge
│   ├── quantization_bindings.cpp  # ADC/DAC, dither, SQNR
│   ├── analysis_bindings.cpp      # stability, sensitivity, condition, acquisition-precision
│   └── math_bindings.cpp          # polynomial, quadratic, elliptic_K, RootFinder
├── python/
│   └── mpdsp/
│       ├── __init__.py             # Public API surface
│       ├── filters.py              # Pythonic filter wrapper classes
│       ├── estimation.py           # Kalman/adaptive filter wrappers
│       ├── image.py                # Image processing helpers
│       ├── analysis.py             # Analysis helpers
│       ├── plotting.py             # matplotlib convenience functions
│       └── io.py                   # File I/O + CSV import
├── notebooks/
│   ├── 02_iir_precision.ipynb          # Mixed-precision IIR comparison
│   ├── 03_fir_and_windows.ipynb        # FIR design, window functions
│   ├── 04_interactive_precision.ipynb  # Interactive precision sweep
│   ├── 05_conditioning.ipynb           # Envelope, compression, AGC
│   ├── 06_estimation.ipynb             # Kalman tracking, LMS adaptive
│   ├── 07_image_processing.ipynb       # 2D filtering, edge detection
│   ├── 08_sensor_noise.ipynb           # Sensor noise precision analysis
│   └── 09_numerical_analysis.ipynb     # Stability, sensitivity, condition
├── scripts/
│   ├── plot_precision.py           # Magnitude/phase from CSV
│   ├── plot_heatmap.py             # SQNR heatmap from CSV
│   ├── plot_pole_zero.py           # Pole-zero on unit circle
│   └── plot_dashboard.py           # Streamlit interactive dashboard
├── tests/                          # 16 test files, ~1250 tests
│   ├── test_signals.py             # generators + windows (bundled)
│   ├── test_filters.py             # IIR + FIR + Remez + Overlap + filtfilt
│   ├── test_spectral.py            # FFT, PSD, welch, spectrogram
│   ├── test_spectrum.py            # analyzer stack (RealtimeSpectrum, RBW/VBW, ...)
│   ├── test_conditioning.py        # envelope, AGC, RationalResampler
│   ├── test_estimation.py          # Kalman + EKF + UKF + adaptive
│   ├── test_acquisition.py         # NCO, CIC, halfband, polyphase
│   ├── test_instrument.py          # scope measurements + capture primitives
│   ├── test_analysis.py            # stability, sensitivity, acquisition-precision
│   ├── test_math.py                # polynomial, quadratic, RootFinder, elliptic_K
│   ├── test_types.py               # TransferFunction + structured biquad types
│   ├── test_image.py               # image processing
│   ├── test_quantization.py        # ADC/DAC, dither, SQNR
│   ├── test_io.py                  # WAV/PGM/PPM/BMP round-trips
│   ├── test_scripts.py             # CSV-plotting script smoke tests
│   └── test_version.py             # version lockstep check
├── docs/
│   ├── api_reference.md
│   ├── dashboard.md
│   ├── publishing.md
│   ├── gap_analysis_2026-08-01.md  # Pre-roadmap coverage snapshot
│   └── gap_analysis_2026-08-02.md  # Post-roadmap coverage snapshot
└── README.md

Build

# Prerequisites: Python 3.9+, CMake 3.22+, C++20 compiler
pip install nanobind numpy matplotlib

# Build the C++ extension module
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

# Install in development mode
pip install -e .

The build system resolves mixed-precision-dsp, Universal, and MTL5 in this order:

1. Sibling clone — if a checkout exists at ../mixed-precision-dsp, ../universal, or ../mtl5, it is used directly. This is the recommended workflow when iterating across the C++ stack and the Python bindings together.
2. find_package — MTL5 only; checks for an installed package config.
3. FetchContent — pulled from GitHub at the pin tags below. Used by cibuildwheel and any other environment without local siblings.

Minimum versions enforced at configure time on the sibling-clone path (stale checkouts abort with a clear error and the git checkout command needed to fix them):

Note: the MTL5 floor was bumped from 5.2.1 → 5.7.0 in 2026-08-02 as prep for UnscentedKalmanFilter, which uses mtl::ldlt_factor (landed in MTL5 v5.3.0). Jumping straight to the latest 5.x release keeps the project on current upstream.

Only the DSP pin is constrained to lag the floor during a development cycle: it moves in lockstep with project(VERSION) (see tests/test_version.py::test_lockstep_prefix) and only advances at release time. The universal and mtl5 pins are free to track the floor — keeping them current avoids CI building in a configuration strictly weaker than what sibling-path devs require.

Override at configure time with -DMPDSP_REQUIRED_DSP_VERSION=... (lower the floor for experimentation) or -DMPDSP_DSP_PIN=main (build against an unreleased upstream).

Quick Start: CSV Plotting (No Build Required)

The plotting scripts work immediately with CSV output from the C++ precision sweep, without building any nanobind module:

# In the mixed-precision-dsp repo:
cd build && ./applications/mp_comparison/iir_precision_sweep /tmp/csv_output

# In this repo:
python scripts/plot_precision.py /tmp/csv_output
python scripts/plot_heatmap.py /tmp/csv_output
python scripts/plot_pole_zero.py /tmp/csv_output

Quick Start: Full Python API

import mpdsp
import numpy as np
import matplotlib.pyplot as plt

# --- Signal Processing ---
# Generate and analyze signals
signal = mpdsp.sine(2000, frequency=440, sample_rate=44100)
window = mpdsp.blackman(2000)
freqs, psd = mpdsp.psd(signal * window, sample_rate=44100)

# --- Filtering ---
# Design and compare IIR filters across arithmetic types
filt = mpdsp.butterworth_lowpass(order=4, sample_rate=44100, cutoff=1000)
results = {}
for dtype in ["reference", "gpu_baseline", "posit_full", "half"]:
    results[dtype] = filt.process(signal, dtype=dtype)
    if dtype != "reference":
        sqnr = mpdsp.sqnr_db(results["reference"], results[dtype])
        print(f"  {dtype:20s}  SQNR = {sqnr:.1f} dB")

# --- Spectral Analysis ---
# fft / ifft / psd / periodogram / spectrogram all accept dtype=.
# Returned tuple is (real, imag).
real, imag = mpdsp.fft(signal, dtype="posit_full")

# --- Image Processing ---
# Full image pipeline
img = mpdsp.checkerboard(256, 256, block_size=16)
noisy = mpdsp.add_noise(img, stddev=0.1)
denoised = mpdsp.gaussian_blur(noisy, sigma=1.5)
edges = mpdsp.canny(denoised, low_threshold=0.1, high_threshold=0.3)

# Compare edge detection across arithmetic types
edges_ref = mpdsp.canny(denoised, 0.1, 0.3, dtype="reference")
edges_p8  = mpdsp.canny(denoised, 0.1, 0.3, dtype="tiny_posit")
agreement = np.mean(edges_ref == edges_p8)
print(f"  Edge agreement (posit<8,2>): {agreement:.1%}")

# --- Estimation ---
# Kalman filter tracking
kf = mpdsp.KalmanFilter(state_dim=4, meas_dim=2)
# configure F, H, Q, R matrices as NumPy arrays
# kf.predict(); kf.update(measurement)

# --- Analysis ---
# Numerical quality tools
print(f"  Stability margin: {filt.stability_margin():.4f}")
print(f"  Condition number: {filt.condition_number():.2e}")
print(f"  Worst sensitivity: {filt.worst_case_sensitivity():.4f}")

Relationship to mixed-precision-dsp

This repository is the Python integration layer for the full stillwater-sc/mixed-precision-dsp C++ library. The C++ library implements 17 DSP modules with mixed-precision arithmetic; this repo makes essentially all of them accessible to Python researchers (~93% of the v0.6.0 surface after the 2026-08-02 bindings-gap roadmap; see docs/gap_analysis_2026-08-02.md for the current coverage state and residual gaps).

Design Documents

• Python integration architecture — dispatch mechanism, pre-instantiated configs
• Projection/embedding generalization — type conversion across domains
• Mixed-precision IIR guide — numerical sensitivity primer
• OpenCV API comparison — image processing design rationale

Dependencies

License

MIT License. Copyright (c) 2024-2026 Stillwater Supercomputing, Inc.