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.

Files changed (39) hide show
  1. aircompkit/__init__.py +32 -0
  2. aircompkit/__main__.py +5 -0
  3. aircompkit/adversary/__init__.py +175 -0
  4. aircompkit/aircomp/__init__.py +41 -0
  5. aircompkit/aircomp/analytic.py +42 -0
  6. aircompkit/aircomp/power_control.py +183 -0
  7. aircompkit/aircomp/preprocess.py +48 -0
  8. aircompkit/bench.py +159 -0
  9. aircompkit/channel/__init__.py +209 -0
  10. aircompkit/cli.py +165 -0
  11. aircompkit/core/__init__.py +1 -0
  12. aircompkit/core/registry.py +123 -0
  13. aircompkit/core/result.py +45 -0
  14. aircompkit/core/rng.py +47 -0
  15. aircompkit/core/scenario.py +226 -0
  16. aircompkit/defense/__init__.py +156 -0
  17. aircompkit/defense/evaluate.py +48 -0
  18. aircompkit/devices/__init__.py +79 -0
  19. aircompkit/learning/__init__.py +32 -0
  20. aircompkit/learning/aggregate.py +49 -0
  21. aircompkit/learning/array.py +140 -0
  22. aircompkit/learning/bank.py +86 -0
  23. aircompkit/learning/data.py +128 -0
  24. aircompkit/learning/fl.py +249 -0
  25. aircompkit/learning/models.py +89 -0
  26. aircompkit/learning/partition.py +58 -0
  27. aircompkit/metrics/__init__.py +36 -0
  28. aircompkit/metrics/privacy.py +36 -0
  29. aircompkit/plot/__init__.py +5 -0
  30. aircompkit/receiver/__init__.py +244 -0
  31. aircompkit/reproduce/__init__.py +26 -0
  32. aircompkit/reproduce/yang2020.py +182 -0
  33. aircompkit/reproduce/zhu2020.py +205 -0
  34. aircompkit-1.0.0.dist-info/METADATA +167 -0
  35. aircompkit-1.0.0.dist-info/RECORD +39 -0
  36. aircompkit-1.0.0.dist-info/WHEEL +5 -0
  37. aircompkit-1.0.0.dist-info/entry_points.txt +2 -0
  38. aircompkit-1.0.0.dist-info/licenses/LICENSE +21 -0
  39. aircompkit-1.0.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,226 @@
1
+ """Scenario: one object (and one config file) that fully specifies a run (FEATURES C1, C5, A8).
2
+
3
+ P1 covers *computation mode*: Monte Carlo AirComp of random unit-power vectors over a
4
+ single-antenna multiple-access channel. Later phases add the receiver, adversary, defence
5
+ and learning task to the same object.
6
+
7
+ Random streams (see ``SeedTree``): ``devices`` (placement),
8
+ ``channel`` (fading, shadowing), ``data`` (symbols), ``noise``. Changing the power-control
9
+ scheme or the symbol dimension therefore leaves the channel realisations unchanged, so
10
+ schemes are compared on identical channels.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import dataclasses
16
+ import platform
17
+ from dataclasses import dataclass
18
+ from pathlib import Path
19
+ from typing import Any
20
+
21
+ import numpy as np
22
+
23
+ from aircompkit.core.registry import build, spec_of
24
+ from aircompkit.core.result import Result
25
+ from aircompkit.core.rng import SeedTree
26
+
27
+ _SYMBOLS = ("real", "complex")
28
+
29
+
30
+ @dataclass
31
+ class Scenario:
32
+ devices: Any
33
+ channel: Any = "rayleigh"
34
+ power_control: Any = "optimal"
35
+ receiver: Any = "maxmin"
36
+ impairments: Any = None
37
+ target: Any = "sum"
38
+ noise_var: float = 1.0
39
+ symbols: str = "real"
40
+ seed: int = 0
41
+
42
+ def __post_init__(self) -> None:
43
+ from aircompkit.channel import as_impairments
44
+
45
+ self.devices = build("devices", self.devices)
46
+ self.channel = build("channel", self.channel)
47
+ self.power_control = build("power_control", self.power_control)
48
+ self.receiver = build("receiver", self.receiver)
49
+ self.impairments = as_impairments(self.impairments)
50
+ self.target = build("aircomp", self.target)
51
+ if self.symbols not in _SYMBOLS:
52
+ raise ValueError(f"symbols must be one of {_SYMBOLS}")
53
+ if self.noise_var < 0:
54
+ raise ValueError("noise_var must be >= 0")
55
+
56
+ # ------------------------------------------------------------------ config I/O
57
+ def to_dict(self) -> dict[str, Any]:
58
+ return {
59
+ "devices": spec_of("devices", self.devices),
60
+ "channel": spec_of("channel", self.channel),
61
+ "power_control": spec_of("power_control", self.power_control),
62
+ "receiver": spec_of("receiver", self.receiver),
63
+ "impairments": dataclasses.asdict(self.impairments),
64
+ "target": spec_of("aircomp", self.target),
65
+ "noise_var": float(self.noise_var),
66
+ "symbols": self.symbols,
67
+ "seed": int(self.seed),
68
+ }
69
+
70
+ @classmethod
71
+ def from_dict(cls, cfg: dict[str, Any]) -> Scenario:
72
+ known = {"devices", "channel", "power_control", "receiver", "impairments", "target",
73
+ "noise_var", "symbols", "seed"}
74
+ extra = set(cfg) - known - {"run", "learning"}
75
+ if extra:
76
+ raise KeyError(f"unknown scenario keys: {sorted(extra)}")
77
+ return cls(**{k: v for k, v in cfg.items() if k in known})
78
+
79
+ @classmethod
80
+ def from_yaml(cls, path: str | Path) -> Scenario:
81
+ return cls.from_dict(load_yaml(path))
82
+
83
+ def to_yaml(self, path: str | Path) -> None:
84
+ import yaml
85
+
86
+ Path(path).write_text(yaml.safe_dump(self.to_dict(), sort_keys=False))
87
+
88
+ def replace(self, **changes: Any) -> Scenario:
89
+ """Copy with some fields changed (handy for sweeps)."""
90
+ cfg = self.to_dict()
91
+ cfg.update(changes)
92
+ return Scenario.from_dict(cfg)
93
+
94
+ # ------------------------------------------------------------------ simulation
95
+ @property
96
+ def noise_var_eff(self) -> float:
97
+ return self.noise_var / 2 if self.symbols == "real" else self.noise_var
98
+
99
+ def sample_channels(
100
+ self, tree: SeedTree, trials: int, distances: np.ndarray | None
101
+ ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
102
+ """Draw ``(h_actual, h_estimated, beta)`` for all ``K`` devices from ``tree``'s
103
+ ``channel`` and ``impairments`` streams. Shapes ``[T, K, N]``, ``[T, K, N]``, ``[T, K]``."""
104
+ h, beta = self.channel.sample(tree.generator("channel"), trials, self.devices.K, distances)
105
+ h_act, h_est = self.impairments.apply(tree.generator("impairments"), h, beta)
106
+ return h_act, h_est, beta
107
+
108
+ def design(
109
+ self, h_act: np.ndarray, h_est: np.ndarray, beta: np.ndarray, p_max: np.ndarray
110
+ ) -> dict[str, np.ndarray]:
111
+ """Receiver + power control for the devices whose channels are given (any subset).
112
+
113
+ Returns ``m [T, N]``, ``c_act``/``c_est`` (effective scalar channels ``m^H h``),
114
+ ``p``, ``b`` (transmit coefficients), ``eta`` and ``amp = c_act b / sqrt(eta)``, the
115
+ per-device amplitude with which a unit symbol arrives in the estimate (1 is perfect
116
+ alignment, 0 a silent device).
117
+ """
118
+ nv = self.noise_var_eff
119
+ m = self.receiver(h_est, p_max, nv) # [T, N], unit norm
120
+ c_est = np.einsum("tkn,tn->tk", h_est, m.conj())
121
+ c_act = np.einsum("tkn,tn->tk", h_act, m.conj())
122
+ g = np.abs(c_est) ** 2
123
+ p, eta = self.power_control(g, beta, p_max, nv)
124
+ if np.any(p < 0) or (
125
+ getattr(self.power_control, "peak_constrained", True)
126
+ and np.any(p > p_max[None, :] * (1 + 1e-9))
127
+ ):
128
+ raise RuntimeError(f"{type(self.power_control).__name__} violated power budgets")
129
+ with np.errstate(divide="ignore", invalid="ignore"):
130
+ phase = np.where(g > 0, np.conj(c_est) / np.sqrt(g), 0.0)
131
+ b = np.sqrt(p) * phase
132
+ amp = c_act * b / np.sqrt(eta)[:, None]
133
+ return {"m": m, "c_act": c_act, "c_est": c_est, "p": p, "b": b, "eta": eta, "amp": amp}
134
+
135
+ def run(self, trials: int = 1000, dim: int = 16, batch: int = 1024) -> Result:
136
+ """Run ``trials`` independent channel realisations.
137
+
138
+ For each trial, the analytical conditional MSE is computed from the channel and
139
+ transmit coefficients. If ``dim > 0``, the AirComp of ``dim``-dimensional random
140
+ symbol vectors is also simulated at signal level and its empirical MSE recorded.
141
+ ``batch`` bounds memory (``batch * K * dim`` complex numbers); results depend on
142
+ ``(seed, trials, dim, batch)``.
143
+
144
+ Returned arrays (per trial unless noted): ``mse`` (analytical), ``mse_empirical``,
145
+ ``eta``, ``n_active`` (devices with ``p_k > 0``), ``power`` (``[trials, K]``).
146
+ """
147
+ from aircompkit.metrics import mse_given_channel
148
+
149
+ if trials < 1 or dim < 0 or batch < 1:
150
+ raise ValueError("need trials >= 1, dim >= 0, batch >= 1")
151
+ tree = SeedTree(self.seed)
152
+ K = self.devices.K
153
+ p_max = self.devices.power_budgets()
154
+ dist = self.devices.sample_distances(tree.generator("devices"))
155
+ h_act, h_est, beta = self.sample_channels(tree, trials, dist)
156
+ lay = self.design(h_act, h_est, beta, p_max)
157
+ p, eta, b, m = lay["p"], lay["eta"], lay["b"], lay["m"]
158
+
159
+ real = self.symbols == "real"
160
+ s = self.target.scale(K)
161
+ # Exact conditional MSE given the *actual* channel: m^H n ~ CN(0, sigma^2) as ||m|| = 1.
162
+ mse = s**2 * mse_given_channel(lay["c_act"], b, eta, self.noise_var_eff, real)
163
+
164
+ arrays: dict[str, np.ndarray] = {
165
+ "mse": mse,
166
+ "eta": eta,
167
+ "n_active": (p > 0).sum(axis=1).astype(float),
168
+ "power": p,
169
+ }
170
+ if dim > 0:
171
+ arrays["mse_empirical"] = s**2 * self._simulate(
172
+ h_act * b[..., None], m, eta, dim, batch,
173
+ tree.generator("data"), tree.generator("noise"),
174
+ )
175
+
176
+ meta = {
177
+ "trials": trials,
178
+ "dim": dim,
179
+ "batch": batch,
180
+ "aircompkit": _version(),
181
+ "numpy": np.__version__,
182
+ "python": platform.python_version(),
183
+ }
184
+ return Result(config=self.to_dict(), arrays=arrays, meta=meta)
185
+
186
+ def _simulate(self, hb, m, eta, dim, batch, rng_data, rng_noise) -> np.ndarray:
187
+ """Signal-level AirComp at the antenna array; returns per-trial empirical MSE of the sum.
188
+
189
+ ``hb [T, K, N]`` holds ``h_k b_k`` with the actual channel, ``m [T, N]`` the combiner.
190
+ """
191
+ T, K, N = hb.shape
192
+ real = self.symbols == "real"
193
+ out = np.empty(T)
194
+ for lo in range(0, T, batch):
195
+ hi = min(lo + batch, T)
196
+ n = hi - lo
197
+ if real:
198
+ x = rng_data.standard_normal((n, K, dim))
199
+ else:
200
+ z = rng_data.standard_normal((n, K, dim, 2))
201
+ x = (z[..., 0] + 1j * z[..., 1]) / np.sqrt(2)
202
+ zn = rng_noise.standard_normal((n, N, dim, 2))
203
+ noise = np.sqrt(self.noise_var / 2) * (zn[..., 0] + 1j * zn[..., 1])
204
+ y = np.einsum("tkn,tkd->tnd", hb[lo:hi], x) + noise
205
+ r = np.einsum("tn,tnd->td", m[lo:hi].conj(), y)
206
+ f_hat = r / np.sqrt(eta[lo:hi])[:, None]
207
+ if real:
208
+ f_hat = f_hat.real
209
+ f = x.sum(axis=1)
210
+ out[lo:hi] = np.mean(np.abs(f_hat - f) ** 2, axis=1)
211
+ return out
212
+
213
+
214
+ def load_yaml(path: str | Path) -> dict[str, Any]:
215
+ import yaml
216
+
217
+ cfg = yaml.safe_load(Path(path).read_text())
218
+ if not isinstance(cfg, dict):
219
+ raise TypeError(f"{path}: expected a mapping at top level")
220
+ return cfg
221
+
222
+
223
+ def _version() -> str:
224
+ from aircompkit import __version__
225
+
226
+ return __version__
@@ -0,0 +1,156 @@
1
+ """Defences for over-the-air aggregation (FEATURES §6).
2
+
3
+ A defence is a stateful object with ``reset(K)`` and ``aggregate(rx, ctx)``. ``rx`` is the
4
+ round's ``Receiver``; the defence decides how the devices
5
+ use the channel (``rx.transmit(ids)`` for AirComp, ``rx.transmit_orthogonal()`` for
6
+ digital baselines) and returns ``(est, keff, flagged)``: ``est`` estimates
7
+ ``sum_{k honest} x_k`` in normalised symbols up to the factor ``keff`` (the server divides
8
+ by ``keff``), and ``flagged`` is the set of devices it excluded.
9
+
10
+ * ``none``: plain AirComp (receive with the design combiner ``m``);
11
+ * ``genie``: null-steering with the true attacker set (an oracle upper bound);
12
+ * ``group_gm``: random groups, one AirComp per group, geometric median of the group means
13
+ (robust AirComp over repeated transmissions; Sifaou & Li; Huang et al.);
14
+ * ``digital_robust``: orthogonal access and a robust rule (``mean``, ``median``,
15
+ ``trimmed_mean``, ``krum``, ``geomed``) on the per-device estimates.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ from dataclasses import dataclass
21
+
22
+ import numpy as np
23
+
24
+ from aircompkit.core.registry import register
25
+
26
+
27
+ # ------------------------------------------------------------------- primitives
28
+ def nulling_combiner(A, flagged, eta, sigma2):
29
+ """Regularised LS combiner with hard nulls on the flagged signatures.
30
+ Returns ``(w, keep)``; ``w^H a_k ~ sqrt(eta)`` for kept devices, ``0`` for flagged."""
31
+ N, K = A.shape
32
+ keep = np.ones(K, bool)
33
+ keep[list(flagged)] = False
34
+ if len(flagged):
35
+ Qf, _ = np.linalg.qr(A[:, list(flagged)], mode="complete")
36
+ Q = Qf[:, len(flagged):]
37
+ else:
38
+ Q = np.eye(N, dtype=complex)
39
+ Ah = Q.conj().T @ A[:, keep]
40
+ v = np.linalg.solve(Ah @ Ah.conj().T + sigma2 * np.eye(Q.shape[1]), Ah.sum(axis=1) * np.sqrt(eta))
41
+ return Q @ v, keep
42
+
43
+
44
+ def geometric_median(X: np.ndarray, iters: int = 100, eps: float = 1e-8) -> np.ndarray:
45
+ """Weiszfeld iterations on the rows of ``X`` (real or complex)."""
46
+ z = X.mean(axis=0)
47
+ for _ in range(iters):
48
+ dist = np.maximum(np.linalg.norm(X - z, axis=1), eps)
49
+ z_new = (X / dist[:, None]).sum(axis=0) / (1 / dist).sum()
50
+ if np.linalg.norm(z_new - z) < 1e-10 * (1 + np.linalg.norm(z)):
51
+ return z_new
52
+ z = z_new
53
+ return z
54
+
55
+
56
+ def krum(X: np.ndarray, f: int) -> np.ndarray:
57
+ """Krum (Blanchard et al. 2017): the row with the smallest sum of squared distances to its
58
+ ``K - f - 2`` nearest neighbours."""
59
+ K = len(X)
60
+ m = max(K - f - 2, 1)
61
+ D = np.sum(np.abs(X[:, None, :] - X[None, :, :]) ** 2, axis=2)
62
+ scores = np.sort(D, axis=1)[:, 1:m + 1].sum(axis=1)
63
+ return X[int(np.argmin(scores))]
64
+
65
+
66
+ # ------------------------------------------------------------------- defences
67
+ @register("defense", "none")
68
+ @dataclass
69
+ class NoDefense:
70
+ """Plain AirComp: ``m^H Y / sqrt(eta)``, divided by the number of transmitting devices."""
71
+
72
+ def reset(self, K: int) -> None:
73
+ pass
74
+
75
+ def aggregate(self, rx, ctx):
76
+ r = rx.transmit()
77
+ return r.m.conj() @ r.Y / np.sqrt(r.eta), float(len(r.ids)), set()
78
+
79
+
80
+ def _nulled(r, flagged):
81
+ w, keep = nulling_combiner(r.A, sorted(flagged), r.eta, r.noise_var)
82
+ keff = float((w.conj() @ r.A[:, keep]).sum().real / np.sqrt(r.eta))
83
+ return w.conj() @ r.Y / np.sqrt(r.eta), keff
84
+
85
+
86
+ @register("defense", "genie")
87
+ @dataclass
88
+ class Genie:
89
+ """Oracle: null-steer exactly the true attackers (upper bound for detection-based defences)."""
90
+
91
+ def reset(self, K: int) -> None:
92
+ pass
93
+
94
+ def aggregate(self, rx, ctx):
95
+ r = rx.transmit()
96
+ flagged = {int(k) for k in ctx["attackers"]}
97
+ est, keff = _nulled(r, flagged)
98
+ return est, keff, flagged
99
+
100
+
101
+ @register("defense", "group_gm")
102
+ @dataclass
103
+ class GroupGM:
104
+ """Random groups, one AirComp per group (``groups`` channel uses), geometric median of the
105
+ normalised group means."""
106
+
107
+ groups: int = 8
108
+
109
+ def reset(self, K: int) -> None:
110
+ pass
111
+
112
+ def aggregate(self, rx, ctx):
113
+ K = rx.x.shape[0]
114
+ perm = rx.rng.permutation(K)
115
+ means = []
116
+ for g, grp in enumerate(np.array_split(perm, self.groups)):
117
+ r = rx.transmit(np.sort(grp), tag=f"group{g}")
118
+ means.append(r.m.conj() @ r.Y / (np.sqrt(r.eta) * len(grp)))
119
+ M = np.array(means)
120
+ z = geometric_median(np.concatenate([M.real, M.imag], axis=1))
121
+ L = M.shape[1]
122
+ return z[:L] + 1j * z[L:], 1.0, set()
123
+
124
+
125
+ @register("defense", "digital_robust")
126
+ @dataclass
127
+ class DigitalRobust:
128
+ """Orthogonal access (K channel uses, full power, MRC) + a robust aggregation rule."""
129
+
130
+ rule: str = "median"
131
+ trim: float = 0.1
132
+ f: int = 0
133
+
134
+ def __post_init__(self) -> None:
135
+ if self.rule not in ("mean", "median", "trimmed_mean", "krum", "geomed"):
136
+ raise ValueError(f"unknown rule {self.rule!r}")
137
+
138
+ def reset(self, K: int) -> None:
139
+ pass
140
+
141
+ def aggregate(self, rx, ctx):
142
+ X = rx.transmit_orthogonal()
143
+ R = np.concatenate([X.real, X.imag], axis=1)
144
+ if self.rule == "mean":
145
+ z = R.mean(axis=0)
146
+ elif self.rule == "median":
147
+ z = np.median(R, axis=0)
148
+ elif self.rule == "trimmed_mean":
149
+ k = int(self.trim * len(R))
150
+ z = np.sort(R, axis=0)[k:len(R) - k].mean(axis=0)
151
+ elif self.rule == "krum":
152
+ z = krum(R, self.f or len(ctx["attackers"]))
153
+ else:
154
+ z = geometric_median(R)
155
+ L = X.shape[1]
156
+ return z[:L] + 1j * z[L:], 1.0, set()
@@ -0,0 +1,48 @@
1
+ """Detection Monte Carlo on a gradient bank (FEATURES M3): stored honest updates, a fresh
2
+ channel, fresh attacker set and fresh noise per trial, one received block, one detection."""
3
+
4
+ from __future__ import annotations
5
+
6
+ from typing import Any
7
+
8
+ import numpy as np
9
+
10
+ from aircompkit.core.rng import SeedTree
11
+ from aircompkit.learning.array import Receiver, normalise, pack
12
+
13
+
14
+ def detection_sweep(scenario, updates: list[np.ndarray], attack: Any, n_attackers: int,
15
+ detector: Any, trials: int = 200, clip: float | None = None,
16
+ seed: int = 0) -> dict[str, float]:
17
+ """Per-trial: pick a stored update matrix ``[K, d]``, draw ``n_attackers`` attackers, let
18
+ them run ``attack`` on the array-level channel, run ``detector.detect(Y, A, noise_var)``.
19
+
20
+ Returns ``tpr`` (detected attackers / attackers), ``fp`` (honest devices flagged per trial),
21
+ ``cover`` (all attackers flagged) and ``exact`` (flagged set == attacker set).
22
+ """
23
+ from aircompkit.core.registry import build
24
+
25
+ attack = build("attack", attack)
26
+ tree = SeedTree(seed)
27
+ rng = tree.generator("trials")
28
+ dist = scenario.devices.sample_distances(SeedTree(scenario.seed).generator("devices"))
29
+ p_max = scenario.devices.power_budgets()
30
+ tp = fp = cover = exact = 0
31
+ for t in range(trials):
32
+ G = np.asarray(updates[rng.integers(len(updates))], float)
33
+ K = G.shape[0]
34
+ byz = np.sort(rng.choice(K, n_attackers, replace=False)) if n_attackers else np.zeros(0, int)
35
+ hon = np.setdiff1d(np.arange(K), byz)
36
+ x, _ = normalise(G, clip)
37
+ gref = pack(G[hon].mean(axis=0)) # scale is irrelevant: attacks normalise it
38
+ rx = Receiver(scenario, x, p_max, dist, tree.child("trial").child(str(t)),
39
+ attackers=byz, attack=attack if n_attackers else None, gref=gref)
40
+ r = rx.transmit()
41
+ flg = {int(k) for k in detector.detect(r.Y, r.A, r.noise_var)}
42
+ B = set(byz.tolist())
43
+ tp += len(flg & B)
44
+ fp += len(flg - B)
45
+ cover += int(flg >= B)
46
+ exact += int(flg == B)
47
+ return {"tpr": tp / max(n_attackers * trials, 1), "fp": fp / trials,
48
+ "cover": cover / trials, "exact": exact / trials}
@@ -0,0 +1,79 @@
1
+ """Device populations: count, power budgets, placement (FEATURES D1, D2).
2
+
3
+ A device population answers two questions for the simulator:
4
+
5
+ * ``power_budgets()``: per-device transmit-power limit ``P_k`` (linear units, per symbol);
6
+ * ``sample_distances(rng)``: distance of each device to the server, or ``None`` when the
7
+ channel has no large-scale model.
8
+
9
+ Placement is drawn once per scenario (from the ``devices`` random stream) and held fixed
10
+ across Monte Carlo trials, which is the usual set-up for a fixed group of FL clients.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from collections.abc import Sequence
16
+ from dataclasses import dataclass
17
+
18
+ import numpy as np
19
+
20
+ from aircompkit.core.registry import register
21
+
22
+
23
+ def _budgets(K: int, p_max: float | Sequence[float]) -> np.ndarray:
24
+ arr = np.asarray(p_max, dtype=float)
25
+ if arr.ndim == 0:
26
+ arr = np.full(K, float(arr))
27
+ if arr.shape != (K,):
28
+ raise ValueError(f"p_max must be a scalar or have length K={K}, got shape {arr.shape}")
29
+ if np.any(arr <= 0):
30
+ raise ValueError("power budgets must be positive")
31
+ return arr
32
+
33
+
34
+ @register("devices", "fixed")
35
+ @dataclass
36
+ class FixedDevices:
37
+ """``K`` devices with given power budgets and (optionally) given distances."""
38
+
39
+ K: int
40
+ p_max: float | list[float] = 1.0
41
+ distances: list[float] | None = None
42
+
43
+ def __post_init__(self) -> None:
44
+ if self.K < 1:
45
+ raise ValueError("K must be >= 1")
46
+ if self.distances is not None:
47
+ d = np.asarray(self.distances, dtype=float)
48
+ if d.shape != (self.K,) or np.any(d <= 0):
49
+ raise ValueError("distances must be K positive numbers")
50
+
51
+ def power_budgets(self) -> np.ndarray:
52
+ return _budgets(self.K, self.p_max)
53
+
54
+ def sample_distances(self, rng: np.random.Generator) -> np.ndarray | None:
55
+ return None if self.distances is None else np.asarray(self.distances, dtype=float)
56
+
57
+
58
+ @register("devices", "uniform_disc")
59
+ @dataclass
60
+ class UniformDisc:
61
+ """``K`` devices placed uniformly (by area) in the annulus ``r_min <= r <= r_max``."""
62
+
63
+ K: int
64
+ p_max: float | list[float] = 1.0
65
+ r_min: float = 1.0
66
+ r_max: float = 100.0
67
+
68
+ def __post_init__(self) -> None:
69
+ if self.K < 1:
70
+ raise ValueError("K must be >= 1")
71
+ if not 0 < self.r_min < self.r_max:
72
+ raise ValueError("need 0 < r_min < r_max")
73
+
74
+ def power_budgets(self) -> np.ndarray:
75
+ return _budgets(self.K, self.p_max)
76
+
77
+ def sample_distances(self, rng: np.random.Generator) -> np.ndarray:
78
+ u = rng.uniform(self.r_min**2, self.r_max**2, size=self.K)
79
+ return np.sqrt(u)
@@ -0,0 +1,32 @@
1
+ """Over-the-air federated learning (FEATURES §7): datasets, partitioners, NumPy models,
2
+ the OTA-FL loop and the gradient bank.
3
+
4
+ import aircompkit as ac
5
+ from aircompkit.learning import FederatedConfig, train
6
+
7
+ sc = ac.Scenario(devices={"name": "fixed", "K": 20}, power_control="channel_inversion")
8
+ res = train(sc, FederatedConfig(dataset="synthetic", rounds=50))
9
+ """
10
+
11
+ from aircompkit.learning.aggregate import aircomp_aggregate
12
+ from aircompkit.learning.bank import GradientBank
13
+ from aircompkit.learning.data import Dataset, fashion_mnist, mnist, synthetic
14
+ from aircompkit.learning.fl import FederatedConfig, train
15
+ from aircompkit.learning.models import MLP, logreg
16
+ from aircompkit.learning.partition import IID, Dirichlet, Shards
17
+
18
+ __all__ = [
19
+ "IID",
20
+ "MLP",
21
+ "Dataset",
22
+ "Dirichlet",
23
+ "FederatedConfig",
24
+ "GradientBank",
25
+ "Shards",
26
+ "aircomp_aggregate",
27
+ "fashion_mnist",
28
+ "logreg",
29
+ "mnist",
30
+ "synthetic",
31
+ "train",
32
+ ]
@@ -0,0 +1,49 @@
1
+ """Over-the-air aggregation of device update vectors (computation core of OTA-FL).
2
+
3
+ Each device ``k`` sends a real vector ``x_k`` of length ``d``. Entry ``j`` travels on
4
+ sub-channel ``s = j mod S`` (Zhu et al.'s broadband mapping: one parameter per sub-channel
5
+ per OFDM symbol, independent fading per sub-channel; ``S = 1`` is a single block-fading
6
+ channel per round). For sub-channel ``s`` the physical layer gives each device an arrival
7
+ amplitude ``amp[s, k]`` and the estimate's noise variance ``nv_eff / eta[s]``.
8
+
9
+ With ``normalize=True``, updates are mapped to zero mean / unit variance using statistics
10
+ shared by all devices (the server broadcasts or receives them digitally), so that the
11
+ power-normalised symbols match the AirComp model; the server undoes this after reception.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import numpy as np
17
+
18
+
19
+ def aircomp_aggregate(
20
+ x: np.ndarray,
21
+ amp: np.ndarray,
22
+ eta: np.ndarray,
23
+ active: np.ndarray,
24
+ noise_var_eff: float,
25
+ rng: np.random.Generator,
26
+ normalize: bool = True,
27
+ divide_by: float | None = None,
28
+ ) -> np.ndarray:
29
+ """Estimate ``sum_k x_k / divide_by`` from one round of AirComp.
30
+
31
+ ``x [K, d]`` real updates; ``amp [S, K]`` complex arrival amplitudes; ``eta [S]``;
32
+ ``active [S, K]`` bool (``p > 0``). ``divide_by`` defaults to ``K`` (mean over the
33
+ scheduled devices, Zhu et al.'s ``1/|K|`` post-processing).
34
+ """
35
+ K, d = x.shape
36
+ S = amp.shape[0]
37
+ if normalize:
38
+ mu = float(x.mean())
39
+ sd = float(x.std()) or 1.0
40
+ xn = (x - mu) / sd
41
+ else:
42
+ mu, sd, xn = 0.0, 1.0, x
43
+ sub = np.arange(d) % S
44
+ a = np.real(amp)[sub] # [d, K]
45
+ est = np.einsum("dk,kd->d", a, xn)
46
+ est += rng.standard_normal(d) * np.sqrt(noise_var_eff / eta[sub])
47
+ n_act = active.sum(axis=1)[sub] # devices actually received on each entry
48
+ est = est * sd + n_act * mu
49
+ return est / (K if divide_by is None else divide_by)