rf-compute 0.1.0__tar.gz

rf_compute-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rf-compute contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rf_compute-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: rf-compute
+Version: 0.1.0
+Summary: Wave-domain computation kernel — one API across the four RF-as-compute lineages (metamaterials, AirComp, microwave photonics, spin-torque neuromorphic). Research and education surface.
+Author: rf-compute contributors
+License: MIT
+Project-URL: Homepage, https://github.com/LE-VAI/rf-compute
+Project-URL: Source, https://github.com/LE-VAI/rf-compute
+Project-URL: Issues, https://github.com/LE-VAI/rf-compute/issues
+Project-URL: Documentation, https://github.com/LE-VAI/rf-compute/blob/main/docs/field-map.md
+Project-URL: Bibliography, https://github.com/LE-VAI/rf-compute/blob/main/docs/bibliography.md
+Project-URL: Contributing, https://github.com/LE-VAI/rf-compute/blob/main/CONTRIBUTING.md
+Keywords: rf,radio-frequency,analog-computing,wave-computing,metamaterials,aircomp,over-the-air-computation,microwave-photonics,neuromorphic,spin-torque,sdr,software-defined-radio,research,education
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Provides-Extra: sdr
+Requires-Dist: SoapySDR>=0.8; extra == "sdr"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.5; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: matplotlib>=3.5; extra == "dev"
+Dynamic: license-file
+
+# rf-compute
+
+<!-- vai-hero:start -->
+<p align="center">
+  <picture>
+    <source media="(prefers-reduced-motion: reduce)" srcset="https://raw.githubusercontent.com/LE-VAI/rf-compute/main/docs/media/hero-poster.png">
+    <img src="https://raw.githubusercontent.com/LE-VAI/rf-compute/main/docs/media/hero-loop.webp" width="800" alt="Two carrier waves travel across the frame. Carrier A completes one cycle per loop and carrier B completes two. The bottom lane shows their sum, sampled as orange stems: the interference is the operation.">
+  </picture>
+</p>
+<p align="center"><sub>A 4-second loop. It plays once and rests, and shows a still frame if you prefer reduced motion. <a href="https://le-vai.github.io/LE-VAI/loops/#rf-compute">Watch it on repeat</a>.</sub></p>
+<!-- vai-hero:end -->
+
+**Radio Frequency as a computational substrate — not a transmission medium.**
+
+A research-and-education surface for wave-domain computation. The waveform is the operand. Interference isn't noise to cancel — it's the multiply-accumulate operation. The medium is the math.
+
+---
+
+## The one-sentence version
+
+> Instead of using RF to carry bits to a digital chip that does the math, you make the RF waveform *be* the math — interference performs the operation, the channel is the adder, the medium is the algorithm.
+
+This is not a new idea. It's been hiding in plain sight across four separate research communities for ~18 years. `rf-compute` is the bridge that makes it legible to builders.
+
+---
+
+## Why this exists
+
+There is no unified developer surface for RF-as-compute. The field is real, peer-reviewed, and active — but it's scattered across four communities that don't share vocabulary, tooling, or a "hello world":
+
+| Lineage | Where it publishes | What it does |
+|---|---|---|
+| **Computational metamaterials** | *Science*, *Nature* | Passive materials that perform math on wavefields |
+| **Over-the-air computation (AirComp)** | *IEEE Trans. Inf. Theory* | The wireless channel *is* the computation |
+| **Microwave photonics** | *Nature Photonics* | RF signals on optical carriers doing NN inference |
+| **Spin-torque neuromorphic** | *Nature Electronics* | Microwave nano-oscillators as neurons |
+
+They all share one thing: **the waveform is the operand.** Nobody has built the bridge between them. That's the gap this project fills.
+
+---
+
+## The $350 hello world
+
+You don't need a fab, a clean room, or a metamaterial. You need **two transmit SDRs, one receive SDR, and a laptop** — clone-tier hardware gets you there around $350; official units run ~$725. Either way, the simulation kernel runs free on NumPy alone.
+
+```
+Tx1 ──┐
+       ├── air ──→ Rx ──→ f(x1 + x2)  ← the channel computed the sum
+Tx2 ──┘
+```
+
+Two transmitters send pre-coded signals simultaneously. The receiver reads their sum from the superposed waveform — **without decoding either signal individually.** Interference is the operation. This is the Nazer & Gastpar 2007 result, made legible.
+
+This is the simplest wave-compute primitive that exists. If you can run this, you understand the field.
+
+📖 **Full walkthrough:** [`docs/hello-world-aircomp.md`](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-aircomp.md) — hardware, code, what to expect, troubleshooting
+
+**Budget option:** One HackRF + one RTL-SDR (clone-tier ~$190, official ~$380). You transmit x1, x2, and x1+x2 sequentially and compare captures in post-processing. You lose the simultaneity that makes AirComp profound, but you learn the signal-processing structure for half the cost. Details in the walkthrough.
+
+### Quick start (60 seconds, no hardware)
+
+```bash
+git clone https://github.com/LE-VAI/rf-compute.git
+cd rf-compute
+pip install -e .
+python examples/tier1_aircomp_kernel.py    # AirComp: 3+5=8
+python examples/tier1_5_lattice_aircomp_kernel.py  # exact lattice sums, $0
+python examples/tier1_6_fading_coefficients.py     # coefficient selection on fading, $0
+python examples/tier2_convolution_kernel.py # 4 operators
+python examples/tier3_inversion_kernel.py   # solves Ax=b
+python examples/tier4_ota_federated_learning.py  # federated learning over the air, $0
+```
+
+The simulation kernel runs the same API as the hardware kernel — switch `backend="sim"` to `backend="sdr"` when you have SDRs. See [`docs/INSTALL.md`](https://github.com/LE-VAI/rf-compute/blob/main/docs/INSTALL.md) for the SDR driver install (the one friction point when you're ready for hardware).
+
+---
+
+## The hello-world ladder
+
+Six reproducible experiments, escalating in cost. Each maps to a peer-reviewed result.
+
+| Tier | Experiment | Cost (clone-tier / official) | Proves | Citation |
+|---|---|---|---|---|
+| **1** | AirComp sum | ~$350 / ~$725 | Interference IS computation | Nazer & Gastpar, *IEEE TIT* (2011) |
+| **1.5** | Lattice-coded AirComp | free (sim) | The exact result: noise-resilient sums in one channel use, no message decoded | Nazer & Gastpar, *IEEE TIT* (2007/2011) |
+| **1.6** | Fading-channel coefficients | free (sim) | Coefficients are an optimization: the plain sum is undecodable on ~95% of fading channels; selection finds a decodable one | Nazer & Gastpar (2011); Sahraei & Gastpar (2014); Liu & Ling, *IEEE TWC* (2016) |
+| **2** | Wave-domain convolution | ~$200 / ~$395 | Linear operators are native to wave physics | Silva et al., *Science* (2014) |
+| **3** | Matrix inversion via feedback | free / ~$200 / ~$350 | The wave domain solves equations; settling, not iterating | Tzarouchis, Edwards & Engheta, *Nature Communications* (2025) |
+| **4** | Over-the-air federated learning | free (sim) | The channel aggregates model updates in `d+1` uses however many devices transmit; a shared pilot rescues training from misalignment, and heterogeneity bounds the rescue | Zhu, Wang & Huang, *IEEE TWC* (2020); Shao, Gündüz & Liew, *IEEE TWC* (2022) |
+
+Tier 3 has three modes (simulation free, software-in-the-loop ~$200 clone / ~$395 official, analog feedback ~$350 clone / ~$480 official) — see the walkthrough for the trade-off.
+
+📖 **Full ladder walkthroughs:** [Tier 1](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-aircomp.md) · [Tier 1.5](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-lattice-aircomp.md) · [Tier 1.6](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-fading-coefficients.md) · [Tier 2](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-convolution.md) · [Tier 3](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-matrix-inversion.md) · [Tier 4](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-ota-federated-learning.md) — each with parts lists, code, and troubleshooting
+
+---
+
+## What this is NOT
+
+This is a **research and education surface**, not a product. We build the map, the vocabulary, and the reproducible "hello world." The community builds the future.
+
+We are explicitly **not** building:
+
+- ❌ Deep-learning-scale matrices (SOTA is 5×5; NN layers are 1024×1024 — that's a hardware physics problem)
+- ❌ Phone-form-factor integration (45 MHz ≈ 6.7m wavelength — subwavelength resonator design at phone scale is unsolved)
+- ❌ Noise-resilient analog compute for hostile EM environments (lab results won't hold in a pocket)
+- ❌ 6G standards integration (AirComp is a 6G research candidate, not yet in 3GPP standardization; that's a multi-year institutional process)
+- ❌ Commercial fabrication (Lightmatter is pursuing the optical frontier; pure-RF commercial compute is not this project)
+
+These are real, important problems. They belong to the metamaterials physics community, the antenna engineers, the RF circuit designers, the standards bodies, and industry — not to a research-and-education surface. We name them clearly so builders know where the open frontier lives.
+
+📖 **Full deferral table:** [`docs/field-map.md`](https://github.com/LE-VAI/rf-compute/blob/main/docs/field-map.md#what-we-are-not-building-graceful-deferral-to-the-community)
+
+---
+
+## The field map
+
+The complete lineage-to-primitive map lives in [`docs/field-map.md`](https://github.com/LE-VAI/rf-compute/blob/main/docs/field-map.md). It covers:
+
+- Each of the four lineages with origin papers, SOTA devices, key labs, and SDR-mappable primitives
+- The SDR bridge: why software-defined radio is the unified developer surface
+- The "hello world" ladder with cost estimates and parts lists
+- Field maturity at a glance
+- Full provenance and citation list
+
+If you read one document, read the field map.
+
+---
+
+## Hardware you'll need
+
+Prices verified 2026-08-31, re-checked 2026-09-30. HackRF One official retail is ~$340 (SparkFun/Adafruit have retired the unit; GSG's successor **HackRF Pro** is ~$400). AliExpress clones run ~$100–150 but degrade above 1 GHz per Great Scott Gadgets' own clone test — fine for sub-GHz learning experiments, not for precision work. RTL-SDR Blog V4 is end-of-line (May 2026); current official units are the V3 or V4L at ~$35–40 (the V4L is itself a limited edition with roughly a year of chip stock).
+
+| Item | Tier 1 | Tier 2 | Tier 3 (Mode B/C) | Official | Clone-tier |
+|---|:---:|:---:|:---:|---|---|
+| HackRF One SDR (Tx) | ×2 | ×1 | ×1 | ~$340 each | ~$100–150 each |
+| RTL-SDR (Rx, receive-only) | ×1 | ×1 | ×1 | ~$35–40 | ~$30 |
+| 10 MHz clock sync cable (BNC/SMA) | ✓ | | | ~$5 | — |
+| Laptop (any OS) | ✓ | ✓ | ✓ | you have one | — |
+| Passive scatterer / reflector | | ✓ (Mode B) | | ~$10–20 | DIY |
+| RF circulator (one-way loop) | | | ✓ (Mode C) | ~$40 | — |
+| Programmable attenuator (loop gain) | | | ✓ (Mode C) | ~$30 | — |
+| RF splitter/combiner | | | ✓ (Mode C) | ~$15–25 | — |
+
+**Total entry cost: free (Tier 3 sim) / clone-tier ~$200–350 / official ~$390–725 depending on tier.** No fab. No clean room. No metamaterial. Tier 3 Mode A is pure simulation and costs nothing — start there to see the math before buying hardware. If you buy clones, know what you're buying: they work for learning, they drift for precision.
+
+---
+
+## Who this is for
+
+- **Builders** who want to touch wave-domain compute without a physics PhD
+- **Researchers** who want a shared vocabulary across the four lineages
+- **Educators** who want reproducible experiments with real citations
+- **Curious engineers** who read "the channel is the adder" and want to see it work
+
+If you've never heard of RF-as-compute and want to understand it: start with the $350 hello world. If you're already in one of the four lineages: the field map is the bridge to the other three.
+
+---
+
+## The key papers (start here)
+
+| Paper | Year | Why it matters |
+|---|---|---|
+| Nazer & Gastpar, "Computation over multiple-access channels," *IEEE Trans. Inf. Theory* | 2007 | The founding result. Interference computes functions. |
+| Silva et al., "Performing mathematical operations with metamaterials," *Science* | 2014 | Passive materials do math on wavefields. |
+| Torrejon et al., "Neuromorphic computing with spintronic oscillators," *Nature* | 2017 | Microwave nano-oscillators as neurons. 99.6% spoken-digit. |
+| Zangeneh-Nejad et al., "Analogue computing with metamaterials," *Nature Reviews Materials* | 2021 | The canonical review. "Wave-based analog computing." |
+| Li et al., "Performing calculus with ENZ metamaterials," *Science Advances* | 2022 | Differentiation + integration in the material. |
+| Tzarouchis, Edwards & Engheta, "Programmable wave-based analog computing machine: a metastructure that designs metastructures," *Nature Communications* 16, 908 ([DOI](https://doi.org/10.1038/s41467-025-56019-1)) | 2025 | **The SOTA.** Matrix inversion, Newton's method, Lagrangian optimization at 45 MHz. |
+| Chegini, Guan & Yao, "Microwave photonic neural network," *J. Lightwave Technology* | 2025 | RF photonic MVM. 55×10⁶ MAC/s. |
+
+📖 **Annotated bibliography:** [`docs/bibliography.md`](https://github.com/LE-VAI/rf-compute/blob/main/docs/bibliography.md) — every citation, reading order, how to use it
+
+---
+
+## Status
+
+**Pre-release.** The spine is complete: field map, six-tier hello-world ladder, annotated bibliography, contribution guide, and the SDR kernel abstraction. The simulation kernel is fully reproducible (every run seed-deterministic; 116 tests).
+
+- ✅ [Field map](https://github.com/LE-VAI/rf-compute/blob/main/docs/field-map.md) — the spine document
+- ✅ [Tier 1: AirComp sum](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-aircomp.md) — the $350 hello world
+- ✅ [Tier 1.5: Lattice-coded AirComp](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-lattice-aircomp.md) — the $0 exact-computation primitive (nested-lattice kernel)
+- ✅ [Tier 1.6: Fading-channel coefficients](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-fading-coefficients.md) — the $0 coefficient-selection tier (computation-rate maximization, MMSE α, LLL + norm-bound search)
+- ✅ [Tier 2: Wave-domain convolution](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-convolution.md) — the $200 linear-operator primitive
+- ✅ [Tier 3: Matrix inversion via feedback](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-matrix-inversion.md) — the wave-domain capstone (free / $200 / $350)
+- ✅ [Tier 4: Over-the-air federated learning](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-ota-federated-learning.md) — the AirComp capstone ($0): aggregation over the air, misalignment, and a pilot-aided equalizer
+- ✅ [Annotated bibliography](https://github.com/LE-VAI/rf-compute/blob/main/docs/bibliography.md) — every citation, reading order, how to use it
+- ✅ [Installation guide](https://github.com/LE-VAI/rf-compute/blob/main/docs/INSTALL.md) — pip install, SDR drivers, troubleshooting
+- ✅ [Contributing guide](https://github.com/LE-VAI/rf-compute/blob/main/CONTRIBUTING.md) — the reproducibility + provenance + honesty bar
+- ✅ [LICENSE](https://github.com/LE-VAI/rf-compute/blob/main/LICENSE) — MIT
+- ✅ [SDR kernel abstraction](https://github.com/LE-VAI/rf-compute/tree/main/rf_compute/) — one API across all four lineages
+  - ✅ [`examples/tier1_aircomp_kernel.py`](https://github.com/LE-VAI/rf-compute/blob/main/examples/tier1_aircomp_kernel.py) — Tier 1 with the kernel
+  - ✅ [`examples/tier1_5_lattice_aircomp_kernel.py`](https://github.com/LE-VAI/rf-compute/blob/main/examples/tier1_5_lattice_aircomp_kernel.py) — Tier 1.5 with the kernel
+  - ✅ [`examples/tier1_6_fading_coefficients.py`](https://github.com/LE-VAI/rf-compute/blob/main/examples/tier1_6_fading_coefficients.py) — Tier 1.6 with the kernel
+  - ✅ [`examples/tier2_convolution_kernel.py`](https://github.com/LE-VAI/rf-compute/blob/main/examples/tier2_convolution_kernel.py) — Tier 2 with the kernel
+  - ✅ [`examples/tier3_inversion_kernel.py`](https://github.com/LE-VAI/rf-compute/blob/main/examples/tier3_inversion_kernel.py) — Tier 3 with the kernel
+  - ✅ [`examples/tier4_ota_federated_learning.py`](https://github.com/LE-VAI/rf-compute/blob/main/examples/tier4_ota_federated_learning.py) — Tier 4 with the kernel
+- ⏳ Community contributions (see `CONTRIBUTING.md`)
+
+---
+
+## License
+
+MIT — see [LICENSE](https://github.com/LE-VAI/rf-compute/blob/main/LICENSE).
+
+---
+
+## Provenance
+
+This project is a research-and-education surface synthesized from peer-reviewed literature. The underlying research was conducted 2026-07-31 via a multi-source academic search across *Science*, *Nature*, *Nature Photonics*, *IEEE Trans. Inf. Theory*, *Journal of Lightwave Technology*, and arXiv. Full provenance and citation verification in [`docs/field-map.md`](https://github.com/LE-VAI/rf-compute/blob/main/docs/field-map.md#provenance).
+
+All citations are peer-reviewed unless marked `[preprint]` or `[vendor]`. Lightmatter performance figures are vendor-sourced. AirComp surveys are preprints. The spin-torque SDR mapping is approximate, not a hardware equivalent.
+
+This surface does not claim authorship of the underlying physics. It claims only the bridge — the map, the vocabulary, and the reproducible "hello world."

rf_compute-0.1.0/README.md

@@ -0,0 +1,213 @@
+# rf-compute
+
+<!-- vai-hero:start -->
+<p align="center">
+  <picture>
+    <source media="(prefers-reduced-motion: reduce)" srcset="https://raw.githubusercontent.com/LE-VAI/rf-compute/main/docs/media/hero-poster.png">
+    <img src="https://raw.githubusercontent.com/LE-VAI/rf-compute/main/docs/media/hero-loop.webp" width="800" alt="Two carrier waves travel across the frame. Carrier A completes one cycle per loop and carrier B completes two. The bottom lane shows their sum, sampled as orange stems: the interference is the operation.">
+  </picture>
+</p>
+<p align="center"><sub>A 4-second loop. It plays once and rests, and shows a still frame if you prefer reduced motion. <a href="https://le-vai.github.io/LE-VAI/loops/#rf-compute">Watch it on repeat</a>.</sub></p>
+<!-- vai-hero:end -->
+
+**Radio Frequency as a computational substrate — not a transmission medium.**
+
+A research-and-education surface for wave-domain computation. The waveform is the operand. Interference isn't noise to cancel — it's the multiply-accumulate operation. The medium is the math.
+
+---
+
+## The one-sentence version
+
+> Instead of using RF to carry bits to a digital chip that does the math, you make the RF waveform *be* the math — interference performs the operation, the channel is the adder, the medium is the algorithm.
+
+This is not a new idea. It's been hiding in plain sight across four separate research communities for ~18 years. `rf-compute` is the bridge that makes it legible to builders.
+
+---
+
+## Why this exists
+
+There is no unified developer surface for RF-as-compute. The field is real, peer-reviewed, and active — but it's scattered across four communities that don't share vocabulary, tooling, or a "hello world":
+
+| Lineage | Where it publishes | What it does |
+|---|---|---|
+| **Computational metamaterials** | *Science*, *Nature* | Passive materials that perform math on wavefields |
+| **Over-the-air computation (AirComp)** | *IEEE Trans. Inf. Theory* | The wireless channel *is* the computation |
+| **Microwave photonics** | *Nature Photonics* | RF signals on optical carriers doing NN inference |
+| **Spin-torque neuromorphic** | *Nature Electronics* | Microwave nano-oscillators as neurons |
+
+They all share one thing: **the waveform is the operand.** Nobody has built the bridge between them. That's the gap this project fills.
+
+---
+
+## The $350 hello world
+
+You don't need a fab, a clean room, or a metamaterial. You need **two transmit SDRs, one receive SDR, and a laptop** — clone-tier hardware gets you there around $350; official units run ~$725. Either way, the simulation kernel runs free on NumPy alone.
+
+```
+Tx1 ──┐
+       ├── air ──→ Rx ──→ f(x1 + x2)  ← the channel computed the sum
+Tx2 ──┘
+```
+
+Two transmitters send pre-coded signals simultaneously. The receiver reads their sum from the superposed waveform — **without decoding either signal individually.** Interference is the operation. This is the Nazer & Gastpar 2007 result, made legible.
+
+This is the simplest wave-compute primitive that exists. If you can run this, you understand the field.
+
+📖 **Full walkthrough:** [`docs/hello-world-aircomp.md`](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-aircomp.md) — hardware, code, what to expect, troubleshooting
+
+**Budget option:** One HackRF + one RTL-SDR (clone-tier ~$190, official ~$380). You transmit x1, x2, and x1+x2 sequentially and compare captures in post-processing. You lose the simultaneity that makes AirComp profound, but you learn the signal-processing structure for half the cost. Details in the walkthrough.
+
+### Quick start (60 seconds, no hardware)
+
+```bash
+git clone https://github.com/LE-VAI/rf-compute.git
+cd rf-compute
+pip install -e .
+python examples/tier1_aircomp_kernel.py    # AirComp: 3+5=8
+python examples/tier1_5_lattice_aircomp_kernel.py  # exact lattice sums, $0
+python examples/tier1_6_fading_coefficients.py     # coefficient selection on fading, $0
+python examples/tier2_convolution_kernel.py # 4 operators
+python examples/tier3_inversion_kernel.py   # solves Ax=b
+python examples/tier4_ota_federated_learning.py  # federated learning over the air, $0
+```
+
+The simulation kernel runs the same API as the hardware kernel — switch `backend="sim"` to `backend="sdr"` when you have SDRs. See [`docs/INSTALL.md`](https://github.com/LE-VAI/rf-compute/blob/main/docs/INSTALL.md) for the SDR driver install (the one friction point when you're ready for hardware).
+
+---
+
+## The hello-world ladder
+
+Six reproducible experiments, escalating in cost. Each maps to a peer-reviewed result.
+
+| Tier | Experiment | Cost (clone-tier / official) | Proves | Citation |
+|---|---|---|---|---|
+| **1** | AirComp sum | ~$350 / ~$725 | Interference IS computation | Nazer & Gastpar, *IEEE TIT* (2011) |
+| **1.5** | Lattice-coded AirComp | free (sim) | The exact result: noise-resilient sums in one channel use, no message decoded | Nazer & Gastpar, *IEEE TIT* (2007/2011) |
+| **1.6** | Fading-channel coefficients | free (sim) | Coefficients are an optimization: the plain sum is undecodable on ~95% of fading channels; selection finds a decodable one | Nazer & Gastpar (2011); Sahraei & Gastpar (2014); Liu & Ling, *IEEE TWC* (2016) |
+| **2** | Wave-domain convolution | ~$200 / ~$395 | Linear operators are native to wave physics | Silva et al., *Science* (2014) |
+| **3** | Matrix inversion via feedback | free / ~$200 / ~$350 | The wave domain solves equations; settling, not iterating | Tzarouchis, Edwards & Engheta, *Nature Communications* (2025) |
+| **4** | Over-the-air federated learning | free (sim) | The channel aggregates model updates in `d+1` uses however many devices transmit; a shared pilot rescues training from misalignment, and heterogeneity bounds the rescue | Zhu, Wang & Huang, *IEEE TWC* (2020); Shao, Gündüz & Liew, *IEEE TWC* (2022) |
+
+Tier 3 has three modes (simulation free, software-in-the-loop ~$200 clone / ~$395 official, analog feedback ~$350 clone / ~$480 official) — see the walkthrough for the trade-off.
+
+📖 **Full ladder walkthroughs:** [Tier 1](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-aircomp.md) · [Tier 1.5](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-lattice-aircomp.md) · [Tier 1.6](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-fading-coefficients.md) · [Tier 2](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-convolution.md) · [Tier 3](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-matrix-inversion.md) · [Tier 4](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-ota-federated-learning.md) — each with parts lists, code, and troubleshooting
+
+---
+
+## What this is NOT
+
+This is a **research and education surface**, not a product. We build the map, the vocabulary, and the reproducible "hello world." The community builds the future.
+
+We are explicitly **not** building:
+
+- ❌ Deep-learning-scale matrices (SOTA is 5×5; NN layers are 1024×1024 — that's a hardware physics problem)
+- ❌ Phone-form-factor integration (45 MHz ≈ 6.7m wavelength — subwavelength resonator design at phone scale is unsolved)
+- ❌ Noise-resilient analog compute for hostile EM environments (lab results won't hold in a pocket)
+- ❌ 6G standards integration (AirComp is a 6G research candidate, not yet in 3GPP standardization; that's a multi-year institutional process)
+- ❌ Commercial fabrication (Lightmatter is pursuing the optical frontier; pure-RF commercial compute is not this project)
+
+These are real, important problems. They belong to the metamaterials physics community, the antenna engineers, the RF circuit designers, the standards bodies, and industry — not to a research-and-education surface. We name them clearly so builders know where the open frontier lives.
+
+📖 **Full deferral table:** [`docs/field-map.md`](https://github.com/LE-VAI/rf-compute/blob/main/docs/field-map.md#what-we-are-not-building-graceful-deferral-to-the-community)
+
+---
+
+## The field map
+
+The complete lineage-to-primitive map lives in [`docs/field-map.md`](https://github.com/LE-VAI/rf-compute/blob/main/docs/field-map.md). It covers:
+
+- Each of the four lineages with origin papers, SOTA devices, key labs, and SDR-mappable primitives
+- The SDR bridge: why software-defined radio is the unified developer surface
+- The "hello world" ladder with cost estimates and parts lists
+- Field maturity at a glance
+- Full provenance and citation list
+
+If you read one document, read the field map.
+
+---
+
+## Hardware you'll need
+
+Prices verified 2026-08-31, re-checked 2026-09-30. HackRF One official retail is ~$340 (SparkFun/Adafruit have retired the unit; GSG's successor **HackRF Pro** is ~$400). AliExpress clones run ~$100–150 but degrade above 1 GHz per Great Scott Gadgets' own clone test — fine for sub-GHz learning experiments, not for precision work. RTL-SDR Blog V4 is end-of-line (May 2026); current official units are the V3 or V4L at ~$35–40 (the V4L is itself a limited edition with roughly a year of chip stock).
+
+| Item | Tier 1 | Tier 2 | Tier 3 (Mode B/C) | Official | Clone-tier |
+|---|:---:|:---:|:---:|---|---|
+| HackRF One SDR (Tx) | ×2 | ×1 | ×1 | ~$340 each | ~$100–150 each |
+| RTL-SDR (Rx, receive-only) | ×1 | ×1 | ×1 | ~$35–40 | ~$30 |
+| 10 MHz clock sync cable (BNC/SMA) | ✓ | | | ~$5 | — |
+| Laptop (any OS) | ✓ | ✓ | ✓ | you have one | — |
+| Passive scatterer / reflector | | ✓ (Mode B) | | ~$10–20 | DIY |
+| RF circulator (one-way loop) | | | ✓ (Mode C) | ~$40 | — |
+| Programmable attenuator (loop gain) | | | ✓ (Mode C) | ~$30 | — |
+| RF splitter/combiner | | | ✓ (Mode C) | ~$15–25 | — |
+
+**Total entry cost: free (Tier 3 sim) / clone-tier ~$200–350 / official ~$390–725 depending on tier.** No fab. No clean room. No metamaterial. Tier 3 Mode A is pure simulation and costs nothing — start there to see the math before buying hardware. If you buy clones, know what you're buying: they work for learning, they drift for precision.
+
+---
+
+## Who this is for
+
+- **Builders** who want to touch wave-domain compute without a physics PhD
+- **Researchers** who want a shared vocabulary across the four lineages
+- **Educators** who want reproducible experiments with real citations
+- **Curious engineers** who read "the channel is the adder" and want to see it work
+
+If you've never heard of RF-as-compute and want to understand it: start with the $350 hello world. If you're already in one of the four lineages: the field map is the bridge to the other three.
+
+---
+
+## The key papers (start here)
+
+| Paper | Year | Why it matters |
+|---|---|---|
+| Nazer & Gastpar, "Computation over multiple-access channels," *IEEE Trans. Inf. Theory* | 2007 | The founding result. Interference computes functions. |
+| Silva et al., "Performing mathematical operations with metamaterials," *Science* | 2014 | Passive materials do math on wavefields. |
+| Torrejon et al., "Neuromorphic computing with spintronic oscillators," *Nature* | 2017 | Microwave nano-oscillators as neurons. 99.6% spoken-digit. |
+| Zangeneh-Nejad et al., "Analogue computing with metamaterials," *Nature Reviews Materials* | 2021 | The canonical review. "Wave-based analog computing." |
+| Li et al., "Performing calculus with ENZ metamaterials," *Science Advances* | 2022 | Differentiation + integration in the material. |
+| Tzarouchis, Edwards & Engheta, "Programmable wave-based analog computing machine: a metastructure that designs metastructures," *Nature Communications* 16, 908 ([DOI](https://doi.org/10.1038/s41467-025-56019-1)) | 2025 | **The SOTA.** Matrix inversion, Newton's method, Lagrangian optimization at 45 MHz. |
+| Chegini, Guan & Yao, "Microwave photonic neural network," *J. Lightwave Technology* | 2025 | RF photonic MVM. 55×10⁶ MAC/s. |
+
+📖 **Annotated bibliography:** [`docs/bibliography.md`](https://github.com/LE-VAI/rf-compute/blob/main/docs/bibliography.md) — every citation, reading order, how to use it
+
+---
+
+## Status
+
+**Pre-release.** The spine is complete: field map, six-tier hello-world ladder, annotated bibliography, contribution guide, and the SDR kernel abstraction. The simulation kernel is fully reproducible (every run seed-deterministic; 116 tests).
+
+- ✅ [Field map](https://github.com/LE-VAI/rf-compute/blob/main/docs/field-map.md) — the spine document
+- ✅ [Tier 1: AirComp sum](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-aircomp.md) — the $350 hello world
+- ✅ [Tier 1.5: Lattice-coded AirComp](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-lattice-aircomp.md) — the $0 exact-computation primitive (nested-lattice kernel)
+- ✅ [Tier 1.6: Fading-channel coefficients](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-fading-coefficients.md) — the $0 coefficient-selection tier (computation-rate maximization, MMSE α, LLL + norm-bound search)
+- ✅ [Tier 2: Wave-domain convolution](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-convolution.md) — the $200 linear-operator primitive
+- ✅ [Tier 3: Matrix inversion via feedback](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-matrix-inversion.md) — the wave-domain capstone (free / $200 / $350)
+- ✅ [Tier 4: Over-the-air federated learning](https://github.com/LE-VAI/rf-compute/blob/main/docs/hello-world-ota-federated-learning.md) — the AirComp capstone ($0): aggregation over the air, misalignment, and a pilot-aided equalizer
+- ✅ [Annotated bibliography](https://github.com/LE-VAI/rf-compute/blob/main/docs/bibliography.md) — every citation, reading order, how to use it
+- ✅ [Installation guide](https://github.com/LE-VAI/rf-compute/blob/main/docs/INSTALL.md) — pip install, SDR drivers, troubleshooting
+- ✅ [Contributing guide](https://github.com/LE-VAI/rf-compute/blob/main/CONTRIBUTING.md) — the reproducibility + provenance + honesty bar
+- ✅ [LICENSE](https://github.com/LE-VAI/rf-compute/blob/main/LICENSE) — MIT
+- ✅ [SDR kernel abstraction](https://github.com/LE-VAI/rf-compute/tree/main/rf_compute/) — one API across all four lineages
+  - ✅ [`examples/tier1_aircomp_kernel.py`](https://github.com/LE-VAI/rf-compute/blob/main/examples/tier1_aircomp_kernel.py) — Tier 1 with the kernel
+  - ✅ [`examples/tier1_5_lattice_aircomp_kernel.py`](https://github.com/LE-VAI/rf-compute/blob/main/examples/tier1_5_lattice_aircomp_kernel.py) — Tier 1.5 with the kernel
+  - ✅ [`examples/tier1_6_fading_coefficients.py`](https://github.com/LE-VAI/rf-compute/blob/main/examples/tier1_6_fading_coefficients.py) — Tier 1.6 with the kernel
+  - ✅ [`examples/tier2_convolution_kernel.py`](https://github.com/LE-VAI/rf-compute/blob/main/examples/tier2_convolution_kernel.py) — Tier 2 with the kernel
+  - ✅ [`examples/tier3_inversion_kernel.py`](https://github.com/LE-VAI/rf-compute/blob/main/examples/tier3_inversion_kernel.py) — Tier 3 with the kernel
+  - ✅ [`examples/tier4_ota_federated_learning.py`](https://github.com/LE-VAI/rf-compute/blob/main/examples/tier4_ota_federated_learning.py) — Tier 4 with the kernel
+- ⏳ Community contributions (see `CONTRIBUTING.md`)
+
+---
+
+## License
+
+MIT — see [LICENSE](https://github.com/LE-VAI/rf-compute/blob/main/LICENSE).
+
+---
+
+## Provenance
+
+This project is a research-and-education surface synthesized from peer-reviewed literature. The underlying research was conducted 2026-07-31 via a multi-source academic search across *Science*, *Nature*, *Nature Photonics*, *IEEE Trans. Inf. Theory*, *Journal of Lightwave Technology*, and arXiv. Full provenance and citation verification in [`docs/field-map.md`](https://github.com/LE-VAI/rf-compute/blob/main/docs/field-map.md#provenance).
+
+All citations are peer-reviewed unless marked `[preprint]` or `[vendor]`. Lightmatter performance figures are vendor-sourced. AirComp surveys are preprints. The spin-torque SDR mapping is approximate, not a hardware equivalent.
+
+This surface does not claim authorship of the underlying physics. It claims only the bridge — the map, the vocabulary, and the reproducible "hello world."

rf_compute-0.1.0/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rf-compute"
+version = "0.1.0"
+description = "Wave-domain computation kernel — one API across the four RF-as-compute lineages (metamaterials, AirComp, microwave photonics, spin-torque neuromorphic). Research and education surface."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "rf-compute contributors" }]
+requires-python = ">=3.9"
+keywords = [
+    "rf",
+    "radio-frequency",
+    "analog-computing",
+    "wave-computing",
+    "metamaterials",
+    "aircomp",
+    "over-the-air-computation",
+    "microwave-photonics",
+    "neuromorphic",
+    "spin-torque",
+    "sdr",
+    "software-defined-radio",
+    "research",
+    "education",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+
+# numpy is the only hard dependency — the simulation backend runs on numpy alone.
+# SoapySDR is optional (only needed for the "sdr" backend); the kernel degrades
+# gracefully to simulation if SoapySDR is absent, so it's not a hard dep.
+dependencies = [
+    "numpy>=1.20",
+]
+
+[project.optional-dependencies]
+# SDR backend — install this extra when you have hardware and want to run
+# the real-RF walkthroughs:  pip install "rf-compute[sdr]"
+sdr = [
+    "SoapySDR>=0.8",
+]
+# Visualization — the walkthrough scripts use matplotlib for spectrum plots.
+# Optional because the kernel itself doesn't depend on it; only the example
+# scripts and walkthroughs do.
+viz = [
+    "matplotlib>=3.5",
+]
+# Development — for contributors running the test suite.
+# SoapySDR is intentionally NOT included here: it's a system library, not a
+# pip package, and `pip install SoapySDR` fails on platforms without the
+# system binding pre-installed. The kernel gracefully degrades to simulation
+# when SoapySDR is absent, so CI runs the full test suite on numpy + pytest
+# alone. Contributors who want SDR tests install SoapySDR separately (see
+# docs/INSTALL.md).
+dev = [
+    "pytest>=7.0",
+    "matplotlib>=3.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/LE-VAI/rf-compute"
+Source = "https://github.com/LE-VAI/rf-compute"
+Issues = "https://github.com/LE-VAI/rf-compute/issues"
+Documentation = "https://github.com/LE-VAI/rf-compute/blob/main/docs/field-map.md"
+Bibliography = "https://github.com/LE-VAI/rf-compute/blob/main/docs/bibliography.md"
+Contributing = "https://github.com/LE-VAI/rf-compute/blob/main/CONTRIBUTING.md"
+
+[tool.setuptools]
+# We use a flat package layout: the package is `rf_compute/` at the repo root.
+# This keeps `from rf_compute import ...` working in both installed and
+# development (pip install -e .) modes without a `src/` prefix.
+packages = ["rf_compute"]
+
+[tool.pytest.ini_options]
+# Tests live in tests/. Run with: pytest
+testpaths = ["tests"]
+python_files = ["test_*.py"]

rf_compute-0.1.0/rf_compute/__init__.py

@@ -0,0 +1,38 @@
+"""rf-compute: wave-domain computation kernel — package init."""
+
+from .rf_compute import (
+    Operator, AirCompOperator, LatticeAirCompOperator, FadingAirCompOperator,
+    OTAAggregationOperator, ConvolutionOperator, InversionOperator, ReservoirOperator,
+    WaveComputeKernel,
+    boxcar, differencer, matched, hilbert,
+)
+from . import lattice
+from . import coefficients
+from . import ota_fl
+from .lattice import (
+    mod_lattice, encode, decode, channel, run_trial, monte_carlo,
+    fading_trial, fading_scoreline,
+)
+from .coefficients import (
+    mmse_alpha, computation_rate, norm_bound, select_coefficients,
+    fading_gains, lll_reduce,
+)
+from .ota_fl import (
+    make_federated_data, gradient_spread, ota_aggregate, aggregation_quality,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    'Operator', 'AirCompOperator', 'LatticeAirCompOperator',
+    'FadingAirCompOperator', 'OTAAggregationOperator',
+    'ConvolutionOperator', 'InversionOperator', 'ReservoirOperator',
+    'WaveComputeKernel',
+    'boxcar', 'differencer', 'matched', 'hilbert',
+    'lattice', 'coefficients', 'ota_fl',
+    'mod_lattice', 'encode', 'decode', 'channel', 'run_trial', 'monte_carlo',
+    'fading_trial', 'fading_scoreline',
+    'mmse_alpha', 'computation_rate', 'norm_bound', 'select_coefficients',
+    'fading_gains', 'lll_reduce',
+    'make_federated_data', 'gradient_spread', 'ota_aggregate', 'aggregation_quality',
+    '__version__',
+]