qsp-modulation

Modulation/demodulation layer for the RQM Technologies 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 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 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

# 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:

pip install -e ../qsp-core

Quick start

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

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

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 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

pytest tests/

Running examples

python examples/digital_demo.py
python examples/iq_demo.py

Documentation

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

License

See LICENSE.