Skip to main content

Phase 5: ENABOL Bridge and Validation

Status:Planned
Tags:Hls4mlImplementationTraining
Last modified:

Goal

Make current ENABOL produce trainable hls4ml configurations and reference traces, then use CSIM to compare firmware behavior against software behavior.

Linked Tasksโ€‹

Notebook Entry Pointโ€‹

The first working notebook is:

/Users/mbvalentin/scripts/ENABOL/workspace/compilation/pipe000_first_compilation_pipeline.ipynb

It should become the small, reproducible path from current ENABOL model construction to hls4ml config export and compilation.

Bridge Responsibilitiesโ€‹

The ENABOL bridge should:

  • build a simple model and dataset
  • apply a requested toolchain profile through enabol.toolchain.toolchain_environment()
  • compute precision recommendations
  • emit Model.Training
  • emit per-layer trainable precision overrides
  • export ground-truth inputs for the testbench
  • export reference traces for forward output, loss, gradients, alpha, and updated parameters

Validation Policyโ€‹

Start with local CSIM and software trace comparison. Vitis/Vivado synthesis can happen later on the server; it should not block the first config and codegen work on the Mac.

Toolchain setup is tracked separately in Toolchain Profiles. The notebook should not set compiler paths directly; it should pass a profile name into the compile bridge once enabol.compile is implemented.

Compile APIโ€‹

The first bridge entry point is:

from enabol.compile import compile

hls_model, hls_config = compile(
model=model,
dataset=dataset,
backend="Vitis",
toolchain="auto",
output_dir="workspace/compilation/pipe000_first_compilation_pipeline",
project_name="pipe000_dense",
part="xcku035-fbva676-2-e",
io_type="io_parallel",
strategy="Latency",
reuse_factor=1,
trainable=True,
optimizer="sgd",
learning_rate=0.01,
batch_size=1, # rounded up to a power of two in Model.Training.BatchSize
epochs=2, # CSIM trainable testbench epochs
shuffle=True, # shuffle samples once per epoch in CSIM
shuffle_seed=13, # deterministic bring-up shuffling
log_every=1, # console logging cadence in global train steps
loss="half_mse",
controller="ctrl-gt-order-0",
precision=precision_dict,
write=True,
compile_cpp=False,
build=False,
)

toolchain="auto" is applied only when build=True. This lets Mac notebooks generate and inspect the hls4ml project without failing on Kona-only paths. On Kona, setting build=True activates the default 2024.1 toolchain profile before hls4ml calls vitis-run.

build=True also forces a project write before launching Vitis. This is necessary because ENABOL stages dataset files under the output directory before conversion; that makes the directory exist, so hls4ml's native ModelGraph.build() will not auto-write build_prj.tcl by directory-existence alone.

For the first notebook trace, use an explicit PrecisionDict:

from enabol.precision import PrecisionDict

precision_dict = PrecisionDict({
"input": {
"value": "ap_fixed<16,8,AP_RND,AP_SAT>",
},
"dense0": {
"weight": "ap_fixed<16,6,AP_RND,AP_SAT>",
"activation": "ap_fixed<16,8,AP_RND,AP_SAT>",
"gradient": "ap_fixed<20,8,AP_RND,AP_SAT>",
"update": "ap_fixed<20,6,AP_RND,AP_SAT>",
"accumulator": "ap_fixed<28,14,AP_RND,AP_SAT>",
},
"loss": {
"value": "ap_fixed<32,16,AP_RND,AP_SAT>",
},
})

The bridge expands these semantic fields into hls4ml trainable fields:

ENABOL fieldhls4ml trainable fields
loss.valueModel.Training.Precision.loss
dense0.gradientgrad_in, grad_out, weight_grad, bias_grad, loss_grad
dense0.updateraw_update, update, optimizer_state
dense0.accumulatorgradient_accum, controller_metric

If no PrecisionDict is passed, the bridge emits conservative placeholder trainable defaults. Those defaults are only for bring-up; automatic precision inference is tracked separately.

Batch size is emitted as a power-of-two hardware cadence. enabol.compile.build_hls_config(...) rounds the requested batch_size up, writes the rounded value to Model.Training.BatchSize, records the original value in Model.Training.BatchSizeRequested, and writes Model.Training.BatchSizeLog2 for shift-based gradient averaging in trainable kernels.

Static learning rate is also part of the generated trainable configuration. For the first path, ENABOL emits Model.Training.Optimizer.LearningRate, hls4ml writes it as trainable_configN::learning_rate in parameters.h, and the SGD call casts that config value into learning_rate_t. We are intentionally not using a top-level learning-rate port yet; dynamic learning-rate IO remains available through LearningRateInput but is deferred until the fixed path passes CSIM.

Trainable CSIM Testbenchโ€‹

When Model.Training.Trainable is true, the Vivado/Vitis writer now emits a trainable-specific *_test.cpp through the normal hls4ml testbench path. This means hls_model.build(csim=True) still uses the standard project script, but the generated C++ testbench trains instead of running a single inference pass.

The generated trainable testbench:

  • loads tb_data/tb_input_features.dat and tb_data/tb_output_predictions.dat
  • indexes all samples once before training
  • shuffles sample order once per epoch when Model.Training.Shuffle is true
  • runs Model.Training.Epochs epochs
  • computes reset_accumulators and batch_end from the rounded power-of-two BatchSize
  • writes predictions to the normal CSIM result log
  • writes loss to tb_data/training/loss.dat
  • writes alpha to tb_data/training/alpha.dat
  • writes controller diagnostics to tb_data/training/controller.dat
  • writes trainable weights and biases once per epoch to per-layer files under tb_data/training/<layer>/
  • prints compact progress every Model.Training.LogEvery global train steps

The current logging is intentionally testbench-side. The firmware kernels stay clean except for the optional HLS4ML_TRAINABLE_TRACE hooks already fenced out of synthesis.

Trace files are comma-delimited .dat files. They intentionally repeat the trace index columns in every file:

# ----
# Trace: loss
# Generated by enabol+hls4ml-trainable
# ENABOL version: 0.1.0
# hls4ml-trainable version: 0.0.0a
# User: ...
# Host: ...
# Date: ...
# Project: ...
# Controller: ...
# Optimizer: ...
# LearningRate: ...
# BatchSize: ...
# Epochs: ...
# ---
epoch,sample,global_step,sample_index,loss
1,1,0,37,2.02597

The controller trace uses the same index columns and then appends the global controller metrics:

epoch,sample,global_step,sample_index,raw_update_norm_sq,controlled_update_norm_sq,actual_update_norm_sq,dgrad_norm_sq,dtheta_for_control_sq,stability_lhs_raw,stability_lhs_ctrl,stability_rhs,alpha_feasible,alpha_state,alpha_code,alpha_min,controller_feasible
1,8,7,37,0.25,0.19043,0.1875,0.5,0.25,0.00005,0.000038,0.5625,0.875,0.9875,28,0.03125,1

For GT-0 and GT-1, controller.dat is written only on batch_end, because the controller law is only meaningful after the batch gradient is available. The control geometry uses the raw optimizer proposal: raw_update_norm_sq and dtheta_for_control_sq are ||Delta theta_raw||^2. For SGD, Delta theta_raw = -eta G, so the learning rate is already included in that value. controlled_update_norm_sq is the alpha-scaled proposal, actual_update_norm_sq is measured after the fixed-point assignment back into stored parameters, and controller_feasible is 0 when the nonzero alpha_min fallback was used because no candidate satisfied the squared inequality.

Layer-local parameter traces live below the global traces:

tb_data/training/dense0/weights.dat
tb_data/training/dense0/biases.dat

Dense weight columns are named weight_<input>_<output> and follow the same row-major flattening as hls4ml dense kernels: flat index input * n_out + output.

epoch and sample are one-based for readability. global_step and sample_index remain zero-based because they are counters and indexes into the original .dat dataset files. Repeating these columns in every trace file is deliberate: traces can be sparse. The current path logs loss and alpha every sample, and logs parameter traces once per epoch with sample_index=-1 because that row describes epoch-end model state rather than a single dataset row.

The generated console output is similarly compact:

Epoch [1/2] - sample 1/128: loss 2.02597, alpha: 1

ENABOL reads these traces through TestbenchData:

from enabol import TestbenchData

tb = TestbenchData.from_dir(hls_model.config.get_output_dir())
tb.plot_training(window_size=30)

TestbenchData.from_dir(...) accepts the hls4ml output directory, tb_data, or tb_data/training. The returned object keeps top-level traces such as loss, alpha, and the columns from controller.dat at tb.frame, parsed display metadata at tb.metadata, and per-trace metadata at tb.metadata_by_trace.

The default training panel treats the controller diagnostics as expected firmware-training signals rather than arbitrary traces. loss is plotted first, alpha is plotted as the controller output, and the global controller norms are plotted together on a twin-axis panel:

tb.plot_training(
metrics=["loss", "alpha", "dgrad_norm", "raw_update_norm"],
scales={"dgrad_norm": "log", "raw_update_norm": "log"},
window_size=30,
)

The norm columns are derived by ENABOL as sqrt(dgrad_norm_sq) and sqrt(raw_update_norm_sq), so the generated firmware only needs to emit the squared accumulator values.

Per-layer parameter traces are loaded into tb.layers when load_weights is enabled. For example, tb.layers["dense0"].weights holds the raw weight evolution and tb.layers["dense0"].stats holds scalar summaries such as weights.mean, weights.std, and weights.norm_l2. tb.stats_frame merges those layer statistics with names such as dense0.weights.mean, and tb.scalar_frame combines top-level traces plus layer statistics for plotting.

The generated metadata comments are emitted by the generated C++ CSIM testbench. Static values such as project, backend, controller, optimizer, loss, and learning rate are injected by the hls4ml writer when it writes *_test.cpp. Runtime values such as User, Host, and Date are read by that C++ testbench during CSIM from the process environment and local clock.

Controller IDs are normalized before trainable writer dispatch. For the currently wired no-controller path, spellings such as none, ctrl-none, ctrl_none, and CTRL-NONE resolve to the same CTRL-NONE behavior. This keeps ENABOL-facing names and generated hls4ml config IDs from fighting over capitalization or separator conventions.

Bridge Change Logโ€‹

TaskDateFilesSummary
HLS4ML-0122026-05-22enabol/compile.py, enabol/__init__.py, tests/test_compile.pyAdded compile(...), build_hls_config(...), trainability resolution, PrecisionDict mapping into ordinary and trainable hls4ml precision fields, dataset testbench export, internal toolchain context use for HLS build, and focused config tests.
HLS4ML-0122026-05-22enabol/compile.py, tests/test_compile.pyAdded default trainable precision emission, expanded semantic precision aliases, and changed trainable=True to apply only to parameterized layers such as Dense.
HLS4ML-0122026-05-22enabol/precision.py, enabol/compile.py, tests/test_precision.pyMoved hls4ml precision translation out of compile.py; compile.py now calls apply_hls_precision_config(...) from precision.py.
HLS4ML-0202026-05-23hls4ml/writer/vivado_writer.py, hls4ml/model/graph.py, enabol/compile.py, test/pytest/test_trainable_config.py, tests/test_compile.pyReplaced literal trainable buffer dimensions with generated config constants, moved static learning rate into the trainable config struct, and added the generated trainable epoch/shuffle/loss-log CSIM testbench.
HLS4ML-0202026-05-23enabol/compile.pyFixed the bridge build path so build=True writes the hls4ml project before Vitis runs, even when dataset staging already created the output directory.
HLS4ML-0372026-05-23hls4ml/writer/vivado_writer.py, hls4ml/model/graph.py, enabol/compile.pyReplaced verbose prediction printing with compact progress logs and added metadata-bearing .dat traces under tb_data/training/ for loss and alpha.
ENB-0242026-05-23enabol/testbench.py, enabol/history.py, tests/test_history.pyAdded ENABOL-side testbench trace loading and plotting through TestbenchData.from_dir(...) and TestbenchData.plot_training(...), while keeping FitHistory scoped to software training.
HLS4ML-0372026-05-23hls4ml/writer/vivado_writer.py, test/pytest/test_trainable_config.pyAdded per-layer epoch-level parameter traces, fixed testbench weight visibility through extern, and normalized accepted no-controller spellings before writer dispatch.
ENB-0242026-05-23enabol/testbench.py, tests/test_history.pyAdded recursive nested-trace loading, sparse-trace plotting support, table-style TestbenchData.__repr__, and per-trace metadata storage.
ENB-0252026-05-23enabol/testbench.py, tests/test_history.pySplit top-level traces from raw per-layer parameter traces, added load_weights, and exposed per-layer parameter summary statistics through tb.stats_frame and tb.scalar_frame.
HLS4ML-0382026-05-23hls4ml/writer/vivado_writer.py, hls4ml/templates/vivado/trainable/controllers/global_throttle.h, enabol/testbench.py, tests/test_history.pyAdded explicit controller metric outputs and tb_data/training/controller.dat, then documented and tested ENABOL-side loading as top-level scalar traces.
ENB-0272026-05-23enabol/testbench.py, tests/test_history.pyPromoted controller diagnostics into the standard TestbenchData.plot_training(...) layout with derived norms, a twin-axis controller panel, and configurable y-axis scales.
HLS4ML-0392026-05-23hls4ml/templates/vivado/trainable/controllers/global_throttle.h, hls4ml/writer/vivado_writer.py, enabol/testbench.py, tests/test_history.pyReplaced actual-update denominator geometry with raw optimizer update geometry, enforced a nonzero alpha candidate floor, and expanded controller telemetry.

The first validation target should be:

Dense(1 -> 1), no bias optional variant, MSE or half-MSE, SGD, CTRL-NONE

Then add:

Dense(1 -> 1), bias, CTRL-GT-ORDER-0
Dense -> activation -> Dense

Exit Criteriaโ€‹

Phase 5 is done when current ENABOL can generate a trainable hls4ml project and compare CSIM outputs against a saved software trace without manual patching of generated firmware.