RAVEL

RAVEL (Rate-Aware Vectorized Engine for Low-latency) generates a specialized, hls4ml-compatible FPGA inference project. Aria 1.3.0 supports P2/P4 temporal packing and Dense x1/x2 for the CNN-for-Arianna model family. New conversions default to P4/D2; P2/D1 remains an explicit compatibility choice. The model family 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

All three 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.

Aria 1.3 P4/D2 reduces II by 47.2% relative to Aria 1.1 P2/D1. It uses 8 DSP, 4436 FF, 53502 LUT, and no BRAM; these estimates correspond to 0.44%, 1.02%, 24.66%, and 0% of the selected KU5P. The LUT increase is 85.0% relative to P2/D1 and is the main cost of doubling Dense work per cycle. Resource figures are Vitis HLS estimates. See the Aria 1.3 synthesis and RTL CoSim evidence and reference report.

The throughput requirements of ARIANNA, RNO-G, and IceCube-Gen2 are already met by the current system design (AI Trigger System, v3.3.0). For models with similar architectures and size, processing speed and power consumption are no longer limiting factors.

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

Install

Use a clean Python 3.11 virtual environment on Linux:

python -m pip install ravel-hls

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)

Optimization is optional. Omission selects the versioned aggressive default:

config["Optimization"] = {
    "TemporalPacking": 2,  # 2 or 4
    "DenseParallelism": 1,  # 1 or 2
}

Each axis may be set independently; an omitted axis keeps its aggressive default. Project.refresh() reuses the resolved values recorded by the project and does not apply newer defaults.

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!

The Future Plan

RAVEL will evolve from the closed, qualified specialization flow into a general rate-aware FPGA inference generator. Plans for higher versions are tentative.

Higher versions will focus primarily on expanding functionality and model support. At present, Nocturne 2.0 is expected to bring the target model into its highest practical throughput range. Further versions may still achieve higher throughput, but the remaining headroom is expected to be quite limited.

• Aria 1.x Continue improving the closed P2/P4 x D1/D2 specialization set, deterministic project lifecycle, verification, and tool compatibility. For this version, RAVEL's goal is simply to design an efficient converter for models currently in use or planned for use for high-energy neutrino experiments, e.g., ARIANNA, RNO-G, and IceCube-Gen2.
• Nocturne 2.x Generalize model support, add P8 where system bandwidth and scheduling permit it, and derive balanced layer-level parallelism.
• Rhapsody 3.x Support multiple independent inference contexts within one IP, with configurable resource sharing, duplication.
• Requiem 4.x Select internal parallelism, IP replication, and lane scheduling according to input rate, internal interval, latency, and FPGA resource constraints.

License

This project licensed under Apache-2.0. See LICENSE.