hls4ml.converters package

Subpackages

Submodules

hls4ml.converters.keras_v2_to_hls module

class hls4ml.converters.keras_v2_to_hls.KerasFileReader(config)

Bases: KerasReader

get_weights_data(layer_name, var_name)

class hls4ml.converters.keras_v2_to_hls.KerasModelReader(keras_model)

Bases: KerasReader

get_weights_data(layer_name, var_name)

class hls4ml.converters.keras_v2_to_hls.KerasNestedFileReader(data_reader, nested_path): Bases: KerasFileReader

class hls4ml.converters.keras_v2_to_hls.KerasReader

Bases: object

get_weights_data(layer_name, var_name)

class hls4ml.converters.keras_v2_to_hls.KerasWrappedLayerFileReader(data_reader, layer_path): Bases: KerasFileReader

class hls4ml.converters.keras_v2_to_hls.KerasWrappedLayerReader(layer)

Bases: KerasReader

get_weights_data(layer_name, var_name)

hls4ml.converters.keras_v2_to_hls.get_layer_handlers()

hls4ml.converters.keras_v2_to_hls.get_model_arch(config)

hls4ml.converters.keras_v2_to_hls.get_supported_keras_layers()

Returns the list of Keras layers that the converter can parse.

The returned list contains all Keras layers that can be parsed into the hls4ml internal representation. Support for computation of these layers may vary across hls4ml backends and conversion configuration.

Returns:: The names of supported Keras layers.
Return type:: list

hls4ml.converters.keras_v2_to_hls.get_weights_data(data_reader, layer_name, var_name)

hls4ml.converters.keras_v2_to_hls.keras_handler(*args)

hls4ml.converters.keras_v2_to_hls.keras_v2_to_hls(config)

hls4ml.converters.keras_v2_to_hls.parse_default_keras_layer(keras_layer, input_names)

hls4ml.converters.keras_v2_to_hls.parse_keras_model(model_arch, reader)

hls4ml.converters.keras_v2_to_hls.register_keras_layer_handler(layer_cname, handler_func)

Register a handler function for the given layer class name.

The handler function should have the following signature:: parse_func(keras_layer, input_names, input_shapes, data_reader, config):

Parameters:

layer_cname (str) – The name of Keras layer (the ‘class_name’ property in the layer’s config)
handler_func (callable) – The handler function

Raises:

Exception – If the layer class has already been registered.

hls4ml.converters.keras_v3_to_hls module

class hls4ml.converters.keras_v3_to_hls.KerasV3HandlerDispatcher(layer_handlers: dict[str, Callable[[keras.Layer, Sequence[keras.KerasTensor], Sequence[keras.KerasTensor]], tuple[dict[str, Any], ...]]], v2_layer_handlers=None)

Bases: object

Dispatcher class to handle different types of keras v3 layers.

v2_call(layer: keras.layers.Layer, inp_tensors: Sequence[KerasTensor], out_tensors: Sequence[KerasTensor])

v3_call(layer: keras.layers.Layer, inp_tensors: Sequence[KerasTensor], out_tensors: Sequence[KerasTensor])

class hls4ml.converters.keras_v3_to_hls.UniqueName

Bases: object

Helper class to generate unique names for layers, if one being used multiple times.

next_name(name: str)

reset()

hls4ml.converters.keras_v3_to_hls.get_io_tensors(layer: keras.Layer, node_whitelist: set[int] | None = None)

Given a keras layer, return a list of tuples of input and output tensors. If the layer is called only once (i.e., layer is not used multiple times in the same model), the list will contain only one tuple.

The layer must have been built before calling this function.

Parameters:

layer – The layer to get input and output tensors from.
node_whitelist – If not None, only return tensors from nodes with ids in this set, used to filter out nodes that are not part of the model. Defaults to None.

Returns:

A list of tuples of input and output tensors. Each inner tuple contains two tuples: the first with input KerasTensors and the second with output KerasTensors.

hls4ml.converters.keras_v3_to_hls.keras_v3_to_hls(config)

hls4ml.converters.keras_v3_to_hls.parse_keras_v3_model(model: keras.Model)

Parse a keras model into a list of dictionaries, each representing a layer in the HLS model, and a list of input and output layer names.

Parameters:

model – keras.Model

Returns:

layer_list (list[dict[str, Any]]): A list of dictionaries,
each representing a layer in the HLS model.
input_layer_names (list[str]): A list of input layer names.
output_layer_names (list[str]): A list of output layer names.
batch_output_shapes (list[list[int]]): A list of output shapes.

Return type:

A tuple containing

Raises:

ValueError – If a circular dependency is detected.

hls4ml.converters.keras_v3_to_hls.resolve_dependency_relation(model: keras.Model)

Given a keras model, return the following information:

A list of input tensor names
A list of output tensor names
A list of (layer_name, input_tensor_names, output_tensor_names) tuples
A dictionary of tensor_name -> KerasTensor

Parameters:

model – The keras model to analyze.

Returns:

inp_tensor_names (tuple[str, …]): A tuple of input tensor names.
out_tensor_names (tuple[str, …]): A tuple of output tensor names.
layer_io (list[tuple[str, tuple[str, …], tuple[str, …]]]): A list of
tuples, where each tuple contains the layer name, a tuple of its input tensor names, and a tuple of its output tensor names.
tensors (dict[str, KerasTensor]): A dictionary mapping tensor names
to KerasTensor objects.

Return type:

A tuple containing

hls4ml.converters.onnx_to_hls module

hls4ml.converters.onnx_to_hls.compute_pads_1d(operation, layer)

hls4ml.converters.onnx_to_hls.compute_pads_2d(operation, layer)

hls4ml.converters.onnx_to_hls.get_constant_value(graph, constant_name)

hls4ml.converters.onnx_to_hls.get_global_input_shape(graph, inp)

Return the global input shape of the graph with name inp

Parameters:

graph – the onnx graph
inp (str) – the global input name

Returns:

The shape

Return type:

list

Raises:

StopIteration – If the global input name is not found

hls4ml.converters.onnx_to_hls.get_input_shape(graph, node)

Return the input shapes of the node in the model

Parameters:

graph – the onnx graph
node – the onnx node for which the input is desired

Returns:

The shapes of all the inputs

Return type:

list of lists

Raises:

StopIteration – If the an input name is not found in the graph

hls4ml.converters.onnx_to_hls.get_onnx_attribute(operation, name, default=None)

hls4ml.converters.onnx_to_hls.get_out_layer_name(graph): Get the output layer’s name for the model. graph.output only returns the output’s node index

hls4ml.converters.onnx_to_hls.get_supported_onnx_layers()

hls4ml.converters.onnx_to_hls.onnx_handler(*args)

hls4ml.converters.onnx_to_hls.onnx_to_hls(config)

Convert onnx model to hls model from configuration.

Parameters:: config (dict) – ONNX configuration from yaml file or passed through API.
Raises:: Exception – Raised if an unsupported operation is found in the ONNX model.
Returns:: hls4ml model object
Return type:: ModelGraph

hls4ml.converters.onnx_to_hls.parse_onnx_model(onnx_model)

Parses the onnx model, both for configuration building and general processing.

Parameters:: onnx_model – an ONNX model object.
Raises:: Exception – Raised if an unsupported operation is found in the ONNX model.
Returns:: The onnx layers input_layers (list): The input layers output_layers (list): The output layers
Return type:: layer_list (list)

hls4ml.converters.onnx_to_hls.register_onnx_layer_handler(layer_name, handler_func)

hls4ml.converters.onnx_to_hls.replace_char_inconsitency(name): Replace some inconsistent characters that cause issues when writing into HLS.

hls4ml.converters.onnx_to_hls.sanitize_layer_name(layer)

hls4ml.converters.pytorch_to_hls module

class hls4ml.converters.pytorch_to_hls.PyTorchFileReader(config): Bases: PyTorchModelReader

class hls4ml.converters.pytorch_to_hls.PyTorchModelReader(config)

Bases: object

PyTorch reader to extract weights data.

get_weights_data(layer_name, var_name)

hls4ml.converters.pytorch_to_hls.get_supported_pytorch_layers()

hls4ml.converters.pytorch_to_hls.get_weights_data(data_reader, layer_name, var_name)

hls4ml.converters.pytorch_to_hls.parse_pytorch_model(config, verbose=True)

Convert PyTorch model to hls4ml ModelGraph.

Parameters:: config (dict) – The conversion config
Raises:: Exception – On unsupported features of the model.
Returns:: hls4ml model object.
Return type:: ModelGraph

hls4ml.converters.pytorch_to_hls.pytorch_handler(*args)

hls4ml.converters.pytorch_to_hls.pytorch_to_hls(config)

hls4ml.converters.pytorch_to_hls.register_pytorch_layer_handler(layer_name, handler_func)

hls4ml.converters.utils module

hls4ml.converters.utils.compute_padding_1d(pad_type, in_size, stride, filt_size)

Computes the amount of padding required on each side of the 1D input tensor.

In case of same padding, this routine tries to pad evenly left and right, but if the amount of columns to be added is odd, it will add the extra column to the right.

Parameters:

pad_type (str) – Padding type, one of same, valid or causal (case insensitive).
in_size (int) – Input size.
stride (int) – Stride length.
filt_size (int) – Length of the kernel window.

Raises:

Exception – Raised if the padding type is unknown.

Returns:

Tuple containing the padded input size, left and right padding values.

Return type:

tuple

hls4ml.converters.utils.compute_padding_1d_pytorch(pad_type, in_size, stride, filt_size, dilation)

Computes the amount of padding required on each side of the 1D input tensor following pytorch conventions.

In case of same padding, this routine tries to pad evenly left and right, but if the amount of columns to be added is odd, it will add the extra column to the right.

Parameters:

pad_type (str or int) – Padding type. If string, one of same, valid or causal (case insensitive).
in_size (int) – Input size.
stride (int) – Stride length.
filt_size (int) – Length of the kernel window.

Raises:

Exception – Raised if the padding type is unknown.

Returns:

Tuple containing the padded input size, left and right padding values.

Return type:

tuple

hls4ml.converters.utils.compute_padding_2d(pad_type, in_height, in_width, stride_height, stride_width, filt_height, filt_width)

Computes the amount of padding required on each side of the 2D input tensor.

In case of same padding, this routine tries to pad evenly left and right (top and bottom), but if the amount of columns to be added is odd, it will add the extra column to the right/bottom.

Parameters:

pad_type (str) – Padding type, one of same or valid (case insensitive).
in_height (int) – The height of the input tensor.
in_width (int) – The width of the input tensor.
stride_height (int) – Stride height.
stride_width (int) – Stride width.
filt_height (int) – Height of the kernel window.
filt_width (int) – Width of the kernel window.

Raises:

Exception – Raised if the padding type is unknown.

Returns:

Tuple containing the padded input height, width, and top, bottom, left and right padding values.

Return type:

tuple

hls4ml.converters.utils.compute_padding_2d_pytorch(pad_type, in_height, in_width, stride_height, stride_width, filt_height, filt_width, dilation_height, dilation_width)

Computes the amount of padding required on each side of the 2D input tensor following pytorch conventions.

In case of same padding, this routine tries to pad evenly left and right (top and bottom), but if the amount of columns to be added is odd, it will add the extra column to the right/bottom.

Parameters:

pad_type (str or int) – Padding type. If string, one of same or valid (case insensitive).
in_height (int) – The height of the input tensor.
in_width (int) – The width of the input tensor.
stride_height (int) – Stride height.
stride_width (int) – Stride width.
filt_height (int) – Height of the kernel window.
filt_width (int) – Width of the kernel window.

Raises:

Exception – Raised if the padding type is unknown.

Returns:

Tuple containing the padded input height, width, and top, bottom, left and right padding values.

Return type:

tuple

hls4ml.converters.utils.parse_data_format(input_shape, data_format='channels_last')

Parses the given input shape according to the specified data format.

This function can be used to ensure the shapes of convolutional and pooling layers is correctly parsed. If the first element of the given input_shape is None it is interpreted as a batch dimension and discarded.The returned tuple will have the channels dimension last.

Parameters:

input_shape (list or tuple) – Input shape of 2D, 3D or 4D tensor with optional batch dimension of None.
data_format (str, optional) – Data format type, one of channels_first or channels_last. (case insensitive). Defaults to ‘channels_last’.

Raises:

Exception – Raised if the data format type is unknown.

Returns:

The input shape (without the batch dimension) in channels_last format.

Return type:

tuple

Module contents

hls4ml.converters.convert_from_config(config)

Convert to hls4ml model based on the provided configuration.

Parameters:: config – A string containing the path to the YAML configuration file on the filesystem or a dict containing the parsed configuration.
Returns:: hls4ml model.
Return type:: ModelGraph

hls4ml.converters.convert_from_keras_model(model, output_dir='my-hls-test', project_name='myproject', input_data_tb=None, output_data_tb=None, backend='Vivado', hls_config=None, **kwargs)

Convert Keras model to hls4ml model based on the provided configuration.

Parameters:

model – Keras model to convert
output_dir (str, optional) – Output directory of the generated HLS project. Defaults to ‘my-hls-test’.
project_name (str, optional) – Name of the HLS project. Defaults to ‘myproject’.
input_data_tb (str, optional) – String representing the path of input data in .npy or .dat format that will be used during csim and cosim.
output_data_tb (str, optional) – String representing the path of output data in .npy or .dat format that will be used during csim and cosim.
backend (str, optional) – Name of the backend to use, e.g., ‘Vivado’ or ‘Quartus’ or ‘Catapult’.
board (str, optional) – One of target boards specified in supported_board.json file. If set to None a default device of a backend will be used. See documentation of the backend used.
part (str, optional) – The FPGA part. If set to None a default part of a backend will be used. See documentation of the backend used. Note that if board is specified, the part associated to that board will overwrite any part passed as a parameter.
clock_period (int, optional) – Clock period of the design. Defaults to 5.
clock_uncertainty (str, optional) – Clock uncertainty Defaults to 12.5% for Vivado HLS, 27% for Vitis HLS; unused for others
io_type (str, optional) – Type of implementation used. One of ‘io_parallel’ or ‘io_stream’. Defaults to ‘io_parallel’.
hls_config (dict, optional) – The HLS config.
kwargs** (dict, optional) – Additional parameters that will be used to create the config of the specified backend

Raises:

Exception – If precision and reuse factor are not present in ‘hls_config’.

Returns:

hls4ml model.

Return type:

ModelGraph

hls4ml.converters.convert_from_onnx_model(model, output_dir='my-hls-test', project_name='myproject', input_data_tb=None, output_data_tb=None, backend='Vivado', hls_config=None, **kwargs)

Convert Keras model to hls4ml model based on the provided configuration.

Parameters:

model – ONNX model to convert.
output_dir (str, optional) – Output directory of the generated HLS project. Defaults to ‘my-hls-test’.
project_name (str, optional) – Name of the HLS project. Defaults to ‘myproject’.
input_data_tb (str, optional) – String representing the path of input data in .npy or .dat format that will be used during csim and cosim.
output_data_tb (str, optional) – String representing the path of output data in .npy or .dat format that will be used during csim and cosim.
backend (str, optional) – Name of the backend to use, e.g., ‘Vivado’ or ‘Quartus’ or ‘Catapult’.
board (str, optional) – One of target boards specified in supported_board.json file. If set to None a default device of a backend will be used. See documentation of the backend used.
part (str, optional) – The FPGA part. If set to None a default part of a backend will be used. See documentation of the backend used. Note that if board is specified, the part associated to that board will overwrite any part passed as a parameter.
clock_period (int, optional) – Clock period of the design. Defaults to 5.
clock_uncertainty (str, optional) – Clock uncertainty Defaults to 12.5% for Vivado HLS, 27% for Vitis HLS; unused for others
io_type (str, optional) – Type of implementation used. One of ‘io_parallel’ or ‘io_stream’. Defaults to ‘io_parallel’.
hls_config (dict, optional) – The HLS config.
kwargs** (dict, optional) – Additional parameters that will be used to create the config of the specified backend

Raises:

Exception – If precision and reuse factor are not present in ‘hls_config’.

Returns:

hls4ml model.

Return type:

ModelGraph

hls4ml.converters.convert_from_pytorch_model(model, output_dir='my-hls-test', project_name='myproject', input_data_tb=None, output_data_tb=None, backend='Vivado', hls_config=None, **kwargs)

Convert PyTorch model to hls4ml model based on the provided configuration.

Parameters:

model – PyTorch model to convert.
output_dir (str, optional) – Output directory of the generated HLS project. Defaults to ‘my-hls-test’.
project_name (str, optional) – Name of the HLS project. Defaults to ‘myproject’.
input_data_tb (str, optional) – String representing the path of input data in .npy or .dat format that will be used during csim and cosim. Defaults to None.
output_data_tb (str, optional) – String representing the path of output data in .npy or .dat format that will be used during csim and cosim. Defaults to None.
backend (str, optional) – Name of the backend to use, e.g., ‘Vivado’ or ‘Quartus’ or ‘Catapult’. Defaults to ‘Vivado’.
board (str, optional) – One of target boards specified in supported_board.json file. If set to None a default device of a backend will be used. See documentation of the backend used.
part (str, optional) – The FPGA part. If set to None a default part of a backend will be used. See documentation of the backend used. Note that if board is specified, the part associated to that board will overwrite any part passed as a parameter.
clock_period (int, optional) – Clock period of the design. Defaults to 5.
clock_uncertainty (str, optional) – Clock uncertainty Defaults to 12.5% for Vivado HLS, 27% for Vitis HLS; unused for others
io_type (str, optional) – Type of implementation used. One of ‘io_parallel’ or ‘io_stream’. Defaults to ‘io_parallel’.
hls_config (dict, optional) – The HLS config.
kwargs** (dict, optional) – Additional parameters that will be used to create the config of the specified backend.

Raises:

Exception – If precision and reuse factor are not present in ‘hls_config’.

Notes

Pytorch uses the “channels_first” data format for its tensors, while hls4ml expects the “channels_last” format used by keras. By default, hls4ml will automatically add layers to the model which transpose the inputs to the “channels_last” format. Not that this is not supported for the “io_stream” io_type, for which the user will have to transpose the input by hand before passing it to hls4ml. In that case the “channels_last_conversion” argument of the “config_from_pytorch_model” function needs to be set to “internal”. This argument can be used to completely disable this internal conversion. By default, the output of the model remains in the “channels_last” data format. The “transpose_outputs” argument of the “config_from_pytorch_model” can be used to add a layer to the model that transposes back to “channels_first”. As before, this will not work for io_stream.

Returns:: hls4ml model.
Return type:: ModelGraph

hls4ml.converters.convert_from_symbolic_expression(expr, n_symbols=None, lut_functions=None, use_built_in_lut_functions=False, output_dir='my-hls-test', project_name='myproject', input_data_tb=None, output_data_tb=None, precision='ap_fixed<16,6>', **kwargs)

Converts a given (SymPy or string) expression to hls4ml model.

Parameters:

expr (str or sympy.Expr) – Expression to convert. The variables in the expression should be in the form of x0, x1, x2, ....
n_symbols (int, optional) – Number of symbols in the expression. If not provided, the largest index of the variable will be used as the number of symbols. Useful if number of inputs differs from the number of variables used in the expression. Defaults to None.
lut_functions (dict, optional) –
LUT function definitions. Defaults to None. The dictionary should have the form of:
```
{
    '<func_name>': {
        'math_func': '<func>',
        'table_size': <table_size>,
        'range_start': <start>,
        'range_end': <end>,
    }
}
```
where <func_name> is a given name that can be used with PySR, <func> is the math function to approximate (sin, cos, log,…), <table_size> is the size of the lookup table, and <start> and <end> are the ranges in which the function will be approximated. It is strongly recommended to use a power-of-two as a range.
use_built_in_lut_functions (bool, optional) – Use built-in sin/cos LUT functions. Defaults to False.
output_dir (str, optional) – Output directory of the generated HLS project. Defaults to ‘my-hls-test’.
project_name (str, optional) – Name of the HLS project. Defaults to ‘myproject’.
input_data_tb (str, optional) – String representing the path of input data in .npy or .dat format that will be used during csim and cosim.
output_data_tb (str, optional) – String representing the path of output data in .npy or .dat format that will be used during csim and cosim.
precision (str, optional) – Precision to use. Defaults to ‘ap_fixed<16,6>’.
part (str, optional) – The FPGA part. If set to None a default part of a backend will be used.
clock_period (int, optional) – Clock period of the design. Defaults to 5.
compiler (str, optional) – Compiler to use, vivado_hls or vitis_hls. Defaults to vivado_hls.
hls_include_path (str, optional) – Path to HLS inlcude files. If None the location will be inferred from the location of the compiler used. If an empty string is passed the HLS math libraries won’t be used during compilation, meaning Python integration won’t work unless all functions are LUT-based. Doesn’t affect synthesis. Defaults to None.
hls_libs_path (str, optional) – Path to HLS libs files. If None the location will be inferred from the location of the compiler used. Defaults to None.

Returns:

hls4ml model.

Return type:

ModelGraph

hls4ml.converters.link_existing_project(project_dir)

Create a stripped-down ModelGraph from an existing project previously generated by hls4ml.

The returned ModelGraph will only allow compile(), predict() and build() functions to be invoked.

Parameters:: project_dir (str) – Path to the existing HLS project previously generated with hls4ml.
Returns:: hls4ml model.
Return type:: FilesystemModelGraph

hls4ml.converters.load_saved_model(file_path, output_dir=None)

Loads an hls4ml model from a compressed file format (.fml).

See hls4ml.utils.serialization.deserialize_model for more details.

Parameters:

file_path (str or pathlib.Path) – The path to the serialized model file (.fml).
output_dir (str or pathlib.Path, optional) – The directory where extracted testbench data files will be saved. If not specified, the files will be restored to the same directory as the .fml file.

Returns:

The deserialized hls4ml model.

Return type:

ModelGraph

Raises:

FileNotFoundError – If the specified .fml file does not exist.
OSError – If an I/O error occurs during extraction or file operations.

hls4ml.converters.parse_yaml_config(config_file)

Parse conversion configuration from the provided YAML file.

This function parses the conversion configuration contained in the YAML file provided as an argument. It ensures proper serialization of hls4ml objects and should be called on YAML files created by hls4ml. A minimal valid YAML file may look like this:

KerasH5: my_keras_model.h5
OutputDir: my-hls-test
ProjectName: myproject
Part: xcvu13p-flga2577-2-e
ClockPeriod: 5
IOType: io_stream
HLSConfig:
    Model:
    Precision: ap_fixed<16,6>
    ReuseFactor: 10

Please refer to the docs for more examples of valid YAML configurations.

Parameters:: config_file (str) – Location of the file on the filesystem.
Returns:: Parsed configuration.
Return type:: dict