Skip to main content

Phase 2: Graph and Flow Integration

Status:In progress
Tags:Hls4mlImplementationArchitecture
Last modified:

Goal

Represent training as hls4ml graph metadata and backend flow work, so the writer receives resolved training artifacts instead of deriving them.

Linked Tasksโ€‹

Flow Shapeโ€‹

The trainable flow should run only when Model.Training.Trainable is enabled. It should be registered through the backend flow system rather than invoked manually from the writer.

The flow should perform these jobs:

PassJob
trainable config validationReject unsupported layer types, missing loss endpoints, invalid controller names, or ambiguous output mappings.
endpoint resolutionAttach ground-truth, loss, loss-gradient seed, and effective output metadata.
reverse traversalProduce a deterministic backward layer order for supported sequential graphs.
precision resolutionAttach trainable typedef names to each layer.
template resolutionAttach backward_config_cpp, backward_function_cpp, loss snippets, and controller snippets.

Implemented So Farโ€‹

TaskCommitFilesWhat changed
HLS4ML-00248a25d86hls4ml/backends/vivado/vivado_backend.py, test/pytest/test_trainable_config.pyRegistered vivado:trainable as a backend flow that runs after vivado:apply_templates and before the writer-facing vivado:ip completion point.
HLS4ML-002084968dbhls4ml/backends/vivado/passes/trainable.py, hls4ml/backends/vivado/vivado_backend.py, test/pytest/test_trainable_config.pyAdded vivado:validate_trainable_config. It is a no-op for inference models and, for trainable models, currently requires positive BatchSize, half_mse, sgd, a supported controller, one output, at least one trainable layer, Dense-only trainable layers, and the required trainable precision attributes.
HLS4ML-00268165be0hls4ml/backends/vivado/passes/trainable.py, hls4ml/backends/vivado/vivado_backend.py, test/pytest/test_trainable_config.pyAdded vivado:resolve_trainable_backward_order. It resolves a single sequential path from model output to model input, rejects branching graphs, and attaches trainable_forward_path, trainable_forward_order, trainable_backward_order, and trainable_output_layer to the ModelGraph.
HLS4ML-00656f9ff00hls4ml/backends/vivado/passes/trainable.py, hls4ml/backends/vivado/vivado_backend.py, test/pytest/test_trainable_config.pyAdded vivado:resolve_trainable_loss_endpoints. It attaches graph-level metadata for the one-output half_mse path: ground-truth input name, scalar loss name/type, loss-gradient seed name/type, loss input tensor/type/shape, output layer, and gradient scale.

The current resolved metadata is intentionally graph-level metadata, not writer logic. The writer should later consume model.trainable_backward_order instead of deriving the backward pass from layer order or generated C++ strings.

Endpoint metadata has started under HLS4ML-006. The remaining HLS4ML-006 work is now codegen-facing: loss config structs, loss helper kernels, ground-truth top-level IO, scalar loss outputs, and actual dL/dy buffer emission. That is the point where we need to review and slim down the old template/header code before porting it.

Initial Graph Supportโ€‹

The first supported graph shape should be intentionally narrow:

Input -> Dense -> OutputLoss

Then:

Input -> Dense -> Activation -> Dense -> OutputLoss

Branches, merges, recurrent layers, convolution, and BatchNorm should be explicit future work, not accidentally half-supported.

Layer Metadataโ€‹

Trainable passes should attach explicit layer attributes for:

  • trainable flag
  • backward function code
  • backward config code
  • gradient input/output typedefs
  • weight and bias gradient typedefs
  • raw update and applied update typedefs
  • accumulator typedefs
  • optimizer-state typedefs
  • references to forward weights, biases, and cached activations

Exit Criteriaโ€‹

Phase 2 is done when a trainable Dense graph reaches the writer with all trainable endpoint and layer metadata already resolved.