Metadata-Version: 2.4
Name: qsp-modulation
Version: 0.1.0
Summary: Modulation/demodulation layer for the RQM Technologies QSP ecosystem
License: MIT License
        
        Copyright (c) 2026 RQM Technologies
        
        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, 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 the Software 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.
        
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qsp-core>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

<img src="https://github.com/RQM-Technologies-dev/qsp-modulation/actions/workflows/ci.yml/badge.svg">

# qsp-modulation

Modulation/demodulation layer for the [RQM Technologies](https://github.com/RQM-Technologies-dev)
quaternion signal-processing (QSP) ecosystem.

## Role in the QSP Ecosystem

`qsp-modulation` is the **Layer-1 modulation primitives library** of the RQM Technologies
QSP platform.  It sits directly on top of
[`qsp-core`](https://github.com/RQM-Technologies-dev/qsp-core) and provides reusable,
composable building blocks for digital communications work:

- **BPSK and QPSK** modulation and hard-decision demodulation helpers
- **IQ representation** helpers (`IQ` named tuple, `to_iq`, `from_iq`, magnitude, phase)
- **Bit grouping and flattening** utilities (`group_bits`, `flatten_bits`)
- **Constellation-oriented symbol mapping** (`bits_to_symbols`, `symbols_to_bits`)
- **Lightweight modulation utilities** — power normalisation, dB conversion

`qsp-modulation` is intentionally a *building-block library*, not a full communications
framework.  Higher-level concerns (channel simulation, FEC, synchronisation, full modem
stacks) belong in downstream repositories such as `quaternionic-modem`.

```
┌──────────────────────────────────────────────────────────┐
│              RQM Technologies QSP Platform                │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │  Downstream / Application Layer                    │  │
│  │  quaternionic-modem · communication prototypes     │  │
│  └──────────────────┬─────────────────────────────────┘  │
│                     │ uses                                │
│  ┌──────────────────▼─────────────────────────────────┐  │
│  │  qsp-modulation              ◄── THIS REPO          │  │
│  │  BPSK/QPSK · IQ helpers · bit/symbol mapping       │  │
│  └──────────────────┬─────────────────────────────────┘  │
│                     │ built on                            │
│  ┌──────────────────▼─────────────────────────────────┐  │
│  │  qsp-core                                           │  │
│  │  Quaternion arithmetic · SU(2) · base utilities     │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                          │
│  Peer ecosystem packages:                                │
│  qsp-fft · qsp-filter · qsp-orientation                 │
└──────────────────────────────────────────────────────────┘
```

## Why This Repo Matters

Digital communications prototyping, waveform construction, and IQ processing
require a stable, well-defined set of low-level primitives.  `qsp-modulation`
provides those primitives so that:

- **Digital communications prototypes** can use correct BPSK/QPSK helpers
  without reimplementing them in every project.
- **Waveform construction pipelines** have a reliable IQ representation layer
  that interoperates with `qsp-fft` and `qsp-filter`.
- **Bit/symbol experiments** have explicit, testable mappings and grouping
  utilities.
- **IQ processing pipelines** can rely on a thin, dependency-free abstraction
  over Python's native `complex` type.
- **Communications education and demos** get a readable, well-documented
  reference implementation.
- **Future modem and receiver stacks** (`quaternionic-modem`, etc.) have a
  stable foundation to build on without absorbing modulation primitives
  themselves.

## QSP Perspective

Within the QSP ecosystem, modulation is not just the assignment of bits to
symbols.  It is the structured representation of information in phase,
amplitude, and coordinate relationships that downstream systems can
manipulate, analyse, and recover.  `qsp-modulation` provides the small,
reusable primitives needed to construct higher-level communication systems
without embedding full application logic at the library layer.

## Boundary

### What belongs in `qsp-modulation`

| Category | Examples |
|---|---|
| Digital modulation primitives | BPSK/QPSK modulate, demodulate |
| IQ conversion helpers | `to_iq`, `from_iq`, `iq_magnitude`, `iq_phase` |
| Bit and symbol mapping | `group_bits`, `flatten_bits`, `bits_to_symbols`, `symbols_to_bits` |
| Lightweight modulation utilities | `normalise_power`, `db_to_linear`, `linear_to_db` |
| Reusable constellation logic | Gray-coded QPSK map |
| Modulation-oriented demos and examples | scripts in `examples/` |
| Tests for the above | `tests/` |

### What does NOT belong here

| Out-of-scope concern | Belongs in |
|---|---|
| `Quaternion` class and arithmetic | `qsp-core` |
| SU(2) / rotation / spinor primitives | `qsp-core` |
| FFT and spectral analysis | `qsp-fft` |
| General filtering pipelines | `qsp-filter` |
| Channel simulation frameworks | downstream (e.g. `quaternionic-modem`) |
| FEC / coding stacks | downstream |
| Synchronisation loops and equalizers | downstream |
| Full transmitter / receiver systems | downstream |
| SDR / hardware integrations | downstream |
| Product-specific communications logic | downstream |

## Constellation and IQ Conventions

These conventions are stable.  Downstream code may rely on them.

| Convention | Detail |
|---|---|
| BPSK mapping | `0 → +1+0j`, `1 → −1+0j` |
| BPSK decision | Hard decision on `Re(s)`: ≥ 0 → bit 0, < 0 → bit 1 |
| QPSK coding | Gray-coded; constellation points at ±45° / ±135° on the unit circle |
| QPSK mapping | `00 → (+1+j)/√2`, `01 → (−1+j)/√2`, `11 → (−1−j)/√2`, `10 → (+1−j)/√2` |
| QPSK decision | Hard decision by quadrant (sign of real and imaginary parts) |
| IQ representation | `IQ(i, q)` named tuple; `i = Re(z)`, `q = Im(z)` |
| Power normalisation | `normalise_power` scales to unit average power by default |

## Relationship to qsp-core

`qsp-core` is the foundational layer of the QSP platform.  It owns:

- The `Quaternion` class and its arithmetic
- SU(2) / spinor rotation primitives
- Low-level numeric helpers shared across all QSP packages

`qsp-modulation` is built *on top of* that foundation and provides
modulation-specific helpers.  Current modulation logic uses only Python's
standard `cmath`/`math` libraries and does not yet require deep quaternion
imports.  This is acceptable — the architectural dependency still holds, and
any future feature that needs quaternion-level primitives should import them
from `qsp-core` rather than re-implementing them here.

See [`docs/dependency-on-qsp-core.md`](docs/dependency-on-qsp-core.md) for
full guidance.

## Downstream Systems

`qsp-modulation` is designed to be consumed by higher-level Layer-2
repositories and application systems:

- **`quaternionic-modem`** — a full modem prototype built on `qsp-modulation`
  primitives
- **Communication system prototypes** — research or demo pipelines that need
  BPSK/QPSK modulation without a full stack
- **Signal-generation demos** — waveform construction scripts combining
  `qsp-modulation` with `qsp-fft` and `qsp-filter`
- **Receiver experimentation pipelines** — systems using the IQ and symbol
  mapping helpers for algorithm prototyping
- **Orientation-aware communication systems** — future combinations of
  `qsp-modulation` and `qsp-orientation` for spatially encoded signals

This layered design keeps application logic out of the primitives library,
making each layer independently testable and reusable.

## Package structure

```
qsp_modulation/
├── __init__.py    — public API
├── digital.py     — bpsk_modulate, bpsk_demodulate, qpsk_modulate, qpsk_demodulate
├── iq.py          — IQ, to_iq, from_iq, iq_magnitude, iq_phase
├── symbols.py     — group_bits, flatten_bits, bits_to_symbols, symbols_to_bits
└── utils.py       — db_to_linear, linear_to_db, normalise_power
```

## Installation

```bash
# From the repo root (development install)
pip install -e ".[dev]"
```

> **Note:** `qsp-core` must be available.  For local development in the RQM
> monorepo, install it first:
>
> ```bash
> pip install -e ../qsp-core
> ```

## Quick start

```python
from qsp_modulation import bpsk_modulate, bpsk_demodulate

bits = [0, 1, 0, 0, 1, 1]
symbols = bpsk_modulate(bits)   # [(1+0j), (-1+0j), (1+0j), ...]
recovered = bpsk_demodulate(symbols)
assert recovered == bits
```

```python
from qsp_modulation import qpsk_modulate, qpsk_demodulate

bits = [0, 0, 0, 1, 1, 0, 1, 1]
symbols = qpsk_modulate(bits)
assert qpsk_demodulate(symbols) == bits
```

```python
from qsp_modulation import to_iq, iq_magnitude, iq_phase
import math

iq = to_iq(3.0 + 4.0j)
print(iq.i, iq.q)               # 3.0  4.0
print(iq_magnitude(iq))         # 5.0
print(math.degrees(iq_phase(iq)))  # 53.13...
```

## Future Extensions

See [`docs/repo-roadmap.md`](docs/repo-roadmap.md) for a full discussion.
Appropriate future additions to this repository include:

- Additional constellations (8-PSK, basic QAM helpers)
- Constellation visualisation helpers
- Soft-decision demodulation utilities
- Symbol-error-rate measurement helpers
- Reusable channel-noise demo utilities
- Improved power-analysis and normalisation helpers

Items that should **not** be added here (they belong in downstream repos):

- Full channel models or propagation simulations
- Synchronisation / carrier-tracking loops
- Adaptive equalisation
- FEC / channel-coding stacks
- RF front-end or SDR integration
- End-to-end modem applications

## Running tests

```bash
pytest tests/
```

## Running examples

```bash
python examples/digital_demo.py
python examples/iq_demo.py
```

## Documentation

- [`docs/architecture.md`](docs/architecture.md) — package layout, design principles, and ecosystem role
- [`docs/api-overview.md`](docs/api-overview.md) — public API reference grouped by category
- [`docs/dependency-on-qsp-core.md`](docs/dependency-on-qsp-core.md) — relationship with `qsp-core`
- [`docs/downstream-usage.md`](docs/downstream-usage.md) — guidance for downstream consumers
- [`docs/repo-roadmap.md`](docs/repo-roadmap.md) — appropriate future extensions

## License

See [LICENSE](LICENSE).
