aircompkit 1.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of aircompkit might be problematic. Click here for more details.
- aircompkit/__init__.py +32 -0
- aircompkit/__main__.py +5 -0
- aircompkit/adversary/__init__.py +175 -0
- aircompkit/aircomp/__init__.py +41 -0
- aircompkit/aircomp/analytic.py +42 -0
- aircompkit/aircomp/power_control.py +183 -0
- aircompkit/aircomp/preprocess.py +48 -0
- aircompkit/bench.py +159 -0
- aircompkit/channel/__init__.py +209 -0
- aircompkit/cli.py +165 -0
- aircompkit/core/__init__.py +1 -0
- aircompkit/core/registry.py +123 -0
- aircompkit/core/result.py +45 -0
- aircompkit/core/rng.py +47 -0
- aircompkit/core/scenario.py +226 -0
- aircompkit/defense/__init__.py +156 -0
- aircompkit/defense/evaluate.py +48 -0
- aircompkit/devices/__init__.py +79 -0
- aircompkit/learning/__init__.py +32 -0
- aircompkit/learning/aggregate.py +49 -0
- aircompkit/learning/array.py +140 -0
- aircompkit/learning/bank.py +86 -0
- aircompkit/learning/data.py +128 -0
- aircompkit/learning/fl.py +249 -0
- aircompkit/learning/models.py +89 -0
- aircompkit/learning/partition.py +58 -0
- aircompkit/metrics/__init__.py +36 -0
- aircompkit/metrics/privacy.py +36 -0
- aircompkit/plot/__init__.py +5 -0
- aircompkit/receiver/__init__.py +244 -0
- aircompkit/reproduce/__init__.py +26 -0
- aircompkit/reproduce/yang2020.py +182 -0
- aircompkit/reproduce/zhu2020.py +205 -0
- aircompkit-1.0.0.dist-info/METADATA +167 -0
- aircompkit-1.0.0.dist-info/RECORD +39 -0
- aircompkit-1.0.0.dist-info/WHEEL +5 -0
- aircompkit-1.0.0.dist-info/entry_points.txt +2 -0
- aircompkit-1.0.0.dist-info/licenses/LICENSE +21 -0
- aircompkit-1.0.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
"""Reproduction: G. Zhu, Y. Wang, K. Huang, "Broadband analog aggregation for low-latency
|
|
2
|
+
federated edge learning", IEEE Trans. Wireless Commun., 19(1), 2020 (arXiv:1812.11494).
|
|
3
|
+
|
|
4
|
+
Paper settings (Sec. VI-A): K = 200 devices uniform in a disc of radius R = 100 m, path-loss
|
|
5
|
+
exponent alpha = 3, M = 1000 sub-channels, average transmit power P0 = 0.1 W per device
|
|
6
|
+
(P0/M per sub-channel), noise N0 = -80 dBm per sub-channel, Rayleigh fading, truncated channel
|
|
7
|
+
inversion with an average power budget, MNIST split IID (200 equal shares) or non-IID
|
|
8
|
+
(400 label-sorted shards of 150, two per device).
|
|
9
|
+
|
|
10
|
+
* **Fig. 4** (SNR-truncation trade-off): ``rho0 = P0 / (M r_max^alpha E1(g_th))`` against the
|
|
11
|
+
truncation ratio ``1 - exp(-g_th)``, with r_max = 100. Checked against Monte Carlo: the
|
|
12
|
+
empirical truncation ratio, the empirical *average* transmit power (must equal P0/M) and
|
|
13
|
+
``eta/N0`` from the simulator's power control.
|
|
14
|
+
* **Fig. 7(b)** (alpha = 3): test accuracy against the cell-interior radius ratio R_in/R.
|
|
15
|
+
The paper uses a 582k-parameter CNN, an unstated number of rounds and a per-point grid
|
|
16
|
+
search over g_th; here an MLP (784-64-10), a fixed number of rounds and g_th = 0.1 are used,
|
|
17
|
+
so only the *trend* is compared. Values read by eye from the paper's bar chart (±0.02).
|
|
18
|
+
|
|
19
|
+
Known outcome (see the Reproductions page of the documentation): the data-limited rise reproduces; the SNR-limited
|
|
20
|
+
decline at large R_in does not appear with the stated SNRs, because SGD averages the
|
|
21
|
+
zero-mean channel noise over rounds (the paper's own Fig. 10 remarks on this robustness).
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
from __future__ import annotations
|
|
25
|
+
|
|
26
|
+
import json
|
|
27
|
+
from pathlib import Path
|
|
28
|
+
from typing import Any
|
|
29
|
+
|
|
30
|
+
import numpy as np
|
|
31
|
+
|
|
32
|
+
from aircompkit.aircomp.power_control import exp1
|
|
33
|
+
from aircompkit.core.registry import register
|
|
34
|
+
from aircompkit.core.rng import SeedTree
|
|
35
|
+
from aircompkit.core.scenario import Scenario
|
|
36
|
+
|
|
37
|
+
K, R, ALPHA, M = 200, 100.0, 3.0, 1000
|
|
38
|
+
P0, N0 = 0.1, 1e-11 # W; -80 dBm
|
|
39
|
+
FIG4_TRUNC = np.array([0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 0.95, 0.99])
|
|
40
|
+
FIG7_RATIOS = (0.1, 0.3, 0.5, 0.7, 0.9)
|
|
41
|
+
PAPER_FIG7B = {"noniid": [0.72, 0.80, 0.85, 0.83, 0.79], "iid": [0.80, 0.85, 0.90, 0.86, 0.81]}
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def rho0_db(trunc: float, r_max: float = R, alpha: float = ALPHA) -> float:
|
|
45
|
+
g = -np.log(1 - trunc)
|
|
46
|
+
return float(10 * np.log10(P0 / (M * r_max**alpha * exp1(g)) / N0))
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def scenario(threshold: float, alpha: float = ALPHA, K_: int = K, seed: int = 0) -> Scenario:
|
|
50
|
+
return Scenario(
|
|
51
|
+
devices={"name": "uniform_disc", "K": K_, "p_max": P0 / M, "r_min": 1.0, "r_max": R},
|
|
52
|
+
channel={"name": "rayleigh", "pathloss": {"exponent": alpha}},
|
|
53
|
+
power_control={"name": "truncated_inversion", "threshold": threshold, "budget": "average"},
|
|
54
|
+
receiver="eigen",
|
|
55
|
+
noise_var=N0,
|
|
56
|
+
symbols="real",
|
|
57
|
+
seed=seed,
|
|
58
|
+
)
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def fig4(trials: int = 20000, seed: int = 0) -> dict[str, Any]:
|
|
62
|
+
"""Closed form vs. Monte Carlo for one device at r_max = R."""
|
|
63
|
+
out: dict[str, Any] = {"truncation_ratio": FIG4_TRUNC.tolist(), "closed_form_db": [],
|
|
64
|
+
"sim_rho0_db": [], "sim_truncation": [], "sim_avg_power_over_budget": []}
|
|
65
|
+
for z in FIG4_TRUNC:
|
|
66
|
+
g = float(-np.log(1 - z))
|
|
67
|
+
sc = Scenario(devices={"name": "fixed", "K": 1, "p_max": P0 / M, "distances": [R]},
|
|
68
|
+
channel={"name": "rayleigh", "pathloss": {"exponent": ALPHA}},
|
|
69
|
+
power_control={"name": "truncated_inversion", "threshold": g, "budget": "average"},
|
|
70
|
+
receiver="eigen", noise_var=N0, symbols="complex", seed=seed)
|
|
71
|
+
h_act, h_est, beta = sc.sample_channels(SeedTree(seed), trials, np.array([R]))
|
|
72
|
+
lay = sc.design(h_act, h_est, beta, sc.devices.power_budgets())
|
|
73
|
+
out["closed_form_db"].append(rho0_db(z))
|
|
74
|
+
out["sim_rho0_db"].append(float(10 * np.log10(lay["eta"].mean() / N0)))
|
|
75
|
+
out["sim_truncation"].append(float(np.mean(lay["p"][:, 0] == 0)))
|
|
76
|
+
out["sim_avg_power_over_budget"].append(float(lay["p"][:, 0].mean() / (P0 / M)))
|
|
77
|
+
return out
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def fig7(data, rounds: int, threshold: float = 0.1, seed: int = 0,
|
|
81
|
+
ratios=FIG7_RATIOS, verbose: bool = False) -> dict[str, Any]:
|
|
82
|
+
from aircompkit.learning import FederatedConfig, train
|
|
83
|
+
|
|
84
|
+
out: dict[str, Any] = {"ratios": list(ratios), "rounds": rounds, "threshold": threshold}
|
|
85
|
+
for split, part in (("iid", "iid"), ("noniid", {"name": "shards", "shards_per_device": 2})):
|
|
86
|
+
ota, ideal, n_sched = [], [], []
|
|
87
|
+
for q in ratios:
|
|
88
|
+
sc = scenario(threshold, seed=seed)
|
|
89
|
+
cfg = {"dataset": data, "partition": part, "model": {"name": "mlp", "hidden": [64]},
|
|
90
|
+
"rounds": rounds, "eval_every": rounds, "lr": 0.1, "batch_size": 50,
|
|
91
|
+
"subchannels": M, "max_distance": q * R, "seed": seed}
|
|
92
|
+
try:
|
|
93
|
+
r = train(sc, FederatedConfig(**cfg))
|
|
94
|
+
ri = train(sc, FederatedConfig(**{**cfg, "aggregation": "ideal"}))
|
|
95
|
+
except ValueError: # nobody inside R_in for this placement
|
|
96
|
+
ota.append(float("nan"))
|
|
97
|
+
ideal.append(float("nan"))
|
|
98
|
+
n_sched.append(0)
|
|
99
|
+
continue
|
|
100
|
+
ota.append(float(r["test_acc"][-1]))
|
|
101
|
+
ideal.append(float(ri["test_acc"][-1]))
|
|
102
|
+
n_sched.append(int(r["n_scheduled"][0]))
|
|
103
|
+
if verbose:
|
|
104
|
+
print(f" {split:6s} R_in/R={q:.1f} devices={n_sched[-1]:3d} "
|
|
105
|
+
f"OTA {ota[-1]:.4f} ideal {ideal[-1]:.4f}")
|
|
106
|
+
out[split] = {"ota": ota, "ideal": ideal, "n_scheduled": n_sched, "paper": PAPER_FIG7B[split]}
|
|
107
|
+
return out
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
@register("reproduction", "zhu2020")
|
|
111
|
+
def run(trials: int | None = None, quick: bool = False, out: str | Path | None = None,
|
|
112
|
+
data_root: str | Path | None = None, rounds: int | None = None,
|
|
113
|
+
seed: int = 0) -> dict[str, Any]:
|
|
114
|
+
"""Fig. 4 always; Fig. 7(b) when MNIST is available locally (see ``learning.data``)."""
|
|
115
|
+
res: dict[str, Any] = {"fig4": fig4(trials or (4000 if quick else 20000), seed)}
|
|
116
|
+
_print_fig4(res["fig4"])
|
|
117
|
+
try:
|
|
118
|
+
from aircompkit.learning.data import mnist
|
|
119
|
+
|
|
120
|
+
data = mnist(root=data_root)
|
|
121
|
+
except FileNotFoundError as e:
|
|
122
|
+
res["fig7"] = None
|
|
123
|
+
print(f"\nFig. 7(b) skipped: {str(e).splitlines()[0]}")
|
|
124
|
+
else:
|
|
125
|
+
n_rounds = rounds or (15 if quick else 100)
|
|
126
|
+
print(f"\nFig. 7(b): accuracy vs R_in/R (alpha=3, MLP, {n_rounds} rounds, g_th=0.1)")
|
|
127
|
+
res["fig7"] = fig7(data, n_rounds, seed=seed, verbose=True)
|
|
128
|
+
_print_fig7(res["fig7"])
|
|
129
|
+
if out is not None:
|
|
130
|
+
out = Path(out)
|
|
131
|
+
out.mkdir(parents=True, exist_ok=True)
|
|
132
|
+
(out / "zhu2020.json").write_text(json.dumps(res, indent=2))
|
|
133
|
+
_plot(res, out / "zhu2020_fig4_fig7.png")
|
|
134
|
+
return res
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def _print_fig4(f4):
|
|
138
|
+
print("Zhu et al. 2020 Fig. 4: receive SNR vs truncation ratio (r_max = 100 m)")
|
|
139
|
+
print(" trunc closed-form dB sim dB sim trunc avg power / budget")
|
|
140
|
+
for row in zip(f4["truncation_ratio"], f4["closed_form_db"], f4["sim_rho0_db"],
|
|
141
|
+
f4["sim_truncation"], f4["sim_avg_power_over_budget"]):
|
|
142
|
+
print(" {:4.2f} {:10.3f} {:8.3f} {:7.4f} {:8.4f}".format(*row))
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
def _print_fig7(f7):
|
|
146
|
+
print(" R_in/R " + "".join(f"{q:>16.1f}" for q in f7["ratios"]))
|
|
147
|
+
for split in ("iid", "noniid"):
|
|
148
|
+
d = f7[split]
|
|
149
|
+
print(f" {split:6s} " + "".join(f" {o:5.3f}/{i:5.3f}/{p:4.2f}"
|
|
150
|
+
for o, i, p in zip(d["ota"], d["ideal"], d["paper"])))
|
|
151
|
+
print(" (OTA / ideal aggregation / paper)")
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def _plot(res, path):
|
|
155
|
+
try:
|
|
156
|
+
import matplotlib.pyplot as plt
|
|
157
|
+
except ImportError:
|
|
158
|
+
return
|
|
159
|
+
f4, f7 = res["fig4"], res["fig7"]
|
|
160
|
+
ncols = 2 if f7 else 1
|
|
161
|
+
fig, axes = plt.subplots(1, ncols, figsize=(4.8 * ncols, 3.6))
|
|
162
|
+
a = axes[0] if ncols == 2 else axes
|
|
163
|
+
a.plot(f4["truncation_ratio"], f4["closed_form_db"], "k-", label="closed form (paper eq. 17)")
|
|
164
|
+
a.plot(f4["sim_truncation"], f4["sim_rho0_db"], "o", mfc="none", label="AirCompKit Monte Carlo")
|
|
165
|
+
a.set_xlabel("truncation ratio")
|
|
166
|
+
a.set_ylabel("receive SNR (dB)")
|
|
167
|
+
a.set_title("(a) cf. Zhu et al. Fig. 4", fontsize=9)
|
|
168
|
+
a.grid(alpha=0.3)
|
|
169
|
+
a.legend(fontsize=7)
|
|
170
|
+
if f7:
|
|
171
|
+
b = axes[1]
|
|
172
|
+
x = np.asarray(f7["ratios"])
|
|
173
|
+
for split, c in (("iid", "tab:green"), ("noniid", "tab:blue")):
|
|
174
|
+
b.plot(x, f7[split]["ota"], "o-", color=c, label=f"AirCompKit OTA, {split}")
|
|
175
|
+
b.plot(x, f7[split]["ideal"], ":", color=c, label=f"ideal aggregation, {split}")
|
|
176
|
+
b.plot(x, f7[split]["paper"], "x--", color=c, lw=0.8, label=f"paper (CNN), {split}")
|
|
177
|
+
b.set_xlabel(r"$R_{in}/R$")
|
|
178
|
+
b.set_ylabel("test accuracy")
|
|
179
|
+
b.set_title(rf"(b) cf. Zhu et al. Fig. 7(b), $\alpha$=3, {f7['rounds']} rounds", fontsize=9)
|
|
180
|
+
b.grid(alpha=0.3)
|
|
181
|
+
b.legend(fontsize=6)
|
|
182
|
+
fig.tight_layout()
|
|
183
|
+
fig.savefig(path, dpi=160)
|
|
184
|
+
print(f"saved {path}")
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
def check(res: dict[str, Any]) -> list[tuple[str, bool, str]]:
|
|
188
|
+
"""Tolerance checks used by ``aircompkit reproduce zhu2020 --check`` (reproduction CI)."""
|
|
189
|
+
f4 = res["fig4"]
|
|
190
|
+
drho = max(abs(a - b) for a, b in zip(f4["sim_rho0_db"], f4["closed_form_db"]))
|
|
191
|
+
dtr = max(abs(a - b) for a, b in zip(f4["sim_truncation"], f4["truncation_ratio"]))
|
|
192
|
+
dpow = max(abs(a - 1) for a, b in zip(f4["sim_avg_power_over_budget"], f4["truncation_ratio"]) if b <= 0.9)
|
|
193
|
+
out = [("Fig. 4: designed rho_0 = closed form (0.1 dB)", drho <= 0.1, f"max {drho:.3g} dB"),
|
|
194
|
+
("Fig. 4: truncation ratio as designed (0.03)", dtr <= 0.03, f"max {dtr:.3f}"),
|
|
195
|
+
("Fig. 4: average power = budget (25 %, ratio <= 0.9)", dpow <= 0.25, f"max {dpow:.3f}")]
|
|
196
|
+
f7 = res.get("fig7")
|
|
197
|
+
if f7:
|
|
198
|
+
gaps = [abs(a - b) for s in ("iid", "noniid") for a, b in zip(f7[s]["ota"], f7[s]["ideal"])
|
|
199
|
+
if np.isfinite(a)]
|
|
200
|
+
out.append(("Fig. 7(b): OTA-FL within 2 points of ideal FedAvg", max(gaps) <= 0.02,
|
|
201
|
+
f"max gap {max(gaps):.3f}"))
|
|
202
|
+
acc = dict(zip(f7["ratios"], f7["noniid"]["ota"]))
|
|
203
|
+
out.append(("Fig. 7(b): non-IID accuracy rises with R_in (data-limited regime)",
|
|
204
|
+
acc[0.9] > acc[0.3], f"{acc[0.3]:.3f} -> {acc[0.9]:.3f}"))
|
|
205
|
+
return out
|
|
@@ -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,39 @@
|
|
|
1
|
+
aircompkit/__init__.py,sha256=UbdqzYnos-LVyYw1PKzP23t0PeRDyF5QcKuUMuqrnks,675
|
|
2
|
+
aircompkit/__main__.py,sha256=oLKlibDWgeXWoSdLhuizKVa3OsgLm5kCUNjYyN3d39M,62
|
|
3
|
+
aircompkit/bench.py,sha256=ftn_ghwJYU0J3SEaQ9cKNxP8PzaDAVkUEI8kxzdlaeU,6846
|
|
4
|
+
aircompkit/cli.py,sha256=AxgWgFNsMsKSjgB9iDKaX1hY8BlsXntAA7VWrN6CR0A,6717
|
|
5
|
+
aircompkit/adversary/__init__.py,sha256=h-CLKhFw_5SNcEVE7tTFZ0Bca1O5ckOajRMEnjbyw0I,6244
|
|
6
|
+
aircompkit/aircomp/__init__.py,sha256=gPpOT98hIzPUX6cSiW3ybjOWNbswDL2jF4FE9dPyFdo,828
|
|
7
|
+
aircompkit/aircomp/analytic.py,sha256=OEuv70l6FJZn43fufvXZj1NahycFHLwG-CH8TGxE_g0,1492
|
|
8
|
+
aircompkit/aircomp/power_control.py,sha256=eE3EybRWw-ev0RCoU4x1wb2EqqT1zxwhWbpK9A5S2V8,6966
|
|
9
|
+
aircompkit/aircomp/preprocess.py,sha256=vH2YfteZM2PK8gbcbP_UDh4Lo7Sem0R7WSC1JrrVas8,2004
|
|
10
|
+
aircompkit/channel/__init__.py,sha256=Gt694Sr78qeIdnBGU2dWem-2GsC853EeuvN2zWIk8Zk,7530
|
|
11
|
+
aircompkit/core/__init__.py,sha256=v7m95EVkCpNM99NYx3JZgGc7S8CwHuI5Xi_9Kf-6ejQ,93
|
|
12
|
+
aircompkit/core/registry.py,sha256=Xg5NuoMxbyL9OWs4Z4kkLlaXgznkFzqsVFrvNLZiO2Y,3682
|
|
13
|
+
aircompkit/core/result.py,sha256=PnXLsgXVbLB2Tm0eGzFOEAcCiOuZjf8STNhkWLISAVg,1723
|
|
14
|
+
aircompkit/core/rng.py,sha256=MRVl3pcy8-H6dt6sQejlubmvrVNf_ejObKvMQR6cMMI,1836
|
|
15
|
+
aircompkit/core/scenario.py,sha256=DXzNCNOnmlMpuXxFyJ5sGdz9-JFeIbZ2a-0K5eBde7c,9327
|
|
16
|
+
aircompkit/defense/__init__.py,sha256=uroC0Burcp8x79v76YWQQa5fefGdVLnmjJhQkhJsIpY,5537
|
|
17
|
+
aircompkit/defense/evaluate.py,sha256=hH3vMSBubZqolA4TzSDKLJqfQpbdmKVCkiWF_UE4H-8,2222
|
|
18
|
+
aircompkit/devices/__init__.py,sha256=U0Gyjqp-mjqD28jzriV6rg6qJZaUPFr3lNwnxQbj0ps,2643
|
|
19
|
+
aircompkit/learning/__init__.py,sha256=ZS1VgWJEw_zQ9vYo0khJaBvTpvfdk6QXuHg_EztQfUc,974
|
|
20
|
+
aircompkit/learning/aggregate.py,sha256=VV1K-Jqsv-EoEj0tlpd1bHCKBAZsWfz9H0j9LRscJRU,1972
|
|
21
|
+
aircompkit/learning/array.py,sha256=7Zms_sWtQ93ld4NfzqHdmBdMd4EWiDEnXdDUMF4ODEA,6477
|
|
22
|
+
aircompkit/learning/bank.py,sha256=kNalm3PCBvLGaW0PNy8xpX1jD41M5lHFMa-yKxrKLwE,3773
|
|
23
|
+
aircompkit/learning/data.py,sha256=yNqrksCKKRyil8cGyK0D08P-N0_d-x8BFQ_SgN107V0,4505
|
|
24
|
+
aircompkit/learning/fl.py,sha256=l3fE1aCn1o1tfcQNmEgRa3nNXvz5eDGYxURNBYidsgE,10582
|
|
25
|
+
aircompkit/learning/models.py,sha256=Rd_jh7B7FYpKotX3Uv-JEMfy-I8WGFdX1WzzHHCHBUQ,3282
|
|
26
|
+
aircompkit/learning/partition.py,sha256=EbodoMtrLCR9Vgf20c6wuOSaAFErvhpr459pqWjsRQ4,2128
|
|
27
|
+
aircompkit/metrics/__init__.py,sha256=wz974QJVRGTE0BRS8rSJJLgJe9n9J5DIAhY5aM-hw-U,1421
|
|
28
|
+
aircompkit/metrics/privacy.py,sha256=dE2I9P-htdt_c800Q9_zqhh_GUuNF17pvtjvaQe0mxw,1787
|
|
29
|
+
aircompkit/plot/__init__.py,sha256=cIRXdGfeaOu5VNkczmPIXsgP-oh8HE399_-IWCIwkjw,148
|
|
30
|
+
aircompkit/receiver/__init__.py,sha256=ciw_atwuuADiz9ZrkUrg9X7MM5g4fkJPeyWxwWVJ0c8,10522
|
|
31
|
+
aircompkit/reproduce/__init__.py,sha256=va-1Y-iRJAbhD-igiBrnZPnT3QJdB2QO6nuK1TfvYlU,1047
|
|
32
|
+
aircompkit/reproduce/yang2020.py,sha256=PZQ8w9k8N51drP0xds4i8eXUACzvSNf92_JkSwpffCs,8020
|
|
33
|
+
aircompkit/reproduce/zhu2020.py,sha256=MP4r0mXQu-lcQ-Gv1zAYnlQP6Lo9FSKHtQPQaYHA5FM,10261
|
|
34
|
+
aircompkit-1.0.0.dist-info/licenses/LICENSE,sha256=Io7Ug5Vk-OkW8qR1Y4pCenRP7phbqR_CUE8f4KprR7o,1066
|
|
35
|
+
aircompkit-1.0.0.dist-info/METADATA,sha256=uBFQrMf5zeI1pk-TsEQnOkx5EjOrAQQtt6by9XZW41o,7838
|
|
36
|
+
aircompkit-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
37
|
+
aircompkit-1.0.0.dist-info/entry_points.txt,sha256=icpnYhXDR6nEAlulAJPs82aOxR7Cjh_a8NbeSAbw-NQ,51
|
|
38
|
+
aircompkit-1.0.0.dist-info/top_level.txt,sha256=-QdTTuOc1HjtHGV5GrrBlcxhv33QAK7tAI4Xw4xoD6c,11
|
|
39
|
+
aircompkit-1.0.0.dist-info/RECORD,,
|
|
@@ -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 @@
|
|
|
1
|
+
aircompkit
|