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,140 @@
1
+ """Array-level over-the-air aggregation with an adversary (the path used by P4 security).
2
+
3
+ Real update vectors are packed two-per-complex-symbol (``L = ceil(d/2)`` symbols) and scaled
4
+ to unit average symbol power (Zhu/Yang-style analog transmission; with ``clip`` set this is
5
+ ``x_k = (g_k^(1) + j g_k^(2)) / nu``, ``nu = clip / sqrt(L)``). One block-fading
6
+ channel use per round: the server observes the whole array block
7
+
8
+ Y = sum_k h_k t_k^T + n (N x L), t_k = b_k x_k for honest devices,
9
+
10
+ and *effective signatures* ``A = [b_k h_est_k]`` (what it believes each device's spatial
11
+ signature to be). A ``Receiver`` hands defences a ``transmit(ids)`` callback, so a defence
12
+ may use one channel use for everyone (AirComp), one per group (group-based robust AirComp),
13
+ or orthogonal access (digital robust baselines).
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
+
25
+
26
+ def pack(x: np.ndarray) -> np.ndarray:
27
+ """Real ``[..., d]`` to complex ``[..., ceil(d/2)]`` (first half + j * second half)."""
28
+ d = x.shape[-1]
29
+ if d % 2:
30
+ x = np.concatenate([x, np.zeros(x.shape[:-1] + (1,))], axis=-1)
31
+ L = x.shape[-1] // 2
32
+ return x[..., :L] + 1j * x[..., L:]
33
+
34
+
35
+ def unpack(z: np.ndarray, d: int) -> np.ndarray:
36
+ """Inverse of ``pack``."""
37
+ return np.concatenate([z.real, z.imag], axis=-1)[..., :d]
38
+
39
+
40
+ @dataclass
41
+ class Reception:
42
+ """One channel use as seen by the server."""
43
+
44
+ Y: np.ndarray # [N, L] received block
45
+ A: np.ndarray # [N, K'] effective signatures b_k h_est_k (as known at the server)
46
+ eta: float # receive scaling: m^H a_k = sqrt(eta) for every device (ZF)
47
+ m: np.ndarray # [N] unit-norm receive combiner used for the design
48
+ ids: np.ndarray # device ids that transmitted
49
+ noise_var: float # per-antenna complex noise variance
50
+
51
+
52
+ @dataclass
53
+ class Receiver:
54
+ """Physical layer of one round, shared by every transmission a defence asks for."""
55
+
56
+ scenario: Any
57
+ x: np.ndarray # [K', L] normalised complex symbols (honest content)
58
+ p_max: np.ndarray # [K] budgets of *all* scenario devices
59
+ distances: np.ndarray | None # [K] of all scenario devices (or None)
60
+ node: Any # SeedTree node of this round
61
+ attackers: np.ndarray = field(default_factory=lambda: np.zeros(0, int)) # local indices
62
+ device_ids: np.ndarray | None = None # local -> scenario device id (default: identity)
63
+ attack: Any = None
64
+ gref: np.ndarray | None = None # normalised honest-mean symbols (omniscient attacks)
65
+ jammer: dict[str, float] | None = None
66
+ uses: int = 0
67
+
68
+ def __post_init__(self) -> None:
69
+ if self.device_ids is None:
70
+ self.device_ids = np.arange(self.x.shape[0])
71
+
72
+ @property
73
+ def rng(self) -> np.random.Generator:
74
+ return self.node.generator("defense")
75
+
76
+ def transmit(self, ids: np.ndarray | None = None, tag: str = "main") -> Reception:
77
+ """One AirComp channel use by devices ``ids`` (default: all)."""
78
+ sc = self.scenario
79
+ K, L = self.x.shape
80
+ ids = np.arange(K) if ids is None else np.asarray(ids)
81
+ sub = self.node.child(tag)
82
+ h_act, h_est, beta = sc.sample_channels(sub, 1, self.distances)
83
+ gid = np.asarray(self.device_ids)[ids]
84
+ h_act, h_est, beta = h_act[:, gid], h_est[:, gid].copy(), beta[:, gid]
85
+ byz_local = np.flatnonzero(np.isin(ids, self.attackers))
86
+ if self.attack is not None and len(byz_local):
87
+ h_est[:, byz_local] = self.attack.distort_csi(h_est[:, byz_local])
88
+ lay = sc.design(h_act, h_est, beta, self.p_max[gid])
89
+ b = lay["b"][0]
90
+ T = self.x[ids] * b[:, None]
91
+ if self.attack is not None and len(byz_local):
92
+ T[byz_local] = self.attack.transmit(self.x[ids[byz_local]], b[byz_local], {
93
+ "rng": sub.generator("attack"), "p_max": self.p_max[gid[byz_local]],
94
+ "gref": self.gref})
95
+ Hn = h_act[0].T # [N, K']
96
+ N = Hn.shape[0]
97
+ Y = Hn @ T + np.sqrt(sc.noise_var) * _cn(sub.generator("noise"), (N, L))
98
+ if self.jammer:
99
+ hj, _ = sc.channel.sample(sub.generator("jammer"), 1, 1,
100
+ np.array([self.jammer.get("distance", 1.0)])
101
+ if self.distances is not None else None)
102
+ Y += np.sqrt(self.jammer["power"]) * np.outer(hj[0, 0], _cn(sub.generator("jam_sym"), (L,)))
103
+ self.uses += 1
104
+ A = h_est[0].T * b[None, :]
105
+ return Reception(Y, A, float(lay["eta"][0]), lay["m"][0], ids, sc.noise_var)
106
+
107
+ def transmit_orthogonal(self, ids: np.ndarray | None = None, tag: str = "orth") -> np.ndarray:
108
+ """Each device in its own resource block at full power with MRC: returns the server's
109
+ per-device estimates of the normalised symbols, ``[K', L]`` (digital baselines)."""
110
+ sc = self.scenario
111
+ K, _L = self.x.shape
112
+ ids = np.arange(K) if ids is None else np.asarray(ids)
113
+ sub = self.node.child(tag)
114
+ h_act, _, _ = sc.sample_channels(sub, 1, self.distances)
115
+ gid = np.asarray(self.device_ids)[ids]
116
+ h = h_act[0, gid] # [K', N]
117
+ gain = np.sqrt(self.p_max[gid]) * np.linalg.norm(h, axis=1) # MRC amplitude
118
+ X = self.x[ids].copy()
119
+ byz_local = np.flatnonzero(np.isin(ids, self.attackers))
120
+ if self.attack is not None and len(byz_local):
121
+ b = np.sqrt(self.p_max[gid[byz_local]]).astype(complex)
122
+ X[byz_local] = self.attack.transmit(self.x[ids[byz_local]], b, {
123
+ "rng": sub.generator("attack"), "p_max": self.p_max[gid[byz_local]],
124
+ "gref": self.gref}) / b[:, None]
125
+ noise = _cn(sub.generator("noise"), X.shape) * np.sqrt(sc.noise_var) / gain[:, None]
126
+ self.uses += len(ids)
127
+ return X + noise
128
+
129
+
130
+ def normalise(X: np.ndarray, clip: float | None) -> tuple[np.ndarray, float]:
131
+ """Pack real updates and scale to unit average symbol power. Returns ``(x, nu)`` with
132
+ ``X ~= nu * unpack(x)``. With ``clip`` (rows already clipped to norm <= clip),
133
+ ``nu = clip / sqrt(L)`` so that ``||x_k||^2 <= L``."""
134
+ z = pack(X)
135
+ L = z.shape[-1]
136
+ if clip is not None:
137
+ nu = clip / np.sqrt(L)
138
+ else:
139
+ nu = float(np.sqrt(np.mean(np.abs(z) ** 2))) or 1.0
140
+ return z / nu, nu
@@ -0,0 +1,86 @@
1
+ """Gradient bank (FEATURES L5): record honest device updates once, replay them through many
2
+ channel / attack / defence realisations without retraining.
3
+
4
+ A training run records ``updates[r] [K_r, d]`` (float32) and the ids of the scheduled devices
5
+ for selected rounds. ``GradientBank.replay`` sends the stored updates through a
6
+ ``Scenario``'s physical layer ``trials`` times per round and
7
+ reports the aggregation NMSE against the ideal mean. P4 builds attack/detection Monte Carlo
8
+ on the same mechanism.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from dataclasses import dataclass, field
14
+ from pathlib import Path
15
+ from typing import Any
16
+
17
+ import numpy as np
18
+
19
+ from aircompkit.core.rng import SeedTree
20
+ from aircompkit.learning.aggregate import aircomp_aggregate
21
+
22
+
23
+ @dataclass
24
+ class GradientBank:
25
+ rounds: list[int] = field(default_factory=list)
26
+ updates: list[np.ndarray] = field(default_factory=list)
27
+ device_ids: list[np.ndarray] = field(default_factory=list)
28
+ meta: dict[str, Any] = field(default_factory=dict)
29
+
30
+ def record(self, round_idx: int, ids: np.ndarray, x: np.ndarray) -> None:
31
+ self.rounds.append(int(round_idx))
32
+ self.device_ids.append(np.asarray(ids, dtype=np.int64))
33
+ self.updates.append(np.asarray(x, dtype=np.float32))
34
+
35
+ def __len__(self) -> int:
36
+ return len(self.rounds)
37
+
38
+ def save(self, path: str | Path) -> Path:
39
+ p = Path(path).with_suffix(".npz")
40
+ p.parent.mkdir(parents=True, exist_ok=True)
41
+ arrays = {"rounds": np.asarray(self.rounds)}
42
+ for i, (u, ids) in enumerate(zip(self.updates, self.device_ids)):
43
+ arrays[f"u{i}"] = u
44
+ arrays[f"ids{i}"] = ids
45
+ import json
46
+
47
+ arrays["meta"] = np.frombuffer(json.dumps(self.meta).encode(), dtype=np.uint8)
48
+ np.savez_compressed(p, **arrays) # type: ignore[arg-type]
49
+ return p
50
+
51
+ @classmethod
52
+ def load(cls, path: str | Path) -> GradientBank:
53
+ import json
54
+
55
+ with np.load(Path(path).with_suffix(".npz")) as z:
56
+ n = len(z["rounds"])
57
+ return cls(
58
+ rounds=z["rounds"].tolist(),
59
+ updates=[z[f"u{i}"] for i in range(n)],
60
+ device_ids=[z[f"ids{i}"] for i in range(n)],
61
+ meta=json.loads(z["meta"].tobytes().decode()) if "meta" in z.files else {},
62
+ )
63
+
64
+ def replay(self, scenario, trials: int = 10, subchannels: int = 1, seed: int = 0,
65
+ normalize: bool = True) -> dict[str, np.ndarray]:
66
+ """Aggregate every stored round ``trials`` times over fresh channel draws.
67
+
68
+ Returns ``nmse [rounds, trials]`` (``||est - mean||^2 / ||mean||^2``) and ``rounds``.
69
+ Devices keep the placement drawn from ``scenario.seed``.
70
+ """
71
+ tree = SeedTree(seed)
72
+ p_max_all = scenario.devices.power_budgets()
73
+ dist = scenario.devices.sample_distances(SeedTree(scenario.seed).generator("devices"))
74
+ out = np.empty((len(self), trials))
75
+ for i, (ids, x) in enumerate(zip(self.device_ids, self.updates)):
76
+ x = x.astype(np.float64)
77
+ ideal = x.mean(axis=0)
78
+ for t in range(trials):
79
+ node = tree.child(f"replay{i}").child(str(t))
80
+ h_act, h_est, beta = scenario.sample_channels(node, subchannels, dist)
81
+ lay = scenario.design(h_act[:, ids], h_est[:, ids], beta[:, ids], p_max_all[ids])
82
+ est = aircomp_aggregate(x, lay["amp"], lay["eta"], lay["p"] > 0,
83
+ scenario.noise_var_eff, node.generator("noise"),
84
+ normalize=normalize)
85
+ out[i, t] = np.sum((est - ideal) ** 2) / max(np.sum(ideal**2), 1e-300)
86
+ return {"rounds": np.asarray(self.rounds), "nmse": out}
@@ -0,0 +1,128 @@
1
+ """Datasets for learning mode (FEATURES L2). Everything is NumPy; no downloads happen here.
2
+
3
+ ``mnist`` / ``fashion_mnist`` are read from local files, searched in this order:
4
+ ``root`` argument, ``$AIRCOMPKIT_DATA``, ``~/.aircompkit/data``. Accepted formats:
5
+
6
+ * ``<name>.npz`` with keys ``x_train, y_train, x_test, y_test`` (the Keras layout) or
7
+ ``xtr, ytr, xte, yte``;
8
+ * the four original IDX files (``train-images-idx3-ubyte[.gz]`` etc.) in ``<root>/<name>/``.
9
+
10
+ ``synthetic`` is a Gaussian-mixture classification task generated from a seed, used by the
11
+ tests and for quick experiments.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import gzip
17
+ import os
18
+ from dataclasses import dataclass
19
+ from pathlib import Path
20
+
21
+ import numpy as np
22
+
23
+ from aircompkit.core.registry import register
24
+
25
+
26
+ @dataclass
27
+ class Dataset:
28
+ x_train: np.ndarray
29
+ y_train: np.ndarray
30
+ x_test: np.ndarray
31
+ y_test: np.ndarray
32
+ n_classes: int
33
+ name: str = ""
34
+
35
+ @property
36
+ def dim(self) -> int:
37
+ return int(self.x_train.shape[1])
38
+
39
+
40
+ def _search_roots(root: str | Path | None) -> list[Path]:
41
+ roots = []
42
+ if root is not None:
43
+ roots.append(Path(root))
44
+ if os.environ.get("AIRCOMPKIT_DATA"):
45
+ roots.append(Path(os.environ["AIRCOMPKIT_DATA"]))
46
+ roots.append(Path.home() / ".aircompkit" / "data")
47
+ return roots
48
+
49
+
50
+ def _read_idx(path: Path) -> np.ndarray:
51
+ opener = gzip.open if path.suffix == ".gz" else open
52
+ with opener(path, "rb") as f:
53
+ data = f.read()
54
+ ndim = data[3]
55
+ dims = [int.from_bytes(data[4 + 4 * i: 8 + 4 * i], "big") for i in range(ndim)]
56
+ return np.frombuffer(data, dtype=np.uint8, offset=4 + 4 * ndim).reshape(dims)
57
+
58
+
59
+ def _load_image_set(name: str, root: str | Path | None) -> Dataset:
60
+ tried = []
61
+ for r in _search_roots(root):
62
+ f = r / f"{name}.npz"
63
+ tried.append(str(f))
64
+ if f.exists():
65
+ with np.load(f) as z:
66
+ keys = set(z.files)
67
+ if {"x_train", "y_train", "x_test", "y_test"} <= keys:
68
+ xtr, ytr, xte, yte = z["x_train"], z["y_train"], z["x_test"], z["y_test"]
69
+ elif {"xtr", "ytr", "xte", "yte"} <= keys:
70
+ xtr, ytr, xte, yte = z["xtr"], z["ytr"], z["xte"], z["yte"]
71
+ else:
72
+ raise ValueError(f"{f}: unrecognised keys {sorted(keys)}")
73
+ return _image_dataset(name, xtr, ytr, xte, yte)
74
+ d = r / name
75
+ files = {}
76
+ for key, stem in (("xtr", "train-images-idx3-ubyte"), ("ytr", "train-labels-idx1-ubyte"),
77
+ ("xte", "t10k-images-idx3-ubyte"), ("yte", "t10k-labels-idx1-ubyte")):
78
+ for cand in (d / stem, d / f"{stem}.gz"):
79
+ if cand.exists():
80
+ files[key] = cand
81
+ tried.append(str(d / "*-idx?-ubyte[.gz]"))
82
+ if len(files) == 4:
83
+ return _image_dataset(name, *(_read_idx(files[k]) for k in ("xtr", "ytr", "xte", "yte")))
84
+ raise FileNotFoundError(
85
+ f"{name} not found. Put {name}.npz (Keras layout) or the IDX files in one of:\n "
86
+ + "\n ".join(tried)
87
+ + "\nor set AIRCOMPKIT_DATA to the folder that holds it."
88
+ )
89
+
90
+
91
+ def _image_dataset(name, xtr, ytr, xte, yte) -> Dataset:
92
+ xtr = np.asarray(xtr, np.float32).reshape(len(xtr), -1) / 255.0
93
+ xte = np.asarray(xte, np.float32).reshape(len(xte), -1) / 255.0
94
+ mu, sd = float(xtr.mean()), float(xtr.std())
95
+ return Dataset((xtr - mu) / sd, np.asarray(ytr, np.int64), (xte - mu) / sd,
96
+ np.asarray(yte, np.int64), 10, name)
97
+
98
+
99
+ @register("dataset", "mnist")
100
+ def mnist(root: str | Path | None = None) -> Dataset:
101
+ return _load_image_set("mnist", root)
102
+
103
+
104
+ @register("dataset", "fashion_mnist")
105
+ def fashion_mnist(root: str | Path | None = None) -> Dataset:
106
+ return _load_image_set("fashion_mnist", root)
107
+
108
+
109
+ @register("dataset", "synthetic")
110
+ def synthetic(
111
+ n_train: int = 6000,
112
+ n_test: int = 2000,
113
+ dim: int = 20,
114
+ n_classes: int = 5,
115
+ separation: float = 1.5,
116
+ seed: int = 0,
117
+ ) -> Dataset:
118
+ """Gaussian mixture: class means ``~ N(0, separation^2 I / dim * ...)``, unit noise."""
119
+ rng = np.random.default_rng(seed)
120
+ means = rng.standard_normal((n_classes, dim)) * separation / np.sqrt(dim) * 3
121
+
122
+ def draw(n):
123
+ y = rng.integers(0, n_classes, n)
124
+ return (means[y] + rng.standard_normal((n, dim))).astype(np.float32), y
125
+
126
+ xtr, ytr = draw(n_train)
127
+ xte, yte = draw(n_test)
128
+ return Dataset(xtr, ytr, xte, yte, n_classes, "synthetic")
@@ -0,0 +1,249 @@
1
+ """Over-the-air federated learning loop (FEATURES L1, L6).
2
+
3
+ Each round:
4
+
5
+ 1. the server schedules devices (all, or the cell interior ``distance <= max_distance``,
6
+ Zhu et al.'s Scheme 1);
7
+ 2. every scheduled device runs ``local_steps`` minibatch SGD steps from the global model
8
+ (``local_steps = 1``: FedSGD; more: FedAvg);
9
+ 3. the devices send their update ``w_k - w`` (``transmit="update"``) or local model ``w_k``
10
+ (``transmit="model"``) through the scenario's physical layer, one fading draw per
11
+ sub-channel; ``aggregation="ideal"`` replaces the channel by the exact mean;
12
+ 4. the server applies the estimated mean.
13
+
14
+ The same seed gives identical data splits, initialisation and minibatches for ``ideal`` and
15
+ ``aircomp`` runs, so their difference is due to the channel alone.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import dataclasses
21
+ import platform
22
+ from dataclasses import dataclass, field
23
+ from typing import Any
24
+
25
+ import numpy as np
26
+
27
+ from aircompkit.core.registry import build, get
28
+ from aircompkit.core.result import Result
29
+ from aircompkit.core.rng import SeedTree
30
+ from aircompkit.learning.aggregate import aircomp_aggregate
31
+ from aircompkit.learning.bank import GradientBank
32
+ from aircompkit.learning.data import Dataset
33
+
34
+
35
+ @dataclass
36
+ class FederatedConfig:
37
+ dataset: Any = "synthetic"
38
+ partition: Any = "iid"
39
+ model: Any = field(default_factory=lambda: {"name": "mlp", "hidden": [64]})
40
+ rounds: int = 100
41
+ local_steps: int = 1
42
+ batch_size: int = 32
43
+ lr: float = 0.1
44
+ eval_every: int = 10
45
+ aggregation: str = "aircomp"
46
+ transmit: str = "update"
47
+ subchannels: int = 1
48
+ max_distance: float | None = None
49
+ normalize: bool = True
50
+ record_bank: list[int] = field(default_factory=list)
51
+ clip: float | None = None
52
+ threat: Any = None
53
+ defense: Any = "none"
54
+ seed: int = 0
55
+
56
+ def __post_init__(self) -> None:
57
+ if self.aggregation not in ("aircomp", "ideal"):
58
+ raise ValueError("aggregation must be 'aircomp' or 'ideal'")
59
+ if self.transmit not in ("update", "model"):
60
+ raise ValueError("transmit must be 'update' or 'model'")
61
+ if min(self.rounds, self.local_steps, self.batch_size, self.eval_every,
62
+ self.subchannels) < 1:
63
+ raise ValueError("rounds, local_steps, batch_size, eval_every, subchannels must be >= 1")
64
+ if self.clip is not None and self.clip <= 0:
65
+ raise ValueError("clip must be > 0")
66
+
67
+ def to_dict(self) -> dict[str, Any]:
68
+ from aircompkit.adversary import ThreatModel
69
+ from aircompkit.core.registry import spec_of
70
+
71
+ plain = {f.name: getattr(self, f.name) for f in dataclasses.fields(self)}
72
+ if isinstance(self.dataset, Dataset):
73
+ plain["dataset"] = self.dataset.name or "custom"
74
+ if isinstance(self.threat, ThreatModel):
75
+ plain["threat"] = self.threat.to_dict()
76
+ if not isinstance(self.defense, (str, dict)):
77
+ plain["defense"] = spec_of("defense", self.defense)
78
+ return plain
79
+
80
+
81
+ def _dataset(spec: Any, data_root: str | None) -> Dataset:
82
+ if isinstance(spec, Dataset):
83
+ return spec
84
+ if isinstance(spec, str):
85
+ spec = {"name": spec}
86
+ params = dict(spec)
87
+ fn = get("dataset", params.pop("name"))
88
+ if fn.__name__ in ("mnist", "fashion_mnist") and data_root is not None:
89
+ params.setdefault("root", data_root)
90
+ return fn(**params)
91
+
92
+
93
+ def _model(spec: Any, data: Dataset):
94
+ if not isinstance(spec, (str, dict)):
95
+ return spec
96
+ params = {"name": spec} if isinstance(spec, str) else dict(spec)
97
+ return get("model", params.pop("name"))(d_in=data.dim, n_classes=data.n_classes, **params)
98
+
99
+
100
+ def train(
101
+ scenario,
102
+ cfg: FederatedConfig | dict[str, Any],
103
+ data: Dataset | None = None,
104
+ bank: GradientBank | None = None,
105
+ data_root: str | None = None,
106
+ verbose: bool = False,
107
+ ) -> Result:
108
+ """Run OTA-FL on ``scenario``'s physical layer. Returns a ``Result`` with arrays
109
+ ``eval_round``, ``test_acc``, ``test_loss`` (per evaluation), ``train_loss``,
110
+ ``n_scheduled``, ``agg_nmse`` (per round; NMSE of the received vs. exact honest mean),
111
+ and on the array path ``det_tp``, ``det_fp`` (flagged attackers / honest devices) and
112
+ ``channel_uses``.
113
+
114
+ Two physical paths:
115
+
116
+ * ``symbols="real"`` (broadband): one real parameter per sub-channel use, scalar
117
+ combining (P3); no adversary or defence;
118
+ * ``symbols="complex"`` (array): parameters packed two per complex symbol, one
119
+ block-fading channel use per round observed at every antenna; supports ``threat`` and
120
+ ``defense`` (P4).
121
+ """
122
+ from aircompkit.adversary import as_threat
123
+ from aircompkit.learning.array import Receiver, normalise, pack, unpack
124
+
125
+ if isinstance(cfg, dict):
126
+ cfg = FederatedConfig(**cfg)
127
+ threat = as_threat(cfg.threat)
128
+ defense = build("defense", cfg.defense)
129
+ array_path = scenario.symbols == "complex"
130
+ if not array_path and (threat is not None or type(defense).__name__ != "NoDefense"):
131
+ raise ValueError("attacks and defences need the array path: use symbols='complex'")
132
+ data = data if data is not None else _dataset(cfg.dataset, data_root)
133
+ model = _model(cfg.model, data)
134
+ K = scenario.devices.K
135
+
136
+ tree = SeedTree(cfg.seed)
137
+ phys = SeedTree(scenario.seed)
138
+ dist = scenario.devices.sample_distances(phys.generator("devices"))
139
+ p_max = scenario.devices.power_budgets()
140
+ parts = build("partitioner", cfg.partition)(data.y_train, K, tree.generator("partition"))
141
+ if cfg.max_distance is None:
142
+ sched = np.arange(K)
143
+ else:
144
+ if dist is None:
145
+ raise ValueError("max_distance needs devices with distances (e.g. uniform_disc)")
146
+ sched = np.flatnonzero(dist <= cfg.max_distance)
147
+ if len(sched) == 0:
148
+ raise ValueError("no device is scheduled; increase max_distance")
149
+
150
+ # attackers: scenario device ids, and their positions among the scheduled devices
151
+ byz = threat.attackers(K) if threat is not None else np.zeros(0, int)
152
+ byz_local = np.flatnonzero(np.isin(sched, byz))
153
+ honest_local = np.setdiff1d(np.arange(len(sched)), byz_local)
154
+ attack = threat.attack if threat is not None else None
155
+ defense.reset(len(sched))
156
+
157
+ w = model.init(tree.generator("model"))
158
+ rng_sgd = tree.generator("sgd")
159
+ eval_round, test_acc, test_loss = [], [], []
160
+ train_loss = np.empty(cfg.rounds)
161
+ nmse = np.zeros(cfg.rounds)
162
+ det_tp = np.zeros(cfg.rounds)
163
+ det_fp = np.zeros(cfg.rounds)
164
+ uses = np.zeros(cfg.rounds)
165
+ nonfinite = 0
166
+ byz_set = set(byz_local.tolist())
167
+
168
+ for t in range(cfg.rounds):
169
+ X = np.empty((len(sched), w.size))
170
+ losses = []
171
+ for i, k in enumerate(sched):
172
+ wk = w.copy()
173
+ idx = parts[k]
174
+ poison = attack is not None and attack.poisons_labels and i in byz_set
175
+ for step in range(cfg.local_steps):
176
+ bsel = idx[rng_sgd.integers(0, len(idx), size=min(cfg.batch_size, len(idx)))]
177
+ y = data.y_train[bsel]
178
+ if poison:
179
+ y = attack.flip_labels(y, data.n_classes) # type: ignore[union-attr]
180
+ loss, g = model.loss_grad(wk, data.x_train[bsel], y)
181
+ if step == 0:
182
+ losses.append(loss)
183
+ wk -= cfg.lr * g
184
+ X[i] = wk - w if cfg.transmit == "update" else wk
185
+ if cfg.clip is not None:
186
+ X[i] *= min(1.0, cfg.clip / (np.linalg.norm(X[i]) + 1e-12))
187
+ train_loss[t] = float(np.mean(losses))
188
+ if bank is not None and t in cfg.record_bank:
189
+ bank.record(t, sched, X)
190
+
191
+ ideal = X[honest_local].mean(axis=0)
192
+ node = phys.child("round").child(str(t))
193
+ if cfg.aggregation == "ideal":
194
+ agg = ideal
195
+ elif array_path:
196
+ x, nu = normalise(X, cfg.clip)
197
+ rx = Receiver(scenario, x, p_max, dist, node, attackers=byz_local,
198
+ attack=attack, gref=pack(ideal),
199
+ jammer=threat.jammer if threat is not None else None,
200
+ device_ids=sched)
201
+ est, keff, flagged = defense.aggregate(rx, {"attackers": byz_local})
202
+ agg = nu * unpack(est, w.size) / keff
203
+ det_tp[t] = len(flagged & byz_set)
204
+ det_fp[t] = len(flagged - byz_set)
205
+ uses[t] = rx.uses
206
+ nmse[t] = np.sum((agg - ideal) ** 2) / max(np.sum(ideal**2), 1e-300)
207
+ else:
208
+ h_act, h_est, beta = scenario.sample_channels(node, cfg.subchannels, dist)
209
+ lay = scenario.design(h_act[:, sched], h_est[:, sched], beta[:, sched], p_max[sched])
210
+ agg = aircomp_aggregate(X, lay["amp"], lay["eta"], lay["p"] > 0,
211
+ scenario.noise_var_eff, node.generator("noise"),
212
+ normalize=cfg.normalize)
213
+ uses[t] = cfg.subchannels
214
+ nmse[t] = np.sum((agg - ideal) ** 2) / max(np.sum(ideal**2), 1e-300)
215
+ w = w + agg if cfg.transmit == "update" else agg
216
+ if not np.all(np.isfinite(w)): # an unbounded attack can blow the model up
217
+ nonfinite += 1
218
+ w = np.nan_to_num(w, nan=0.0, posinf=0.0, neginf=0.0)
219
+
220
+ if (t + 1) % cfg.eval_every == 0 or t == cfg.rounds - 1:
221
+ lo, acc = model.evaluate(w, data.x_test, data.y_test)
222
+ eval_round.append(t + 1)
223
+ test_acc.append(acc)
224
+ test_loss.append(lo)
225
+ if verbose:
226
+ print(f"round {t + 1:5d} acc {acc:.4f} loss {lo:.4f} nmse {nmse[t]:.2e}")
227
+
228
+ from aircompkit import __version__
229
+
230
+ arrays = {
231
+ "eval_round": np.asarray(eval_round, float),
232
+ "test_acc": np.asarray(test_acc),
233
+ "test_loss": np.asarray(test_loss),
234
+ "train_loss": train_loss,
235
+ "agg_nmse": nmse,
236
+ "n_scheduled": np.full(cfg.rounds, float(len(sched))),
237
+ "channel_uses": uses,
238
+ }
239
+ if array_path:
240
+ arrays["det_tp"] = det_tp
241
+ arrays["det_fp"] = det_fp
242
+ meta = {"aircompkit": __version__, "numpy": np.__version__,
243
+ "python": platform.python_version(), "model_size": int(w.size),
244
+ "dataset": data.name, "final_params_norm": float(np.linalg.norm(w)),
245
+ "attackers": byz.tolist(), "nonfinite_rounds": nonfinite}
246
+ if bank is not None:
247
+ bank.meta.update({"scenario": scenario.to_dict(), "learning": cfg.to_dict()})
248
+ return Result(config={"scenario": scenario.to_dict(), "learning": cfg.to_dict()},
249
+ arrays=arrays, meta=meta)