RAVEL

RAVEL (Rate-Aware Vectorized Engine for Low-latency) generates a specialized, hls4ml-compatible FPGA inference project. Aria 1.1.0 implements the qualified pair-parallel, two-row wide-stream profile for the CNN-for-Arianna model family, which is capable of processing an 8-channel ADC stream with a rate of up to 4.4 GSa/s on the KU5P. This model distinguishes in real time between neutrino signals generated by Askaryn Radiation and noise, and can detect over 99% of neutrinos at a trigger rate of 1 Hz.

Performance

Like-for-like HLS comparison

Both flows below use the exact same Keras model, hls4ml configuration, part, and clock target. The vanilla project is emitted directly by hls4ml without manual changes to generated C++, headers, Tcl, or YAML.

RAVEL delivers a 17.3x lower initiation interval and 16.9x lower cycle latency, with 86.7% fewer FF, 24.6% fewer LUT, and no BRAM_18K. It uses four DSPs instead of zero. The estimated clock periods are 3.619 ns for vanilla hls4ml and 3.647 ns for RAVEL, both below the 5 ns target. Resource figures in this table are Vitis HLS estimates; see the source-backed comparison evidence and original reports for the full audit.

More Information about implementation using RAVEL, please see the performance of the CNN-Core-Generator.

Install

Use a clean Python 3.11 environment on Linux for the fully qualified generation, C++ verification, and Vitis HLS workflow:

python -m pip install ravel-hls==1.1.0
ravel-hls doctor --json

For an editable source checkout, replace the install command with:

python -m pip install -c constraints/aria-reference.txt -e .

Do not co-install the retired HGQ distribution with hgq2; both own the hgq Python namespace and RAVEL rejects that conflict before generation.

Python API

import hls4ml
import keras
from hgq.layers import QConv2D, QDense
import ravel_hls as ravel

model = keras.models.load_model(
    "model.keras", custom_objects={"QConv2D": QConv2D, "QDense": QDense}
)
hls = hls4ml.utils.config_from_keras_model(
    model, granularity="name", backend="Vitis"
)
hls["Model"].update({"Strategy": "Latency", "ReuseFactor": 1})

config = {
    "Project": {"Name": "cnn_core", "OutputDir": "cnn_core"},
    "HLS": {
        "Backend": "Vitis",
        "IOType": "io_stream",
        "Part": "xcku5p-ffvb676-2-e",
        "ClockPeriod": 5.0,
        "Config": hls,
    },
    "Verification": {"Mode": "required", "Samples": 32, "Seed": 19},
    "Vitis": {"Run": False},
}

project = ravel.convert(model, config)
print(project.status)

Vitis.Run defaults to False. Set it to True to run vitis_hls -f build_prj.tcl after atomic project publication and automatically record the synthesis report. The default Vitis stages are reset and synthesis; CSim, CoSim, validation, export, and Vivado synthesis remain disabled unless their booleans under Vitis.Stages are enabled explicitly. The same operation can be requested later with project.build().

The concise project lifecycle is Project.open(path), project.refresh(model), project.build(), project.record(report_dir), and project.link(). The CLI command ravel-hls inspect PROJECT --json performs full source-integrity checking; add --fast when payload hashing should be skipped.

Parameter packages

Parameters stores portable generation-relevant inference state without generated HLS sources or executable Python objects:

parameters = ravel.Parameters.extract(model)
parameters.save("trained.ravelparams")

project = ravel.Project.open("cnn_core")
project.refresh(ravel.Parameters.load("trained.ravelparams"))

The deterministic archive contains JSON plus NPY arrays for kernel, bias, and learned K/I/F quantizer state. Static quantizer contracts and slot schemas are compatibility-checked before a complete staged regeneration. A parameter package is not encrypted.

Other Information

See the executable CNN-for-Arianna reference, architecture, compatibility, and project format for the full contracts.

Our Project used RAVEL

• CNN Core Generator
• AI Trigger System
• Hi-Lo Gated CNN Trigger
• And more!

License

This project licensed under Apache-2.0. See LICENSE.