beamsim v0.3.1

beamsim v0.3.1

Patch release: a single physics fix to the knife-edge-diffraction (KED) blockage attenuation, plus a follow-up to the MATLAB-parity audit that resolves the W_HIGH and MCMD slot-7 questions.

Fixed: KED attenuation now uses the physical Fresnel-zone scale

The previous KED attenuation formula in channel._ked_attenuation_db hardcoded lambda_eff = 0.4 — a magic constant with no physical motivation — and used the wrong algebraic form (π/λ_eff − 1)/cos. TR 38.901 §7.6.4.1 and Eq 3.17 of the predecessor MSc report specify π·r/λ · (1/cos − 1) inside the square root, where r is the blocker depth and λ is the carrier wavelength.

The corrected formula:

• Threads the carrier frequency through BlockageState.wavelength_m (computed as c / fc_hz from ChannelParams.fc_hz).
• Adds BlockageState.blocker_radius_m, defaulting to 10 m to match the predecessor's blockage.m.
• Computes scale = π · r / λ (≈ 2940 at 28 GHz with a 10 m blocker, three orders of magnitude larger than the previous 6.85), so KED attenuation depth at oblique incidence is now physically meaningful and scales correctly with both wavelength and blocker depth.

Audit follow-up: W_HIGH and MCMD slot-7 resolved as already-thesis-faithful

The MATLAB-parity audit had flagged Python's W_HIGH = (0.16, 0.36, 0.49) and Python's three-criterion MCMD as divergences from the MATLAB code. After reading the predecessor MSc thesis (Fig 5.26 pie charts and the surrounding text), both turn out to be cases where Python is faithful to the published thesis and the MATLAB code is from a later un-published re-fit — the evolutionary search (Algorithm 7) uses random initialisation, so re-runs produce different terminal weights. No code change to MCMD was needed; the audit's Bugs in Python (MATLAB is the correct reference) category is now empty.

Test count

248 → 250 passing.

---

Engineering log: CHANGELOG.md. Audit: docs/MATLAB_PARITY.md. Deferred work: docs/ROADMAP.md.

beamsim v0.3.0

beamsim v0.3.0

Minor release: closes the largest gaps from the MATLAB-parity audit by porting four standalone algorithms and adding Uniform Planar Array (UPA) support — the original predecessor MATLAB simulator exposed all of these but the Python re-implementation did not.

Four algorithms ported from tracking_algos/

• AgeMx — standalone least-recently-measured beam-pair scan, exposing the age criterion as an MBP policy independent of MCMD.
• RandomSearch — randperm-then-mark scan baseline; RNG seeded from context["trial_seed"].
• NNSTabu (Ascent_Tabu) — the algorithm MCMD's slot-7 weight (W_High[7] = 0.8742 in the MATLAB simulator) actually points at; distinct from plain NNS by using the global argmax of |Y_obs| for relocation when the five-cell list is exhausted.
• ContextInformationMBS — multi-BS CI: picks the closest BS by L2 distance, then runs the standard sin-space CI match in that BS's frame.

Uniform Planar Array (UPA) support

• PlanarCodebook + planar_steering_vector — UPA with n_x × n_y elements in the xy-plane at half-wavelength spacing, azimuth-only steering uniform over [0, 2π), mirroring MATLAB placodebook.m.
• PlanarFreeSpaceLosChannel — companion LOS channel; works with BPLMState via the same w.conj() @ H @ f contract as the existing ULA channel.
• Default factories: make_default_planar_ue_codebook() (2×2 UPA, 6 beams) and make_default_planar_bs_codebook() (4×4 UPA, 12 beams).

BPLMState now accepts either Codebook (ULA) or PlanarCodebook (UPA) on each side; the switch is purely at construction time.

What's still ULA-only

The full TR 38.901 cluster channel (ChannelRealisation) still uses ULA steering internally. The end-to-end planar path today is PlanarCodebook + PlanarFreeSpaceLosChannel. Extending the cluster channel to UPA is tracked in docs/ROADMAP.md.

Why hand-rolled numpy

The planar steering implementation is hand-rolled numpy rather than a wrapper around a mature wireless-simulation library. NVIDIA Sionna and DeepMIMO are the closest candidates and both are at least an order of magnitude heavier than the codebook layer alone needs. DeepMIMO is the natural integration when ray-traced channels are added, at the channel layer rather than the codebook layer.

Test count

216 → 248 passing.

---

Engineering log: CHANGELOG.md. Audit: docs/MATLAB_PARITY.md. Deferred work: docs/ROADMAP.md.

beamsim v0.2.1

beamsim v0.2.1

Patch release: the codebook-oracle SNR diagnostics shipped in v0.2.0 now apply uniformly across all runner.py paths, not just the multi-BS handover scenarios.

Fixed / extended

• runner.py single-BS oracle. Experiment runs with a single base station now compute and store snr_oracle per step, using metrics.oracle_snr_db over the per-step channel matrix. Previously this field was populated only for multi-BS experiments, leaving single-BS scenarios without a regret comparator.
• TrialResult.snr_oracle and save_experiment schema. The field is now populated for both topologies; the .npz archive carries snr_oracle as a top-level array whenever the experiment supplies it.
• Three new tests (tests/test_runner.py::TestRunExperiment):
  test_single_bs_oracle_populated, test_oracle_dominates_achieved_single_bs (oracle ≥ achieved at every step under Perfect), and test_oracle_matches_metrics_function (cross-validates the runner's einsum against the standalone metrics.oracle_snr_db).

Why this matters

The snr_regret_db diagnostic added in v0.2.0 needs an oracle trace to subtract from. With this patch every experiment configuration produces one, so oracle - achieved is a well-defined per-step quantity for every algorithm in every scenario.

Test count

213 → 216 passing.

---

Engineering log: CHANGELOG.md. Scope and out-of-scope items: docs/related_work.md. Deferred work: docs/ROADMAP.md.

beamsim v0.2.0

beamsim v0.2.0

This release adds modern evaluation diagnostics for codebook-based mmWave beam-alignment simulation while keeping the repository's scope intentionally narrow.

Added

• Finite-codebook oracle SNR:
  best achievable SNR over the simulated UE × BS codebook for the same channel realization.
• dB SNR regret:
  additive gap between the finite-codebook oracle and the achieved beam pair.
• Outage probability:
  strict-threshold estimate, Pr(SNR_dB < threshold_db).
• Beam-switch rate:
  transition-normalized switching frequency over output beam-pair histories.
• Measurement-budget taxonomy and lifecycle framing in the documentation.
• Roadmap entries for deferred measurement-budget accounting and blockage reacquisition latency.

Methodological positioning

beamsim remains a focused simulator for codebook-based mmWave beam alignment and tracking. It is not a general 5G/6G beam-management benchmark, ML beam-prediction framework, RIS simulator, digital-twin platform, or near-field / sub-THz model.

The central contribution of this release is clearer paired stochastic evaluation and finite-codebook oracle diagnostics for reproducible comparison of beam-alignment policies.

---

Full engineering log: CHANGELOG.md. Scope and out-of-scope items: docs/related_work.md. Deferred work: docs/ROADMAP.md.