Simulation Sandbox — JuPedSim + BLE + CSI-proxy coupled, mechanism + harness validation

Motivation

This experiment's primary deliverable is a harness that the rest of the experiment series reuses, and its secondary deliverable is the headline λ-sweep evidence for L4½.4 / L4½.5 (the continuity-residual penalty reduces per-cell MAE; that reduction is empirically separable from the architecture choice). Both are simulation-only and start today.

The narrower experiment-design rationale lives in diary/2026-05-20 - Experiment Series Reorganization. The engineering chassis is specified in IP-077; this note is the experimental contract.

Hypotheses

• H-S1.1 (harness validity) — A coupled JuPedSim + PedPy + log-distance-BLE + CSI-proxy run completes end-to-end on CPU in < 5 min wall-clock for the minimal scenario (Geometry A, S5, $N=4$, 60 s) and emits a structured run card + ≥ 6 OTel child spans matching the IP-077 taxonomy.
• H-S1.2 (mechanism signal) — A continuity-residual penalty $\lambda \cdot | \partial\rho/\partial t + \nabla\cdot(\rho\mathbf{v}) |_2^2$ added to the supervised MSE loss reduces per-cell occupancy MAE by ≥ 0.10 ped/cell at the best $\lambda^*$ on at least 2 of 3 models in the small zoo (Bagging-LGBM + hand-rolled PINN + a deep baseline) at one density level $N=8$.
• H-S1.3 (separability) — The sign of the lift at $\lambda^*$ is consistent (positive) across the 3 models with bounded variance in magnitude (sd / mean ≤ 0.5). If H-S1.3 fails, L4½.5 needs Layer F evidence to close.

Setup

Geometry

Parametric Geometry A only — the seminar room described in EXP-006:

+----------------------------------------+
|              CELL A (8 × 12)           |
|                                        |
|  [CSIAP-1]               [BLEBeacon-1] |
|                                        |
|  [BLEBeacon-2]           [CSIAP-2]     |
|                                        |
+---[Door-N]----------------[Door-S]-----+

Six target cells (3 × 2 logical grid), 2 CSI AP pairs, 2 BLE beacons, 4 BLE observers at corners. Geometry B (corridor with side rooms) deferred to Phase B follow-on if H-S1.3 needs cross-geometry evidence.

Simulation stack

Per-window feature schema

Identical to the EXP-006 redesign schema — 4-tuple per :CSIAP / :BLEBeacon / :Cell / :Door node, 1-s window, target per-cell occupancy at $t+1,\text{s}$.

Procedure

Phase A — Harness validation (the platform test)

The smallest end-to-end run. Startable today, no GPU, no hardware, no GIS.

1. GeometryFactory("a_seminar") builds the Shapely polygon + cell dict.
2. JuPedSimAdapter.run(geometry=A, scenario=S5, n_agents=4, seconds=60, seed=0) writes trajectory.parquet.
3. PedPyAnalyser.voronoi_density(traj) writes density.parquet (per-cell Voronoi density + smoothed-projection variant + continuity-residual target).
4. BLEChannelModel.synthesise(agents=[], observers=corners) writes an empty rssi.parquet (S5 = 0 carriers).
5. GraphBuilder.build(traj_window=1s, csi=None, ble=ble) writes snapshots.pt (PyG HeteroData).
6. LGBMBaseline.fit_predict(graph) writes predictions.parquet.
7. SimulationPipeline.run(phase="A") ties them together; emits sim.exp-s1.run span + ≥ 6 child spans.

Gate to Phase B: end-to-end < 5 min CPU wall-clock; Tempo shows the span tree; run card written to _attachments/.exp-s1-last-run.json; the LGBM forward pass returns one MAE per cell (number does not have to be good — just defined and finite).

Phase B — Mechanism λ-sweep (the headline)

1. Scale to $N=8$ at scenario S3 (50 % phone penetration) on Geometry A, 5 random seeds × 600 s.
2. Implement the continuity-residual penalty as a one-line autograd term in the PINN; LGBM gets a discretised analogue (penalty as additional feature) for completeness; CNN+LSTM gets the autograd term.
3. λ-sweep $\in {0.0, 0.01, 0.1, 0.3, 1.0}$ across all 3 models. 3 × 5 × 5 × 600 / 60 = 75 training runs at the headline scale — feasible on a single workstation in a day.
4. Persist per-window achieved residual + per-cell MAE per (model, λ, seed).

Gate to Phase C: the (penalty lift, achieved residual, MAE) trio is plotted per model; the headline figure (λ-sweep curve × 3 models) exists.

Phase C — Fidelity / scope follow-ons (optional)

Conditional on Phase B's λ-sweep direction; only run if the direction is in doubt or the mechanism signal is borderline.

1. Sionna RT spot-check — one (Geometry A, S3, N=8) configuration; re-run the LGBM/PINN λ-sweep on Sionna CSI; check whether the QuaDRiGa-stub direction holds. If yes, headline holds; if no, the QuaDRiGa result becomes an upper bound on the simulation lift.
2. Geometry B — re-run Phase B headline on the corridor-with-side-rooms geometry to deliver L4½.6 cross-geometry transfer evidence.
3. AVM locomotion ablation — re-run Phase B with AVM agents; expect the mechanism signal to survive the locomotion-model change.
4. Random-law counter-test — replace $\nabla \cdot (\rho\mathbf{v})$ with a random conservation law; if MAEs match, the penalty is acting as generic regularisation, not a physics prior. Falsification test for the mechanism claim.

Phase D — Field-mode interface (the bridge to EXP-F*)

The point of Phase D is to swap the synthetic data sources for measured data sources without touching the analyser / model zoo / report code. Activated when EXP-P1 telemetry is available.

1. MobileAppAdapter.parse(app_dump) emits the same trajectory parquet shape as JuPedSimAdapter.run().
2. BLEListenerAdapter.ingest(esp32_c6_scan_log) emits the same RSSI parquet shape as BLEChannelModel.synthesise().
3. FeitCSIAdapter.ingest(pi5_csi_stream) emits the same per-link feature 4-tuple shape as the CSI proxy.
4. The SimulationPipeline.ColdRun strategy unchanged; a new MeasuredRun strategy injects measured adapters where synthetic ones lived. The same run-card schema applies.

Expected outputs

• _attachments/exp-s1/geometry/a_seminar/{geometry.json,scene.xml}
• _attachments/exp-s1/trajectories/<scenario>/<seed>/positions.parquet
• _attachments/exp-s1/ble_rssi/<scenario>/<seed>/rssi.parquet
• _attachments/exp-s1/density/<scenario>/<seed>/density.parquet
• _attachments/exp-s1/graphs/<scenario>/<seed>/snapshots.pt
• _attachments/exp-s1/results/<model>_<lambda>_<scenario>.parquet
• _attachments/exp-s1/figures/lambda_sweep_geomA_N8.{png,pdf,tex} — headline
• _attachments/.exp-s1-last-run.json — run card (MCP-discoverable)

Analysis plan

Primary metrics

1. Phase-A success — end-to-end wall-clock < 5 min CPU; ≥ 6 child spans; run card valid.
2. Penalty lift $\Delta\mathrm{MAE}(\lambda^) = \mathrm{MAE}(\lambda{=}0) - \mathrm{MAE}(\lambda^)$ per model.
3. Lift consistency — sign of $\Delta\mathrm{MAE}(\lambda^*)$ across the 3 models; sd / mean across models.
4. Achieved residual ↔ MAE correlation — per-window Pearson + Spearman. The penalty's mechanism is "reducing residual ⇒ reducing MAE"; if the correlation is weak, the penalty is acting as generic regularisation.
5. PedPy gate — fundamental diagram falls within the Microscopic insights into pedestrian motion through a bottleneck, resolving spatial and temporal variations ↗ empirical band; Cordes Intrusion / Avoidance numbers reported per scenario.

Key figures

• Fig 1. λ-sweep curves (MAE vs λ) for all 3 models at S3, N=8, Geometry A — the headline.
• Fig 2. Cross-architecture penalty-lift bar chart at $\lambda^*$ — visual evidence for L4½.5.
• Fig 3. Achieved-residual ↔ MAE scatter, coloured by model.
• Fig 4. PedPy fundamental diagram against the Adrian-2024 / Liddle-2022 band.
• Fig 5 (Phase C optional) — λ-sweep on Sionna spot-check vs QuaDRiGa-stub.

Success criteria

• Phase A: end-to-end run completes in < 5 min CPU wall-clock with the gate above. Tempo shows the span tree; MCP exp_runs(exp_id="exp-s1") returns the run card.
• Phase B: penalty lift $\Delta\mathrm{MAE}(\lambda^*) \geq 0.10$ ped/cell on at least 2 of 3 models at S3, Geometry A.
• Phase B: penalty-lift sign is positive across all 3 models with sd / mean ≤ 0.5.
• Phase B: achieved-residual ↔ MAE correlation $\rho > 0.3$ on at least the PINN (and ideally on the others).
• PedPy gate: fundamental-diagram residual within published empirical band; Cordes regime numbers reported.

Risks and mitigations

1. Synthetic-CSI fidelity — the headline number is not predictive of hardware performance. Mitigation: market this as mechanism validation, not performance prediction. The wang2026_2758 3–5 year sim-to-real horizon framing is intact.
2. PINN training instability — λ > 0 can destabilise training if the residual term dominates. Mitigation: λ-sweep starts at 0.01; warmup schedule on the penalty term; gradient-clip.
3. The QuaDRiGa-stub is a one-page statistical model, not QuaDRiGa proper. Mitigation: that's the point — the stub is enough to detect λ-sweep direction. If Phase B's direction is borderline, Phase C upgrades to Sionna RT, not to "real" QuaDRiGa (which has its own MATLAB-Runtime overhead).
4. Random-law counter-test parked in Phase C — if H-S1.2 passes, the falsification test in Phase C is what defends the mechanism interpretation against reviewers. If Phase B doesn't reach Phase C, L4½.5's defensibility is conditional.
5. Phase-D adapter swap drift — synthetic vs measured parquet shapes could drift over time. Mitigation: schema-validation tests in CI that run both adapters against canned fixtures; documented in IP-077.

Dependencies

• Compute: one CPU workstation for Phase A and B; one consumer GPU (≥ 16 GB VRAM) for Phase C Sionna spot-check only.
• Software: poetry install --with sim (new optional extra introduced in IP-077). Pulls jupedsim, pedpy, torch, torch-geometric, lightgbm. Sionna and Sionna-RT only pull when Phase C is enabled.
• No vault dependencies for Phase A/B. No GIS dependency at any phase (Phase D uses gis://floor/<id> only if the room polygon is available; falls back to parametric geometry otherwise).

Related work in vault

Physics-informed loss

• di2023_285b ↗ — λ-sweep range provenance.
• hughes2002_57b4 ↗ · maury2018_d24a ↗ — the prior the penalty enforces.
• zabin2026_a20c ↗ — closest published physics-aware CSI adaptation; doesn't use continuity explicitly (the gap this experiment fills).

Data-scale grounding

• mondal2023_7f7a ↗ — LGBM > deep at this scale.

Pedestrian dynamics ground truth

• liddle2022_ee2c ↗ — Voronoi-density gate.
• cordes2024_05a8 ↗ — regime declarations.

Cross-experiment links

• EXP-P1 — consumes the Phase-D adapter contracts.
• EXP-F1 · EXP-F2 · EXP-F3 — inherit the simulation harness as the data plane.

Notes

The thesis-quality narrative this experiment unlocks:

"Before deploying the BLE calibration campaign on real CSI infrastructure, we validated in simulation that a continuity-residual penalty added to the supervised loss measurably reduces per-cell occupancy MAE across a 3-model zoo, and that the lift's sign is consistent across architectures. The mechanism (Ch3 L3.4 / Ch5 L5.6), not the architecture, is the contribution. Synthetic-CSI fidelity is a known limitation: the simulation-side lift is not predictive of hardware performance; what is predictive is the architectural commitment — the mechanism transfers; the model-specific parameters do not."

The Phase-D adapter swap is the load-bearing engineering decision that lets this experiment be the platform test for EXP-P1 and EXP-F*: same parquet shapes, same graph builder, same model zoo, same report.