mhostetter · mhostetter · Aug 13, 2023 · Aug 7, 2023 · Aug 10, 2023 · Aug 10, 2023
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -25,16 +25,22 @@
         "exponentials",
         "Feedforward",
         "hexdump",
+        "lowpass",
         "matplotlib",
+        "multirate",
         "overdamped",
         "passband",
         "periodogram",
         "periodograms",
+        "polyphase",
         "pyplot",
         "resampler",
         "resamplers",
         "scipy",
+        "sinc",
+        "stopband",
         "underdamped",
+        "upsampled",
         "upsampling"
     ]
 }
diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@
   <a href="https://github.com/mhostetter/sdr/actions/workflows/lint.yaml"><img src="https://github.com/mhostetter/sdr/actions/workflows/lint.yaml/badge.svg"></a>
   <a href="https://github.com/mhostetter/sdr/actions/workflows/build.yaml"><img src="https://github.com/mhostetter/sdr/actions/workflows/build.yaml/badge.svg"></a>
   <a href="https://github.com/mhostetter/sdr/actions/workflows/test.yaml"><img src="https://github.com/mhostetter/sdr/actions/workflows/test.yaml/badge.svg"></a>
-  <a href="https://codecov.io/gh/mhostetter/sdr"><img src="https://codecov.io/gh/mhostetter/sdr/branch/master/graph/badge.svg?token=3FJML79ZUK"></a>
+  <a href="https://codecov.io/gh/mhostetter/sdr"><img src="https://codecov.io/gh/mhostetter/sdr/branch/main/graph/badge.svg?token=3FJML79ZUK"></a>
 </div>
 
 The `sdr` library is a Python 3 package for software-defined radio (SDR).
@@ -46,44 +46,24 @@ python3 -m pip install sdr
 
 ## Features
 
-- Digital signal processing:
-   - Filtering: `sdr.FIR`, `sdr.FIRInterpolator`, `sdr.IIR`
-   - Resampling: `sdr.FarrowResampler`
-   - Signal manipulation: `sdr.mix()`, `sdr.to_complex_bb()`, `sdr.to_real_pb()`
-- Sequences: `sdr.barker()`, `sdr.zadoff_chu()`
-- Modulation:
-   - Classes: `sdr.PSK`
-   - Pulse shapes: `sdr.raised_cosine()`, `sdr.root_raised_cosine()`, `sdr.gaussian()`
-   - Symbol mapping: `sdr.binary_code()`, `sdr.gray_code()`
-   - Symbol encoding: `sdr.diff_encode()`, `sdr.diff_decode()`
-- Synchronization: `sdr.NCO`, `sdr.DDS`, `sdr.LoopFilter`, `sdr.ClosedLoopPLL`
-- Measurement:
-   - Energy: `sdr.energy()`
-   - Power: `sdr.peak_power()`, `sdr.average_power()`, `sdr.papr()`
-   - Voltage: `sdr.peak_voltage()`, `sdr.rms_voltage()`, `sdr.crest_factor()`
-   - Modulation: `sdr.ErrorRate`, `sdr.evm()`
-- Conversions:
-   - From $E_b/N_0$: `sdr.ebn0_to_esn0()`, `sdr.ebn0_to_snr()`
-   - From $E_s/N_0$: `sdr.esn0_to_ebn0()`, `sdr.esn0_to_snr()`
-   - From $S/N$: `sdr.snr_to_ebn0()`, `sdr.snr_to_esn0()`
-- Simulation:
-   - Channel models: `sdr.bec()`, `sdr.bsc()`, `sdr.dmc()`
-   - Signal impairments: `sdr.awgn()`, `sdr.frequency_offset()`, `sdr.sample_rate_offset()`,
-     `sdr.iq_imbalance()`
-- Link budgets:
-   - Channel capacity: `sdr.awgn_capacity()`, `sdr.bec_capacity()`, `sdr.bsc_capacity()`
-   - Path losses: `sdr.fspl()`
-   - Antennas: `sdr.parabolic_antenna()`
-- Probability: `sdr.Q()`, `sdr.Qinv()`
-- Data manipulation: `sdr.pack()`, `sdr.unpack()`, `sdr.hexdump()`
-- Plotting:
-   - Time-domain: `sdr.plot.time_domain()`
-   - Spectral estimation: `sdr.plot.periodogram()`, `sdr.plot.spectrogram()`
-   - Modulation: `sdr.plot.ber()`, `sdr.plot.ser()`, `sdr.plot.constellation()`,
-     `sdr.plot.symbol_map()`
-   - Filters: `sdr.plot.impulse_response()`, `sdr.plot.step_response()`,
-     `sdr.plot.frequency_response()`, `sdr.plot.phase_response()`, `sdr.plot.phase_delay()`,
-     `sdr.plot.group_delay()`, `sdr.plot.zeros_poles()`, `sdr.plot.filter()`
+View all available classes and functions in the [API Reference](https://mhostetter.github.io/sdr/latest/api/dsp/).
+
+- **Digital signal processing**: Finite impulse response (FIR) filters, infinite impulse response (IIR) filters,
+  polyphase interpolator, polyphase decimator, polyphase resampler, Farrow arbitrary resampler,
+  complex mixing, real/complex conversion.
+- **Sequences**: Barker, Zadoff-Chu.
+- **Modulation**: Phase-shift keying (PSK), raised cosine pulse shape, root raised cosine pulse shape,
+  Gaussian pulse shape, binary and Gray symbol mapping, differential encoding.
+- **Synchronization**: Numerically-controlled oscillators (NCO), direct digital synthesizers (DDS), loop filters,
+  closed-loop PLL analysis.
+- **Measurement**: Energy, power, voltage, bit/symbol error rate, error vector magnitude (EVM).
+- **Conversions**: Between linear units and decibels. Between $E_b/N_0$, $E_s/N_0$, and $S/N$.
+- **Simulation**: Binary symmetric channel (BSC), binary erasure channel (BEC), discrete memoryless channel (DMC),
+  additive white Gaussian noise (AWGN), frequency offset, sample rate offset, IQ imbalance.
+- **Link budgets**: Channel capacities, free-space path loss, antenna gains.
+- **Data manipulation**: Packing and unpacking binary data, hexdumping binary data.
+- **Plotting**: Time-domain, periodogram, spectrogram, BER, SER, constellation, symbol map, impulse response,
+  step response, magnitude response, phase response, phase delay, group delay, and zeros/poles.
 
 ## Examples
 

diff --git a/docs/api/conversions.rst b/docs/api/conversions.rst
@@ -1,6 +1,11 @@
 Conversions
 ===========
 
+Decibels
+--------
+
+.. python-apigen-group:: conversions-decibels
+
 From $E_b/N_0$
 --------------
 

diff --git a/docs/api/dsp.rst b/docs/api/dsp.rst
@@ -6,7 +6,12 @@ Digital signal processing
 Filtering
 ---------
 
-.. python-apigen-group:: filtering
+.. python-apigen-group:: dsp-filtering
+
+Multirate filtering
+-------------------
+
+.. python-apigen-group:: dsp-multirate-filtering
 
 Resampling
 ----------

diff --git a/docs/conf.py b/docs/conf.py
@@ -273,7 +273,7 @@
     ("property:.*", 60),
     (r".*:.*\.is_[a-z,_]*", 70),
 ]
-python_apigen_order_tiebreaker = "alphabetical"
+# python_apigen_order_tiebreaker = "alphabetical"
 python_apigen_case_insensitive_filesystem = False
 python_apigen_show_base_classes = True
 

diff --git a/docs/examples/farrow-resampler.ipynb b/docs/examples/farrow-resampler.ipynb
diff --git a/docs/examples/fir-filters.ipynb b/docs/examples/fir-filters.ipynb
diff --git a/docs/examples/iir-filters.ipynb b/docs/examples/iir-filters.ipynb
diff --git a/docs/examples/peak-to-average-power.ipynb b/docs/examples/peak-to-average-power.ipynb
diff --git a/docs/examples/phase-locked-loop.ipynb b/docs/examples/phase-locked-loop.ipynb
diff --git a/docs/examples/psk.ipynb b/docs/examples/psk.ipynb
diff --git a/docs/examples/pulse-shapes.ipynb b/docs/examples/pulse-shapes.ipynb
diff --git a/docs/index.rst b/docs/index.rst
@@ -37,44 +37,24 @@ The latest version of :obj:`sdr` can be installed from `PyPI`_ using `pip`_.
 Features
 --------
 
-- Digital signal processing:
-   - Filtering: :class:`sdr.FIR`, :class:`sdr.FIRInterpolator`, :class:`sdr.IIR`
-   - Resampling: :class:`sdr.FarrowResampler`
-   - Signal manipulation: :func:`sdr.mix()`, :func:`sdr.to_complex_bb()`, :func:`sdr.to_real_pb()`
-- Sequences: :func:`sdr.barker()`, :func:`sdr.zadoff_chu()`
-- Modulation:
-   - Classes: :class:`sdr.PSK`
-   - Pulse shapes: :func:`sdr.raised_cosine()`, :func:`sdr.root_raised_cosine()`, :func:`sdr.gaussian()`
-   - Symbol mapping: :func:`sdr.binary_code()`, :func:`sdr.gray_code()`
-   - Symbol encoding: :func:`sdr.diff_encode()`, :func:`sdr.diff_decode()`
-- Synchronization: :class:`sdr.NCO`, :class:`sdr.DDS`, :class:`sdr.LoopFilter`, :class:`sdr.ClosedLoopPLL`
-- Measurement:
-   - Energy: :func:`sdr.energy()`
-   - Power: :func:`sdr.peak_power()`, :func:`sdr.average_power()`, :func:`sdr.papr()`
-   - Voltage: :func:`sdr.peak_voltage()`, :func:`sdr.rms_voltage()`, :func:`sdr.crest_factor()`
-   - Modulation: :class:`sdr.ErrorRate`, :func:`sdr.evm()`
-- Conversions:
-   - From $E_b/N_0$: :func:`sdr.ebn0_to_esn0()`, :func:`sdr.ebn0_to_snr()`
-   - From $E_s/N_0$: :func:`sdr.esn0_to_ebn0()`, :func:`sdr.esn0_to_snr()`
-   - From $S/N$: :func:`sdr.snr_to_ebn0()`, :func:`sdr.snr_to_esn0()`
-- Simulation:
-   - Channel models: :func:`sdr.bec()`, :func:`sdr.bsc()`, :func:`sdr.dmc()`
-   - Signal impairments: :func:`sdr.awgn()`, :func:`sdr.frequency_offset()`, :func:`sdr.sample_rate_offset()`,
-     :func:`sdr.iq_imbalance()`
-- Link budgets:
-   - Channel capacity: :func:`sdr.awgn_capacity()`, :func:`sdr.bec_capacity()`, :func:`sdr.bsc_capacity()`
-   - Path losses: :func:`sdr.fspl()`
-   - Antennas: :func:`sdr.parabolic_antenna()`
-- Probability: :func:`sdr.Q()`, :func:`sdr.Qinv()`
-- Data manipulation: :func:`sdr.pack()`, :func:`sdr.unpack()`, :func:`sdr.hexdump()`
-- Plotting:
-   - Time-domain: :func:`sdr.plot.time_domain()`
-   - Spectral estimation: :func:`sdr.plot.periodogram()`, :func:`sdr.plot.spectrogram()`
-   - Modulation: :func:`sdr.plot.ber()`, :func:`sdr.plot.ser()`, :func:`sdr.plot.constellation()`,
-     :func:`sdr.plot.symbol_map()`
-   - Filters: :func:`sdr.plot.impulse_response()`, :func:`sdr.plot.step_response()`,
-     :func:`sdr.plot.frequency_response()`, :func:`sdr.plot.phase_response()`, :func:`sdr.plot.phase_delay()`,
-     :func:`sdr.plot.group_delay()`, :func:`sdr.plot.zeros_poles()`, :func:`sdr.plot.filter()`
+View all available classes and functions in the `API Reference <https://mhostetter.github.io/sdr/latest/api/dsp/>`_.
+
+- **Digital signal processing**: Finite impulse response (FIR) filters, infinite impulse response (IIR) filters,
+  polyphase interpolator, polyphase decimator, polyphase resampler, Farrow arbitrary resampler,
+  complex mixing, real/complex conversion.
+- **Sequences**: Barker, Zadoff-Chu.
+- **Modulation**: Phase-shift keying (PSK), raised cosine pulse shape, root raised cosine pulse shape,
+  Gaussian pulse shape, binary and Gray symbol mapping, differential encoding.
+- **Synchronization**: Numerically-controlled oscillators (NCO), direct digital synthesizers (DDS), loop filters,
+  closed-loop PLL analysis.
+- **Measurement**: Energy, power, voltage, bit/symbol error rate, error vector magnitude (EVM).
+- **Conversions**: Between linear units and decibels. Between $E_b/N_0$, $E_s/N_0$, and $S/N$.
+- **Simulation**: Binary symmetric channel (BSC), binary erasure channel (BEC), discrete memoryless channel (DMC),
+  additive white Gaussian noise (AWGN), frequency offset, sample rate offset, IQ imbalance.
+- **Link budgets**: Channel capacities, free-space path loss, antenna gains.
+- **Data manipulation**: Packing and unpacking binary data, hexdumping binary data.
+- **Plotting**: Time-domain, periodogram, spectrogram, BER, SER, constellation, symbol map, impulse response,
+  step response, magnitude response, phase response, phase delay, group delay, and zeros/poles.
 
 .. toctree::
    :caption: Examples

diff --git a/docs/release-notes/v0.0.md b/docs/release-notes/v0.0.md
@@ -4,6 +4,30 @@ tocdepth: 2
 
 # v0.0
 
+## v0.0.5
+
+*Released August 13, 2023*
+
+### Changes
+
+- Added polyphase FIR decimator in `sdr.Decimator()`.
+- Added multirate FIR filter design in `sdr.multirate_taps()`.
+- Added polyphase decomposition in `sdr.polyphase_matrix()`.
+- Added linear to decibel conversion in `sdr.db()`.
+- Added decibel to linear conversion in `sdr.linear()`.
+- Added linear and zero-order hold polyphase FIR interpolators.
+- Added a `state` property to FIR filters.
+- Added a `flush()` method to FIR filters.
+- Added support for passing filter objects into filter plotting functions.
+- Added ability to center or offset a time-domain plot.
+- Improved the string representation of classes.
+- Renamed `sdr.plot.frequency_response()` to `sdr.plot.magnitude_response()`.
+- Removed superfluous methods like `FIR.filter()` and replaced with `FIR.__call__()`.
+
+### Contributors
+
+- Matt Hostetter ([@mhostetter](https://github.com/mhostetter))
+
 ## v0.0.4
 
 *Released August 6, 2023*

diff --git a/src/sdr/__init__.py b/src/sdr/__init__.py
@@ -14,6 +14,7 @@
     )
 
 from . import plot
+from ._conversion import *
 from ._data import *
 from ._farrow import *
 from ._filter import *
@@ -27,4 +28,3 @@
 from ._sequence import *
 from ._signal import *
 from ._simulation import *
-from ._snr import *
diff --git a/src/sdr/_snr.py → src/sdr/_conversion.py b/src/sdr/_snr.py → src/sdr/_conversion.py
@@ -1,13 +1,143 @@
 """
-A module that converts between various types of signal-to-noise ratios (SNRs).
+A module that contains various conversion functions.
 """
 from __future__ import annotations
 
 import numpy as np
 import numpy.typing as npt
+from typing_extensions import Literal
 
 from ._helper import export
 
+##############################################################################
+# Decibels
+##############################################################################
+
+
+@export
+def db(
+    x: npt.ArrayLike,
+    type: Literal["value", "power", "voltage"] = "value",  # pylint: disable=redefined-builtin
+) -> np.ndarray:
+    r"""
+    Converts from linear units to decibels.
+
+    Arguments:
+        x: The input value or signal.
+        type: The type of input value or signal.
+
+            - `"value"`: The input value/signal is any value.
+
+            $$x_{\text{dB}} = 10 \log_{10} x_{\text{linear}}$$
+
+            - `"power"`: The input value/signal is a power measurement.
+
+            $$P_{\text{dB}} = 10 \log_{10} P_{\text{linear}}$$
+
+            - `"voltage"`: The input value/signal is a voltage measurement.
+
+            $$V_{\text{dB}} = 20 \log_{10} V_{\text{linear}}$$
+
+    Returns:
+        The value or signal in dB.
+
+    Examples:
+        Convert 50 MHz to 77 dB-Hz.
+
+        .. ipython:: python
+
+            sdr.db(50e6)
+
+        Convert 100 mW to 20 dBm.
+
+        .. ipython:: python
+
+            sdr.db(100, type="power")
+
+        Convert 2 V to 6 dBV.
+
+        .. ipython:: python
+
+            sdr.db(2, type="voltage")
+
+    Group:
+        conversions-decibels
+    """
+    x = np.asarray(x)
+    if not np.all(x >= 0):
+        raise ValueError("Argument 'x' must be non-negative.")
+
+    if type in ["value", "power"]:
+        return 10 * np.log10(x)
+
+    if type == "voltage":
+        return 20 * np.log10(x)
+
+    raise ValueError(f"Argument 'type' must be 'value', 'power', or 'voltage', not {type!r}.")
+
+
+@export
+def linear(
+    x: npt.ArrayLike,
+    type: Literal["value", "power", "voltage"] = "value",  # pylint: disable=redefined-builtin
+) -> np.ndarray:
+    r"""
+    Converts from decibels to linear units.
+
+    Arguments:
+        x: The input value or signal in dB.
+        type: The type of output value or signal.
+
+            - `"value"`: The output value/signal is any value.
+
+            $$x_{\text{linear}} = 10^{\frac{x_{\text{dB}}}{10}}$$
+
+            - `"power"`: The output value/signal is a power measurement.
+
+            $$P_{\text{linear}} = 10^{\frac{P_{\text{dB}}}{10}}$$
+
+            - `"voltage"`: The output value/signal is a voltage measurement.
+
+            $$V_{\text{linear}} = 10^{\frac{V_{\text{dB}}}{20}}$$
+
+    Returns:
+        The value or signal in linear units.
+
+    Examples:
+        Convert 77 dB-Hz to 50 MHz.
+
+        .. ipython:: python
+
+            sdr.linear(77)
+
+        Convert 20 dBm to 100 mW.
+
+        .. ipython:: python
+
+            sdr.linear(20, type="power")
+
+        Convert 6 dBV to 2 V.
+
+        .. ipython:: python
+
+            sdr.linear(6, type="voltage")
+
+    Group:
+        conversions-decibels
+    """
+    x = np.asarray(x)
+    if not np.all(x >= 0):
+        raise ValueError("Argument 'x' must be non-negative.")
+
+    if type in ["value", "power"]:
+        return 10 ** (x / 10)
+
+    if type == "voltage":
+        return 10 ** (x / 20)
+
+    raise ValueError(f"Argument 'type' must be 'value', 'power', or 'voltage', not {type!r}.")
+
+
 ##############################################################################
 # From Eb/N0
 ##############################################################################