softlora 0.3.0__py3-none-any.whl

softlora/__init__.py

@@ -0,0 +1,22 @@
+from softlora.chase import chase_decode
+from softlora.decoder import DecoderSettings, LoRaDecoder
+from softlora.io import (
+    iter_iq_chunks, load_iq, save_packets, sample_rate,
+)
+from softlora.packet import Packet, estimate_snr
+from softlora.utils import demodulate_spectra_from
+
+__version__ = '0.3.0'
+
+__all__ = [
+    'LoRaDecoder',
+    'DecoderSettings',
+    'Packet',
+    'load_iq',
+    'iter_iq_chunks',
+    'save_packets',
+    'sample_rate',
+    'estimate_snr',
+    'chase_decode',
+    'demodulate_spectra_from',
+]

softlora/chase.py

@@ -0,0 +1,338 @@
+"""Chase (soft-decision) decoding for LoRa payload symbols.
+
+Port of the Chase decoder used by the real-signal multi-receiver decoder
+(``lorab_receiver``): given the per-symbol FFT power spectra of the payload,
+a hard decision is taken and the least-reliable symbols/bits are probed with
+alternative candidates until ``decode_fn`` accepts one.
+
+Two stages are tried, in order:
+
+* **Symbol-level Chase** -- each symbol's spectrum is reduced to its top-K
+  bins; the ratio of the top bin to the second bin is the reliability.
+  The max-likelihood (argmax) symbol vector is tried first; if it fails,
+  single, pair and triple symbol flips among the least-reliable positions are
+  tried, ranked by their ``-log(power ratio)`` cost.
+* **Bit-level Chase** -- symbol spectra are converted to per-bit LLRs;
+  the least-reliable bits are flipped one at a time, then in pairs, and
+  each candidate is re-decoded.
+
+``decode_fn`` is the injected success predicate (e.g. full payload decode
+with a valid CRC-16), so this module is agnostic to the exact coding scheme.
+"""
+
+import math
+import itertools
+from typing import Callable, Dict, List, Optional, Tuple
+
+import numpy as np
+
+DecoderFn = Callable[[np.ndarray], bool]
+
+
+def spectra_to_probs(spectra: np.ndarray) -> np.ndarray:
+    """Normalize per-symbol power spectra into probability vectors.
+
+    Rows with zero total power carry no information and become uniform.
+
+    Parameters
+    ----------
+    spectra : ndarray
+        (num_syms, N_bins) non-negative FFT power spectra.
+
+    Returns
+    -------
+    ndarray
+        (num_syms, N_bins) rows normalized to sum to 1.
+    """
+    probs = np.asarray(spectra, dtype=np.float64).copy()
+    row_sums = probs.sum(axis=1)
+    zero_rows = row_sums <= 0
+    probs[zero_rows] = 1.0
+    row_sums = probs.sum(axis=1)
+    probs /= row_sums[:, None]
+    return probs
+
+
+def _top_k_bins(probs: np.ndarray, K: int):
+    """Return (top_bins, top_power) each of shape (num_syms, K)."""
+    num_syms = probs.shape[0]
+    top_bins = np.zeros((num_syms, K), dtype=int)
+    top_power = np.zeros((num_syms, K))
+    for m in range(num_syms):
+        idx_sorted = np.argsort(probs[m])[::-1]
+        top_bins[m] = idx_sorted[:K]
+        top_power[m] = probs[m, idx_sorted[:K]]
+    return top_bins, top_power
+
+
+def _reliability(top_power: np.ndarray) -> np.ndarray:
+    """Reliability = top1 / top2 power ratio per symbol (inf if top2 ~ 0)."""
+    second = top_power[:, 1]
+    return np.where(second > 0, top_power[:, 0] / (second + 1e-300), np.inf)
+
+
+def _spectra_to_bit_llrs(probs: np.ndarray, sf: int, offset: int) -> np.ndarray:
+    """Convert symbol spectra to per-bit LLRs (MSB-first).
+
+    For each symbol the spectrum is rolled by ``-offset`` into the common
+    reference frame, then each bit's LLR is ``log(P(bit=0) / P(bit=1))``
+    computed by summing probabilities over bins with that bit set.
+    """
+    num_syms = probs.shape[0]
+    de2bi = ((np.arange(2 ** sf)[:, None] >> np.arange(sf - 1, -1, -1)) & 1)
+    bit_llr = np.zeros((num_syms, sf))
+    for m in range(num_syms):
+        prob_shifted = np.roll(probs[m], -offset)
+        prob_shifted = np.maximum(prob_shifted, 1e-12)
+        for b in range(sf):
+            mask0 = de2bi[:, b] == 0
+            mask1 = de2bi[:, b] == 1
+            p0 = float(np.sum(prob_shifted[mask0]))
+            p1 = float(np.sum(prob_shifted[mask1]))
+            bit_llr[m, b] = math.log(p0 / (p1 + 1e-300))
+    return bit_llr
+
+
+def _bit_llrs_to_symbols(bit_llr: np.ndarray, sf: int) -> np.ndarray:
+    """Convert an (num_syms, sf) LLR array to symbol indices (MSB-first)."""
+    hard_bits = (bit_llr < 0).astype(int)
+    weights = (1 << np.arange(sf - 1, -1, -1))
+    return hard_bits @ weights
+
+
+def _chase_symbol_candidates(
+    probs: np.ndarray,
+    top_bins: np.ndarray,
+    top_power: np.ndarray,
+    reliability: np.ndarray,
+    hard_syms: np.ndarray,
+    offset: int,
+    N_bins: int,
+    K: int,
+    reliability_thresh: float,
+    max_flip_pos: int,
+    max_attempts: int,
+):
+    """Yield (candidate_symbols, label) for symbol-level Chase, in cost order.
+
+    The max-likelihood (argmax) vector is emitted first, followed by single,
+    pair and triple flips among the least-reliable positions ranked by
+    flipping cost.
+    """
+    num_syms = probs.shape[0]
+    yield hard_syms.copy(), "hard"
+
+    rel_order = np.argsort(reliability)
+    flip_pos = rel_order[reliability[rel_order] < reliability_thresh]
+    flip_pos = flip_pos[:max_flip_pos]
+    nf = len(flip_pos)
+
+    if nf == 0:
+        return
+
+    def is_valid(p: int, r: int) -> bool:
+        return top_power[p, r] >= top_power[p, 0] * 0.03
+
+    def rank_cost(p: int, r: int) -> float:
+        return -math.log(top_power[p, r] / (top_power[p, 0] + 1e-300))
+
+    singles: List[Tuple] = []
+    for p in flip_pos:
+        for r in range(1, K):
+            if not is_valid(p, r):
+                continue
+            singles.append((p, r, rank_cost(p, r)))
+    singles.sort(key=lambda x: x[2])
+
+    pairs: List[Tuple] = []
+    for p1, p2 in itertools.combinations(flip_pos, 2):
+        for r1 in range(1, K):
+            if not is_valid(p1, r1):
+                continue
+            c1 = rank_cost(p1, r1)
+            for r2 in range(1, K):
+                if not is_valid(p2, r2):
+                    continue
+                c2 = rank_cost(p2, r2)
+                pairs.append((p1, r1, p2, r2, c1 + c2))
+    pairs.sort(key=lambda x: x[4])
+
+    nf3 = min(nf, 4)
+    triples: List[Tuple] = []
+    for p1, p2, p3 in itertools.combinations(flip_pos[:nf3], 3):
+        for r1 in range(1, K):
+            if not is_valid(p1, r1):
+                continue
+            c1 = rank_cost(p1, r1)
+            for r2 in range(1, K):
+                if not is_valid(p2, r2):
+                    continue
+                c2 = rank_cost(p2, r2)
+                for r3 in range(1, K):
+                    if not is_valid(p3, r3):
+                        continue
+                    c3 = rank_cost(p3, r3)
+                    triples.append((p1, r1, p2, r2, p3, r3, c1 + c2 + c3))
+    triples.sort(key=lambda x: x[6])
+
+    ranked: List[Tuple[str, tuple]] = []
+    for s in singles:
+        ranked.append(('single', s))
+    for p in pairs:
+        ranked.append(('pair', p))
+    for t in triples:
+        ranked.append(('triple', t))
+    ranked.sort(key=lambda x: x[1][-1])
+
+    for tag, row in ranked[:max_attempts]:
+        cand = hard_syms.copy()
+        if tag == 'single':
+            p, r, _ = row
+            cand[p] = (top_bins[p, r] - offset) % N_bins
+            label = f"1-flip pos={p} rank={r}"
+        elif tag == 'pair':
+            p1, r1, p2, r2, _ = row
+            cand[p1] = (top_bins[p1, r1] - offset) % N_bins
+            cand[p2] = (top_bins[p2, r2] - offset) % N_bins
+            label = f"2-flip pos=[{p1} {p2}] ranks=[{r1} {r2}]"
+        else:
+            p1, r1, p2, r2, p3, r3, _ = row
+            cand[p1] = (top_bins[p1, r1] - offset) % N_bins
+            cand[p2] = (top_bins[p2, r2] - offset) % N_bins
+            cand[p3] = (top_bins[p3, r3] - offset) % N_bins
+            label = f"3-flip pos=[{p1} {p2} {p3}]"
+        yield cand, label
+
+
+def _chase_bit_candidates(
+    probs: np.ndarray,
+    offset: int,
+    sf: int,
+    max_bit_flips: int,
+    max_pair_flips: int,
+):
+    """Yield (candidate_symbols, label) for bit-level Chase, in cost order.
+
+    The bit-reconstructed hard vector (symbols rebuilt from per-bit LLR
+    signs, which may differ from the per-symbol argmax) is emitted first,
+    followed by single-bit and bit-pair flips of the least-reliable bits.
+    """
+    bit_llr = _spectra_to_bit_llrs(probs, sf, offset)
+    hard_bits_vec = (bit_llr.ravel() < 0).astype(int)
+    llr_flat = np.abs(bit_llr).ravel()
+    bit_order = np.argsort(llr_flat)
+    n_flips = min(len(hard_bits_vec), max_bit_flips)
+    bit_weights = 1 << np.arange(sf - 1, -1, -1)
+
+    def bits_to_syms(bvec: np.ndarray) -> np.ndarray:
+        return bvec.reshape(-1, sf) @ bit_weights
+
+    yield bits_to_syms(hard_bits_vec), "hard-bits"
+
+    for fi in range(n_flips):
+        flipped = hard_bits_vec.copy()
+        flipped[bit_order[fi]] ^= 1
+        yield bits_to_syms(flipped), f"bit-flip {fi + 1}"
+
+    n_pair = min(max_pair_flips, n_flips)
+    for i in range(n_pair):
+        for j in range(i + 1, n_pair):
+            flipped = hard_bits_vec.copy()
+            flipped[bit_order[i]] ^= 1
+            flipped[bit_order[j]] ^= 1
+            yield bits_to_syms(flipped), f"2-bit-flip {i},{j}"
+
+
+def chase_decode(
+    spectra: np.ndarray,
+    decode_fn: DecoderFn,
+    *,
+    sf: int,
+    offset: int = 0,
+    K: int = 5,
+    reliability_thresh: float = 15.0,
+    max_flip_pos: int = 6,
+    max_attempts: int = 120,
+    max_bit_flips: int = 40,
+    max_pair_flips: int = 15,
+    enable_bit_chase: bool = True,
+) -> Tuple[bool, Optional[np.ndarray], Dict[str, object]]:
+    """Chase-decode payload symbols from their FFT power spectra.
+
+    Parameters
+    ----------
+    spectra : ndarray
+        (num_syms, N_bins) per-symbol FFT power spectra.  The hard symbol
+        value for symbol *m* is taken as ``argmax(spectra[m]) - offset``.
+    decode_fn : callable
+        ``decode_fn(symbols) -> bool`` returning True when a candidate symbol
+        vector decodes correctly (e.g. CRC-16 valid).  The first accepted
+        candidate is returned.
+    sf : int
+        Spreading factor (needed for the bit-level stage).
+    offset : int
+        Bin offset applied when converting spectra to symbol values.
+        ``0`` in the standard receiver reference frame.
+    K : int
+        Number of top bins considered per symbol.
+    reliability_thresh : float
+        Symbols with reliability below this value are treated as ambiguous
+        flip positions.
+    max_flip_pos : int
+        Maximum number of least-reliable symbol positions to flip.
+    max_attempts : int
+        Maximum symbol-level candidates tried.
+    max_bit_flips : int
+        Maximum number of single-bit flips tried in the bit-level stage.
+    max_pair_flips : int
+        Maximum number of bit-pair flips tried in the bit-level stage.
+    enable_bit_chase : bool
+        Set False to skip the bit-level stage.
+
+    Returns
+    -------
+    ok : bool
+        True if a candidate decoded successfully.
+    symbols : ndarray or None
+        The accepted symbol vector (``None`` if not ok).
+    info : dict
+        Debug info: attempts, labels tried, and which stage succeeded.
+    """
+    num_syms, N_bins = spectra.shape
+    probs = spectra_to_probs(spectra)
+
+    info: Dict[str, object] = {
+        'attempts': 0,
+        'labels': [],
+        'stage': None,
+        'num_syms': num_syms,
+    }
+
+    def try_candidate(cand: np.ndarray, label: str) -> bool:
+        info['attempts'] = int(info['attempts']) + 1
+        info['labels'].append(label)
+        return bool(decode_fn(cand))
+
+    top_bins, top_power = _top_k_bins(probs, K)
+    reliability = _reliability(top_power)
+    hard_syms = (top_bins[:, 0] - offset) % N_bins
+
+    for cand, label in _chase_symbol_candidates(
+        probs, top_bins, top_power, reliability, hard_syms, offset, N_bins,
+        K, reliability_thresh, max_flip_pos, max_attempts,
+    ):
+        if try_candidate(cand, label):
+            info['stage'] = 'symbol'
+            return True, cand, info
+
+    if enable_bit_chase:
+        for cand, label in _chase_bit_candidates(
+            probs, offset, sf,
+            max_bit_flips, max_pair_flips,
+        ):
+            if try_candidate(cand, label):
+                info['stage'] = 'bit'
+                return True, cand, info
+
+    info['stage'] = 'none'
+    return False, None, info

softlora/chirp.py

@@ -0,0 +1,22 @@
+import numpy as np
+
+
+def generate_chirps(N):
+    """Generate the N-sample baseband reference upchirp and downchirp.
+
+    Parameters
+    ----------
+    N : int
+        Samples per symbol (2**sf).
+
+    Returns
+    -------
+    upchirp : ndarray
+        The LoRa upchirp (symbol 0 preamble chirp).
+    downchirp : ndarray
+        The complex conjugate (downchirp), used to dechirp received windows.
+    """
+    n = np.arange(N, dtype=float)
+    upchirp = np.exp(1j * 2 * np.pi * (n**2 / (2 * N) - n / 2))
+    downchirp = np.exp(-1j * 2 * np.pi * (n**2 / (2 * N) - n / 2))
+    return upchirp, downchirp