Skip to main content
Get up and running with hls4ml in under 5 minutes. This guide walks you through installing hls4ml, converting your first neural network model to FPGA firmware, and running synthesis.
1

Install hls4ml

Install hls4ml using pip:
pip install hls4ml
For profiling capabilities, install with the profiling extra:
pip install hls4ml[profiling]
hls4ml supports Python 3.8+. You’ll need an HLS tool (Vivado HLS, Vitis HLS, Quartus, etc.) installed for synthesis, but you can explore conversion without it.
2

Fetch an Example Model

hls4ml provides a collection of example models to get you started quickly. Let’s fetch a simple 3-layer Keras model:
import hls4ml

# Fetch an example model from the hls4ml repository
# This downloads the model and returns a configuration
config = hls4ml.utils.fetch_example_model('KERAS_3layer.json')

# The configuration contains all settings for conversion
print(config)
This downloads:
  • KERAS_3layer.json - Model architecture
  • KERAS_3layer_weights.h5 - Trained weights
  • KERAS_3layer_config.yml - Conversion configuration (if available)
  • Example input/output data for testing
See all available example models:
hls4ml.utils.fetch_example_list()
This prints a list of all available models including Keras, PyTorch, ONNX, and TensorFlow formats.
3

Convert to HLS

Now convert the Keras model to HLS firmware:
# Convert the model to HLS
hls_model = hls4ml.converters.keras_v2_to_hls(config)

# The hls_model is a ModelGraph object representing your neural network
# in the hls4ml intermediate representation
print(hls_model)
To convert your own Keras model instead:
from tensorflow import keras

# Load your trained Keras model
model = keras.models.load_model('my_model.h5')

# Convert with minimal configuration
hls_model = hls4ml.converters.convert_from_keras_model(
    model,
    output_dir='my-hls-test',
    project_name='myproject',
    backend='Vivado',
    hls_config={
        'Model': {
            'Precision': 'ap_fixed<16,6>',
            'ReuseFactor': 1
        }
    }
)
See the Keras Frontend guide for more options.
4

Build the HLS Project

Synthesize the model using your HLS tool. This example uses Vivado HLS:
# Run HLS synthesis
# This generates the C++ code, runs synthesis, and creates reports
hls_model.build()
This step requires Vivado HLS or Vitis HLS installed and available in your PATH. Synthesis can take several minutes depending on your model size and complexity.
The build process:
  1. Generates optimized C++ firmware code
  2. Runs C simulation (csim) to verify correctness
  3. Performs HLS synthesis to generate RTL
  4. Produces resource utilization and timing reports
Control which stages of the build to run:
# Just compile (no synthesis)
hls_model.compile()

# Full build with co-simulation
hls_model.build(csim=True, synth=True, cosim=True)

# Use a different backend
hls_model.build(backend='Vitis')
5

View Results

After synthesis completes, examine the reports to understand resource usage and performance:
# Read and print the synthesis report
hls4ml.report.read_vivado_report('my-hls-test')
The report shows:
  • Latency: Clock cycles required for inference
  • Interval: Throughput (how often you can process new inputs)
  • Resource Usage: DSPs, BRAMs, LUTs, and FFs consumed
  • Clock Period: Achieved timing
# Parse the report into a dictionary
from hls4ml.report import parse_vivado_report

report = parse_vivado_report('my-hls-test')
print(f"Latency: {report['LatencyBest']} cycles")
print(f"Interval: {report['IntervalBest']} cycles")
print(f"DSPs: {report['DSP']}")
Key metrics in the synthesis report:
  • Latency: Total time (in clock cycles) from input to output. Lower is better for real-time applications.
  • Interval (II): Initiation interval - how many cycles between processing consecutive inputs. II=1 means full throughput.
  • DSPs: Digital signal processing blocks used for multiplication/accumulation.
  • BRAMs: Block RAM used for weights and intermediate values.
  • LUTs: Look-up tables for logic implementation.
  • FFs: Flip-flops for registers.
6

Test Your Model

Verify the converted model produces correct results:
import numpy as np

# Create or load test data
X_test = np.load('KERAS_3layer_input.dat')

# Run prediction with hls4ml model
y_hls = hls_model.predict(X_test)

# Compare with original model (if using your own model)
# y_keras = model.predict(X_test)
# print(f"Accuracy match: {np.mean(np.abs(y_keras - y_hls))}")
The predict() method runs a bit-accurate C simulation of the firmware. This verifies correctness before committing to a full FPGA build.

​
Complete Example

Here’s a complete end-to-end example you can copy and run: 
import hls4ml
import numpy as np

# 1. Fetch example model
config = hls4ml.utils.fetch_example_model('KERAS_3layer.json')

# 2. Convert to HLS
hls_model = hls4ml.converters.keras_v2_to_hls(config)

# 3. Compile (generates C++ but doesn't run synthesis)
hls_model.compile()

# 4. Test with example data
X_test = np.load('KERAS_3layer_input.dat')
y_pred = hls_model.predict(X_test)
print(f"Predictions shape: {y_pred.shape}")

# 5. Build and synthesize (requires HLS tools)
hls_model.build(csim=True, synth=True)

# 6. View results
hls4ml.report.read_vivado_report('my-hls-test')

​
Next Steps

Now that you’ve converted your first model, explore more advanced features:

Model Conversion

Learn about the conversion process and configuration options

Precision Optimization

Optimize resource usage with mixed precision and quantization

HLS Backends

Configure different HLS tools (Vivado, Vitis, Quartus)

Profiling

Profile your model to identify optimization opportunities

​
Different Model Frameworks

hls4ml supports multiple ML frameworks. Here’s how to convert models from each: 
import hls4ml
from tensorflow import keras

model = keras.models.load_model('model.h5')

hls_model = hls4ml.converters.convert_from_keras_model(
    model,
    output_dir='my-hls-test',
    backend='Vivado',
    hls_config={'Model': {'Precision': 'ap_fixed<16,6>', 'ReuseFactor': 1}}
)
For detailed information on each framework, see the Keras, PyTorch, and ONNX frontend documentation.

​
Common Issues

Make sure your HLS tool (Vivado HLS, Vitis HLS, etc.) is installed and available in your PATH:
# For Vivado HLS
source /path/to/Vivado/2020.1/settings64.sh

# For Vitis HLS
source /path/to/Vitis_HLS/2022.1/settings64.sh
Check that your layer types are supported:
# List supported Keras layers
print(hls4ml.converters.get_supported_keras_layers())

# List supported PyTorch layers
print(hls4ml.converters.get_supported_pytorch_layers())

# List supported ONNX ops
print(hls4ml.converters.get_supported_onnx_layers())
Increase the reuse factor or reduce precision:
hls_config = {
    'Model': {
        'Precision': 'ap_fixed<8,3>',  # Lower precision
        'ReuseFactor': 8  # Higher reuse (slower but smaller)
    }
}
See Precision Optimization for detailed guidance.
The model accuracy may differ from the original due to quantization. Use profiling to identify problematic layers:
# Profile layer-by-layer accuracy
hls4ml.model.profiling.numerical(model, hls_model, X_test)
See Profiling for more details.

​
Get Help

FAQ

Common questions and synthesis issues

GitHub Discussions

Ask questions and share your projects

Video Tutorial

Introduction to FPGAs, HLS, and ML inference

Full Tutorials

Detailed hands-on tutorials

Build docs developers (and LLMs) love

Get started for freeTalk to us