Setup and Quick Start
Getting started with
hls4ml is very easy. There are several installation options available and once installed,
it takes only a few lines of code to run your first synthesis.
The latest release of
hls4ml can be installed with
pip install hls4ml
If you want to use our profiling toolbox, you might need to install extra dependencies:
pip install hls4ml[profiling]
hls4ml is also available as a
conda package in the
conda-forge repository. To install, run:
Version of hls4ml available on
conda-forge is outdated, we recommend installing with
pip to get the latest version.
conda install -c conda-forge hls4ml
hls4ml is rapidly evolving and many experimental features and bugfixes are available on the development branch. Development
version can be installed directly from
pip install git+https://github.com/fastmachinelearning/hls4ml@main
hls4ml library depends on a number of Python packages and external tools for synthesis and simulation. Python dependencies are automatically managed
ONNX (version 1.4.0 and newer) is required by the ONNX converter.
PyTorch package is optional. If not installed, the PyTorch converter will not be available.
Running C simulation from Python requires a C++11-compatible compiler. On Linux, a GCC C++ compiler
g++ is required. Any version from a recent
Linux should work. On MacOS, the clang-based
g++ is enough.
To run FPGA synthesis, installation of following tools is required:
Xilinx Vivado HLS 2018.2 to 2020.1 for synthesis for Xilinx FPGAs
Vitis HLS 2022.1 or newer is required for synthesis for Xilinx FPGAs using the experimental
Intel Quartus 20.1 to 21.4 for the synthesis for Intel FPGAs
For basic concepts to understand the tool, please visit the Concepts chapter. Here we give line-by-line instructions to demonstrate the general workflow.
import hls4ml # Fetch a keras model from our example repository # This will download our example model to your working directory and return an example configuration file config = hls4ml.utils.fetch_example_model('KERAS_3layer.json') # You can print it to see some default parameters print(config) # Convert it to a hls project hls_model = hls4ml.converters.keras_to_hls(config) # Print full list of example model if you want to explore more hls4ml.utils.fetch_example_list()
After that, you can use
Vivado HLS to synthesize the model:
# Use Vivado HLS to synthesize the model # This might take several minutes hls_model.build() # Print out the report if you want hls4ml.report.read_vivado_report('my-hls-test')
Done! You’ve built your first project using
hls4ml! To learn more about our various API functionalities, check out our tutorials here.
If you want to configure your model further, check out our Configuration page.
Apart from our main API, we also support model conversion using a command line interface, check out our next section to find out more:
Getting started with hls4ml CLI (deprecated)
As an alternative to the recommended Python PI, the command-line interface is provided via the
To follow this tutorial, you must first download our
git clone https://github.com/fastmachinelearning/example-models
Alternatively, you can clone the
hls4ml repository with submodules
git clone --recurse-submodules https://github.com/fastmachinelearning/hls4ml
The model files, along with other configuration parameters, are defined in the
Further information about
.yml files can be found in Configuration page.
In order to create an example HLS project, first go to
example-models/ from the main directory:
And use this command to translate a Keras model:
hls4ml convert -c keras-config.yml
This will create a new HLS project directory with an implementation of a model from the
To build the HLS project, do:
hls4ml build -p my-hls-test -a
This will create a Vivado HLS project with your model implementation!
NOTE: For the last step, you can alternatively do the following to build the HLS project:
cd my-hls-test vivado_hls -f build_prj.tcl
vivado_hls can be controlled with:
vivado_hls -f build_prj.tcl "csim=1 synth=1 cosim=1 export=1 vsynth=1"
Setting the additional parameters from
0 disables that step, but disabling
synth also disables
For further information about how to use
If you need help for a particular
hls4ml command -hwill show help for the requested
We provide a detailed documentation for each of the command in the Command Help section
pip uninstall hls4ml
If installed with
conda, remove the package with:
conda remove hls4ml