code-HFD_lzk / scripts /third_party_convergence_plan.py
Tinghong-Ye22's picture
Add files using upload-large-folder tool
55e0599 verified
Raw History Blame Contribute Delete
11.7 kB
"""CPU-only epoch coverage, exact loss accounting and conservative stop rules.
These are training-only convergence diagnostics, never held-out success claims.
The new budget is independent of the parent's exhausted optimizer schedule.
"""
from __future__ import annotations
import math
import random
from collections import Counter
PROBE_TOLERANCES = {
"control_accuracy": ("higher", 0.02),
"background_only_false_motion_rate": ("lower", 0.05),
"missed_motion_rate": ("lower", 0.02),
"joint_mae_radians": ("lower_relative", 0.10),
}
def _budget(min_epochs, max_epochs):
if (not isinstance(min_epochs, int) or not isinstance(max_epochs, int)
or not 6 <= min_epochs <= max_epochs <= 20):
raise ValueError("New stage requires at least six epochs and at most twenty")
def _positive_integer(value, name):
if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
raise ValueError(f"{name} must be a positive integer")
return value
def plan_epochs(selection, *, batch_size=16, seed=26100701, min_epochs=6, max_epochs=20):
"""Every new epoch consumes all fixed 300 sessions exactly once, with tails.
Source groups are length-sorted; only group order is shuffled independently
per epoch. This neither resamples classes nor changes the loss weighting.
"""
_budget(min_epochs, max_epochs)
_positive_integer(batch_size, "batch_size")
rows = selection["sessions"]
ids = selection["session_ids"]
if (selection.get("split", "train") != "train" or len(rows) != 300
or len(ids) != 300 or len(set(ids)) != 300
or [r["session_id"] for r in rows] != list(ids)):
raise ValueError("Expected exactly 300 aligned, unique, train-only sessions")
classes = Counter(r["session_type"] for r in rows)
if len(classes) != 6 or set(classes.values()) != {50}:
raise ValueError("Expected six classes, fifty sessions per class")
lengths = [_positive_integer(r["dense_steps"], "dense_steps") for r in rows]
semantic = [_positive_integer(r["semantic_steps"], "semantic_steps") for r in rows]
if any(r.get("split", "train") != "train" for r in rows):
raise ValueError("Held-out sessions cannot enter this training stage")
indices = sorted(range(len(rows)), key=lambda i: (lengths[i], ids[i]))
groups = [indices[i:i + batch_size] for i in range(0, len(indices), batch_size)]
epochs = []
for epoch in range(1, max_epochs + 1):
epoch_seed = int(seed) + epoch * 1_000_003
ordered = [list(group) for group in groups]
random.Random(epoch_seed).shuffle(ordered)
steps = [max(lengths[i] for i in group) for group in ordered]
epochs.append({"epoch": epoch, "seed": epoch_seed,
"source_indices": ordered, "group_steps": steps,
"source_count": len(rows), "optimizer_updates": sum(steps),
"action_samples": sum(lengths), "control_samples": sum(semantic),
"class_counts": dict(sorted(classes.items()))})
return {"schema": 1, "evaluation_split": "train_only", "batch_size": batch_size,
"seed": int(seed), "min_epochs": min_epochs, "max_epochs": max_epochs,
"epochs": epochs, "max_optimizer_updates": sum(e["optimizer_updates"] for e in epochs),
"policy": "complete original sources once each epoch; length groups; epoch-shuffled group order; no loss reweighting"}
class EpochLossAccumulator:
"""Accumulate actual active-example sums, not batch or logged-row means.
The driver must call add for EVERY optimizer event, not just persisted log
rows, and supply actual active source/window counts (not batch capacity).
control_samples is zero on action-only updates, so absent CE is permitted.
"""
def __init__(self):
self.action_sum = 0.0
self.action_samples = 0.0
self.control_sum = 0.0
self.control_samples = 0.0
self.optimizer_updates = 0
self.control_updates = 0
def add(self, *, action_loss, action_samples, control_ce=None, control_samples=0):
values = (action_loss, action_samples, control_samples)
if any(not math.isfinite(float(value)) for value in values):
raise FloatingPointError("Nonfinite action loss or sample count")
action_loss, action_samples, control_samples = map(float, values)
if action_loss < 0 or action_samples <= 0 or control_samples < 0:
raise ValueError("Loss must be nonnegative and active action count positive")
if control_samples > action_samples + 1e-6:
raise ValueError("Control count cannot exceed active action-example count")
if control_samples:
if control_ce is None or not math.isfinite(float(control_ce)):
raise FloatingPointError("Semantic update requires finite control CE")
if float(control_ce) < 0:
raise ValueError("Control CE must be nonnegative")
elif control_ce is not None and not math.isfinite(float(control_ce)):
raise FloatingPointError("Nonfinite supplied control CE")
self.action_sum += action_loss * action_samples
self.action_samples += action_samples
if control_samples:
self.control_sum += float(control_ce) * control_samples
self.control_samples += control_samples
self.control_updates += 1
self.optimizer_updates += 1
def summary(self):
if self.action_samples <= 0 or self.control_samples <= 0:
raise ValueError("A complete epoch must contain action and control supervision")
return {"action_loss": self.action_sum / self.action_samples,
"control_ce": self.control_sum / self.control_samples,
"action_loss_sum": self.action_sum, "action_samples": self.action_samples,
"control_ce_sum": self.control_sum, "control_samples": self.control_samples,
"optimizer_updates": self.optimizer_updates, "control_updates": self.control_updates}
def _probe_regressions(current, reference, tolerances):
reasons = []
for key, (direction, tolerance) in tolerances.items():
value, anchor = current[key], reference[key]
if value is None or anchor is None:
reasons.append(f"{key}: unavailable")
continue
value, anchor = float(value), float(anchor)
if not math.isfinite(value) or not math.isfinite(anchor):
reasons.append(f"{key}: nonfinite")
continue
if direction == "higher":
bad = value < anchor - tolerance
elif direction == "lower":
bad = value > anchor + tolerance
elif direction == "lower_relative":
bad = value > anchor + tolerance * max(abs(anchor), 1e-6)
else:
raise ValueError(f"Unknown metric direction {direction}")
if bad:
reasons.append(f"{key}: {value:.8g} versus {anchor:.8g}")
return reasons
def assess_progress(epoch_records, *, baseline_probe, min_epochs=6, max_epochs=20,
patience=3, relative_tolerance=0.01, denominator_floor=1e-6,
probe_tolerances=None):
"""Return continue/stop_plateau/stop_budget/stop_regression/stop_divergence.
Plateau requires three consecutive non-worsening <1% adjacent-epoch drops
for BOTH losses and no material fixed-panel regression against the anchor
or each previous epoch. One worse probe does not stop training; two do.
A hard budget exit explicitly does NOT assert convergence.
"""
_budget(min_epochs, max_epochs)
_positive_integer(patience, "patience")
if not 0 < relative_tolerance < 1 or not math.isfinite(relative_tolerance):
raise ValueError("Relative tolerance must be finite and between zero and one")
if not 0 < denominator_floor or not math.isfinite(denominator_floor):
raise ValueError("A positive finite denominator floor is required")
tolerances = PROBE_TOLERANCES if probe_tolerances is None else probe_tolerances
records = list(epoch_records)
output = {"action": "continue", "stop": False, "converged": False,
"completed_epochs": len(records), "evaluation_split": "train_only",
"reason": "More complete epochs or stable evidence needed"}
if not records:
return output
def stopped(action, reason):
return {**output, "action": action, "stop": True,
"converged": action == "stop_plateau", "reason": reason}
loss_keys = ("control_ce", "action_loss")
for index, record in enumerate(records, 1):
if record.get("epoch") != index or not record.get("complete") or record.get("source_count") != 300:
raise ValueError("Only consecutive, complete, 300-source epochs may be assessed")
if any(not math.isfinite(float(record[key])) for key in loss_keys):
return stopped("stop_nonfinite", f"Nonfinite loss in epoch {index}")
if any(float(record[key]) < 0 for key in loss_keys):
raise ValueError("Loss cannot be negative")
probe = record.get("probe")
if probe is not None and any(probe.get(key) is not None and not math.isfinite(float(probe[key])) for key in tolerances):
return stopped("stop_nonfinite", f"Nonfinite fixed-panel metric in epoch {index}")
# Both consecutive losses must exceed twice a prior best by a meaningful
# absolute margin; tiny near-zero stochastic variations are not divergence.
if len(records) >= 3:
for key in loss_keys:
prior_best = min(float(r[key]) for r in records[:-2])
boundary = max(2 * prior_best, prior_best + 0.1)
if all(float(r[key]) > boundary for r in records[-2:]):
return stopped("stop_divergence", f"Two consecutive {key} values exceed prior best by >2x and >0.1")
def regressions(record, anchor):
if record.get("probe") is None or anchor is None:
return ["fixed60 panel unavailable"]
return _probe_regressions(record["probe"], anchor, tolerances)
if (len(records) >= 2 and baseline_probe is not None
and all(r.get("probe") is not None for r in records[-2:])):
bad = [regressions(r, baseline_probe) for r in records[-2:]]
# Missing support is insufficient to call either improvement or
# regression, and must not accidentally stop an otherwise valid run.
genuine = [[reason for reason in row if not reason.endswith("unavailable")] for row in bad]
if all(genuine):
return stopped("stop_regression", "Two consecutive fixed60 checks regressed: " + "; ".join(genuine[-1]))
if len(records) >= min_epochs and len(records) >= patience + 1:
window = records[-patience - 1:]
changes = {key: [(float(a[key]) - float(b[key])) / max(abs(float(a[key])), denominator_floor)
for a, b in zip(window, window[1:])] for key in loss_keys}
output["recent_relative_improvements"] = changes
losses_flat = all(0 <= value < relative_tolerance for values in changes.values() for value in values)
probes_ok = all(not regressions(r, baseline_probe) for r in window)
probes_ok = probes_ok and all(not regressions(b, a.get("probe")) for a, b in zip(window, window[1:]))
if losses_flat and probes_ok:
return stopped("stop_plateau", "Both weighted epoch losses plateaued and fixed60 checks did not materially regress")
if len(records) >= max_epochs:
return stopped("stop_budget", "Hard epoch budget reached; convergence is not asserted")
return output