hls4ml.model package

Subpackages

Submodules

hls4ml.model.attributes module

class hls4ml.model.attributes.Attribute(name, value_type=<class 'int'>, default=None, configurable=False)

Bases: object

property config_name
validate_value(value)
class hls4ml.model.attributes.AttributeDict(layer)

Bases: MutableMapping

class hls4ml.model.attributes.AttributeMapping(attributes, clazz)

Bases: MutableMapping

class hls4ml.model.attributes.ChoiceAttribute(name, choices, default=None, configurable=True)

Bases: Attribute

validate_value(value)
class hls4ml.model.attributes.CodeAttrubute(name)

Bases: Attribute

class hls4ml.model.attributes.CodeMapping(attributes)

Bases: AttributeMapping

class hls4ml.model.attributes.ConfigurableAttribute(name, value_type=<class 'int'>, default=None)

Bases: Attribute

class hls4ml.model.attributes.TypeAttribute(name, default=None, configurable=True)

Bases: Attribute

class hls4ml.model.attributes.TypeMapping(attributes)

Bases: AttributeMapping

class hls4ml.model.attributes.VariableAttribute(name)

Bases: Attribute

class hls4ml.model.attributes.VariableMapping(attributes)

Bases: AttributeMapping

class hls4ml.model.attributes.WeightAttribute(name)

Bases: Attribute

class hls4ml.model.attributes.WeightMapping(attributes)

Bases: AttributeMapping

hls4ml.model.graph module

class hls4ml.model.graph.HLSConfig(config)

Bases: object

The configuration class as stored in the ModelGraph.

Parameters

config (dict) – The configuration dictionary

get_bram_size(layer)
get_compression(layer)
get_config_value(key, default=None)
get_conv_implementation(layer)
get_layer_config(layer)
get_layer_config_value(layer, key, default=None)
get_output_dir()
get_precision(layer, var='default')
get_project_name()
get_reuse_factor(layer)
get_strategy(layer)
get_target_cycles(layer)
is_resource_strategy(layer)
class hls4ml.model.graph.ModelGraph(config, data_reader, layer_list, inputs=None, outputs=None)

Bases: object

The ModelGraph represents the network that is being processed by hls4ml.

Parameters

  • config (dict) – The configuration dictionary

  • data_reader – The data reader from where weights can be extracted

  • layer_list (list(dict)) – The list contains a dictionary for each input layer

  • inputs (list, optional) – The inputs to the model. If None, determined from layer_list

  • outputs (list, optional) – The outputs to the model. If None, determined from layer_list

apply_flow(flow, reapply='single')

Applies a flow (a collection of optimizers).

Parameters

  • flow (str) – The name of the flow to apply

  • reapply (str, optional) – Determines the action to take if the flow and its requirements have already been applied. Possible values are: - ‘all’: Apply the flow and all its requirements. - ‘single’: Apply only the given flow, but skip the already applied requirements. - ‘none’: Skip applying the flow. Defaults to ‘single’.

build(**kwargs)

Builds the generated project using HLS compiler.

Please see the build() function of backends for a list of possible arguments.

compile()

Compile the generated project and link the library into current environment.

Users should call this function if they want to use predict functionality for simulation.

get_input_variables()
get_layer_output_variable(output_name)
get_layers()
get_output_variables()
get_weight_variables()
get_weights_data(layer_name, var_name)
insert_node(node, before=None, input_idx=0)

Insert a new node into the model graph.

The node to be inserted should be created with make_node() function. The optional parameter before can be used to specify the node that follows in case of ambiguities.

Parameters

  • node (Layer) – Node to insert

  • before (Layer, optional) – The next node in sequence before which a new node should be inserted.

  • input_idx (int, optional) – If the next node takes multiple inputs, the input index

Raises

Exception – If an attempt to insert a node with multiple inputs is made or if before does not specify a correct node in sequence.

make_node(kind, name, attributes, inputs, outputs=None)

Make a new node not connected to the model graph.

The ‘kind’ should be a valid layer registered with register_layer. If no outputs are specified, a default output named the same as the node will be created. The returned node should be added to the graph with insert_node or replace_node functions.

Parameters

  • kind (type or str) – Type of node to add

  • name (str) – Name of the node

  • attributes (dict) – Initial set of attributes required to construct the node (Layer)

  • inputs (list) – List of inputs to the layer

  • outputs (list, optional) – The optional list of named outputs of the node

Raises

Exception – If an attempt to insert a node with multiple inputs is made or if before does not specify a correct node in sequence.

Returns

The node created.

Return type

Layer

next_layer()
predict(x)
register_output_variable(out_name, variable)
remove_node(node, rewire=True)

Remove a node from a graph.

By default, this function can connect the outputs of previous node to the input of next one. Note that when removing a leaf node rewire should be set to False.

Parameters

  • node (Layer) – The node to remove

  • rewire (bool, optional) – If True, connects the outputs of the previous node to the inputs of the next node

Raises

Exception – If an attempt is made to rewire a leaf node or a node with multiple inputs/outputs.

replace_node(old_node, new_node)

Replace an existing node in the graph with a new one.

Parameters

  • old_node (Layer) – The node to replace

  • new_node (Layer) – The new node

trace(x)
write()

Write the generated project to disk.

This function converts the model to C++ and writes the generated files in the output directory specified in the config.

hls4ml.model.layers module

class hls4ml.model.layers.Activation(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.BatchNormalization(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.BiasAdd(model, name, attributes, inputs, outputs=None)

Bases: Merge

initialize()
class hls4ml.model.layers.Concatenate(model, name, attributes, inputs, outputs=None)

Bases: Merge

initialize()
class hls4ml.model.layers.Conv1D(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.Conv2D(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.Conv2DBatchnorm(model, name, attributes, inputs, outputs=None)

Bases: Conv2D

initialize()
class hls4ml.model.layers.Dense(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.DepthwiseConv2D(model, name, attributes, inputs, outputs=None)

Bases: Conv2D

initialize()
class hls4ml.model.layers.Dot(model, name, attributes, inputs, outputs=None)

Bases: Merge

initialize()
class hls4ml.model.layers.Embedding(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.GRU(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.GarNet(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
ref_impl = False
class hls4ml.model.layers.GarNetStack(model, name, attributes, inputs, outputs=None)

Bases: GarNet

class hls4ml.model.layers.GlobalPooling1D(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.GlobalPooling2D(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.Input(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.LSTM(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.Layer(model, name, attributes, inputs, outputs=None)

Bases: object

The base class for all layers, which are the nodes in the model graph. Note: they don’t necessarily correspond 1:1 with the network layers.

The expected attributes are index, trace (configurable), and result (type)

Parameters

  • model (ModelGraph) – The ModelGraph that this Layer is part of

  • name (str) – The node name

  • attributes (dict) – Initial set of attributes required to construct the node (Layer)

  • inputs (list) – List of inputs to the layer

  • outputs (list, optional) – The optional list of named outputs of the node

add_bias(quantizer=None)
add_output_variable(shape, dim_names, out_name=None, var_name='layer{index}_out', type_name='layer{index}_t', precision=None)
add_weights(quantizer=None, compression=False)
add_weights_variable(name, var_name=None, type_name=None, precision=None, data=None, quantizer=None, compression=False)
property class_name
expected_attributes = [<hls4ml.model.attributes.Attribute object>, <hls4ml.model.attributes.ConfigurableAttribute object>, <hls4ml.model.attributes.TypeAttribute object>]
get_attr(key, default=None)
get_input_node(input_name=None)
get_input_variable(input_name=None)
get_layer_precision()
get_numbers_cpp()
get_output_nodes(output_name=None)
get_output_use_map()
get_output_variable(output_name=None)
get_variables()
get_weights(var_name=None)
initialize()
precision_cpp()
set_attr(key, value)
class hls4ml.model.layers.Merge(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.PReLU(model, name, attributes, inputs, outputs=None)

Bases: Activation

initialize()
class hls4ml.model.layers.ParametrizedActivation(model, name, attributes, inputs, outputs=None)

Bases: Activation

class hls4ml.model.layers.Pooling1D(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.Pooling2D(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.Reshape(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.Resize(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.SeparableConv1D(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.SeparableConv2D(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.SimpleRNN(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.Softmax(model, name, attributes, inputs, outputs=None)

Bases: Activation

initialize()
class hls4ml.model.layers.TernaryTanh(model, name, attributes, inputs, outputs=None)

Bases: Activation

initialize()
class hls4ml.model.layers.Transpose(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.ZeroPadding1D(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.ZeroPadding2D(model, name, attributes, inputs, outputs=None)

Bases: Layer

initialize()
class hls4ml.model.layers.classproperty(func)

Bases: object

hls4ml.model.layers.register_layer(name, clazz)

hls4ml.model.profiling module

hls4ml.model.profiling.activation_types_hlsmodel(model)
hls4ml.model.profiling.activations_hlsmodel(model, X, fmt='summary', plot='boxplot')
hls4ml.model.profiling.activations_keras(model, X, fmt='longform', plot='boxplot')
hls4ml.model.profiling.activations_torch(model, X, fmt='longform', plot='boxplot')
hls4ml.model.profiling.ap_fixed_WIFS(dtype)
hls4ml.model.profiling.array_to_summary(x, fmt='boxplot')
hls4ml.model.profiling.boxplot(data, fmt='longform')
hls4ml.model.profiling.compare(keras_model, hls_model, X, plot_type='dist_diff')

Compare each layer’s output in keras and hls model. Note that the hls_model should not be compiled before using this.

Parameters

  • keras_model – original keras model

  • hls_model – converted ModelGraph, with “Trace:True” in the configuration file.

  • X (array-like) – Input for the model.

  • plot_type (string) –

    different methods to visualize the y_model and y_sim differences. Possible options include:

    • ’norm_diff’ : square root of the sum of the squares of the differences between each output vectors

    • ’dist_diff’ : The normalized distribution of the differences of the elements between two output vectors

Returns

plot object of the histogram depicting the difference in each layer’s output

Return type

matplotlib figure

hls4ml.model.profiling.get_unoptimized_hlsmodel(model)
hls4ml.model.profiling.get_ymodel_keras(keras_model, X)

Calculate each layer’s ouput and put them into a dictionary

Parameters

  • keras_model – a keras model

  • X (array-like) – Test data on which to evaluate the model to profile activations. Must be formatted suitably for the model.predict(X) method.

Returns

A dictionary in the form {“layer_name”: ouput array of layer}

Return type

dictionary

hls4ml.model.profiling.histogram(data, fmt='longform')
hls4ml.model.profiling.numerical(model=None, hls_model=None, X=None, plot='boxplot')

Perform numerical profiling of a model

Parameters

  • model (keras or pytorch model) – The model to profile

  • hls_model (ModelGraph) – The ModelGraph to profile

  • X (array-like, optional) – Test data on which to evaluate the model to profile activations Must be formatted suitably for the model.predict(X) method

  • plot (str, optional) – The type of plot to produce. Options are: ‘boxplot’ (default), ‘violinplot’, ‘histogram’, ‘FacetGrid’

Returns

The quadruple of produced figures. First weights and biases for the pre- and post-optimization models respectively, then activations for the pre- and post-optimization models respectively. (Optimizations are applied to an ModelGraph by hls4ml, a post-optimization ModelGraph is a final model)

Return type

tuple

hls4ml.model.profiling.types_boxplot(data, fmt='longform')
hls4ml.model.profiling.types_histogram(data, fmt='longform')
hls4ml.model.profiling.types_hlsmodel(model)
hls4ml.model.profiling.weights_hlsmodel(model, fmt='longform', plot='boxplot')
hls4ml.model.profiling.weights_keras(model, fmt='longform', plot='boxplot')
hls4ml.model.profiling.weights_torch(model, fmt='longform', plot='boxplot')

hls4ml.model.types module

class hls4ml.model.types.CompressedType(name, precision, index_precision, **kwargs)

Bases: NamedType

class hls4ml.model.types.CompressedWeightVariable(var_name, type_name, precision, data, reuse_factor, quantizer=None, **kwargs)

Bases: WeightVariable

next()
class hls4ml.model.types.ExponentPrecisionType(width=16, signed=True)

Bases: IntegerPrecisionType

Convenience class to differentiate ‘regular’ integers from those which represent exponents, for QKeras po2 quantizers, for example.

class hls4ml.model.types.ExponentType(name, precision, **kwargs)

Bases: NamedType

class hls4ml.model.types.ExponentWeightVariable(var_name, type_name, precision, data, quantizer=None, **kwargs)

Bases: WeightVariable

next()
class hls4ml.model.types.FixedPrecisionType(width=16, integer=6, signed=True, rounding_mode=None, saturation_mode=None, saturation_bits=None)

Bases: PrecisionType

property rounding_mode
property saturation_mode
class hls4ml.model.types.InplaceVariable(shape, dim_names, proxy)

Bases: Variable

definition_cpp(name_suffix='', as_reference=False)
get_shape()
size_cpp()
class hls4ml.model.types.IntegerPrecisionType(width=16, signed=True)

Bases: PrecisionType

class hls4ml.model.types.NamedType(name, precision, **kwargs)

Bases: object

class hls4ml.model.types.PackedType(name, precision, n_elem, n_pack, **kwargs)

Bases: NamedType

class hls4ml.model.types.PrecisionType(width, signed)

Bases: object

class hls4ml.model.types.Quantizer(bits, hls_type)

Bases: object

class hls4ml.model.types.RoundingMode(value)

Bases: Enum

An enumeration.

RND = 3
RND_CONV = 7
RND_INF = 5
RND_MIN_INF = 6
RND_ZERO = 4
TRN = 1
TRN_ZERO = 2
classmethod from_string(mode)
class hls4ml.model.types.SaturationMode(value)

Bases: Enum

An enumeration.

SAT = 2
SAT_SYM = 4
SAT_ZERO = 3
WRAP = 1
classmethod from_string(mode)
class hls4ml.model.types.Source(code)

Bases: object

class hls4ml.model.types.TensorVariable(shape, dim_names, var_name='layer{index}', type_name='layer{index}_t', precision=None, **kwargs)

Bases: Variable

get_shape()
size()
size_cpp()
class hls4ml.model.types.Variable(var_name, atype, **kwargs)

Bases: object

class hls4ml.model.types.WeightVariable(var_name, type_name, precision, data, quantizer=None, **kwargs)

Bases: Variable

next()
update_precision(new_precision)
class hls4ml.model.types.XnorPrecisionType

Bases: IntegerPrecisionType

Convenience class to differentiate ‘regular’ integers from BNN Xnor ones

hls4ml.model.types.find_minimum_width(data, signed=True)

Helper function to find the minimum integer width to express all entries in the data array without saturation / overflow

Module contents