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.
- aircompkit-1.0.0/LICENSE +21 -0
- aircompkit-1.0.0/PKG-INFO +167 -0
- aircompkit-1.0.0/README.md +116 -0
- aircompkit-1.0.0/pyproject.toml +68 -0
- aircompkit-1.0.0/setup.cfg +4 -0
- aircompkit-1.0.0/src/aircompkit/__init__.py +32 -0
- aircompkit-1.0.0/src/aircompkit/__main__.py +5 -0
- aircompkit-1.0.0/src/aircompkit/adversary/__init__.py +175 -0
- aircompkit-1.0.0/src/aircompkit/aircomp/__init__.py +41 -0
- aircompkit-1.0.0/src/aircompkit/aircomp/analytic.py +42 -0
- aircompkit-1.0.0/src/aircompkit/aircomp/power_control.py +183 -0
- aircompkit-1.0.0/src/aircompkit/aircomp/preprocess.py +48 -0
- aircompkit-1.0.0/src/aircompkit/bench.py +159 -0
- aircompkit-1.0.0/src/aircompkit/channel/__init__.py +209 -0
- aircompkit-1.0.0/src/aircompkit/cli.py +165 -0
- aircompkit-1.0.0/src/aircompkit/core/__init__.py +1 -0
- aircompkit-1.0.0/src/aircompkit/core/registry.py +123 -0
- aircompkit-1.0.0/src/aircompkit/core/result.py +45 -0
- aircompkit-1.0.0/src/aircompkit/core/rng.py +47 -0
- aircompkit-1.0.0/src/aircompkit/core/scenario.py +226 -0
- aircompkit-1.0.0/src/aircompkit/defense/__init__.py +156 -0
- aircompkit-1.0.0/src/aircompkit/defense/evaluate.py +48 -0
- aircompkit-1.0.0/src/aircompkit/devices/__init__.py +79 -0
- aircompkit-1.0.0/src/aircompkit/learning/__init__.py +32 -0
- aircompkit-1.0.0/src/aircompkit/learning/aggregate.py +49 -0
- aircompkit-1.0.0/src/aircompkit/learning/array.py +140 -0
- aircompkit-1.0.0/src/aircompkit/learning/bank.py +86 -0
- aircompkit-1.0.0/src/aircompkit/learning/data.py +128 -0
- aircompkit-1.0.0/src/aircompkit/learning/fl.py +249 -0
- aircompkit-1.0.0/src/aircompkit/learning/models.py +89 -0
- aircompkit-1.0.0/src/aircompkit/learning/partition.py +58 -0
- aircompkit-1.0.0/src/aircompkit/metrics/__init__.py +36 -0
- aircompkit-1.0.0/src/aircompkit/metrics/privacy.py +36 -0
- aircompkit-1.0.0/src/aircompkit/plot/__init__.py +5 -0
- aircompkit-1.0.0/src/aircompkit/receiver/__init__.py +244 -0
- aircompkit-1.0.0/src/aircompkit/reproduce/__init__.py +26 -0
- aircompkit-1.0.0/src/aircompkit/reproduce/yang2020.py +182 -0
- aircompkit-1.0.0/src/aircompkit/reproduce/zhu2020.py +205 -0
- aircompkit-1.0.0/src/aircompkit.egg-info/PKG-INFO +167 -0
- aircompkit-1.0.0/src/aircompkit.egg-info/SOURCES.txt +48 -0
- aircompkit-1.0.0/src/aircompkit.egg-info/dependency_links.txt +1 -0
- aircompkit-1.0.0/src/aircompkit.egg-info/entry_points.txt +2 -0
- aircompkit-1.0.0/src/aircompkit.egg-info/requires.txt +30 -0
- aircompkit-1.0.0/src/aircompkit.egg-info/top_level.txt +1 -0
- aircompkit-1.0.0/tests/test_core.py +104 -0
- aircompkit-1.0.0/tests/test_p1_aircomp.py +253 -0
- aircompkit-1.0.0/tests/test_p2_mimo.py +247 -0
- aircompkit-1.0.0/tests/test_p3_learning.py +231 -0
- aircompkit-1.0.0/tests/test_p4_security.py +254 -0
- aircompkit-1.0.0/tests/test_p5_bench_checks.py +117 -0
aircompkit-1.0.0/LICENSE
ADDED
|
@@ -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
|
+
[](https://github.com/moyeendev/AirCompKit/actions/workflows/ci.yml)
|
|
55
|
+
[](https://github.com/moyeendev/AirCompKit/actions/workflows/reproduce.yml)
|
|
56
|
+
[](https://moyeendev.github.io/AirCompKit/)
|
|
57
|
+
[](LICENSE)
|
|
58
|
+
[](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
|
+
[](https://github.com/moyeendev/AirCompKit/actions/workflows/ci.yml)
|
|
4
|
+
[](https://github.com/moyeendev/AirCompKit/actions/workflows/reproduce.yml)
|
|
5
|
+
[](https://moyeendev.github.io/AirCompKit/)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](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,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,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))
|