Metadata-Version: 2.4
Name: ravel-hls
Version: 1.2.4
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

# 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.

| Flow | II | Latency (cycles) | BRAM_18K | DSP | FF | LUT |
|---|---:|---:|---:|---:|---:|---:|
| Vanilla hls4ml | 3076 | 3084 | 18 | 0 | 26275 | 38365 |
| RAVEL Aria 1.1.0 | 178 | 183 | 0 | 4 | 3483 | 28922 |

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](references/cnn_for_arianna/legacy/reports/hls4ml_exact_current.json)
and [original reports](references/cnn_for_arianna/README.md) for the full audit.

More Information about implementation using RAVEL, 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 environment on Linux for the fully qualified generation,
C++ verification, and Vitis HLS workflow:

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

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

```bash
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

```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)
```

`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!

## License
This project licensed under Apache-2.0. See [LICENSE](LICENSE).
