pymodulation 0.1.0__tar.gz → 0.2.0__tar.gz

pymodulation-0.2.0/AUTHORS

@@ -0,0 +1,9 @@
+# This is the list of PyModulation's significant contributors.
+#
+# This does not necessarily list everyone who has contributed code,
+# especially since many members of one organization may be contributing.
+# To see the full list of contributors, see the revision history in
+# source control.
+
+Gabriel Mariano Marcelino <gabriel.mm8@gmail.com>
+Carlos Augusto Porto Freitas <carlos.portof@hotmail.com>

{pymodulation-0.1.0 → pymodulation-0.2.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: pymodulation
-Version: 0.1.0
+Version: 0.2.0
 Summary: PyModulation library
-Home-page: https://github.com/mgm8/pymodulation
-Download-URL: https://github.com/mgm8/pymodulation/releases
+Home-page: https://github.com/pymodulation/pymodulation
+Download-URL: https://github.com/pymodulation/pymodulation/releases
 Author: Gabriel Mariano Marcelino
 Author-email: gabriel.mm8@gmail.com
 Maintainer: Gabriel Mariano Marcelino
@@ -30,6 +30,7 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Description-Content-Type: text/markdown
 License-File: LICENSE
+License-File: AUTHORS
 Requires-Dist: numpy
 Requires-Dist: scipy
 Dynamic: author
@@ -48,20 +49,23 @@ Dynamic: requires-dist
 Dynamic: summary
 
 <h1 align="center">
-    <a href="https://mgm8.github.io/pymodulation/"><img src="docs/img/logo.jpg" alt="PyModulation" width="50%"></a>
+    <a href="https://pymodulation.github.io/pymodulation/"><img src="docs/img/logo.jpg" alt="PyModulation" width="50%"></a>
 </h1>
 
 <a href="https://pypi.org/project/pymodulation/">
     <img src="https://img.shields.io/pypi/v/pymodulation?style=for-the-badge">
 </a>
+<a href="https://doi.org/10.5281/zenodo.18202698">
+    <img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.18202698-blue?style=for-the-badge">
+</a>
 <a href="https://pypi.org/project/pymodulation/">
     <img src="https://img.shields.io/pypi/pyversions/pymodulation?style=for-the-badge">
 </a>
-<a href="https://github.com/mgm8/pymodulation/blob/main/LICENSE">
-    <img src="https://img.shields.io/github/license/mgm8/pymodulation?style=for-the-badge">
+<a href="https://github.com/pymodulation/pymodulation/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/pymodulation/pymodulation?style=for-the-badge">
 </a>
-<a href="https://github.com/mgm8/pymodulation/actions">
-    <img src="https://img.shields.io/github/actions/workflow/status/mgm8/pymodulation/test.yml?style=for-the-badge">
+<a href="https://github.com/pymodulation/pymodulation/actions">
+    <img src="https://img.shields.io/github/actions/workflow/status/pymodulation/pymodulation/test.yml?style=for-the-badge">
 </a>
 
 ## Overview
@@ -75,11 +79,12 @@ PyModulation is suitable for a wide range of applications, including SDR-based t
 The following modulations are currently supported:
 
 * GFSK/GMSK
+* BPSK
 
 ## Dependencies
 
-* NumPy
-* SciPy
+* [NumPy](https://numpy.org/)
+* [SciPy](https://scipy.org/)
 
 ## Installing
 
@@ -89,9 +94,9 @@ This library can be installed directly from the source files:
 
 ## Documentation
 
-The documentation page is available [here](https://mgm8.github.io/pymodulation/). Instructions to build the documentation page are described below.
+The documentation page is available [here](https://pymodulation.github.io/pymodulation/). Instructions to build the documentation page are described below.
 
-Contributing instructions are also available [here](https://github.com/mgm8/pyngham/blob/main/CONTRIBUTING.md).
+Contributing instructions are also available [here](https://github.com/pymodulation/pyngham/blob/main/CONTRIBUTING.md).
 
 ### Dependencies
 
@@ -103,6 +108,23 @@ The documentation pages can be built with Sphinx by running the following comman
 
 * ```make html```
 
+## Citing
+
+If you use PyModulation in your academic work or project, you can cite it:
+
+```
+@misc{marcelino2026,
+    author       = {Marcelino, Gabriel Mariano},
+    title        = {PyModulation},
+    month        = jan,
+    year         = 2026,
+    publisher    = {Zenodo},
+    version      = {v0.1},
+    doi          = {10.5281/zenodo.18202698},
+    url          = {https://doi.org/10.5281/zenodo.18202698},
+}
+```
+
 ## License
 
 This project is licensed under LGPLv3 license.

{pymodulation-0.1.0 → pymodulation-0.2.0}/README.md

@@ -1,18 +1,21 @@
 <h1 align="center">
-    <a href="https://mgm8.github.io/pymodulation/"><img src="docs/img/logo.jpg" alt="PyModulation" width="50%"></a>
+    <a href="https://pymodulation.github.io/pymodulation/"><img src="docs/img/logo.jpg" alt="PyModulation" width="50%"></a>
 </h1>
 
 <a href="https://pypi.org/project/pymodulation/">
     <img src="https://img.shields.io/pypi/v/pymodulation?style=for-the-badge">
 </a>
+<a href="https://doi.org/10.5281/zenodo.18202698">
+    <img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.18202698-blue?style=for-the-badge">
+</a>
 <a href="https://pypi.org/project/pymodulation/">
     <img src="https://img.shields.io/pypi/pyversions/pymodulation?style=for-the-badge">
 </a>
-<a href="https://github.com/mgm8/pymodulation/blob/main/LICENSE">
-    <img src="https://img.shields.io/github/license/mgm8/pymodulation?style=for-the-badge">
+<a href="https://github.com/pymodulation/pymodulation/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/pymodulation/pymodulation?style=for-the-badge">
 </a>
-<a href="https://github.com/mgm8/pymodulation/actions">
-    <img src="https://img.shields.io/github/actions/workflow/status/mgm8/pymodulation/test.yml?style=for-the-badge">
+<a href="https://github.com/pymodulation/pymodulation/actions">
+    <img src="https://img.shields.io/github/actions/workflow/status/pymodulation/pymodulation/test.yml?style=for-the-badge">
 </a>
 
 ## Overview
@@ -26,11 +29,12 @@ PyModulation is suitable for a wide range of applications, including SDR-based t
 The following modulations are currently supported:
 
 * GFSK/GMSK
+* BPSK
 
 ## Dependencies
 
-* NumPy
-* SciPy
+* [NumPy](https://numpy.org/)
+* [SciPy](https://scipy.org/)
 
 ## Installing
 
@@ -40,9 +44,9 @@ This library can be installed directly from the source files:
 
 ## Documentation
 
-The documentation page is available [here](https://mgm8.github.io/pymodulation/). Instructions to build the documentation page are described below.
+The documentation page is available [here](https://pymodulation.github.io/pymodulation/). Instructions to build the documentation page are described below.
 
-Contributing instructions are also available [here](https://github.com/mgm8/pyngham/blob/main/CONTRIBUTING.md).
+Contributing instructions are also available [here](https://github.com/pymodulation/pyngham/blob/main/CONTRIBUTING.md).
 
 ### Dependencies
 
@@ -54,6 +58,23 @@ The documentation pages can be built with Sphinx by running the following comman
 
 * ```make html```
 
+## Citing
+
+If you use PyModulation in your academic work or project, you can cite it:
+
+```
+@misc{marcelino2026,
+    author       = {Marcelino, Gabriel Mariano},
+    title        = {PyModulation},
+    month        = jan,
+    year         = 2026,
+    publisher    = {Zenodo},
+    version      = {v0.1},
+    doi          = {10.5281/zenodo.18202698},
+    url          = {https://doi.org/10.5281/zenodo.18202698},
+}
+```
+
 ## License
 
 This project is licensed under LGPLv3 license.

{pymodulation-0.1.0 → pymodulation-0.2.0}/pymodulation/__init__.py

@@ -22,5 +22,6 @@
 
 from pymodulation.version import __version__
 
+from pymodulation.bpsk import BPSK
 from pymodulation.gfsk import GFSK
 from pymodulation.gmsk import GMSK

pymodulation-0.2.0/pymodulation/bpsk.py

@@ -0,0 +1,109 @@
+#
+# bpsk.py
+# 
+# Copyright The PyModulation Contributors.
+# 
+# This file is part of PyModulation library.
+# 
+# PyModulation library is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# PyModulation library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with PyModulation library. If not, see <http://www.gnu.org/licenses/>.
+# 
+#
+
+import numpy as np
+from scipy.signal import upfirdn
+
+from pymodulation.modulation import Modulation
+
+_BPSK_DEFAULT_OVERSAMPLING_FACTOR = 100
+
+class BPSK(Modulation):
+    """
+    BPSK modulator/demodulator.
+    """
+
+    def modulate(self, data: list, L=_BPSK_DEFAULT_OVERSAMPLING_FACTOR):
+        """
+        Modulate data into BPSK IQ samples (baseband).
+
+        :param data: List of integers with the data bytes.
+        :type: list
+
+        :param L: Oversampling factor (Tb/Ts)
+        :type: int
+
+        :return: Tuple of (IQ samples, sample rate in Hz, transmission duration in seconds)
+        :rtype: tuple(np.ndarray, float, float)
+        """
+        s_bb, t = self.modulate_time_domain(data, L)
+        samples = s_bb.astype(np.complex64) # BPSK is purely real at baseband
+
+        f_sym = self.get_baudrate()         # Symbol rate in baud
+        fs = L * f_sym                      # Sample rate in Hz
+
+        n_bits = len(data) * 8
+        dur = n_bits / f_sym                # Transmission duration in seconds
+
+        return samples, fs, dur
+
+    def modulate_time_domain(self, data, L=_BPSK_DEFAULT_OVERSAMPLING_FACTOR):
+        """
+        Generates the BPSK modulated signal in time domain (baseband).
+
+        :param data: List of integers with the data bytes.
+        :type: list
+
+        :param L: Oversampling factor (Tb/Ts)
+        :type: int
+
+        :return: Baseband signal in time domain (length N*L).
+        :rtype: np.ndarray
+
+        :return: Discrete time base (length N*L).
+        :rtype: np.ndarray
+        """
+        # Convert to array of bits
+        bits = np.array(self._int_list_to_bit_list(data))
+        n_bits = len(bits)
+
+        # NRZ encoder: upfirdn with h=[1]*L produces output of length N*L + L-1
+        s_bb_full = upfirdn(h=[1] * L, x=2 * bits - 1, up=L)
+
+        s_bb = s_bb_full[:n_bits * L]
+
+        t = np.arange(start=0, stop=n_bits * L)  # Discrete time base
+
+        return s_bb, t
+
+    def demodulate(self, samples: np.ndarray, fs) -> list:
+        """
+        Demodulate BPSK IQ samples into bits.
+
+        :param samples: IQ samples.
+        :type: np.ndarray
+
+        :param fs: Sample rate in S/s
+        :type: int
+
+        :return: Demodulated bits (0 or 1).
+        :rtype: list
+        """
+        L = int(fs/self.get_baudrate()) # Oversampling factor (Samples/bit)
+        x = np.real(samples)            # I arm
+        x = np.convolve(x, np.ones(L))  # Integrate for Tb duration (L samples)
+
+        x = x[L - 1::L]                 # Sample at the end of each integration window
+
+        bits = (x > 0).transpose()      # Threshold detector
+
+        return list(map(int, bits))

pymodulation-0.2.0/pymodulation/gfsk.py

@@ -0,0 +1,330 @@
+#
+# gfsk.py
+#
+# Copyright The PyModulation Contributors.
+#
+# This file is part of PyModulation library.
+#
+# PyModulation library is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# PyModulation library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with PyModulation library. If not, see <http://www.gnu.org/licenses/>.
+#
+#
+
+import numpy as np
+from scipy.signal import upfirdn, lfilter
+
+from pymodulation.modulation import Modulation
+
+_GFSK_DEFAULT_OVERSAMPLING_FACTOR = 100
+
+class GFSK(Modulation):
+    """
+    GFSK modulator/demodulator.
+    """
+
+    def __init__(self, modidx, bt, baud):
+        """
+        Class constructor with modulation initialization.
+
+        :param modidx: Modulation index.
+        :type: float
+
+        :param bt: BT product (bandwidth x bit period) for GFSK.
+        :type: float
+
+        :param baud: The desired data rate in bps.
+        :type: int
+
+        :return None
+        """
+        super().__init__(baud)
+
+        self._mod_index = float()
+        self._bt        = float()
+
+        self.set_modulation_index(modidx)
+        self.set_bt(bt)
+
+    def set_modulation_index(self, modidx):
+        """
+        Sets the modulation index.
+
+        :param modidx: The new modulation index.
+        :type: float
+
+        :return: None.
+        """
+        self._mod_index = modidx
+
+    def get_modulation_index(self):
+        """
+        Gets the modulation index.
+
+        :return: The configured modulation index.
+        :rtype: float
+        """
+        return self._mod_index
+
+    def set_bt(self, bt):
+        """
+        Sets the bandwidth-time index.
+
+        :param bt: The new bandwidth-time product.
+        :type: float
+
+        :return: None
+        """
+        self._bt = bt
+
+    def get_bt(self):
+        """
+        Gets the current bandwidth-time index.
+
+        :return: The configured bandwidth-time product.
+        :rtype: float
+        """
+        return self._bt
+
+    def modulate(self, data, sps=_GFSK_DEFAULT_OVERSAMPLING_FACTOR):
+        """
+        Function to modulate an integer stream using GFSK modulation.
+
+        :param data: input integer list to modulate (bytes as integers)
+        :type: list
+
+        :param sps: Samples per symbol.
+        :type: int
+
+        :return: s_complex: baseband GFSK signal (I+jQ).
+        :rtype: np.ndarray
+
+        :return: samp: Sample rate in S/s.
+        :rtype: int
+
+        :return: dur: Signal duration in seconds.
+        :rtype: float
+        """
+        I, Q, fs, dur = self.get_iq(data, sps)
+        s_complex = I + 1j * Q  # Complex baseband representation
+
+        return s_complex, fs, dur
+
+    def get_iq(self, data, sps=_GFSK_DEFAULT_OVERSAMPLING_FACTOR):
+        """
+        Computes the IQ data of the GFSK modulated signal.
+
+        :param data: Input integer list to modulate (bytes as integers).
+        :type: list
+
+        :param sps: Samples per symbol.
+        :type: int
+
+        :return: I: I data of the modulated signal
+        :rtype: TODO
+
+        :return: Q: Q data of the modulated signal
+        :rtype: TODO
+
+        :return: samp: Sample rate in S/s.
+        :rtype: int
+
+        :return: dur: Signal duration in seconds
+        :rtype: float
+        """
+        # Convert to array of bits
+        data = self._int_list_to_bit_list(data)
+
+        data = np.array(data)
+
+        # Timing parameters
+        fc = self.get_baudrate()    # Carrier frequency = Data transfer rate in bps
+        fs = sps * fc               # Sample frequency in Hz
+        Ts = np.float64(1.0) / fs   # Sample period in seconds
+        Tb = sps * Ts               # Bit period in seconds
+
+        c_t = upfirdn(h=[1] * sps, x=2 * data - 1, up=sps)  # NRZ pulse train c(t)
+        k = 1                                               # Truncation length for Gaussian LPF
+        h_t = self.gaussian_lpf(Tb, sps, k)                 # Gaussian LPF
+        b_t = np.convolve(h_t, c_t, "full")                 # Convolve c(t) with Gaussian LPF to get b(t)
+        bnorm_t = b_t / np.max(np.abs(b_t))                 # Normalize the output of Gaussian LPF to +/-1
+
+        # Integrate to get phase information
+        h = np.float64(self.get_modulation_index())         # Modulation index
+        phi_t = lfilter(b=[1], a=[1, -1], x=bnorm_t * Ts) * h * np.pi / Tb
+        I = np.cos(phi_t)
+        Q = np.sin(phi_t)                                   # Cross-correlated baseband I/Q signals
+
+        # Sampling values
+        dur = len(data) * Tb        # Transmission duration in seconds
+
+        return I, Q, fs, dur
+
+    def modulate_time_domain(self, data, sps=_GFSK_DEFAULT_OVERSAMPLING_FACTOR):
+        """
+        Generates the GFSK modulated signal in time domain.
+
+        :param data: Input integer list to modulate (bytes as integers).
+        :type: list
+
+        :param sps: Samples per symbol.
+        :type: int
+
+        :return: s_t: GFSK modulated signal with carrier s(t) (time domain).
+        :rtype: TODO
+
+        :return: samp: Sample rate in S/s.
+        :rtype: int
+
+        :return: dur: Signal duration in seconds.
+        :rtype: float
+        """
+        I, Q, samp, dur = self.get_iq(data, sps)
+
+        fc = self.get_baudrate()  # Carrier frequency = Data transfer rate in bps
+        fs = sps * fc
+        Ts = 1 / fs
+
+        t = Ts * np.arange(start=0, stop=len(I))    # Time base for RF carrier
+        sI_t = I * np.cos(2 * np.pi * fc * t)
+        sQ_t = Q * np.sin(2 * np.pi * fc * t)
+        s_t = sI_t - sQ_t                           # s(t) - GFSK with RF carrier
+
+        return s_t, t, samp, dur
+
+    def gaussian_lpf(self, Tb, sps, k):
+        """
+        Generate filter coefficients of Gaussian low pass filter.
+
+        :param Tb: Bit period.
+        :type: float
+
+        :param sps: Samples per symbol.
+        :type: int
+
+        :param k: Span length of the pulse (bit interval).
+        :type: float
+
+        :return h_norm: normalized filter coefficients of Gaussian LPF
+        :rtype: list
+        """
+        B = self.get_bt() / Tb  # Bandwidth of the filter
+
+        # Truncated time limits for the filter
+        t = np.arange(start=-k * Tb, stop=k * Tb + Tb / sps, step=Tb / sps)
+        h = (B * np.sqrt(2 * np.pi / (np.log(2))) * np.exp(-2 * (t * np.pi * B) ** 2 / (np.log(2))))
+        h_norm = h / np.sum(h)
+
+        return h_norm
+
+    def gaussian_pulse(self, Tb, sps, k):
+        """
+        Construct the Gaussian pulse shape from gaussian filter impulse response taps.
+
+        :param Tb: Bit period.
+        :type: float
+
+        :param sps: Samples per symbol.
+        :type: int
+
+        :param k: Span of the gaussian filter impulse response.
+        :type: TODO
+
+        :return: Gaussian pulse shape.
+        :rtype: np.ndarray
+        """
+        h = self.gaussian_lpf(Tb, sps, k)
+        nrz = np.ones(sps)
+        g = np.convolve(h, nrz, mode="full")
+
+        return g / np.sum(g)
+
+    def demodulate(self, iq_samples, fs):
+        """
+        Perform GFSK demodulation.
+
+        :param iq_samples: IQ samples.
+        :type: np.ndarray
+
+        :param fs: Sample rate in S/s.
+        :type: int
+
+        :return: The demodulated bitstream.
+        :rtype: list
+
+        :return: The baseband signal in NRZ format.
+        :rtype: list
+        """
+        sps = int(fs / self.get_baudrate())
+
+        # Applies the gain of quadrature demod following the equation: gain = fs / (2π * deviation), where deviation is: h * baudrate / 2
+        gain = fs / (np.pi * self.get_modulation_index() * self.get_baudrate())
+
+        # Frequency discriminator
+        freq_deviation = gain * self._frequency_discriminator(iq_samples)
+
+        # Apply Gaussian matched filter
+        gaussian_filter = self.gaussian_pulse(1 / self.get_baudrate(), sps, 1)
+        filtered_signal = np.convolve(freq_deviation, gaussian_filter, mode="same")
+
+        # Downsample to symbol rate
+        sampled_signal = filtered_signal[sps // 2 :: sps]
+
+        # Decision thresholding
+        demodulated_bits = (sampled_signal > 0).astype(int)
+
+        return list(demodulated_bits), sampled_signal
+
+    def _frequency_discriminator(self, iq_samples):
+        """
+        Extract frequency deviations using phase changes in IQ samples.
+
+        :param iq_samples: IQ samples.
+        :type: np.ndarray
+
+        :return: TODO
+        :rtype: TODO
+        """
+        freq_deviation = np.angle(iq_samples[1:] * np.conj(iq_samples[:-1]))
+
+        return np.concatenate([[0], freq_deviation])  # Keep length consistent
+
+    def quadrature_demod_soft(self, samples, fs):
+        """
+        Non-coherent demodulation based on frequency discrimination.
+
+        :param samples: Signal IQ samples.
+        :type: np.ndarray
+
+        :param fs: Sample rate in S/s.
+        :type: int
+
+        :return: Soft symbols at the same rate of the input samples (meaning that sps remains the same, useful for time synchronization loop later).
+        :rtype: TODO
+        """
+        iq_samples = np.asarray(samples, dtype=np.complex64)
+
+        sps = int(fs / self._baudrate)
+
+        # Applies the gain of quadrature demod following the equation: gain = fs / (2π * deviation), where deviation is: h * baudrate / 2
+        gain = fs / (np.pi * self.get_modulation_index() * self.get_baudrate())
+
+        freq_deviation = gain * self._frequency_discriminator(iq_samples)
+
+        # Removing DC (mean) from deviation is equivalent to removing residual Carrier Frequency Offset (CFO)
+        freq_deviation -= np.mean(freq_deviation)
+
+        # Apply matched filter
+        g = self.gaussian_pulse(1 / self._baudrate, sps, 1)
+        soft_symbols = np.convolve(freq_deviation, g, "same")
+
+        return soft_symbols

{pymodulation-0.1.0 → pymodulation-0.2.0}/pymodulation/gmsk.py

@@ -24,16 +24,17 @@ from pymodulation.gfsk import GFSK
 
 class GMSK(GFSK):
     """
-    GMSK modulator.
+    GMSK modulator/demodulator.
     """
+
     def __init__(self, bt, baud):
         """
         Class constructor with modulation initialization.
 
-        :param bt: BT product (bandwidth x bit period) for GMSK
+        :param bt: BT product (bandwidth x bit period) for GMSK.
         :type: float
 
-        :param baud: The desired data rate in bps
+        :param baud: The desired data rate in bps.
         :type: int
 
         :return: None.