A Python 3 package for producing ipbb-compatible wrappers of hls4ml IPs, along with easy-to-use ipbb_convert and numpy_to_mp7 command-line scripts.
This repository is at a temporary location, it will be moved to mpp-hep soon.
In all cases, make sure your Python environment is the one you want to set up hls4ml-ipbb in.
Clone this repository and run the following command inside your newly-created repository folder:
pip install -e .
If you want to make changes to the code (e.g. tweak the VHDL wrapper template for your use case), you can do so directly in the repository folder.
hls4ml-ipbb takes an hls4ml project and produces an ipbb component directory that you can use in your project using ipbb, e.g. an emp-fwk project (a CERN account required).
Before using the package, make sure that an hls4ml project to be converted has the exported IP (this can be done by running an appropriate feature in your HLS software, e.g. "Export RTL" in Vivado HLS).
The easiest way to start working with hls4ml-ipbb is using the provided ipbb_convert script.
To convert an hls4ml project stored in folder A to an ipbb component to be stored in folder B, run:
ipbb_convert A B
That's it! If a directory B does not exist, it will be automatically created.
ipbb_convert has a few extra options that can or must be used, depending on your use case (e.g. the name of an HLS solution to be processed). Run ipbb_convert -h for the extensive help message.
If you want to integrate hls4ml-ipbb into your Python project, you can do it by using the hls4ml_ipbb module. All public classes and methods should be either documented with docstrings or self-explanatory (if a subclass does not have docstrings, try looking for them in its parent class).
Here is a short example of how to use hls4ml_ipbb to convert an hls4ml project with a Vivado HLS solution called "solution1":
import hls4ml_ipbb
project = hls4ml_ipbb.Project('<path to your hls4ml project>',
backend=hls4ml_ipbb.backend.VivadoBackend())
ip = project.get_ip('solution1')
wrapper = hls4ml_ipbb.VHDLWrapper(ip)
wrapper.save('<path to a directory where the ipbb component should be created>')hls4ml-ipbb includes also a small script numpy_to_mp7 designed for converting numpy files to the textual format recognisable by boards using ipbb (e.g. Imperial MP7).
The script maps the features of the specified input numpy file to a channel for the output file. Multiple parameters can be set to define the mapping, please run numpy_to_mp7 -h to get their full list along with their description.
Here are two usage examples:
numpy_to_mp7 --board_name ALGO_TESTBENCH --link_range 0 111 --generate_float_from_fix False --link_bitwidth 64 --invalid_rows 25 --fixed_point_bits 16 6 --input_data_path y_hls.npy --output_data_path result.txt
numpy_to_mp7 --board_name JETS --link_range 0 111 --generate_float_from_fix True --link_bitwidth 64 --invalid_rows 6 --fixed_point_bits 16 6 --input_data_path X_test.npy --output_data_path source.txt
Only VHDL and Vivado HLS are supported at the moment. However, hls4ml-ipbb is designed with extensibility in mind, so if you need support of a different HDL or HLS software and you are comfortable with Python 3, feel free to contribute!