improved logging

python_app/scripts/k209_sweep_benchmark.py

@@ -62,6 +62,7 @@ class BenchmarkResult:
 
 
 def _validate_config() -> None:
+    """Raise if any module-level benchmark constant is outside its valid range."""
     if POINTS < 2:
         raise ValueError("POINTS must be >= 2")
     if WARMUP_SWEEPS < 0:
@@ -77,6 +78,7 @@ def _validate_config() -> None:
 
 
 def _validate_interleaved(raw, expected_points: int) -> None:
+    """Raise unless a raw interleaved sweep has the expected shapes, monotonic axis, and finite values."""
     if raw.frequency_hz.shape != (expected_points,):
         raise RuntimeError(f"Unexpected frequency shape: {raw.frequency_hz.shape}")
     if raw.s11_values.shape != (expected_points * 2,):
@@ -94,6 +96,7 @@ def _validate_interleaved(raw, expected_points: int) -> None:
 
 
 def _validate_result(result, expected_points: int) -> None:
+    """Raise unless a converted SweepResult has the expected shapes and finite S11/S21."""
     if result.x.shape != (expected_points,):
         raise RuntimeError(f"Unexpected frequency shape: {result.x.shape}")
     for name in ("s11", "s21"):
@@ -105,12 +108,18 @@ def _validate_result(result, expected_points: int) -> None:
 
 
 def _percentile(values: list[float], percentile: float) -> float:
+    """Return the nearest-rank percentile (0..1) of ``values``."""
     sorted_values = sorted(values)
     index = round((len(sorted_values) - 1) * percentile)
     return sorted_values[index]
 
 
 def _run_benchmark(service: CompactMK209Service, *, points: int, warmup: int, sweeps: int, convert: bool) -> BenchmarkResult:
+    """Time ``sweeps`` acquisitions after ``warmup`` warm-up sweeps and return their durations.
+
+    When ``convert`` is True the timed path includes SweepResult construction; otherwise it
+    times the raw interleaved REAL32 acquisition. The first and last sweeps are validated.
+    """
     acquire = service.acquire if convert else service.acquire_interleaved
 
     first = acquire()
@@ -137,6 +146,7 @@ def _run_benchmark(service: CompactMK209Service, *, points: int, warmup: int, sw
 
 
 def _print_limits(limits: dict[str, float | int]) -> None:
+    """Print the device frequency/IFBW/power/point limits as a single human-readable line."""
     print(
         "K209 limits: "
         f"frequency={limits['min_frequency_hz']:.0f}..{limits['max_frequency_hz']:.0f} Hz, "
@@ -147,6 +157,7 @@ def _print_limits(limits: dict[str, float | int]) -> None:
 
 
 def main() -> int:
+    """Run the K209 sweep-acquisition benchmark and print timing/throughput statistics."""
     _validate_config()
 
     sweep = RadarSweepModel(