Skip to main content

๐Ÿ“ˆ History Module Reference

Status:ValidIn progress
Tags:ImplementationHistory
Last modified:

What this page covers

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โ€‹

ObjectKindPurpose
FitHistoryclassDictionary-like container mapping metric names to NumPy arrays.
FitHistory.__repr__()methodPrints metric names and array shapes.
FitHistory.plot_results(...)methodCreates the default six-panel diagnostic plot.
History TODOs
  • 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.py if FitHistory starts 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:

KeyMeaning
lossTraining loss per step.
weight_error_froFrobenius error against the teacher matrix, when a reference matrix is supplied.
grad_normGlobal gradient norm.
curvature_proxyOnline gradient-change curvature proxy.
curvature_emaEMA-smoothed curvature signal used by the controller.
hessian_lambda_maxAnalytic or logged maximum Hessian eigenvalue when available.
stability_margin_lambda_rawRaw eta * lambda_max(H) margin.
alpha_wouldController 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 repr
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:

PanelMetric
Top leftloss
Top rightweight_error_fro
Middle leftgrad_norm
Middle rightcurvature_proxy, curvature_ema, hessian_lambda_max
Bottom leftstability_margin_lambda_raw with a horizontal stability limit at 2.0
Bottom rightalpha_would

Usage:

history.plot_results(title="Baseline run")
Plot preset is not universal

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โ€‹

TaskDateFilesSummary
ENB-0242026-05-23enabol/history.py, enabol/testbench.py, tests/test_history.pyKept FitHistory scoped to software training and moved hls4ml CSIM trace parsing/plotting to TestbenchData.