Reorganize library and API reference

mhostetter · Jul 27, 2023 · fe8fa84 · fe8fa84
1 parent ac6cc8a
commit fe8fa84
Show file tree

Hide file tree

Showing 47 changed files with 496 additions and 387 deletions.
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1,4 +1,4 @@
-api/
+api/sdr.*
 build/
 jupyter_execute/
 savefig/
diff --git a/docs/api.rst b/docs/api.rst
diff --git a/docs/api/data-manipulation.rst b/docs/api/data-manipulation.rst
@@ -0,0 +1,4 @@
+Data manipulation
+-----------------
+
+.. python-apigen-group:: data
diff --git a/docs/api/filtering.rst b/docs/api/filtering.rst
@@ -0,0 +1,6 @@
+.. py:module:: sdr
+
+Filtering
+=========
+
+.. python-apigen-group:: filtering
diff --git a/docs/api/link-budgets.rst b/docs/api/link-budgets.rst
@@ -0,0 +1,17 @@
+Link budgets
+============
+
+Channel capacity
+----------------
+
+.. python-apigen-group:: link-budget-channel-capacity
+
+Path losses
+-----------
+
+.. python-apigen-group:: link-budget-path-losses
+
+Antennas
+--------
+
+.. python-apigen-group:: link-budget-antennas
diff --git a/docs/api/measurement.rst b/docs/api/measurement.rst
@@ -0,0 +1,17 @@
+Measurement
+===========
+
+Energy
+------
+
+.. python-apigen-group:: measurement-energy
+
+Power
+-----
+
+.. python-apigen-group:: measurement-power
+
+Voltage
+-------
+
+.. python-apigen-group:: measurement-voltage
diff --git a/docs/api/modulation.rst b/docs/api/modulation.rst
@@ -0,0 +1,22 @@
+Modulation
+==========
+
+Classes
+-------
+
+.. python-apigen-group:: modulation-classes
+
+Pulse shaping
+-------------
+
+.. python-apigen-group:: modulation-pulse-shaping
+
+Symbol mapping
+--------------
+
+.. python-apigen-group:: modulation-symbol-mapping
+
+Symbol encoding
+---------------
+
+.. python-apigen-group:: modulation-symbol-encoding
diff --git a/docs/api/plotting.rst b/docs/api/plotting.rst
@@ -0,0 +1,22 @@
+Plotting
+--------
+
+Configuration
+.............
+
+.. python-apigen-group:: plot-config
+
+Time-domain
+...........
+
+.. python-apigen-group:: plot-time
+
+Frequency-domain
+................
+
+.. python-apigen-group:: plot-freq
+
+Filter analysis
+...............
+
+.. python-apigen-group:: plot-filter
diff --git a/docs/api/probability.rst b/docs/api/probability.rst
@@ -0,0 +1,4 @@
+Probability
+-----------
+
+.. python-apigen-group:: probability
diff --git a/docs/api/resampling.rst b/docs/api/resampling.rst
@@ -0,0 +1,4 @@
+Resampling
+----------
+
+.. python-apigen-group:: resampling
diff --git a/docs/api/simulation.rst b/docs/api/simulation.rst
@@ -0,0 +1,12 @@
+Simulation
+==========
+
+Channel models
+--------------
+
+.. python-apigen-group:: simulation-channel-models
+
+Signal impairments
+------------------
+
+.. python-apigen-group:: simulation-impairments
diff --git a/docs/api/synchronization.rst b/docs/api/synchronization.rst
@@ -0,0 +1,4 @@
+Synchronization
+===============
+
+.. python-apigen-group:: pll
diff --git a/docs/index.rst b/docs/index.rst
@@ -59,9 +59,19 @@ Features
 .. toctree::
    :caption: API Reference
    :hidden:
-   :maxdepth: 2
+   :maxdepth: 4
 
-   api.rst
+   api/filtering.rst
+   api/resampling.rst
+   api/modulation.rst
+   api/synchronization.rst
+   api/impairments.rst
+   api/measurement.rst
+   api/simulation.rst
+   api/link-budgets.rst
+   api/probability.rst
+   api/data-manipulation.rst
+   api/plotting.rst
 
 .. toctree::
    :caption: Release Notes

diff --git a/src/sdr/__init__.py b/src/sdr/__init__.py
@@ -14,17 +14,14 @@
     )
 
 from . import plot
-from ._capacity import *
-from ._channel_model import *
 from ._data import *
 from ._farrow import *
 from ._filter import *
-from ._impairment import *
 from ._link_budget import *
 from ._loop_filter import *
 from ._measurement import *
 from ._modulation import *
 from ._nco import *
 from ._pll import *
 from ._probability import *
-from ._pulse_shape import *
+from ._simulation import *
diff --git a/src/sdr/_constants.py b/src/sdr/_constants.py
@@ -0,0 +1,4 @@
+"""
+A module with various physical constants.
+"""
+SPEED_OF_LIGHT = 299_792_458  # m/s
diff --git a/src/sdr/_farrow.py b/src/sdr/_farrow.py
@@ -89,6 +89,8 @@ def resample(self, x: npt.ArrayLike, rate: float) -> np.ndarray:
         Examples:
             See the :ref:`farrow-arbitrary-resampler` example.
         """
+        if not isinstance(rate, (int, float)):
+            raise TypeError("Argument 'rate' must be an integer or float.")
         if not rate > 0:
             raise ValueError("Argument 'rate' must be positive.")
 

diff --git a/src/sdr/_link_budget/__init__.py b/src/sdr/_link_budget/__init__.py
@@ -0,0 +1,6 @@
+"""
+A subpackage for link budget calculations.
+"""
+from ._antenna import *
+from ._capacity import *
+from ._path_loss import *
diff --git a/src/sdr/_link_budget.py → src/sdr/_link_budget/_antenna.py b/src/sdr/_link_budget.py → src/sdr/_link_budget/_antenna.py
@@ -1,58 +1,13 @@
 """
-A module containing functions for calculating link budgets.
+A module containing functions for calculating antenna gains.
 """
 from __future__ import annotations
 
 import numpy as np
 import numpy.typing as npt
 
-from ._helper import export
-
-SPEED_OF_LIGHT = 299_792_458  # m/s
-
-
-@export
-def fspl(d: npt.ArrayLike, f: npt.ArrayLike) -> npt.ArrayLike:
-    r"""
-    Calculates the free-space path loss (FSPL) in dB.
-
-    $$\text{FSPL} = 10 \log_{10} \left( \frac{4 \pi d f}{c} \right)^2$$
-
-    Arguments:
-        d: The distance $d$ in meters between the transmitter and receiver.
-        f: The frequency $f$ in Hz of the signal.
-
-    Returns:
-        The free-space path loss (FSPL) in dB.
-
-    Examples:
-        Compute the free-space path loss for a 1 km link at 1 GHz.
-
-        .. ipython:: python
-
-            sdr.fspl(1e3, 1e9)
-
-        The free-space path loss is proportional to the square of the distance. So, doubling the distance
-        results in a 6 dB increase in the free-space path loss.
-
-        .. ipython:: python
-
-            sdr.fspl(2e3, 1e9)
-
-        The free-space path loss is also proportional to the square of the frequency. So, doubling the frequency
-        results in a 6 dB increase in the free-space path loss.
-
-        .. ipython:: python
-
-            sdr.fspl(1e3, 2e9)
-
-    Group:
-        link-budget
-    """
-    d = np.asarray(d)
-    f = np.asarray(f)
-    loss = 20 * np.log10(4 * np.pi * d * f / SPEED_OF_LIGHT)
-    return loss
+from .._constants import SPEED_OF_LIGHT
+from .._helper import export
 
 
 @export
@@ -94,7 +49,7 @@ def parabolic_antenna(
             sdr.parabolic_antenna(1e9, 2)
 
     Group:
-        link-budget
+        link-budget-antennas
     """
     freq = np.asarray(freq)
 

diff --git a/src/sdr/_capacity.py → src/sdr/_link_budget/_capacity.py b/src/sdr/_capacity.py → src/sdr/_link_budget/_capacity.py
@@ -6,7 +6,7 @@
 import numpy as np
 import numpy.typing as npt
 
-from ._helper import export
+from .._helper import export
 
 
 def Hb(x: npt.ArrayLike) -> np.ndarray:
@@ -60,7 +60,7 @@ def bsc_capacity(p: npt.ArrayLike) -> np.ndarray:
             plt.tight_layout()
 
     Group:
-        link-budget
+        link-budget-channel-capacity
     """
     p = np.asarray(p)
     if not (np.all(0 <= p) and np.all(p <= 1)):
@@ -108,7 +108,7 @@ def bec_capacity(p: npt.ArrayLike) -> np.ndarray:
             plt.tight_layout()
 
     Group:
-        link-budget
+        link-budget-channel-capacity
     """
     p = np.asarray(p)
     if not (np.all(0 <= p) and np.all(p <= 1)):
@@ -185,7 +185,7 @@ def awgn_capacity(snr: npt.ArrayLike, bandwidth: float | None = None) -> np.ndar
             plt.tight_layout()
 
     Group:
-        link-budget
+        link-budget-channel-capacity
     """
     snr = np.asarray(snr)
     snr_linear = 10 ** (snr / 10)