commkit 1.0.0__py3-none-any.whl

commkit-1.0.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: commkit
+Version: 1.0.0
+Summary: A Python library for high-performance digital communications research.
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: jax>=0.10
+Requires-Dist: matplotlib>=3.11
+Requires-Dist: numba>=0.65
+Requires-Dist: numpy>=2.4
+Requires-Dist: pydantic>=2.13
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: scipy>=1.17
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda13x>=14.1; extra == 'gpu'
+Requires-Dist: jax[cuda13]>=0.10; extra == 'gpu'
+Requires-Dist: nvidia-curand>=10.4.1.34; extra == 'gpu'
+Provides-Extra: notebook
+Requires-Dist: jupyter>=1.1.1; extra == 'notebook'
+Description-Content-Type: text/markdown
+
+# CommKit
+
+**High-performance digital communications research kit for Python.**
+
+![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)
+![Backends](https://img.shields.io/badge/backend-NumPy%20%7C%20CuPy%20%7C%20JAX-orange)
+![License](https://img.shields.io/badge/license-MIT-green)
+![CUDA](https://img.shields.io/badge/CUDA-13.x-76B900?logo=nvidia)
+
+---
+
+CommKit is a Python library for digital communications research that treats hardware as a first-class concern. A single `Signal` object carries IQ samples, physical metadata, and modulation context - with DSP operations dispatching automatically to NumPy, CuPy, or JAX based on data location.
+
+---
+
+## Why CommKit?
+
+- **One object, complete context:** Sampling rate, symbol rate, modulation format, and pulse shape travel with the signal through the processing pipeline.
+- **Backend-transparent DSP:** `dispatch()` resolves NumPy, CuPy, or SciPy modules at runtime. The same code executes seamlessly on CPU or GPU.
+- **Method chaining:** High-level fluent API (`sig.to("gpu").fir_filter(taps).resample(sps_out=2)...`) for rapid prototyping.
+- **JAX escape hatch:** Zero-copy DLPack export on GPU allows direct application of JAX transforms (gradients, `vmap`, `scan`) without leaving the research loop.
+
+---
+
+## Modules & Features
+
+| Module | Key Capabilities & Features |
+| --- | --- |
+| [`commkit.core`](commkit/core) | `Signal` container (IQ samples + metadata), `SingleCarrierFrame`, `Preamble`, and symbol/frame factories (PAM, PSK, QAM). |
+| [`commkit.backend`](commkit/backend.py) | Hardware abstraction layer (`dispatch`, `to_device`, `to_jax`, `from_jax`), placement management, and backend execution (NumPy, CuPy, JAX). |
+| [`commkit.mapping`](commkit/mapping) | Gray-coded constellations, symbol mapping, hard demapping, soft LLR computation (max-log and exact log-sum-exp via JAX JIT), and GMI. |
+| [`commkit.filtering`](commkit/filtering.py) | Pulse shaping (RRC, RC, Gaussian, Smooth-Rectangle), tap generators, matched filtering, Overlap-Save, and polyphase multirate filtering. |
+| [`commkit.multirate`](commkit/multirate.py) | Fractional and integer sample rate conversion (`resample`, `decimate`, `upsample`, `decimate_to_symbol_rate`). |
+| [`commkit.timing`](commkit/timing.py) | Preamble generation (Barker, Zadoff-Chu), cross-correlation timing delay estimation, and frame alignment. |
+| [`commkit.frequency`](commkit/frequency.py) | Carrier frequency offset estimation (FOE via M-th power, Mengali-Morelli, Jacobsen) and phase-locked FOE correction. |
+| [`commkit.recovery`](commkit/recovery) | Carrier phase recovery (CPR via Viterbi-Viterbi, BPS, DD-PLL) and cycle-slip detection/correction. |
+| [`commkit.equalization`](commkit/equalization) | Adaptive equalizers (`lms`, `rls`, `cma`, `rde`, `zf`), butterfly MIMO topology support, with Numba JIT and JAX execution backends. |
+| [`commkit.impairments`](commkit/impairments) | Channel impairments simulation: AWGN (with SPS correction), PMD (differential group delay, Jones matrix), phase noise, IQ imbalance, and chromatic dispersion. |
+| [`commkit.coding`](commkit/coding) | Channel coding and FEC primitives (BCH, Convolutional, CRC, Galois field arithmetic, Hamming, Interleaving, LDPC, Polar, Rate matching, Reed-Solomon, Turbo codes). |
+| [`commkit.metrics`](commkit/metrics.py) | System performance evaluation: EVM (%, dB), data-aided SNR, and BER estimation. |
+| [`commkit.analysis`](commkit/analysis) | Laser phase and linewidth characterization: DSH, homodyne IQ, zero-phase drift detrending, AWGN-free lag-slope linewidth fit, Di Domenico $\beta$-separation line FWHM, and Allan deviation. |
+| [`commkit.spectral`](commkit/spectral.py) | Welch PSD estimation and frequency shifting with bin-quantized mixing. |
+| [`commkit.io`](commkit/io.py) | Signal persistence and disk serialization (`load_npz`, `save_npz`). |
+| [`commkit.plotting`](commkit/plotting) | Visualization tools for constellations, eye diagrams, PSDs, time-domain signals, filter responses, and equalizer convergence. |
+| [`commkit.helpers`](commkit/helpers.py) | General DSP helpers: random bit/symbol generators, array normalization, RMS calculation, and SI prefix formatting. |
+
+---
+
+## Installation & Usage
+
+**Requires Python 3.12+** and [`uv`](https://github.com/astral-sh/uv).
+
+### Core Installation (CPU)
+
+```bash
+# Using uv (Recommended)
+uv pip install git+https://github.com/lokgar/commkit.git
+
+# Or with standard pip
+pip install git+https://github.com/lokgar/commkit.git
+```
+
+### GPU Support
+
+To install with CUDA acceleration (includes JAX CUDA 13 and CuPy stacks):
+
+```bash
+# Using uv
+uv pip install "commkit[gpu] @ git+https://github.com/lokgar/commkit.git"
+
+# Or with standard pip
+pip install "commkit[gpu] @ git+https://github.com/lokgar/commkit.git"
+```
+
+> [!NOTE]
+> **WSL2 CUDA Configuration:**  
+> When NVIDIA drivers and CUDA are properly installed on Windows, there is no need to install CUDA inside WSL2. However, to allow Python CUDA packages inside WSL2 to locate the bundled NVIDIA shared libraries, add the following line to your `~/.bashrc`:
+>
+> ```bash
+> export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$(echo $HOME/commkit/.venv/lib/python3.*/site-packages/nvidia/cu13/lib)
+> ```
+>
+> *(Assumes `commkit` is cloned in `$HOME/commkit`. If located elsewhere, replace `$HOME/commkit` with `<path-to-repo>`. `python3.*/` matches any Python version automatically).*
+
+### Development Installation
+
+```bash
+git clone https://github.com/lokgar/commkit.git
+cd commkit
+
+# Sync core environment
+uv sync
+
+# Sync environment with all extras (including GPU packages)
+uv sync --all-extras
+```
+
+---
+
+## Examples & Notebooks
+
+For complete usage scripts and DSP examples, explore the [`examples/`](examples) directory.
+
+---
+
+## Running Tests
+
+```bash
+# CPU test suite
+uv run pytest --device=cpu
+
+# GPU test suite (requires CuPy + CUDA)
+uv run pytest --device=gpu
+
+# Run all test suites
+uv run pytest --device=all
+```
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

commkit-1.0.0.dist-info/RECORD

@@ -0,0 +1,84 @@
+commkit/__init__.py,sha256=m9-JgEkO_ba43EXxfw6z2Dk9nHRH4-Cbo82WEuwwZwo,1922
+commkit/backend.py,sha256=k3EpznsfHZd6OVlYbi3Kx-GZfxY904QuhbQfIYObpfg,15786
+commkit/filtering.py,sha256=EkT9_ogjKyysdR1xfaexXVFYiH-5ZrOHpWkN4mm-bE8,37452
+commkit/frequency.py,sha256=uTtTx7cp6enYYtFBCWHvu0LpKFGDTXQgfnJqCj2geG4,46152
+commkit/helpers.py,sha256=b2qzLAQzSTdFl9emBSXYHew5Ib5ZbREWo0qo4aCqrfI,17402
+commkit/io.py,sha256=xSH58lNYg64BnsHojO13GvMdKeitiKAhy05_gQs20Z8,11991
+commkit/logger.py,sha256=C1HWxH_G3CC2RVfXt7QDkFy7ztCfb4TJknR_GqPmA8g,2790
+commkit/metrics.py,sha256=Ypmdv0VoMmJnoe2ow2HTEq5WfwyEjiOz1Y2chFUNxQ4,35975
+commkit/multirate.py,sha256=pFmq_zwnM7ejLhvondEZq3yTHpv3wJR3sTtqkj2a010,17059
+commkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+commkit/spectral.py,sha256=pQcoqoI8j73uDUOG1ydNfbxvokfFg9eC0ATX5kkQB14,21071
+commkit/timing.py,sha256=0yTn0iB1S3P8vsnUFYZjCSlPEzq-8OpqJIYetmkurWg,31785
+commkit/_cuda/__init__.py,sha256=ivwcVqDn_buIKf9QEkRy4EW3NwyXL3KTPvn6cFrzJbU,11028
+commkit/_cuda/compiler.py,sha256=auZBcdGBUHnLSSpv2d8IkSwgfni3SD_XR_9dBTQxgTE,2669
+commkit/_cuda/src/bps_min_d2.cu,sha256=2qqv9o-kMW_ddChF5rSf1k-Xg17HZ3by1RASO5AFiwQ,4078
+commkit/_cuda/src/cs_block.cu,sha256=NLVXTX8wYUo1gtYXDu3Dx4Z_TqJsuvy_iqu0JZBJjFg,5021
+commkit/_cuda/src/selftest.cu,sha256=wVM-4HvA8egVF6CGp7Q_Z4A0SlO8dW6sQZmcMwpoPDo,511
+commkit/analysis/__init__.py,sha256=6ENcGmyhW946NHYGR7UIzMhFLMCThjVDoJ2scJqt7HU,2160
+commkit/analysis/_common.py,sha256=mEkXRDmRdesqHykDEzmC4-JCY0GAG8CittQRhrcyUU0,9697
+commkit/analysis/allan.py,sha256=YvJ_LdvAFIAB9N2qjqlNTXIXYHBx6b43BLDHBHbIq14,4108
+commkit/analysis/drift.py,sha256=rN2rmTJg21bAEYl2niLfgYQi30bjdAEpoK_ss2R9YHo,8313
+commkit/analysis/interferometry.py,sha256=esdxvznJiXYuierAkbjG0iHX5qeNc_Y8CqMScMpvd3w,39607
+commkit/analysis/linewidth.py,sha256=p6cmaHgRv-UwHBQglsQtvYxErQyNDpTm32Xi4Ey87R8,20173
+commkit/analysis/trajectory.py,sha256=Jel_TUqt_1fXzITtqYDfryeRPM-oxRagxadxGvztVH8,3806
+commkit/coding/__init__.py,sha256=_C3jhsmr5d3qHFokzY3gbUGKVV0GrUAWeba3Z2kqz9Q,1085
+commkit/coding/base.py,sha256=sSwlyYB7n2Vf9_9mUiEy8BsuWjfmTbLSY8nRyRIjOAQ,753
+commkit/coding/bch.py,sha256=YY3b0reQndVCpsPZ4NHAwinNfTdzkZ01KVYu5E_UKws,154
+commkit/coding/convolutional.py,sha256=IVZmOfvSRxq4UT-eTbbyn4zou7fTiD2RZMLx4ZHcQC4,239
+commkit/coding/crc.py,sha256=cVSI0YhU4jZj7h9ysM6Neqs0oOr0xjTK-mGJSsE_DaU,208
+commkit/coding/galois.py,sha256=WhjS11z0VUnNSd29d_uL3JD6kOiEMg6wTrkoo7iQ2f0,301
+commkit/coding/hamming.py,sha256=GI7QwYV05jpGPMv3-gApqx6hWhC5DL18MI9rzymhUBg,153
+commkit/coding/interleaving.py,sha256=VH220faQB4GRIM89zDdT4de9pkoI3KL7bHvkLpNUwmc,224
+commkit/coding/ldpc.py,sha256=1Sp_Q3MxAlqcdW7RyuredBzpLszLA9RTySd1AHdCVGQ,313
+commkit/coding/polar.py,sha256=rCDqC6NYah3-Pz0hLaz11RJnmI0XCXFWcMHVxlM7nbI,293
+commkit/coding/ratematch.py,sha256=i7dstHwKOlmoZsqCYigMmECn9Jnxb8zh2-tqb4vIYBo,159
+commkit/coding/reed_solomon.py,sha256=U2IU1WfNuGhYCYAU94oWv-QwDGVBvvpzOxRw9R0-qX8,153
+commkit/coding/turbo.py,sha256=p6W0BGdsW-sBCi7SXt2THyKEs4vkVuWDWkVzM5sTRqM,275
+commkit/core/__init__.py,sha256=VsaPj73qIQo0ucr1Ftzp_kMLsGoUa2SeFEWC54wM8IY,871
+commkit/core/frame.py,sha256=cAvvWAMG15AMfqbwTICv5319nTFysxAZq4685Wu1p0A,37861
+commkit/core/generation.py,sha256=Y4xnJ0u-ZSfo-xkytCsWG9podHpdHg9xssb272HzaIk,18883
+commkit/core/signal.py,sha256=ESQn0KknVUJPtEx-TVpkNfyvWCfQXwNe_2Rn_BVeaO0,28059
+commkit/equalization/__init__.py,sha256=P3x5dek0AFk1QzM7siIPwMfuf8Nj4tYz_Un65aaOeYY,1640
+commkit/equalization/_block.py,sha256=lBcnuijIunrw4u_V8vjvAE8m3cKlJzAVttseSVNx05o,81322
+commkit/equalization/_common.py,sha256=3pagobuXFAZiaSYH9HyEz3yjLh1WPursbr4dbCKisys,22717
+commkit/equalization/_kernels_jax.py,sha256=g8bx5l6Q5pqI9_LVHjy3L-z5Ht15ev198hP1Rve7XJQ,70885
+commkit/equalization/_kernels_numba.py,sha256=4nw4l1e1KrvemI5V4tZN_ZVcA7tWa7xAR-G6wzrLYkw,75198
+commkit/equalization/blind.py,sha256=b_EzCne4RBws8K07KzXN0MWwmIRBhlGJmSn4mgmJfFU,8296
+commkit/equalization/linear.py,sha256=dgheW19-s7LqBP-lZb6zM-xf5YTfgH9FF7axLm574sA,14671
+commkit/equalization/polarization.py,sha256=Ti44l3RRvdde6q38uxTAFZatzjX0mnK3uw1ZRqd5OWc,36513
+commkit/equalization/result.py,sha256=SdmHSmLUDGpPaTiGctJpLxXCxQOfJFTuijtcQOpw2TA,8142
+commkit/equalization/sequential.py,sha256=_8zM7yMDfek7AlNEmpyF9bMDupu1psUvTjEFYIPmTlA,120190
+commkit/impairments/__init__.py,sha256=_GsY_M3flYVRHDq0FP9n2F-_RSTXQg9mSBxtW7w4Ugg,1437
+commkit/impairments/frontend.py,sha256=YKTRnwPi9YBTgU4x0hmFi_1ik0GPjjTgpeXRlcKw4i0,6850
+commkit/impairments/noise.py,sha256=OgvyA6DD9qS7JnqMCemL0DRfZgT8YOO6d6fYPEJPq7k,3722
+commkit/impairments/source.py,sha256=9nqZqYhvE8LbQVQTRbnUfX_oN2pRY6W-CUnzVztFabM,7298
+commkit/impairments/channel/__init__.py,sha256=GzEAZu6PxYlYqlYh8SPTjiY7fN9F6piiLmdAmnr3hO0,471
+commkit/impairments/channel/linear.py,sha256=P9e9gmYg9b_LIOsLVpm9mQ0sOpom1sEh8K35lztK9wc,9947
+commkit/impairments/channel/nonlinear.py,sha256=0LhoqErFEdZ-xQznC4wyqoW8t_JhmDyOJqCNimPzo80,456
+commkit/mapping/__init__.py,sha256=MB6DGYDBG4tO0hLXl3PRmJ4pJ0g1J1kpJC5hyCue1dc,1511
+commkit/mapping/bits.py,sha256=hFksHu6_evXZTf4ZppsKtBlc7wrE_vvIlRxUfTgPSR0,8599
+commkit/mapping/constellation.py,sha256=B-Aur0_eZqeXhAV9qsR23fWgOkzYGYYGs_TbsWFnnOQ,4975
+commkit/mapping/gray.py,sha256=t3bPUDyOn3VIDYwjqqo-uOXl777oqq06CnGF-1B45So,11439
+commkit/mapping/llr.py,sha256=stT9sHW4J8iOQelqqLno9Y14mzgP_FCwujOuRDxUXzM,9024
+commkit/mapping/shaping.py,sha256=qxPq8j6zk5Cu9knBluFMc_9k1J84-_5OW96dAz_NEV8,6939
+commkit/plotting/__init__.py,sha256=A9QdogNOglW6Gqz6FuMIgnV2Jzc0tNvj43gBfPBt_4Y,2512
+commkit/plotting/analysis.py,sha256=eYosIuRH3KKiFEDDqgOeFgjINNXbQNeL6A72obVB2kU,19256
+commkit/plotting/constellation.py,sha256=faCRkYUYYaoLntVwtJuU8849Q7WFrkDv2zp4Ion4stI,15219
+commkit/plotting/equalizer.py,sha256=jUyY5yywWD132xWRLpzoq6gFsUSihVSgxA6zaerM4_Y,12517
+commkit/plotting/eye.py,sha256=_nFmtT5_Gwz0B1Gwgg556TjfGQXdDcZcIUQ6UO9ijfg,11784
+commkit/plotting/spectral.py,sha256=E3QvZG-t2ohGoU9QkZJvk1uI4BHiFml_ZVv7Eqge3ig,18133
+commkit/plotting/sync.py,sha256=7txbQYmqjJD6D9WOmqHSe4e2pvWrFXwz0vlaP4Ic9l0,31235
+commkit/plotting/theme.py,sha256=N2QmSnVMg4L427kjKdXHO9HDnJKM752scBNeCXHBytg,6832
+commkit/plotting/waveform.py,sha256=bzGxp1_uBo6DfpxK1Bo8YnCXZ8p2Mob2yj7zxQGnU4c,5503
+commkit/recovery/__init__.py,sha256=mtEqN3oKm1E6vy_qrICSF1Y55oAaxDZVW0RTlGZg1yQ,1659
+commkit/recovery/bps.py,sha256=d5d2vkEg0_AX-eak06ZHUTEaXsxCLQlxHZXnw_RbHnQ,14469
+commkit/recovery/corrections.py,sha256=Km8tV7WrpbsNzxTcJYvOGNgmp38St4RIikzwgTOIirM,30180
+commkit/recovery/pilots.py,sha256=pIXXGK_ZUZitJ91yIYjwHqDGGN877_reqbaam2cn0pY,34460
+commkit/recovery/pll.py,sha256=NNrypJWQuJ-u96QKdAMBeohszu1hHuAOmpFciaLP03c,17882
+commkit/recovery/tikhonov.py,sha256=C2LakaYs3NmuzfBJQ6RwWnNIBPjvRAA1UboLee5bATU,16219
+commkit/recovery/viterbi_viterbi.py,sha256=SPy1mEbwueBSA9dSAcAIHWXBiasSBgrHnFfm3G-K5LU,9567
+commkit-1.0.0.dist-info/METADATA,sha256=V6qOUaUJs5VKFYGAZvfeYQLGpFwnVvW3Sr2Kw1WsA7E,6692
+commkit-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+commkit-1.0.0.dist-info/licenses/LICENSE,sha256=X9bm1DEtmmDugEV7ulyQzdX-fZcZ711lPAwtdDiU2yg,1059
+commkit-1.0.0.dist-info/RECORD,,

commkit-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

commkit-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lokgar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction acting including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom it is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.