commkit 1.0.0__tar.gz → 1.1.0__tar.gz

{commkit-1.0.0 → commkit-1.1.0}/CLAUDE.md

@@ -78,7 +78,7 @@ uv run pytest benchmarks/ --benchmark-only --device=all \
     --benchmark-compare=0001 --benchmark-storage=file://benchmarks/baselines
 ```
 
-See **Section 6 - Benchmark Suite** for what each file measures and how to read the results.
+See **Section 5 - Benchmark Suite** for what each file measures and how to read the results.
 
 ### Linting & Formatting
 
@@ -153,37 +153,7 @@ Since `bump-my-version` is defined in the project's development dependencies, al
 
 ---
 
-## 3. Reference Implementation Files
-
-> `examples/` holds notebook-style scripts (jupytext `# %%` cell format, ready
-> to convert to `.ipynb`) that walk through a full analysis chain end-to-end
-> with the physics, method limitations, and interpretation of the results
-> spelled out in markdown cells:
->
-> * `examples/carrier_phase_analysis.py` - data-aided carrier-phase
->   characterization of a coherent transmission (trajectory -> drift/PN split ->
->   linewidth -> Allan -> dashboard).
-> * `examples/laser_linewidth_dsh.py` - delayed self-heterodyne (AOM receiver)
->   laser linewidth and FM-noise PSD estimation (all three estimators, both
->   coherence regimes, flicker-noise effects).
-> * `examples/laser_linewidth_homodyne_iq.py` - the decoherence interferometer
->   with a 90°-hybrid IQ receiver (no AOM) as the main path: dark-capture DC
->   calibration, GSOP, all three estimators at 0 Hz, discriminator Allan
->   deviation.
-> * `examples/measurement_laser_linewidth_dsh.py` /
->   `examples/measurement_laser_linewidth_homodyne_iq.py` - **measurement
->   templates**: edit the system-parameter cell, point `DATA_FILE` at a real
->   capture, run.  Include τ_d calibration from the notch comb (DSH) and a
->   seeded synthetic demo fallback so they run end-to-end without data.
->
-> Examples are **runners, not library code**: orchestration chains belong in
-> `examples/` (or user projects), never as `commkit` functions.  For
-> everything not yet covered by an example, `tests/` is the most current usage
-> reference for every public function.
-
----
-
-## 4. DSP & Coding Guidelines
+## 3. DSP & Coding Guidelines
 
 ### Multi-Backend Dispatching
 
@@ -264,6 +234,151 @@ Inside library code, **never extract a scalar from a possibly-GPU array inside a
 * **SISO**: 1-D array: `(N_samples,)`
 * **MIMO**: 2-D array: `(N_channels, N_samples)` - **time is always on the last axis**.
 
+Never hand-roll the promote/squeeze idiom.  `commkit/helpers.py` owns it, so the
+validation is identical everywhere (0-d and 3-D inputs raise a shape error
+naming the offending argument instead of silently reaching a confusing
+broadcast failure downstream):
+
+```python
+from commkit.helpers import as_2d, broadcast_channels, require_channels, restore_1d
+
+def my_dsp_function(samples, ref_symbols):
+    x, xp, _ = dispatch(samples)
+    x2, was_1d = as_2d(x, name="samples")             # (N,) -> (1, N)
+    ref = broadcast_channels(xp.asarray(ref_symbols),  # (L,) / (1, L) -> (C, L)
+                             x2.shape[0], xp, name="ref_symbols")
+    out = ...                                          # channel-batched body
+    return restore_1d(was_1d, out)                     # squeeze back for SISO
+```
+
+* `as_2d` / `restore_1d` - the promote/squeeze pair.  `restore_1d` takes several
+  outputs at once: `drift, pn = restore_1d(was_1d, drift, pn)`.
+* `broadcast_channels` - a shared reference across channels, with the
+  channel-count check the bare `ref[None, :]` promotion lacks.  Returns a
+  **read-only** broadcast view; `.copy()` before writing.
+* `require_channels` - for entry points defined only at a fixed channel count
+  (dual-pol channel models); pass `description=` to keep domain wording in the
+  error.
+* `to_report_scalar` - the reporting-layer counterpart: collapses a `(C,)`
+  metric to a Python float for SISO, transferring from device if needed.
+* `linear_trend_slope` / `remove_linear_trend` - the per-channel least-squares
+  slope shared by the pilot-tone and DSH detrend stages; keeps `Σ(x-x̄)²` on
+  device rather than syncing it back as a float.
+
+Note these are plain indexing/broadcast helpers, valid on NumPy, CuPy **and**
+JAX arrays - unlike `dispatch`, which recognizes NumPy/CuPy only and will
+silently pull a JAX array to the host.
+
+### Signal-Awareness
+
+Any new DSP function whose primary argument is genuinely **signal-representable
+data** (raw IQ samples, or a field a `Signal` actually carries, like
+`resolved_symbols`) should accept a `Signal` alongside a raw array, transparently:
+array in → array out, `Signal` in → `Signal` out.  Use the same idiom
+everywhere, defined once in `commkit/helpers.py`:
+
+```python
+from commkit.helpers import unwrap_signal, rewrap_signal
+
+def fir_filter(samples, taps, axis=-1):
+    x, sig = unwrap_signal(samples)          # x: array; sig: Signal | None
+    if sig is not None:
+        return rewrap_signal(sig, fir_filter(x, taps, axis=-1))
+    ... existing array-only body, unchanged ...
+```
+
+* `unwrap_signal(x, *, field="samples")` - returns `(array, signal_or_None)`.
+  Most functions read `.samples`; a few (hard-decision demapping, phase-rotation
+  correction on `resolved_symbols`) pass `field=` to read a different attribute.
+* `rewrap_signal(sig, array, **metadata)` - `sig=None` passes `array` through
+  unchanged; otherwise returns `sig.copy()` with `.samples = array` and any
+  `**metadata` kwargs applied via `setattr` (e.g. `sampling_rate=sig.symbol_rate`
+  after decimating to symbol rate).
+
+**Metadata priority: the `Signal`'s own value always wins.** When a function
+takes both a `Signal` and a scalar metadata parameter that duplicates one of
+its fields (`sampling_rate`, `sps`, `mod_scheme`, `mod_order`, `ps_pmf`,
+...), the `Signal`'s field - never the supplied argument - is what the
+Signal-branch call actually uses. A caller passing a conflicting value on a
+`Signal` is a bug to catch, not a request to honor: silently letting the
+supplied value win would let a signal at 2 GSa/s be equalized with a stale
+`sps=2` nobody meant to apply to it.
+
+There is no shared helper for this - both cases are short enough to write
+inline in the `if sig is not None:` branch, and a generic helper covering
+both the "always wins" and "falls back with a warning" behaviors in one call
+signature ends up harder to read at the call site than the few extra lines.
+
+* **Required fields** (`sampling_rate`, `symbol_rate`, and the derived `sps`)
+  are never `None` on a `Signal` - pydantic enforces it - so the Signal
+  branch references `sig.sampling_rate`/`sig.sps` directly and drops the
+  supplied argument entirely.  There is no case where the Signal is missing
+  the field, but the caller can still pass a stale/conflicting value by
+  mistake, so warn whenever one was supplied at all:
+
+  ```python
+  x, sig = unwrap_signal(samples)
+  if sig is not None:
+      # sig.sampling_rate is required, so it always wins over a supplied
+      # sampling_rate - see CLAUDE.md, "Signal-Awareness".
+      if sampling_rate is not None:
+          logger.warning(
+              "my_dsp_function(): ignoring supplied sampling_rate=%r for "
+              "Signal input; using the signal's own sampling_rate=%r instead.",
+              sampling_rate,
+              sig.sampling_rate,
+          )
+      return my_dsp_function(x, sig.sampling_rate, ...)
+  ```
+
+* **Optional fields** (`mod_scheme`, `mod_order`, `ps_pmf`, ...) can
+  legitimately be unset on a `Signal` (e.g. an unshaped QAM signal has
+  `ps_pmf=None`). Read the Signal's field first; fall back to the supplied
+  argument - logging a `logger.warning` - only when the Signal genuinely
+  lacks it *and* a fallback was supplied. Passing neither stays silent (the
+  common case), so the log isn't spammed on every call to an unshaped signal:
+
+  ```python
+  mod = sig.mod_scheme
+  if mod is None:
+      mod = modulation
+      if mod is not None:
+          logger.warning(
+              "my_dsp_function(): Signal has no mod_scheme set; falling "
+              "back to supplied modulation=%r.", mod,
+          )
+  ```
+
+**Metadata rules for functions that change rate or domain:**
+
+| Situation | What to pass `rewrap_signal` |
+| --- | --- |
+| Shape/rate unchanged (most `apply_*`/`correct_*`) | `rewrap_signal(sig, result)` - no metadata |
+| Decimates to one sample/symbol (equalizers) | `sampling_rate=sig.symbol_rate` |
+| Upsamples by an integer factor | `sampling_rate=sig.sampling_rate * factor` |
+| Resamples to an explicit target rate | `sampling_rate=<the target rate param>` |
+| Output field differs from the input field (`resolve_symbols`, `demap_symbols_hard`) | Skip `rewrap_signal`; `sig.copy()` + `setattr` by hand - the one sanctioned exception |
+| Returns a scalar/dict/tuple in a different domain (frequency/tau/PSD bins, phase or frequency *estimates*) | `unwrap_signal` only, on the input - never wrap the output |
+
+**Not every array parameter is signal-representable.** A function that
+consumes a *derived* quantity - a phase or frequency trajectory, a
+correlation array, PSD bins, an `EqualizerResult`, filter taps - one or more
+stages downstream of the original capture has no sound field to unwrap from;
+forcing Signal-awareness there is backwards, since there is no `Signal` yet
+(or any more) to preserve metadata from.  `smooth_phase_wiener`,
+`estimate_fractional_delay`, `allan_deviation`, and every `plot_*` function
+in `plotting/{analysis,equalizer,sync}.py` are examples: they take arrays a
+`Signal` would never hold as `.samples`, so they stay plain-array functions.
+Likewise, a function whose only job is to build the data a `Signal` gets
+constructed *from* is a synthesis primitive, not a transform on existing
+`Signal` data - same exclusion as `generate_*`.  `core/generation.py`'s
+`shape_pulse`/`expand` (TX symbol -> waveform) and
+`equalization.build_pilot_ref` (sparse pilots -> dense equalizer reference)
+are the current examples; note that `shape_pulse`/`expand` live in
+`core/generation.py` rather than `filtering.py`/`multirate.py` for exactly
+this reason - they build the samples a `Signal` gets constructed from, not
+transform an existing one.
+
 ### Naming Conventions
 
 * **Verb prefixes for processing functions.** Recovery/correction routines follow a
@@ -296,9 +411,38 @@ Inside library code, **never extract a scalar from a possibly-GPU array inside a
   modules and `plotting`. Never add a bare-noun plot function that shadows a
   compute function.
 
+### Design-vs-Apply Separation
+
+For any DSP building block with distinct "design" and "apply" phases - a
+coefficient/parameter generator, and a step that consumes those coefficients
+against data - keep the two as separate functions rather than one function
+that does both internally.  This lets a caller design once and apply many
+times (e.g. reuse the same filter across a batch of signals) and keeps each
+function's signature focused.  Established examples in `filtering.py`:
+
+* FIR taps generators (`rrc_taps`, `rc_taps`, `gaussian_taps`, `fir_taps`
+  (lowpass/highpass/bandpass/bandstop via `btype=`), ...) produce coefficient
+  arrays; `fir_filter(samples, taps)` applies them.
+* IIR SOS generators (`butterworth_sos`, `chebyshev1_sos`, `chebyshev2_sos`,
+  `elliptic_sos`, `bessel_sos`) produce second-order-section coefficients;
+  `iir_filter(samples, sos)` applies them.
+
+New DSP building blocks with a design/apply split should follow this same
+two-function pattern rather than folding both steps into one.
+
+`filtering.py` vs. `smoothing.py`: `filtering.py` holds real signal-chain
+filters (the design/apply pairs above, matched filtering, Overlap-Save) with
+an actual frequency response and causality claim.  `smoothing.py` holds
+diagnostic/plotting-only smoothers (`moving_average`, `savgol_smooth`,
+`smooth_density_2d`) - non-causal, no frequency-response meaning, used only
+to make a plotted curve or a robust estimate less noisy.  A routine that
+removes/passes a frequency band as part of the signal chain itself belongs in
+`filtering.py`; a routine that only exists to smooth something for display or
+a peak search belongs in `smoothing.py`.
+
 ---
 
-## 5. Testing Conventions
+## 4. Testing Conventions
 
 * **Parametrization**: Test cases must utilize `backend_device` and `xp` fixtures from `conftest.py` to automatically validate code correctness on both CPU and GPU backends.
 * **Assertions**: Standard `numpy.testing` assertions raise `TypeError` when evaluated on GPU arrays. Always use the `xpt` helper assertion module. Use `xp.asarray(expected)` to cast expectation variables to the active backend, and cast reductions to standard Python scalars before comparison:
@@ -318,10 +462,19 @@ Inside library code, **never extract a scalar from a possibly-GPU array inside a
     `test_winit.py`, `test_linear.py` (zf/MMSE), `test_polarization.py`,
     `test_blind.py` + `test_block_update.py` (block_cma/block_rde),
     `test_block.py` (block_lms / FDAF), `test_cpr.py`, and the CUDA-kernel tests
-    `test_bps_kernel.py` / `test_cs_kernel.py`.
+    `test_bps_kernel.py` / `test_cs_kernel.py`.  `sequential.py` and `_block.py`
+    are themselves subpackages internally (`sequential/_dd.py` + `_blind.py`;
+    `_block/_seqmode.py` + `_dd.py` + `_blind.py`) per the module-splitting
+    trigger below - the test files above are unaffected since they exercise
+    the public `commkit.equalization` surface, not these internal module
+    paths (a handful of `patch()`/`monkeypatch` targets in `test_block.py` /
+    `test_sequential_jax.py` do reach into the internal paths and were
+    updated when the split landed).
   * `tests/recovery/` <-> `commkit/recovery/` - `test_viterbi_viterbi.py`,
     `test_bps.py`, `test_pilots.py`, `test_tikhonov.py`, `test_pll.py`,
-    `test_corrections.py`, plus `test_joint.py` for the cross-algorithm
+    `test_corrections.py` (also covers `recovery/_common.py`'s shared
+    `_vv_block_phase` block-phase estimator and `_log_phase_summary` CPR
+    diagnostic logger), plus `test_joint.py` for the cross-algorithm
     joint-channel consistency checks.
   * `tests/core/` <-> `commkit/core/` - `test_signal.py`, `test_signal_mimo.py`,
     `test_frame.py` (`Preamble`/`SingleCarrierFrame`), `test_psqam.py` (generation).
@@ -336,8 +489,8 @@ Inside library code, **never extract a scalar from a possibly-GPU array inside a
   * `tests/mapping/` <-> `commkit/mapping/` - `test_gray.py`, `test_bits.py`,
     `test_llr.py`, `test_constellation.py` (the `Constellation` value object).
     Probabilistic-shaping tests live in `tests/core/test_psqam.py`.
-  * Flat modules (`filtering`, `metrics`, `spectral`, `timing`, `frequency`, ...)
-    keep a single top-level `tests/test_<module>.py`.
+  * Flat modules (`filtering`, `metrics`, `spectral`, `timing`, `frequency`,
+    `smoothing`, ...) keep a single top-level `tests/test_<module>.py`.
 
   When a single module's test file grows unwieldy, split it by *concern* within
   the same subpackage (e.g. sequential vs. JAX vs. MIMO) rather than letting one
@@ -355,7 +508,7 @@ Inside library code, **never extract a scalar from a possibly-GPU array inside a
 
 ---
 
-## 6. Benchmark Suite
+## 5. Benchmark Suite
 
 The `benchmarks/` directory tracks the performance of the GPU-relevant hot paths. Baselines are committed under `benchmarks/baselines/` so any optimization PR can be gated quantitatively (run -> compare -> quote the delta).
 

{commkit-1.0.0 → commkit-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: commkit
-Version: 1.0.0
+Version: 1.1.0
 Summary: A Python library for high-performance digital communications research.
 License: MIT
 License-File: LICENSE
@@ -12,6 +12,11 @@ Requires-Dist: numpy>=2.4
 Requires-Dist: pydantic>=2.13
 Requires-Dist: pyyaml>=6.0.2
 Requires-Dist: scipy>=1.17
+Provides-Extra: full
+Requires-Dist: cupy-cuda13x>=14.1; extra == 'full'
+Requires-Dist: jax[cuda13]>=0.10; extra == 'full'
+Requires-Dist: jupyter>=1.1.1; extra == 'full'
+Requires-Dist: nvidia-curand>=10.4.1.34; extra == 'full'
 Provides-Extra: gpu
 Requires-Dist: cupy-cuda13x>=14.1; extra == 'gpu'
 Requires-Dist: jax[cuda13]>=0.10; extra == 'gpu'
@@ -39,7 +44,7 @@ CommKit is a Python library for digital communications research that treats hard
 
 - **One object, complete context:** Sampling rate, symbol rate, modulation format, and pulse shape travel with the signal through the processing pipeline.
 - **Backend-transparent DSP:** `dispatch()` resolves NumPy, CuPy, or SciPy modules at runtime. The same code executes seamlessly on CPU or GPU.
-- **Method chaining:** High-level fluent API (`sig.to("gpu").fir_filter(taps).resample(sps_out=2)...`) for rapid prototyping.
+- **Functional pipelines:** DSP functions accept and return a `Signal` directly (`sig = fir_filter(sig, taps)`; `sig = resample(sig, sps_out=2)`), so pipelines compose without a monolithic `Signal` wrapper API - `sig.to("gpu")` moves data across backends, the rest is plain function composition.
 - **JAX escape hatch:** Zero-copy DLPack export on GPU allows direct application of JAX transforms (gradients, `vmap`, `scan`) without leaving the research loop.
 
 ---
@@ -48,23 +53,24 @@ CommKit is a Python library for digital communications research that treats hard
 
 | Module | Key Capabilities & Features |
 | --- | --- |
-| [`commkit.core`](commkit/core) | `Signal` container (IQ samples + metadata), `SingleCarrierFrame`, `Preamble`, and symbol/frame factories (PAM, PSK, QAM). |
+| [`commkit.core`](commkit/core) | `Signal` container (IQ samples + metadata), `SingleCarrierFrame`, `Preamble`, and symbol/frame factories (PAM, PSK, QAM, PS-QAM). |
 | [`commkit.backend`](commkit/backend.py) | Hardware abstraction layer (`dispatch`, `to_device`, `to_jax`, `from_jax`), placement management, and backend execution (NumPy, CuPy, JAX). |
-| [`commkit.mapping`](commkit/mapping) | Gray-coded constellations, symbol mapping, hard demapping, soft LLR computation (max-log and exact log-sum-exp via JAX JIT), and GMI. |
-| [`commkit.filtering`](commkit/filtering.py) | Pulse shaping (RRC, RC, Gaussian, Smooth-Rectangle), tap generators, matched filtering, Overlap-Save, and polyphase multirate filtering. |
+| [`commkit.mapping`](commkit/mapping) | Gray-coded constellations, symbol mapping, hard demapping, soft LLR computation (max-log and exact log-sum-exp via JAX JIT), and probabilistic shaping (Maxwell-Boltzmann). |
+| [`commkit.filtering`](commkit/filtering.py) | Pulse shaping (RRC, RC, Gaussian, Smooth-Rectangle), FIR tap generators, IIR SOS filter design (Butterworth, Chebyshev I/II, elliptic, Bessel) and application, matched filtering, and Overlap-Save. |
 | [`commkit.multirate`](commkit/multirate.py) | Fractional and integer sample rate conversion (`resample`, `decimate`, `upsample`, `decimate_to_symbol_rate`). |
 | [`commkit.timing`](commkit/timing.py) | Preamble generation (Barker, Zadoff-Chu), cross-correlation timing delay estimation, and frame alignment. |
-| [`commkit.frequency`](commkit/frequency.py) | Carrier frequency offset estimation (FOE via M-th power, Mengali-Morelli, Jacobsen) and phase-locked FOE correction. |
-| [`commkit.recovery`](commkit/recovery) | Carrier phase recovery (CPR via Viterbi-Viterbi, BPS, DD-PLL) and cycle-slip detection/correction. |
-| [`commkit.equalization`](commkit/equalization) | Adaptive equalizers (`lms`, `rls`, `cma`, `rde`, `zf`), butterfly MIMO topology support, with Numba JIT and JAX execution backends. |
-| [`commkit.impairments`](commkit/impairments) | Channel impairments simulation: AWGN (with SPS correction), PMD (differential group delay, Jones matrix), phase noise, IQ imbalance, and chromatic dispersion. |
-| [`commkit.coding`](commkit/coding) | Channel coding and FEC primitives (BCH, Convolutional, CRC, Galois field arithmetic, Hamming, Interleaving, LDPC, Polar, Rate matching, Reed-Solomon, Turbo codes). |
-| [`commkit.metrics`](commkit/metrics.py) | System performance evaluation: EVM (%, dB), data-aided SNR, and BER estimation. |
+| [`commkit.frequency`](commkit/frequency.py) | Carrier frequency offset estimation (FOE via M-th power, Mengali-Morelli, pilot-symbol, bias-tone) and static/blockwise time-varying FOE correction. |
+| [`commkit.recovery`](commkit/recovery) | Carrier phase recovery (CPR via Viterbi-Viterbi, BPS, DD-PLL, MAP Tikhonov-RTS, pilot-symbol/pilot-tone), cycle-slip detection/correction, and phase/channel-permutation ambiguity resolution. |
+| [`commkit.equalization`](commkit/equalization) | Sequential (`lms`, `rls`, `cma`, `rde`) and frequency-domain block (`block_lms`, `block_cma`, `block_rde`) adaptive equalizers, `zf_equalizer`, butterfly MIMO topology support, and polarization-tone demultiplexing, with Numba JIT and JAX execution backends. |
+| [`commkit.impairments`](commkit/impairments) | Channel impairments simulation: AWGN (with SPS correction), PMD (differential group delay, Jones matrix), phase noise, IQ imbalance (application + Löwdin/Gram-Schmidt compensation), and chromatic dispersion. |
+| [`commkit.coding`](commkit/coding) | **Planned, not yet implemented** - scaffold-only placeholders reserving the layout for channel coding / FEC primitives (BCH, Convolutional, CRC, Galois field arithmetic, Hamming, Interleaving, LDPC, Polar, Rate matching, Reed-Solomon, Turbo codes). |
+| [`commkit.metrics`](commkit/metrics.py) | System performance evaluation: EVM, SNR, BER, SER, and capacity metrics (GMI, MI) with PS-QAM support. |
 | [`commkit.analysis`](commkit/analysis) | Laser phase and linewidth characterization: DSH, homodyne IQ, zero-phase drift detrending, AWGN-free lag-slope linewidth fit, Di Domenico $\beta$-separation line FWHM, and Allan deviation. |
-| [`commkit.spectral`](commkit/spectral.py) | Welch PSD estimation and frequency shifting with bin-quantized mixing. |
+| [`commkit.spectral`](commkit/spectral.py) | Welch PSD estimation, spectrograms, and frequency shifting with bin-quantized mixing. |
+| [`commkit.smoothing`](commkit/smoothing.py) | Diagnostic/plotting-only smoothers (moving average, Savitzky-Golay, 2-D density smoothing) - not signal-chain filters; see `commkit.filtering` for those. |
 | [`commkit.io`](commkit/io.py) | Signal persistence and disk serialization (`load_npz`, `save_npz`). |
-| [`commkit.plotting`](commkit/plotting) | Visualization tools for constellations, eye diagrams, PSDs, time-domain signals, filter responses, and equalizer convergence. |
-| [`commkit.helpers`](commkit/helpers.py) | General DSP helpers: random bit/symbol generators, array normalization, RMS calculation, and SI prefix formatting. |
+| [`commkit.plotting`](commkit/plotting) | Visualization tools for constellations, eye diagrams, PSDs/spectrograms, time-domain signals, filter responses, equalizer convergence, and sync/CPR diagnostics (timing correlation, FOE spectra, carrier-phase trajectories). |
+| [`commkit.helpers`](commkit/helpers.py) | General DSP helpers: random bit/symbol generators, array normalization, RMS calculation, dB<->linear conversion, and SI prefix formatting. |
 
 ---
 
@@ -76,10 +82,10 @@ CommKit is a Python library for digital communications research that treats hard
 
 ```bash
 # Using uv (Recommended)
-uv pip install git+https://github.com/lokgar/commkit.git
+uv pip install commkit
 
 # Or with standard pip
-pip install git+https://github.com/lokgar/commkit.git
+pip install commkit
 ```
 
 ### GPU Support
@@ -88,10 +94,10 @@ To install with CUDA acceleration (includes JAX CUDA 13 and CuPy stacks):
 
 ```bash
 # Using uv
-uv pip install "commkit[gpu] @ git+https://github.com/lokgar/commkit.git"
+uv pip install "commkit[gpu]"
 
 # Or with standard pip
-pip install "commkit[gpu] @ git+https://github.com/lokgar/commkit.git"
+pip install "commkit[gpu]"
 ```
 
 > [!NOTE]
@@ -104,6 +110,20 @@ pip install "commkit[gpu] @ git+https://github.com/lokgar/commkit.git"
 >
 > *(Assumes `commkit` is cloned in `$HOME/commkit`. If located elsewhere, replace `$HOME/commkit` with `<path-to-repo>`. `python3.*/` matches any Python version automatically).*
 
+### Notebook Support
+
+To run the example notebooks and enable the rich HTML `Signal.print_info()` table (falls back to plain text without it):
+
+```bash
+# Using uv
+uv pip install "commkit[notebook]"
+
+# Or with standard pip
+pip install "commkit[notebook]"
+```
+
+Extras can be combined, e.g. `commkit[gpu,notebook]`, or install everything at once with `commkit[full]`.
+
 ### Development Installation
 
 ```bash
@@ -113,7 +133,7 @@ cd commkit
 # Sync core environment
 uv sync
 
-# Sync environment with all extras (including GPU packages)
+# Sync environment with all extras (including GPU and notebook packages)
 uv sync --all-extras
 ```
 

{commkit-1.0.0 → commkit-1.1.0}/README.md

@@ -17,7 +17,7 @@ CommKit is a Python library for digital communications research that treats hard
 
 - **One object, complete context:** Sampling rate, symbol rate, modulation format, and pulse shape travel with the signal through the processing pipeline.
 - **Backend-transparent DSP:** `dispatch()` resolves NumPy, CuPy, or SciPy modules at runtime. The same code executes seamlessly on CPU or GPU.
-- **Method chaining:** High-level fluent API (`sig.to("gpu").fir_filter(taps).resample(sps_out=2)...`) for rapid prototyping.
+- **Functional pipelines:** DSP functions accept and return a `Signal` directly (`sig = fir_filter(sig, taps)`; `sig = resample(sig, sps_out=2)`), so pipelines compose without a monolithic `Signal` wrapper API - `sig.to("gpu")` moves data across backends, the rest is plain function composition.
 - **JAX escape hatch:** Zero-copy DLPack export on GPU allows direct application of JAX transforms (gradients, `vmap`, `scan`) without leaving the research loop.
 
 ---
@@ -26,23 +26,24 @@ CommKit is a Python library for digital communications research that treats hard
 
 | Module | Key Capabilities & Features |
 | --- | --- |
-| [`commkit.core`](commkit/core) | `Signal` container (IQ samples + metadata), `SingleCarrierFrame`, `Preamble`, and symbol/frame factories (PAM, PSK, QAM). |
+| [`commkit.core`](commkit/core) | `Signal` container (IQ samples + metadata), `SingleCarrierFrame`, `Preamble`, and symbol/frame factories (PAM, PSK, QAM, PS-QAM). |
 | [`commkit.backend`](commkit/backend.py) | Hardware abstraction layer (`dispatch`, `to_device`, `to_jax`, `from_jax`), placement management, and backend execution (NumPy, CuPy, JAX). |
-| [`commkit.mapping`](commkit/mapping) | Gray-coded constellations, symbol mapping, hard demapping, soft LLR computation (max-log and exact log-sum-exp via JAX JIT), and GMI. |
-| [`commkit.filtering`](commkit/filtering.py) | Pulse shaping (RRC, RC, Gaussian, Smooth-Rectangle), tap generators, matched filtering, Overlap-Save, and polyphase multirate filtering. |
+| [`commkit.mapping`](commkit/mapping) | Gray-coded constellations, symbol mapping, hard demapping, soft LLR computation (max-log and exact log-sum-exp via JAX JIT), and probabilistic shaping (Maxwell-Boltzmann). |
+| [`commkit.filtering`](commkit/filtering.py) | Pulse shaping (RRC, RC, Gaussian, Smooth-Rectangle), FIR tap generators, IIR SOS filter design (Butterworth, Chebyshev I/II, elliptic, Bessel) and application, matched filtering, and Overlap-Save. |
 | [`commkit.multirate`](commkit/multirate.py) | Fractional and integer sample rate conversion (`resample`, `decimate`, `upsample`, `decimate_to_symbol_rate`). |
 | [`commkit.timing`](commkit/timing.py) | Preamble generation (Barker, Zadoff-Chu), cross-correlation timing delay estimation, and frame alignment. |
-| [`commkit.frequency`](commkit/frequency.py) | Carrier frequency offset estimation (FOE via M-th power, Mengali-Morelli, Jacobsen) and phase-locked FOE correction. |
-| [`commkit.recovery`](commkit/recovery) | Carrier phase recovery (CPR via Viterbi-Viterbi, BPS, DD-PLL) and cycle-slip detection/correction. |
-| [`commkit.equalization`](commkit/equalization) | Adaptive equalizers (`lms`, `rls`, `cma`, `rde`, `zf`), butterfly MIMO topology support, with Numba JIT and JAX execution backends. |
-| [`commkit.impairments`](commkit/impairments) | Channel impairments simulation: AWGN (with SPS correction), PMD (differential group delay, Jones matrix), phase noise, IQ imbalance, and chromatic dispersion. |
-| [`commkit.coding`](commkit/coding) | Channel coding and FEC primitives (BCH, Convolutional, CRC, Galois field arithmetic, Hamming, Interleaving, LDPC, Polar, Rate matching, Reed-Solomon, Turbo codes). |
-| [`commkit.metrics`](commkit/metrics.py) | System performance evaluation: EVM (%, dB), data-aided SNR, and BER estimation. |
+| [`commkit.frequency`](commkit/frequency.py) | Carrier frequency offset estimation (FOE via M-th power, Mengali-Morelli, pilot-symbol, bias-tone) and static/blockwise time-varying FOE correction. |
+| [`commkit.recovery`](commkit/recovery) | Carrier phase recovery (CPR via Viterbi-Viterbi, BPS, DD-PLL, MAP Tikhonov-RTS, pilot-symbol/pilot-tone), cycle-slip detection/correction, and phase/channel-permutation ambiguity resolution. |
+| [`commkit.equalization`](commkit/equalization) | Sequential (`lms`, `rls`, `cma`, `rde`) and frequency-domain block (`block_lms`, `block_cma`, `block_rde`) adaptive equalizers, `zf_equalizer`, butterfly MIMO topology support, and polarization-tone demultiplexing, with Numba JIT and JAX execution backends. |
+| [`commkit.impairments`](commkit/impairments) | Channel impairments simulation: AWGN (with SPS correction), PMD (differential group delay, Jones matrix), phase noise, IQ imbalance (application + Löwdin/Gram-Schmidt compensation), and chromatic dispersion. |
+| [`commkit.coding`](commkit/coding) | **Planned, not yet implemented** - scaffold-only placeholders reserving the layout for channel coding / FEC primitives (BCH, Convolutional, CRC, Galois field arithmetic, Hamming, Interleaving, LDPC, Polar, Rate matching, Reed-Solomon, Turbo codes). |
+| [`commkit.metrics`](commkit/metrics.py) | System performance evaluation: EVM, SNR, BER, SER, and capacity metrics (GMI, MI) with PS-QAM support. |
 | [`commkit.analysis`](commkit/analysis) | Laser phase and linewidth characterization: DSH, homodyne IQ, zero-phase drift detrending, AWGN-free lag-slope linewidth fit, Di Domenico $\beta$-separation line FWHM, and Allan deviation. |
-| [`commkit.spectral`](commkit/spectral.py) | Welch PSD estimation and frequency shifting with bin-quantized mixing. |
+| [`commkit.spectral`](commkit/spectral.py) | Welch PSD estimation, spectrograms, and frequency shifting with bin-quantized mixing. |
+| [`commkit.smoothing`](commkit/smoothing.py) | Diagnostic/plotting-only smoothers (moving average, Savitzky-Golay, 2-D density smoothing) - not signal-chain filters; see `commkit.filtering` for those. |
 | [`commkit.io`](commkit/io.py) | Signal persistence and disk serialization (`load_npz`, `save_npz`). |
-| [`commkit.plotting`](commkit/plotting) | Visualization tools for constellations, eye diagrams, PSDs, time-domain signals, filter responses, and equalizer convergence. |
-| [`commkit.helpers`](commkit/helpers.py) | General DSP helpers: random bit/symbol generators, array normalization, RMS calculation, and SI prefix formatting. |
+| [`commkit.plotting`](commkit/plotting) | Visualization tools for constellations, eye diagrams, PSDs/spectrograms, time-domain signals, filter responses, equalizer convergence, and sync/CPR diagnostics (timing correlation, FOE spectra, carrier-phase trajectories). |
+| [`commkit.helpers`](commkit/helpers.py) | General DSP helpers: random bit/symbol generators, array normalization, RMS calculation, dB<->linear conversion, and SI prefix formatting. |
 
 ---
 
@@ -54,10 +55,10 @@ CommKit is a Python library for digital communications research that treats hard
 
 ```bash
 # Using uv (Recommended)
-uv pip install git+https://github.com/lokgar/commkit.git
+uv pip install commkit
 
 # Or with standard pip
-pip install git+https://github.com/lokgar/commkit.git
+pip install commkit
 ```
 
 ### GPU Support
@@ -66,10 +67,10 @@ To install with CUDA acceleration (includes JAX CUDA 13 and CuPy stacks):
 
 ```bash
 # Using uv
-uv pip install "commkit[gpu] @ git+https://github.com/lokgar/commkit.git"
+uv pip install "commkit[gpu]"
 
 # Or with standard pip
-pip install "commkit[gpu] @ git+https://github.com/lokgar/commkit.git"
+pip install "commkit[gpu]"
 ```
 
 > [!NOTE]
@@ -82,6 +83,20 @@ pip install "commkit[gpu] @ git+https://github.com/lokgar/commkit.git"
 >
 > *(Assumes `commkit` is cloned in `$HOME/commkit`. If located elsewhere, replace `$HOME/commkit` with `<path-to-repo>`. `python3.*/` matches any Python version automatically).*
 
+### Notebook Support
+
+To run the example notebooks and enable the rich HTML `Signal.print_info()` table (falls back to plain text without it):
+
+```bash
+# Using uv
+uv pip install "commkit[notebook]"
+
+# Or with standard pip
+pip install "commkit[notebook]"
+```
+
+Extras can be combined, e.g. `commkit[gpu,notebook]`, or install everything at once with `commkit[full]`.
+
 ### Development Installation
 
 ```bash
@@ -91,7 +106,7 @@ cd commkit
 # Sync core environment
 uv sync
 
-# Sync environment with all extras (including GPU packages)
+# Sync environment with all extras (including GPU and notebook packages)
 uv sync --all-extras
 ```