docs(program.md): remove tried/reverted tables and key-lesson verdicts

Borda · claude · Borda · commit 5d61be1f32d0 · 2026-04-07T12:06:41.000+02:00
Keep "already in the code" tables (prevent duplicate work) but strip
dataset-specific verdicts that anchor future agents against valid hypotheses:
- ByteTrack Phase 1 "tried and reverted" block removed
- SORT Phase 1 "tried and reverted" sub-section removed
- OC-SORT Phase 1 "Optuna findings" paragraph removed

Full campaign history remains in autotune/README.md Journal section.

---
Co-authored-by: Claude Code &lt;noreply@anthropic.com&gt;
diff --git a/autotune/best_config.json b/autotune/best_config.json
@@ -261,4 +261,4 @@
             }
         }
     }
-}
+}
diff --git a/autotune/default_config.json b/autotune/default_config.json
@@ -1,56 +1,56 @@
 {
-  "_comment": "Default tracker parameters used for baseline evaluation (--n-trials 1).",
-  "_edit_here": "Edit this file to change defaults. Do not hard-code values in optimize_tracking.py.",
-  "bytetrack": {
-    "lost_track_buffer": 57,
-    "track_activation_threshold": 0.3328,
-    "minimum_consecutive_frames": 1,
-    "minimum_iou_threshold": 0.146,
-    "stage2_iou_threshold": 0.2999,
-    "iou_age_weight": 0.07197,
-    "high_conf_det_threshold": 0.7952,
-    "q_scale": 0.003,
-    "r_scale": 0.5762,
-    "p_scale": 2.5,
-    "velocity_decay": 0.82,
-    "q_miss_alpha": 0.7961,
-    "max_interpolation_gap": 48,
-    "p_reset_threshold": 12,
-    "oru_threshold": 0,
-    "conf_cost_weight": 0.1696,
-    "stage2_min_updates": 12,
-    "giou_blend": 0.42
-  },
-  "sort": {
-    "lost_track_buffer": 26,
-    "track_activation_threshold": 0.9725,
-    "minimum_consecutive_frames": 1,
-    "minimum_iou_threshold": 0.275,
-    "max_interpolation_gap": 57,
-    "velocity_decay": 0.82,
-    "q_miss_alpha": 0.8,
-    "p_reset_threshold": 10,
-    "oru_threshold": 3,
-    "conf_cost_weight": 0.2,
-    "iou_age_weight": 0.0,
-    "high_conf_det_threshold": 0.0,
-    "stage2_iou_threshold": 0.05
-  },
-  "ocsort": {
-    "lost_track_buffer": 74,
-    "minimum_consecutive_frames": 1,
-    "minimum_iou_threshold": 0.1487990736044123,
-    "direction_consistency_weight": 0.0006177923357997676,
-    "high_conf_det_threshold": 0.6875834299207869,
-    "delta_t": 1,
-    "max_interpolation_gap": 42,
-    "q_scale": 0.7203257524174236,
-    "r_scale": 1.1889118447922835,
-    "p_scale": 0.09520352672425254,
-    "conf_cost_weight": 0.9698770881869533,
-    "iou_age_weight": 0.42792379789381346,
-    "p_reset_threshold": 8,
-    "velocity_decay": 0.9259939633989623,
-    "q_miss_alpha": 0.5122722647370503
-  }
+    "_comment": "Default tracker parameters used for baseline evaluation (--n-trials 1).",
+    "_edit_here": "Edit this file to change defaults. Do not hard-code values in optimize_tracking.py.",
+    "bytetrack": {
+        "lost_track_buffer": 57,
+        "track_activation_threshold": 0.3328,
+        "minimum_consecutive_frames": 1,
+        "minimum_iou_threshold": 0.146,
+        "stage2_iou_threshold": 0.2999,
+        "iou_age_weight": 0.07197,
+        "high_conf_det_threshold": 0.7952,
+        "q_scale": 0.003,
+        "r_scale": 0.5762,
+        "p_scale": 2.5,
+        "velocity_decay": 0.82,
+        "q_miss_alpha": 0.7961,
+        "max_interpolation_gap": 48,
+        "p_reset_threshold": 12,
+        "oru_threshold": 0,
+        "conf_cost_weight": 0.1696,
+        "stage2_min_updates": 12,
+        "giou_blend": 0.42
+    },
+    "sort": {
+        "lost_track_buffer": 26,
+        "track_activation_threshold": 0.9725,
+        "minimum_consecutive_frames": 1,
+        "minimum_iou_threshold": 0.275,
+        "max_interpolation_gap": 57,
+        "velocity_decay": 0.82,
+        "q_miss_alpha": 0.8,
+        "p_reset_threshold": 10,
+        "oru_threshold": 3,
+        "conf_cost_weight": 0.2,
+        "iou_age_weight": 0.0,
+        "high_conf_det_threshold": 0.0,
+        "stage2_iou_threshold": 0.05
+    },
+    "ocsort": {
+        "lost_track_buffer": 74,
+        "minimum_consecutive_frames": 1,
+        "minimum_iou_threshold": 0.1487990736044123,
+        "direction_consistency_weight": 0.0006177923357997676,
+        "high_conf_det_threshold": 0.6875834299207869,
+        "delta_t": 1,
+        "max_interpolation_gap": 42,
+        "q_scale": 0.7203257524174236,
+        "r_scale": 1.1889118447922835,
+        "p_scale": 0.09520352672425254,
+        "conf_cost_weight": 0.9698770881869533,
+        "iou_age_weight": 0.42792379789381346,
+        "p_reset_threshold": 8,
+        "velocity_decay": 0.9259939633989623,
+        "q_miss_alpha": 0.5122722647370503
+    }
 }
diff --git a/autotune/guard.py b/autotune/guard.py
@@ -1,19 +1,34 @@
+# ------------------------------------------------------------------------
+# Trackers
+# Copyright (c) 2026 Roboflow. All Rights Reserved.
+# Licensed under the Apache License, Version 2.0 [see LICENSE for details]
+# ------------------------------------------------------------------------
+
 """Regression guard: ensures no tracker's HOTA drops >0.5% from the stored best."""
 
 import json
 import re
-import subprocess
 import sys
+from contextlib import redirect_stdout
+from io import StringIO
+from pathlib import Path
+
+from optimize_tracking import main as optimize_tracking_main
+
+
+def _run_search(tracker_name: str) -> str:
+    """Run tracker optimization and return captured stdout."""
+    stdout_buffer = StringIO()
+    with redirect_stdout(stdout_buffer):
+        optimize_tracking_main(tracker=tracker_name, det_source="sdp", n_trials=500)
+    return stdout_buffer.getvalue()
+
 
-best = json.load(open("best_config.json"))
+best = json.loads((Path(__file__).parent / "best_config.json").read_text())
 failed = []
 
 for t in ["bytetrack", "sort", "ocsort"]:
-    out = subprocess.run(
-        ["uv", "run", "python", "optimize_tracking.py", t, "sdp", "--n-trials", "500"],
-        capture_output=True,
-        text=True,
-    ).stdout
+    out = _run_search(t)
     m = re.search(r"HOTA=([0-9.]+)", out)
     if not m:
         failed.append(f"{t}: no HOTA output")
diff --git a/autotune/program.md b/autotune/program.md
@@ -129,20 +129,6 @@ These hypotheses were implemented and kept in ByteTrack Phase 1. They are **not
 | Post-processing gap interpolation (max_gap=20) | +1.666%                 |
 | P reset on re-detection after occlusion        | +1.674%                 |
 
-### ByteTrack Phase 1 — tried and reverted (likely to regress for any tracker)
-
-| Hypothesis                                   | Outcome                                         |
-| -------------------------------------------- | ----------------------------------------------- |
-| Non-uniform P init (pos/vel split)           | Both regressions on ByteTrack                   |
-| Size-adaptive R (area scaling)               | Regression                                      |
-| NSA Kalman confidence-gated R                | Regression                                      |
-| Two-stage IoU threshold (Stage 1 ≠ Stage 2)  | Both regressions on ByteTrack                   |
-| Immature track grace period (1 missed frame) | Regression                                      |
-| Joseph-form covariance update                | No change (algebraically equivalent at float32) |
-| Two-hit birth policy                         | Regression                                      |
-| Per-axis velocity decay (pos/size split)     | Regression                                      |
-| Velocity-only Q inflation                    | No change                                       |
-
 ### Research starting points — SOTA-inspired, not yet tried on all trackers
 
 Provided as inspiration, not a prescribed order. Hypotheses apply to the active `{algo}` tracker unless noted.
@@ -183,16 +169,6 @@ Campaign run on `bemch/auto-research` using 3-team parallel strategy (Kalman / A
 
 **New SORT constructor params**: `velocity_decay`, `q_miss_alpha`, `p_reset_threshold`, `oru_threshold`, `conf_cost_weight`, `iou_age_weight`, `high_conf_det_threshold`, `stage2_iou_threshold`
 
-#### Tried and reverted
-
-| Hypothesis                                              | Outcome    |
-| ------------------------------------------------------- | ---------- |
-| xcycsr Kalman state representation                      | −0.51%     |
-| Velocity-adaptive Q scaling                             | −0.06%     |
-| Mahalanobis distance gate                               | Regression |
-| GIoU as association metric                              | Regression |
-| OC-SORT velocity correction (duplicate, second attempt) | Reverted   |
-
 #### Tuned best config (sort/sdp, 500 trials)
 
 ```json
@@ -229,8 +205,6 @@ Campaign run on `bemch/auto-research` using 3-team parallel strategy (Kalman / A
 | P reset to identity on re-detection after gap (p_reset_threshold)                | `9960dd5`  | enables Optuna headroom |
 | Velocity decay + Q inflation during missed frames (velocity_decay, q_miss_alpha) | `9525885`  | +0.43% to HOTA 58.905   |
 
-**Optuna findings**: `direction_consistency_weight` converged near-zero (0.0006) — OCM direction signal hurts on SDP; `conf_cost_weight` converged high (0.97); `iou_age_weight` = 0.43 is effective; `velocity_decay` = 0.926 + `q_miss_alpha` = 0.512 reduce prediction drift.
-
 **New OC-SORT constructor params**: `conf_cost_weight`, `iou_age_weight`, `p_reset_threshold`, `velocity_decay`, `q_miss_alpha`
 
 #### Tuned best config (ocsort/sdp, 500 trials, HOTA=58.905)
diff --git a/trackers/core/sort/kalman.py b/trackers/core/sort/kalman.py
@@ -170,9 +170,7 @@ def update(self, bbox: NDArray[np.float64]) -> None:
             and self._last_observed_bbox is not None
         ):
             bbox_f = bbox.astype(np.float32)
-            virtual_vel = (
-                (bbox_f[:4] - self._last_observed_bbox) / was_lost_for
-            )
+            virtual_vel = (bbox_f[:4] - self._last_observed_bbox) / was_lost_for
             self.state[4, 0] = virtual_vel[0]
             self.state[5, 0] = virtual_vel[1]
             self.state[6, 0] = virtual_vel[2]
diff --git a/trackers/core/sort/utils.py b/trackers/core/sort/utils.py
@@ -50,9 +50,7 @@ def get_alive_trackers(
     return alive_trackers
 
 
-def _compute_diou_matrix(
-    boxes_a: np.ndarray, boxes_b: np.ndarray
-) -> np.ndarray:
+def _compute_diou_matrix(boxes_a: np.ndarray, boxes_b: np.ndarray) -> np.ndarray:
     """Compute Distance IoU (DIoU) between two sets of boxes.
 
     DIoU = IoU - d^2 / c^2 where d is the Euclidean distance between box
@@ -74,9 +72,7 @@ def _compute_diou_matrix(
     x2_inter = np.minimum(boxes_a[:, 2:3], boxes_b[:, 2:3].T)
     y2_inter = np.minimum(boxes_a[:, 3:4], boxes_b[:, 3:4].T)
 
-    inter_area = np.maximum(x2_inter - x1_inter, 0) * np.maximum(
-        y2_inter - y1_inter, 0
-    )
+    inter_area = np.maximum(x2_inter - x1_inter, 0) * np.maximum(y2_inter - y1_inter, 0)
 
     # Areas of individual boxes
     area_a = (

Original file line number	Diff line number	Diff line change
`@@ -261,4 +261,4 @@`
`261`	`261`	`}`
`262`	`262`	`}`
`263`	`263`	`}`
`264`		`-}`
	`264`	`+}`