aircompkit 1.0.0__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.

Potentially problematic release.


This version of aircompkit might be problematic. Click here for more details.

Files changed (50) hide show
  1. aircompkit-1.0.0/LICENSE +21 -0
  2. aircompkit-1.0.0/PKG-INFO +167 -0
  3. aircompkit-1.0.0/README.md +116 -0
  4. aircompkit-1.0.0/pyproject.toml +68 -0
  5. aircompkit-1.0.0/setup.cfg +4 -0
  6. aircompkit-1.0.0/src/aircompkit/__init__.py +32 -0
  7. aircompkit-1.0.0/src/aircompkit/__main__.py +5 -0
  8. aircompkit-1.0.0/src/aircompkit/adversary/__init__.py +175 -0
  9. aircompkit-1.0.0/src/aircompkit/aircomp/__init__.py +41 -0
  10. aircompkit-1.0.0/src/aircompkit/aircomp/analytic.py +42 -0
  11. aircompkit-1.0.0/src/aircompkit/aircomp/power_control.py +183 -0
  12. aircompkit-1.0.0/src/aircompkit/aircomp/preprocess.py +48 -0
  13. aircompkit-1.0.0/src/aircompkit/bench.py +159 -0
  14. aircompkit-1.0.0/src/aircompkit/channel/__init__.py +209 -0
  15. aircompkit-1.0.0/src/aircompkit/cli.py +165 -0
  16. aircompkit-1.0.0/src/aircompkit/core/__init__.py +1 -0
  17. aircompkit-1.0.0/src/aircompkit/core/registry.py +123 -0
  18. aircompkit-1.0.0/src/aircompkit/core/result.py +45 -0
  19. aircompkit-1.0.0/src/aircompkit/core/rng.py +47 -0
  20. aircompkit-1.0.0/src/aircompkit/core/scenario.py +226 -0
  21. aircompkit-1.0.0/src/aircompkit/defense/__init__.py +156 -0
  22. aircompkit-1.0.0/src/aircompkit/defense/evaluate.py +48 -0
  23. aircompkit-1.0.0/src/aircompkit/devices/__init__.py +79 -0
  24. aircompkit-1.0.0/src/aircompkit/learning/__init__.py +32 -0
  25. aircompkit-1.0.0/src/aircompkit/learning/aggregate.py +49 -0
  26. aircompkit-1.0.0/src/aircompkit/learning/array.py +140 -0
  27. aircompkit-1.0.0/src/aircompkit/learning/bank.py +86 -0
  28. aircompkit-1.0.0/src/aircompkit/learning/data.py +128 -0
  29. aircompkit-1.0.0/src/aircompkit/learning/fl.py +249 -0
  30. aircompkit-1.0.0/src/aircompkit/learning/models.py +89 -0
  31. aircompkit-1.0.0/src/aircompkit/learning/partition.py +58 -0
  32. aircompkit-1.0.0/src/aircompkit/metrics/__init__.py +36 -0
  33. aircompkit-1.0.0/src/aircompkit/metrics/privacy.py +36 -0
  34. aircompkit-1.0.0/src/aircompkit/plot/__init__.py +5 -0
  35. aircompkit-1.0.0/src/aircompkit/receiver/__init__.py +244 -0
  36. aircompkit-1.0.0/src/aircompkit/reproduce/__init__.py +26 -0
  37. aircompkit-1.0.0/src/aircompkit/reproduce/yang2020.py +182 -0
  38. aircompkit-1.0.0/src/aircompkit/reproduce/zhu2020.py +205 -0
  39. aircompkit-1.0.0/src/aircompkit.egg-info/PKG-INFO +167 -0
  40. aircompkit-1.0.0/src/aircompkit.egg-info/SOURCES.txt +48 -0
  41. aircompkit-1.0.0/src/aircompkit.egg-info/dependency_links.txt +1 -0
  42. aircompkit-1.0.0/src/aircompkit.egg-info/entry_points.txt +2 -0
  43. aircompkit-1.0.0/src/aircompkit.egg-info/requires.txt +30 -0
  44. aircompkit-1.0.0/src/aircompkit.egg-info/top_level.txt +1 -0
  45. aircompkit-1.0.0/tests/test_core.py +104 -0
  46. aircompkit-1.0.0/tests/test_p1_aircomp.py +253 -0
  47. aircompkit-1.0.0/tests/test_p2_mimo.py +247 -0
  48. aircompkit-1.0.0/tests/test_p3_learning.py +231 -0
  49. aircompkit-1.0.0/tests/test_p4_security.py +254 -0
  50. aircompkit-1.0.0/tests/test_p5_bench_checks.py +117 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 moyeendev
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,167 @@
1
+ Metadata-Version: 2.4
2
+ Name: aircompkit
3
+ Version: 1.0.0
4
+ Summary: Security-aware simulator for over-the-air computation and over-the-air federated learning.
5
+ Author: M. A. Moyeen, Kuljeet Kaur, Anjali Agarwal
6
+ License: MIT
7
+ Project-URL: Repository, https://github.com/moyeendev/AirCompKit
8
+ Project-URL: Documentation, https://moyeendev.github.io/AirCompKit/
9
+ Project-URL: Changelog, https://github.com/moyeendev/AirCompKit/blob/main/CHANGELOG.md
10
+ Keywords: over-the-air computation,AirComp,federated learning,wireless,6G,Byzantine robustness,physical-layer security,simulation
11
+ Classifier: Development Status :: 5 - Production/Stable
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: License :: OSI Approved :: MIT License
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Intended Audience :: Science/Research
20
+ Classifier: Topic :: Scientific/Engineering
21
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
22
+ Classifier: Topic :: Communications
23
+ Requires-Python: >=3.10
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Requires-Dist: numpy>=1.24
27
+ Requires-Dist: pyyaml>=6
28
+ Provides-Extra: torch
29
+ Requires-Dist: torch>=2.1; extra == "torch"
30
+ Provides-Extra: plot
31
+ Requires-Dist: matplotlib>=3.7; extra == "plot"
32
+ Provides-Extra: test
33
+ Requires-Dist: pytest>=7; extra == "test"
34
+ Provides-Extra: dev
35
+ Requires-Dist: pytest>=7; extra == "dev"
36
+ Requires-Dist: pytest-cov>=4; extra == "dev"
37
+ Requires-Dist: ruff>=0.5; extra == "dev"
38
+ Requires-Dist: mypy>=1.8; extra == "dev"
39
+ Requires-Dist: types-PyYAML; extra == "dev"
40
+ Requires-Dist: matplotlib>=3.7; extra == "dev"
41
+ Provides-Extra: docs
42
+ Requires-Dist: mkdocs-material>=9.5; extra == "docs"
43
+ Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
44
+ Requires-Dist: mkdocs-jupyter>=0.24; extra == "docs"
45
+ Requires-Dist: nbclient>=0.10; extra == "docs"
46
+ Requires-Dist: ipykernel>=6; extra == "docs"
47
+ Requires-Dist: matplotlib>=3.7; extra == "docs"
48
+ Provides-Extra: all
49
+ Requires-Dist: aircompkit[plot,torch]; extra == "all"
50
+ Dynamic: license-file
51
+
52
+ # AirCompKit
53
+
54
+ [![CI](https://github.com/moyeendev/AirCompKit/actions/workflows/ci.yml/badge.svg)](https://github.com/moyeendev/AirCompKit/actions/workflows/ci.yml)
55
+ [![Reproductions](https://github.com/moyeendev/AirCompKit/actions/workflows/reproduce.yml/badge.svg)](https://github.com/moyeendev/AirCompKit/actions/workflows/reproduce.yml)
56
+ [![Docs](https://github.com/moyeendev/AirCompKit/actions/workflows/docs.yml/badge.svg)](https://moyeendev.github.io/AirCompKit/)
57
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
58
+ [![Python 3.10-3.13](https://img.shields.io/badge/python-3.10--3.13-blue.svg)](pyproject.toml)
59
+
60
+ **Security-aware simulator for over-the-air computation (AirComp) and over-the-air federated learning (OTA-FL).**
61
+
62
+ > Status: **v1.0.0**. AirComp over AWGN, Rayleigh and Rician
63
+ > channels (multi-antenna server, spatial correlation, path loss/shadowing, imperfect CSI,
64
+ > phase errors), four power-control schemes, four receive beamformers, over-the-air
65
+ > federated learning (FedSGD/FedAvg, NumPy models, MNIST/Fashion-MNIST/synthetic data,
66
+ > gradient bank), a threat model with seven attacks, and defences from grouped over-the-air
67
+ > aggregation to robust digital rules, plus an interface for detection-based defences. Validated against closed forms and published results, re-checked
68
+ > weekly in CI (`aircompkit reproduce NAME --check`).
69
+ >
70
+ > **Documentation:** <https://moyeendev.github.io/AirCompKit/> (user guide, six executed
71
+ > tutorial notebooks in [docs/tutorials](docs/tutorials), API reference, reproductions,
72
+ > benchmarks). See also [FEATURES.md](FEATURES.md).
73
+
74
+ ## Security in three lines
75
+
76
+ ```python
77
+ from aircompkit.learning import FederatedConfig, train
78
+
79
+ threat = {"attack": {"name": "collude", "boost_db": 15}, "n_attackers": 6,
80
+ "knowledge": ["own_data", "own_csi", "honest_mean"]} # assumptions are explicit
81
+ res = train(scenario, FederatedConfig(dataset="mnist", clip=0.2, threat=threat,
82
+ defense={"name": "digital_robust", "rule": "median"}))
83
+ ```
84
+
85
+ `scenario` needs a multi-antenna channel and `symbols="complex"` (the array-level path); see
86
+ [examples/secure_otafl.py](examples/secure_otafl.py) for a full setup.
87
+
88
+ AirComp lets many devices transmit at once so that the wireless channel computes their sum.
89
+ Because signals superpose before the server sees them, per-client defences no longer apply.
90
+ AirCompKit models the **channel, the AirComp transceiver, the learning loop, the adversary and
91
+ the defence** as interchangeable components, and it ships a suite that reproduces published
92
+ AirComp results.
93
+
94
+ ## Install
95
+
96
+ From PyPI once v1.0.0 is released: `pip install aircompkit` (add `[plot]` for figures).
97
+ For development:
98
+
99
+ ```bash
100
+ git clone https://github.com/moyeendev/AirCompKit.git
101
+ cd AirCompKit
102
+ python -m pip install -e ".[dev]"
103
+ pytest
104
+ ```
105
+
106
+ ## Quickstart
107
+
108
+ ```python
109
+ import aircompkit as ac
110
+
111
+ sc = ac.Scenario(
112
+ devices={"name": "uniform_disc", "K": 20, "p_max": 1.0, "r_min": 10, "r_max": 100},
113
+ channel={"name": "rayleigh", "pathloss": {"exponent": 3.0, "ref_gain_db": -30}},
114
+ power_control="optimal", # truncated_inversion | full_power | channel_inversion
115
+ target="mean",
116
+ noise_var=1e-10,
117
+ seed=0,
118
+ )
119
+ res = sc.run(trials=2000, dim=32) # analytical + signal-level Monte Carlo
120
+ print(res.summary()["mse"]) # (mean, 95% CI half-width)
121
+ res.save("results/demo") # .npz arrays + .json with the full config
122
+ ```
123
+
124
+ The same scenario as YAML is in [configs/rayleigh_optimal.yaml](configs/rayleigh_optimal.yaml).
125
+ [examples/mse_vs_snr.py](examples/mse_vs_snr.py) compares the power-control schemes against
126
+ the closed-form MSE of truncated channel inversion.
127
+ [examples/secure_otafl.py](examples/secure_otafl.py) compares the defences under three attacks on MNIST
128
+ (about 45 minutes; `--quick` for a smoke test).
129
+
130
+ ## Command line
131
+
132
+ ```bash
133
+ aircompkit --version
134
+ aircompkit list # registered components per kind
135
+ aircompkit run configs/rayleigh_optimal.yaml --trials 5000 --out results/run1
136
+ aircompkit run configs/mimo_maxmin_csi.yaml --out results/mimo
137
+ aircompkit reproduce yang2020 --out results/yang2020 # Yang et al. TWC 2020, Figs. 4-5
138
+ aircompkit train configs/otafl_synthetic.yaml --out results/otafl
139
+ aircompkit reproduce zhu2020 --out results/zhu2020 # Zhu et al. TWC 2020, Figs. 4, 7(b)
140
+ aircompkit reproduce yang2020 --quick --check # compare with the paper; exit 1 on failure
141
+ aircompkit reproduce --all --quick --check # all reproductions (~1 min with MNIST)
142
+ aircompkit bench --out results/bench # performance benchmarks
143
+ python -m aircompkit list # same as above, if your system blocks pip-generated launchers
144
+ ```
145
+
146
+ MNIST and Fashion-MNIST are never downloaded automatically. Put `mnist.npz` (Keras layout)
147
+ or the four IDX files in a folder and pass `--data-root` or set `AIRCOMPKIT_DATA`.
148
+
149
+ ## Repository layout
150
+
151
+ | Path | Contents |
152
+ |------|----------|
153
+ | `src/aircompkit/core` | registry, seed tree, Scenario, Result |
154
+ | `src/aircompkit/{devices,channel,aircomp,receiver}` | physical layer |
155
+ | `src/aircompkit/{adversary,defense}` | threat model, attacks, defences |
156
+ | `src/aircompkit/learning` | OTA-FL loop, datasets, gradient bank |
157
+ | `src/aircompkit/{metrics,reproduce}`, `bench.py` | evaluation, paper reproductions with tolerance checks, benchmarks |
158
+ | `configs/`, `examples/` | scenarios, examples |
159
+ | `docs/` | MkDocs site; `docs/tutorials/*.ipynb` executed tutorials (`python docs/execute_notebooks.py`) |
160
+
161
+ ## Citing
162
+
163
+ See [CITATION.cff](CITATION.cff). A SoftwareX paper is in preparation.
164
+
165
+ ## License
166
+
167
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,116 @@
1
+ # AirCompKit
2
+
3
+ [![CI](https://github.com/moyeendev/AirCompKit/actions/workflows/ci.yml/badge.svg)](https://github.com/moyeendev/AirCompKit/actions/workflows/ci.yml)
4
+ [![Reproductions](https://github.com/moyeendev/AirCompKit/actions/workflows/reproduce.yml/badge.svg)](https://github.com/moyeendev/AirCompKit/actions/workflows/reproduce.yml)
5
+ [![Docs](https://github.com/moyeendev/AirCompKit/actions/workflows/docs.yml/badge.svg)](https://moyeendev.github.io/AirCompKit/)
6
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
7
+ [![Python 3.10-3.13](https://img.shields.io/badge/python-3.10--3.13-blue.svg)](pyproject.toml)
8
+
9
+ **Security-aware simulator for over-the-air computation (AirComp) and over-the-air federated learning (OTA-FL).**
10
+
11
+ > Status: **v1.0.0**. AirComp over AWGN, Rayleigh and Rician
12
+ > channels (multi-antenna server, spatial correlation, path loss/shadowing, imperfect CSI,
13
+ > phase errors), four power-control schemes, four receive beamformers, over-the-air
14
+ > federated learning (FedSGD/FedAvg, NumPy models, MNIST/Fashion-MNIST/synthetic data,
15
+ > gradient bank), a threat model with seven attacks, and defences from grouped over-the-air
16
+ > aggregation to robust digital rules, plus an interface for detection-based defences. Validated against closed forms and published results, re-checked
17
+ > weekly in CI (`aircompkit reproduce NAME --check`).
18
+ >
19
+ > **Documentation:** <https://moyeendev.github.io/AirCompKit/> (user guide, six executed
20
+ > tutorial notebooks in [docs/tutorials](docs/tutorials), API reference, reproductions,
21
+ > benchmarks). See also [FEATURES.md](FEATURES.md).
22
+
23
+ ## Security in three lines
24
+
25
+ ```python
26
+ from aircompkit.learning import FederatedConfig, train
27
+
28
+ threat = {"attack": {"name": "collude", "boost_db": 15}, "n_attackers": 6,
29
+ "knowledge": ["own_data", "own_csi", "honest_mean"]} # assumptions are explicit
30
+ res = train(scenario, FederatedConfig(dataset="mnist", clip=0.2, threat=threat,
31
+ defense={"name": "digital_robust", "rule": "median"}))
32
+ ```
33
+
34
+ `scenario` needs a multi-antenna channel and `symbols="complex"` (the array-level path); see
35
+ [examples/secure_otafl.py](examples/secure_otafl.py) for a full setup.
36
+
37
+ AirComp lets many devices transmit at once so that the wireless channel computes their sum.
38
+ Because signals superpose before the server sees them, per-client defences no longer apply.
39
+ AirCompKit models the **channel, the AirComp transceiver, the learning loop, the adversary and
40
+ the defence** as interchangeable components, and it ships a suite that reproduces published
41
+ AirComp results.
42
+
43
+ ## Install
44
+
45
+ From PyPI once v1.0.0 is released: `pip install aircompkit` (add `[plot]` for figures).
46
+ For development:
47
+
48
+ ```bash
49
+ git clone https://github.com/moyeendev/AirCompKit.git
50
+ cd AirCompKit
51
+ python -m pip install -e ".[dev]"
52
+ pytest
53
+ ```
54
+
55
+ ## Quickstart
56
+
57
+ ```python
58
+ import aircompkit as ac
59
+
60
+ sc = ac.Scenario(
61
+ devices={"name": "uniform_disc", "K": 20, "p_max": 1.0, "r_min": 10, "r_max": 100},
62
+ channel={"name": "rayleigh", "pathloss": {"exponent": 3.0, "ref_gain_db": -30}},
63
+ power_control="optimal", # truncated_inversion | full_power | channel_inversion
64
+ target="mean",
65
+ noise_var=1e-10,
66
+ seed=0,
67
+ )
68
+ res = sc.run(trials=2000, dim=32) # analytical + signal-level Monte Carlo
69
+ print(res.summary()["mse"]) # (mean, 95% CI half-width)
70
+ res.save("results/demo") # .npz arrays + .json with the full config
71
+ ```
72
+
73
+ The same scenario as YAML is in [configs/rayleigh_optimal.yaml](configs/rayleigh_optimal.yaml).
74
+ [examples/mse_vs_snr.py](examples/mse_vs_snr.py) compares the power-control schemes against
75
+ the closed-form MSE of truncated channel inversion.
76
+ [examples/secure_otafl.py](examples/secure_otafl.py) compares the defences under three attacks on MNIST
77
+ (about 45 minutes; `--quick` for a smoke test).
78
+
79
+ ## Command line
80
+
81
+ ```bash
82
+ aircompkit --version
83
+ aircompkit list # registered components per kind
84
+ aircompkit run configs/rayleigh_optimal.yaml --trials 5000 --out results/run1
85
+ aircompkit run configs/mimo_maxmin_csi.yaml --out results/mimo
86
+ aircompkit reproduce yang2020 --out results/yang2020 # Yang et al. TWC 2020, Figs. 4-5
87
+ aircompkit train configs/otafl_synthetic.yaml --out results/otafl
88
+ aircompkit reproduce zhu2020 --out results/zhu2020 # Zhu et al. TWC 2020, Figs. 4, 7(b)
89
+ aircompkit reproduce yang2020 --quick --check # compare with the paper; exit 1 on failure
90
+ aircompkit reproduce --all --quick --check # all reproductions (~1 min with MNIST)
91
+ aircompkit bench --out results/bench # performance benchmarks
92
+ python -m aircompkit list # same as above, if your system blocks pip-generated launchers
93
+ ```
94
+
95
+ MNIST and Fashion-MNIST are never downloaded automatically. Put `mnist.npz` (Keras layout)
96
+ or the four IDX files in a folder and pass `--data-root` or set `AIRCOMPKIT_DATA`.
97
+
98
+ ## Repository layout
99
+
100
+ | Path | Contents |
101
+ |------|----------|
102
+ | `src/aircompkit/core` | registry, seed tree, Scenario, Result |
103
+ | `src/aircompkit/{devices,channel,aircomp,receiver}` | physical layer |
104
+ | `src/aircompkit/{adversary,defense}` | threat model, attacks, defences |
105
+ | `src/aircompkit/learning` | OTA-FL loop, datasets, gradient bank |
106
+ | `src/aircompkit/{metrics,reproduce}`, `bench.py` | evaluation, paper reproductions with tolerance checks, benchmarks |
107
+ | `configs/`, `examples/` | scenarios, examples |
108
+ | `docs/` | MkDocs site; `docs/tutorials/*.ipynb` executed tutorials (`python docs/execute_notebooks.py`) |
109
+
110
+ ## Citing
111
+
112
+ See [CITATION.cff](CITATION.cff). A SoftwareX paper is in preparation.
113
+
114
+ ## License
115
+
116
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,68 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "aircompkit"
7
+ dynamic = ["version"]
8
+ description = "Security-aware simulator for over-the-air computation and over-the-air federated learning."
9
+ readme = "README.md"
10
+ license = { text = "MIT" }
11
+ requires-python = ">=3.10"
12
+ authors = [{ name = "M. A. Moyeen" }, { name = "Kuljeet Kaur" }, { name = "Anjali Agarwal" }]
13
+ keywords = [
14
+ "over-the-air computation", "AirComp", "federated learning", "wireless",
15
+ "6G", "Byzantine robustness", "physical-layer security", "simulation",
16
+ ]
17
+ classifiers = [
18
+ "Development Status :: 5 - Production/Stable",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3.10",
21
+ "Programming Language :: Python :: 3.11",
22
+ "Programming Language :: Python :: 3.12",
23
+ "Programming Language :: Python :: 3.13",
24
+ "License :: OSI Approved :: MIT License",
25
+ "Operating System :: OS Independent",
26
+ "Intended Audience :: Science/Research",
27
+ "Topic :: Scientific/Engineering",
28
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
29
+ "Topic :: Communications",
30
+ ]
31
+ dependencies = ["numpy>=1.24", "pyyaml>=6"]
32
+
33
+ [project.optional-dependencies]
34
+ torch = ["torch>=2.1"]
35
+ plot = ["matplotlib>=3.7"]
36
+ test = ["pytest>=7"]
37
+ dev = ["pytest>=7", "pytest-cov>=4", "ruff>=0.5", "mypy>=1.8", "types-PyYAML", "matplotlib>=3.7"]
38
+ docs = [
39
+ "mkdocs-material>=9.5", "mkdocstrings[python]>=0.25", "mkdocs-jupyter>=0.24",
40
+ "nbclient>=0.10", "ipykernel>=6", "matplotlib>=3.7",
41
+ ]
42
+ all = ["aircompkit[torch,plot]"]
43
+
44
+ [project.urls]
45
+ Repository = "https://github.com/moyeendev/AirCompKit"
46
+ Documentation = "https://moyeendev.github.io/AirCompKit/"
47
+ Changelog = "https://github.com/moyeendev/AirCompKit/blob/main/CHANGELOG.md"
48
+
49
+ [project.scripts]
50
+ aircompkit = "aircompkit.cli:main"
51
+
52
+ [tool.setuptools.dynamic]
53
+ version = { attr = "aircompkit.__version__" }
54
+
55
+ [tool.setuptools.packages.find]
56
+ where = ["src"]
57
+
58
+ [tool.pytest.ini_options]
59
+ testpaths = ["tests"]
60
+ addopts = "-p no:hypothesispytest"
61
+
62
+ [tool.ruff]
63
+ line-length = 100
64
+ target-version = "py310"
65
+
66
+ [tool.mypy]
67
+ python_version = "3.10"
68
+ ignore_missing_imports = true
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,32 @@
1
+ """AirCompKit: security-aware over-the-air computation simulator."""
2
+
3
+ __version__ = "1.0.0"
4
+
5
+ # Importing the component packages registers their components.
6
+ from aircompkit import ( # noqa: F401
7
+ adversary,
8
+ aircomp,
9
+ channel,
10
+ defense,
11
+ devices,
12
+ learning,
13
+ metrics,
14
+ receiver,
15
+ reproduce,
16
+ )
17
+ from aircompkit.core.registry import KINDS, available, build, get, register
18
+ from aircompkit.core.result import Result
19
+ from aircompkit.core.rng import SeedTree
20
+ from aircompkit.core.scenario import Scenario
21
+
22
+ __all__ = [
23
+ "KINDS",
24
+ "Result",
25
+ "Scenario",
26
+ "SeedTree",
27
+ "__version__",
28
+ "available",
29
+ "build",
30
+ "get",
31
+ "register",
32
+ ]
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from aircompkit.cli import main
4
+
5
+ sys.exit(main())
@@ -0,0 +1,175 @@
1
+ """Threat model and attack library (FEATURES §5).
2
+
3
+ A ``ThreatModel`` says *who* attacks (a fixed set of ``n_attackers`` devices or a
4
+ ``fraction``), *what they know* (``knowledge``) and *how much power* they may use
5
+ (``max_boost_db``), plus an optional external ``jammer``. Attacks declare what they
6
+ ``need``; building a threat model whose attack needs more than it grants is an error (T5),
7
+ so results always state their assumptions.
8
+
9
+ Attacks act on the array-level path (``aircompkit.learning.array``): honest devices send
10
+ ``t_k = b_k x_k`` with unit-power symbols ``x_k`` and AirComp pre-equaliser ``b_k``; an
11
+ attacker replaces its row via ``transmit(x_own, b_own, ctx)``, may distort the server's CSI
12
+ of its own channel (``distort_csi``), or poison its local labels (``poisons_labels``).
13
+ ``boost_db`` is the attacker's power over what the power-control rule prescribes.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from dataclasses import dataclass, field
19
+ from typing import Any
20
+
21
+ import numpy as np
22
+
23
+ from aircompkit.channel import _cn
24
+ from aircompkit.core.registry import build, register
25
+
26
+ KNOWLEDGE = frozenset({"own_data", "own_csi", "honest_mean", "receiver"})
27
+
28
+
29
+ @dataclass
30
+ class Attack:
31
+ """Base class for attacks: subclass it, override ``transmit`` (and optionally ``distort_csi``,
32
+ ``flip_labels``), set ``needs``, and register with ``@register("attack", name)``."""
33
+
34
+ boost_db: float = 0.0
35
+ needs = frozenset({"own_data"})
36
+ poisons_labels = False
37
+
38
+ @property
39
+ def gain(self) -> float:
40
+ return float(10 ** (self.boost_db / 20))
41
+
42
+ def transmit(self, x, b, ctx):
43
+ return self.gain * x * b[:, None]
44
+
45
+ def distort_csi(self, h_est):
46
+ return h_est
47
+
48
+ def flip_labels(self, y, n_classes):
49
+ return y
50
+
51
+
52
+ @register("attack", "gaussian")
53
+ @dataclass
54
+ class GaussianNoise(Attack):
55
+ """Transmit ``CN(0, P_k)`` noise at the boosted power limit (jamming from inside)."""
56
+
57
+ needs = frozenset()
58
+
59
+ def transmit(self, x, b, ctx):
60
+ P = np.asarray(ctx["p_max"], float)[:, None]
61
+ return self.gain * np.sqrt(P) * _cn(ctx["rng"], x.shape)
62
+
63
+
64
+ @register("attack", "sign_flip")
65
+ @dataclass
66
+ class SignFlip(Attack):
67
+ """Send ``-x_k`` (own update reversed) with power boost; independent across attackers."""
68
+
69
+ def transmit(self, x, b, ctx):
70
+ return -self.gain * x * b[:, None]
71
+
72
+
73
+ @register("attack", "scaled")
74
+ @dataclass
75
+ class Scaled(Attack):
76
+ """Send the own honest update with a power boost (pure power-control violation)."""
77
+
78
+
79
+ @register("attack", "collude")
80
+ @dataclass
81
+ class Collude(Attack):
82
+ """Omniscient colluders: all send the same unit-power vector opposite to the honest mean
83
+ (rank-1 attack, the hardest for spatial detection)."""
84
+
85
+ needs = frozenset({"honest_mean"})
86
+
87
+ def transmit(self, x, b, ctx):
88
+ g = ctx["gref"]
89
+ v = -g / np.sqrt(max(float(np.mean(np.abs(g) ** 2)), 1e-300))
90
+ return self.gain * v[None, :] * b[:, None]
91
+
92
+
93
+ @register("attack", "misalign")
94
+ @dataclass
95
+ class Misalign(Attack):
96
+ """Rotate the own (honest) signal by ``phase`` radians: destructive superposition without
97
+ changing the payload; ``phase = pi`` equals ``sign_flip``."""
98
+
99
+ phase: float = float(np.pi / 2)
100
+
101
+ def transmit(self, x, b, ctx):
102
+ return self.gain * np.exp(1j * self.phase) * x * b[:, None]
103
+
104
+
105
+ @register("attack", "label_flip")
106
+ @dataclass
107
+ class LabelFlip(Attack):
108
+ """Data poisoning: train on labels ``y -> C - 1 - y``, then transmit like an honest device."""
109
+
110
+ poisons_labels = True
111
+
112
+ def flip_labels(self, y, n_classes):
113
+ return n_classes - 1 - y
114
+
115
+
116
+ @register("attack", "csi_spoof")
117
+ @dataclass
118
+ class CSISpoof(Attack):
119
+ """Pilot manipulation: the attacker makes its channel look ``factor`` times weaker. With
120
+ channel inversion the weakest device sets the receive scaling, so every device's SNR drops,
121
+ and the attacker's own row arrives ``1/factor`` times too strong."""
122
+
123
+ factor: float = 0.1
124
+ needs = frozenset({"own_data", "own_csi"})
125
+
126
+ def distort_csi(self, h_est):
127
+ return self.factor * h_est
128
+
129
+
130
+ @dataclass
131
+ class ThreatModel:
132
+ attack: Any = "sign_flip"
133
+ n_attackers: int = 0
134
+ fraction: float | None = None
135
+ knowledge: list[str] = field(default_factory=lambda: ["own_data", "own_csi"])
136
+ max_boost_db: float | None = None
137
+ jammer: dict[str, float] | None = None
138
+ seed: int = 0
139
+
140
+ def __post_init__(self) -> None:
141
+ self.attack = build("attack", self.attack)
142
+ unknown = set(self.knowledge) - KNOWLEDGE
143
+ if unknown:
144
+ raise ValueError(f"unknown knowledge flags {sorted(unknown)}; allowed {sorted(KNOWLEDGE)}")
145
+ missing = set(self.attack.needs) - set(self.knowledge)
146
+ if missing:
147
+ raise ValueError(
148
+ f"attack {type(self.attack).__name__} needs knowledge {sorted(missing)} that the "
149
+ "threat model does not grant (add it to 'knowledge')")
150
+ if self.max_boost_db is not None and self.attack.boost_db > self.max_boost_db:
151
+ raise ValueError(f"boost_db {self.attack.boost_db} exceeds max_boost_db {self.max_boost_db}")
152
+ if self.fraction is not None and not 0 <= self.fraction < 1:
153
+ raise ValueError("fraction must be in [0, 1)")
154
+ if self.jammer is not None and self.jammer.get("power", 0) < 0:
155
+ raise ValueError("jammer power must be >= 0")
156
+
157
+ def attackers(self, K: int) -> np.ndarray:
158
+ n = round(self.fraction * K) if self.fraction is not None else self.n_attackers
159
+ if not 0 <= n < K:
160
+ raise ValueError(f"need 0 <= attackers < K, got {n} of {K}")
161
+ rng = np.random.default_rng(self.seed)
162
+ return np.sort(rng.choice(K, n, replace=False)) if n else np.zeros(0, int)
163
+
164
+ def to_dict(self) -> dict[str, Any]:
165
+ from aircompkit.core.registry import spec_of
166
+
167
+ return {"attack": spec_of("attack", self.attack), "n_attackers": self.n_attackers,
168
+ "fraction": self.fraction, "knowledge": list(self.knowledge),
169
+ "max_boost_db": self.max_boost_db, "jammer": self.jammer, "seed": self.seed}
170
+
171
+
172
+ def as_threat(x: ThreatModel | dict[str, Any] | None) -> ThreatModel | None:
173
+ if x is None or isinstance(x, ThreatModel):
174
+ return x
175
+ return ThreatModel(**x)
@@ -0,0 +1,41 @@
1
+ """AirComp transmitter side: target functions and power control (FEATURES A1, A3, A8)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+
7
+ from aircompkit.aircomp.power_control import (
8
+ ChannelInversion,
9
+ FullPower,
10
+ OptimalPowerControl,
11
+ TruncatedInversion,
12
+ )
13
+ from aircompkit.core.registry import register
14
+
15
+
16
+ @register("aircomp", "sum")
17
+ @dataclass
18
+ class Sum:
19
+ """Target ``f = sum_k x_k``."""
20
+
21
+ def scale(self, K: int) -> float:
22
+ return 1.0
23
+
24
+
25
+ @register("aircomp", "mean")
26
+ @dataclass
27
+ class Mean:
28
+ """Target ``f = (1/K) sum_k x_k``. The receiver divides the sum estimate by ``K``."""
29
+
30
+ def scale(self, K: int) -> float:
31
+ return 1.0 / K
32
+
33
+
34
+ __all__ = [
35
+ "ChannelInversion",
36
+ "FullPower",
37
+ "Mean",
38
+ "OptimalPowerControl",
39
+ "Sum",
40
+ "TruncatedInversion",
41
+ ]
@@ -0,0 +1,42 @@
1
+ """Closed-form AirComp MSE expressions, used for validation and as plot references.
2
+
3
+ All expressions follow the model in ``aircompkit.aircomp.power_control`` and use the
4
+ *effective* noise variance (``sigma^2`` for complex symbols, ``sigma^2/2`` for real ones).
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from collections.abc import Sequence
10
+
11
+ import numpy as np
12
+
13
+
14
+ def channel_inversion_awgn_mse(
15
+ gains: Sequence[float], p_max: float | Sequence[float], noise_var: float
16
+ ) -> float:
17
+ """Non-fading channel ``|h_k|^2 = gains_k``: ``MSE = sigma^2 / min_k P_k g_k``."""
18
+ g = np.asarray(gains, float)
19
+ p = np.broadcast_to(np.asarray(p_max, float), g.shape)
20
+ return float(noise_var / np.min(p * g))
21
+
22
+
23
+ def truncated_inversion_rayleigh_mse(
24
+ mean_gains: Sequence[float],
25
+ p_max: float | Sequence[float],
26
+ threshold: float,
27
+ noise_var: float,
28
+ relative: bool = True,
29
+ ) -> float:
30
+ """Average MSE of truncated channel inversion under Rayleigh fading.
31
+
32
+ With ``|h_k|^2 ~ Exp(mean beta_k)``, device ``k`` is silent with probability
33
+ ``q_k = 1 - exp(-thr_k / beta_k)`` and then contributes error 1; ``eta = min_k P_k thr_k``
34
+ is deterministic, so
35
+
36
+ E[MSE] = sum_k q_k + sigma^2 / eta.
37
+ """
38
+ beta = np.asarray(mean_gains, float)
39
+ p = np.broadcast_to(np.asarray(p_max, float), beta.shape)
40
+ thr = threshold * beta if relative else np.full_like(beta, threshold)
41
+ q = 1.0 - np.exp(-thr / beta)
42
+ return float(q.sum() + noise_var / np.min(p * thr))