commkit 3.2.1__tar.gz → 3.3.0__tar.gz

{commkit-3.2.1 → commkit-3.3.0}/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 Notable changes to CommKit, newest first. Performance figures are from the reference machine (RTX 4070 Ti, Ryzen 7 7800X3D, WSL2) unless stated otherwise, as a ratio of new to old time (below 1 is faster).
 
+## [Unreleased]
+
+## [3.3.0] - 2026-11-03
+
+Numerical filter responses and plots built for comparisons. `filter_response`, `impulse_response` and `step_response` evaluate any FIR, SOS or `(b, a)` filter on its device; the multi-panel diagnostics draw one selected panel, and every plot can overlay several results on one axis. The example notebooks explain what each result shows.
+
+### Changes that may need code updates
+
+- `plot_filter_response` raises `ValueError` when `ax` holds other than four axes for the dashboard (or one for a selected `quantity=`), as the other multi-panel plots do; it used to log a warning and open a new figure. Pass the right number of axes, or none.
+
+### Added
+
+- `filter_response` (returning a `FilterResponse` of frequencies, complex response and group delay), `impulse_response` and `step_response` compute the responses of FIR taps, second-order sections or a `(b, a)` pair on the coefficients' device. The group delay of SOS filters is summed section by section, so high orders keep their accuracy; real IIR time responses run through `iir_filter`, in double-precision state whatever the coefficients' precision.
+- Multi-panel diagnostics (`plot_filter_response`, `plot_equalizer_result`, `plot_zf_equalizer_response`, `plot_llr_distribution`, `plot_parity_check`, `plot_timing_correlation`, `plot_mm_autocorrelation`, `plot_frequency_offset_blockwise_result`, `plot_pilot_phase_estimate`, `plot_pilot_tone_phase_estimate`, `plot_pilot_tones_phase_estimate`) take `quantity=` to draw one panel on one axis.
+- Comparisons on one axis: the single-panel plots and a selected `quantity=` take `label=`, `xlim=`, `ylim=` and `legend=` (`True` shows, `False` hides, `None` keeps the plot's default), and the plots with fits, guides or markers take `annotations=False` to draw only the measured curves of an overlay. `plot_eye_diagram(quantity="i" | "q")` draws one component; `plot_carrier_phase_characterization` accepts existing axes.
+- The example notebooks explain what each receiver result shows, their subplot grids scale the theme's figure size, and notebooks 13 and 16 overlay filter, smoothing, shaping and equalizer comparisons on one axis.
+
+### Development
+
+- The transfer audit documents the Tikhonov smoother's host round trip, which it flagged as undocumented.
+- `bench_filter_response` times responses on the DFT grid and on an arbitrary grid at 31, 257 and 4097 taps.
+
 ## [3.2.1] - 2026-11-02
 
 Fixes found by a rework of the test suite, which now checks what each algorithm achieves against the transmitted truth and theory. Five numerical defaults or models were wrong and change results (PLL cycle-slip repair, Tikhonov smoothing, `block_cma`'s step, `ols_fir_filter`'s alignment of even taps, `MthPower` near 0 Hz); no signature changes. Plots take their sizes from the theme.
@@ -341,7 +363,8 @@ See the [GitHub release](https://github.com/lokgar/commkit/releases/tag/v1.1.0)
 
 First release. See the [GitHub release](https://github.com/lokgar/commkit/releases/tag/v1.0.0).
 
-[Unreleased]: https://github.com/lokgar/commkit/compare/v3.2.1...HEAD
+[Unreleased]: https://github.com/lokgar/commkit/compare/v3.3.0...HEAD
+[3.3.0]: https://github.com/lokgar/commkit/compare/v3.2.1...v3.3.0
 [3.2.1]: https://github.com/lokgar/commkit/compare/v3.2.0...v3.2.1
 [3.2.0]: https://github.com/lokgar/commkit/compare/v3.1.3...v3.2.0
 [3.1.3]: https://github.com/lokgar/commkit/compare/v3.1.2...v3.1.3

{commkit-3.2.1 → commkit-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: commkit
-Version: 3.2.1
+Version: 3.3.0
 Summary: A Python library for high-performance digital communications research.
 Project-URL: Homepage, https://github.com/lokgar/commkit
 Project-URL: Repository, https://github.com/lokgar/commkit
@@ -49,7 +49,7 @@ CommKit covers the receiver chain of coherent and IM/DD links (waveform generati
 
 ## The model
 
-Data is a NumPy or CuPy array, or a `Signal` that wraps the samples together with what is known about them. Algorithms are plain functions that take the data and return a new `Signal` or array, or a typed result such as `EqualizerResult` or an `*Estimate`. Plotting functions draw those results; they never compute them.
+Data is a NumPy or CuPy array, or a `Signal` that wraps the samples together with what is known about them. Algorithms are plain functions that take the data and return a new `Signal` or array, or a typed result such as `EqualizerResult` or an `*Estimate`. Plotting functions draw those results or call the public compute functions needed to produce them.
 
 - **Things that describe** a modulation, a pulse or a sub-algorithm are small frozen objects written in the call: `lms(rx, cpr=BPS(test_phases=64))`. The same object works standalone: `correct_carrier_phase(y, BPS())`.
 - **A `Signal` carries facts and ground truth.** Facts are `sampling_rate`, `symbol_rate`, `center_frequency` and `domain`; the carrier of an optical Signal gives its `center_wavelength_nm`, which dispersion, fiber propagation and OSNR noise read. The description is `constellation` and `pulse`. The ground truth is `reference`: the transmitted symbols, the bits on the air and the source bits before coding or distribution matching (the same array when there is neither). Functions take facts from the Signal and raise on a conflicting argument. Choices such as the decision constellation default to the Signal's and can be overridden.
@@ -87,6 +87,32 @@ res2 = ck.equalization.lms(rx, num_taps=21, step_size=1e-3, cpr=cpr, state=res.s
 
 Without CuPy, pass `device="cpu"` (the default): the same code runs on the CPU.
 
+## Comparing filter responses
+
+Calculate a response on the coefficients' device, or overlay selected panels
+of several filters:
+
+```python
+short = ck.filtering.fir_taps(sampling_rate=1e6, num_taps=21, cutoff=100e3)
+long = ck.filtering.fir_taps(sampling_rate=1e6, num_taps=101, cutoff=100e3)
+response = ck.filtering.filter_response(long, sampling_rate=1e6)
+print(response.frequencies, response.response, response.group_delay)
+
+ck.plotting.apply_default_theme()
+_, ax = ck.plotting.plot_filter_response(
+    short, sampling_rate=1e6, quantity="magnitude", label="21 taps"
+)
+ck.plotting.plot_filter_response(
+    long, sampling_rate=1e6, quantity="magnitude", ax=ax,
+    label="101 taps", legend=True, show=True,
+)
+```
+
+See notebook 03 for filter and smoothing comparisons. The multi-panel
+equalizer, timing, recovery and coding diagnostics take `quantity=` in the
+same way: draw a second result on the returned axis with its own `label=`,
+and `annotations=False` to leave out repeated fits and guides.
+
 ## CPU and GPU
 
 CommKit never picks a device for you: data stays where you put it, and each function runs on the device of its input. A few habits get the speed out of a GPU:
@@ -116,7 +142,7 @@ CommKit never picks a device for you: data stays where you put it, and each func
 | --- | --- |
 | [`commkit.core`](https://github.com/lokgar/commkit/tree/main/commkit/core) | `Signal`, `Reference`, `generate` (uniform, shaped through a distribution matcher, or coded with `code=`), `SingleCarrierFrame` and `Preamble` (pilots, guard intervals, MIMO channels), `extract_payload`. |
 | [`commkit.mapping`](https://github.com/lokgar/commkit/tree/main/commkit/mapping) | `Constellation` (QAM, PSK, PAM, arbitrary points; Gray labels; probabilistic shaping with `.shaped()`), bit mapping, hard demapping, max-log and exact LLRs. |
-| [`commkit.filtering`](https://github.com/lokgar/commkit/tree/main/commkit/filtering) | Pulses (`RRC`, `RC`, `Gaussian`, `Rect`, `SmoothRect`), FIR and IIR design (Butterworth, Chebyshev I/II, elliptic, Bessel), `fir_filter`, `iir_filter`, `matched_filter`, overlap-save, chromatic-dispersion compensation and digital backpropagation (`correct_fiber_propagation`). |
+| [`commkit.filtering`](https://github.com/lokgar/commkit/tree/main/commkit/filtering) | Pulses (`RRC`, `RC`, `Gaussian`, `Rect`, `SmoothRect`), FIR and IIR design (Butterworth, Chebyshev I/II, elliptic, Bessel), numerical filter responses, `fir_filter`, `iir_filter`, `matched_filter`, overlap-save, chromatic-dispersion compensation and digital backpropagation (`correct_fiber_propagation`). |
 | [`commkit.multirate`](https://github.com/lokgar/commkit/blob/main/commkit/multirate.py) | `resample` (fractional), `decimate`, `upsample`, `decimate_to_symbol_rate`. |
 | [`commkit.spectral`](https://github.com/lokgar/commkit/blob/main/commkit/spectral.py) | Welch PSD, spectrograms, frequency shifting, pilot tones. |
 | [`commkit.impairments`](https://github.com/lokgar/commkit/tree/main/commkit/impairments) | AWGN at an Es/N0 (measured as energy per symbol) or of an absolute variance, ASE at an OSNR (`apply_ase`), phase noise, IQ imbalance (blind estimate; Löwdin and Gram-Schmidt correction), chromatic dispersion, PMD and polarization mixing, and nonlinear fiber propagation over amplified spans (split-step Kerr effect with dispersion, loss, PMD and ASE) of a `Fiber`. |

{commkit-3.2.1 → commkit-3.3.0}/README.md

@@ -13,7 +13,7 @@ CommKit covers the receiver chain of coherent and IM/DD links (waveform generati
 
 ## The model
 
-Data is a NumPy or CuPy array, or a `Signal` that wraps the samples together with what is known about them. Algorithms are plain functions that take the data and return a new `Signal` or array, or a typed result such as `EqualizerResult` or an `*Estimate`. Plotting functions draw those results; they never compute them.
+Data is a NumPy or CuPy array, or a `Signal` that wraps the samples together with what is known about them. Algorithms are plain functions that take the data and return a new `Signal` or array, or a typed result such as `EqualizerResult` or an `*Estimate`. Plotting functions draw those results or call the public compute functions needed to produce them.
 
 - **Things that describe** a modulation, a pulse or a sub-algorithm are small frozen objects written in the call: `lms(rx, cpr=BPS(test_phases=64))`. The same object works standalone: `correct_carrier_phase(y, BPS())`.
 - **A `Signal` carries facts and ground truth.** Facts are `sampling_rate`, `symbol_rate`, `center_frequency` and `domain`; the carrier of an optical Signal gives its `center_wavelength_nm`, which dispersion, fiber propagation and OSNR noise read. The description is `constellation` and `pulse`. The ground truth is `reference`: the transmitted symbols, the bits on the air and the source bits before coding or distribution matching (the same array when there is neither). Functions take facts from the Signal and raise on a conflicting argument. Choices such as the decision constellation default to the Signal's and can be overridden.
@@ -51,6 +51,32 @@ res2 = ck.equalization.lms(rx, num_taps=21, step_size=1e-3, cpr=cpr, state=res.s
 
 Without CuPy, pass `device="cpu"` (the default): the same code runs on the CPU.
 
+## Comparing filter responses
+
+Calculate a response on the coefficients' device, or overlay selected panels
+of several filters:
+
+```python
+short = ck.filtering.fir_taps(sampling_rate=1e6, num_taps=21, cutoff=100e3)
+long = ck.filtering.fir_taps(sampling_rate=1e6, num_taps=101, cutoff=100e3)
+response = ck.filtering.filter_response(long, sampling_rate=1e6)
+print(response.frequencies, response.response, response.group_delay)
+
+ck.plotting.apply_default_theme()
+_, ax = ck.plotting.plot_filter_response(
+    short, sampling_rate=1e6, quantity="magnitude", label="21 taps"
+)
+ck.plotting.plot_filter_response(
+    long, sampling_rate=1e6, quantity="magnitude", ax=ax,
+    label="101 taps", legend=True, show=True,
+)
+```
+
+See notebook 03 for filter and smoothing comparisons. The multi-panel
+equalizer, timing, recovery and coding diagnostics take `quantity=` in the
+same way: draw a second result on the returned axis with its own `label=`,
+and `annotations=False` to leave out repeated fits and guides.
+
 ## CPU and GPU
 
 CommKit never picks a device for you: data stays where you put it, and each function runs on the device of its input. A few habits get the speed out of a GPU:
@@ -80,7 +106,7 @@ CommKit never picks a device for you: data stays where you put it, and each func
 | --- | --- |
 | [`commkit.core`](https://github.com/lokgar/commkit/tree/main/commkit/core) | `Signal`, `Reference`, `generate` (uniform, shaped through a distribution matcher, or coded with `code=`), `SingleCarrierFrame` and `Preamble` (pilots, guard intervals, MIMO channels), `extract_payload`. |
 | [`commkit.mapping`](https://github.com/lokgar/commkit/tree/main/commkit/mapping) | `Constellation` (QAM, PSK, PAM, arbitrary points; Gray labels; probabilistic shaping with `.shaped()`), bit mapping, hard demapping, max-log and exact LLRs. |
-| [`commkit.filtering`](https://github.com/lokgar/commkit/tree/main/commkit/filtering) | Pulses (`RRC`, `RC`, `Gaussian`, `Rect`, `SmoothRect`), FIR and IIR design (Butterworth, Chebyshev I/II, elliptic, Bessel), `fir_filter`, `iir_filter`, `matched_filter`, overlap-save, chromatic-dispersion compensation and digital backpropagation (`correct_fiber_propagation`). |
+| [`commkit.filtering`](https://github.com/lokgar/commkit/tree/main/commkit/filtering) | Pulses (`RRC`, `RC`, `Gaussian`, `Rect`, `SmoothRect`), FIR and IIR design (Butterworth, Chebyshev I/II, elliptic, Bessel), numerical filter responses, `fir_filter`, `iir_filter`, `matched_filter`, overlap-save, chromatic-dispersion compensation and digital backpropagation (`correct_fiber_propagation`). |
 | [`commkit.multirate`](https://github.com/lokgar/commkit/blob/main/commkit/multirate.py) | `resample` (fractional), `decimate`, `upsample`, `decimate_to_symbol_rate`. |
 | [`commkit.spectral`](https://github.com/lokgar/commkit/blob/main/commkit/spectral.py) | Welch PSD, spectrograms, frequency shifting, pilot tones. |
 | [`commkit.impairments`](https://github.com/lokgar/commkit/tree/main/commkit/impairments) | AWGN at an Es/N0 (measured as energy per symbol) or of an absolute variance, ASE at an OSNR (`apply_ase`), phase noise, IQ imbalance (blind estimate; Löwdin and Gram-Schmidt correction), chromatic dispersion, PMD and polarization mixing, and nonlinear fiber propagation over amplified spans (split-step Kerr effect with dispersion, loss, PMD and ASE) of a `Fiber`. |

{commkit-3.2.1 → commkit-3.3.0}/benchmarks/bench_filters.py

@@ -4,12 +4,15 @@
 (1% of the sampling rate, poles near z = 1) on dual-channel complex64; on the
 GPU it times the double-precision ``cupyx.scipy.signal`` path.
 ``bench_moving_average_valid`` smooths a two-channel float32 phase record.
+``bench_filter_response`` evaluates the response and group delay of
+low-pass FIRs on the default 4096-point grid (FFTs) and on an arbitrary
+grid of as many points (Horner evaluation).
 """
 
 import pytest
 from workloads import FS, bps_workload, phase_workload
 
-from commkit.filtering import butterworth_sos, iir_filter
+from commkit.filtering import butterworth_sos, filter_response, fir_taps, iir_filter
 from commkit.smoothing import moving_average
 
 ROUNDS = dict(rounds=3, warmup_rounds=1, iterations=1)
@@ -39,3 +42,18 @@ def bench_moving_average_valid(benchmark, backend_device, xp, sync, window):
         return out
 
     benchmark.pedantic(run, **ROUNDS)
+
+
+@pytest.mark.parametrize("grid", ["dft", "custom"])
+@pytest.mark.parametrize("num_taps", [31, 257, 4097])
+def bench_filter_response(benchmark, backend_device, xp, sync, num_taps, grid):
+    taps = fir_taps(sampling_rate=FS, num_taps=num_taps, cutoff=0.1 * FS)
+    taps = xp.asarray(taps, dtype=xp.float32)
+    frequencies = xp.linspace(-0.5, 0.5, 4096) if grid == "custom" else None
+
+    def run():
+        result = filter_response(taps, nfft=4096, frequencies=frequencies)
+        sync()
+        return result
+
+    benchmark.pedantic(run, **ROUNDS)

{commkit-3.2.1 → commkit-3.3.0}/commkit/__init__.py

@@ -31,7 +31,7 @@ Matplotlib, change warning filters, or touch the GPU.
 import importlib
 from typing import Any
 
-__version__ = "3.2.1"
+__version__ = "3.3.0"
 
 from .backend import PrecisionWarning
 from .core import (

{commkit-3.2.1 → commkit-3.3.0}/commkit/filtering/__init__.py

@@ -6,6 +6,9 @@
 - Design: :func:`fir_taps` (window method) and the IIR designs in
   second-order sections, :func:`butterworth_sos`, :func:`chebyshev1_sos`,
   :func:`chebyshev2_sos`, :func:`elliptic_sos` and :func:`bessel_sos`.
+- Responses: :func:`filter_response` (a :class:`FilterResponse`),
+  :func:`impulse_response` and :func:`step_response`, computed on the
+  coefficients' device.
 - Application: :func:`fir_filter` (FFT convolution, optionally circular),
   :func:`ols_fir_filter` (overlap-save, for long filters), :func:`iir_filter`
   and :func:`matched_filter`.
@@ -40,8 +43,10 @@ from .pulses import (
     Rect,
     SmoothRect,
 )
+from .response import FilterResponse, filter_response, impulse_response, step_response
 
 __all__ = [
+    "FilterResponse",
     "Gaussian",
     "Pulse",
     "RC",
@@ -55,9 +60,12 @@ __all__ = [
     "correct_chromatic_dispersion",
     "correct_fiber_propagation",
     "elliptic_sos",
+    "filter_response",
     "fir_filter",
     "fir_taps",
     "iir_filter",
+    "impulse_response",
     "matched_filter",
     "ols_fir_filter",
+    "step_response",
 ]

commkit-3.3.0/commkit/filtering/response.py

@@ -0,0 +1,260 @@
+"""Frequency, impulse and step responses of digital filters.
+
+:func:`filter_response` (returning a :class:`FilterResponse`),
+:func:`impulse_response` and :func:`step_response` accept FIR taps,
+second-order sections, or a ``(b, a)`` transfer function, and compute on the
+coefficients' device.  Frequencies are in cycles per sample unless a sampling
+rate in Hz is given.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+import scipy
+
+from .. import _fft
+from ..backend import ArrayType, dispatch, to_device
+from ..math import _phasor
+from .linear import iir_filter
+
+__all__ = ["FilterResponse", "filter_response", "impulse_response", "step_response"]
+
+
+@dataclass(frozen=True)
+class FilterResponse:
+    """Frequency response and group delay of a digital filter.
+
+    Attributes
+    ----------
+    frequencies : ndarray
+        Frequency grid in Hz, or cycles per sample without a sampling rate.
+    response : ndarray
+        Complex frequency response on the input device.
+    group_delay : ndarray
+        Group delay in seconds, or samples without a sampling rate. Undefined
+        values at response zeros are ``nan``.
+    """
+
+    frequencies: ArrayType
+    response: ArrayType
+    group_delay: ArrayType
+
+
+def _system(system: Any) -> tuple[str, ArrayType, ArrayType | None, Any, Any]:
+    """Validate a filter representation and select its device."""
+    if isinstance(system, tuple):
+        if len(system) != 2:
+            raise ValueError("system must be FIR taps, SOS, or a (b, a) pair")
+        b, xp, sp = dispatch(system[0])
+        a, axp, _ = dispatch(system[1])
+        if xp is not axp:
+            raise ValueError("system coefficients must be on the same device")
+        if b.ndim != 1 or a.ndim != 1 or not b.size or not a.size:
+            raise ValueError("system coefficients b and a must be nonempty 1-D arrays")
+        return "ba", b, a, xp, sp
+    x, xp, sp = dispatch(system)
+    if x.ndim == 1 and x.size:
+        return "fir", x, None, xp, sp
+    if x.ndim == 2 and x.shape[0] and x.shape[1] == 6:
+        return "sos", x, None, xp, sp
+    raise ValueError("system must be nonempty FIR taps, SOS, or a (b, a) pair")
+
+
+def filter_response(
+    system: Any,
+    *,
+    nfft: int = 2048,
+    sampling_rate: float | None = None,
+    frequencies: ArrayType | None = None,
+) -> FilterResponse:
+    """Calculate the frequency response and group delay of a digital filter.
+
+    Parameters
+    ----------
+    system : array_like or (b, a) tuple
+        FIR taps, second-order sections ``(S, 6)``, or transfer coefficients.
+    nfft : int, default 2048
+        Number of frequency points from DC to just below Nyquist when
+        ``frequencies`` is not given.
+    sampling_rate : float, optional
+        Sampling rate in Hz. Without it, frequencies are cycles per sample
+        and group delays are samples; otherwise they are Hz and seconds.
+    frequencies : array_like, optional
+        Frequencies to evaluate, in Hz or cycles per sample when no sampling
+        rate is given. Must be one-dimensional and on the coefficients' device.
+        When omitted, a uniform grid of ``nfft`` points is used.
+
+    Returns
+    -------
+    FilterResponse
+        Frequency grid, complex response and group delay on the input device.
+
+    Notes
+    -----
+    The group delay is the sum of the section delays for SOS filters. It is
+    undefined at a zero or pole and is returned as ``nan`` there. Values
+    indistinguishable from zero in the coefficient precision are also marked
+    undefined. Frequency grids and phase wrapping use float64; coefficient
+    arithmetic follows the coefficient dtype.
+    """
+    if not isinstance(nfft, (int, np.integer)) or nfft <= 0:
+        raise ValueError("nfft must be a positive integer")
+    if sampling_rate is not None and (
+        not np.isfinite(sampling_rate) or sampling_rate <= 0
+    ):
+        raise ValueError("sampling_rate must be positive and finite")
+    kind, b, a, xp, _ = _system(system)
+    scale = float(sampling_rate) if sampling_rate is not None else 1.0
+    if frequencies is None:
+        f = xp.arange(nfft, dtype=xp.float64) * (scale / (2 * nfft))
+    else:
+        f, fxp, _ = dispatch(frequencies)
+        if fxp is not xp:
+            raise ValueError("frequencies must be on the system's device")
+        if f.ndim != 1 or f.size == 0 or xp.iscomplexobj(f):
+            raise ValueError("frequencies must be a nonempty real 1-D array")
+        if not bool(xp.all(xp.isfinite(f))):
+            raise ValueError("frequencies must be finite")
+        f = f.astype(xp.float64, copy=False)
+    # Wrap before forming the phase: multiplying a large frequency by 2π
+    # first discards its fractional cycle, especially in single precision.
+    cycles = xp.remainder(f, scale) / scale
+    dtype = xp.result_type(b.dtype, a.dtype if a is not None else b.dtype, xp.complex64)
+    z = _phasor(-2 * np.pi * cycles, dtype, xp)
+
+    def evaluate(coeff: ArrayType) -> tuple[ArrayType, ArrayType]:
+        coeff = coeff.astype(dtype, copy=False)
+        weighted_coeff = coeff * xp.arange(coeff.size, dtype=coeff.real.dtype)
+        if coeff.size > 16 and frequencies is None:
+            # Frequencies lie on a 2*nfft DFT grid. Folding coefficients
+            # preserves their response there even when the filter is longer.
+            fft_size = 2 * nfft
+            if coeff.size > fft_size:
+                pad = (-coeff.size) % fft_size
+                coeff = xp.pad(coeff, (0, pad)).reshape(-1, fft_size).sum(axis=0)
+                weighted_coeff = (
+                    xp.pad(weighted_coeff, (0, pad)).reshape(-1, fft_size).sum(axis=0)
+                )
+            value = _fft.fft(coeff, n=fft_size)[:nfft]
+            weighted = _fft.fft(weighted_coeff, n=fft_size)[:nfft]
+        else:
+            value = xp.polyval(coeff[::-1], z)
+            weighted = xp.polyval(weighted_coeff[::-1], z)
+        return value, weighted
+
+    response = xp.ones(f.size, dtype=dtype)
+    delay = xp.zeros(f.size, dtype=xp.empty((), dtype=dtype).real.dtype)
+    sections = (
+        ((b[i, :3], b[i, 3:]) for i in range(b.shape[0]))
+        if kind == "sos"
+        else ((b, a),)
+    )
+    for num, den in sections:
+        h, hn = evaluate(num)
+        if den is None:
+            d = xp.ones_like(h)
+            dn = xp.zeros_like(h)
+        else:
+            d, dn = evaluate(den)
+        # Evaluating a mathematical zero on the unit circle can leave a
+        # rounding-sized residual (e.g. sin(π)); its delay is not meaningful.
+        eps = xp.finfo(delay.dtype).eps
+        h_floor = eps * xp.sum(xp.abs(num))
+        d_floor = eps * xp.sum(xp.abs(den)) if den is not None else 0.0
+        valid = (xp.abs(h) > h_floor) & (xp.abs(d) > d_floor)
+        with np.errstate(divide="ignore", invalid="ignore"):
+            response *= h / d
+            delay += xp.where(valid, xp.real(hn / h - dn / d), xp.nan)
+    return FilterResponse(f, response, delay / scale)
+
+
+def _time_response(system: Any, num_samples: int, step: bool) -> ArrayType:
+    """Impulse (``step=False``) or unit-step response of ``num_samples``."""
+    if not isinstance(num_samples, (int, np.integer)) or num_samples <= 0:
+        raise ValueError("num_samples must be a positive integer")
+    kind, b, a, xp, sp = _system(system)
+    if kind == "ba" and a is not None and a.size == 1:
+        kind, b = "fir", b / a[0]
+    dtype = xp.result_type(b.dtype, a.dtype if a is not None else b.dtype, xp.float32)
+    if kind == "fir":
+        # The impulse response of an FIR filter is its taps, the step response
+        # their running sum: no recursion, so nothing to filter.
+        h = xp.zeros(num_samples, dtype=dtype)
+        count = min(num_samples, b.size)
+        h[:count] = b[:count]
+        return xp.cumsum(h) if step else h
+    if step:
+        x = xp.ones(num_samples, dtype=dtype)
+    else:
+        x = xp.zeros(num_samples, dtype=dtype)
+        x[0] = 1
+    if x.dtype.kind == "c":
+        # iir_filter takes real sections; complex coefficients run through
+        # SciPy's direct form in their own precision.
+        if kind == "sos":
+            return sp.signal.sosfilt(b, x)
+        return sp.signal.lfilter(b, a, x)
+    # The sections go to the host, as iir_filter takes them (its kernels and
+    # their state transitions read float64 host sections; tf2sos is SciPy's
+    # root finding): a few coefficients, while x stays on its device.
+    if kind == "sos":
+        sos = np.asarray(to_device(b, "cpu"), dtype=np.float64)
+        sos = sos / sos[:, 3:4]
+    else:
+        sos = scipy.signal.tf2sos(
+            np.asarray(to_device(b, "cpu"), dtype=np.float64),
+            np.asarray(to_device(a, "cpu"), dtype=np.float64),
+        )
+    # iir_filter keeps the sections and the state in double precision, which
+    # poles near z = 1 need, and the samples in their own precision.
+    return iir_filter(x, sos)
+
+
+def impulse_response(system: Any, *, num_samples: int = 500) -> ArrayType:
+    """Calculate a filter's causal impulse response.
+
+    Parameters
+    ----------
+    system : array_like or (b, a) tuple
+        FIR taps, second-order sections, or transfer coefficients.
+    num_samples : int, default 500
+        Number of output samples, including zeros after an FIR response.
+
+    Returns
+    -------
+    ndarray
+        Impulse response, ``(num_samples,)``, on the coefficients' device.
+
+    Notes
+    -----
+    Real IIR filters run through :func:`iir_filter`, with the sections and
+    the state in double precision whatever the coefficients' precision (a
+    ``(b, a)`` pair is first converted to sections); the response keeps the
+    coefficients' precision, at least single.  Complex IIR coefficients run
+    through SciPy's direct form in their own precision.
+    """
+    return _time_response(system, num_samples, False)
+
+
+def step_response(system: Any, *, num_samples: int = 500) -> ArrayType:
+    """Calculate a filter's causal unit-step response.
+
+    Parameters
+    ----------
+    system : array_like or (b, a) tuple
+        FIR taps, second-order sections, or transfer coefficients.
+    num_samples : int, default 500
+        Number of output samples.
+
+    Returns
+    -------
+    ndarray
+        Step response, ``(num_samples,)``, on the coefficients' device.
+
+    Notes
+    -----
+    Computed as :func:`impulse_response` is; for FIR taps it is their running
+    sum.
+    """
+    return _time_response(system, num_samples, True)

{commkit-3.2.1 → commkit-3.3.0}/commkit/plotting/__init__.py

@@ -2,9 +2,10 @@
 
 Every public function but :func:`apply_default_theme` is a ``plot_*`` function
 that draws a Signal, an array or a result object (an estimate, an
-:class:`~commkit.equalization.EqualizerResult`, an analysis summary) and never
-computes the result itself; device arrays are reduced on the device and only
-what is drawn is transferred.  Axis labels use SI prefixes.
+:class:`~commkit.equalization.EqualizerResult`, an analysis summary). A plot
+that needs a calculation calls the corresponding public compute function;
+device arrays are reduced on the device and only what is drawn is transferred.
+Tick labels use SI prefixes.
 :func:`apply_default_theme` sets the library's Matplotlib style; importing the
 package changes no Matplotlib settings.