gun selector: hysteresis measured NEGATIVE, shipped at the lightest setting
Hypothesis under test: the selector chatters (~54 switches/100 ticks) and that chatter suppresses firing, so committing to the virtual-best gun should raise real hit rate. MEASURED AGAINST THE REAL DRUSSGT: it does not. setting switches/100t real hit % dmg/run shots/run no hysteresis 0/0 54.29 7.02% 217 244.8 light 10/0.05 1.95 6.22% 191 235.3 moderate 30/0.15 1.33 5.10% 156 233.9 aggressive 60/0.30 - 5.72% 175 242.5 (16 runs x 7 rounds per config except aggressive = 8; server-side events sidecar; permutation test baseline-vs-moderate p=0.002, baseline-vs-light p=0.18.) Hysteresis cuts chatter 28-54x but every variant fires slightly FEWER shots and deals LESS damage than baseline. Mechanism [INFERRED, consistent with docs/gun_rack_analysis.md 2/4]: the per-tick random tie-break among the tied band is a hedge, and hysteresis destroys it by committing to the virtual-best gun - which is not the real-best, because the virtual metric is a weak, sign-unstable ranker. The chattering was load-bearing. Shipped: GunDwellTicks=10, GunSwitchMargin=0.05 (GUN_SELECTOR_DWELL / GUN_SELECTOR_MARGIN) - the only setting within the baseline's run-to-run spread. GUN_SELECTOR_DWELL=0 GUN_SELECTOR_MARGIN=0 reproduces the pre-change selector exactly. Seam: VirtualTracker, which already owns the other selection state (fitness, the relative floor's peakRateRef), so the bot needs no new fields. bestGun and chooseFromFit stay pure/memoryless, which is why the existing random-tiebreak test needed no change. Guards: test_gun_harness 39/39 (33 original + 6 new hysteresis checks), test_vbullet_metric, test_power_selection, acceptance_offline_vs_online 12/12.
This commit is contained in:
@@ -34,6 +34,34 @@ const
|
||||
## Dimensionless: only if the field collapsed vs its own recent best.
|
||||
SelectorWindow* = 256 ## ticks of per-tick bestRate kept for the RELATIVE floor reference
|
||||
|
||||
# ── selector hysteresis (anti-chatter) ─────────────────────────────────────
|
||||
#
|
||||
# Without these, `chooseFromFit` performs a fresh uniform draw among the tied
|
||||
# set EVERY tick. With the 20% relative tie band that is most of the rack, so
|
||||
# the turret re-aims on ~37% of ticks (live config log; offline replay of the
|
||||
# same selection path: 54.3 switches / 100 ticks). The two constants below
|
||||
# make the selector commit.
|
||||
#
|
||||
# Shipped values are the CONSERVATIVE end of a measured sweep against the real
|
||||
# DrussGT (8-16 runs x 7 rounds per setting, server-side events sidecar).
|
||||
# Offline replay of the same selection path gives the chatter column:
|
||||
# dwell 0 / margin 0.00 : chatter 54.3/100t real 7.02% 217 dmg/run
|
||||
# dwell 10 / margin 0.05 : chatter 1.95/100t real 6.22% 191 dmg/run
|
||||
# dwell 30 / margin 0.15 : chatter 1.33/100t real 5.10% 156 dmg/run
|
||||
# dwell 60 / margin 0.30 : real 5.72% 175 dmg/run (8 runs)
|
||||
# The light setting cuts chatter ~28x and is the only one not distinguishable
|
||||
# from the no-hysteresis baseline (overlapping per-run ranges, permutation
|
||||
# p=0.18); the heavier settings cost real hit rate (moderate p=0.002). So the
|
||||
# conservative setting ships. Set BOTH env knobs to 0 to disable hysteresis.
|
||||
GunDwellTicks* = 10 ## TICKS: once selected, a gun is held for at least
|
||||
## this many ticks unless it becomes disqualified
|
||||
## (below the eligibility sample gate) or the field
|
||||
## collapses (existing floor path -> HeadOn).
|
||||
GunSwitchMargin* = 0.05 ## DIMENSIONLESS fraction of the incumbent's score: a
|
||||
## challenger must beat the incumbent by more than
|
||||
## this (score > incumbent * (1 + margin)) before it is
|
||||
## allowed to displace it. A merely-tied gun cannot.
|
||||
|
||||
MetricEnvVar* = "GUN_VBULLET_METRIC"
|
||||
## RUNTIME switch selecting how a virtual bullet is scored. Read once per
|
||||
## process at module init, so the SAME compiled binary can be A/B'd by
|
||||
@@ -154,6 +182,12 @@ let ActivePooled* = envBool("GUN_SELECTOR_POOL", true)
|
||||
let ActiveRank* = parseRank(getEnv("GUN_SELECTOR_RANK", ""))
|
||||
let ActiveShrink* = max(0.0, envFloat("GUN_SELECTOR_SHRINK", 20.0))
|
||||
|
||||
# Runtime hysteresis knobs, read once per process like the rest, so one binary
|
||||
# can be swept. Defaults equal the shipped constants; setting BOTH to 0
|
||||
# reproduces the pre-hysteresis (pure per-tick) selection for A/B.
|
||||
let ActiveDwellTicks* = max(0, envInt("GUN_SELECTOR_DWELL", GunDwellTicks))
|
||||
let ActiveSwitchMargin* = max(0.0, envFloat("GUN_SELECTOR_MARGIN", GunSwitchMargin))
|
||||
|
||||
# Optional per-process seed so independent A/B runs use independent tie-breaks
|
||||
# (Nim's default rand() stream is identical in every process, which would make
|
||||
# "random" tie-breaks repeat across runs). Unset => leave the RNG untouched.
|
||||
@@ -199,6 +233,7 @@ type
|
||||
tiedCount*: int ## eligible guns within the tie band of bestRate (0 if floor fired)
|
||||
anyQualifies*: bool ## at least one gun reached MinObsBeforeCompete
|
||||
floorRate*: float ## the floor actually applied this tick
|
||||
incumbentKept*: bool ## hysteresis retained the incumbent this tick
|
||||
|
||||
VirtualTracker* = object
|
||||
bullets*: array[MaxBullets, VirtualBullet]
|
||||
@@ -212,12 +247,18 @@ type
|
||||
rateHistHead*: int
|
||||
rateHistCount*: int
|
||||
peakRateRef*: float ## max bestRate in rateHist; 0.0 = not enough history yet
|
||||
# Hysteresis state (see `selectGun`): the incumbent gun and the tick it was
|
||||
# chosen on. `-1` means no gun selected yet. Only the live `selectGun` path
|
||||
# reads/writes these; `bestGun`/`chooseFromFit` stay memoryless.
|
||||
currentGun*: GunId
|
||||
currentSince*: int
|
||||
|
||||
proc initTracker*(numGuns: int, metric = ActiveMetric): VirtualTracker =
|
||||
## `metric` defaults to the process-wide `GUN_VBULLET_METRIC` switch; pass it
|
||||
## explicitly only from tests that need both models in one process.
|
||||
result.numGuns = numGuns
|
||||
result.metric = metric
|
||||
result.currentGun = -1
|
||||
|
||||
proc windowHits(fw: FitnessWindow, want: int): int =
|
||||
## Hits among the most recent `want` samples, in ring order. Reading the last
|
||||
@@ -560,7 +601,9 @@ proc bestPower*(t: VirtualTracker, gunId: GunId, targetId: int = -1): (int, floa
|
||||
|
||||
proc chooseFromFit*(fit: seq[GunFitness], diag: ptr SelectorDiag = nil,
|
||||
mode: SelectorMode = smAbsolute,
|
||||
referenceRate = -1.0): GunId =
|
||||
referenceRate = -1.0,
|
||||
incumbent: GunId = -1,
|
||||
switchMargin = 0.0): GunId =
|
||||
## Core gun ranking over an already-resolved fitness seq. Split out from
|
||||
## `bestGun` so the offline range can rank without copying a VirtualTracker,
|
||||
## and so callers can request `diag` for the selection internals.
|
||||
@@ -574,7 +617,16 @@ proc chooseFromFit*(fit: seq[GunFitness], diag: ptr SelectorDiag = nil,
|
||||
## * `referenceRate` (the recent field-best rate). Pooled over
|
||||
## power bins, since one lucky bin is a poor ranker.
|
||||
## `referenceRate` <= 0 disables the RELATIVE floor (no history yet).
|
||||
## Ties (within the band) are broken randomly to avoid index-0 bias.
|
||||
##
|
||||
## `incumbent` (>= 0) enables switch hysteresis: the incumbent is retained
|
||||
## unless the best eligible gun beats it by the RELATIVE `switchMargin`
|
||||
## (score > incumbentScore * (1 + margin)). Defaults keep the pure-ranking
|
||||
## behaviour the offline analyzer and the `bestGun` tests rely on.
|
||||
##
|
||||
## Ties (within the band) are broken randomly to avoid index-0 bias. The draw
|
||||
## runs ONLY when a switch is actually permitted — a tick that retains the
|
||||
## incumbent returns before `rand`, so the tie-break no longer re-decides
|
||||
## every tick.
|
||||
let pooled = if mode == smRelative: ActivePooled else: false
|
||||
|
||||
var anyQualifies = false
|
||||
@@ -630,6 +682,33 @@ proc chooseFromFit*(fit: seq[GunFitness], diag: ptr SelectorDiag = nil,
|
||||
if scores[gunId] >= bestScore - tieBand:
|
||||
tied.add(gunId)
|
||||
if diag != nil: diag[].tiedCount = tied.len
|
||||
|
||||
# ── switch hysteresis ──────────────────────────────────────────────────────
|
||||
# A settled incumbent is displaced only by a challenger that clears the
|
||||
# relative margin. This is what stops a merely-tied gun from churning the
|
||||
# turret. `incumbent < 0` disables the rule (pure ranking).
|
||||
if incumbent >= 0 and incumbent < fit.len:
|
||||
var incumbentEligible = true
|
||||
if requireMin and not gunEligible(fit[incumbent], true):
|
||||
incumbentEligible = false
|
||||
if incumbentEligible:
|
||||
let incumbentScore = scores[incumbent]
|
||||
let bar = incumbentScore * (1.0 + switchMargin)
|
||||
if bestScore <= bar:
|
||||
if diag != nil: diag[].incumbentKept = true
|
||||
return incumbent
|
||||
# Keep only genuine challengers (guns that clear the margin); if none do,
|
||||
# the incumbent survives even when `bestScore` technically exceeds the bar
|
||||
# (the top gun may sit inside the tie band but not be switched to).
|
||||
var challengers: seq[GunId]
|
||||
for g in tied:
|
||||
if scores[g] > bar: challengers.add g
|
||||
if challengers.len > 0:
|
||||
tied = challengers
|
||||
else:
|
||||
if diag != nil: diag[].incumbentKept = true
|
||||
return incumbent
|
||||
|
||||
if tied.len == 0: return 0
|
||||
result = tied[rand(tied.len - 1)]
|
||||
|
||||
@@ -639,6 +718,63 @@ proc bestGun*(t: VirtualTracker, targetId: int = -1,
|
||||
## Uses per-enemy fitness when targetId >= 0 and data exists; else aggregate.
|
||||
## `diag`, when non-nil, receives the selection internals (bestRate, floor,
|
||||
## tie count) exactly as used by the decision.
|
||||
##
|
||||
## This is the PURE, memoryless ranking primitive: it starts a fresh tie-break
|
||||
## every call. The live bot uses `selectGun` (below), which wraps it with the
|
||||
## dwell/switch-margin hysteresis. Keeping this pure is what lets the offline
|
||||
## analyzer and the harness tests stay deterministic and side-effect free.
|
||||
result = chooseFromFit(t.fitnessFor(targetId), diag,
|
||||
mode = ActiveSelectorMode,
|
||||
referenceRate = t.peakRateRef)
|
||||
|
||||
proc selectGun*(t: var VirtualTracker, targetId: int = -1, tick = 0,
|
||||
diag: ptr SelectorDiag = nil): GunId =
|
||||
## Stateful, sticky gun selection — the LIVE path (`selector.selectShot` calls
|
||||
## this). Wraps the pure `chooseFromFit` ranking with two commitments:
|
||||
##
|
||||
## * minimum dwell — once selected, a gun is held for at least
|
||||
## `GUN_SELECTOR_DWELL` ticks unless it becomes disqualified (below the
|
||||
## eligibility sample gate) or the field collapses (existing floor path ->
|
||||
## HeadOn);
|
||||
## * switch margin — a challenger must beat the incumbent by
|
||||
## `GUN_SELECTOR_MARGIN` (a fraction of the incumbent's score) before it can
|
||||
## displace it, so a merely-tied gun does not.
|
||||
##
|
||||
## Setting BOTH knobs to 0 disables hysteresis entirely and reproduces the old
|
||||
## per-tick behaviour, so the same binary can A/B against the baseline.
|
||||
##
|
||||
## Seam: the incumbent lives in the `VirtualTracker` because the tracker
|
||||
## already owns all other selection state (`fitness`, the floor's
|
||||
## `peakRateRef` history) and is threaded through the whole live loop; the bot
|
||||
## does not need to know about it. `bestGun`/`chooseFromFit` stay pure for the
|
||||
## offline tools.
|
||||
let fit = t.fitnessFor(targetId)
|
||||
var local: SelectorDiag
|
||||
let d = if diag != nil: diag else: addr local
|
||||
|
||||
# Both zero == no hysteresis: pass no incumbent, matching the pre-change
|
||||
# (pure per-tick) selector for a clean A/B.
|
||||
let useIncumbent = ActiveDwellTicks > 0 or ActiveSwitchMargin > 0.0
|
||||
let incumbent = if useIncumbent: t.currentGun else: -1
|
||||
|
||||
let challenger = chooseFromFit(fit, d, ActiveSelectorMode, t.peakRateRef,
|
||||
incumbent = incumbent,
|
||||
switchMargin = ActiveSwitchMargin)
|
||||
|
||||
# The floor collapses the field to HeadOn regardless of dwell.
|
||||
if d[].floorFired:
|
||||
if t.currentGun != 0:
|
||||
t.currentGun = 0
|
||||
t.currentSince = tick
|
||||
return 0
|
||||
|
||||
result = challenger
|
||||
# Minimum dwell: hold the incumbent while it is still eligible.
|
||||
if useIncumbent and t.currentGun >= 0 and t.currentGun < fit.len:
|
||||
let eligible = (not d[].anyQualifies) or gunEligible(fit[t.currentGun], true)
|
||||
if eligible and (tick - t.currentSince) < ActiveDwellTicks:
|
||||
result = t.currentGun
|
||||
|
||||
if result != t.currentGun:
|
||||
t.currentGun = result
|
||||
t.currentSince = tick
|
||||
|
||||
Reference in New Issue
Block a user