๐ History Module Reference
This page is a coder-facing reference for enabol/history.py. The module contains the FitHistory container used by instrumented software training loops. hls4ml CSIM outputs are handled separately by enabol/testbench.py.
Module Mapโ
| Object | Kind | Purpose |
|---|---|---|
FitHistory | class | Dictionary-like container mapping metric names to NumPy arrays. |
FitHistory.__repr__() | method | Prints metric names and array shapes. |
FitHistory.plot_results(...) | method | Creates the default six-panel diagnostic plot. |
- Split plotting presets by experiment family once EXP-001 and multi-layer tests exist.
- Add optional save/export helpers so notebooks can write figures consistently.
- Consider moving plotting code into
plots.pyifFitHistorystarts carrying too many display responsibilities.
Imports And Dependenciesโ
import numpy as np
import matplotlib.pyplot as plt
history.py intentionally has no TensorFlow dependency. It receives arrays after the software training loop has already converted logs into NumPy values.
Classesโ
FitHistoryโ
class FitHistory(dict[str, np.array]):
def __init__(self, **kwargs):
super().__init__(**kwargs)
FitHistory is a thin dict subclass. Keys are metric names and values are arrays with one entry per logged software training step.
Typical construction happens at the end of BaseModel.train_instrumented(...):
return FitHistory(**{k: np.asarray(v) for k, v in history.items()})
Typical notebook usage:
from enabol import Controller
history = model.train_instrumented(X, Y, controller=Controller.from_str("gt-order-0"))
print(history)
history.plot_results(title="EXP-000A controller run")
Expected keys depend on the training loop. Current one-layer ablations commonly include:
| Key | Meaning |
|---|---|
loss | Training loss per step. |
weight_error_fro | Frobenius error against the teacher matrix, when a reference matrix is supplied. |
grad_norm | Global gradient norm. |
curvature_proxy | Online gradient-change curvature proxy. |
curvature_ema | EMA-smoothed curvature signal used by the controller. |
hessian_lambda_max | Analytic or logged maximum Hessian eigenvalue when available. |
stability_margin_lambda_raw | Raw eta * lambda_max(H) margin. |
alpha_would | Controller throttle that would be applied, even in baseline runs. |
__repr__()โ
def __repr__(self) -> str:
s = "FitHistory:\n"
for k, v in self.items():
s += f" {k}: {v.shape}\n"
return s
Returns a compact shape summary. This is useful in notebooks because it confirms which metrics were recorded without printing full arrays.
Example output:
FitHistory:
loss: (1200,)
grad_norm: (1200,)
curvature_proxy: (1200,)
alpha_would: (1200,)plot_results(title=None)โ
def plot_results(self, title=None):
fig, axs = plt.subplots(3, 2, figsize=(12, 10), sharex=True)
...
Creates the default six-panel plot used by the first global-throttle experiments:
| Panel | Metric |
|---|---|
| Top left | loss |
| Top right | weight_error_fro |
| Middle left | grad_norm |
| Middle right | curvature_proxy, curvature_ema, hessian_lambda_max |
| Bottom left | stability_margin_lambda_raw with a horizontal stability limit at 2.0 |
| Bottom right | alpha_would |
Usage:
history.plot_results(title="Baseline run")
plot_results(...) assumes the history contains the keys above. It is correct for the early one-layer throttle experiments, but future experiments with quantization, phase diagnostics, or multi-layer metrics may need separate plotting presets.
Extension Notesโ
Keep FitHistory lightweight. Its job is to carry software-training arrays and provide simple convenience plots. Testbench parsing, CSIM statistics, and generated firmware trace analysis belong in TestbenchData.
Change Logโ
| Task | Date | Files | Summary |
|---|---|---|---|
| ENB-024 | 2026-05-23 | enabol/history.py, enabol/testbench.py, tests/test_history.py | Kept FitHistory scoped to software training and moved hls4ml CSIM trace parsing/plotting to TestbenchData. |