commkit 3.1.1__tar.gz → 3.1.2__tar.gz

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

@@ -4,6 +4,20 @@ Notable changes to CommKit, newest first. Performance figures are from the refer
 
 ## [Unreleased]
 
+## [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.
+
+### Changes that alter results
+
+- **`apply_awgn(esn0_db=)` gives every channel the requested Es/N0.** The default noise level comes from each channel's own mean power; it used to come from the mean over all channels, so with unequal channel powers a stronger channel got a better Es/N0 than requested and a weaker one a worse. Equal powers give the same result as before. Pass a scalar `signal_power` for the old behavior, one absolute noise level shared by every channel.
+- **`apply_awgn(osnr_db=)` counts the ASE of `noise_modes` modes, `max(C, 2)` by default.** One or two channels are unchanged (both polarizations of a single-mode fiber). More channels, such as the modes of a few-mode fiber or the cores of a multicore fiber, each count as a mode; they used to share the ASE of two polarizations, which put C/2 times too much noise on each.
+
+### Added
+
+- `apply_awgn(noise_modes=)` for a medium that guides modes without signal, e.g. `noise_modes=6` for four channels in a three-mode fiber.
+- `apply_awgn(signal_power=)` accepts one power per channel, `(C,)`.
+
 ## [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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: commkit
-Version: 3.1.1
+Version: 3.1.2
 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

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

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

commkit-3.1.2/commkit/impairments/noise.py

@@ -0,0 +1,229 @@
+"""Additive white Gaussian noise: :func:`apply_awgn`."""
+
+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, adapt_signal
+from ..logger import logger
+from ..math import db_to_linear
+
+__all__ = ["apply_awgn"]
+
+
+def apply_awgn(
+    samples: S,
+    *,
+    esn0_db: float | None = None,
+    osnr_db: float | None = None,
+    sps: float | None = None,
+    signal_power: float | ArrayType | None = None,
+    reference_bandwidth: float = 12.5e9,
+    noise_modes: int | None = None,
+    rng: RNG = None,
+) -> S:
+    """Add white Gaussian noise at an Es/N0, or at an OSNR for an optical field.
+
+    Powers are per sample and per channel, in the squared units of the
+    samples: ``P_c = mean(|x_c[n]|²)`` over the samples of channel ``c``.
+    A symbol lasts ``T = sps / f_s``, so its energy is
+    ``Es_c = P_c · T = sps · P_c / f_s``; white noise of variance ``σ²``
+    per sample fills the band ``f_s`` with the density ``N0 = σ² / f_s``.
+    Hence ``Es/N0 = sps · P_c / σ²``: in sample units, ``Es`` is the power
+    summed over the ``sps`` samples of a symbol and ``N0`` the noise
+    variance of one sample.
+
+    With ``esn0_db`` every channel gets the requested Es/N0 on its own:
+    channel ``c`` gets noise of variance ``σ_c² = sps · P_c / (Es/N0)`` per
+    sample.  That is the Es/N0 per symbol after a matched filter and
+    decimation, whatever the oversampling.  A channel can be anything with
+    its own receiver noise: a polarization, an antenna, a wire pair, a lane.
+
+    With ``osnr_db`` (an optical Signal) the noise is amplified spontaneous
+    emission 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``; every channel therefore gets the
+    same
+
+        σ² = (Σ_c P_c) · f_s / (M · B_ref · OSNR),
+
+    which for equal powers 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 : array_like or Signal
+        Input samples, time on the last axis, ``(N,)`` or ``(C, N)``; for
+        ``osnr_db`` a complex optical Signal (``domain="OPT"``) with one
+        channel per guided mode it occupies (polarization, spatial mode or
+        core).
+    esn0_db : float, optional
+        Symbol energy over noise spectral density, Es/N0, in dB, for each
+        channel.
+    osnr_db : float, optional
+        Optical signal-to-noise ratio in dB in ``reference_bandwidth``,
+        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.
+    signal_power : float or array_like, optional
+        The power ``P_c`` per sample of each channel, ``mean(|x_c|²)`` in
+        the squared units of the samples, that the Es/N0 or OSNR refers to:
+        ``Es_c = sps · P_c``.  A scalar is the power of *each* channel (not
+        their sum or a total), so every channel gets the same absolute
+        noise level, as identical receivers with one noise floor; ``(C,)``
+        gives one power per channel.  Defaults to each channel's measured
+        mean power over the whole record, which counts any silent stretch.
+        Pass the nominal power instead when that is the reference: e.g.
+        ``signal_power=1.0`` for unit-power symbols at one sample per
+        symbol sent in bursts separated by zero guard intervals, whose
+        measured mean falls below the power of the symbols.  For a
+        pulse-shaped signal the per-sample power of unit-energy symbols is
+        ``1 / sps`` (``signal_power=1 / sig.sps``).  With ``osnr_db`` the
+        signal power is the sum over channels, ``C · signal_power`` for a
+        scalar.
+    reference_bandwidth : float, default 12.5e9
+        Noise reference bandwidth ``B_ref`` of ``osnr_db`` 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.
+        ``reference_bandwidth=17.5e9`` for an O-band OSNR in 0.1 nm.
+    noise_modes : int, optional
+        For ``osnr_db``: 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.  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 ``osnr_db`` are given,
+        ``osnr_db`` is given for anything but a complex optical Signal,
+        ``reference_bandwidth`` is not positive, ``noise_modes`` is not an
+        integer of at least ``C``, or a per-channel ``signal_power`` 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.  At
+    ``sps = 1`` Es/N0 equals the per-sample SNR.
+
+    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
+    --------
+    >>> sig = generate(Constellation.pam(4), 1000, symbol_rate=1e6, sps=4)
+    >>> noisy = apply_awgn(sig.samples, esn0_db=20, sps=4)
+    >>> noisy = apply_awgn(sig, esn0_db=20)  # Signal input: sps taken from sig
+    >>> field = sig.replace(domain="OPT", center_frequency=193.4e12)
+    >>> noisy = apply_awgn(field, osnr_db=18)  # in 12.5 GHz, both polarizations
+    """
+    signal_adapter = adapt_signal(samples, function_name="apply_awgn()")
+    if (esn0_db is None) == (osnr_db is None):
+        raise ValueError("apply_awgn(): give one of esn0_db and osnr_db.")
+    x, xp, _ = dispatch(signal_adapter.array)
+    num_channels = 1 if x.ndim == 1 else x.shape[0]
+    power = _channel_power(x, xp, signal_power, num_channels)
+
+    if osnr_db is not None:
+        sig = signal_adapter.signal
+        if sig is None or sig.domain != "OPT" or not xp.iscomplexobj(x):
+            raise ValueError(
+                "apply_awgn(): osnr_db needs a complex optical Signal "
+                "(domain='OPT'), whose sampling rate sets the noise bandwidth."
+            )
+        if not reference_bandwidth > 0:
+            raise ValueError(
+                "apply_awgn(): reference_bandwidth must be positive (Hz), got "
+                f"{reference_bandwidth!r}."
+            )
+        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_awgn(): 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
+        )
+        # The ASE density is the same in every mode: one variance for all
+        # channels, from their total power.
+        noise_power = (
+            xp.sum(xp.broadcast_to(power, (num_channels, 1)))
+            * 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))
+
+    sps = signal_adapter.resolve_fact("sps", sps)
+    logger.info("Adding AWGN (Es/N0 target: %.2f dB).", esn0_db)
+
+    # Es/N0 to the noise variance per sample: Es = sps · P_c is the energy of
+    # a symbol over its sps samples; white noise of variance σ² over the band
+    # f_s = sps · R_s has N0 = σ² / f_s, so Es/N0 = P_c · sps / σ² per
+    # symbol, i.e. a per-sample SNR of Es/N0 / sps.
+    esn0_linear = max(db_to_linear(esn0_db, power=True), 1e-20)
+    noise_power = power * (sps / esn0_linear)
+    return signal_adapter.wrap_samples(x + _noise(x, xp, noise_power, rng))
+
+
+def _channel_power(
+    x: ArrayType, xp: Any, signal_power: Any, num_channels: int
+) -> ArrayType:
+    """Signal power per channel, broadcastable against ``x``: measured,
+    ``(C, 1)`` (``(1,)`` for 1-D input), or the given scalar or ``(C,)``."""
+    if signal_power is None:
+        return xp.mean(xp.abs(x) ** 2, axis=-1, keepdims=True)
+    power = xp.asarray(signal_power, dtype=xp.float64)
+    if power.ndim == 0:
+        return power
+    if power.shape != (num_channels,):
+        raise ValueError(
+            f"apply_awgn(): signal_power must be a scalar or have one entry per "
+            f"channel ({num_channels},), got shape {power.shape}."
+        )
+    return power[:, None] if x.ndim == 2 else power
+
+
+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.1 → commkit-3.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "commkit"
-version = "3.1.1"
+version = "3.1.2"
 description = "A Python library for high-performance digital communications research."
 readme = "README.md"
 authors = [{ name = "Denis Fatkhiev" }]
@@ -86,7 +86,7 @@ markers = [
 ]
 
 [tool.bumpversion]
-current_version = "3.1.1"
+current_version = "3.1.2"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 search = "{current_version}"

{commkit-3.1.1 → commkit-3.1.2}/tests/impairments/test_noise.py

@@ -37,7 +37,7 @@ class TestAddAWGN:
         )
 
     def test_awgn_signal_power_override(self, xp):
-        """Explicit signal_power sets an absolute noise level (dark capture)."""
+        """Explicit signal_power sets an absolute noise level (silent capture)."""
         dark = xp.zeros(20000, dtype=xp.complex128)
         noisy = apply_awgn(dark, esn0_db=10.0, sps=1, signal_power=1.0, rng=3)
         # Without the override the noise power would be 0; with it, 0.1.
@@ -158,3 +158,87 @@ class TestOSNR:
         wide = apply_awgn(sig, osnr_db=15.0, reference_bandwidth=25e9, rng=1)
         var_wide = float(xp.mean(xp.abs(wide.samples - x) ** 2))
         assert var_wide == pytest.approx(var / 2, rel=0.02)
+
+
+class TestPerChannel:
+    """Es/N0 holds per channel; a scalar signal_power shares one noise floor."""
+
+    @staticmethod
+    def _noise_var(xp, noisy, x):
+        return xp.mean(xp.abs(noisy - x) ** 2, axis=-1)
+
+    def test_each_channel_gets_its_esn0(self, xp):
+        x = xp.ones((2, 1 << 16), dtype=xp.complex64)
+        x[1] *= 2.0  # 6 dB stronger
+        noisy = apply_awgn(x, esn0_db=10.0, sps=1, rng=1)
+        var = self._noise_var(xp, noisy, x)
+        assert xp.allclose(var, xp.asarray([0.1, 0.4]), rtol=0.03)
+
+    def test_scalar_signal_power_is_shared(self, xp):
+        x = xp.ones((2, 1 << 16), dtype=xp.complex64)
+        x[1] *= 2.0
+        noisy = apply_awgn(x, esn0_db=10.0, sps=1, signal_power=1.0, rng=1)
+        var = self._noise_var(xp, noisy, x)
+        assert xp.allclose(var, xp.asarray([0.1, 0.1]), rtol=0.03)
+
+    def test_per_channel_signal_power(self, xp):
+        x = xp.zeros((2, 1 << 16), dtype=xp.complex64)
+        noisy = apply_awgn(x, esn0_db=10.0, sps=2, signal_power=[1.0, 0.5], rng=1)
+        var = self._noise_var(xp, noisy, x)
+        assert noisy.dtype == xp.complex64
+        assert xp.allclose(var, xp.asarray([0.2, 0.1]), rtol=0.03)
+        with pytest.raises(ValueError, match="one entry per channel"):
+            apply_awgn(x, esn0_db=10.0, sps=1, signal_power=[1.0, 1.0, 1.0])
+
+
+class TestNoiseModes:
+    """apply_awgn(osnr_db=, noise_modes=): ASE counted over the guided modes."""
+
+    RS = 32e9
+
+    def _field(self, xp, num_channels, sps=2):
+        x = xp.ones((num_channels, 1 << 16), dtype=xp.complex64)
+        return Signal(
+            samples=x,
+            sampling_rate=sps * self.RS,
+            symbol_rate=self.RS,
+            domain="OPT",
+            center_frequency=193.4e12,
+        )
+
+    def _esn0(self, xp, sig, **kwargs):
+        noisy = apply_awgn(sig, osnr_db=20.0, rng=2, **kwargs)
+        var = float(xp.mean(xp.abs(noisy.samples - sig.samples) ** 2))
+        return sig.sps / var
+
+    def test_mode_division_default_counts_every_channel(self, xp):
+        """Six channels in a 3-mode fiber: Es/N0 = 6 B_ref / (6 R_s) · OSNR,
+        the single-mode dual-polarization value."""
+        esn0 = self._esn0(xp, self._field(xp, 6))
+        assert esn0 == pytest.approx(100 * 12.5e9 / self.RS, rel=0.02)
+        assert self._esn0(xp, self._field(xp, 2)) == pytest.approx(esn0, rel=0.02)
+
+    def test_unexcited_modes_still_carry_ase(self, xp):
+        """4 of 6 modes carry signal: the ASE of all 6 counts, so each
+        channel sees 6/4 of the default's Es/N0."""
+        sig = self._field(xp, 4)
+        assert self._esn0(xp, sig, noise_modes=6) == pytest.approx(
+            1.5 * self._esn0(xp, sig), rel=0.02
+        )
+
+    def test_unequal_powers_share_one_ase_level(self, xp):
+        sig = self._field(xp, 2)
+        x = sig.samples.copy()
+        x[1] *= 2.0
+        noisy = apply_awgn(sig.replace(samples=x), osnr_db=20.0, rng=2)
+        var = xp.mean(xp.abs(noisy.samples - x) ** 2, axis=-1)
+        assert float(var[1]) == pytest.approx(float(var[0]), rel=0.03)
+        # Total power 1 + 4 = 5 over two modes: 5 · f_s / (2 B_ref OSNR).
+        expected = 5 * 2 * self.RS / (2 * 12.5e9 * 100)
+        assert float(var[0]) == pytest.approx(expected, rel=0.03)
+
+    def test_noise_modes_validated(self, xp):
+        sig = self._field(xp, 4)
+        for bad in (3, 0, 4.0, True):
+            with pytest.raises(ValueError, match="noise_modes"):
+                apply_awgn(sig, osnr_db=20.0, noise_modes=bad)

{commkit-3.1.1 → commkit-3.1.2}/uv.lock

@@ -418,7 +418,7 @@ wheels = [
 
 [[package]]
 name = "commkit"
-version = "3.1.1"
+version = "3.1.2"
 source = { editable = "." }
 dependencies = [
     { name = "matplotlib" },

commkit-3.1.1/commkit/impairments/noise.py

@@ -1,184 +0,0 @@
-"""Additive white Gaussian noise: :func:`apply_awgn`."""
-
-from typing import Any
-
-from .._random import RNG, as_generator, complex_normal, standard_normal
-from ..backend import dispatch
-from ..core._signal_adapter import S, adapt_signal
-from ..logger import logger
-from ..math import db_to_linear
-
-__all__ = ["apply_awgn"]
-
-
-def apply_awgn(
-    samples: S,
-    *,
-    esn0_db: float | None = None,
-    osnr_db: float | None = None,
-    sps: float | None = None,
-    signal_power: float | None = None,
-    reference_bandwidth: float = 12.5e9,
-    rng: RNG = None,
-) -> S:
-    """Add white Gaussian noise at an Es/N0, or at an OSNR for an optical field.
-
-    With ``esn0_db`` the noise variance per sample is
-    ``signal_power · sps / (Es/N0)``: with ``Es = sps · signal_power``, that
-    is ``Es/N0`` per symbol after a matched filter and decimation, whatever
-    the oversampling.
-
-    With ``osnr_db`` (an optical Signal) the noise is amplified spontaneous
-    emission specified as optical links are: the total signal power over the
-    ASE power in ``reference_bandwidth``, counted in both polarizations.  ASE
-    is white over the simulated band ``f_s``, so complex noise of variance
-    ``σ²`` per polarization has the density ``σ²/f_s`` and puts
-    ``2 σ² B_ref / f_s`` into ``B_ref`` over both polarizations; each
-    channel therefore gets
-
-        σ² = C · signal_power · f_s / (2 · B_ref · OSNR),
-
-    which gives the textbook ``Es/N0 = 2 B_ref / (p R_s) · OSNR`` for ``p``
-    polarizations, whatever the oversampling.  A single-polarization Signal
-    (``C = 1``) still counts the ASE of both polarizations, as an OSNR meter
-    does, and receives the half that falls into its own: the noise a
-    single-polarization coherent receiver sees, 3 dB less than a
-    dual-polarization signal of the same total power at the same OSNR.
-
-    OSNR is a property of the whole optical field, so pass every
-    polarization in one call.  Calling once per polarization of a
-    dual-polarization signal counts only that polarization's power and
-    adds half the intended noise.  The orthogonal polarization's ASE is not
-    simulated for ``C = 1``, which matters for a receiver without a
-    polarizer (direct detection, where it adds ASE-ASE beat noise); model
-    such a link with both polarizations.
-
-    Parameters
-    ----------
-    samples : array_like or Signal
-        Input samples, time on the last axis; for ``osnr_db`` a complex
-        optical Signal (``domain="OPT"``), ``(N,)`` or ``(C, N)`` with one
-        channel per polarization.
-    esn0_db : float, optional
-        Symbol energy over noise spectral density, Es/N0, in dB.
-    osnr_db : float, optional
-        Optical signal-to-noise ratio in dB in ``reference_bandwidth``,
-        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.
-    signal_power : float, optional
-        Signal power per channel for the noise scaling.  Defaults to the mean
-        power of ``samples`` over all channels, which counts any silent
-        stretch.  Pass the nominal power instead when that is the reference:
-        e.g. ``signal_power=1.0`` for a unit-power constellation sent in
-        bursts separated by zero guard intervals, whose measured mean falls
-        below the power of the symbols.
-    reference_bandwidth : float, default 12.5e9
-        Noise reference bandwidth ``B_ref`` of ``osnr_db`` 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.
-        ``reference_bandwidth=17.5e9`` for an O-band OSNR in 0.1 nm.
-    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 ``osnr_db`` are given,
-        ``osnr_db`` is given for anything but a complex optical Signal, or
-        ``reference_bandwidth`` is not positive.
-
-    Notes
-    -----
-    Complex input gets circular complex noise, its variance split equally
-    between I and Q; real input gets real noise of the full variance.  At
-    ``sps = 1`` Es/N0 equals the per-sample SNR.
-
-    Examples
-    --------
-    >>> sig = generate(Constellation.pam(4), 1000, symbol_rate=1e6, sps=4)
-    >>> noisy = apply_awgn(sig.samples, esn0_db=20, sps=4)
-    >>> noisy = apply_awgn(sig, esn0_db=20)  # Signal input: sps taken from sig
-    >>> field = sig.replace(domain="OPT", center_frequency=193.4e12)
-    >>> noisy = apply_awgn(field, osnr_db=18)  # in 12.5 GHz, both polarizations
-    """
-    signal_adapter = adapt_signal(samples, function_name="apply_awgn()")
-    if (esn0_db is None) == (osnr_db is None):
-        raise ValueError("apply_awgn(): give one of esn0_db and osnr_db.")
-    x, xp, _ = dispatch(signal_adapter.array)
-    if signal_power is None:
-        signal_power = xp.mean(xp.abs(x) ** 2)
-    if osnr_db is not None:
-        sig = signal_adapter.signal
-        if sig is None or sig.domain != "OPT" or not xp.iscomplexobj(x):
-            raise ValueError(
-                "apply_awgn(): osnr_db needs a complex optical Signal "
-                "(domain='OPT'), whose sampling rate sets the noise bandwidth."
-            )
-        if not reference_bandwidth > 0:
-            raise ValueError(
-                "apply_awgn(): reference_bandwidth must be positive (Hz), got "
-                f"{reference_bandwidth!r}."
-            )
-        logger.info("Adding ASE noise (OSNR target: %.2f dB).", osnr_db)
-        num_channels = 1 if x.ndim == 1 else x.shape[0]
-        total_power = num_channels * signal_power
-        noise_power = (
-            total_power
-            * sig.sampling_rate
-            / (2.0 * reference_bandwidth * db_to_linear(osnr_db, power=True))
-        )
-        return signal_adapter.wrap_samples(x + _noise(x, xp, noise_power, rng))
-
-    sps = signal_adapter.resolve_fact("sps", sps)
-    logger.info("Adding AWGN (Es/N0 target: %.2f dB).", esn0_db)
-
-    # === Es/N0 to sample-level SNR conversion ===
-    #
-    # Es/N0 = Symbol Energy / Noise Spectral Density
-    #
-    # For oversampled signals:
-    #   - Symbol energy Es = sps * (average sample power)  [sum over sps samples]
-    #   - Noise power in full bandwidth = N0 * fs = N0 * (sps * symbol_rate)
-    #   - Noise power per sample = N0 * symbol_rate
-    #
-    # Therefore:
-    #   Es/N0 = (sps * P_sample) / (N0 * symbol_rate)
-    #   Sample_SNR = P_sample / P_noise_per_sample = P_sample / (N0 * symbol_rate)
-    #
-    # Relationship: Sample_SNR = Es/N0 / sps
-    #
-    # Or equivalently: P_noise = P_signal * sps / Es_N0_linear
-
-    esn0_linear = db_to_linear(esn0_db, power=True)
-
-    # Noise power accounting for oversampling
-    if esn0_linear <= 1e-20:
-        noise_power = signal_power * sps / 1e-20
-    else:
-        noise_power = signal_power * sps / esn0_linear
-
-    return signal_adapter.wrap_samples(x + _noise(x, xp, noise_power, rng))
-
-
-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)