Metadata-Version: 2.4
Name: ravel-hls
Version: 1.4.0
Summary: Rate-Aware Vectorized Engine for Low-latency FPGA inference
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/albertc9/RAVEL
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: hls4ml==1.2.0
Requires-Dist: hgq2==0.1.7
Requires-Dist: Jinja2==3.1.6
Requires-Dist: keras==3.12.1
Requires-Dist: numpy==1.26.4
Requires-Dist: quantizers==1.2.2
Requires-Dist: PyYAML==6.0.3
Requires-Dist: tensorflow-cpu==2.20.0; platform_system == "Linux"
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == "test"
Dynamic: license-file

[![GitHub](https://img.shields.io/badge/GitHub-albertc9%2FRAVEL-181717?logo=github)](https://github.com/albertc9/RAVEL) [![PyPI](https://img.shields.io/pypi/v/ravel-hls?logo=pypi&logoColor=white)](https://pypi.org/project/ravel-hls/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
# RAVEL

RAVEL (Rate-Aware Vectorized Engine for Low-latency) generates a specialized,
hls4ml-compatible FPGA inference project. Aria 1.4.0 supports P2/P4 temporal
packing and Dense x1/x2 for the CNN-for-Arianna model family. New conversions
default to P4/D2 with sequential packed Dense weights; 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 comparison

Same model, hls4ml configuration, KU5P target, and 5 ns clock constraint. OOC
resources and WNS are single-core Vivado 2023.2 post-route results. Resource
counts are followed by KU5P utilization.

| Flow | II | Latency (cycles) | HLS clock (ns) | OOC BRAM tile | OOC DSP | OOC registers | OOC LUTs | OOC WNS (ns) |
|---|---:|---:|---:|---:|---:|---:|---:|---:|
| Vanilla hls4ml | 3076 | 3084 | 3.619 | 5.5 (1.15%) | 1 (0.05%) | 21745 (5.01%) | 18312 (8.44%) | +0.206 |
| RAVEL Aria 1.1.0 P2/D1 | 178 | 183 | 3.647 | 1.0 (0.21%) | 7 (0.38%) | 2953 (0.68%) | 5332 (2.46%) | +1.121 |
| RAVEL Aria 1.3.0 P4/D2 | 94 | 99 | 3.502 | 0.5 (0.10%) | 14 (0.77%) | 3709 (0.85%) | 7861 (3.62%) | +0.817 |
| RAVEL Aria 1.4.0 P4/D2 | 94 | 99 | 3.402 | 1.5 (0.31%) | 15 (0.82%) | 3622 (0.83%) | 6981 (3.22%) | +0.524 |

At 200 MHz, 1 GSa/s equals 3.90625 million 256-sample chunks/s and requires
60.08/3.48/1.84/1.84 equivalent cores for vanilla/Aria 1.1/1.3/1.4. Relative
to vanilla, Aria 1.1/1.3/1.4 reduce equivalent core count by
94.2%/96.9%/96.9%, BRAM by 98.9%/99.7%/99.2%, DSP by 59.5%/57.2%/54.2%,
registers by 99.2%/99.5%/99.5%, and LUTs by 98.3%/98.7%/98.8%. These
linearized estimates allow fractional core counts and exclude all other FPGA
logic.

The throughput requirements of ARIANNA, RNO-G, and IceCube-Gen2 are already met by the current system design ([AI Trigger System, v3.3.0](https://github.com/NuDAQ/AI-Trigger-System/tree/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](https://github.com/NuDAQ/CNN-Core-Generator/tree/d37a0a6dc31cf5a38f0d241f47e21263e0fe9e67#performance) of the CNN-Core-Generator.

## Install

Use a clean Python 3.11 virtual environment on Linux:

```bash
python -m pip install ravel-hls
```

## Python API

```python
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:

```python
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:

```python
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](references/cnn_for_arianna/README.md),
[architecture](docs/architecture.md), [compatibility](docs/compatibility.md), and
[project format](docs/project-format.md) for the full contracts.

## Our Project used RAVEL

- [CNN Core Generator](https://github.com/NuDAQ/CNN-Core-Generator)
- [AI Trigger System](https://github.com/NuDAQ/AI-Trigger-System)
- [Hi-Lo Gated CNN Trigger](https://github.com/NuDAQ/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](LICENSE).
