hamsci-dsp 0.10.1__tar.gz

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 (135) hide show
  1. hamsci_dsp-0.10.1/LICENSE +21 -0
  2. hamsci_dsp-0.10.1/PKG-INFO +125 -0
  3. hamsci_dsp-0.10.1/README.md +103 -0
  4. hamsci_dsp-0.10.1/pyproject.toml +58 -0
  5. hamsci_dsp-0.10.1/setup.cfg +4 -0
  6. hamsci_dsp-0.10.1/src/hamsci_dsp/__init__.py +20 -0
  7. hamsci_dsp-0.10.1/src/hamsci_dsp/chirp/__init__.py +1 -0
  8. hamsci_dsp-0.10.1/src/hamsci_dsp/chirp/clean.py +143 -0
  9. hamsci_dsp-0.10.1/src/hamsci_dsp/chirp/screen.py +81 -0
  10. hamsci_dsp-0.10.1/src/hamsci_dsp/chirp/waveform.py +127 -0
  11. hamsci_dsp-0.10.1/src/hamsci_dsp/constants.py +22 -0
  12. hamsci_dsp-0.10.1/src/hamsci_dsp/counter_map.py +132 -0
  13. hamsci_dsp-0.10.1/src/hamsci_dsp/data/giro_stations.tsv +135 -0
  14. hamsci_dsp-0.10.1/src/hamsci_dsp/data_product_registry.py +630 -0
  15. hamsci_dsp-0.10.1/src/hamsci_dsp/dsp.py +183 -0
  16. hamsci_dsp-0.10.1/src/hamsci_dsp/geometry.py +242 -0
  17. hamsci_dsp-0.10.1/src/hamsci_dsp/io/__init__.py +32 -0
  18. hamsci_dsp-0.10.1/src/hamsci_dsp/io/authority_snapshot_store.py +386 -0
  19. hamsci_dsp-0.10.1/src/hamsci_dsp/io/calibration_file.py +284 -0
  20. hamsci_dsp-0.10.1/src/hamsci_dsp/io/dual_writer.py +61 -0
  21. hamsci_dsp-0.10.1/src/hamsci_dsp/io/sqlite_reader.py +353 -0
  22. hamsci_dsp-0.10.1/src/hamsci_dsp/io/sqlite_writer.py +589 -0
  23. hamsci_dsp-0.10.1/src/hamsci_dsp/io/uncertainty.py +253 -0
  24. hamsci_dsp-0.10.1/src/hamsci_dsp/ionosphere/__init__.py +5 -0
  25. hamsci_dsp-0.10.1/src/hamsci_dsp/ionosphere/data_service.py +1739 -0
  26. hamsci_dsp-0.10.1/src/hamsci_dsp/ionosphere/ionex.py +279 -0
  27. hamsci_dsp-0.10.1/src/hamsci_dsp/ionosphere/model.py +1562 -0
  28. hamsci_dsp-0.10.1/src/hamsci_dsp/ionosphere/solar.py +84 -0
  29. hamsci_dsp-0.10.1/src/hamsci_dsp/ionosphere/space_weather.py +371 -0
  30. hamsci_dsp-0.10.1/src/hamsci_dsp/ionosphere/tomography.py +488 -0
  31. hamsci_dsp-0.10.1/src/hamsci_dsp/propagation/__init__.py +37 -0
  32. hamsci_dsp-0.10.1/src/hamsci_dsp/propagation/arrival_matrix.py +1521 -0
  33. hamsci_dsp-0.10.1/src/hamsci_dsp/propagation/carrier.py +94 -0
  34. hamsci_dsp-0.10.1/src/hamsci_dsp/propagation/carrier_tec.py +453 -0
  35. hamsci_dsp-0.10.1/src/hamsci_dsp/propagation/engine.py +228 -0
  36. hamsci_dsp-0.10.1/src/hamsci_dsp/propagation/mode_solver.py +1262 -0
  37. hamsci_dsp-0.10.1/src/hamsci_dsp/propagation/model.py +1295 -0
  38. hamsci_dsp-0.10.1/src/hamsci_dsp/propagation/oblique.py +139 -0
  39. hamsci_dsp-0.10.1/src/hamsci_dsp/propagation/scintillation.py +654 -0
  40. hamsci_dsp-0.10.1/src/hamsci_dsp/propagation/tec_estimator.py +404 -0
  41. hamsci_dsp-0.10.1/src/hamsci_dsp/propagation/tec_geometry.py +98 -0
  42. hamsci_dsp-0.10.1/src/hamsci_dsp/propagation/tec_validator.py +338 -0
  43. hamsci_dsp-0.10.1/src/hamsci_dsp/propagation/transmission_time.py +1680 -0
  44. hamsci_dsp-0.10.1/src/hamsci_dsp/propagation/vtec.py +637 -0
  45. hamsci_dsp-0.10.1/src/hamsci_dsp/raytrace.py +741 -0
  46. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/__init__.py +170 -0
  47. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/calibration_v1.json +147 -0
  48. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/data_dictionary.json +370 -0
  49. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/diag_chrony_stats_v1.json +125 -0
  50. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l1_all_arrivals_v1.json +122 -0
  51. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l1_bcd_timecode_v1.json +79 -0
  52. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l1_broadcast_measurements_v1.json +407 -0
  53. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l1_channel_observables_v1.json +237 -0
  54. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l1_metrology_measurements_v1.json +143 -0
  55. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l1_tone_detections_v1.json +229 -0
  56. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l2_decoder_comparison_v1.json +165 -0
  57. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l2_detection_attempts_v1.json +127 -0
  58. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l2_physics_v1.json +87 -0
  59. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l2_test_signal_v1.json +447 -0
  60. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l2_tick_phase_v1.json +135 -0
  61. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l2_tick_timing_v1.json +135 -0
  62. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l2_timing_measurements_v1.json +387 -0
  63. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l3_dtec_diff_v1.json +80 -0
  64. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l3_dtec_timeseries_v1.json +101 -0
  65. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l3_dtec_v1.json +136 -0
  66. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l3_fusion_timing_v1.json +400 -0
  67. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l3_gnss_vtec_v1.json +143 -0
  68. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l3_physics_v1.json +91 -0
  69. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l3_tec_v1.json +150 -0
  70. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l3_tid_v1.json +134 -0
  71. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l3b_absorption_v1.json +146 -0
  72. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l3b_iono_events_v1.json +151 -0
  73. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/l3c_propagation_stats_v1.json +181 -0
  74. hamsci_dsp-0.10.1/src/hamsci_dsp/schemas/registry.json +115 -0
  75. hamsci_dsp-0.10.1/src/hamsci_dsp/sigmondb_rows.py +167 -0
  76. hamsci_dsp-0.10.1/src/hamsci_dsp/stability.py +310 -0
  77. hamsci_dsp-0.10.1/src/hamsci_dsp/stations.py +153 -0
  78. hamsci_dsp-0.10.1/src/hamsci_dsp/t6_anchor.py +96 -0
  79. hamsci_dsp-0.10.1/src/hamsci_dsp/timing.py +558 -0
  80. hamsci_dsp-0.10.1/src/hamsci_dsp/timing_map.py +433 -0
  81. hamsci_dsp-0.10.1/src/hamsci_dsp.egg-info/PKG-INFO +125 -0
  82. hamsci_dsp-0.10.1/src/hamsci_dsp.egg-info/SOURCES.txt +133 -0
  83. hamsci_dsp-0.10.1/src/hamsci_dsp.egg-info/dependency_links.txt +1 -0
  84. hamsci_dsp-0.10.1/src/hamsci_dsp.egg-info/requires.txt +12 -0
  85. hamsci_dsp-0.10.1/src/hamsci_dsp.egg-info/top_level.txt +1 -0
  86. hamsci_dsp-0.10.1/tests/test_arrival_matrix_remediation.py +257 -0
  87. hamsci_dsp-0.10.1/tests/test_authority_reader_wspr_parity.py +191 -0
  88. hamsci_dsp-0.10.1/tests/test_authority_snapshot_store.py +574 -0
  89. hamsci_dsp-0.10.1/tests/test_carrier_tec_quality.py +253 -0
  90. hamsci_dsp-0.10.1/tests/test_chirp_clean.py +76 -0
  91. hamsci_dsp-0.10.1/tests/test_chirp_screen.py +111 -0
  92. hamsci_dsp-0.10.1/tests/test_chirp_waveform.py +43 -0
  93. hamsci_dsp-0.10.1/tests/test_counter_map.py +109 -0
  94. hamsci_dsp-0.10.1/tests/test_dsp.py +80 -0
  95. hamsci_dsp-0.10.1/tests/test_geometry.py +89 -0
  96. hamsci_dsp-0.10.1/tests/test_import_lint.py +33 -0
  97. hamsci_dsp-0.10.1/tests/test_iono_data_service.py +271 -0
  98. hamsci_dsp-0.10.1/tests/test_iono_tomography_split.py +140 -0
  99. hamsci_dsp-0.10.1/tests/test_ionosphere_ionex.py +67 -0
  100. hamsci_dsp-0.10.1/tests/test_ionosphere_model_ionex_cache.py +58 -0
  101. hamsci_dsp-0.10.1/tests/test_ionosphere_raytrace.py +55 -0
  102. hamsci_dsp-0.10.1/tests/test_ionosphere_space_weather.py +94 -0
  103. hamsci_dsp-0.10.1/tests/test_ionospheric_hmf2_solar.py +47 -0
  104. hamsci_dsp-0.10.1/tests/test_ionospheric_ionex_selection.py +66 -0
  105. hamsci_dsp-0.10.1/tests/test_ionospheric_ionogram_calibration.py +58 -0
  106. hamsci_dsp-0.10.1/tests/test_ionospheric_iri_cache.py +109 -0
  107. hamsci_dsp-0.10.1/tests/test_leap_second_notice_field.py +32 -0
  108. hamsci_dsp-0.10.1/tests/test_mode_solver_remediation.py +357 -0
  109. hamsci_dsp-0.10.1/tests/test_propagation.py +109 -0
  110. hamsci_dsp-0.10.1/tests/test_propagation_engine.py +51 -0
  111. hamsci_dsp-0.10.1/tests/test_propagation_group_delay_bound.py +127 -0
  112. hamsci_dsp-0.10.1/tests/test_propagation_model.py +535 -0
  113. hamsci_dsp-0.10.1/tests/test_propagation_uncertainty_sigma.py +80 -0
  114. hamsci_dsp-0.10.1/tests/test_raytrace_deferral.py +51 -0
  115. hamsci_dsp-0.10.1/tests/test_raytrace_interp.py +92 -0
  116. hamsci_dsp-0.10.1/tests/test_raytrace_perhop.py +80 -0
  117. hamsci_dsp-0.10.1/tests/test_raytrace_timeout.py +72 -0
  118. hamsci_dsp-0.10.1/tests/test_retired_stations_cost_nothing.py +89 -0
  119. hamsci_dsp-0.10.1/tests/test_schemas.py +140 -0
  120. hamsci_dsp-0.10.1/tests/test_scintillation_conventions.py +118 -0
  121. hamsci_dsp-0.10.1/tests/test_sigmondb_rows.py +123 -0
  122. hamsci_dsp-0.10.1/tests/test_sporadic_e_detection.py +310 -0
  123. hamsci_dsp-0.10.1/tests/test_sqlite_reader.py +486 -0
  124. hamsci_dsp-0.10.1/tests/test_sqlite_writer.py +800 -0
  125. hamsci_dsp-0.10.1/tests/test_stability.py +242 -0
  126. hamsci_dsp-0.10.1/tests/test_station_antennas.py +141 -0
  127. hamsci_dsp-0.10.1/tests/test_stations.py +107 -0
  128. hamsci_dsp-0.10.1/tests/test_t6_anchor.py +84 -0
  129. hamsci_dsp-0.10.1/tests/test_tec_estimator_confidence.py +140 -0
  130. hamsci_dsp-0.10.1/tests/test_tec_geometry.py +273 -0
  131. hamsci_dsp-0.10.1/tests/test_tec_validator.py +405 -0
  132. hamsci_dsp-0.10.1/tests/test_timing.py +510 -0
  133. hamsci_dsp-0.10.1/tests/test_timing_map.py +303 -0
  134. hamsci_dsp-0.10.1/tests/test_uncertainty.py +199 -0
  135. hamsci_dsp-0.10.1/tests/test_vtec_mapper.py +141 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Michael James Hauan
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,125 @@
1
+ Metadata-Version: 2.4
2
+ Name: hamsci-dsp
3
+ Version: 0.10.1
4
+ Summary: Shared DSP / timing utilities for the HamSCI sigmond suite
5
+ Author-email: Michael Hauan <mjh@hauan.org>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/HamSCI/hamsci-dsp
8
+ Project-URL: Bug Tracker, https://github.com/HamSCI/hamsci-dsp/issues
9
+ Requires-Python: >=3.10
10
+ Description-Content-Type: text/markdown
11
+ License-File: LICENSE
12
+ Requires-Dist: numpy>=1.24.0
13
+ Requires-Dist: geographiclib>=2.0
14
+ Provides-Extra: dev
15
+ Requires-Dist: pytest>=7.0; extra == "dev"
16
+ Requires-Dist: scipy>=1.10; extra == "dev"
17
+ Provides-Extra: tomography
18
+ Requires-Dist: scipy>=1.10; extra == "tomography"
19
+ Provides-Extra: iono
20
+ Requires-Dist: iri2020>=1.7; extra == "iono"
21
+ Dynamic: license-file
22
+
23
+ # hamsci-dsp
24
+
25
+ Signal-processing, geometry and timing code for HF radio science, shared by
26
+ the programs of the [HamSCI](https://hamsci.org/) **sigmond** station suite.
27
+ Each function here once lived as a copy inside several of those programs; this
28
+ library keeps one tested version of each.
29
+
30
+ It provides a library only: no command line, no service, no daemon.
31
+
32
+ ## Install
33
+
34
+ ```bash
35
+ pip install hamsci-dsp
36
+ ```
37
+
38
+ The core needs only numpy and geographiclib. Heavier engines wait behind
39
+ extras:
40
+
41
+ | Extra | Adds | For |
42
+ |-------|------|-----|
43
+ | `iono` | `iri2020` (builds with gfortran) | the IRI ionosphere model in `hamsci_dsp.ionosphere` |
44
+ | `tomography` | `scipy` | E/F-layer tomography in `hamsci_dsp.ionosphere.tomography` |
45
+
46
+ ```bash
47
+ pip install 'hamsci-dsp[iono,tomography]'
48
+ ```
49
+
50
+ Ray tracing has no extra. `hamsci_dsp.raytrace` uses HamSCI's PyLAP and the
51
+ PHaRLAP ray tracer when you have installed them yourself (PHaRLAP carries its
52
+ own licence and download), and does nothing otherwise.
53
+
54
+ ## A first example
55
+
56
+ ```python
57
+ from hamsci_dsp.geometry import grid_to_latlon, great_circle_km, latlon_to_grid
58
+
59
+ tx = grid_to_latlon("EN50") # (40.5, -89.0), the centre of the square
60
+ rx = grid_to_latlon("FN42hn") # (42.5625, -71.375)
61
+ print(round(great_circle_km(*tx, *rx), 1)) # 1485.8
62
+ print(latlon_to_grid(*rx)) # FN42hn
63
+ ```
64
+
65
+ ## What it holds
66
+
67
+ **Geometry, signals and propagation**
68
+
69
+ | Module | Provides | Needs |
70
+ |--------|----------|-------|
71
+ | `hamsci_dsp.constants` | `C_M_S`, `K_TEC = 40.3`, `R_EARTH_KM`, `TECU` | stdlib |
72
+ | `hamsci_dsp.geometry` | great-circle distance, bearing, midpoint and destination (geographiclib); reflection geometry (elevation, hops, height from path); Maidenhead grid to and from latitude and longitude | geographiclib |
73
+ | `hamsci_dsp.dsp` | peak SNR (Rayleigh and signed), robust noise floor, `CoherentStack` for slow-time range-Doppler, carrier to Doppler, FFT correlation | numpy |
74
+ | `hamsci_dsp.propagation` | path observables: `carrier` (phase to dTEC and its rate), `oblique` (virtual height, equivalent vertical frequency, MUF, obliquity), `scintillation` (S4 and σφ after ITU-R P.531) | numpy |
75
+ | `hamsci_dsp.chirp` | chirp-sounder waveform, screening and cleaning, shared by chirp-recorder and its tools | numpy |
76
+ | `hamsci_dsp.stability` | Allan deviation and related stability measures | numpy |
77
+
78
+ **The ionosphere**
79
+
80
+ | Module | Provides | Needs |
81
+ |--------|----------|-------|
82
+ | `hamsci_dsp.ionosphere` | solar position and zenith angle (no dependencies); `ionosphere_state`, which uses IRI when installed and a parametric model otherwise | numpy; `iono` for IRI |
83
+ | `hamsci_dsp.ionosphere.ionex` | a reader for IGS Global Ionosphere Map (IONEX) files | numpy |
84
+ | `hamsci_dsp.ionosphere.space_weather` | near-real-time solar and geomagnetic indices; the caller supplies the download | stdlib |
85
+ | `hamsci_dsp.ionosphere.data_service` | WAM-IPE and GIRO ionosonde data, with a bundled GIRO station table | numpy; `requests`, `xarray` if present |
86
+ | `hamsci_dsp.ionosphere.tomography` | E- and F-layer TEC separated from many HF ray paths | `tomography` |
87
+ | `hamsci_dsp.raytrace` | `RaytraceEngine`, a wrapper for PyLAP and PHaRLAP that does nothing when they are absent | PyLAP, PHaRLAP (yours) |
88
+
89
+ **Timing and the sigmond suite's shared formats**
90
+
91
+ | Module | Provides | Needs |
92
+ |--------|----------|-------|
93
+ | `hamsci_dsp.timing` | `AuthorityReader` and `AuthoritySnapshot` for hf-timestd's `authority.json`; `acquire_anchor_utc`, the one RTP-to-UTC anchor every recorder shares; the timing-authority report clients publish | stdlib |
94
+ | `hamsci_dsp.timing_map` | `TimeMap`, the runtime form of the suite's measurement model (schema v2) | stdlib |
95
+ | `hamsci_dsp.counter_map` | `CounterMap`, which maps one channel's RTP counter to the radio's input-sample index | stdlib |
96
+ | `hamsci_dsp.t6_anchor` | reads hf-timestd's T6 anchor file and projects input-sample indices to UTC nanoseconds, with the tie's measured error | stdlib |
97
+ | `hamsci_dsp.stations` | a fixed catalogue of HF time-signal stations | stdlib |
98
+ | `hamsci_dsp.io` | the schema-driven SQLite writer and reader behind hf-timestd's data store | numpy |
99
+ | `hamsci_dsp.sigmondb_rows` | the sigmondb chirp row (`arrival` and `capture`) that codar-sounder writes | stdlib |
100
+ | `hamsci_dsp.data_product_registry` | the suite's data-product schemas (L1 to L3), bundled with the package | stdlib |
101
+
102
+ ## Versions
103
+
104
+ Versions follow `MAJOR.MINOR.PATCH`. While the major number stays 0, a minor
105
+ release may change an interface; each sigmond release pins the exact version it
106
+ tested. The [commit history](https://github.com/HamSCI/hamsci-dsp/commits/main)
107
+ lists every change.
108
+
109
+ ## Developing
110
+
111
+ ```bash
112
+ git clone https://github.com/HamSCI/hamsci-dsp
113
+ cd hamsci-dsp
114
+ uv sync --extra dev
115
+ uv run pytest
116
+ ```
117
+
118
+ A version tag (`vX.Y.Z`) publishes to PyPI through GitHub Actions, after the
119
+ tests pass against the built wheel. Notes for the suite's own programs, which
120
+ develop against a sibling checkout, sit in [docs/CONSUMERS.md](https://github.com/HamSCI/hamsci-dsp/blob/main/docs/CONSUMERS.md).
121
+
122
+ ## Licence and authors
123
+
124
+ MIT. Michael Hauan (AC0G), for [HamSCI](https://hamsci.org/).
125
+ Source: https://github.com/HamSCI/hamsci-dsp
@@ -0,0 +1,103 @@
1
+ # hamsci-dsp
2
+
3
+ Signal-processing, geometry and timing code for HF radio science, shared by
4
+ the programs of the [HamSCI](https://hamsci.org/) **sigmond** station suite.
5
+ Each function here once lived as a copy inside several of those programs; this
6
+ library keeps one tested version of each.
7
+
8
+ It provides a library only: no command line, no service, no daemon.
9
+
10
+ ## Install
11
+
12
+ ```bash
13
+ pip install hamsci-dsp
14
+ ```
15
+
16
+ The core needs only numpy and geographiclib. Heavier engines wait behind
17
+ extras:
18
+
19
+ | Extra | Adds | For |
20
+ |-------|------|-----|
21
+ | `iono` | `iri2020` (builds with gfortran) | the IRI ionosphere model in `hamsci_dsp.ionosphere` |
22
+ | `tomography` | `scipy` | E/F-layer tomography in `hamsci_dsp.ionosphere.tomography` |
23
+
24
+ ```bash
25
+ pip install 'hamsci-dsp[iono,tomography]'
26
+ ```
27
+
28
+ Ray tracing has no extra. `hamsci_dsp.raytrace` uses HamSCI's PyLAP and the
29
+ PHaRLAP ray tracer when you have installed them yourself (PHaRLAP carries its
30
+ own licence and download), and does nothing otherwise.
31
+
32
+ ## A first example
33
+
34
+ ```python
35
+ from hamsci_dsp.geometry import grid_to_latlon, great_circle_km, latlon_to_grid
36
+
37
+ tx = grid_to_latlon("EN50") # (40.5, -89.0), the centre of the square
38
+ rx = grid_to_latlon("FN42hn") # (42.5625, -71.375)
39
+ print(round(great_circle_km(*tx, *rx), 1)) # 1485.8
40
+ print(latlon_to_grid(*rx)) # FN42hn
41
+ ```
42
+
43
+ ## What it holds
44
+
45
+ **Geometry, signals and propagation**
46
+
47
+ | Module | Provides | Needs |
48
+ |--------|----------|-------|
49
+ | `hamsci_dsp.constants` | `C_M_S`, `K_TEC = 40.3`, `R_EARTH_KM`, `TECU` | stdlib |
50
+ | `hamsci_dsp.geometry` | great-circle distance, bearing, midpoint and destination (geographiclib); reflection geometry (elevation, hops, height from path); Maidenhead grid to and from latitude and longitude | geographiclib |
51
+ | `hamsci_dsp.dsp` | peak SNR (Rayleigh and signed), robust noise floor, `CoherentStack` for slow-time range-Doppler, carrier to Doppler, FFT correlation | numpy |
52
+ | `hamsci_dsp.propagation` | path observables: `carrier` (phase to dTEC and its rate), `oblique` (virtual height, equivalent vertical frequency, MUF, obliquity), `scintillation` (S4 and σφ after ITU-R P.531) | numpy |
53
+ | `hamsci_dsp.chirp` | chirp-sounder waveform, screening and cleaning, shared by chirp-recorder and its tools | numpy |
54
+ | `hamsci_dsp.stability` | Allan deviation and related stability measures | numpy |
55
+
56
+ **The ionosphere**
57
+
58
+ | Module | Provides | Needs |
59
+ |--------|----------|-------|
60
+ | `hamsci_dsp.ionosphere` | solar position and zenith angle (no dependencies); `ionosphere_state`, which uses IRI when installed and a parametric model otherwise | numpy; `iono` for IRI |
61
+ | `hamsci_dsp.ionosphere.ionex` | a reader for IGS Global Ionosphere Map (IONEX) files | numpy |
62
+ | `hamsci_dsp.ionosphere.space_weather` | near-real-time solar and geomagnetic indices; the caller supplies the download | stdlib |
63
+ | `hamsci_dsp.ionosphere.data_service` | WAM-IPE and GIRO ionosonde data, with a bundled GIRO station table | numpy; `requests`, `xarray` if present |
64
+ | `hamsci_dsp.ionosphere.tomography` | E- and F-layer TEC separated from many HF ray paths | `tomography` |
65
+ | `hamsci_dsp.raytrace` | `RaytraceEngine`, a wrapper for PyLAP and PHaRLAP that does nothing when they are absent | PyLAP, PHaRLAP (yours) |
66
+
67
+ **Timing and the sigmond suite's shared formats**
68
+
69
+ | Module | Provides | Needs |
70
+ |--------|----------|-------|
71
+ | `hamsci_dsp.timing` | `AuthorityReader` and `AuthoritySnapshot` for hf-timestd's `authority.json`; `acquire_anchor_utc`, the one RTP-to-UTC anchor every recorder shares; the timing-authority report clients publish | stdlib |
72
+ | `hamsci_dsp.timing_map` | `TimeMap`, the runtime form of the suite's measurement model (schema v2) | stdlib |
73
+ | `hamsci_dsp.counter_map` | `CounterMap`, which maps one channel's RTP counter to the radio's input-sample index | stdlib |
74
+ | `hamsci_dsp.t6_anchor` | reads hf-timestd's T6 anchor file and projects input-sample indices to UTC nanoseconds, with the tie's measured error | stdlib |
75
+ | `hamsci_dsp.stations` | a fixed catalogue of HF time-signal stations | stdlib |
76
+ | `hamsci_dsp.io` | the schema-driven SQLite writer and reader behind hf-timestd's data store | numpy |
77
+ | `hamsci_dsp.sigmondb_rows` | the sigmondb chirp row (`arrival` and `capture`) that codar-sounder writes | stdlib |
78
+ | `hamsci_dsp.data_product_registry` | the suite's data-product schemas (L1 to L3), bundled with the package | stdlib |
79
+
80
+ ## Versions
81
+
82
+ Versions follow `MAJOR.MINOR.PATCH`. While the major number stays 0, a minor
83
+ release may change an interface; each sigmond release pins the exact version it
84
+ tested. The [commit history](https://github.com/HamSCI/hamsci-dsp/commits/main)
85
+ lists every change.
86
+
87
+ ## Developing
88
+
89
+ ```bash
90
+ git clone https://github.com/HamSCI/hamsci-dsp
91
+ cd hamsci-dsp
92
+ uv sync --extra dev
93
+ uv run pytest
94
+ ```
95
+
96
+ A version tag (`vX.Y.Z`) publishes to PyPI through GitHub Actions, after the
97
+ tests pass against the built wheel. Notes for the suite's own programs, which
98
+ develop against a sibling checkout, sit in [docs/CONSUMERS.md](https://github.com/HamSCI/hamsci-dsp/blob/main/docs/CONSUMERS.md).
99
+
100
+ ## Licence and authors
101
+
102
+ MIT. Michael Hauan (AC0G), for [HamSCI](https://hamsci.org/).
103
+ Source: https://github.com/HamSCI/hamsci-dsp
@@ -0,0 +1,58 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "hamsci-dsp"
7
+ version = "0.10.1"
8
+ description = "Shared DSP / timing utilities for the HamSCI sigmond suite"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "MIT"
12
+ authors = [
13
+ {name = "Michael Hauan", email = "mjh@hauan.org"},
14
+ ]
15
+ # `hamsci_dsp.timing` is stdlib-only and importable without these; the
16
+ # numeric subpackages (geometry/dsp/propagation) need numpy + geographiclib,
17
+ # both light and universal across the suite. Heavy/optional scientific
18
+ # engines are gated behind extras below.
19
+ dependencies = [
20
+ "numpy>=1.24.0",
21
+ "geographiclib>=2.0",
22
+ ]
23
+
24
+ [project.urls]
25
+ Homepage = "https://github.com/HamSCI/hamsci-dsp"
26
+ "Bug Tracker" = "https://github.com/HamSCI/hamsci-dsp/issues"
27
+
28
+ [project.optional-dependencies]
29
+ dev = [
30
+ "pytest>=7.0",
31
+ "scipy>=1.10",
32
+ ]
33
+ # Ionospheric tomography (hamsci_dsp.ionosphere.tomography) imports scipy
34
+ # at module level.
35
+ tomography = [
36
+ "scipy>=1.10",
37
+ ]
38
+ # Ionospheric profile model (hamsci_dsp.ionosphere). Needs a Fortran build.
39
+ iono = [
40
+ "iri2020>=1.7",
41
+ ]
42
+ # HF ray tracing (hamsci_dsp.raytrace) wraps HamSCI's PyLAP/PHaRLAP, which
43
+ # stays out of the published extras: PHaRLAP is license-restricted and staged
44
+ # by the operator, and the PyPI name "pylap" belongs to an unrelated,
45
+ # unattributed upload. raytrace imports the PyLAP installed in the venv,
46
+ # and does nothing when none is (see README).
47
+
48
+ [tool.setuptools.packages.find]
49
+ where = ["src"]
50
+
51
+ [tool.setuptools.package-data]
52
+ # GIRO ionosonde fallback table for hamsci_dsp.ionosphere.data_service,
53
+ # and the L1/L2/L3 data-product schema registry (split §5.2 data layer).
54
+ hamsci_dsp = ["data/*.tsv", "schemas/*.json"]
55
+
56
+ [tool.pytest.ini_options]
57
+ testpaths = ["tests"]
58
+ markers = ["slow: multi-seed statistical tests, about 10 s or more"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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