hamsci-dsp 0.10.1__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.
Files changed (80) hide show
  1. hamsci_dsp/__init__.py +20 -0
  2. hamsci_dsp/chirp/__init__.py +1 -0
  3. hamsci_dsp/chirp/clean.py +143 -0
  4. hamsci_dsp/chirp/screen.py +81 -0
  5. hamsci_dsp/chirp/waveform.py +127 -0
  6. hamsci_dsp/constants.py +22 -0
  7. hamsci_dsp/counter_map.py +132 -0
  8. hamsci_dsp/data/giro_stations.tsv +135 -0
  9. hamsci_dsp/data_product_registry.py +630 -0
  10. hamsci_dsp/dsp.py +183 -0
  11. hamsci_dsp/geometry.py +242 -0
  12. hamsci_dsp/io/__init__.py +32 -0
  13. hamsci_dsp/io/authority_snapshot_store.py +386 -0
  14. hamsci_dsp/io/calibration_file.py +284 -0
  15. hamsci_dsp/io/dual_writer.py +61 -0
  16. hamsci_dsp/io/sqlite_reader.py +353 -0
  17. hamsci_dsp/io/sqlite_writer.py +589 -0
  18. hamsci_dsp/io/uncertainty.py +253 -0
  19. hamsci_dsp/ionosphere/__init__.py +5 -0
  20. hamsci_dsp/ionosphere/data_service.py +1739 -0
  21. hamsci_dsp/ionosphere/ionex.py +279 -0
  22. hamsci_dsp/ionosphere/model.py +1562 -0
  23. hamsci_dsp/ionosphere/solar.py +84 -0
  24. hamsci_dsp/ionosphere/space_weather.py +371 -0
  25. hamsci_dsp/ionosphere/tomography.py +488 -0
  26. hamsci_dsp/propagation/__init__.py +37 -0
  27. hamsci_dsp/propagation/arrival_matrix.py +1521 -0
  28. hamsci_dsp/propagation/carrier.py +94 -0
  29. hamsci_dsp/propagation/carrier_tec.py +453 -0
  30. hamsci_dsp/propagation/engine.py +228 -0
  31. hamsci_dsp/propagation/mode_solver.py +1262 -0
  32. hamsci_dsp/propagation/model.py +1295 -0
  33. hamsci_dsp/propagation/oblique.py +139 -0
  34. hamsci_dsp/propagation/scintillation.py +654 -0
  35. hamsci_dsp/propagation/tec_estimator.py +404 -0
  36. hamsci_dsp/propagation/tec_geometry.py +98 -0
  37. hamsci_dsp/propagation/tec_validator.py +338 -0
  38. hamsci_dsp/propagation/transmission_time.py +1680 -0
  39. hamsci_dsp/propagation/vtec.py +637 -0
  40. hamsci_dsp/raytrace.py +741 -0
  41. hamsci_dsp/schemas/__init__.py +170 -0
  42. hamsci_dsp/schemas/calibration_v1.json +147 -0
  43. hamsci_dsp/schemas/data_dictionary.json +370 -0
  44. hamsci_dsp/schemas/diag_chrony_stats_v1.json +125 -0
  45. hamsci_dsp/schemas/l1_all_arrivals_v1.json +122 -0
  46. hamsci_dsp/schemas/l1_bcd_timecode_v1.json +79 -0
  47. hamsci_dsp/schemas/l1_broadcast_measurements_v1.json +407 -0
  48. hamsci_dsp/schemas/l1_channel_observables_v1.json +237 -0
  49. hamsci_dsp/schemas/l1_metrology_measurements_v1.json +143 -0
  50. hamsci_dsp/schemas/l1_tone_detections_v1.json +229 -0
  51. hamsci_dsp/schemas/l2_decoder_comparison_v1.json +165 -0
  52. hamsci_dsp/schemas/l2_detection_attempts_v1.json +127 -0
  53. hamsci_dsp/schemas/l2_physics_v1.json +87 -0
  54. hamsci_dsp/schemas/l2_test_signal_v1.json +447 -0
  55. hamsci_dsp/schemas/l2_tick_phase_v1.json +135 -0
  56. hamsci_dsp/schemas/l2_tick_timing_v1.json +135 -0
  57. hamsci_dsp/schemas/l2_timing_measurements_v1.json +387 -0
  58. hamsci_dsp/schemas/l3_dtec_diff_v1.json +80 -0
  59. hamsci_dsp/schemas/l3_dtec_timeseries_v1.json +101 -0
  60. hamsci_dsp/schemas/l3_dtec_v1.json +136 -0
  61. hamsci_dsp/schemas/l3_fusion_timing_v1.json +400 -0
  62. hamsci_dsp/schemas/l3_gnss_vtec_v1.json +143 -0
  63. hamsci_dsp/schemas/l3_physics_v1.json +91 -0
  64. hamsci_dsp/schemas/l3_tec_v1.json +150 -0
  65. hamsci_dsp/schemas/l3_tid_v1.json +134 -0
  66. hamsci_dsp/schemas/l3b_absorption_v1.json +146 -0
  67. hamsci_dsp/schemas/l3b_iono_events_v1.json +151 -0
  68. hamsci_dsp/schemas/l3c_propagation_stats_v1.json +181 -0
  69. hamsci_dsp/schemas/registry.json +115 -0
  70. hamsci_dsp/sigmondb_rows.py +167 -0
  71. hamsci_dsp/stability.py +310 -0
  72. hamsci_dsp/stations.py +153 -0
  73. hamsci_dsp/t6_anchor.py +96 -0
  74. hamsci_dsp/timing.py +558 -0
  75. hamsci_dsp/timing_map.py +433 -0
  76. hamsci_dsp-0.10.1.dist-info/METADATA +125 -0
  77. hamsci_dsp-0.10.1.dist-info/RECORD +80 -0
  78. hamsci_dsp-0.10.1.dist-info/WHEEL +5 -0
  79. hamsci_dsp-0.10.1.dist-info/licenses/LICENSE +21 -0
  80. hamsci_dsp-0.10.1.dist-info/top_level.txt +1 -0
hamsci_dsp/__init__.py ADDED
@@ -0,0 +1,20 @@
1
+ """hamsci-dsp — shared DSP / timing utilities for the HamSCI sigmond suite.
2
+
3
+ This is the canonical home for code that several sigmond clients otherwise
4
+ duplicate. It is an importable library only — no CLI, no systemd, no client
5
+ contract surface — pinned by each consumer via
6
+ ``[tool.uv.sources] hamsci-dsp = { path = "../hamsci-dsp", editable = true }``.
7
+
8
+ Modules:
9
+ timing — AuthorityReader / AuthoritySnapshot: the consumer side of
10
+ hf-timestd's /run/hf-timestd/authority.json (RTP↔UTC offset);
11
+ acquire_anchor_utc: the one shared RTP->UTC anchor every
12
+ recorder pins at stream start (RTP timestamp + authority offset).
13
+ Epoch-aligned slot *boundaries* live in ka9q.SlotClock, not here.
14
+ """
15
+
16
+ try:
17
+ from importlib.metadata import PackageNotFoundError, version as _version
18
+ __version__ = _version("hamsci-dsp")
19
+ except PackageNotFoundError: # source tree without installed metadata
20
+ __version__ = "unknown"
@@ -0,0 +1 @@
1
+ """Chirp-sounder signal pieces shared by chirp-recorder and its tools."""
@@ -0,0 +1,143 @@
1
+ """CLEAN for chirp delay profiles: remove each arrival's gating ladder.
2
+
3
+ Ports codar-mf's clean.py with the waveform passed in. The plain-replica
4
+ matched filter turns one gated arrival into a main peak plus rungs every
5
+ 1 / (|k| * Tg). Their power pattern depends on the gate period and duty,
6
+ not on the gate phase, so one synthesised response serves every site in a
7
+ sweep group. CLEAN takes the strongest peak of the residual, synthesises a
8
+ noiseless gated chirp at that delay (sub-sample), and fits all amplitudes
9
+ together after each new component.
10
+
11
+ Pure functions. No clock reads, no I/O.
12
+ """
13
+ from __future__ import annotations
14
+
15
+ from dataclasses import dataclass
16
+ from functools import lru_cache
17
+ from typing import Optional
18
+
19
+ import numpy as np
20
+
21
+ from hamsci_dsp.chirp.waveform import (Waveform, gated, replica,
22
+ rung_spacing_s, samples_per_period)
23
+
24
+ _RESIDUE_S = 1e-4 # within this of a stronger component: main-lobe residue
25
+ _RUNG_TOL_S = 3e-4 # within this of m * L: sits on a rung
26
+ _MAX_RUNG = 4
27
+
28
+
29
+ @dataclass(frozen=True)
30
+ class Component:
31
+ """One CLEAN component. Tags: "A" arrival, "R" rung, "m" main-lobe residue."""
32
+ tau_s: float
33
+ level_db: float
34
+ tag: str
35
+ parent_tau_s: Optional[float] = None
36
+ rung: Optional[int] = None
37
+
38
+
39
+ @lru_cache(maxsize=8)
40
+ def _replica_fft_conj(wf: Waveform, fs: float) -> np.ndarray:
41
+ out = np.conj(np.fft.fft(replica(wf, fs)))
42
+ out.setflags(write=False)
43
+ return out
44
+
45
+
46
+ def matched_profile(sweeps: np.ndarray, wf: Waveform, fs: float) -> np.ndarray:
47
+ """Mean matched-filter power per lag against the plain replica.
48
+
49
+ ``sweeps`` has shape (M, N), N = samples_per_period(wf, fs).
50
+ """
51
+ x = np.asarray(sweeps)
52
+ if x.ndim != 2 or x.shape[1] != samples_per_period(wf, fs):
53
+ raise ValueError(f"sweeps must have shape (M, {samples_per_period(wf, fs)})")
54
+ R = np.fft.ifft(np.fft.fft(x, axis=1) * _replica_fft_conj(wf, fs)[None, :], axis=1)
55
+ return np.mean(np.abs(R) ** 2, axis=0)
56
+
57
+
58
+ @lru_cache(maxsize=512)
59
+ def _response(wf: Waveform, fs: float, tau_s: float) -> np.ndarray:
60
+ """Normalised profile of one noiseless arrival at ``tau_s``."""
61
+ r = matched_profile(gated(wf, fs, tau_s)[None, :], wf, fs)
62
+ out = r / r.max()
63
+ out.setflags(write=False)
64
+ return out
65
+
66
+
67
+ def _refine(p: np.ndarray, i: int) -> float:
68
+ """Parabolic peak interpolation in log power; returns a fractional index."""
69
+ n = p.size
70
+ a, b, c = np.log(p[(i - 1) % n]), np.log(p[i]), np.log(p[(i + 1) % n])
71
+ den = a - 2 * b + c
72
+ return i + (0.5 * (a - c) / den if den < 0 else 0.0)
73
+
74
+
75
+ def clean(profile: np.ndarray, wf: Waveform, fs: float, *,
76
+ floor_db: float = 10.0, max_comp: int = 12):
77
+ """Matching pursuit with a joint amplitude refit after every new component.
78
+
79
+ Greedy one-at-a-time subtraction misassigns power where ladders overlap.
80
+ Refitting every amplitude together removes that. Returns the components,
81
+ strongest first and all tagged "A", and the residual profile.
82
+ """
83
+ p = np.asarray(profile, dtype=float)
84
+ n = p.size
85
+ period = wf.period_s
86
+ floor = np.median(p)
87
+ sig = p - floor
88
+ taus: list = []
89
+ cols: list = []
90
+ res, amps = sig.copy(), np.zeros(0)
91
+ blocked = np.zeros(n, bool) # lags already explained by a component
92
+ for _ in range(4 * max_comp):
93
+ if len(taus) == max_comp:
94
+ break
95
+ i = int(np.argmax(np.where(blocked, -np.inf, res)))
96
+ if res[i] <= floor * 10 ** (floor_db / 10):
97
+ break
98
+ fi = _refine(np.maximum(res, floor * 1e-3), i)
99
+ tau = (fi / fs) % period
100
+ if any(abs(((tau - t + period / 2) % period) - period / 2) * fs < 1.0
101
+ for t in taus):
102
+ blocked[i] = True # main-lobe leftover of an existing component
103
+ continue
104
+ taus.append(tau)
105
+ cols.append(_response(wf, fs, tau))
106
+ A = np.stack(cols, axis=1)
107
+ amps = np.linalg.lstsq(A, sig, rcond=None)[0]
108
+ while (amps < 0).any(): # drop components the fit rejects
109
+ keep = amps > 0
110
+ taus = [t for t, k in zip(taus, keep) if k]
111
+ cols = [c for c, k in zip(cols, keep) if k]
112
+ A = np.stack(cols, axis=1)
113
+ amps = np.linalg.lstsq(A, sig, rcond=None)[0]
114
+ res = sig - A @ amps
115
+ pairs = sorted(zip(taus, (10 * np.log10(a / floor) for a in amps)),
116
+ key=lambda c: -c[1])
117
+ return [Component(t, float(db), "A") for t, db in pairs], res + floor
118
+
119
+
120
+ def tag_ladder(comps: list, wf: Waveform) -> list:
121
+ """Tag components that sit on a stronger component's ladder.
122
+
123
+ Within 0.1 ms of a stronger component: "m", main-lobe residue. Within
124
+ 0.3 ms of m * L for 1 <= |m| <= 4 (L the rung spacing): "R", a rung.
125
+ Everything else keeps its tag. The first stronger parent that matches wins.
126
+ """
127
+ L = rung_spacing_s(wf)
128
+ P = wf.period_s
129
+ out = []
130
+ for j, c in enumerate(comps):
131
+ tagged = c
132
+ for c0 in comps[:j]:
133
+ d = ((c.tau_s - c0.tau_s + P / 2) % P) - P / 2
134
+ if abs(d) < _RESIDUE_S:
135
+ tagged = Component(c.tau_s, c.level_db, "m", c0.tau_s, None)
136
+ break
137
+ if L is not None:
138
+ m = round(d / L)
139
+ if m != 0 and abs(d - m * L) < _RUNG_TOL_S and abs(m) <= _MAX_RUNG:
140
+ tagged = Component(c.tau_s, c.level_db, "R", c0.tau_s, int(m))
141
+ break
142
+ out.append(tagged)
143
+ return out
@@ -0,0 +1,81 @@
1
+ """Two screens on a detected chirp arrival: the half-band image test and the null rates.
2
+
3
+ Ports the screens of the 11-08 analyze.py. A chirp centred on the group's
4
+ centre fills both halves of the sweep. A chirp from a neighbouring centre
5
+ (same rate, 25 kHz away) overlaps one half only, so it shows as an image:
6
+ one half stands near the noise. The null rates are chirp rates no radar
7
+ uses; their peak-over-median levels measure the chain's own floor.
8
+
9
+ Pure functions. No clock reads, no I/O.
10
+ """
11
+ from __future__ import annotations
12
+
13
+ from dataclasses import replace
14
+
15
+ import numpy as np
16
+
17
+ from hamsci_dsp.chirp.clean import matched_profile
18
+ from hamsci_dsp.chirp.waveform import Waveform, replica, samples_per_period
19
+
20
+ NULL_RATES_HZ_PER_S: tuple = (60e3, -60e3, 70e3, -70e3, 130e3, -130e3,
21
+ 150e3, -150e3, 165e3, -165e3, 240e3, -240e3)
22
+
23
+
24
+ def _half_profile(sweeps: np.ndarray, wf: Waveform, fs: float, half: int) -> np.ndarray:
25
+ n = samples_per_period(wf, fs)
26
+ x = np.asarray(sweeps)
27
+ if x.ndim != 2 or x.shape[1] != n:
28
+ raise ValueError(f"sweeps must have shape (M, {n})")
29
+ t = np.arange(n) / fs
30
+ c = replica(wf, fs) * ((t < wf.period_s / 2) if half == 0 else (t >= wf.period_s / 2))
31
+ R = np.fft.ifft(np.fft.fft(x, axis=1) * np.conj(np.fft.fft(c))[None, :], axis=1)
32
+ return np.mean(np.abs(R) ** 2, axis=0)
33
+
34
+
35
+ def half_band_db(sweeps, wf: Waveform, fs: float, tau_s: float) -> float:
36
+ """Absolute dB difference between the two half-sweep levels at ``tau_s``.
37
+
38
+ Each half-sweep profile (replica masked to the first or second half of
39
+ the period) is read at the lag nearest ``tau_s``, as the peak within two
40
+ samples, over that profile's own median.
41
+ """
42
+ i = int(round(tau_s * fs))
43
+ levels = []
44
+ for half in (0, 1):
45
+ p = _half_profile(sweeps, wf, fs, half)
46
+ near = p[np.arange(i - 2, i + 3) % p.size]
47
+ levels.append(10 * np.log10(near.max() / np.median(p)))
48
+ return float(abs(levels[0] - levels[1]))
49
+
50
+
51
+ def split_null_rates(wf: Waveform, rates=NULL_RATES_HZ_PER_S) -> tuple:
52
+ """Split ``rates`` into (used, skipped) for ``wf``.
53
+
54
+ Skip any null rate within 10 % of the waveform's own sweep rate (as
55
+ c13.py:26 chose the set): ``|k - wf.rate| < 0.1 * |wf.rate|``. Such a
56
+ rate would read the arrival itself. This function never raises.
57
+ """
58
+ used, skipped = [], []
59
+ for k in rates:
60
+ (skipped if abs(k - wf.rate_hz_per_s) < 0.1 * abs(wf.rate_hz_per_s) else used).append(float(k))
61
+ return used, skipped
62
+
63
+
64
+ def null_levels(sweeps, wf: Waveform, fs: float, rates=NULL_RATES_HZ_PER_S) -> list:
65
+ """Peak-over-median dB of the matched profile at each usable null rate.
66
+
67
+ The twelve rates come from the 13 MHz analysis (c13.NULLS). Uses the
68
+ same centre and period as ``wf``; only the rate changes. A rate within
69
+ 10 % of the group's own sweep rate (``|k - wf.rate| < 0.1 * |wf.rate|``,
70
+ as c13.py:26 chose the set) is skipped,
71
+ so the list then holds fewer than twelve levels. ``split_null_rates``
72
+ names the skipped rates. The matched filter leaks a fixed fraction of
73
+ the arrival into the other rates: the arrival stands about 37 dB over the
74
+ null maximum at high SNR (a 61 dB peak puts the null maximum near 23 dB).
75
+ """
76
+ used, _ = split_null_rates(wf, rates)
77
+ out = []
78
+ for k in used:
79
+ p = matched_profile(sweeps, replace(wf, rate_hz_per_s=k), fs)
80
+ out.append(float(10 * np.log10(p.max() / np.median(p))))
81
+ return out
@@ -0,0 +1,127 @@
1
+ """A chirp sounder's waveform: descriptor, replica, gated model and gate fit.
2
+
3
+ Ports the module globals of codar-mf's clean.py into one frozen descriptor.
4
+ A gated chirp compressed by the plain-chirp matched filter gives a main peak
5
+ with rungs every 1 / (|k| * Tg). The rung pattern depends on the gate period
6
+ and duty, not on the gate phase.
7
+
8
+ Pure functions. No clock reads, no I/O.
9
+ """
10
+ from __future__ import annotations
11
+
12
+ from dataclasses import dataclass
13
+ from typing import Optional
14
+
15
+ import numpy as np
16
+
17
+ from hamsci_dsp.sigmondb_rows import group_key as _group_key
18
+
19
+
20
+ @dataclass(frozen=True)
21
+ class Waveform:
22
+ """One sweep group's transmitted waveform.
23
+
24
+ ``sweep_s`` names a sweep shorter than its period. It enters the group
25
+ key and the bandwidth; the replica still fills the whole period.
26
+ The gate turns on at the sweep start (gate phase 0).
27
+ """
28
+ centre_hz: float
29
+ rate_hz_per_s: float
30
+ period_s: float = 1.0
31
+ sweep_s: Optional[float] = None
32
+ gate_period_s: Optional[float] = None
33
+ gate_duty: float = 0.5
34
+
35
+ def group_key(self) -> str:
36
+ return _group_key(self.centre_hz, self.rate_hz_per_s, self.period_s,
37
+ self.sweep_s)
38
+
39
+ def bandwidth_hz(self) -> float:
40
+ return abs(self.rate_hz_per_s) * (self.sweep_s or self.period_s)
41
+
42
+
43
+ def samples_per_period(wf: Waveform, fs: float) -> int:
44
+ """Samples in one sweep period; the period must hold whole samples."""
45
+ x = wf.period_s * fs
46
+ n = int(round(x))
47
+ if abs(x - n) > 1e-6:
48
+ raise ValueError(
49
+ f"period {wf.period_s} s at {fs} Hz holds {x} samples, not a whole number")
50
+ return n
51
+
52
+
53
+ def _chirp(wf: Waveform, t: np.ndarray) -> np.ndarray:
54
+ P = wf.period_s
55
+ return np.exp(1j * np.pi * wf.rate_hz_per_s * ((t % P) - P / 2) ** 2)
56
+
57
+
58
+ def replica(wf: Waveform, fs: float) -> np.ndarray:
59
+ """One period of the baseband chirp, complex128."""
60
+ t = np.arange(samples_per_period(wf, fs)) / fs
61
+ return _chirp(wf, t)
62
+
63
+
64
+ def gated(wf: Waveform, fs: float, tau_s: float) -> np.ndarray:
65
+ """Noiseless gated chirp whose sweep starts ``tau_s`` after sample 0.
66
+
67
+ Plain (ungated) when ``gate_period_s`` is None.
68
+ """
69
+ t = np.arange(samples_per_period(wf, fs)) / fs
70
+ u = (t - tau_s) % wf.period_s
71
+ out = _chirp(wf, u)
72
+ if wf.gate_period_s is not None:
73
+ out = out * (((u / wf.gate_period_s) % 1.0) < wf.gate_duty)
74
+ return out
75
+
76
+
77
+ def rung_spacing_s(wf: Waveform) -> Optional[float]:
78
+ """Lag between the main peak and its first gating rung."""
79
+ if wf.gate_period_s is None:
80
+ return None
81
+ return 1.0 / (abs(wf.rate_hz_per_s) * wf.gate_period_s)
82
+
83
+
84
+ @dataclass(frozen=True)
85
+ class GateFit:
86
+ period_s: float
87
+ n_rungs: int
88
+
89
+
90
+ _MIN_RUNG_DB = 6.0 # a rung must stand this far over the median
91
+ _DROP_DB = (2.0, 6.0) # and sit this far under the main peak (50 % gate: 3.9)
92
+ _L_MIN_S, _L_MAX_S = 2e-3, 40e-3
93
+
94
+
95
+ def fit_gate(profile: np.ndarray, wf: Waveform, fs: float) -> Optional[GateFit]:
96
+ """Fit the gate period from a plain-replica matched profile.
97
+
98
+ Take the strongest lag, scan rung spacings of 2 to 40 ms in one-sample
99
+ steps, and keep the spacing whose first rungs score highest over the
100
+ median. Accept it only when that rung stands 6 dB over the median and
101
+ 2 to 6 dB under the main peak. Return None otherwise.
102
+ """
103
+ p = np.asarray(profile, dtype=float)
104
+ n = p.size
105
+ med = float(np.median(p))
106
+ if med <= 0:
107
+ return None
108
+ i0 = int(np.argmax(p))
109
+ lo, hi = int(np.ceil(_L_MIN_S * fs)), int(np.floor(_L_MAX_S * fs))
110
+ lags = np.arange(lo, min(hi, n // 2) + 1)
111
+ if lags.size == 0:
112
+ return None
113
+ score = 0.5 * (p[(i0 + lags) % n] + p[(i0 - lags) % n]) / med
114
+ j = int(np.argmax(score))
115
+ L = int(lags[j])
116
+ rung_db = 10 * np.log10(score[j])
117
+ drop_db = 10 * np.log10(p[i0] / (score[j] * med))
118
+ if rung_db < _MIN_RUNG_DB or not (_DROP_DB[0] <= drop_db <= _DROP_DB[1]):
119
+ return None
120
+
121
+ def clears(m: int) -> bool:
122
+ c = i0 + m * L
123
+ near = p[np.arange(c - 2, c + 3) % n]
124
+ return 10 * np.log10(near.max() / med) >= _MIN_RUNG_DB
125
+
126
+ n_rungs = sum(clears(m) for m in (-4, -3, -2, -1, 1, 2, 3, 4))
127
+ return GateFit(period_s=1.0 / (abs(wf.rate_hz_per_s) * (L / fs)), n_rungs=n_rungs)
@@ -0,0 +1,22 @@
1
+ """Physical constants shared across the sigmond propagation stack.
2
+
3
+ Consolidates the speed-of-light / ionospheric / Earth constants that were
4
+ redefined (in several unit forms) across hf-timestd, hf-tec, and codar-sounder.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ # Speed of light
9
+ C_M_S = 299_792_458.0 # m/s
10
+ C_KM_S = C_M_S / 1_000.0 # km/s
11
+ C_KM_MS = C_KM_S / 1_000.0 # km/ms
12
+
13
+ # Ionospheric group-delay / TEC constant: Δτ = (K_TEC / f²) · TEC (SI).
14
+ # Phase advance and group delay share this 40.3 m³ s⁻² constant.
15
+ K_TEC = 40.3 # m³ / s²
16
+
17
+ # 1 TEC unit = 1e16 electrons / m²
18
+ TECU = 1.0e16
19
+
20
+ # Mean Earth radius (same value the clients' haversines used).
21
+ R_EARTH_KM = 6371.0088
22
+ R_EARTH_M = R_EARTH_KM * 1_000.0
@@ -0,0 +1,132 @@
1
+ """CounterMap: one channel's RTP counter mapped to radiod's input-sample index.
2
+
3
+ Since ka9q-radio e5f790dd every radiod channel starts its own RTP counter, so
4
+ two channels' RTP values never compare directly. Each channel does report a
5
+ pair in its own status stream: INPUT_SAMPLES (radio_status.c:670, the value
6
+ `chan->filter.out.sample_index`) and RTP_TIMESNAP (radio_status.c:819, the
7
+ channel's RTP timestamp). This module learns, from several such pairs, the
8
+ map from that channel's RTP to the absolute input-sample index, a coordinate
9
+ that every channel of one radiod run shares.
10
+
11
+ Assumption: the RTP-to-INPUT_SAMPLES offset convention holds equally for every
12
+ linear channel. Task 3's live run tests that assumption.
13
+
14
+ Pure logic. No clock reads, no I/O. `input_epoch_gps_s` only names the radiod
15
+ run (gps_s - input_samples / f_in); it never carries timing.
16
+
17
+ RTP is a 32-bit counter, so `input_index` and `rolled_forward` reach only
18
+ half the range (2**31 samples, 24 h 51 m at 24 kHz) from `rtp_ref`. A map held
19
+ longer must roll forward before it falls out of that reach.
20
+ """
21
+ from __future__ import annotations
22
+
23
+ from collections import Counter
24
+ from dataclasses import dataclass
25
+ from typing import Optional, Sequence
26
+
27
+ _MOD = 2**32
28
+
29
+
30
+ def _s32(x: int) -> int:
31
+ """Signed 32-bit difference."""
32
+ x &= 0xFFFFFFFF
33
+ return x - _MOD if x >= 2**31 else x
34
+
35
+
36
+ @dataclass(frozen=True)
37
+ class CounterPoll:
38
+ """One (INPUT_SAMPLES, RTP_TIMESNAP) status pair with its context."""
39
+ rtp_timesnap: int
40
+ input_samples: int
41
+ filter_blocksize: int
42
+ input_samprate: int
43
+ output_samprate: int
44
+ gps_time_ns: int
45
+
46
+
47
+ @dataclass(frozen=True)
48
+ class CounterMap:
49
+ rtp_ref: int # block-aligned RTP in this channel's counter
50
+ input_ref: int # radiod input-sample index at rtp_ref
51
+ ilen: int # FILTER_BLOCKSIZE: input samples per block
52
+ olen: int # output samples per block
53
+ input_samprate: int
54
+ input_epoch_gps_s: float # least-late gps_s - input_samples/f_in; names the run
55
+ n_agree: int
56
+
57
+ @classmethod
58
+ def from_polls(cls, polls: Sequence[CounterPoll],
59
+ min_agree: int = 3) -> Optional["CounterMap"]:
60
+ if not polls:
61
+ return None
62
+ first = polls[0]
63
+ ilen, f_in, f_out = first.filter_blocksize, first.input_samprate, first.output_samprate
64
+ if ilen <= 0 or f_in <= 0 or f_out <= 0:
65
+ return None
66
+ num = f_out * ilen
67
+ if num % f_in:
68
+ return None
69
+ olen = num // f_in
70
+ if olen == 0:
71
+ return None
72
+ rtp0 = first.rtp_timesnap & 0xFFFFFFFF
73
+ intercepts = []
74
+ for p in polls:
75
+ if (p.filter_blocksize, p.input_samprate, p.output_samprate) != (ilen, f_in, f_out):
76
+ return None
77
+ d = _s32(p.rtp_timesnap - rtp0)
78
+ if d % olen:
79
+ return None
80
+ intercepts.append(p.input_samples - (d // olen) * ilen)
81
+ value, count = Counter(intercepts).most_common(1)[0]
82
+ if count < min_agree:
83
+ return None
84
+ epoch = min(p.gps_time_ns / 1e9 - p.input_samples / f_in
85
+ for p, i in zip(polls, intercepts) if i == value)
86
+ return cls(rtp_ref=rtp0, input_ref=value, ilen=ilen, olen=olen,
87
+ input_samprate=f_in, input_epoch_gps_s=epoch, n_agree=count)
88
+
89
+ def input_index(self, rtp: int) -> float:
90
+ return self.input_ref + _s32((rtp & 0xFFFFFFFF) - self.rtp_ref) * self.ilen / self.olen
91
+
92
+ def rolled_forward(self, rtp_now: int) -> "CounterMap":
93
+ blocks = round(_s32((rtp_now & 0xFFFFFFFF) - self.rtp_ref) / self.olen)
94
+ return CounterMap(
95
+ rtp_ref=(self.rtp_ref + blocks * self.olen) % _MOD,
96
+ input_ref=self.input_ref + blocks * self.ilen,
97
+ ilen=self.ilen, olen=self.olen, input_samprate=self.input_samprate,
98
+ input_epoch_gps_s=self.input_epoch_gps_s, n_agree=self.n_agree)
99
+
100
+ def same_run(self, other: "CounterMap", tol_s: float = 0.5) -> bool:
101
+ return ((self.ilen, self.olen, self.input_samprate)
102
+ == (other.ilen, other.olen, other.input_samprate)
103
+ and abs(self.input_epoch_gps_s - other.input_epoch_gps_s) <= tol_s)
104
+
105
+ def intercept_blocks_from(self, other: "CounterMap") -> Optional[int]:
106
+ """Whole blocks by which this map's index at its rtp_ref exceeds
107
+ `other`'s; None for another run or a non-whole difference."""
108
+ if not self.same_run(other):
109
+ return None
110
+ blocks = (self.input_index(self.rtp_ref) - other.input_index(self.rtp_ref)) / self.ilen
111
+ whole = round(blocks)
112
+ return whole if abs(blocks - whole) < 1e-6 else None
113
+
114
+ def to_dict(self) -> dict:
115
+ return {"rtp_ref": self.rtp_ref, "input_ref": self.input_ref,
116
+ "ilen": self.ilen, "olen": self.olen,
117
+ "input_samprate": self.input_samprate,
118
+ "input_epoch_gps_s": self.input_epoch_gps_s,
119
+ "n_agree": self.n_agree}
120
+
121
+ @classmethod
122
+ def from_dict(cls, d: Optional[dict]) -> Optional["CounterMap"]:
123
+ if not d:
124
+ return None
125
+ try:
126
+ return cls(rtp_ref=int(d["rtp_ref"]), input_ref=int(d["input_ref"]),
127
+ ilen=int(d["ilen"]), olen=int(d["olen"]),
128
+ input_samprate=int(d["input_samprate"]),
129
+ input_epoch_gps_s=float(d["input_epoch_gps_s"]),
130
+ n_agree=int(d["n_agree"]))
131
+ except (KeyError, TypeError, ValueError):
132
+ return None
@@ -0,0 +1,135 @@
1
+ # GIRO/DIDBase ionosonde station fallback table for hf-timestd.
2
+ # Bundled snapshot of https://lgdc.uml.edu/common/DIDBFastStationList
3
+ # Generated 2026-06-12 ; longitudes normalised to [-180,180).
4
+ # Columns: ursi_code<TAB>name<TAB>lat_deg<TAB>lon_deg
5
+ # Used only when the live station list is unreachable/unparseable.
6
+ #
7
+ AA343 ALMATY 43.18 76.95
8
+ AC843 IDAHO NATIONAL LAB 43.81 -112.68
9
+ AH223 AHMEDABAD 23.00 72.50
10
+ AL945 ALPENA 45.07 -83.56
11
+ AN438 ANYANG 37.39 126.95
12
+ AS00Q ASCENSION ISLAND -7.95 -14.40
13
+ AT138 ATHENS 38.00 23.50
14
+ AU930 AUSTIN 30.40 -97.70
15
+ AW426 AWASE 26.32 127.84
16
+ BC840 BOULDER 40.00 -105.30
17
+ BJJ32 BERMUDA 32.40 -64.70
18
+ BLJ03 BELEM 1.43 -48.44
19
+ BP440 BEIJING 40.30 116.20
20
+ BR52P BRISBANE -27.06 153.06
21
+ BV53Q BUNDOORA -37.70 145.05
22
+ BVJ03 BOA VISTA 2.80 -60.70
23
+ CAJ2M CACHOEIRA PAULISTA -22.70 -45.00
24
+ CB53N CANBERRA -35.32 149.00
25
+ CGK21 CAMPO GRANDE -20.50 -55.00
26
+ CH833 CHERRY 32.90 -106.41
27
+ CL424 CHUNG-LI 25.00 121.20
28
+ CN53L CAMDEN -34.05 150.67
29
+ CO764 COLLEGE AK 64.90 -148.00
30
+ CS31K COCOS_ISLAND -12.18 96.83
31
+ CS839 COLORADO_SPRINGS 39.00 -104.88
32
+ CXM9B CACHIMBO -9.50 -54.80
33
+ DB049 DOURBES 50.10 4.60
34
+ DH224 AL DHAFRA AFB 24.24 54.58
35
+ DS932 DYESS AFB 32.40 -99.80
36
+ DW41K DARWIN -12.45 130.95
37
+ EA036 EL ARENOSILLO 37.10 -6.70
38
+ EA653 EARECKSON 52.73 -174.08
39
+ EB040 ROQUETES 40.80 0.50
40
+ EG931 EGLIN AFB 30.50 -86.50
41
+ EI764 EIELSON 64.66 -147.07
42
+ FF051 FAIRFORD 51.70 -1.50
43
+ FZA0M FORTALEZA -3.90 -38.40
44
+ GA313 GADANKI 13.46 79.17
45
+ GA762 GAKONA 62.38 -145.00
46
+ GM037 GIBILMANNA 37.90 14.00
47
+ GR13L GRAHAMSTOWN -33.30 26.50
48
+ GSJ53 GOOSE BAY 53.30 -60.30
49
+ GU513 GUAM 13.62 144.86
50
+ HA419 HAINAN 19.40 109.00
51
+ HAJ43 HANSCOM AFB 42.50 -71.30
52
+ HE13N HERMANUS -34.42 19.22
53
+ HO54K HOBART -42.92 147.32
54
+ IC437 I-CHEON 37.14 127.54
55
+ IF843 IDAHO NATIONAL LAB 43.81 -112.68
56
+ IL008 ILORIN 8.50 4.50
57
+ IR352 IRKUTSK 52.40 104.30
58
+ JB57N JANG BOGO -74.62 164.24
59
+ JI91J JICAMARCA -12.00 -76.80
60
+ JJ433 JEJU 33.43 126.30
61
+ JR055 JULIUSRUH 54.60 13.40
62
+ KB547 KHABAROVSK 47.52 134.77
63
+ KI167 KIRUNA SWEDEN 67.86 20.43
64
+ KI939 KENT IS 38.96 -76.28
65
+ KJ609 KWAJALEIN 9.00 167.20
66
+ KL154 KALININGRAD 54.36 20.12
67
+ KR835 KIRTLAND 35.00 -106.53
68
+ KS759 KING SALMON 58.40 -156.40
69
+ LA42Q LAVERTON -28.30 122.80
70
+ LAA38 LAJES TERCEIRA ISLAND 38.77 -27.09
71
+ LD160 ST. PETERSBURG 60.00 30.70
72
+ LL721 LUALUALEI 21.43 -158.15
73
+ LM42B LEARMONTH -21.80 114.10
74
+ LV12P LOUISVALE -28.50 21.20
75
+ MA155 MOSCOW 55.49 37.29
76
+ MA560 MAGADAN 60.09 150.93
77
+ ME929 MELROSE 29.71 -82.00
78
+ MH453 MOHE 52.00 122.52
79
+ MHJ45 MILLSTONE HILL 42.60 -71.50
80
+ MI540 MISAWA 40.71 141.38
81
+ ML10L MALINDI -3.10 40.70
82
+ MO155 MOSCOW 55.47 37.30
83
+ MO156 ELEKTROUGLI 55.76 38.28
84
+ MU12K MADIMBO -22.39 30.88
85
+ MU230 MULTAN 33.03 72.01
86
+ MU834 MUNYO 33.56 -106.65
87
+ MZ152 WARSAW 52.20 21.10
88
+ ND61R NIUE -19.07 -169.93
89
+ NDA81 NORD GREENLAND 81.40 -17.50
90
+ NI135 NICOSIA 35.03 33.16
91
+ NO369 NORILSK 69.20 88.00
92
+ NQJ61 NARSSARSSUAQ 61.20 -45.40
93
+ NV355 NOVOSIBIRSK 55.02 82.21
94
+ OK426 OKINAWA 26.68 128.15
95
+ OL246 OLSZTYN 53.80 20.50
96
+ PA836 PT ARGUELLO 34.80 -120.50
97
+ PE43K PERTH -32.00 116.13
98
+ PF765 POKER FLAT 65.13 -147.45
99
+ PK553 PETROPAVLOVSK 52.97 158.24
100
+ PQ052 PRUHONICE 50.00 14.60
101
+ PRJ18 RAMEY 18.50 -67.10
102
+ PSJ5J PORT STANLEY -51.60 -57.90
103
+ RL052 CHILTON 51.50 -0.60
104
+ RM041 ROME 41.80 12.50
105
+ RO041 ROME 41.90 12.50
106
+ RV149 ROSTOV 47.24 39.63
107
+ SA418 SANYA 18.34 109.42
108
+ SAA0K SAOLUIS -2.60 -44.20
109
+ SH266 SALEKHARD 66.51 66.66
110
+ SJJ18 PUERTO RICO 18.11 -66.25
111
+ SMJ67 SONDRESTROM 66.98 -50.94
112
+ SMK29 SANTA MARIA -29.73 -53.71
113
+ SN437 OSAN AB 37.10 127.00
114
+ SO148 SOPRON 47.63 16.72
115
+ SQ832 SQUIRT 32.42 -106.29
116
+ THJ76 THULE 76.54 -68.44
117
+ THJ77 THULE/QAANAAQ 77.50 -69.20
118
+ TM308 TRIVANDRUM 8.54 76.87
119
+ TNJ20 TUCUMAN AIS-INGV -26.90 -65.40
120
+ TO535 KOKUBUNJI 35.70 139.50
121
+ TR0P2 TROLL -72.01 2.53
122
+ TR169 TROMSO 69.60 19.20
123
+ TR170 EISCAT TROMSO 69.58 19.22
124
+ TUJ2O TUCUMAN -26.90 -65.40
125
+ TV51R TOWNSVILLE -19.63 146.85
126
+ TZ362 TUNGUSKA 61.58 90.02
127
+ VT139 SAN VITO 40.60 17.80
128
+ WA619 WAKE 19.29 166.65
129
+ WI937 WALLOPS ISLAND 37.94 -75.58
130
+ WP937 WALLOPS IS 37.90 -75.50
131
+ WU430 WUHAN 30.50 114.40
132
+ XI434 XINXIANG CHINA 35.30 113.92
133
+ YA462 YAKUTSK 62.00 129.60
134
+ ZH466 ZHIGANSK 66.80 123.40
135
+ ZS36R ZHONG SHAN -69.40 76.40