PyChOpMarg 2.1.1__tar.gz → 2.1.2__tar.gz

{pychopmarg-2.1.1 → pychopmarg-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PyChOpMarg
-Version: 2.1.1
+Version: 2.1.2
 Summary: Python implementation of COM, as per IEEE 802.3-22 Annex 93A/178A.
 Author-email: David Banas <capn.freako@gmail.com>
 License: BSD3

{pychopmarg-2.1.1 → pychopmarg-2.1.2}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "PyChOpMarg"
 description = "Python implementation of COM, as per IEEE 802.3-22 Annex 93A/178A."
-version = "2.1.1"
+version = "2.1.2"
 authors = [{name = "David Banas", email = "capn.freako@gmail.com"}]
 urls = { documentation = "https://pychopmarg.readthedocs.io/en/latest/"}
 readme = "README.md"

{pychopmarg-2.1.1 → pychopmarg-2.1.2}/src/PyChOpMarg.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PyChOpMarg
-Version: 2.1.1
+Version: 2.1.2
 Summary: Python implementation of COM, as per IEEE 802.3-22 Annex 93A/178A.
 Author-email: David Banas <capn.freako@gmail.com>
 License: BSD3

{pychopmarg-2.1.1 → pychopmarg-2.1.2}/src/pychopmarg/com.py

@@ -48,7 +48,12 @@ class OptMode(Enum):
 
 
 class COM():  # pylint: disable=too-many-instance-attributes,too-many-public-methods
-    "Encoding of the IEEE 802.3-22 Annex 93A/178A 'Channel Operating Margin' (COM) specification."
+    """
+    Encoding of the IEEE 802.3-22 Annex 93A/178A 'Channel Operating Margin' (COM) specification.
+
+    ToDo:
+        1. Clean up unused attributes.
+    """
 
     status_str = str("Ready")
     debug = bool(False)
@@ -149,7 +154,6 @@ class COM():  # pylint: disable=too-many-instance-attributes,too-many-public-met
 
     # - Results
     # -- COM
-    # ToDo: Clean up unused attributes.
     com = float(0.0)
     com_As = float(0.0)
     com_cursor_ix = int(0)
@@ -250,8 +254,8 @@ class COM():  # pylint: disable=too-many-instance-attributes,too-many-public-met
                 Default: None
 
         Notes:
-            1. The instance's current value(s) for `gDC` and `gDC2` are used if not provided.
-                (Necessary, to accommodate sweeping when optimizing EQ.)
+            1. The instance's current value(s) for ``gDC`` and ``gDC2`` are used if not provided.
+            (Necessary, to accommodate sweeping when optimizing EQ.)
         """
         gDC = gDC or self.gDC
         gDC2 = gDC2 or self.gDC2
@@ -672,9 +676,9 @@ class COM():  # pylint: disable=too-many-instance-attributes,too-many-public-met
 
         Notes:
             1. It is at this point in the analysis that the "raw" Touchstone data
-                gets interpolated to our system frequency vector.
-            2. After this step, the package and R0/Rd mismatch have been accounted for,
-                but not the EQ.
+            gets interpolated to our system frequency vector.
+
+            2. After this step, the package and R0/Rd mismatch have been accounted for, but not the EQ.
         """
 
         assert s2p.s[0].shape == (2, 2), ValueError("I can only convert 2-port networks.")
@@ -704,15 +708,15 @@ class COM():  # pylint: disable=too-many-instance-attributes,too-many-public-met
 
         Keyword Args:
             tx_taps: Tx FFE tap weights.
-                Default: None (i.e. - Use `self.tx_taps`.)
+                Default: None (i.e. - Use ``self.tx_taps``.)
             gDC: CTLE first stage d.c. gain (dB).
-                Default: None (i.e. - Use `self.gDC`.)
+                Default: None (i.e. - Use ``self.gDC``.)
             gDC2: CTLE second stage d.c. gain (dB).
-                Default: None (i.e. - Use `self.gDC2`.)
+                Default: None (i.e. - Use ``self.gDC2``.)
             rx_taps: Rx FFE tap weights.
-                Default: None (i.e. - Use `self.rx_taps`.)
+                Default: None (i.e. - Use ``self.rx_taps``.)
             dfe_taps: Rx DFE tap weights.
-                Default: None (i.e. - Use `self.dfe_taps`.)
+                Default: None (i.e. - Use ``self.dfe_taps``.)
             passive_RxFFE: Enforce passivity of Rx FFE when True.
                 Default: True
 
@@ -724,11 +728,13 @@ class COM():  # pylint: disable=too-many-instance-attributes,too-many-public-met
 
         Notes:
             1. It is in this processing step that linear EQ is first applied.
-            2. Any unprovided EQ values are taken from the `COM` instance.
-                If you really want to omit a particular EQ component then call with:
 
-                - `tx_taps`/`rx_taps`: []
-                - `gDC`/`gDC2`: 0
+            2. Any unprovided EQ values are taken from the ``COM`` instance.
+            If you really want to omit a particular EQ component then call with:
+
+                - ``tx_taps``: []
+                - ``rx_taps``: [1.0]
+                - ``gDC``/``gDC2``: 0
         """
 
         assert s2p.s[0, :, :].shape == (2, 2), ValueError(
@@ -777,7 +783,7 @@ class COM():  # pylint: disable=too-many-instance-attributes,too-many-public-met
 
         Notes:
             1. It is at this point in the signal processing chain that we change
-                time domains.
+            time domains.
         """
 
         assert len(H) == len(self.freqs), ValueError(
@@ -799,17 +805,17 @@ class COM():  # pylint: disable=too-many-instance-attributes,too-many-public-met
 
         Keyword Args:
             ntwks: The list of networks to generate pulse responses for.
-                Default: None (i.e. - Use `self.chnls`.)
+                Default: None (i.e. - Use ``self.chnls``.)
             gDC: Rx CTLE first stage d.c. gain.
-                Default: None (i.e. - Use `self.gDC`.)
+                Default: None (i.e. - Use ``self.gDC``.)
             gDC2: Rx CTLE second stage d.c. gain.
-                Default: None (i.e. - Use `self.gDC2`.)
+                Default: None (i.e. - Use ``self.gDC2``.)
             tx_taps: Desired Tx tap weights.
-                Default: None (i.e. - Use `self.tx_taps`.)
+                Default: None (i.e. - Use ``self.tx_taps``.)
             rx_taps: Desired Rx FFE tap weights.
-                Default: None (i.e. - Use `self.rx_taps`.)
+                Default: None (i.e. - Use ``self.rx_taps``.)
             dfe_taps: Desired Rx DFE tap weights.
-                Default: None (i.e. - Use `self.dfe_taps`.)
+                Default: None (i.e. - Use ``self.dfe_taps``.)
             apply_eq: Include linear EQ when True; otherwise, exclude it.
                 (Allows for pulse response generation of terminated, but unequalized, channel.)
                 Default: True
@@ -817,16 +823,14 @@ class COM():  # pylint: disable=too-many-instance-attributes,too-many-public-met
         Returns:
             list of pulse responses.
 
-        Raises:
-            None
-
         Notes:
-            1. Assumes `self.gDC`, `self.gDC2`, `self.tx_taps`, `self.rx_taps`, and `self.dfe_taps`
-                have been set correctly, if the equivalent function parameters have not been provided.
+            1. Assumes ``self.gDC``, ``self.gDC2``, ``self.tx_taps``, ``self.rx_taps``, and ``self.dfe_taps``
+            have been set correctly, if the equivalent function parameters have not been provided.
+
             2. To generate pulse responses that include all linear EQ except the Rx FFE/DFE
-                (i.e. - pulse responses suitable for Rx FFE/DFE tap weight optimization,
-                via either `optimize.przf()` or `optimize.mmse()`),
-                set `rx_taps` equal to: [1.0] and `dfe_taps` equal to: [].
+            (i.e. - pulse responses suitable for Rx FFE/DFE tap weight optimization,
+            via either ``optimize.przf()`` or ``optimize.mmse()``),
+            set ``rx_taps`` equal to: ``[1.0]`` and ``dfe_taps`` equal to: ``[]``.
         """
 
         gDC  = gDC  or self.gDC  # The more Pythonic way, but doesn't work for lists in newer versions of Python.
@@ -880,7 +884,7 @@ class COM():  # pylint: disable=too-many-instance-attributes,too-many-public-met
                 Default: 0.001 (i.e. - 0.1%, as per Note 2 of 93A.1.7.1)
 
         Returns:
-            The subset of `pr_samps` passing filtration.
+            The subset of ``pr_samps`` passing filtration.
         """
 
         thresh = As * rel_thresh
@@ -930,8 +934,8 @@ class COM():  # pylint: disable=too-many-instance-attributes,too-many-public-met
 
         Notes:
             1. As per v3.70 of the COM MATLAB code, we only minimize the
-                residual of (93A-25); we don't require solving it exactly.
-                (We do, however, give priority to exact solutions.)
+            residual of (93A-25); we don't require solving it exactly.
+            (We do, however, give priority to exact solutions.)
         """
 
         M = self.nspui
@@ -993,20 +997,19 @@ class COM():  # pylint: disable=too-many-instance-attributes,too-many-public-met
             norm_mode: The tap weight normalization mode to use.
                 Default: None (i.e. - Use ``self.norm_mode``.)
             unit_amp: Enforce unit pulse response amplitude when True.
-                (For comparing `optimize.przf()` results to `optimize.mmse()` results.)
+                (For comparing ``optimize.przf()`` results to ``optimize.mmse()`` results.)
                 Default: None (i.e. - Use ``self.unit_amp``.)
 
         Returns:
             The resultant figure of merit.
 
-        Raises:
-            None
-
         Notes:
             1. See: IEEE 802.3-2022 93A.1.6.
-            2. When not provided, the values for ``gDC`` and ``gDC2`` are taken from the `COM` instance.
-            3. Unlike other member functions of the `COM` class,
-                this function **optimizes** the Rx FFE tap weights when they are not provided.
+
+            2. When not provided, the values for ``gDC`` and ``gDC2`` are taken from the ``COM`` instance.
+
+            3. Unlike other member functions of the ``COM`` class,
+               this function *optimizes* the Rx FFE tap weights when they are not provided.
         """
 
         # Honor any mode overrides.
@@ -1146,25 +1149,28 @@ class COM():  # pylint: disable=too-many-instance-attributes,too-many-public-met
         unit_amp: Optional[bool] = None
     ) -> bool:
         """
-        Find the optimum values for the linear equalization parameters:
-        c[n], gDC, gDC2, and w[n] as per IEEE 802.3-22 93A.1.6
+        Find and set the optimum values for the linear equalization parameters:
+        ``c[n]``, ``gDC``, ``gDC2``, and ``w[n]`` as per IEEE 802.3-22 93A.1.6
         (or, [1] slide 11 if MMSE has been chosen).
 
         Keyword Args:
             do_opt_eq: Perform optimization of linear EQ when True.
                 Default: True
-            tx_taps: Used when `do_opt_eq` = False.
+            tx_taps: Used when ``do_opt_eq`` = False.
                 Default: None
             opt_mode: Optimization mode.
-                Default: None (i.e. - Use `self.opt_mode`.)
+                Default: None (i.e. - Use ``self.opt_mode``.)
             norm_mode: The tap weight normalization mode to use.
-                Default: None (i.e. - Use `self.norm_mode`.)
+                Default: None (i.e. - Use ``self.norm_mode``.)
             unit_amp: Enforce unit pulse response amplitude when True.
-                (For comparing `przf()` results to `mmse()` results.)
-                Default: None (i.e. - Use `self.unit_amp`.)
+                (For comparing ``przf()`` results to ``mmse()`` results.)
+                Default: None (i.e. - Use ``self.unit_amp``.)
 
         Returns:
             True if no errors encountered; False otherwise.
+
+        Notes:
+            1. The found optimum equalization values are set for the instance.
         """
 
         if do_opt_eq:
@@ -1267,29 +1273,37 @@ class COM():  # pylint: disable=too-many-instance-attributes,too-many-public-met
                 (In support of MMSE.)
                 Default: None
             opt_mode: Optimization mode.
-                Default: None (i.e. - Use `self.opt_mode`.)
+                Default: None (i.e. - Use ``self.opt_mode``.)
             norm_mode: The tap weight normalization mode to use.
-                Default: None (i.e. - Use `self.norm_mode`.)
+                Default: None (i.e. - Use ``self.norm_mode``.)
             unit_amp: Enforce unit pulse response amplitude when True.
-                (For comparing `przf()` results to `mmse()` results.)
-                Default: None (i.e. - Use `self.unit_amp`.)
+                (For comparing ``przf()`` results to ``mmse()`` results.)
+                Default: None (i.e. - Use ``self.unit_amp``.)
             dbg_dict: Optional dictionary into which debugging values may be stashed,
                 for later analysis.
                 Default: None
 
         Returns:
-            - signal amplitude
-            - noise + interference amplitude (V)
-            - cursor location within victim pulse response vector
+            A triplet containing
+
+                - signal amplitude (V)
+                - noise + interference amplitude (V)
+                - cursor location within victim pulse response vector
 
         Notes:
             1. Assumes the following instance variables have been set optimally:
-                - gDC
-                - gDC2
-                - tx_taps
-                - rx_taps
-                (This assumption is embedded into the `gen_pulse_resps()` function.)
-            2. Fills in the `com_results` dictionary w/ various useful values for debugging.
+
+                - ``gDC``
+                - ``gDC2``
+                - ``tx_taps``
+                - ``rx_taps``
+
+                (This assumption is embedded into the ``gen_pulse_resps()`` function.)
+
+            2. Fills in the ``com_results`` dictionary w/ various useful values for debugging.
+
+        ToDo:
+            1. ``DER0 / 2`` in ``Ani`` calculation?
         """
 
         # Honor any mode overrides.

{pychopmarg-2.1.1 → pychopmarg-2.1.2}/src/pychopmarg/common.py

@@ -6,6 +6,9 @@ Original author: David Banas <capn.freako@gmail.com>
 Original date:   March 3, 2024 (Copied from `pybert.utility`.)
 
 Copyright (c) 2024 David Banas; all rights reserved World wide.
+
+ToDo:
+    1. Specify ``COMParams`` concretely.
 """
 
 from typing import TypeVar, TypeAlias, Any

{pychopmarg-2.1.1 → pychopmarg-2.1.2}/src/pychopmarg/noise.py

@@ -147,25 +147,28 @@ class NoiseCalc():  # pylint: disable=too-many-instance-attributes
 
     def from_irfft(self, x: Rvec) -> Rvec:
         """
-        Interpolate `irfft()` output to `t` and subsample at fBaud.
+        Interpolate ``irfft()`` output to ``t`` and subsample at fBaud.
 
         Args:
-            x: `irfft()` results to be interpolated and subsampled.
+            x: ``irfft()`` results to be interpolated and subsampled.
 
         Returns:
-            y: interpolated and subsampled vector.
+            Interpolated and subsampled vector.
 
         Raises:
-            IndexError: If length of input doesn't match length of `t_irfft` vector.
+            IndexError: If length of input doesn't match length of ``t_irfft`` vector.
 
         Notes:
-            1. Input vector is shifted, such that its peak occurs at `0.1 * max(t)`, before interpolating.
-                This is done to:
-                    - ensure that we don't omit any non-causal behavior,
-                    which ends up at the end of an IFFT output vector
-                    when the peak is very near the beginning, and
-                    - to ensure that the majority of our available time span
-                    is available for capturing reflections.
+            1. Input vector is shifted, such that its peak occurs at ``0.1 * max(t)``, before interpolating.
+               This is done to:
+
+                * ensure that we don't omit any non-causal behavior,
+                  which ends up at the end of an IFFT output vector
+                  when the peak is very near the beginning, and
+
+                * to ensure that the majority of our available time span
+                  is available for capturing reflections.
+
             2. The sub-sampling phase is adjusted, so as to ensure that we catch the peak.
         """
 
@@ -193,8 +196,8 @@ class NoiseCalc():  # pylint: disable=too-many-instance-attributes
         uniformly sampled over [0, PI] (rads./s norm.).
 
         Notes:
-            1. Re: the scaling term: `2 * self.f[-1]`, when combined w/
-                the implicit `1/N` of the `irfft()` function, this gives `df`.
+            1. Re: the scaling term: ``2 * self.f[-1]``, when combined w/
+            the implicit ``1/N`` of the ``irfft()`` function, this gives ``df``.
         """
         # "/ 2" in [1] omitted, since we're only considering: m >= 0.
         rslt  = self.eta0 * 1e-9 * abs(self.Hr * self.Hctf) ** 2
@@ -209,8 +212,7 @@ class NoiseCalc():  # pylint: disable=too-many-instance-attributes
             agg_pulse_resp: Aggressor pulse response (V).
 
         Returns:
-            Sxn: One-sided crosstalk PSD at Rx FFE input,
-                uniformly sampled over [0, PI] (rads./s norm.).
+            One-sided crosstalk PSD at Rx FFE input, uniformly sampled over [0, PI] (rads./s norm.).
         """
 
         nspui = self.nspui
@@ -224,6 +226,9 @@ class NoiseCalc():  # pylint: disable=too-many-instance-attributes
         """
         One-sided Tx noise PSD at Rx FFE input,
         uniformly sampled over [0, PI] (rads./s norm.).
+
+        ToDo:
+            1. Do I need to honor ``ts_ix``?
         """
 
         Tb    = self.Tb

{pychopmarg-2.1.1 → pychopmarg-2.1.2}/src/pychopmarg/optimize.py

@@ -25,10 +25,18 @@ from pychopmarg.noise   import NoiseCalc
 
 class NormMode(Enum):
     "Tap weight normalization mode."
-    P8023dj   = 1  # As per standard (i.e. - clip then renormalize for unit amplitude pulse response.)
-    Scaled    = 2  # Uniformly and minimally scaled to bring tap weights just within their limits.
-    Unaltered = 3  # Use constrained optimization solution, unchanged.
-    UnitDcGain = 4  # Tap weights are uniformly scaled, to yield unity gain at d.c.
+
+    P8023dj   = 1
+    "As per standard (i.e. - clip then renormalize for unit amplitude pulse response.)"
+
+    Scaled    = 2
+    "Uniformly and minimally scaled to bring tap weights just within their limits."
+
+    Unaltered = 3
+    "Use constrained optimization solution, unchanged."
+
+    UnitDcGain = 4
+    "Tap weights are uniformly scaled, to yield unity gain at d.c."
 
 
 def scale_taps(w: Rvec, w_min: Optional[Rvec] = None, w_max: Optional[Rvec] = None) -> Rvec:
@@ -40,12 +48,12 @@ def scale_taps(w: Rvec, w_min: Optional[Rvec] = None, w_max: Optional[Rvec] = No
 
     Keyword Args:
         w_min: Minimum tap weights.
-            Default: None (Use `-ones(len(w))`.)
+            Default: None (Use ``-ones(len(w))``.)
         w_max: Maximum tap weights.
-            Default: None (Use `ones(len(w))`.)
+            Default: None (Use ``ones(len(w))``.)
 
     Returns:
-        w_lim: Tap weights, scaled proportionally, to just fit inside min/max limits.
+        Tap weights, scaled proportionally to just fit inside min/max limits.
     """
 
     if w_min is None:
@@ -82,18 +90,18 @@ def clip_taps(
 
     Args:
         w: The tap weights to clip.
-        curs_ix: The index, in `w`, of the cursor tap.
+        curs_ix: The index, in ``w``, of the cursor tap.
 
     Keyword Args:
         w_min: Minimum tap weights.
-            Default: None (Use `-ones(len(w))`.)
+            Default: None (Use ``-ones(len(w))``.)
         w_max: Maximum tap weights.
-            Default: None (Use `ones(len(w))`.)
+            Default: None (Use ``ones(len(w))``.)
         obey_spec: Allow cursor tap weight to grow w/o bound, as per D1.2, when True.
             Default: True
 
     Returns:
-        w_lim: Tap weights, clipped accordingly.
+        Tap weights, clipped accordingly.
     """
 
     if w_min is None:
@@ -136,7 +144,7 @@ def przf(  # pylint: disable=too-many-arguments,too-many-positional-arguments,to
     norm_mode: NormMode = NormMode.P8023dj, unit_amp: bool = False
 ) -> tuple[Rvec, Rvec, Rvec]:
     """
-    Optimize FFE tap weights, via _Pulse Response Zero Forcing_ (PRZF).
+    Optimize FFE tap weights, via *Pulse Response Zero Forcing* (PRZF).
 
     Args:
         pulse_resp: The pulse response to be filtered.
@@ -151,20 +159,22 @@ def przf(  # pylint: disable=too-many-arguments,too-many-positional-arguments,to
 
     Keyword Args:
         norm_mode: The tap weight normalization mode to use.
-            Default: Unaltered
+            Default: ``P8023dj``
         unit_amp: Enforce unit pulse response amplitude when True.
-            (For comparing results to `mmse()`.)
+            (For comparing results to ``mmse()``.)
             Default: False
 
     Returns:
-        A triple consisting of:
-            - FFE tap weights: The optimum FFE tap weights.
-            - DFE tap weights: The optimum DFE tap weights.
-            - pr_samps: The pulse response samples used in optimization.
+        A triple consisting of
+
+            - The optimum FFE tap weights.
+            - The optimum DFE tap weights.
+            - The pulse response samples used in optimization.
 
     Notes:
         1. The algorithm implemented below is a slightly modified version of:
-            Mellitz, R., Lusted, K., "RX FFE Implementation Algorithm for COM 4.1",
+
+            Mellitz, R., Lusted, K., *RX FFE Implementation Algorithm for COM 4.1*,
             IEEE P802.3dj Task Force, August 31, 2023.
 
     ToDo:
@@ -241,7 +251,7 @@ def mmse(  # pylint: disable=too-many-arguments,too-many-positional-arguments,to
     ts_sweep: float = 0.5, norm_mode: NormMode = NormMode.P8023dj
 ) -> dict[str, Any]:
     """
-    Optimize Rx FFE tap weights, via **Minimum Mean Squared Error** (MMSE).
+    Optimize Rx FFE tap weights, via *Minimum Mean Squared Error* (MMSE).
 
     Args:
         theNoiseCalc: Initialized instance of ``NoiseCalc`` class.
@@ -257,25 +267,27 @@ def mmse(  # pylint: disable=too-many-arguments,too-many-positional-arguments,to
 
     Keyword Args:
         ts_sweep: The cursor sampling time "search radius" around the peak pulse response amplitude (UI).
-            Default: 0.5 (i.e. - `ts` within [-UI/2, +UI/2] of peak location)
+            Default: 0.5 (i.e. - ``ts`` within [-UI/2, +UI/2] of peak location)
         norm_mode: The tap weight normalization mode to use.
-            Default: Unaltered
+            Default: ``P8023dj``
 
     Returns:
-        A dictionary containing:
-            - the optimized FFE tap weights, in the "rx_taps" key,
-            - the optimized DFE tap weights, in the "dfe_tap_weights" key, and
-            - several other values of general utility for plotting/analysis/debugging.
+        A dictionary containing
+
+            * the optimized FFE tap weights, in the "rx_taps" key,
+            * the optimized DFE tap weights, in the "dfe_tap_weights" key, and
+            * several other values of general utility for plotting/analysis/debugging.
 
     Raises:
-        ValueError if:
-            - `dw` > `Nw`, or
-            - there is insufficient room at the beginning/end of the pulse response vector, for `ts` sweeping.
+        ValueError: If ``dw`` > ``Nw``, or there is insufficient room at the beginning/end \
+        of the pulse response vector for ``ts`` sweeping.
 
     Notes:
-        1. The optimization technique encoded here is taken from the following references:
-            [1] Healey, A., Hegde, R., **Reference receiver framework for 200G/lane electrical interfaces and PHYs**,
-                IEEE P802.3dj Task Force, Jan. 2024
+        1. The optimization technique encoded here is taken from the following references
+
+            [1] Healey, A., Hegde, R., *Reference receiver framework for 200G/lane electrical interfaces and PHYs*,
+            IEEE P802.3dj Task Force, Jan. 2024
+
             [2] D1.2 of P802.3dj, IEEE P802.3dj Task Force, Aug. 2024
     """
 

{pychopmarg-2.1.1 → pychopmarg-2.1.2}/src/pychopmarg/utility/filter.py

@@ -3,7 +3,7 @@ Filtering utilities for PyChOpMarg.
 
 Original author: David Banas <capn.freako@gmail.com>
 
-Original date:   March 3, 2024 (Copied from `pybert.utility`.)
+Original date:   March 3, 2024
 
 Copyright (c) 2024 David Banas; all rights reserved World wide.
 """
@@ -26,19 +26,16 @@ def calc_Hctle(  # pylint: disable=too-many-arguments,too-many-positional-argume
     according to (93A-22).
 
     Args:
-        f: Frequencies at which to calculate `Hctle(f)` (Hz).
+        f: Frequencies at which to calculate ``Hctle`` (Hz).
         fz: First stage zero frequency (Hz).
         fp1: First stage lower pole frequency (Hz).
         fp2: First stage upper pole frequency (Hz).
         fLF: Second stage pole/zero frequency (Hz).
-        gDC: CTLE first stage d.c. gain (dB).
-        gDC2: CTLE second stage d.c. gain (dB).
+        gDC: First stage d.c. gain (dB).
+        gDC2: Second stage d.c. gain (dB).
 
     Returns:
         The complex voltage transfer function, H(f), for the CTLE.
-
-    Raises:
-        None
     """
     g1 = from_dB(gDC)
     g2 = from_dB(gDC2)
@@ -56,20 +53,17 @@ def calc_Hffe(
     Calculate the voltage transfer function, H(f), for a digital FFE, according to (93A-21).
 
     Args:
-        freqs: Frequencies at which to calculate `Hffe` (Hz).
+        freqs: Frequencies at which to calculate ``Hffe`` (Hz).
         td: Tap delay time (s).
         tap_weights: The filter tap weights.
         n_post: The number of post-cursor taps.
 
     Keyword Args:
-        hasCurs: `tap_weights` includes the cursor tap weight when True.
+        hasCurs: ``tap_weights`` includes the cursor tap weight when True.
             Default: False (Cursor tap weight will be calculated.)
 
     Returns:
         The complex voltage transfer function, H(f), for the FFE.
-
-    Raises:
-        None
     """
 
     bs = list(np.array(tap_weights).flatten())
@@ -82,10 +76,10 @@ def calc_Hffe(
 
 def calc_Hdfe(freqs: Rvec, td: float, tap_weights: Rvec) -> Cvec:
     """
-    Calculate the voltage transfer function, H(f), for a _Decision Feedback Equalizer_ (DFE).
+    Calculate the voltage transfer function, H(f), for a *Decision Feedback Equalizer* (DFE).
 
     Args:
-        freqs: Frequencies at which to calculate `Hdfe` (Hz).
+        freqs: Frequencies at which to calculate ``Hdfe`` (Hz).
         td: Tap delay time (s).
         tap_weights: The vector of filter tap weights.
 
@@ -100,7 +94,7 @@ def calc_Hdfe(freqs: Rvec, td: float, tap_weights: Rvec) -> Cvec:
 
 def null_filter(nTaps: int, nPreTaps: int = 0) -> Rvec:
     """
-    Construct a null filter w/ `nTaps` taps and (optionally) `nPreTaps` pre-cursor taps.
+    Construct a null filter w/ ``nTaps`` taps and (optionally) ``nPreTaps`` pre-cursor taps.
 
     Args:
         nTaps: Total number of taps, including the cursor tap.
@@ -110,7 +104,7 @@ def null_filter(nTaps: int, nPreTaps: int = 0) -> Rvec:
             Default: 0
 
     Returns:
-        taps: The filter tap weight vector, including the cursor tap weight.
+        The filter tap weight vector, including the cursor tap weight.
     """
 
     assert nTaps > 0, ValueError(

{pychopmarg-2.1.1 → pychopmarg-2.1.2}/src/pychopmarg/utility/general.py

@@ -3,7 +3,7 @@ General purpose utilities for PyChOpMarg.
 
 Original author: David Banas <capn.freako@gmail.com>
 
-Original date:   March 3, 2024 (Copied from `pybert.utility`.)
+Original date:   March 3, 2024
 
 Copyright (c) 2024 David Banas; all rights reserved World wide.
 """
@@ -43,7 +43,7 @@ def mk_combs(trips: list[tuple[float, float, float]]) -> list[list[float]]:
         trips: A list of "(min, max, step)" triples, one per weight.
 
     Returns:
-        combs: A list of lists of tap weights, including all possible combinations.
+        A list of lists of tap weights, including all possible combinations.
     """
     ranges = []
     for trip in trips:
@@ -56,28 +56,30 @@ def mk_combs(trips: list[tuple[float, float, float]]) -> list[list[float]]:
 
 def from_irfft(x: Rvec, t_irfft: Rvec, t: Rvec, nspui: int) -> Rvec:
     """
-    Interpolate `irfft()` output to `t` and subsample at fBaud.
+    Interpolate ``irfft()`` output to ``t`` and subsample at fBaud.
 
     Args:
-        x: `irfft()` results to be interpolated and subsampled.
-        t_irfft: Time index vector for `x`.
-        t: Desired new time index vector (same units as `t_irfft`).
-        nspui: Number of samples per unit interval.
+        x: ``irfft()`` results to be interpolated and subsampled.
+        t_irfft: Time index vector for ``x``.
+        t: Desired new time index vector (same units as ``t_irfft``).
+        nspui: Number of samples per unit interval in ``t``.
 
     Returns:
-        y: interpolated and subsampled vector.
+        Interpolated and subsampled vector.
 
     Raises:
-        IndexError: If length of input doesn't match length of `t_irfft` vector.
+        IndexError: If length of input doesn't match length of ``t_irfft`` vector.
 
     Notes:
-        1. Input vector is shifted, such that its peak occurs at `0.1 * max(t)`, before interpolating.
-            This is done to:
-                - ensure that we don't omit any non-causal behavior,
-                which ends up at the end of an IFFT output vector
-                when the peak is very near the beginning, and
-                - to ensure that the majority of our available time span
-                is available for capturing reflections.
+        1. Input vector is shifted, such that its peak occurs at ``0.1 * max(t)``, before interpolating.
+        This is done to:
+
+            - ensure that we don't omit any non-causal behavior,
+              which ends up at the end of an IFFT output vector
+              when the peak is very near the beginning, and
+            - to ensure that the majority of our available time span
+              is available for capturing reflections.
+
         2. The sub-sampling phase is adjusted, so as to ensure that we catch the peak.
     """
 

{pychopmarg-2.1.1 → pychopmarg-2.1.2}/src/pychopmarg/utility/probability.py

@@ -3,7 +3,7 @@ Statistical utilities for PyChOpMarg.
 
 Original author: David Banas <capn.freako@gmail.com>
 
-Original date:   March 3, 2024 (Copied from `pybert.utility`.)
+Original date:   March 3, 2024
 
 Copyright (c) 2024 David Banas; all rights reserved World wide.
 """
@@ -28,7 +28,7 @@ def filt_pr_samps(pr_samps: Rvec, As: float, rel_thresh: float = 0.001) -> Rvec:
             Default: 0.001 (i.e. - 0.1%, as per Note 2 of 93A.1.7.1)
 
     Returns:
-        The subset of `pr_samps` passing filtration.
+        The subset of ``pr_samps`` passing filtration.
     """
     thresh = As * rel_thresh
     return np.array(list(filter(lambda x: abs(x) >= thresh, pr_samps)))
@@ -58,19 +58,20 @@ def delta_pmf(  # pylint: disable=too-many-arguments,too-many-positional-argumen
             Default: None
 
     Returns:
-        A pair consisting of:
-        - the voltages corresponding to the bins, and
-        - their probabilities.
+        A pair consisting of
+
+            - the voltages corresponding to the bins, and
+            - their probabilities.
 
     Raises:
-        `ValueError` if the given pulse response contains any NaNs.
-        `ValueError` if a needed shift exceeds half the result vector length.
+        ValueError: If the given pulse response contains any NaNs.
+        ValueError: If a needed shift exceeds half the result vector length.
 
     Notes:
         1. The input set of pulse response samples is filtered,
-            as per Note 2 of 93A.1.7.1, unless a y-values override
-            vector is provided, in which case it is assumed that
-            the caller has already done the filtering.
+        as per Note 2 of 93A.1.7.1, unless a y-values override
+        vector is provided, in which case it is assumed that
+        the caller has already done the filtering.
     """
 
     assert not any(np.isnan(h_samps)), ValueError(

{pychopmarg-2.1.1 → pychopmarg-2.1.2}/src/pychopmarg/utility/sparams.py

@@ -3,7 +3,7 @@ S-parameter utilities for PyChOpMarg.
 
 Original author: David Banas <capn.freako@gmail.com>
 
-Original date:   March 3, 2024 (Copied from `pybert.utility`.)
+Original date:   March 3, 2024
 
 Copyright (c) 2024 David Banas; all rights reserved World wide.
 """
@@ -27,7 +27,7 @@ def sdd_21(ntwk: rf.Network, norm: float = 0.5, renumber: bool = False) -> rf.Ne
 
     Keyword Args:
         norm: Normalization factor. (Default = 0.5)
-        renumber: Automatically detect correct through path when True.
+        renumber: Automatically detect and correct through path when True.
                   Default: False
 
     Returns:
@@ -43,22 +43,27 @@ def sdd_21(ntwk: rf.Network, norm: float = 0.5, renumber: bool = False) -> rf.Ne
 
 def se2mm(ntwk: rf.Network, norm: float = 0.5, renumber: bool = False) -> rf.Network:
     """
-    Given a 4-port single-ended network, return its mixed mode equivalent.
+    Given a 4-port single-ended network,
+    return its mixed mode equivalent in the following format:
+
+    .. math::
+        \\begin{bmatrix}
+            Sdd11 & Sdd12 & Sdc11 & Sdc12 \\\\
+            Sdd21 & Sdd22 & Sdc21 & Sdc22 \\\\
+            Scd11 & Scd12 & Scc11 & Scc12 \\\\
+            Scd21 & Scd22 & Scc21 & Scc22
+        \\end{bmatrix}
 
     Args:
         ntwk: 4-port single ended network.
 
     Keyword Args:
         norm: Normalization factor. (Default = 0.5)
-        renumber: Automatically detect correct through path when True.
+        renumber: Automatically detect and correct through path when True.
                   Default: False
 
     Returns:
-        Mixed mode equivalent network, in the following format:
-            Sdd11  Sdd12  Sdc11  Sdc12
-            Sdd21  Sdd22  Sdc21  Sdc22
-            Scd11  Scd12  Scc11  Scc12
-            Scd21  Scd22  Scc21  Scc22
+        Mixed mode equivalent network.
 
     Notes:
         1. A "1->2/3->4" port ordering convention is assumed when `renumber` is False.
@@ -121,9 +126,10 @@ def import_s32p(  # pylint: disable=too-many-locals
 
     Returns:
         List of 8 pairs, each consisting of:
+
             - a 2-port network representing a *differential* channel, and
             - the type of that channel, one of: 'THRU', 'NEXT', or 'FEXT.
-                (First element is the victim and the only one of type 'THRU'.)
+              (First element is the victim and the only one of type 'THRU'.)
 
     Raises:
         ValueError: If Touchstone file is not 32-port.
@@ -132,7 +138,7 @@ def import_s32p(  # pylint: disable=too-many-locals
         1. Input Touchstone file is assumed single-ended.
         2. The differential through and xtalk channels are returned.
         3. Port 2 of all returned channels correspond to the same physical circuit node,
-            typically, the Rx input node.
+           typically, the Rx input node.
     """
 
     # Import and sanity check the Touchstone file.
@@ -197,8 +203,8 @@ def sCshunt(freqs: Rvec, c: float, r0: float = 50.0) -> rf.Network:
             Default: 50 Ohms.
 
     Returns:
-        s2p: The network corresponding to a shunt capacitance, `c`,
-            calculated at the given frequencies, `freqs`.
+        The network corresponding to a shunt capacitance, ``c``,
+        calculated at the given frequencies, ``freqs``.
     """
     w = TWOPI * np.array(freqs)
     s = 1j * w
@@ -221,8 +227,8 @@ def sLseries(freqs: Rvec, inductance: float, r0: float = 50.0) -> rf.Network:
             Default: 50 Ohms.
 
     Returns:
-        s2p: The network corresponding to a series inductance, `inductance`,
-            calculated at the given frequencies, `freqs`.
+        The network corresponding to a series inductance, ``inductance``,
+        calculated at the given frequencies, ``freqs``.
     """
     w = TWOPI * np.array(freqs)
     s = 1j * w
@@ -242,12 +248,13 @@ def sDieLadderSegment(freqs: Rvec, trip: tuple[float, float, float]) -> rf.Netwo
     Args:
         f: List of frequencies to use for network creation (Hz).
         trip: Triple containing:
+
             - R0: Reference impedance for network (Ohms).
             - Cd: Shunt capacitance (F).
             - Ls: Series inductance (H).
 
     Returns:
-        s2p: Two port network for segment.
+        Two port network for segment.
     """
     R0, Cd, Ls = trip
     return sCshunt(freqs, Cd, r0=R0) ** sLseries(freqs, Ls, r0=R0)
@@ -269,6 +276,7 @@ def sPkgTline(  # pylint: disable=too-many-arguments,too-many-positional-argumen
         tau: Propagation delay (ns/mm).
         gamma0: Propagation loss constant (1/mm).
         z_pairs: List of pairs defining the T-line segments, each containing:
+
             - zc: Characteristic impedance of segment (Ohms).
             - zp: Length of segment (mm).
 
@@ -297,6 +305,7 @@ def sPkgTline(  # pylint: disable=too-many-arguments,too-many-positional-argumen
 
         Args:
             z_pair: Pair consisting of:
+
                 - zc: Characteristic impedance of leg (Ohms).
                 - zp: Length of leg (mm).