commkit 3.5.0__tar.gz → 3.6.0__tar.gz

{commkit-3.5.0 → commkit-3.6.0}/AGENTS.md

@@ -80,6 +80,7 @@ Dependencies point downward only:
 | Presentation | `plotting` | everything; **nothing imports plotting** (no `debug_plot`: plot functions consume results or recompute through public functions) |
 
 - **Responsibilities:** `filtering` holds signal-chain filters with a real frequency response; `smoothing` display and estimation smoothers only; `analysis` laser and phase characterization; `metrics` is the reporting layer.
+- **Plot axes in SI units** are labelled with the base unit in brackets (`Frequency [Hz]`, `Time [s]`) and get `_set_eng_formatter` (`plotting/theme.py`): at each draw it picks one SI prefix from the visible ticks and writes it into the label's unit (`Frequency [GHz]`), with plain numbers on the ticks. Pass data in SI units and never pre-scale it or prefix the label by hand; log axes keep a prefix per tick, as no single one fits decades.
 - **Codes are storable:** `io` stores a code as its class and constructor fields, so those fields are numbers, strings, tuples, host arrays, constellations or other codes.
 - **Splitting modules:** promote a flat module to a package only when it exceeds about 1000 lines *and* has two or more separable concerns. Never create a `utils/` package or one-function files.
 - **One documented home per public name.** A package `__init__` re-exports its subpackages' public names, and users and documentation import them from the package (`commkit.impairments.Fiber`), not from the subpackage that defines them.
@@ -240,7 +241,7 @@ Docstrings describe the code as it is; a change in behavior updates them in the
 
 - **Fixtures:** use `backend_device`, `xp` and `xpt` from `tests/conftest.py`. Assert with `xpt.assert_allclose(...)` (`numpy.testing` raises on CuPy arrays); cast expectations with `xp.asarray` and reductions with `float(...)`.
 - **No configuration skips.** The GPU legs skip only when CuPy is not installed, and fail instead under an explicit `--device=gpu`; a broken CuPy fails under any setting. Tests outside the selected run are deselected at collection (`gpu_only`, `cpu_only`, `slow` without `--run-slow`), so a run with CuPy reports no skips. A new test never calls `pytest.skip` for a configuration.
-- **Layout mirrors the source:** `tests/<subpackage>/test_<module>.py`, `tests/test_<module>.py` for flat modules. Basenames are globally unique (prepend import mode). Split a large file by concern, each part named after its module (`impairments/test_channel_linear.py`, `test_channel_nonlinear.py`). Shared builders live in `tests/common/` and use the public API.
+- **Layout mirrors the source:** `tests/<subpackage>/test_<module>.py`, `tests/test_<module>.py` for flat modules. Basenames are globally unique (prepend import mode). Split a large file by concern, each part named after its module (`impairments/test_fiber_channel_linear.py`, `test_fiber_channel_nonlinear.py`). Shared builders live in `tests/common/` and use the public API.
 - **Contract registry** (`tests/test_api_contracts.py`): every public function has a row, checked generically for array and Signal in/out, device preserved, input not mutated, keyword-only parameters, `TypeError` on unsupported arrays, fact conflicts and return rules. Do not repeat these checks per module.
 - **Oracles:** sequential kernels are tested against plain-Python references in `tests/common/reference_impl.py`, CUDA kernels against their CPU reference. Kernel tests skip only on the CPU parametrization (`skip_unless_gpu`), so a kernel that fails to compile fails its tests.
 - **Mathematical meaning:** test documented definitions (a pulse width, a dispersion sign, noise-variance scaling) against independently derived expectations, not only shapes and energies.

{commkit-3.5.0 → commkit-3.6.0}/CHANGELOG.md

@@ -4,6 +4,41 @@ Notable changes to CommKit, newest first. Performance figures are from the refer
 
 ## [Unreleased]
 
+## [3.6.0] - 2026-11-05
+
+Chromatic dispersion for real captures. The compensation takes the link's accumulated dispersion and works as a receiver does, an FIR filter (or overlap-save blocks for backpropagation) in bounded memory, with the exact whole-record path as an option that is valid on captures too; three estimators measure an unknown dispersion, blind or from known symbols. The laser-characterization chain and its notebooks were corrected wherever a plot or a number did not mean what it said, method names that were generic now say what they do, and plot axes carry their SI prefix in the label.
+
+### Changes that may need code updates
+
+- `correct_chromatic_dispersion` takes the link's accumulated dispersion, `dispersion_ps_nm=` (D·L in ps/nm), instead of `dispersion_ps_nm_km=` and `fiber_length_km=`: a receiver knows the total, and only the product enters the physics. Write `dispersion_ps_nm=17 * 80` for 80 km of standard fiber. `dispersion_compensation_taps` takes the same argument.
+- `correct_chromatic_dispersion(method=)` and `correct_fiber_propagation(method=)` choose between two implementations of the same inverse. The default is the receiver's form, in bounded memory on a record of any length: CD by the FIR of `dispersion_compensation_taps` applied by overlap-save (`bandwidth=` and `num_taps=` choose the filter), DBP in overlapping blocks guarded by the link's dispersion memory, all blocks in one batched pass. `method="whole_record"` is the former path, the exact response over the whole record treated as one period; pass it to reproduce earlier results on simulated records. On a capture both are right except within half the dispersion memory of its ends, which no method can recover; `"whole_record"` is the more precise elsewhere, the default suits streams and studies of the filter.
+- Method objects whose names were generic, or named one thing two ways, say what they do: `recovery.ConstantPhase` replaces `DataAided` (every known-symbol method is data-aided; this one fits one constant phase per channel), `recovery.PilotInterpolation` replaces `PilotAided` and `frequency.PilotSlope` replaces `PilotSymbols` (the same pilots, interpolated as a phase or fitted as a slope), `frequency.SpectralPeak` replaces `BiasTone` (the tone `recovery.PilotTone` names too; its mechanism is the spectral peak, the counterpart of `MthPower`), `analysis.DshFmFit` replaces `DshFmPsd` (one word from the result class `DshFmNoisePsd`), and `coding.StageDecoders` replaces `Stages`. Rename at the call; nothing else changes.
+- `commkit.impairments.channel` is `commkit.impairments.fiber_channel`, leaving room for other channel models. Import from `commkit.impairments` and nothing changes.
+- `filter_response` and `plot_filter_response` evaluate complex coefficients over the whole band `[-fs/2, fs/2)` by default, since their response differs at negative frequencies; real coefficients keep the grid from DC to Nyquist. Pass `frequencies=` for the old grid.
+- `BetaSeparation`'s white-FM floor (`linewidth_floor`) is a Whittle fit of white FM, flicker FM and the detection noise's `f²` tail, the model of `DshFmFit`, instead of the median of an auto-detected plateau, and the estimate now carries `flicker`, `angle_noise_var` and `fm_psd_model`. Without a fence the fit runs from the plateau's lower edge to Nyquist. The default segment is the largest power of two within an eighth of the record (it was capped at 4096 samples), so the β-area can resolve the white-FM crossover; pass `nperseg=` for the old segment.
+- Plot axes in SI units carry one SI prefix in the axis label (`Frequency [GHz]`, `Time [ns]`) with plain numbers on the ticks, chosen anew at every draw, so zooming or new limits rescale both; ticks no longer repeat the prefix (`10 G`). Log axes keep a prefix per tick. Limits stay in SI units (`xlim=(0, 2e9)`).
+- `plot_allan_deviation` draws no `τ^(-1/2)` guide by default (`reference_slopes=False`): anchored at the first point, it was meaningless wherever that point is not white-FM limited.
+
+### Added
+
+- `filtering.dispersion_compensation_taps` designs the FIR filter of `correct_chromatic_dispersion`: the least-squares fit of the inverse fiber response over a band (the signal's occupied bandwidth, or the whole sampled band), exact through Fresnel integrals. Its default length is 1.25 times the group-delay spread over the band, which reaches about -45 dB of residual against the frequency-domain compensation; fitting only the occupied band needs about a third of the taps of a fit over the whole band. Notebook 19 shows the taps, their response and the SNR against the length.
+- `filtering.estimate_chromatic_dispersion` with `ClockToneScan` measures a capture's accumulated dispersion blind, before frequency and carrier recovery: Godard's clock-tone spectral correlation, every candidate scanned by one inverse FFT, the estimate the centroid of the peak (a standard deviation of 5 ps/nm at rolloff 0.1 and 1 ps/nm at 0.35 on 2^17 samples at 15 dB; within 62 ps/nm with 10 ps of DGD and a 1 GHz offset). It returns a `ChromaticDispersionEstimate` with the scan, which `correct_chromatic_dispersion(x, estimate)` takes as its `how` (or `correct_chromatic_dispersion(x, ClockToneScan())` to estimate first), and whose value designs the taps to study with `dispersion_compensation_taps(dispersion_ps_nm=estimate.value, ...)`.
+- `estimate_chromatic_dispersion` has two more methods: `FourthMomentScan`, blind and without an excess band (Nyquist pulses), which scores each candidate compensation by the normalized fourth moment of the field (within 11 ps/nm at rolloff 0 and 0.1; about a second on the CPU, 0.05 s on the GPU), and `QuadraticPhaseFit`, data-aided from the Signal's reference or `symbols=`, which fits the quadratic phase of the channel response measured against the known symbols (within 12 ps/nm to ±34000 ps/nm at 6 dB Es/N0, with phase noise and PMD) and returns the measured group delay. `ClockToneScan` warns when the Signal's pulse has a rolloff below 0.05.
+
+### Fixed
+
+- `BetaSeparation`'s floor read the foot of the AWGN `f²` tail as plateau: 11 % high on the 32 GBd, 1 MHz, 20 dB trajectory of notebook 23 at the default segment (now 0.999 MHz). When the Welch bins cannot resolve the white-FM crossover with the β-line, a warning says so and names the segment needed; the β-area used to return 0 silently.
+- `DshFmPsd` on a real (single-photodiode) beat reports `fm_psd` and `fm_psd_model` as NaN beyond the beat's support, `min(f_shift, f_s/2 - f_shift)`, where the bins read several times low; `valid` marks it. The fit already excluded them.
+- `plot_frequency_noise_psd` draws the fitted model through the same log-binned reduction as a dense PSD (a fringe-resolving DSH model swung at every notch and was drawn as a filled band), keeps the β-line from setting the vertical range, and no longer breaks log-binned curves at empty low-frequency cells. `plot_dsh_beat_psd` zooms on the line, twice the deep width on each side. `plot_carrier_phase_decomposition` labels the total phase next to the drift.
+- The laser-characterization notebooks (23 to 28) report what their plots show: beat-spectrum limits in Hz (they were MHz on a Hz axis, an empty plot), the β-area resolved and explained as the observed width next to the intrinsic floor, the Allan deviation of the unfiltered frequency with its white-PM, white-FM and wander regions, the flicker corner on segments that resolve it, the record-to-record scatter of `DshIncrement` and of the Lorentzian widths, and verdicts in the measurement templates computed from the numbers instead of printed unconditionally.
+- The fiber channel functions document that they treat their record as one period (circular), which the receiver inverts exactly with `method="whole_record"`.
+
+### Development
+
+- The precision audit caught the clock-tone scan's frequency-shift phasor built in complex128, which promoted the complex64 scan; it is built in the data's precision.
+- The transfer audit lists the dispersion estimators' host-side fits and the data-aided fit's known symbols; CD compensation and block DBP add no transfers.
+- `AGENTS.md` states the plotting convention for SI units (the base unit in the label, the prefix chosen at draw time) and names the fiber-channel test files.
+
 ## [3.5.0] - 2026-11-05
 
 One name per concept, finished. A review of the API and the module layout renamed the arguments and result fields that broke the library's naming rules, split or merged the modules that broke its size rules, and fixed the two audit tools that could pass without checking anything. Numerical results do not change.
@@ -426,7 +461,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.5.0...HEAD
+[Unreleased]: https://github.com/lokgar/commkit/compare/v3.6.0...HEAD
+[3.6.0]: https://github.com/lokgar/commkit/compare/v3.5.0...v3.6.0
 [3.5.0]: https://github.com/lokgar/commkit/compare/v3.4.0...v3.5.0
 [3.4.0]: https://github.com/lokgar/commkit/compare/v3.3.0...v3.4.0
 [3.3.0]: https://github.com/lokgar/commkit/compare/v3.2.1...v3.3.0

{commkit-3.5.0 → commkit-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: commkit
-Version: 3.5.0
+Version: 3.6.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
@@ -147,8 +147,8 @@ CommKit never picks a device for you: data stays where you put it, and each func
 | [`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.timing`](https://github.com/lokgar/commkit/blob/main/commkit/timing.py) | Barker and Zadoff-Chu sequences, `estimate_timing` / `correct_timing`, fractional delay estimation and correction. |
-| [`commkit.frequency`](https://github.com/lokgar/commkit/blob/main/commkit/frequency.py) | `estimate_frequency_offset` / `correct_frequency_offset` with `MthPower`, `MengaliMorelli`, `PilotSymbols` and `BiasTone`; static and blockwise. |
-| [`commkit.recovery`](https://github.com/lokgar/commkit/tree/main/commkit/recovery) | `estimate_carrier_phase` / `correct_carrier_phase` with `ViterbiViterbi`, `BPS`, `PLL`, `Tikhonov`, `DataAided`, `PilotAided`, `PilotTone(s)`; cycle-slip correction; `resolve_phase_ambiguity` and `resolve_channel_permutation`. |
+| [`commkit.frequency`](https://github.com/lokgar/commkit/blob/main/commkit/frequency.py) | `estimate_frequency_offset` / `correct_frequency_offset` with `MthPower`, `MengaliMorelli`, `PilotSlope` and `SpectralPeak`; static and blockwise. |
+| [`commkit.recovery`](https://github.com/lokgar/commkit/tree/main/commkit/recovery) | `estimate_carrier_phase` / `correct_carrier_phase` with `ViterbiViterbi`, `BPS`, `PLL`, `Tikhonov`, `ConstantPhase`, `PilotInterpolation`, `PilotTone(s)`; cycle-slip correction; `resolve_phase_ambiguity` and `resolve_channel_permutation`. |
 | [`commkit.equalization`](https://github.com/lokgar/commkit/tree/main/commkit/equalization) | Sequential `lms`, `rls`, `cma`, `rde` (Numba) and frequency-domain `block_lms`, `block_cma`, `block_rde` (CuPy, CUDA graphs), butterfly MIMO, inline carrier recovery (`cpr=PLL()` / `BPS()`), continuation with `state=`, `zf_equalizer`; pilot-aided CMA and RDE from a frame's pilots (`EqualizerPilots`); polarization demultiplexing on pilot tones (`estimate_polarization_tones` / `correct_polarization`). |
 | [`commkit.metrics`](https://github.com/lokgar/commkit/blob/main/commkit/metrics.py) | `evm`, `snr`, `ber`, `fer`, `ser`, `gmi`, `ngmi`, `mi`, including shaped constellations; pre-FEC and post-FEC (`ber(decoded, sig)`); `estimate_noise_variance` for LLRs; host values per channel. |
 | [`commkit.analysis`](https://github.com/lokgar/commkit/tree/main/commkit/analysis) | Laser and carrier-phase characterization: `estimate_linewidth` (increment slope, β-separation, delayed self-heterodyne FM-PSD / increment / Lorentzian), FM-noise PSDs, drift separation, Allan deviation. |

{commkit-3.5.0 → commkit-3.6.0}/README.md

@@ -111,8 +111,8 @@ CommKit never picks a device for you: data stays where you put it, and each func
 | [`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.timing`](https://github.com/lokgar/commkit/blob/main/commkit/timing.py) | Barker and Zadoff-Chu sequences, `estimate_timing` / `correct_timing`, fractional delay estimation and correction. |
-| [`commkit.frequency`](https://github.com/lokgar/commkit/blob/main/commkit/frequency.py) | `estimate_frequency_offset` / `correct_frequency_offset` with `MthPower`, `MengaliMorelli`, `PilotSymbols` and `BiasTone`; static and blockwise. |
-| [`commkit.recovery`](https://github.com/lokgar/commkit/tree/main/commkit/recovery) | `estimate_carrier_phase` / `correct_carrier_phase` with `ViterbiViterbi`, `BPS`, `PLL`, `Tikhonov`, `DataAided`, `PilotAided`, `PilotTone(s)`; cycle-slip correction; `resolve_phase_ambiguity` and `resolve_channel_permutation`. |
+| [`commkit.frequency`](https://github.com/lokgar/commkit/blob/main/commkit/frequency.py) | `estimate_frequency_offset` / `correct_frequency_offset` with `MthPower`, `MengaliMorelli`, `PilotSlope` and `SpectralPeak`; static and blockwise. |
+| [`commkit.recovery`](https://github.com/lokgar/commkit/tree/main/commkit/recovery) | `estimate_carrier_phase` / `correct_carrier_phase` with `ViterbiViterbi`, `BPS`, `PLL`, `Tikhonov`, `ConstantPhase`, `PilotInterpolation`, `PilotTone(s)`; cycle-slip correction; `resolve_phase_ambiguity` and `resolve_channel_permutation`. |
 | [`commkit.equalization`](https://github.com/lokgar/commkit/tree/main/commkit/equalization) | Sequential `lms`, `rls`, `cma`, `rde` (Numba) and frequency-domain `block_lms`, `block_cma`, `block_rde` (CuPy, CUDA graphs), butterfly MIMO, inline carrier recovery (`cpr=PLL()` / `BPS()`), continuation with `state=`, `zf_equalizer`; pilot-aided CMA and RDE from a frame's pilots (`EqualizerPilots`); polarization demultiplexing on pilot tones (`estimate_polarization_tones` / `correct_polarization`). |
 | [`commkit.metrics`](https://github.com/lokgar/commkit/blob/main/commkit/metrics.py) | `evm`, `snr`, `ber`, `fer`, `ser`, `gmi`, `ngmi`, `mi`, including shaped constellations; pre-FEC and post-FEC (`ber(decoded, sig)`); `estimate_noise_variance` for LLRs; host values per channel. |
 | [`commkit.analysis`](https://github.com/lokgar/commkit/tree/main/commkit/analysis) | Laser and carrier-phase characterization: `estimate_linewidth` (increment slope, β-separation, delayed self-heterodyne FM-PSD / increment / Lorentzian), FM-noise PSDs, drift separation, Allan deviation. |

{commkit-3.5.0 → commkit-3.6.0}/benchmarks/bench_fiber.py

@@ -54,11 +54,28 @@ def bench_fiber_propagation(benchmark, backend_device, xp, sync, monkeypatch, n,
 @pytest.mark.parametrize("path", PATHS)
 @pytest.mark.parametrize("steps", [1, 10])
 def bench_dbp(benchmark, backend_device, xp, sync, monkeypatch, steps, path):
+    """The whole record (``method="whole_record"``), as the 0008 baseline measured."""
     _stages(backend_device, monkeypatch, path)
     x = xp.asarray(fiber_workload(2**20))
 
     def run():
-        out = correct_fiber_propagation(x, steps_per_span=steps, **LINK)
+        out = correct_fiber_propagation(
+            x, steps_per_span=steps, method="whole_record", **LINK
+        )
+        sync()
+        return out
+
+    benchmark.pedantic(run, **ROUNDS)
+
+
+@pytest.mark.parametrize("path", PATHS)
+def bench_dbp_blocks(benchmark, backend_device, xp, sync, monkeypatch, path):
+    """A capture: overlap-save blocks, ten steps per span."""
+    _stages(backend_device, monkeypatch, path)
+    x = xp.asarray(fiber_workload(2**20))
+
+    def run():
+        out = correct_fiber_propagation(x, steps_per_span=10, **LINK)
         sync()
         return out
 

{commkit-3.5.0 → commkit-3.6.0}/commkit/__init__.py

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

commkit-3.6.0/commkit/_dispersion.py

@@ -0,0 +1,194 @@
+"""Chromatic dispersion physics (private).
+
+Single source of the fiber dispersion model used by
+``impairments.apply_chromatic_dispersion`` (the channel) and
+``filtering.correct_chromatic_dispersion`` (its inverse):
+
+- ``beta2_length``: the accumulated dispersion D·L [ps/nm] and λ [nm] to the
+  β₂·L product [s²], ``β₂ = -D λ² / (2π c)``; ``beta3_length`` adds the
+  accumulated slope S·L [ps/nm²] for the β₃·L product [s³]
+  (``commkit._fiber``).  The channel passes D·L of a fiber, the receiver the
+  accumulated dispersion it knows.
+- ``dispersion_phase``: the phase ``-(β₂Lω²/2 + β₃Lω³/6)`` on the FFT grid
+  (also used by ``commkit._fiber``).
+- ``transfer_function``: ``H(ω) = exp(-j β₂ L ω² / 2)`` on the FFT grid of
+  ``num_samples`` samples, or its inverse ``exp(+j β₂ L ω² / 2)``.
+- ``spread_samples`` and ``compensation_taps``: the group-delay spread over
+  the sampled band and the FIR form of the inverse
+  (``filtering.dispersion_compensation_taps``).
+
+Sign convention: NumPy's FFT uses the engineering kernel ``exp(-jωt)``, so a
+field propagating through the fiber is multiplied by ``exp(-j β₂ L ω² / 2)``.
+Its group delay ``τ(ω) = -dφ/dω = β₂ L ω`` makes the higher frequency
+(shorter wavelength) arrive first in anomalous fiber (D > 0, β₂ < 0), with
+``Δτ = D L Δλ``.
+"""
+
+from types import ModuleType
+from typing import Any
+
+import numpy as np
+import scipy.linalg
+import scipy.special
+
+from . import _fft
+from ._array import as_2d, restore_1d
+from ._constants import SPEED_OF_LIGHT as _SPEED_OF_LIGHT
+from .backend import ArrayType, dispatch
+from .math import _phasor
+
+
+def beta2_length(*, dispersion_ps_nm: float, center_wavelength_nm: float) -> float:
+    """The ``β₂ · L`` product in s² for the accumulated dispersion D·L in ps/nm."""
+    dl = dispersion_ps_nm * 1e-12 / 1e-9  # s/m
+    lam = center_wavelength_nm * 1e-9  # m
+    return float(-(dl * lam**2) / (2.0 * np.pi * _SPEED_OF_LIGHT))
+
+
+def beta3_length(
+    *,
+    dispersion_ps_nm: float,
+    dispersion_slope_ps_nm2: float,
+    center_wavelength_nm: float,
+) -> float:
+    """The ``β₃ · L`` product in s³ for D·L, the accumulated slope S·L and λ.
+
+    From ``D = -(2πc/λ²) β₂`` and ``dω/dλ = -2πc/λ²``:
+    ``β₃ = (S + 2D/λ) · (λ² / (2πc))²``, times the length.
+    """
+    dl = dispersion_ps_nm * 1e-12 / 1e-9  # s/m
+    sl = dispersion_slope_ps_nm2 * 1e-12 / (1e-9 * 1e-9)  # s/m²
+    lam = center_wavelength_nm * 1e-9  # m
+    k = lam**2 / (2.0 * np.pi * _SPEED_OF_LIGHT)
+    return float((sl + 2.0 * dl / lam) * k**2)
+
+
+def dispersion_phase(
+    num_samples: int,
+    *,
+    sampling_rate: float,
+    beta2_length: float,
+    beta3_length: float = 0.0,
+    xp: ModuleType,
+) -> ArrayType:
+    """Propagation phase ``-(β₂L ω²/2 + β₃L ω³/6)`` on the ``fftfreq`` grid.
+
+    float64 on ``xp``'s device, because it reaches thousands of radians.
+    """
+    omega = 2.0 * np.pi * xp.fft.fftfreq(num_samples, d=1.0 / sampling_rate)
+    phase = (beta2_length / 2.0) * omega**2
+    if beta3_length:
+        phase += (beta3_length / 6.0) * omega**3
+    return -phase
+
+
+def transfer_function(
+    num_samples: int,
+    *,
+    sampling_rate: float,
+    beta2_length: float,
+    inverse: bool,
+    xp: ModuleType,
+    dtype: Any = np.complex128,
+) -> ArrayType:
+    """Fiber transfer function on the ``fftfreq`` grid (or its inverse).
+
+    The phase is computed in float64 and the response is returned as
+    ``dtype``, so complex64 data is filtered in single precision instead of
+    being promoted.
+    """
+    phase = dispersion_phase(
+        num_samples, sampling_rate=sampling_rate, beta2_length=beta2_length, xp=xp
+    )
+    return _phasor(-phase if inverse else phase, dtype, xp)
+
+
+def spread_samples(
+    beta2_length: float, *, sampling_rate: float, bandwidth: float
+) -> float:
+    """Group-delay spread over a band, in samples.
+
+    ``τ(ω) = β₂ L ω`` over ``|f| <= bandwidth / 2`` spans
+    ``2π |β₂ L| · bandwidth`` seconds; over the whole sampled band
+    (``bandwidth = fs``) this is Savory's FIR length (Opt. Express 16, 2008).
+    """
+    return 2.0 * np.pi * abs(beta2_length) * bandwidth * sampling_rate
+
+
+def _band_integral(a: float, n: np.ndarray, half_band: float) -> np.ndarray:
+    """``(1/2π) ∫_{-W}^{W} exp(j(a θ² + n θ)) dθ`` by Fresnel integrals.
+
+    Completing the square, ``a θ² + n θ = a (θ + n/2a)² - n²/4a``.
+    """
+    scale = np.sqrt(2.0 * abs(a) / np.pi)
+    shift = n / (2.0 * a)
+    s_hi, c_hi = scipy.special.fresnel(scale * (half_band + shift))
+    s_lo, c_lo = scipy.special.fresnel(scale * (-half_band + shift))
+    integral = np.sqrt(np.pi / (2.0 * abs(a))) * (
+        (c_hi - c_lo) + 1j * np.sign(a) * (s_hi - s_lo)
+    )
+    phase = np.exp(-1j * n**2 / (4.0 * a))
+    return np.asarray(phase * integral / (2.0 * np.pi), dtype=np.complex128)
+
+
+#: Tikhonov term added to the diagonal of the band's Gram matrix (whose
+#: diagonal is ``bandwidth / fs``): bounds the gain outside the band.
+_LS_REGULARIZATION = 1e-6
+
+
+def compensation_taps(
+    beta2_length: float, *, sampling_rate: float, bandwidth: float, num_taps: int
+) -> np.ndarray:
+    """Least-squares FIR fit of the inverse response over a band.
+
+    Minimizes ``∫_{|θ|<W} |Σ h[n] e^{-jθn} - exp(j a θ²)|² dθ`` with
+    ``θ = ω / fs``, ``W = π · bandwidth / fs`` and ``a = β₂ L fs² / 2``, for
+    ``n`` centred on tap ``(num_taps - 1) // 2`` (Eghbali et al., J.
+    Lightw. Technol. 32, 2014): ``Q h = p`` with the Toeplitz Gram matrix
+    ``Q[m, k] = (W/π) sinc(W (m-k) / π)`` and ``p[m]`` the band integral of
+    the response, exact through Fresnel integrals.  Over the whole band
+    (``W = π``) ``Q`` is the identity and ``h = p``, the truncated
+    band-limited impulse response.  Host complex128.
+    """
+    n = np.arange(num_taps) - (num_taps - 1) // 2
+    a = beta2_length * sampling_rate**2 / 2.0
+    if a == 0.0:
+        return np.asarray(n == 0, dtype=np.complex128)
+    half_band = np.pi * bandwidth / sampling_rate
+    p = _band_integral(a, n, half_band)
+    if bandwidth >= sampling_rate:
+        return p
+    col = (half_band / np.pi) * np.sinc(half_band * np.arange(num_taps) / np.pi)
+    col[0] += _LS_REGULARIZATION
+    return np.asarray(scipy.linalg.solve_toeplitz(col, p), dtype=np.complex128)
+
+
+def apply_dispersion(
+    samples: ArrayType,
+    *,
+    sampling_rate: float,
+    dispersion_ps_nm: float,
+    center_wavelength_nm: float,
+    inverse: bool,
+) -> ArrayType:
+    """Filter samples with the fiber's dispersion response or its inverse.
+
+    ``(N,)`` or ``(C, N)`` samples keep their shape, dtype and device.
+    """
+    samples, xp, _ = dispatch(samples)
+    samples, was_1d = as_2d(samples, name="samples")
+    h = transfer_function(
+        samples.shape[-1],
+        sampling_rate=sampling_rate,
+        beta2_length=beta2_length(
+            dispersion_ps_nm=dispersion_ps_nm,
+            center_wavelength_nm=center_wavelength_nm,
+        ),
+        inverse=inverse,
+        xp=xp,
+        dtype=np.result_type(samples.dtype, np.complex64),
+    )
+    result = _fft.ifft(_fft.fft(samples, axis=-1) * h[None, :], axis=-1)
+    if result.dtype != samples.dtype:
+        result = result.astype(samples.dtype)
+    return restore_1d(was_1d, result)

{commkit-3.5.0 → commkit-3.6.0}/commkit/_fiber.py

@@ -620,18 +620,19 @@ def propagate(
 ) -> ArrayType:
     """Propagate the field over the link, or backpropagate it.
 
-    ``x`` is ``(C, N)`` in sqrt(W) with C in {1, 2}; ``direction=-1``
-    backpropagates (DBP: no ASE, no PMD).
+    ``x`` is ``(C, N)`` in sqrt(W) with C in {1, 2}, or ``(C, B, N)``: ``B``
+    independent records (the blocks of an overlap-save DBP) propagated at
+    once, which every stage broadcasts over; ``direction=-1`` backpropagates
+    (DBP: no ASE, no PMD).
 
     ``x`` is consumed: it is the working buffer.
     """
     fiber = link.fiber
-    C, N = x.shape
+    C, N = x.shape[0], x.shape[-1]
     forward = direction > 0
     plan = _span_plan(link, C)
-    kw = {
-        "dispersion_ps_nm_km": fiber.dispersion_ps_nm_km,
-        "fiber_length_km": 1.0,
+    kw = {  # per km: the accumulated dispersion of 1 km is D
+        "dispersion_ps_nm": fiber.dispersion_ps_nm_km,
         "center_wavelength_nm": link.center_wavelength_nm,
     }
     slope = fiber.dispersion_slope_ps_nm2_km
@@ -640,9 +641,7 @@ def propagate(
         sampling_rate=sampling_rate,
         beta2_length=beta2_length(**kw),
         beta3_length=(
-            0.0
-            if slope is None
-            else beta3_length(dispersion_slope_ps_nm2_km=slope, **kw)
+            0.0 if slope is None else beta3_length(dispersion_slope_ps_nm2=slope, **kw)
         ),
         xp=xp,
     )

{commkit-3.5.0 → commkit-3.6.0}/commkit/analysis/__init__.py

@@ -11,7 +11,7 @@ DSP stages that produce them:
 - :func:`allan_deviation`: overlapping Allan deviation of the frequency.
 - :func:`estimate_linewidth`: the laser linewidth, with one method object per
   estimator (:class:`IncrementSlope`, :class:`IncrementSubtract`,
-  :class:`BetaSeparation` on phase trajectories; :class:`DshFmPsd`,
+  :class:`BetaSeparation` on phase trajectories; :class:`DshFmFit`,
   :class:`DshIncrement`, :class:`DshLorentzian` on delayed self-heterodyne
   beats, whose front end is :func:`dsh_beat` and :func:`dsh_phase`).
 
@@ -32,7 +32,7 @@ from .fm_noise import DshFmNoisePsd, dsh_fm_noise_psd, fm_noise_psd
 from .interferometry import dsh_beat, dsh_phase
 from .linewidth import (
     BetaSeparation,
-    DshFmPsd,
+    DshFmFit,
     DshIncrement,
     DshLorentzian,
     IncrementSlope,
@@ -46,7 +46,7 @@ __all__ = [
     "AllanDeviation",
     "BetaSeparation",
     "DshFmNoisePsd",
-    "DshFmPsd",
+    "DshFmFit",
     "DshIncrement",
     "DshLorentzian",
     "FrequencyDrift",

{commkit-3.5.0 → commkit-3.6.0}/commkit/analysis/_common.py

@@ -10,16 +10,13 @@ from scipy.optimize import nnls
 from scipy.stats import chi2
 
 from ..backend import to_device
-from ..logger import logger
 
 __all__ = [
     "_BETA_SLOPE",
     "_FWHM_FROM_AREA",
-    "_floor_levels",
     "_increment_variance_fit",
     "_plateau_mask",
     "_resolve_nperseg",
-    "_welch_floor_bias",
     "_welch_median_bias",
     "_whittle_fit",
 ]
@@ -248,118 +245,6 @@ def _plateau_mask(
     return used2, levels
 
 
-def _welch_floor_bias(n_samples: int, nperseg: int, *, label: str) -> tuple[float, int]:
-    """``_welch_median_bias`` plus the shared segment-count diagnostic.
-
-    Every median-based white-FM floor in this package (β-separation and DSH
-    alike) divides out the same χ²-median bias and wants the same warning when
-    too few Welch segments back it, so the message lives here rather than being
-    re-typed per estimator.
-
-    Parameters
-    ----------
-    n_samples : int
-        Length of the sequence handed to Welch (the differentiated phase).
-    nperseg : int
-        Welch segment length actually used (see ``_resolve_nperseg``).
-    label : str
-        Caller name used in the log messages.
-
-    Returns
-    -------
-    factor : float
-        ``median/mean`` ratio to divide the median-based floor by.
-    num_segments : int
-        Welch segment count ``K``.
-    """
-    m_med, k_seg = _welch_median_bias(n_samples, nperseg)
-    if k_seg < 4:
-        logger.warning(
-            "%s: only %d Welch segment(s) at nperseg=%d - the floor median is "
-            "noisy and the χ²-median correction (÷%.3f) is asymptotic; extend "
-            "the record (aim for ≥ 5·nperseg samples).",
-            label,
-            k_seg,
-            nperseg,
-            m_med,
-        )
-    else:
-        logger.info(
-            "%s: %d Welch segments - χ²-median floor bias corrected by ÷%.4f.",
-            label,
-            k_seg,
-            m_med,
-        )
-    return m_med, k_seg
-
-
-def _floor_levels(
-    f,
-    s2,
-    base2,
-    *,
-    auto: bool,
-    label: str,
-    fallback_desc: str = "the fenced band",
-):
-    """White-FM floor level per channel, by plateau auto-detection or fence.
-
-    The summary half of both PSD linewidth routes: ``Δν = π · level`` once the
-    caller divides out the χ²-median bias.  Host-side NumPy by design (the
-    spectrum has already been transferred once).
-
-    Parameters
-    ----------
-    f : ndarray, (nf,)
-        One-sided frequency axis (host).
-    s2 : ndarray, (C, nf)
-        FM-noise PSD per channel (host; NaN allowed at masked bins).
-    base2 : ndarray of bool, (C, nf)
-        Eligible bins (validity mask and any user fences).
-    auto : bool
-        If True, auto-detect the plateau (``_plateau_mask``) and fall back to
-        ``base2`` per channel where detection fails.  If False, the median
-        runs over ``base2`` as given.
-    label : str
-        Caller name used in the fallback warning.
-    fallback_desc : str
-        Human-readable description of ``base2``, the fallback, for the warning.
-
-    Returns
-    -------
-    used2 : ndarray of bool, (C, nf)
-        Bins the median actually ran over.
-    levels : ndarray, (C,)
-        Raw median level per channel - **not** χ²-corrected - or NaN where no
-        eligible bin remained (the caller decides whether that is a zero floor
-        or an error).
-    """
-    n_ch = s2.shape[0]
-
-    def _median(mask_row, ch):
-        return float(np.median(s2[ch][mask_row])) if mask_row.any() else np.nan
-
-    if auto:
-        used2, levels = _plateau_mask(f, s2, base2)
-        for c in range(n_ch):
-            if np.isfinite(levels[c]):
-                continue
-            logger.warning(
-                "%s: no plateau detected (channel %d) - the floor median falls "
-                "back to %s. Inspect the PSD before quoting Δν.",
-                label,
-                c,
-                fallback_desc,
-            )
-            used2[c] = base2[c]
-            levels[c] = _median(used2[c], c)
-        return used2, levels
-
-    used2 = np.broadcast_to(base2, s2.shape)
-    levels = np.array([_median(used2[c], c) for c in range(n_ch)])
-    return used2, levels
-
-
 def _increment_variance_fit(y2, lags, dt: float, xp):
     r"""Least-squares fit of the increment variance ``Var(Δ_a)`` against lag.
 

{commkit-3.5.0 → commkit-3.6.0}/commkit/analysis/fm_noise.py

@@ -278,7 +278,7 @@ def dsh_fm_noise_psd(
     -------
     DshFmNoisePsd
         ``f``, ``S_f`` and ``valid``, on the input's device;
-        ``estimate_linewidth(x, DshFmPsd(...))`` is the reporting layer that
+        ``estimate_linewidth(x, DshFmFit(...))`` is the reporting layer that
         returns host values.
 
     See Also
@@ -295,7 +295,7 @@ def dsh_fm_noise_psd(
     * Additive detection noise on the beat adds white phase noise, an
       ``∝ sin²(πf/f_s)`` (≈ ``f²``) term that is not shaped by the
       interferometer; after the division it rises in every lobe.
-      ``DshFmPsd`` fits it as a separate term instead of dividing it.
+      ``DshFmFit`` fits it as a separate term instead of dividing it.
     * Near the notches (long segments only) the division amplifies the
       estimation noise by ``1/(4 sin²)``.
     * With long segments the result depends on τ_d through the notch

{commkit-3.5.0 → commkit-3.6.0}/commkit/analysis/interferometry.py

@@ -72,7 +72,7 @@ use.
 The DSH estimators are methods of
 :func:`~commkit.analysis.linewidth.estimate_linewidth`:
 
-* ``DshFmPsd``: fits white FM, flicker FM and detection noise to the beat's
+* ``DshFmFit``: fits white FM, flicker FM and detection noise to the beat's
   FM-noise PSD, through the interferometer response as a Welch estimate sees
   it; it works in the coherent (short-delay) and the incoherent regime and,
   with its default segments, needs the delay only roughly.

{commkit-3.5.0 → commkit-3.6.0}/commkit/analysis/linewidth/__init__.py

@@ -6,7 +6,7 @@ The method object chooses the estimator and the kind of record it reads:
   ``IncrementSubtract`` and ``BetaSeparation``, e.g. the output of
   ``carrier_phase_trajectory`` or ``separate_drift_phase_noise``;
 * delayed self-heterodyne / self-homodyne beat records (real photocurrent or
-  complex IQ, array or Signal) - ``DshFmPsd``, ``DshIncrement`` and
+  complex IQ, array or Signal) - ``DshFmFit``, ``DshIncrement`` and
   ``DshLorentzian`` (see :mod:`commkit.analysis.interferometry`).
 
 Every method returns a :class:`LinewidthEstimate`: the linewidth in Hz plus
@@ -21,7 +21,7 @@ from ...backend import ArrayType, dispatch
 from ...core._signal_adapter import adapt_signal
 from ...core.signal import Signal
 from .dsh import (
-    DshFmPsd,
+    DshFmFit,
     DshIncrement,
     DshLorentzian,
     _dsh_fm_psd,
@@ -41,7 +41,7 @@ from .result import LinewidthEstimate
 
 __all__ = [
     "BetaSeparation",
-    "DshFmPsd",
+    "DshFmFit",
     "DshIncrement",
     "DshLorentzian",
     "IncrementSlope",
@@ -61,7 +61,7 @@ _PHASE_METHODS: dict[type, Any] = {
     BetaSeparation: _beta_separation,
 }
 _BEAT_METHODS: dict[type, Any] = {
-    DshFmPsd: _dsh_fm_psd,
+    DshFmFit: _dsh_fm_psd,
     DshIncrement: _dsh_increment,
     DshLorentzian: _dsh_lorentzian,
 }
@@ -85,7 +85,7 @@ def estimate_linewidth(
           real phase trajectory in radians (``carrier_phase_trajectory``,
           ``separate_drift_phase_noise``, ``dsh_phase``).  Complex input
           raises.
-        * ``DshFmPsd``, ``DshIncrement``, ``DshLorentzian``: a delayed
+        * ``DshFmFit``, ``DshIncrement``, ``DshLorentzian``: a delayed
           self-heterodyne beat record, real (single photodetector) or complex
           (IQ front end), as an array or a Signal.  A phase trajectory is
           real too, so it cannot be rejected by type: real input logs a
@@ -94,7 +94,7 @@ def estimate_linewidth(
           beat line, a peak 10 dB above the spectrum at half and 1.5 times
           its frequency (a drift-removed residual, or a beat too weak or too
           wide for its carrier to measure).
-    method : IncrementSlope, IncrementSubtract, BetaSeparation, DshFmPsd, DshIncrement or DshLorentzian
+    method : IncrementSlope, IncrementSubtract, BetaSeparation, DshFmFit, DshIncrement or DshLorentzian
         The estimator and its parameters.
     sampling_rate : float, optional
         Sampling rate of the record in Hz (a fact: the symbol rate for a
@@ -133,6 +133,6 @@ def estimate_linewidth(
         return _BEAT_METHODS[kind](x, method, fs)
     raise TypeError(
         f"{name}: method must be IncrementSlope, IncrementSubtract, "
-        "BetaSeparation, DshFmPsd, DshIncrement or DshLorentzian, got "
+        "BetaSeparation, DshFmFit, DshIncrement or DshLorentzian, got "
         f"{kind.__name__}."
     )