FAQ

• High-energy physics triggers at CERN’s Large Hadron Collider
• Real-time control systems for quantum computing
• Feedback loops in nuclear fusion reactors
• Low-power environmental monitoring on satellites
• Biomedical signal processing (e.g., arrhythmia classification)

1. Parse the trained model to extract architecture and weights
2. Optimize by fusing layers (e.g., BatchNorm into Conv), applying precision inference
3. Generate C++ HLS code implementing each layer
4. Synthesize with vendor tools (Vivado HLS, Vitis, Quartus, etc.) to create RTL
5. Integrate into FPGA designs or run standalone

• On-chip weight storage: All model parameters stored in FPGA block RAM for immediate access
• Spatial dataflow architecture: Exploits FPGA parallelism by implementing layers as hardware pipelines
• Configurable parallelism: Fully parallel (ReuseFactor=1) for minimum latency or resource-sharing for efficiency
• Fixed-point arithmetic: Uses optimized fixed-point types instead of floating-point
• Layer fusion: Merges operations (e.g., Conv+BatchNorm+ReLU) into single hardware blocks

• io_parallel: 50-200 nanoseconds for small models
• io_stream: 1-10 microseconds for larger models

• Dense (fully connected) layers
• Convolutional layers (Conv1D, Conv2D, DepthwiseConv)
• Pooling layers (MaxPooling, AveragePooling, GlobalPooling)
• Activations (ReLU, sigmoid, tanh, softmax, ELU, LeakyReLU, etc.)
• Batch normalization
• Recurrent layers (LSTM, GRU)
• Residual/skip connections
• Quantized layers (QKeras, HGQ, Brevitas)

• Graph Neural Networks (experimental)
• Transformers (early development, not stable)
• Custom layers (requires extension API)

• Large Language Models (LLMs)
• Large vision transformers
• Extremely novel architectures

• Small models: O(1,000) parameters on modest FPGAs
• Medium models: O(10,000) parameters with quantization
• Larger models: O(100,000) parameters on large FPGAs with aggressive optimization

# Quantization - reduce bit widths
config['Model']['Precision'] = 'ap_fixed<8,3>'

# Increase reuse factor
config['Model']['ReuseFactor'] = 16

# Use streaming I/O
hls_model = hls4ml.converters.convert_from_keras_model(
    model, hls_config=config, io_type='io_stream'
)

1. Part 1: Introduction to FPGAs and HLS
2. Part 2: Your first hls4ml model conversion
3. Part 3: Model optimization and compression
4. Part 4: Advanced features (profiling, custom layers)

import hls4ml
from keras.models import Sequential
from keras.layers import Dense

# Create model
model = Sequential([Dense(64, input_shape=(16,), activation='relu')])

# Convert to HLS
config = hls4ml.utils.config_from_keras_model(model)
hls_model = hls4ml.converters.convert_from_keras_model(
    model, hls_config=config, backend='Vitis'
)

# Test
hls_model.compile()

• Linux or macOS machine with Python 3.10+
• C++ compiler (g++ on Linux, Xcode on macOS)
• 8GB+ RAM recommended

• Vendor HLS tools (see Installation):
  • Vivado HLS 2020.1+ or Vitis HLS 2022.2+ (Xilinx/AMD)
  • Quartus 20.1-21.4 or oneAPI 2024.1-2025.0 (Intel/Altera)
  • Catapult HLS 2024.1+ (Siemens/Mentor)
• 16GB+ RAM recommended for synthesis
• Multi-core CPU helpful (synthesis is parallelizable)

• Target FPGA board matching your chosen part
• JTAG programmer/debugger
• Host interface (PCIe, Ethernet, etc.) if needed

• No HDL (Verilog/VHDL) knowledge required
• No understanding of FPGA primitives needed
• Basic Python and ML framework knowledge sufficient

• Fixed-point arithmetic and precision
• Parallelism vs resource usage tradeoffs
• Latency vs throughput
• FPGA resources (LUTs, FFs, DSPs, BRAMs)

1. Check the log file:
   cat my-hls-test/vivado_hls.log
   # or
   cat my-hls-test/vitis_hls.log
   
2. Look for C++ errors in the generated code:
   # Check for syntax errors
   g++ -c my-hls-test/firmware/myproject.cpp -Imy-hls-test/firmware
   
3. Common causes:
   • Unsupported layer configuration
   • Edge case in layer shape handling
   • Missing layer handler for custom operations
4. Report the bug: Open an issue at github.com/fastmachinelearning/hls4ml with:
   • Model architecture (code or summary)
   • Configuration used
   • Error messages from log
   • hls4ml version

1. Replace with equivalent supported layers (easiest)
2. Use the extension API to add support:
   from hls4ml.converters import register_keras_v2_layer_handler
   from hls4ml.model.layers import Layer
   
   # Define your custom layer
   class MyCustomLayer(Layer):
       def initialize(self):
           # Setup layer attributes
           pass
   
   # Register handler
   @register_keras_v2_layer_handler('MyCustomLayer')
   def parse_my_layer(keras_layer, input_names, input_shapes, data_reader, config):
       # Parse layer and return hls4ml layer
       pass
   
3. Request support via GitHub Discussions

from hls4ml.model.profiling import numerical
import matplotlib.pyplot as plt

# Load your model and test data
model = load_keras_model('model.h5')
X_test = np.load('test_data.npy')

# Convert to HLS
config = hls4ml.utils.config_from_keras_model(model, granularity='name')
hls_model = hls4ml.converters.convert_from_keras_model(
    model, hls_config=config
)

# Profile (requires: pip install hls4ml[profiling])
plots = numerical(
    model=model,
    hls_model=hls_model,
    X=X_test
)

plt.show()

• Box plots show distribution of weights/activations
• Grey boxes show range representable with current precision
• If box-and-whisker extends outside grey box → increase precision
• If grey box is much larger → can reduce precision

git clone https://github.com/YOUR_USERNAME/hls4ml.git
cd hls4ml
pip install -e .[testing]

# Make changes
# Run tests
pytest test/

• Attend online meetings (request invite via CERN e-group)
• Chat on GitHub Discussions
• Present your use cases

We acknowledge the Fast Machine Learning collective as an open community of multi-domain experts and collaborators.

1. Environment info:
   import hls4ml
   print(hls4ml.__version__)
   import sys
   print(sys.version)
   
2. Minimal reproducible example:
   # Code that demonstrates the bug
   
3. Error messages:
   • Full stack trace
   • HLS log files if synthesis failed
4. Expected vs actual behavior