commkit 3.1.2__tar.gz → 3.1.3__tar.gz

{commkit-3.1.2 → commkit-3.1.3}/CHANGELOG.md

@@ -4,6 +4,27 @@ Notable changes to CommKit, newest first. Performance figures are from the refer
 
 ## [Unreleased]
 
+## [3.1.3] - 2026-10-30
+
+Additive noise without a scaling knob. `apply_awgn` either measures the signal or takes an absolute noise variance, and the OSNR moves to its own function, `apply_ase`.
+
+### Changes that may need code updates
+
+- **`apply_awgn(signal_power=)` is removed.** Its uses each have a direct replacement:
+  - silence or zero padding around the signal: nothing to pass, as Es is now measured as energy per symbol (below);
+  - a fixed noise floor, noise referenced to the transmitter, or noise on a dark capture: `noise_var=`, the absolute noise variance per sample. For unit-energy symbols, `noise_var = 10 ** (-esn0_db / 10)` at any `sps`.
+- **`apply_awgn(osnr_db=, reference_bandwidth=, noise_modes=)` is `apply_ase(osnr_db=, reference_bandwidth=, noise_modes=)`.** Same arguments and noise.
+
+### Changes that alter results
+
+- **`apply_awgn(esn0_db=)` measures Es as energy per symbol**: each channel's energy over the number of symbols the record carries (a Signal's frame length without a zero guard, else its reference's symbol count, else `N / sps`). Zero padding and silence around a frame no longer lower the noise level; without silence the noise is as before. `apply_ase` measures the signal power the same way.
+
+### Added
+
+- `apply_awgn(noise_var=)`, an absolute noise variance per sample, scalar or `(C,)`; exactly one of `esn0_db` and `noise_var` is given.
+- `apply_awgn(per_channel=False)` gives every channel one noise level, from the mean symbol energy over channels, as identical receivers with one noise floor; the default gives each channel the requested Es/N0.
+- Notebook 06 shows relative (`esn0_db`) against absolute (`noise_var`) noise.
+
 ## [3.1.2] - 2026-10-29
 
 `apply_awgn` without hidden assumptions about what a channel is: Es/N0 holds per channel, and the OSNR counts the ASE of the modes the medium guides instead of assuming the two polarizations of a single-mode fiber.

{commkit-3.1.2 → commkit-3.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: commkit
-Version: 3.1.2
+Version: 3.1.3
 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
@@ -119,7 +119,7 @@ CommKit never picks a device for you: data stays where you put it, and each func
 | [`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 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.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-3.1.2 → commkit-3.1.3}/README.md

@@ -83,7 +83,7 @@ CommKit never picks a device for you: data stays where you put it, and each func
 | [`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 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.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-3.1.2 → commkit-3.1.3}/commkit/__init__.py

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

{commkit-3.1.2 → commkit-3.1.3}/commkit/impairments/__init__.py

@@ -1,6 +1,7 @@
 """Channel impairments, grouped by where in the link they originate.
 
-- :mod:`~commkit.impairments.noise`: additive noise (:func:`apply_awgn`).
+- :mod:`~commkit.impairments.noise`: additive noise (:func:`apply_awgn`) and
+  amplified spontaneous emission at an OSNR (:func:`apply_ase`).
 - :mod:`~commkit.impairments.source`: laser and oscillator phase noise
   (:func:`generate_phase_noise`, :func:`apply_phase_noise`).
 - :mod:`~commkit.impairments.frontend`: transceiver IQ imbalance
@@ -28,7 +29,7 @@ from .frontend import (
     correct_iq_imbalance,
     estimate_iq_imbalance,
 )
-from .noise import apply_awgn
+from .noise import apply_ase, apply_awgn
 from .source import apply_phase_noise, generate_phase_noise
 
 __all__ = [
@@ -36,6 +37,7 @@ __all__ = [
     "GramSchmidt",
     "IQImbalanceEstimate",
     "Lowdin",
+    "apply_ase",
     "apply_awgn",
     "apply_chromatic_dispersion",
     "apply_fiber_propagation",

commkit-3.1.3/commkit/impairments/noise.py

@@ -0,0 +1,283 @@
+"""Additive white Gaussian noise: :func:`apply_awgn`, and amplified
+spontaneous emission at an OSNR: :func:`apply_ase`.
+
+Powers are per sample and per channel, in the squared units of the samples.
+The signal's symbol energy is measured as energy per symbol: the energy of
+each channel over the number of symbols it carries, so silence around the
+signal (zero padding, a capture before the frame arrives) lowers neither.
+"""
+
+from typing import Any
+
+from .._random import RNG, as_generator, complex_normal, standard_normal
+from ..backend import ArrayType, dispatch
+from ..core._signal_adapter import S, SignalAdapter, adapt_signal
+from ..logger import logger
+from ..math import db_to_linear
+
+__all__ = ["apply_ase", "apply_awgn"]
+
+
+def apply_awgn(
+    samples: S,
+    *,
+    esn0_db: float | None = None,
+    noise_var: float | ArrayType | None = None,
+    sps: float | None = None,
+    per_channel: bool = True,
+    rng: RNG = None,
+) -> S:
+    """Add white Gaussian noise, relative to the signal or of an absolute
+    variance.
+
+    Give exactly one of:
+
+    - ``esn0_db``, the noise *relative to the signal*: the symbol energy
+      ``Es`` is measured, and channel ``c`` gets noise of variance
+      ``σ_c² = Es_c / (Es/N0)`` per sample.  Scaling the signal scales the
+      noise with it; the Es/N0 stays.
+    - ``noise_var``, the *absolute* noise variance ``σ² = E|n|²`` per sample,
+      in the squared units of the samples; nothing is measured.  A fixed
+      noise floor, such as a receiver's thermal noise: scaling the signal
+      leaves the noise as it is, and the SNR changes.
+
+    The symbol energy is energy per symbol, ``Es_c = E_c / K`` with ``E_c =
+    Σ|x_c[n]|²`` the energy of channel ``c`` and ``K`` the number of symbols
+    the record carries: a Signal's frame length in symbols (without a zero
+    guard), else its reference's symbol count, else (and for arrays, or a
+    record shorter than that) ``N / sps``.  Without silence this is
+    ``sps · mean(|x_c|²)``, the power summed over the ``sps`` samples of a
+    symbol; zero padding adds no energy and no symbols, so it changes
+    nothing.  With ``Es`` in these units the noise density is ``N0 = σ²``,
+    the variance of one sample, and ``Es/N0`` is the SNR per symbol after a
+    matched filter and decimation, whatever the oversampling.
+
+    Parameters
+    ----------
+    samples : array_like or Signal
+        Input samples, time on the last axis, ``(N,)`` or ``(C, N)``.  A
+        channel is anything with its own receiver noise: a polarization, an
+        antenna, a wire pair, a lane.
+    esn0_db : float, optional
+        Symbol energy over noise spectral density, Es/N0, in dB.
+    noise_var : float or array_like, optional
+        Noise variance ``E|n|²`` per sample: a scalar for every channel, or
+        ``(C,)`` per channel.  Instead of ``esn0_db``.
+    sps : float, optional
+        Samples per symbol, for ``esn0_db``.  Taken from the Signal; required
+        for array input.  A value that disagrees with the Signal raises.
+    per_channel : bool, default True
+        For ``esn0_db``: ``True`` gives every channel the requested Es/N0
+        from its own symbol energy; ``False`` gives every channel the same
+        noise, from the mean symbol energy over channels, as identical
+        receivers with one noise floor (a channel that arrives weaker, e.g.
+        through polarization-dependent loss, then has a lower Es/N0).
+    rng : int, numpy.random.Generator or None
+        Random source.  The noise is drawn on the data's device: from this
+        Generator on the CPU, and on the GPU from a CuPy Generator seeded from
+        it, so a seed is reproducible per device.
+
+    Returns
+    -------
+    ndarray or Signal
+        The noisy samples, same shape, dtype and device as the input.
+
+    Raises
+    ------
+    ValueError
+        If neither or both of ``esn0_db`` and ``noise_var`` are given, or a
+        per-channel ``noise_var`` does not have ``C`` entries.
+
+    Notes
+    -----
+    Complex input gets circular complex noise, its variance split equally
+    between I and Q; real input gets real noise of the full variance.
+
+    Examples
+    --------
+    >>> sig = generate(Constellation.pam(4), 1000, symbol_rate=1e6, sps=4)
+    >>> noisy = apply_awgn(sig, esn0_db=20)  # sps taken from sig
+    >>> noisy = apply_awgn(sig.samples, esn0_db=20, sps=4)
+    >>> floor = apply_awgn(sig, noise_var=1e-3)  # absolute, whatever the signal
+    """
+    signal_adapter = adapt_signal(samples, function_name="apply_awgn()")
+    if (esn0_db is None) == (noise_var is None):
+        raise ValueError("apply_awgn(): give one of esn0_db and noise_var.")
+    x, xp, _ = dispatch(signal_adapter.array)
+    num_channels = 1 if x.ndim == 1 else x.shape[0]
+
+    if noise_var is not None:
+        logger.info("Adding AWGN (noise variance given).")
+        var = xp.asarray(noise_var, dtype=xp.float64)
+        if var.ndim != 0:
+            if var.shape != (num_channels,):
+                raise ValueError(
+                    "apply_awgn(): noise_var must be a scalar or have one entry "
+                    f"per channel ({num_channels},), got shape {var.shape}."
+                )
+            var = var[:, None] if x.ndim == 2 else var
+        return signal_adapter.wrap_samples(x + _noise(x, xp, var, rng))
+
+    sps = signal_adapter.resolve_fact("sps", sps)
+    logger.info("Adding AWGN (Es/N0 target: %.2f dB).", esn0_db)
+    es = _symbol_energy(signal_adapter, x, xp, sps)
+    if not per_channel:
+        es = xp.mean(es)
+    esn0_linear = max(db_to_linear(esn0_db, power=True), 1e-20)
+    return signal_adapter.wrap_samples(x + _noise(x, xp, es / esn0_linear, rng))
+
+
+def apply_ase(
+    samples: S,
+    *,
+    osnr_db: float,
+    reference_bandwidth: float = 12.5e9,
+    noise_modes: int | None = None,
+    rng: RNG = None,
+) -> S:
+    """Add amplified spontaneous emission at an optical signal-to-noise ratio.
+
+    OSNR is specified as optical links are: the total signal power of all
+    channels over the ASE power in ``reference_bandwidth``, summed over the
+    ``M = noise_modes`` modes the medium guides (polarizations included).
+    ASE has the same density in every mode and is white over the simulated
+    band ``f_s``, so complex noise of variance ``σ²`` per mode puts
+    ``M σ² B_ref / f_s`` into ``B_ref``, and every channel gets the same
+
+        σ² = P · f_s / (M · B_ref · OSNR),
+
+    with ``P = Σ_c Es_c / sps`` the total signal power while the signal is
+    present (the symbol energy as in :func:`apply_awgn`, so silence around
+    the signal does not lower it).  For equal channel powers this gives
+    ``Es/N0 = M B_ref / (C R_s) · OSNR`` per channel, whatever the
+    oversampling: the textbook ``2 B_ref / (p R_s) · OSNR`` for ``p``
+    polarizations of a single-mode fiber.
+
+    Parameters
+    ----------
+    samples : Signal
+        A complex optical Signal (``domain="OPT"``), ``(N,)`` or ``(C, N)``
+        with one channel per guided mode it occupies (polarization, spatial
+        mode or core); its sampling rate sets the noise bandwidth.
+    osnr_db : float
+        Optical signal-to-noise ratio in dB in ``reference_bandwidth``.
+    reference_bandwidth : float, default 12.5e9
+        Noise reference bandwidth ``B_ref`` in Hz.  The standard reference
+        is 0.1 nm of optical bandwidth, ``c · 0.1 nm / λ²``: 12.5 GHz in the
+        C band (12.48 GHz at 1550 nm), 17.5 GHz at 1310 nm.  Outside the C
+        band pass the value for the carrier, e.g. ``17.5e9`` for an O-band
+        OSNR in 0.1 nm.
+    noise_modes : int, optional
+        The number ``M`` of guided modes, polarizations included, whose ASE
+        the OSNR counts.  Defaults to ``max(C, 2)``: both polarizations of a
+        single-mode fiber for one or two channels (an OSNR meter's
+        definition; a single-polarization signal receives the half of the
+        ASE in its own polarization), and one mode per channel beyond that
+        (few-mode or multicore fiber with every mode carrying signal).  Pass
+        it when the medium guides modes that carry no signal, e.g.
+        ``noise_modes=6`` for 4 channels in a 3-mode fiber.
+    rng : int, numpy.random.Generator or None
+        Random source, as in :func:`apply_awgn`.
+
+    Returns
+    -------
+    Signal
+        The noisy Signal, same shape, dtype and device.
+
+    Raises
+    ------
+    ValueError
+        If ``samples`` is not a complex optical Signal,
+        ``reference_bandwidth`` is not positive, or ``noise_modes`` is not
+        an integer of at least ``C``.
+
+    Notes
+    -----
+    OSNR is a property of the whole optical field, so pass every channel in
+    one call: calling once per polarization of a dual-polarization signal
+    counts only that polarization's power and adds half the intended
+    noise.  Modes left out of a simulation carry no noise, which matters
+    for a receiver without a polarizer (direct detection, where the
+    orthogonal polarization adds ASE-ASE beat noise); model such a link
+    with both polarizations.
+
+    Examples
+    --------
+    >>> field = sig.replace(domain="OPT", center_frequency=193.4e12)
+    >>> noisy = apply_ase(field, osnr_db=18)  # in 12.5 GHz, both polarizations
+    """
+    signal_adapter = adapt_signal(samples, function_name="apply_ase()")
+    x, xp, _ = dispatch(signal_adapter.array)
+    sig = signal_adapter.signal
+    if sig is None or sig.domain != "OPT" or not xp.iscomplexobj(x):
+        raise ValueError(
+            "apply_ase(): needs a complex optical Signal (domain='OPT'), whose "
+            "sampling rate sets the noise bandwidth."
+        )
+    if not reference_bandwidth > 0:
+        raise ValueError(
+            "apply_ase(): reference_bandwidth must be positive (Hz), got "
+            f"{reference_bandwidth!r}."
+        )
+    num_channels = 1 if x.ndim == 1 else x.shape[0]
+    if noise_modes is None:
+        noise_modes = max(num_channels, 2)
+    if (
+        isinstance(noise_modes, bool)
+        or not isinstance(noise_modes, int)
+        or noise_modes < num_channels
+    ):
+        raise ValueError(
+            f"apply_ase(): noise_modes must be an integer of at least the "
+            f"{num_channels} channels, got {noise_modes!r}."
+        )
+    logger.info(
+        "Adding ASE noise (OSNR target: %.2f dB, %d modes).", osnr_db, noise_modes
+    )
+    sps = float(sig.sps)
+    # The ASE density is the same in every mode: one variance for all
+    # channels, from their total power while the signal is present.
+    power = xp.sum(_symbol_energy(signal_adapter, x, xp, sps)) / sps
+    noise_power = (
+        power
+        * sig.sampling_rate
+        / (noise_modes * reference_bandwidth * db_to_linear(osnr_db, power=True))
+    )
+    return signal_adapter.wrap_samples(x + _noise(x, xp, noise_power, rng))
+
+
+def _symbol_energy(
+    signal_adapter: SignalAdapter[Any], x: ArrayType, xp: Any, sps: float
+) -> ArrayType:
+    """Energy per symbol of each channel in sample units, ``(C, 1)`` (``(1,)``
+    for 1-D input): the channel's energy over the symbols the record
+    carries (see :func:`apply_awgn`)."""
+    num_periods = x.shape[-1] / sps
+    num_symbols = num_periods
+    sig = signal_adapter.signal
+    if sig is not None:
+        if sig.frame is not None:
+            frame = sig.frame
+            zero_guard = frame.guard_num_symbols if frame.guard_type == "zero" else 0
+            num_symbols = frame.num_symbols - zero_guard
+        elif sig.reference is not None and sig.reference.symbols is not None:
+            num_symbols = sig.reference.symbols.shape[-1]
+    # A record shorter than its frame or reference holds only part of the
+    # signal: its own length counts.
+    num_symbols = min(num_symbols, num_periods)
+    mean_power = xp.mean(xp.abs(x) ** 2, axis=-1, keepdims=True)
+    return mean_power * (x.shape[-1] / num_symbols)
+
+
+def _noise(x: Any, xp: Any, noise_power: Any, rng: RNG) -> Any:
+    """White Gaussian noise of ``noise_power`` per sample, shaped like ``x``.
+
+    Complex noise splits its power equally between I and Q.
+    """
+    gen = as_generator(rng)
+    real_dtype = x.real.dtype if x.real.dtype.kind == "f" else xp.dtype(xp.float64)
+    if xp.iscomplexobj(x):
+        std = xp.sqrt(noise_power / 2).astype(real_dtype)
+        return complex_normal(gen, x.shape, std=std, dtype=real_dtype, xp=xp)
+    std = xp.sqrt(noise_power).astype(real_dtype)
+    return std * standard_normal(gen, x.shape, dtype=real_dtype, xp=xp)

{commkit-3.1.2 → commkit-3.1.3}/examples/06-awgn-and-performance-metrics.ipynb

@@ -97,6 +97,53 @@
    "cell_type": "markdown",
    "id": "4",
    "metadata": {},
+   "source": [
+    "### Relative or absolute noise\n",
+    "\n",
+    "`apply_awgn` takes the amount of noise in one of two ways, never both:\n",
+    "\n",
+    "* `esn0_db`, **relative to the signal**: it measures the symbol energy `Es`\n",
+    "  and adds noise of variance `σ² = Es / (Es/N0)` per sample, so the Es/N0\n",
+    "  is what you ask for whatever the signal's scale.  `Es` is the energy per\n",
+    "  symbol the `Signal` carries, so silence around a frame (11) does not lower\n",
+    "  it, and each channel of a multichannel record gets the requested Es/N0\n",
+    "  from its own energy (`per_channel=False` gives all channels one noise\n",
+    "  floor from their mean).\n",
+    "* `noise_var`, **absolute**: the variance `σ² = E|n|²` per sample, in the\n",
+    "  squared units of the samples, with nothing measured.  This is a fixed\n",
+    "  noise floor, such as a receiver's thermal noise: the SNR follows the\n",
+    "  signal's power.\n",
+    "\n",
+    "In sample units the symbol energy of unit-energy symbols is 1 at any `sps`,\n",
+    "so `noise_var=0.01` is Es/N0 = 20 dB for the transmitted signal.  The two\n",
+    "part ways when the signal arrives 10 dB weaker:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "attenuated = tx.replace(samples=tx.samples * 10 ** (-10 / 20))  # 10 dB of loss\n",
+    "for name, sig in ((\"as sent\", tx), (\"10 dB weaker\", attenuated)):\n",
+    "    snrs = []\n",
+    "    for noisy in (\n",
+    "        ck.impairments.apply_awgn(sig, esn0_db=20, rng=2),  # relative\n",
+    "        ck.impairments.apply_awgn(sig, noise_var=0.01, rng=2),  # absolute\n",
+    "    ):\n",
+    "        y = ck.multirate.decimate_to_symbol_rate(ck.filtering.matched_filter(noisy))\n",
+    "        snrs.append(ck.metrics.snr(y))\n",
+    "    print(\n",
+    "        f\"{name:12s}: esn0_db=20 gives {snrs[0]:5.2f} dB, noise_var=0.01 gives {snrs[1]:5.2f} dB\"\n",
+    "    )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6",
+   "metadata": {},
    "source": [
     "## 2. SNR and EVM\n",
     "\n",
@@ -118,7 +165,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "5",
+   "id": "7",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -136,7 +183,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "6",
+   "id": "8",
    "metadata": {},
    "source": [
     "## 3. Error rates against theory\n",
@@ -157,7 +204,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "7",
+   "id": "9",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -190,7 +237,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "8",
+   "id": "10",
    "metadata": {},
    "source": [
     "## 4. Soft information: LLRs\n",
@@ -216,7 +263,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "9",
+   "id": "11",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -258,7 +305,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "10",
+   "id": "12",
    "metadata": {},
    "source": [
     "## 5. Achievable rates: GMI and MI\n",
@@ -279,7 +326,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "11",
+   "id": "13",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -314,7 +361,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "12",
+   "id": "14",
    "metadata": {},
    "source": [
     "## 6. Conventions of the metrics\n",
@@ -332,7 +379,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "13",
+   "id": "15",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -349,13 +396,15 @@
   },
   {
    "cell_type": "markdown",
-   "id": "14",
+   "id": "16",
    "metadata": {},
    "source": [
     "**Summary**\n",
     "\n",
     "* `apply_awgn(esn0_db=...)` gives SNR = Es/N0 after the matched filter at\n",
     "  any `sps`.\n",
+    "* `esn0_db` sets the noise relative to the measured symbol energy;\n",
+    "  `noise_var` sets an absolute noise floor instead.\n",
     "* `snr` and data-aided `evm` are two views of one number,\n",
     "  `EVM = 1/sqrt(SNR)`.\n",
     "* `ser` / `ber` match the closed-form QAM curves; LLR signs are the hard\n",

{commkit-3.1.2 → commkit-3.1.3}/examples/11-frame-synchronization-and-timing.ipynb

@@ -131,9 +131,9 @@
     "## 3. A capture with an unknown delay\n",
     "\n",
     "The capture below holds 1000.37 samples of silence before the frame and\n",
-    "some after, with noise at Es/N0 = 15 dB.  `signal_power=` pins the noise to\n",
-    "the frame's power (`1/sps`) rather than to the power of the whole capture,\n",
-    "which the silence lowers.\n",
+    "some after, with noise at Es/N0 = 15 dB.  `apply_awgn` measures `Es` as\n",
+    "the energy per symbol of the frame the `Signal` carries, so the silence\n",
+    "around it does not lower the noise level.\n",
     "\n",
     "`estimate_timing` correlates the capture with the preamble, shaped with the\n",
     "`Signal`'s pulse at its `sps` (a `Signal` with a frame needs no template\n",
@@ -162,7 +162,7 @@
     "capture = tx.replace(\n",
     "    samples=ck.timing.fft_fractional_delay(padded, delay=TRUE_DELAY - 1000)\n",
     ")\n",
-    "capture = ck.impairments.apply_awgn(capture, esn0_db=15, signal_power=1 / tx.sps, rng=1)\n",
+    "capture = ck.impairments.apply_awgn(capture, esn0_db=15, rng=1)\n",
     "\n",
     "est = ck.timing.estimate_timing(capture)\n",
     "print(\n",
@@ -268,7 +268,7 @@
     "            ]\n",
     "        )\n",
     "    )\n",
-    "    cap = ck.impairments.apply_awgn(cap, esn0_db=15, signal_power=1 / t.sps, rng=2)\n",
+    "    cap = ck.impairments.apply_awgn(cap, esn0_db=15, rng=2)\n",
     "    preamble_seconds = preamble.num_symbols / t.symbol_rate\n",
     "    for turns in (0.0, 0.25, 0.5, 1.0, 2.0):\n",
     "        e = ck.timing.estimate_timing(\n",

{commkit-3.1.2 → commkit-3.1.3}/examples/15-linear-channel-equalization.ipynb

@@ -85,9 +85,10 @@
     "def through(h):\n",
     "    xp = tx.xp\n",
     "    r = xp.convolve(tx.samples, xp.asarray(h))[: tx.samples.shape[-1]]\n",
-    "    # The noise is set against the transmitted power (1), not the received one.\n",
+    "    # A fixed receiver noise floor: Es/N0 = 18 dB for the transmitted\n",
+    "    # unit-energy symbols, whatever the channel does to the received power.\n",
     "    return ck.impairments.apply_awgn(\n",
-    "        tx.replace(samples=r), esn0_db=ESN0, signal_power=1.0, rng=2\n",
+    "        tx.replace(samples=r), noise_var=10 ** (-ESN0 / 10), rng=2\n",
     "    )\n",
     "\n",
     "\n",

{commkit-3.1.2 → commkit-3.1.3}/examples/16-adaptive-equalization.ipynb

@@ -65,8 +65,9 @@
     "## 1. The link and the LMS equalizer\n",
     "\n",
     "16-QAM at 32 GBd and 2 samples per symbol through a 12 GHz electrical\n",
-    "bandwidth ([10](10-front-end-impairments.ipynb) · section 3), with AWGN at Es/N0 = 20 dB, then the\n",
-    "matched filter.  The ISI closes the eye completely.\n",
+    "bandwidth ([10](10-front-end-impairments.ipynb) · section 3), with receiver noise at Es/N0 = 20 dB\n",
+    "for the transmitted symbols, then the matched filter.  The noise is a fixed\n",
+    "floor (`noise_var`), so the power the filter removes counts against the SNR.  The ISI closes the eye completely.\n",
     "\n",
     "`lms` runs a **fractionally spaced** FIR filter (here 21 taps at 2 samples\n",
     "per symbol) and outputs one symbol per symbol period.  For each output `y`\n",
@@ -98,6 +99,9 @@
     "    rng=1,\n",
     "    device=DEVICE,\n",
     ")\n",
+    "# Receiver noise at Es/N0 = 20 dB for the transmitted unit-energy symbols\n",
+    "# (Es = 1 in sample units at any sps), fixed whatever the filter does.\n",
+    "NOISE_VAR = 10 ** (-20 / 10)\n",
     "bessel = ck.filtering.bessel_sos(\n",
     "    sampling_rate=tx.sampling_rate, cutoff=12e9, order=4, norm=\"mag\"\n",
     ")\n",
@@ -105,7 +109,7 @@
     "\n",
     "def link(rng):\n",
     "    x = ck.filtering.iir_filter(tx, bessel)\n",
-    "    x = ck.impairments.apply_awgn(x, esn0_db=20, signal_power=1 / tx.sps, rng=rng)\n",
+    "    x = ck.impairments.apply_awgn(x, noise_var=NOISE_VAR, rng=rng)\n",
     "    return ck.filtering.matched_filter(x)\n",
     "\n",
     "\n",
@@ -319,7 +323,7 @@
     "    ck.filtering.iir_filter(stream, bessel), linewidth=1e6, rng=4\n",
     ")\n",
     "stream = ck.filtering.matched_filter(\n",
-    "    ck.impairments.apply_awgn(stream, esn0_db=20, signal_power=1 / tx.sps, rng=5)\n",
+    "    ck.impairments.apply_awgn(stream, noise_var=NOISE_VAR, rng=5)\n",
     ")\n",
     "\n",
     "\n",

{commkit-3.1.2 → commkit-3.1.3}/examples/22-coherent-transceiver-end-to-end.ipynb

@@ -142,7 +142,7 @@
     "x = ck.impairments.apply_iq_imbalance(\n",
     "    x, amplitude_imbalance_db=1.0, phase_imbalance_deg=5.0\n",
     ")\n",
-    "rx = ck.impairments.apply_awgn(x, esn0_db=25, signal_power=1 / SPS, rng=3)\n",
+    "rx = ck.impairments.apply_awgn(x, esn0_db=25, rng=3)\n",
     "\n",
     "ck.plotting.plot_psd(\n",
     "    rx, nperseg=2048, title=\"Received spectrum (both polarizations)\", show=True\n",
@@ -368,9 +368,9 @@
     "        **LINK,\n",
     "    )\n",
     "    if not nonlinear:  # ... and the ASE of the 2 dBm link added by hand\n",
-    "        z = ck.impairments.apply_awgn(z, esn0_db=ase_esn0, signal_power=1 / SPS, rng=4)\n",
+    "        z = ck.impairments.apply_awgn(z, esn0_db=ase_esn0, rng=4)\n",
     "    if receiver_noise:\n",
-    "        z = ck.impairments.apply_awgn(z, esn0_db=25, signal_power=1 / SPS, rng=3)\n",
+    "        z = ck.impairments.apply_awgn(z, esn0_db=25, rng=3)\n",
     "    z = ck.filtering.correct_chromatic_dispersion(\n",
     "        z,\n",
     "        dispersion_ps_nm_km=fiber.dispersion_ps_nm_km,\n",

{commkit-3.1.2 → commkit-3.1.3}/examples/26-laser-linewidth-self-homodyne-iq.ipynb

@@ -210,13 +210,11 @@
    "source": [
     "# Dark capture -> DC calibration.  With the signal blocked the ADCs record\n",
     "# offset + detector noise; the noise level does not depend on the blocked\n",
-    "# signal, so pin it with signal_power=1.0 - the level a unit-amplitude beat\n",
-    "# sees (the record's own near-zero power cannot define it).\n",
+    "# signal, so give it as an absolute variance: the level a unit-amplitude\n",
+    "# beat sees at SNR_DB (the record's own near-zero power cannot define it).\n",
     "z_dark = apply_awgn(\n",
     "    xp.full(1 << 16, DC_TRUE, dtype=xp.complex128),\n",
-    "    sps=1,\n",
-    "    esn0_db=SNR_DB,\n",
-    "    signal_power=1.0,\n",
+    "    noise_var=10 ** (-SNR_DB / 10),\n",
     "    rng=2,\n",
     ")\n",
     "dc_cal = complex(xp.mean(z_dark))\n",