commkit 3.1.0__tar.gz → 3.1.1__tar.gz

{commkit-3.1.0 → commkit-3.1.1}/AGENTS.md

@@ -138,6 +138,7 @@ Dependencies point downward only:
   - `analysis` holds laser and phase characterization.
   - `metrics` is the reporting layer.
 - **Splitting modules:** promote a flat module to a package only when it exceeds about 1000 lines *and* has two or more separable concerns. The package `__init__` re-exports the public names. Never create a `utils/` package or one-function files.
+- **One documented home per public name.** A package re-exports its subpackages' names, and users and documentation import them from the package (`commkit.impairments.Fiber`, `commkit.impairments.apply_pmd`), not from the subpackage that defines them.
 - **Shared physics lives in one private module**, used by the channel and by its compensation: `_dispersion` (β₂, β₃, the dispersion response) and `_fiber` (`Fiber` and the split-step solver behind `apply_fiber_propagation` and `correct_fiber_propagation`).
 
 ---
@@ -146,7 +147,7 @@ Dependencies point downward only:
 
 ### Signal
 
-- `Signal` holds: samples (NumPy or CuPy, `(N,)` or `(C, N)`, time on the last axis), the **facts** `sampling_rate`, `symbol_rate`, `center_frequency` and `domain` (`"DIG"`, `"RF"` or `"OPT"`; only RF and optical signals have a carrier), the **description** `constellation` and `pulse`, and the ground truth `reference` (transmitted symbols, the bits on the air `bits` and the source bits `info_bits`, the same array when nothing is coded or matched, and the `code` between them) plus the `frame` layout.
+- `Signal` holds: samples (NumPy or CuPy, `(N,)` or `(C, N)`, time on the last axis), the **facts** `sampling_rate`, `symbol_rate`, `center_frequency` and `domain` (`"DIG"`, `"RF"` or `"OPT"`; only RF and optical signals have a carrier; an optical carrier also gives the derived `center_wavelength_nm`, which the dispersion, fiber and OSNR functions take as a fact), the **description** `constellation` and `pulse`, and the ground truth `reference` (transmitted symbols, the bits on the air `bits` and the source bits `info_bits`, the same array when nothing is coded or matched, and the `code` between them) plus the `frame` layout.
 - It never holds pipeline results.
 - Construction does no hidden work: no mapping, no normalization, no device move, no shape guessing. Factories (`generate`, frames) do that work.
 - `sig.to("gpu")` and `sig.replace(...)` return new Signals. Arrays are shared, not copied; use `clone()` for an independent copy.
@@ -154,7 +155,7 @@ Dependencies point downward only:
 
 ### Function signatures
 
-- `f(data, other_data, *, params)`: everything after the data arguments is keyword-only. A function without data arguments may keep its single primary parameter positional (`barker_sequence(13)`, `gray_code(5)`); with several parameters, all are keyword-only (`rrc_taps(sps=2, rolloff=0.1, span=10)`). The data-argument count is recorded per function in the contract registry.
+- `f(data, other_data, *, params)`: everything after the data arguments is keyword-only. A function without data arguments may keep its single primary parameter positional (`barker_sequence(13)`, `gray_code(5)`); with several parameters, all are keyword-only (`fir_taps(sampling_rate=..., num_taps=..., cutoff=...)`). The data-argument count is recorded per function in the contract registry.
 - **Signal awareness.** A function whose main argument is waveform data (or a field a Signal really carries) accepts an array or a Signal. It unwraps once with `adapt_signal()` (in `core/_signal_adapter.py`), works on arrays, and returns through `wrap_samples()`. Never re-enter the public function recursively.
   - Functions on *derived* quantities (phase trajectories, correlations, taps, PSD bins, results) and synthesis primitives stay array-only.
 - **Metadata rule: facts versus choices.**
@@ -176,7 +177,7 @@ Dependencies point downward only:
 - **Device follows the data.** There are no `backend=` arguments and no global switches. Unsupported array types (JAX, PyTorch) raise `TypeError`.
   - Only factories with no input data to follow (`generate`, `generate_phase_noise`, `Preamble`/`SingleCarrierFrame.to_signal`, `load_npz`) take `device: str = "cpu"`, validated with `require_device()`. They draw randomness as the rule above says and do the vectorized work (mapping, shaping) on `device`. The default is never "GPU if available".
 - **No `debug_plot`.** Numerical code never imports plotting. Plot functions consume results or recompute through public compute functions.
-- **Design and apply are separate functions**, for example `rrc_taps` and `fir_filter`, or `butterworth_sos` and `iir_filter`.
+- **Design and apply are separate functions**, for example `RRC(...).taps(sps)` and `fir_filter`, or `butterworth_sos` and `iir_filter`.
 
 ### Returns
 
@@ -202,8 +203,11 @@ Dependencies point downward only:
 - The algorithm is chosen by an object, never by the function name or a string: `estimate_carrier_phase(y, BPS())`, not `recover_carrier_phase_bps(y)`. The verb function dispatches on the object's type through a private table in its module. There is no `recover_*` or `compensate_*`.
 - Computations use plain nouns (`allan_deviation`).
 - **Glossary**, one name each:
-  - `num_taps`, `step_size`, `sps`, `constellation`, `pulse`, `rng`, `num_symbols`, `num_blocks` (code blocks, codewords of a FEC code), `num_channels`, `sampling_rate`, `symbol_rate`.
-  - Units are in the docstring. Use `_db` and `_hz` suffixes where the unit is ambiguous.
+  - `num_taps`, `step_size`, `sps`, `constellation`, `pulse`, `rng`, `num_symbols`, `num_channels` (never streams), `sampling_rate`, `symbol_rate`, `noise_var`, `nfft`, `regularization`, `max_iterations`.
+  - A size names its unit: `num_symbols`, `num_blocks` (code blocks, codewords of a FEC code), `info_bits` (a code's information length where it is a parameter), `blocks_per_frame`, `num_variables`, `num_segments`. In `coding`, `length` and `n` mean the codeword length in bits and `k` the information length, nothing else.
+  - A seeded part of a factory takes `<part>_rng` (`payload_rng`), with the same int / Generator / None semantics as `rng`.
+  - A variant of one algorithm is a `method=` string only where it is a numerical flavor, not an algorithm (`method="maxlog" | "exact"`); algorithms are objects.
+  - Values are in SI units without a suffix: Hz, s, rad, rad/s, W (`linewidth` and `reference_bandwidth` in Hz, `drift_rate` in rad/s, `taus` in s). A result that holds one quantity in two units suffixes the SI one (`lags` in samples, `lag_s` in seconds). A conventional non-SI unit goes into the name: `_db`, `_dbm`, `_deg`, `_nm`, `_km`, `_ps_nm_km`. Normalized quantities say so (`normalized_bandwidth`). Do not add second names for one quantity in another unit (no `center_frequency_ghz` next to `center_frequency`); `center_wavelength_nm` is a different quantity, derived from the carrier.
 
 ### Docstrings
 

{commkit-3.1.0 → commkit-3.1.1}/CHANGELOG.md

@@ -4,6 +4,53 @@ Notable changes to CommKit, newest first. Performance figures are from the refer
 
 ## [Unreleased]
 
+## [3.1.1] - 2026-10-29
+
+API consistency. One name per concept and a unit in every size, defaults that model the physics, physical units where the rest of the API has them, and features that use what the Signal and the frame already carry: the optical carrier for dispersion, fiber and OSNR noise, the frame's pilots for the pilot-aided algorithms, the code of the reference for post-FEC metrics. Most changes are renames that fail loudly with `TypeError`; the four default changes and the speed of light alter numbers and are listed first.
+
+### Changes that alter results
+
+- **`iir_filter` is causal by default** (`zero_phase=False`): a DAC, driver or photodiode bandwidth has group delay and an unsquared magnitude response. The old default filtered forward and backward, squaring the response. Pass `zero_phase=True` for offline zero-phase filtering.
+- **`correct_timing` zero-fills by default** (`mode="zero"`); `mode="circular"` wrapped the end of a capture onto its start, right only for a periodic record.
+- **`SingleCarrierFrame` draws a fresh payload by default** (`payload_rng=None`), so a Monte Carlo loop over frames no longer repeats one payload. Pass `payload_rng=<int>` for a fixed payload; the frame keeps the seed it used, so copies, `replace()` and saved frames rebuild the same one. The pilots keep their fixed `pilot_seed`.
+- **`SingleCarrierFrame.to_signal` and `Preamble.to_signal` require `symbol_rate`** and default to `sps=1`, as `generate` does; they used to default to 1 MBd at 4 samples per symbol.
+- **One exact speed of light** (299 792 458 m/s): dispersion used 2.998e8, which moves chromatic-dispersion results by 7e-5 relative.
+
+### Changes that may need code updates
+
+- **Code sizes name their unit**: `CRC`, `ConvolutionalCode` and `TurboCode` (and `CRC.nr`, `CRC.ethernet`, `ConvolutionalCode.k7`, `TurboCode.lte`) take `info_bits` instead of `block_length`; `CCDM` takes `num_symbols`; `StaircaseCode`, `StaircaseCode.g709_2` and `Concatenated.cfec` take `blocks_per_frame` instead of `num_blocks` (which `generate` uses for codewords); `LDPCCode`'s mother length is `num_variables`; `PolarCode.nr(k=, n=)` is keyword-only. The Reed-Solomon `length` property (in code symbols) is gone: read `symbols` or `n`.
+- **`num_streams` is `num_channels`** in `SingleCarrierFrame`, `Preamble` and `Signal`.
+- **One name per concept**:
+  - `noise_var` in `zf_equalizer` and `plot_zf_equalizer_response` (was `noise_variance`); `LinewidthEstimate.awgn_var`, a phase term in rad², is `angle_noise_var`.
+  - `nfft` in `estimate_transfer_function` (was `n_fft`) and `ols_fir_filter` (was `fft_size`).
+  - `regularization` in `estimate_transfer_function` (was `reg`) and `rls` (was `delta`).
+  - `zf_equalizer(center_tap=)` (was `center`); `ols_fir_filter(causal=False)` replaces `center=True`.
+  - `num_train_symbols` and `num_impulse_samples` in the equalizer plots (were `n_train`, `n_impulse`).
+  - `HardIterations(max_iterations=)` (was `iterations`, though it stops early); `BCJR` and `TurboIterations` take `method="maxlog" | "exact"` like `compute_llr` (was `exact=False | True`).
+  - `barker_sequence` and `zadoff_chu_sequence` take `num_symbols` like `Preamble` (was `length`).
+  - `AllanDeviation.taus` matches `allan_deviation(taus=)` (was `tau_s`); `LinewidthEstimate.num_segments` (was `n_segments`).
+- **`estimate_transfer_function(received, reference)`**: the data under test first, as everywhere else (was `reference, received`).
+- **Physical units**: `apply_polarization_mixing(drift_rate=)` in rad/s with the sampling rate from the Signal (was `drift_rad_per_sample`); `Tikhonov(linewidth=)` in Hz like `apply_phase_noise`, the symbol period taken from its one-sample-per-symbol input (was `linewidth_symbol_periods`); `PLL(normalized_bandwidth=)` (was `bandwidth`), so a bandwidth in Hz cannot be passed by mistake.
+- **One entry point per concept**: the pulse objects (`RRC`, `RC`, `Gaussian`, `Rect`, `SmoothRect`) are the only way to build pulse taps; `rrc_taps`, `rc_taps`, `gaussian_taps`, `rect_taps` and `smoothrect_taps` are private, as their defaults disagreed with the objects'. `demap_symbols_hard` is `demap_symbols`, the twin of `Constellation.demap`.
+- **Polarization demultiplexing on pilot tones is an estimate / correct pair**: `estimate_polarization_tones(samples, tone_frequencies=, track_bandwidth=)` returns a `JonesTrack` (one unmixing matrix by default, or matrices tracked over time), and `correct_polarization(samples, track)` applies it. This replaces `demultiplex_polarization_tones_static` / `_dynamic`, whose return type changed with `return_matrix` and `apply`, and the public `apply_interpolated_matrix`.
+- **The optical functions read the carrier**: `apply_chromatic_dispersion`, `correct_chromatic_dispersion`, `apply_fiber_propagation` and `correct_fiber_propagation` take `center_wavelength_nm` from an optical Signal's `center_frequency`; an explicit value must agree. Arrays and other Signals must pass it: the fiber functions no longer assume 1550 nm silently.
+- **Pilots for the blind equalizers are one object**: `EqualizerPilots(values, mask, gain_db)` replaces the `pilot_ref`, `pilot_mask` and `pilot_gain_db` arguments of `cma`, `rde`, `block_cma` and `block_rde` (now `pilots=`) and the `build_pilot_ref` helper.
+
+### Added
+
+- **`Signal.center_wavelength_nm`**, the wavelength of an optical Signal's carrier.
+- **`apply_awgn(osnr_db=, reference_bandwidth=12.5e9)`** adds ASE to an optical Signal at an OSNR, counted over both polarizations in the reference bandwidth, so `Es/N0 = 2 B_ref / (p R_s) · OSNR` whatever the oversampling.
+- **`EqualizerPilots.from_frame`, `PilotAided.from_frame` and `PilotSymbols.from_frame`** take the pilot positions, symbols and gain from a `SingleCarrierFrame`.
+- **Post-FEC metrics from a `DecodeResult`**: `ber(decoded, sig)` and `fer(decoded, sig)` compare with the reference's `info_bits`, and `fer` takes the block length from the code.
+- **`estimate_noise_variance`**, the data-aided noise variance that `compute_llr`, `gmi` and `mi` take, without the round trip through `snr`.
+- **`estimate_iq_imbalance`** measures the amplitude (dB) and phase (degrees) of an IQ imbalance blindly, per channel, as an `IQImbalanceEstimate`; `correct_iq_imbalance` also takes the estimate and inverts the model exactly.
+- `SingleCarrierFrame.pilot_mask` and `payload_mask`, the symbol masks over the whole frame.
+
+### Fixed
+
+- `apply_awgn` rejects a non-positive `reference_bandwidth`.
+- `zadoff_chu_sequence`'s length error names the argument.
+
 ## [3.1.0] - 2026-10-29
 
 Review fixes and the completion of the coding release. Coded records are sized in codewords (`generate(num_blocks=)`, `SingleCarrierFrame(payload_blocks=)`) or padded to any length, the reference carries its code, `save_npz` stores everything a Signal holds (codes included), and `Signal.domain` is back. Reed-Solomon and BCH decoding run in per-codeword kernels (KP4 23 times faster on the GPU, 16 on the CPU), and the remaining decoders, LLRs and several DSP paths got faster. Correctness fixes cover bit validation in `encode`, staircase and CCDM validity, complex FIR taps, ZF precision and timing correction. Frame lengths in symbols are renamed `*_num_symbols`; see the first section.

{commkit-3.1.0 → commkit-3.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: commkit
-Version: 3.1.0
+Version: 3.1.1
 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
@@ -52,7 +52,7 @@ CommKit covers the receiver chain of coherent and IM/DD links (waveform generati
 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.
 
 - **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` and `center_frequency`. 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.
+- **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.
 - **Results with several values are frozen dataclasses** with named fields. Metrics return host floats: one per channel for `(C, N)` input.
 - **The device follows the data.** Processing functions have no `backend=` or `device=` argument. Only factories, which have no input data to follow, take `device=`: `generate(..., device="gpu")`. Move existing data with `sig.to("gpu")`.
 - **Plots draw results.** `plot_*` functions take a Signal, an array or a result object; numerical code never imports plotting.
@@ -114,17 +114,17 @@ CommKit never picks a device for you: data stays where you put it, and each func
 
 | Module | Contents |
 | --- | --- |
-| [`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 streams), `extract_payload`. |
+| [`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.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, phase noise, IQ imbalance (with 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.impairments`](https://github.com/lokgar/commkit/tree/main/commkit/impairments) | AWGN at an Es/N0 or an OSNR, 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.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`, polarization-tone demultiplexing. |
-| [`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; host values per channel. |
+| [`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.math`](https://github.com/lokgar/commkit/blob/main/commkit/math.py) | `rms`, `normalize`, dB conversions. |
 | [`commkit.smoothing`](https://github.com/lokgar/commkit/blob/main/commkit/smoothing.py) | Display and estimation smoothers (moving average, Savitzky-Golay, 2-D density). Signal-chain filters are in `filtering`. |

{commkit-3.1.0 → commkit-3.1.1}/README.md

@@ -16,7 +16,7 @@ CommKit covers the receiver chain of coherent and IM/DD links (waveform generati
 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.
 
 - **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` and `center_frequency`. 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.
+- **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.
 - **Results with several values are frozen dataclasses** with named fields. Metrics return host floats: one per channel for `(C, N)` input.
 - **The device follows the data.** Processing functions have no `backend=` or `device=` argument. Only factories, which have no input data to follow, take `device=`: `generate(..., device="gpu")`. Move existing data with `sig.to("gpu")`.
 - **Plots draw results.** `plot_*` functions take a Signal, an array or a result object; numerical code never imports plotting.
@@ -78,17 +78,17 @@ CommKit never picks a device for you: data stays where you put it, and each func
 
 | Module | Contents |
 | --- | --- |
-| [`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 streams), `extract_payload`. |
+| [`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.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, phase noise, IQ imbalance (with 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.impairments`](https://github.com/lokgar/commkit/tree/main/commkit/impairments) | AWGN at an Es/N0 or an OSNR, 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.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`, polarization-tone demultiplexing. |
-| [`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; host values per channel. |
+| [`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.math`](https://github.com/lokgar/commkit/blob/main/commkit/math.py) | `rms`, `normalize`, dB conversions. |
 | [`commkit.smoothing`](https://github.com/lokgar/commkit/blob/main/commkit/smoothing.py) | Display and estimation smoothers (moving average, Savitzky-Golay, 2-D density). Signal-chain filters are in `filtering`. |

{commkit-3.1.0 → commkit-3.1.1}/benchmarks/bench_coding.py

@@ -102,8 +102,8 @@ def _bench_decode(benchmark, xp, sync, code, method, num_codewords, esn0_db):
     ("method", "esn0_db"), [(SC(), 3.0), (SCL(8), 2.0)], ids=["sc", "scl8"]
 )
 def bench_polar_decode(benchmark, backend_device, xp, sync, method, esn0_db):
-    """PolarCode.nr(512, 1024) with the NR CRC-16, 64 codewords."""
-    code = PolarCode.nr(512, 1024, crc="16")
+    """PolarCode.nr(k=512, n=1024) with the NR CRC-16, 64 codewords."""
+    code = PolarCode.nr(k=512, n=1024, crc="16")
     _bench_decode(benchmark, xp, sync, code, method, 64, esn0_db)
 
 
@@ -114,11 +114,11 @@ def bench_viterbi_decode(benchmark, backend_device, xp, sync, termination):
     _bench_decode(benchmark, xp, sync, code, Viterbi(), 16, 5.0)
 
 
-@pytest.mark.parametrize("exact", [False, True], ids=["maxlog", "exact"])
-def bench_turbo_decode(benchmark, backend_device, xp, sync, exact):
+@pytest.mark.parametrize("method", ["maxlog", "exact"])
+def bench_turbo_decode(benchmark, backend_device, xp, sync, method):
     """TurboCode.lte(1024), 32 blocks, 6 iterations, at Es/N0 = 0 dB."""
     code = TurboCode.lte(1024)
-    _bench_decode(benchmark, xp, sync, code, TurboIterations(6, exact=exact), 32, 0.0)
+    _bench_decode(benchmark, xp, sync, code, TurboIterations(6, method=method), 32, 0.0)
 
 
 def bench_chase_decode(benchmark, backend_device, xp, sync):
@@ -131,7 +131,7 @@ def bench_chase_decode(benchmark, backend_device, xp, sync):
 
 def bench_ccdm_decode(benchmark, backend_device, xp, sync):
     """Dematching of 8 blocks of 20000 PS-64-QAM symbols (labels, no noise)."""
-    code = CCDM(Constellation.qam(64).shaped(entropy=5.0), block_length=20_000)
+    code = CCDM(Constellation.qam(64).shaped(entropy=5.0), num_symbols=20_000)
     rng = np.random.default_rng(0)
     bits = rng.integers(0, 2, 8 * code.k, dtype=np.int8)
     labels = xp.asarray(np.asarray(encode(bits, code=code)))

{commkit-3.1.0 → commkit-3.1.1}/benchmarks/bench_fiber.py

@@ -17,6 +17,7 @@ from commkit.impairments import Fiber, apply_fiber_propagation
 ROUNDS = dict(rounds=3, warmup_rounds=1, iterations=1)
 FS = 64e9
 LINK = dict(
+    center_wavelength_nm=1550.0,
     fiber=Fiber(),
     span_length_km=80.0,
     num_spans=4,

{commkit-3.1.0 → commkit-3.1.1}/benchmarks/bench_signal_pipeline.py

@@ -33,7 +33,7 @@ def _frame_signal():
         # snapped 32_768 up to, so the workload matches the 0002 baseline.
         payload_num_symbols=32_798,
         payload_constellation=Constellation.qam(16),
-        payload_seed=42,
+        payload_rng=42,
         preamble=Preamble(sequence_type="barker", num_symbols=13),
         pilot_pattern="comb",
         pilot_period=32,

{commkit-3.1.0 → commkit-3.1.1}/commkit/__init__.py

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

commkit-3.1.1/commkit/_constants.py

@@ -0,0 +1,3 @@
+"""Physical constants shared across the package."""
+
+SPEED_OF_LIGHT = 299_792_458.0  # m/s, exact (SI definition)

{commkit-3.1.0 → commkit-3.1.1}/commkit/_dispersion.py

@@ -26,12 +26,10 @@ import numpy as np
 
 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
 
-# Speed of light used by the 1.x conversion, kept so results do not change.
-_SPEED_OF_LIGHT = 2.998e8  # m/s
-
 
 def beta2_length(
     *,

{commkit-3.1.0 → commkit-3.1.1}/commkit/_sequences.py

@@ -21,7 +21,7 @@ _BARKER_SEQUENCES = {
 }
 
 
-def barker_sequence(length: int) -> np.ndarray:
+def barker_sequence(num_symbols: int) -> np.ndarray:
     """Generate a Barker sequence.
 
     Barker sequences are binary (+1, -1) sequences whose aperiodic
@@ -30,36 +30,36 @@ def barker_sequence(length: int) -> np.ndarray:
 
     Parameters
     ----------
-    length : {2, 3, 4, 5, 7, 11, 13}
-        Sequence length.
+    num_symbols : {2, 3, 4, 5, 7, 11, 13}
+        Sequence length in symbols.
 
     Returns
     -------
     ndarray
-        Host float32 BPSK symbols (+1, -1), ``(length,)``; move them with
+        Host float32 BPSK symbols (+1, -1), ``(num_symbols,)``; move them with
         ``to_device`` if needed.
 
     Raises
     ------
     ValueError
-        If the requested length is not a valid Barker length.
+        If ``num_symbols`` is not a Barker length.
 
     Examples
     --------
     >>> barker_sequence(7)
     array([ 1.,  1.,  1., -1., -1.,  1., -1.], dtype=float32)
     """
-    if length not in _BARKER_SEQUENCES:
+    if num_symbols not in _BARKER_SEQUENCES:
         valid = sorted(_BARKER_SEQUENCES.keys())
-        raise ValueError(f"No Barker sequence of length {length}. Valid: {valid}")
+        raise ValueError(f"No Barker sequence of length {num_symbols}. Valid: {valid}")
 
-    seq = np.array(_BARKER_SEQUENCES[length], dtype="float32")
+    seq = np.array(_BARKER_SEQUENCES[num_symbols], dtype="float32")
 
-    logger.debug("Generated Barker-%s sequence.", length)
+    logger.debug("Generated Barker-%s sequence.", num_symbols)
     return seq
 
 
-def zadoff_chu_sequence(length: int, *, root: int = 1) -> np.ndarray:
+def zadoff_chu_sequence(num_symbols: int, *, root: int = 1) -> np.ndarray:
     r"""Generate a Zadoff-Chu (ZC) synchronization sequence.
 
     ZC sequences are constant-amplitude zero-autocorrelation (CAZAC)
@@ -69,72 +69,72 @@ def zadoff_chu_sequence(length: int, *, root: int = 1) -> np.ndarray:
 
     Parameters
     ----------
-    length : int
+    num_symbols : int
         Sequence length ``N_ZC``; a prime gives the lowest cross-correlation
         between roots.
     root : int, default 1
-        Root index ``u`` in ``[1, length)``, coprime to ``length`` (not
+        Root index ``u`` in ``[1, num_symbols)``, coprime to ``num_symbols`` (not
         checked).
 
     Returns
     -------
     ndarray
-        Host complex64 symbols of unit magnitude, ``(length,)``.
+        Host complex64 symbols of unit magnitude, ``(num_symbols,)``.
 
     Raises
     ------
     ValueError
-        If ``length < 1`` or ``root`` is outside ``[1, length)``.
+        If ``num_symbols < 1`` or ``root`` is outside ``[1, num_symbols)``.
 
     Notes
     -----
     - For odd lengths: x[n] = exp(-j * pi * u * n * (n + 1) / N_ZC)
     - For even lengths: x[n] = exp(-j * pi * u * n^2 / N_ZC)
     """
-    if length < 1:
-        raise ValueError("Length must be positive.")
-    if root < 1 or root >= length:
-        raise ValueError(f"Root must be in [1, {length - 1}].")
+    if num_symbols < 1:
+        raise ValueError(f"num_symbols must be positive, got {num_symbols}.")
+    if root < 1 or root >= num_symbols:
+        raise ValueError(f"Root must be in [1, {num_symbols - 1}].")
 
     xp = np
 
     # ZC formula: x[n] = exp(-j * pi * u * n * (n+1) / N)
-    n = xp.arange(length)
-    if length % 2 == 0:
+    n = xp.arange(num_symbols)
+    if num_symbols % 2 == 0:
         # Even length: x[n] = exp(-j * pi * u * n^2 / N)
-        seq = xp.exp(-1j * xp.pi * root * n * n / length)
+        seq = xp.exp(-1j * xp.pi * root * n * n / num_symbols)
     else:
         # Odd length: x[n] = exp(-j * pi * u * n * (n+1) / N)
-        seq = xp.exp(-1j * xp.pi * root * n * (n + 1) / length)
+        seq = xp.exp(-1j * xp.pi * root * n * (n + 1) / num_symbols)
 
     out: np.ndarray = seq.astype(xp.complex64)
 
-    logger.debug("Generated ZC sequence: length=%s, root=%s.", length, root)
+    logger.debug("Generated ZC sequence: num_symbols=%s, root=%s.", num_symbols, root)
     return out
 
 
-def zc_mimo_root(stream_idx: int, base_root: int, length: int) -> int:
-    """Return the Zadoff-Chu root for TX stream ``stream_idx`` in a MIMO preamble.
+def zc_mimo_root(channel_index: int, base_root: int, num_symbols: int) -> int:
+    """Return the Zadoff-Chu root for channel ``channel_index`` in a MIMO preamble.
 
-    Assigns a deterministic unique root to each TX stream by cycling through
+    Assigns a deterministic unique root to each channel by cycling through
     distinct roots starting from ``base_root``, wrapping in the range
-    ``[1, length-1]``.  For prime ``length`` all roots are valid CAZAC
+    ``[1, num_symbols-1]``.  For a prime ``num_symbols`` all roots are valid CAZAC
     sequences; any two distinct roots are near-orthogonal with cross-correlation
-    magnitude ``1/sqrt(length)`` at every lag.
+    magnitude ``1/sqrt(num_symbols)`` at every lag.
 
     Parameters
     ----------
-    stream_idx : int
-        TX stream index (0-based).
+    channel_index : int
+        Channel index (0-based).
     base_root : int
-        ZC root assigned to stream 0.  Must be in ``[1, length-1]``.
-    length : int
+        ZC root assigned to channel 0.  Must be in ``[1, num_symbols-1]``.
+    num_symbols : int
         Sequence length (should be prime for the CAZAC property).
 
     Returns
     -------
     int
-        ZC root for stream ``stream_idx``, guaranteed in ``[1, length-1]``.
+        ZC root for channel ``channel_index``, guaranteed in ``[1, num_symbols-1]``.
 
     Examples
     --------
@@ -143,4 +143,4 @@ def zc_mimo_root(stream_idx: int, base_root: int, length: int) -> int:
     >>> [zc_mimo_root(k, 10, 13) for k in range(4)]
     [10, 11, 12, 1]
     """
-    return ((base_root - 1 + stream_idx) % (length - 1)) + 1
+    return ((base_root - 1 + channel_index) % (num_symbols - 1)) + 1

{commkit-3.1.0 → commkit-3.1.1}/commkit/analysis/_common.py

@@ -76,7 +76,7 @@ def _welch_median_bias(n_samples: int, nperseg: int) -> tuple[float, int]:
     -------
     factor : float
         ``median/mean`` ratio in ``(0, 1]``.
-    n_segments : int
+    num_segments : int
         Welch segment count ``K``.
     """
     step = max(nperseg // 2, 1)
@@ -269,7 +269,7 @@ def _welch_floor_bias(n_samples: int, nperseg: int, *, label: str) -> tuple[floa
     -------
     factor : float
         ``median/mean`` ratio to divide the median-based floor by.
-    n_segments : int
+    num_segments : int
         Welch segment count ``K``.
     """
     m_med, k_seg = _welch_median_bias(n_samples, nperseg)

{commkit-3.1.0 → commkit-3.1.1}/commkit/analysis/allan.py

@@ -19,14 +19,14 @@ class AllanDeviation:
 
     Attributes
     ----------
-    tau_s : numpy.ndarray
+    taus : numpy.ndarray
         Averaging times in seconds, ``(n_tau,)``.
     adev : numpy.ndarray
         Allan deviation in Hz, ``(n_tau,)`` or ``(C, n_tau)``; NaN where a
         ``tau`` does not fit the record.
     """
 
-    tau_s: np.ndarray
+    taus: np.ndarray
     adev: np.ndarray
 
 
@@ -59,7 +59,7 @@ def allan_deviation(
     Returns
     -------
     AllanDeviation
-        ``tau_s`` and ``adev``, ``(n_tau,)`` (SISO) or ``(C, n_tau)`` (MIMO),
+        ``taus`` and ``adev``, ``(n_tau,)`` (SISO) or ``(C, n_tau)`` (MIMO),
         host NumPy arrays.
 
     Notes
@@ -101,7 +101,7 @@ def allan_deviation(
         ms = np.unique(np.maximum(1, np.round(taus_cpu / tau0).astype(int)))
         ms = ms[ms <= max(1, (x.shape[-1] - 1) // 2)]
 
-    tau_s = ms * tau0
+    taus = ms * tau0
     adev = xp.full((c, ms.size), xp.nan, dtype=xp.float64)
     # One vectorized second-difference per τ across all channels (the C-loop
     # would launch C·n_tau tiny kernels on GPU for no benefit).
@@ -113,8 +113,8 @@ def allan_deviation(
         avar = xp.mean(d2**2, axis=-1) / (2.0 * (m * tau0) ** 2)
         adev[:, j] = xp.sqrt(avar)
 
-    tau_s_cpu = np.asarray(tau_s, dtype=np.float64)
+    taus_cpu = np.asarray(taus, dtype=np.float64)
     adev_cpu = to_device(adev, "cpu")
     adev_out = restore_1d(was_1d, adev_cpu)
 
-    return AllanDeviation(tau_s=tau_s_cpu, adev=adev_out)
+    return AllanDeviation(taus=taus_cpu, adev=adev_out)

{commkit-3.1.0 → commkit-3.1.1}/commkit/analysis/linewidth/dsh.py

@@ -118,7 +118,7 @@ class DshFmPsd:
     * the last term: additive detection noise.  Noise on the beat adds a
       white angle error of ``σ²`` rad² per sample, whose first difference
       has this ``≈ f²`` spectrum; it bypasses the interferometer, so ``g``
-      does not shape it (reported as ``awgn_var``).
+      does not shape it (reported as ``angle_noise_var``).
 
     The PSD is computed without the ``sinc²`` correction of
     :func:`fm_noise_psd`: sampled white FM has white increments, so its PSD is
@@ -474,9 +474,9 @@ def _dsh_fm_psd(samples: ArrayType, method: DshFmPsd, fs: float) -> LinewidthEst
         valid=valid,
         used=per_channel(used2),
         band=(float(f_used[0]), float(f_used[-1])),
-        n_segments=k_seg,
+        num_segments=k_seg,
         flicker=to_report_scalar(theta[:, 1], was_1d=was_1d),
-        awgn_var=to_report_scalar(theta[:, 2], was_1d=was_1d),
+        angle_noise_var=to_report_scalar(theta[:, 2], was_1d=was_1d),
     )
 
 
@@ -534,7 +534,7 @@ def _dsh_increment(
         value=to_report_scalar(np.maximum(slope, 0.0) / (4.0 * np.pi), was_1d=was_1d),
         method=method,
         f_shift=f_hat,
-        awgn_var=to_report_scalar(intercept, was_1d=was_1d),
+        angle_noise_var=to_report_scalar(intercept, was_1d=was_1d),
         dphi_var=to_report_scalar(to_device(dphi_var, "cpu"), was_1d=was_1d),
         lags=ls,
         lag_s=a_sec,

{commkit-3.1.0 → commkit-3.1.1}/commkit/analysis/linewidth/phase.py

@@ -247,7 +247,7 @@ def _increment_slope(
         value=to_report_scalar(np.maximum(slope, 0.0) / (2.0 * np.pi), was_1d=was_1d),
         method=method,
         dphi_var=to_report_scalar(to_device(var1, "cpu"), was_1d=was_1d),
-        awgn_var=to_report_scalar(intercept, was_1d=was_1d),
+        angle_noise_var=to_report_scalar(intercept, was_1d=was_1d),
         lag_s=lag_sec,
         var=var_k_cpu.T,
         slope=slope,
@@ -285,10 +285,10 @@ def _increment_subtract(
         d2 = normalize(d2, mode="average_power", axis=-1)
         inv = 1.0 / xp.maximum(xp.abs(d2) ** 2, 1e-12)
         pair_mean = 0.5 * (inv[:, 1:] + inv[:, :-1])
-        awgn_var = sigma_n2 * xp.mean(pair_mean, axis=-1)
+        angle_noise_var = sigma_n2 * xp.mean(pair_mean, axis=-1)
     else:
-        awgn_var = sigma_n2.copy()
-    linewidth = xp.maximum(var1 - awgn_var, 0.0) / (2.0 * np.pi * t_sym)
+        angle_noise_var = sigma_n2.copy()
+    linewidth = xp.maximum(var1 - angle_noise_var, 0.0) / (2.0 * np.pi * t_sym)
 
     var1_cpu = to_device(var1, "cpu")
     was_1d = p.ndim == 1
@@ -296,7 +296,9 @@ def _increment_subtract(
         value=to_report_scalar(to_device(linewidth, "cpu"), was_1d=was_1d),
         method=method,
         dphi_var=to_report_scalar(var1_cpu, was_1d=was_1d),
-        awgn_var=to_report_scalar(to_device(awgn_var, "cpu"), was_1d=was_1d),
+        angle_noise_var=to_report_scalar(
+            to_device(angle_noise_var, "cpu"), was_1d=was_1d
+        ),
         lag_s=np.array([t_sym]),
         var=np.atleast_1d(var1_cpu)[:, None],
     )
@@ -370,7 +372,7 @@ def _beta_separation(
         value=to_report_scalar(lw_cpu, was_1d=was_1d),
         method=method,
         linewidth_floor=to_report_scalar(lw_floor_cpu, was_1d=was_1d),
-        n_segments=k_seg,
+        num_segments=k_seg,
         area_hz2=to_report_scalar(area_cpu, was_1d=was_1d),
         f=f_cpu,
         S_f=S_cpu,

{commkit-3.1.0 → commkit-3.1.1}/commkit/analysis/linewidth/result.py

@@ -51,7 +51,7 @@ class LinewidthEstimate:
     band : tuple of float or None
         ``BetaSeparation``: the ``(f_min, f_max)`` fence applied.
         ``DshFmPsd``: the frequency extent of ``used``.
-    n_segments : int or None
+    num_segments : int or None
         Welch segment count ``K`` behind every bin (``BetaSeparation``,
         ``DshFmPsd``).
     flicker : float or numpy.ndarray or None
@@ -82,7 +82,7 @@ class LinewidthEstimate:
     slope, intercept : numpy.ndarray or None
         The fit ``var = slope * lag_s + intercept`` per channel, rad²/s and
         rad² (``IncrementSlope``, ``DshIncrement``).
-    awgn_var : float or numpy.ndarray or None
+    angle_noise_var : float or numpy.ndarray or None
         Additive-noise term in rad²: the fitted intercept (``IncrementSlope``,
         ``DshIncrement``), the subtracted term (``IncrementSubtract``) or the
         fitted angle-noise variance per sample (``DshFmPsd``).
@@ -109,7 +109,7 @@ class LinewidthEstimate:
     S_f_model: np.ndarray | None = None
     used: np.ndarray | None = None
     band: tuple[float, float] | None = None
-    n_segments: int | None = None
+    num_segments: int | None = None
     flicker: float | np.ndarray | None = None
     linewidth_floor: float | np.ndarray | None = None
     area_hz2: float | np.ndarray | None = None
@@ -122,7 +122,7 @@ class LinewidthEstimate:
     var: np.ndarray | None = None
     slope: np.ndarray | None = None
     intercept: np.ndarray | None = None
-    awgn_var: float | np.ndarray | None = None
+    angle_noise_var: float | np.ndarray | None = None
     dphi_var: float | np.ndarray | None = None
     linewidth_3db: float | np.ndarray | None = None
     lineshape_ratio: float | np.ndarray | None = None