Calibration

A Waveflow component’s timing model is loosely-timed (see Timing Models): it predicts a timeline from a few numbers — a latency, an initiation interval, a per-row depth. Those numbers are properties of the synthesized hardware. Calibration is the discipline of fitting them from measurement — running the kernel through synthesis or RTL cosim at a range of sizes, recording the resulting cycle counts (and resource usage), and fitting a model so the fast LT simulation tracks the slow RTL without you transcribing report numbers by hand.

The same machinery calibrates timing (cycles vs. size) and resources (LUT/FF/BRAM vs. a parameter) — both are “fit a small model to a table of measurements.”

The waveflow.calib package is deliberately bare-bones: a thin pandas.DataFrame wrapper for the corpus, plus sklearn-backed and interpolation models with held-out-error / R² / plot helpers. It is not an ML framework — the models are small and physically motivated.

The workflow

synth / cosim sweep   →   CalibDataFrame   →   fit a per-target model   →   predict in the LT sim
 (one row per run)        (the corpus)         (Lin / Interp)               (and validate held-out)

1. Measure. Run the kernel at several sizes; each run is one datapoint (features like n_row, n_col, and measured targets like cycles or bram).
2. Collect the runs into a CalibDataFrame — the structured corpus, one row per measurement.
3. Fit a model per target. Targets have different shapes, so each gets its own model (a linear fit for an affine cycle count, a calibrated lookup for a saturating curve).
4. Predict inside the component’s timing model, and validate on a held-out point so you know the fit generalizes rather than memorizes.

The pieces

The corpus and the models are documented on their own pages. In brief: the corpus is a CalibDataFrame — a thin pandas.DataFrame wrapper holding one timestamped row per synth/cosim measurement; the models fit a single target (e.g. cycles) from a basis of its columns.

In this section

• The corpus — CalibDataFrame — one timestamped row per measurement, a pandas.DataFrame under .df, with save / load.
• Models — the per-target fit / predict / score interface (CalibModel), the linear model (LinCalibModel), and the calibrated lookup (InterpCalibModel).
• A worked example — fit a line to (size, cycles), score it, plot it, hold a point out; then a saturating curve with InterpCalibModel.
• Instrumenting a calibration — the playbook for collecting real data: where to log events in the sim, how to extract timing from a cosim sweep, and how to feed the fitted model back in (worked against the FIR example).

See also

• Fitting a timing model — the conceptual fit (recovering latency / ii from a line) that LinCalibModel performs.
• Timing Analysis Tools — the measurement side: extracting cycle counts and bus spans from a VCD / cosim run (where the datapoints come from).
• examples/rowwise_fir — the richest worked case: a physical, near-fit-free decomposition with a single calibrated InterpCalibModel curve.

---

Table of contents

• The corpus — CalibDataFrame - CalibDataFrame is the calibration corpus: a thin wrapper composing a pandas.DataFrame, one row per synth/cosim measurement. It adds only what a raw frame lacks — a per-row measured_at timestamp and a save/load storage path — and otherwise exposes the underlying frame as .df for native pandas filter/select.
• Models - The per-target calibration models. CalibModel is the fit / predict / score / holdout interface over column-name basis and target. LinCalibModel is an sklearn LinearRegression with coeffs, plot, and a through-origin knob. InterpCalibModel is a calibrated 1-D lookup (a measured table, not a curve fit) for smooth, saturating physical curves.
• A worked example - A minimal end-to-end calibration: build a CalibDataFrame from a few (size, cycles) measurements, fit a LinCalibModel, read its coefficients, score it, hold a point out, and plot it; then calibrate a saturating curve with InterpCalibModel.
• Instrumenting a calibration - The calibration playbook: how to actually collect the data and close the loop so the LT simulation reproduces the RTL timeline. Instrument the sim with begin/end events at the top level, fit each block's primitive in isolation, let the sim compose the end-to-end timing, extract the datapoints from a cosim sweep, and feed the fitted model back into the component. Worked against the FIR example.