wsprpool 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
wsprpool/_sim.py ADDED
@@ -0,0 +1,105 @@
1
+ """Synthetic WSPR slots heard by several receivers, for measuring the combining gain."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+
7
+ import numpy as np
8
+
9
+ from ._decode import LEAD, decode_slot
10
+ from ._demod import FS, SPS, TONE_OFFSETS, WINDOW
11
+ from ._wspr import Message, symbols
12
+
13
+
14
+ @dataclass
15
+ class Channel:
16
+ snr_db: float
17
+ freq_error: float = 0.0
18
+ time_error: float = 0.0
19
+ doppler: float = 0.0
20
+
21
+
22
+ def waveform(msg: Message, freq: float, drift: float = 0.0) -> np.ndarray:
23
+ """Continuous-phase 4-FSK at 375 Hz baseband with unit amplitude.
24
+
25
+ drift moves the frequency linearly by that many Hz from the first symbol to the last.
26
+ """
27
+ tones = symbols(msg)
28
+ k = np.arange(len(tones) * SPS) - len(tones) * SPS / 2
29
+ inst = np.repeat(freq + TONE_OFFSETS[tones], SPS) + drift * k / (len(tones) * SPS)
30
+ return np.exp(2j * np.pi * np.cumsum(inst) / FS)
31
+
32
+
33
+ def fading(n: int, doppler: float, rng: np.random.Generator) -> np.ndarray:
34
+ """Rayleigh fading gain with unit mean power and a Gaussian Doppler spectrum.
35
+
36
+ doppler is the two-sigma spread, as in the Watterson HF channel model (ITU-R F.1487).
37
+ """
38
+ if doppler <= 0:
39
+ return np.ones(n, complex)
40
+ shape = np.sqrt(np.exp(-np.fft.fftfreq(n, 1 / FS) ** 2 / (2 * (doppler / 2) ** 2)))
41
+ white = (rng.normal(size=n) + 1j * rng.normal(size=n)) / np.sqrt(2)
42
+ return np.fft.ifft(np.fft.fft(white) * shape) / np.sqrt(np.mean(shape**2))
43
+
44
+
45
+ def slot(
46
+ msg: Message,
47
+ freq: float,
48
+ channels: list[Channel],
49
+ start: float = 1.0,
50
+ rng: np.random.Generator | None = None,
51
+ noise: bool = True,
52
+ drift: float = 0.0,
53
+ ) -> list[np.ndarray]:
54
+ """One decode window per receiver: noise of unit variance per sample plus the signal.
55
+
56
+ snr_db uses the WSPR convention (signal power over noise in 2500 Hz). Pass
57
+ noise=False to get the signal alone, for adding more stations to a slot.
58
+ """
59
+ rng = rng or np.random.default_rng()
60
+ out = []
61
+ for ch in channels:
62
+ sig = waveform(msg, freq + ch.freq_error, drift)
63
+ amp = np.sqrt(10 ** (ch.snr_db / 10) * 2500 / FS)
64
+ sig = amp * sig * fading(len(sig), ch.doppler, rng)
65
+ x = np.zeros(WINDOW, complex)
66
+ if noise:
67
+ x += (rng.normal(size=WINDOW) + 1j * rng.normal(size=WINDOW)) / np.sqrt(2)
68
+ i = int(round((LEAD + start + ch.time_error) * FS))
69
+ x[i : i + len(sig)] += sig[: WINDOW - i]
70
+ out.append(x)
71
+ return out
72
+
73
+
74
+ def random_message(rng: np.random.Generator) -> Message:
75
+ def pick(chars: str, n: int = 1) -> str:
76
+ return "".join(chars[int(i)] for i in rng.integers(len(chars), size=n))
77
+
78
+ letters, digits = "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "0123456789"
79
+ call = pick(letters, 2) + pick(digits) + pick(letters, int(rng.integers(1, 4)))
80
+ grid = pick(letters[:18], 2) + pick(digits, 2)
81
+ return Message(call, grid, int(rng.choice([23, 30, 33, 37])))
82
+
83
+
84
+ def decode_rate(
85
+ n: int, snr_db: float, trials: int, doppler: float, rng: np.random.Generator
86
+ ) -> float:
87
+ """Fraction of slots where the transmitted message is decoded by n combined receivers."""
88
+ hits = 0
89
+ for _ in range(trials):
90
+ msg = random_message(rng)
91
+ chans = [
92
+ Channel(snr_db, rng.normal(0, 0.03), rng.normal(0, 0.01), doppler) for _ in range(n)
93
+ ]
94
+ xs = slot(msg, rng.uniform(-90, 90), chans, rng=rng)
95
+ spots = decode_slot({str(i): x for i, x in enumerate(xs)}, alone=False, passes=1).combined
96
+ hits += any(s.message == msg for s in spots)
97
+ return hits / trials
98
+
99
+
100
+ def threshold(snrs: list[float], rates: list[float], level: float = 0.5) -> float | None:
101
+ """SNR where the decode rate crosses `level`, by linear interpolation."""
102
+ for (s0, r0), (s1, r1) in zip(zip(snrs, rates), zip(snrs[1:], rates[1:])):
103
+ if (r0 - level) * (r1 - level) <= 0 and r0 != r1:
104
+ return s0 + (level - r0) * (s1 - s0) / (r1 - r0)
105
+ return None
wsprpool/_spots.py ADDED
@@ -0,0 +1,75 @@
1
+ """Ground truth from the public wspr.live spot database."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import re
7
+ import urllib.parse
8
+ import urllib.request
9
+ from datetime import datetime, timezone
10
+
11
+ from ._wspr import Message, callhash
12
+
13
+ URL = "https://db1.wspr.live/"
14
+ CALL = re.compile(r"[A-Z0-9/]{3,10}")
15
+ GRID6 = re.compile(r"[A-R]{2}[0-9]{2}[A-X]{2}")
16
+
17
+ # (call, locator in upper case, power, reporter)
18
+ Row = tuple[str, str, int, str]
19
+
20
+
21
+ def band(freq_hz: float) -> int:
22
+ """wspr.live's band number: the integer MHz for every HF band."""
23
+ return int(freq_hz // 1_000_000)
24
+
25
+
26
+ def fetch(slots: list[float], messages: list[Message], freq_hz: float,
27
+ timeout: float = 30.0) -> dict[float, list[Row]]:
28
+ """Every wspr.live report on this band, per slot start, that could match a message.
29
+
30
+ That is every report of a call we decoded, plus every report from a 6-character
31
+ locator we decoded a type 3 message from, so a hash nobody else here heard can
32
+ still be put to a call.
33
+ """
34
+ calls = {m.call for m in messages if m.call and CALL.fullmatch(m.call)}
35
+ grids = {m.grid for m in messages if m.kind == 3 and GRID6.fullmatch(m.grid)}
36
+ if not slots or not (calls or grids):
37
+ return {}
38
+ times = ",".join(
39
+ "'" + datetime.fromtimestamp(t, timezone.utc).strftime("%Y-%m-%d %H:%M:%S") + "'"
40
+ for t in sorted(set(slots)))
41
+ conds = []
42
+ if calls:
43
+ conds.append("tx_sign IN (" + ",".join(f"'{c}'" for c in sorted(calls)) + ")")
44
+ if grids:
45
+ conds.append("upper(tx_loc) IN (" + ",".join(f"'{g}'" for g in sorted(grids)) + ")")
46
+ match = " OR ".join(conds)
47
+ sql = (f"SELECT toUnixTimestamp(time) AS t, tx_sign, tx_loc, power, rx_sign FROM wspr.rx "
48
+ f"WHERE band = {band(freq_hz)} AND time IN ({times}) AND ({match}) FORMAT JSON")
49
+ req = urllib.request.Request(URL + "?" + urllib.parse.urlencode({"query": sql}),
50
+ headers={"User-Agent": "wsprpool"})
51
+ with urllib.request.urlopen(req, timeout=timeout) as r:
52
+ data = json.load(r)["data"]
53
+ out: dict[float, list[Row]] = {}
54
+ for row in data:
55
+ out.setdefault(float(row["t"]), []).append(
56
+ (row["tx_sign"], row["tx_loc"].upper(), int(row["power"]), row["rx_sign"]))
57
+ return out
58
+
59
+
60
+ def confirm(msg: Message, rows: list[Row]) -> tuple[Message, set[str]]:
61
+ """The message, with a hashed call named by wspr.live, and who else reported it.
62
+
63
+ A report names a hash only when its call hashes to it from the same locator and power.
64
+ That also overrides a name picked in-session, where two calls can share a hash.
65
+ """
66
+ if msg.kind == 3:
67
+ for call, loc, power, _ in rows:
68
+ if loc == msg.grid and power == msg.power and callhash(call) == msg.callhash:
69
+ msg = Message(call, msg.grid, msg.power, msg.callhash)
70
+ break
71
+ if not msg.call:
72
+ return msg, set()
73
+ return msg, {rx for call, loc, power, rx in rows
74
+ if call == msg.call and power == msg.power
75
+ and (msg.kind == 2 or loc[:4] == msg.grid[:4])}
wsprpool/_version.py ADDED
@@ -0,0 +1,3 @@
1
+ from importlib.metadata import version
2
+
3
+ __version__ = version("wsprpool")
wsprpool/_wspr.py ADDED
@@ -0,0 +1,313 @@
1
+ """WSPR message packing, convolutional coding, interleaving and channel symbols."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+
7
+ import numpy as np
8
+
9
+ NSYM = 162
10
+ NBITS = 81
11
+ NDATA = 50
12
+ SYMBOL_RATE = 12000 / 8192
13
+ TONE_SPACING = SYMBOL_RATE
14
+ POLY1 = 0xF2D05351
15
+ POLY2 = 0xE4613C47
16
+
17
+ SYNC = np.array([
18
+ 1, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 1, 1, 0, 0, 0, 1, 0, 0, 1, 0, 1, 1, 1, 1, 0, 0, 0,
19
+ 0, 0, 0, 0, 1, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 0, 1,
20
+ 1, 0, 1, 0, 0, 0, 0, 1, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 0, 1, 0, 0, 1, 0, 1, 1, 0, 0, 0, 1,
21
+ 1, 0, 1, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 1, 0, 0, 1, 1, 1, 0, 1, 1, 0, 0, 1, 1,
22
+ 0, 1, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0, 0, 1, 0, 1, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0,
23
+ 1, 0, 1, 1, 0, 0, 0, 1, 1, 0, 0, 0,
24
+ ], dtype=np.int8)
25
+
26
+ VALID_POWERS = frozenset(p for p in range(61) if p % 10 in (0, 3, 7))
27
+ ALPHA = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ "
28
+ M32 = 0xFFFFFFFF
29
+
30
+
31
+ def _bitrev8(i: int) -> int:
32
+ return int(f"{i:08b}"[::-1], 2)
33
+
34
+
35
+ # coded bit p goes to channel position PERM[p]
36
+ PERM = np.array([j for j in (_bitrev8(i) for i in range(256)) if j < NSYM], dtype=np.int64)
37
+
38
+
39
+ @dataclass(frozen=True)
40
+ class Message:
41
+ """A WSPR message of any of the three types.
42
+
43
+ Type 1 is a plain call, a 4-character locator and power. Type 2 is a compound call
44
+ like PJ4/K1ABC or K1ABC/P with power and no locator. Type 3 carries a 15-bit hash
45
+ of the call, a 6-character locator and power: `call` stays empty until the hash is
46
+ matched to a call heard in another message, and `callhash` holds the hash.
47
+ """
48
+
49
+ call: str
50
+ grid: str
51
+ power: int
52
+ callhash: int | None = None
53
+
54
+ @property
55
+ def kind(self) -> int:
56
+ if len(self.grid) == 6:
57
+ return 3
58
+ return 2 if "/" in self.call else 1
59
+
60
+ def __str__(self) -> str:
61
+ if self.kind == 3:
62
+ return f"<{self.call or '...'}> {self.grid} {self.power}"
63
+ if self.kind == 2:
64
+ return f"{self.call} {self.power}"
65
+ return f"{self.call} {self.grid} {self.power}"
66
+
67
+
68
+ def _rot(x: int, k: int) -> int:
69
+ return ((x << k) | (x >> (32 - k))) & M32
70
+
71
+
72
+ def _mix(a: int, b: int, c: int) -> tuple[int, int, int]:
73
+ for r1, r2, r3 in ((4, 6, 8), (16, 19, 4)):
74
+ a = ((a - c) & M32) ^ _rot(c, r1)
75
+ c = (c + b) & M32
76
+ b = ((b - a) & M32) ^ _rot(a, r2)
77
+ a = (a + c) & M32
78
+ c = ((c - b) & M32) ^ _rot(b, r3)
79
+ b = (b + a) & M32
80
+ return a, b, c
81
+
82
+
83
+ def _final(a: int, b: int, c: int) -> int:
84
+ c = ((c ^ b) - _rot(b, 14)) & M32
85
+ a = ((a ^ c) - _rot(c, 11)) & M32
86
+ b = ((b ^ a) - _rot(a, 25)) & M32
87
+ c = ((c ^ b) - _rot(b, 16)) & M32
88
+ a = ((a ^ c) - _rot(c, 4)) & M32
89
+ b = ((b ^ a) - _rot(a, 14)) & M32
90
+ return ((c ^ b) - _rot(b, 24)) & M32
91
+
92
+
93
+ def lookup3(data: bytes, initval: int) -> int:
94
+ """Bob Jenkins' hashlittle from lookup3.c, which wsprd uses to hash callsigns."""
95
+ a = b = c = (0xDEADBEEF + len(data) + initval) & M32
96
+ while len(data) > 12:
97
+ a = (a + int.from_bytes(data[0:4], "little")) & M32
98
+ b = (b + int.from_bytes(data[4:8], "little")) & M32
99
+ c = (c + int.from_bytes(data[8:12], "little")) & M32
100
+ a, b, c = _mix(a, b, c)
101
+ data = data[12:]
102
+ if not data:
103
+ return c
104
+ tail = data.ljust(12, b"\0")
105
+ a = (a + int.from_bytes(tail[0:4], "little")) & M32
106
+ b = (b + int.from_bytes(tail[4:8], "little")) & M32
107
+ c = (c + int.from_bytes(tail[8:12], "little")) & M32
108
+ return _final(a, b, c)
109
+
110
+
111
+ def callhash(call: str) -> int:
112
+ """The 15-bit hash a type 3 message carries in place of the call."""
113
+ return lookup3(call.upper().encode(), 146) & 0x7FFF
114
+
115
+
116
+ def _charval(c: str) -> int:
117
+ i = ALPHA.find(c)
118
+ if i < 0:
119
+ raise ValueError(f"bad character {c!r} in callsign")
120
+ return i
121
+
122
+
123
+ def _normalize_call(call: str) -> str:
124
+ call = call.upper()
125
+ if len(call) > 6 or not call.isalnum():
126
+ raise ValueError(f"{call!r} is not a plain callsign of up to 6 characters")
127
+ if len(call) >= 3 and not call[2].isdigit():
128
+ call = " " + call
129
+ if len(call) < 3 or len(call) > 6 or not call[2].isdigit():
130
+ raise ValueError(f"{call!r} has no digit in the third position")
131
+ return call.ljust(6)
132
+
133
+
134
+ def _pack_call(call: str) -> int:
135
+ v = [_charval(ch) for ch in _normalize_call(call)]
136
+ if v[1] == 36 or v[2] > 9 or any(x < 10 for x in v[3:]):
137
+ raise ValueError(f"{call!r} does not fit the WSPR callsign layout")
138
+ n = v[0]
139
+ n = n * 36 + v[1]
140
+ n = n * 10 + v[2]
141
+ for x in v[3:]:
142
+ n = n * 27 + (26 if x == 36 else x - 10)
143
+ return n
144
+
145
+
146
+ def _unpack_call(n: int) -> str | None:
147
+ chars = []
148
+ for _ in range(3):
149
+ n, r = divmod(n, 27)
150
+ chars.append(" " if r == 26 else ALPHA[r + 10])
151
+ n, r = divmod(n, 10)
152
+ chars.append(ALPHA[r])
153
+ n, r = divmod(n, 36)
154
+ chars.append(ALPHA[r])
155
+ if n > 36:
156
+ return None
157
+ chars.append(ALPHA[n])
158
+ return "".join(reversed(chars))
159
+
160
+
161
+ def _pack_grid(grid: str) -> int:
162
+ g = grid.upper()
163
+ if len(g) != 4 or not ("A" <= g[0] <= "R" and "A" <= g[1] <= "R"
164
+ and g[2].isdigit() and g[3].isdigit()):
165
+ raise ValueError(f"{grid!r} is not a 4-character locator")
166
+ a, b = ord(g[0]) - 65, ord(g[1]) - 65
167
+ return (179 - 10 * a - int(g[2])) * 180 + 10 * b + int(g[3])
168
+
169
+
170
+ def _unpack_grid(m: int) -> str | None:
171
+ x, y = divmod(m, 180)
172
+ a, c = divmod(179 - x, 10)
173
+ b, d = divmod(y, 10)
174
+ if not (0 <= a < 18 and 0 <= b < 18):
175
+ return None
176
+ return f"{chr(65 + a)}{chr(65 + b)}{c}{d}"
177
+
178
+
179
+ def _affix(call: str) -> tuple[str, int]:
180
+ """Split a compound call into the plain call and its prefix or suffix code."""
181
+ left, _, right = call.upper().partition("/")
182
+ if "/" in right or not left or not right:
183
+ raise ValueError(f"{call!r} needs exactly one '/' between two parts")
184
+ if len(right) == 1 and right.isalnum():
185
+ return left, 60000 + _charval(right)
186
+ if len(right) == 2 and right.isdigit() and right[0] != "0":
187
+ return left, 60000 + 26 + int(right)
188
+ if len(left) <= 3 and left.isalnum():
189
+ n = 0
190
+ for ch in left.rjust(3):
191
+ n = n * 37 + _charval(ch)
192
+ return right, n
193
+ raise ValueError(f"{call!r}: WSPR allows a prefix of 1 to 3 characters, or a suffix of "
194
+ "one character or two digits")
195
+
196
+
197
+ def _unaffix(call: str, n3: int) -> str | None:
198
+ if n3 < 60000:
199
+ pfx = ""
200
+ for _ in range(3):
201
+ n3, r = divmod(n3, 37)
202
+ pfx = ALPHA[r] + pfx
203
+ # three base-37 characters only reach 50652; anything above is no prefix
204
+ if n3:
205
+ return None
206
+ pfx = pfx.lstrip()
207
+ return None if not pfx or " " in pfx else f"{pfx}/{call}"
208
+ nc = n3 - 60000
209
+ if nc < 36:
210
+ return f"{call}/{ALPHA[nc]}"
211
+ return f"{call}/{nc - 26}" if nc <= 125 else None
212
+
213
+
214
+ def _grid6_ok(g: str) -> bool:
215
+ return ("A" <= g[0] <= "R" and "A" <= g[1] <= "R" and g[2].isdigit() and g[3].isdigit()
216
+ and "A" <= g[4] <= "X" and "A" <= g[5] <= "X")
217
+
218
+
219
+ def pack(msg: Message) -> int:
220
+ """Pack a message of any type into its 50-bit integer."""
221
+ if msg.power not in VALID_POWERS:
222
+ raise ValueError(f"{msg.power} dBm is not a valid WSPR power")
223
+ if msg.kind == 3:
224
+ g = msg.grid.upper()
225
+ if not _grid6_ok(g):
226
+ raise ValueError(f"{msg.grid!r} is not a 6-character locator")
227
+ h = msg.callhash if msg.callhash is not None else callhash(msg.call)
228
+ # the locator rides in the callsign field, rotated so a digit lands third
229
+ n = _pack_call(g[1:] + g[0])
230
+ m = h * 128 - (msg.power + 1) + 64
231
+ elif msg.kind == 2:
232
+ if msg.grid:
233
+ raise ValueError(f"a compound call like {msg.call!r} carries no locator")
234
+ base, n3 = _affix(msg.call)
235
+ n = _pack_call(base)
236
+ ng, high = (n3 - 32768, 1) if n3 > 32767 else (n3, 0)
237
+ m = ng * 128 + msg.power + 1 + high + 64
238
+ else:
239
+ n = _pack_call(msg.call)
240
+ m = _pack_grid(msg.grid) * 128 + msg.power + 64
241
+ return (n << 22) | m
242
+
243
+
244
+ def unpack(value: int) -> Message | None:
245
+ """Unpack a 50-bit value; None when it is not a valid message of any type."""
246
+ n, m = value >> 22, value & 0x3FFFFF
247
+ ntype = (m & 0x7F) - 64
248
+ ng = m >> 7
249
+ raw = _unpack_call(n)
250
+ if raw is None or ntype > 62:
251
+ return None
252
+ if ntype < 0:
253
+ grid = raw[5] + raw[:5]
254
+ power = -(ntype + 1)
255
+ if power not in VALID_POWERS or not _grid6_ok(grid):
256
+ return None
257
+ return Message("", grid, power, ng)
258
+ call = raw.strip()
259
+ if " " in call or not call:
260
+ return None
261
+ if ntype % 10 in (0, 3, 7):
262
+ g4 = _unpack_grid(ng)
263
+ return None if g4 is None else Message(call, g4, ntype)
264
+ # type 2: the power's last digit is bumped by 1 or 2 to flag a prefix or a suffix
265
+ nu = ntype % 10
266
+ nadd = nu - 7 if nu > 7 else nu - 3 if nu > 3 else nu
267
+ power = ntype - nadd
268
+ full = _unaffix(call, ng + 32768 * (nadd - 1))
269
+ if full is None or power not in VALID_POWERS:
270
+ return None
271
+ return Message(full, "", power)
272
+
273
+
274
+ def resolve(msg: Message, calls: dict[int, str]) -> Message:
275
+ """Fill in a type 3 message's call from a table of hashes of calls heard elsewhere."""
276
+ if msg.kind != 3 or msg.call or msg.callhash not in calls:
277
+ return msg
278
+ return Message(calls[msg.callhash], msg.grid, msg.power, msg.callhash)
279
+
280
+
281
+ def parity(x: int) -> int:
282
+ return x.bit_count() & 1
283
+
284
+
285
+ def bits_of(value: int) -> list[int]:
286
+ """The 81 encoder input bits: 50 message bits, MSB first, then 31 zero tail bits."""
287
+ return [(value >> (NDATA - 1 - i)) & 1 for i in range(NDATA)] + [0] * (NBITS - NDATA)
288
+
289
+
290
+ def convolve(bits: list[int]) -> np.ndarray:
291
+ reg = 0
292
+ out = np.empty(2 * len(bits), dtype=np.int8)
293
+ for i, b in enumerate(bits):
294
+ reg = ((reg << 1) | b) & 0xFFFFFFFF
295
+ out[2 * i] = parity(reg & POLY1)
296
+ out[2 * i + 1] = parity(reg & POLY2)
297
+ return out
298
+
299
+
300
+ def interleave(coded: np.ndarray) -> np.ndarray:
301
+ out = np.empty_like(coded)
302
+ out[PERM] = coded
303
+ return out
304
+
305
+
306
+ def deinterleave(chan: np.ndarray) -> np.ndarray:
307
+ return chan[PERM]
308
+
309
+
310
+ def symbols(msg: Message) -> np.ndarray:
311
+ """The 162 channel tones (0-3) for a message."""
312
+ data = interleave(convolve(bits_of(pack(msg))))
313
+ return (SYNC + 2 * data).astype(np.int8)