snntoolbox.parsing

On the input side of the SNN conversion toolbox, models from the following neural network libraries can be parsed:

snntoolbox.parsing.model_libs.keras_input_lib	Keras model parser.
snntoolbox.parsing.model_libs.pytorch_input_lib	PyTorch model parser.
snntoolbox.parsing.model_libs.lasagne_input_lib
snntoolbox.parsing.model_libs.caffe_input_lib

These parsers inherit from AbstractModelParser in

snntoolbox.parsing.utils

Functions common to input model parsers.

See Extending the toolbox on how to extend the toolbox by another input model library.

snntoolbox.parsing.model_libs

keras_input_lib

Keras model parser.

@author: rbodo

class snntoolbox.parsing.model_libs.keras_input_lib.ModelParser(input_model, config)

Bases: snntoolbox.parsing.utils.AbstractModelParser

get_layer_iterable()

Get an iterable over the layers of the network.

Returns:layers Return type:list

get_type(layer)

Get layer class name.

Returns:layer_type – Layer class name. Return type:str

get_batchnorm_parameters(layer)

Get the parameters of a batch-normalization layer.

Returns:mean, var_eps_sqrt_inv, gamma, beta, axis Return type:tuple

get_inbound_layers(layer)

Get inbound layers of layer.

Returns:inbound Return type:Sequence

layers_to_skip

Return a list of layer names that should be skipped during conversion to a spiking network.

Returns:self._layers_to_skip Return type:List[str]

has_weights(layer)

Return True if layer has weights.

initialize_attributes(layer=None)

Return a dictionary that will be used to collect all attributes of a layer. This dictionary can then be used to instantiate a new parsed layer.

get_input_shape()

Get the input shape of a network, not including batch size.

Returns:input_shape – Input shape. Return type:tuple

get_output_shape(layer)

Get output shape of a layer.

Parameters:layer – Layer. Returns:output_shape – Output shape of layer. Return type:Sized

parse_sparse(layer, attributes)

parse_dense(layer, attributes)

Parse a fully-connected layer.

Parameters:

• layer – Layer.
• attributes (dict) – The layer attributes as key-value pairs in a dict.

parse_sparse_convolution(layer, attributes)

parse_convolution(layer, attributes)

Parse a convolutional layer.

Parameters:

• layer – Layer.
• attributes (dict) – The layer attributes as key-value pairs in a dict.

parse_sparse_depthwiseconvolution(layer, attributes)

parse_depthwiseconvolution(layer, attributes)

Parse a depthwise convolution layer.

Parameters:

• layer – Layer.
• attributes (dict) – The layer attributes as key-value pairs in a dict.

parse_pooling(layer, attributes)

Parse a pooling layer.

Parameters:

• layer – Layer.
• attributes (dict) – The layer attributes as key-value pairs in a dict.

get_activation(layer)

Get the activation string of an activation layer.

Parameters:layer – Layer Returns:activation – String indicating the activation of the layer. Return type:str

get_outbound_layers(layer)

Get outbound layers of layer.

Parameters:layer – Layer. Returns:outbound – Outbound layers of layer. Return type:list

parse_concatenate(layer, attributes)

Parse a concatenation layer.

Parameters:

• layer – Layer.
• attributes (dict) – The layer attributes as key-value pairs in a dict.

snntoolbox.parsing.model_libs.keras_input_lib.load(path, filename, **kwargs)

Load network from file.

Parameters:

• path (str) – Path to directory where to load model from.
• filename (str) – Name of file to load model from.

Returns:

A dictionary of objects that constitute the input model. It must contain the following two keys:

• ’model’: keras.models.Sequential

  Keras model instance of the network.

• ’val_fn’: function

  Function that allows evaluating the original model.

Return type:

dict[str, Union[keras.models.Sequential, function]]

snntoolbox.parsing.model_libs.keras_input_lib.evaluate(val_fn, batch_size, num_to_test, x_test=None, y_test=None, dataflow=None)

Evaluate the original ANN.

Can use either numpy arrays x_test, y_test containing the test samples, or generate them with a dataflow (Keras.ImageDataGenerator.flow_from_directory object).

Parameters:

• val_fn – Function to evaluate model.
• batch_size (int) – Batch size
• num_to_test (int) – Number of samples to test
• x_test (Optional[np.ndarray]) –
• y_test (Optional[np.ndarray]) –
• dataflow (keras.ImageDataGenerator.flow_from_directory) –

pytorch_input_lib

PyTorch model parser.

@author: rbodo

snntoolbox.parsing.model_libs.pytorch_input_lib.to_numpy(tensor)

class snntoolbox.parsing.model_libs.pytorch_input_lib.ModelParser(input_model, config)

Bases: snntoolbox.parsing.model_libs.keras_input_lib.ModelParser

try_insert_flatten(layer, idx, name_map)

snntoolbox.parsing.model_libs.pytorch_input_lib.load(path, filename)

Load network from file.

Parameters:

• path (str) – Path to directory where to load model from.
• filename (str) – Name of file to load model from.

Returns:

A dictionary of objects that constitute the input model. It must contain the following two keys:

• ’model’: keras.models.Sequential

  Keras model instance of the network.

• ’val_fn’: function

  Function that allows evaluating the original model.

Return type:

dict[str, Union[keras.models.Sequential, function]]

snntoolbox.parsing.model_libs.pytorch_input_lib.evaluate(*args, **kwargs)

lasagne_input_lib

caffe_input_lib

snntoolbox.parsing.utils

Functions common to input model parsers.

The core of this module is an abstract base class extracts an input model written in some neural network library and prepares it for further processing in the SNN toolbox.

AbstractModelParser

Abstract base class for neural network model parsers.

The idea is to make all further steps in the conversion/simulation pipeline independent of the original model format.

Other functions help navigate through the network in order to explore network connectivity and layer attributes:

get_type	Get type of Keras layer.
has_weights	Return True if layer has weights.
get_fanin	Return fan-in of a neuron in layer.
get_fanout	Return fan-out of a neuron in layer.
get_inbound_layers	Return inbound layers.
get_inbound_layers_with_params	Iterate until inbound layers are found that have parameters.
get_inbound_layers_without_params	Return inbound layers.
get_outbound_layers	Return outbound layers.
get_outbound_activation	Iterate over 2 outbound layers to find an activation layer.

@author: rbodo

class snntoolbox.parsing.utils.AbstractModelParser(input_model, config)

Bases: object

Abstract base class for neural network model parsers.

Parameters:

• input_model – The input network object.
• config (configparser.Configparser) – Contains the toolbox configuration for a particular experiment.

input_model

The input network object.

Type:dict

config

Contains the toolbox configuration for a particular experiment.

Type:configparser.Configparser

_layer_list

A list where each entry is a dictionary containing layer specifications. Obtained by calling parse. Used to build new, parsed Keras model.

Type:list[dict]

_layer_dict

Maps the layer names of the specific input model library to our standard names (currently Keras).

Type:dict

parsed_model

The parsed model.

Type:keras.models.Model

parse()

Extract the essential information about a neural network.

This method serves to abstract the conversion process of a network from the language the input model was built in (e.g. Keras or Lasagne).

The methods iterates over all layers of the input model and writes the layer specifications and parameters into _layer_list. The keys are chosen in accordance with Keras layer attributes to facilitate instantiation of a new, parsed Keras model (done in a later step by build_parsed_model).

This function applies several simplifications and adaptations to prepare the model for conversion to spiking. These modifications include:

• Removing layers only used during training (Dropout, BatchNormalization, …)
• Absorbing the parameters of BatchNormalization layers into the parameters of the preceeding layer. This does not affect performance because batch-norm-parameters are constant at inference time.
• Removing ReLU activation layers, because their function is inherent to the spike generation mechanism. The information which nonlinearity was used in the original model is preserved in the activation key in _layer_list. If the output layer employs the softmax function, a spiking version is used when testing the SNN in INIsim or MegaSim simulators.
• Inserting a Flatten layer between Conv and FC layers, if the input model did not explicitly include one.

get_layer_iterable()

Get an iterable over the layers of the network.

Returns:layers Return type:list

get_type(layer)

Get layer class name.

Returns:layer_type – Layer class name. Return type:str

get_batchnorm_parameters(layer)

Get the parameters of a batch-normalization layer.

Returns:mean, var_eps_sqrt_inv, gamma, beta, axis Return type:tuple

get_inbound_layers_with_parameters(layer)

Iterate until inbound layers are found that have parameters.

Parameters:layer – Layer Returns:List of inbound layers. Return type:list

get_inbound_names(layer, name_map)

Get names of inbound layers.

Parameters:

• layer – Layer
• name_map (dict) – Maps the name of a layer to the id of the layer object.

Returns:

The names of inbound layers.

Return type:

list

get_inbound_layers(layer)

Get inbound layers of layer.

Returns:inbound Return type:Sequence

layers_to_skip

Return a list of layer names that should be skipped during conversion to a spiking network.

Returns:self._layers_to_skip Return type:List[str]

has_weights(layer)

Return True if layer has weights.

initialize_attributes(layer=None)

Return a dictionary that will be used to collect all attributes of a layer. This dictionary can then be used to instantiate a new parsed layer.

get_input_shape()

Get the input shape of a network, not including batch size.

Returns:input_shape – Input shape. Return type:tuple

get_batch_input_shape()

Get the input shape of a network, including batch size.

Returns:batch_input_shape – Batch input shape. Return type:tuple

get_name(layer, idx, layer_type=None)

Create a name for a layer.

The format is <layer_num><layer_type>_<layer_shape>.

>>> # Name of first convolution layer with 32 feature maps and
>>> # dimension 64x64:
"00Conv2D_32x64x64"
>>> # Name of final dense layer with 100 units:
"06Dense_100"

Parameters:

• layer – Layer.
• idx (int) – Layer index.
• layer_type (Optional[str]) – Type of layer.

Returns:

name – Layer name.

Return type:

str

format_layer_idx(idx)

Pad the layer index with the appropriate amount of zeros.

The number of zeros used for padding is determined by the maximum index (i.e. the number of layers in the network).

Parameters:idx (int) – Layer index. Returns:num_str – Zero-padded layer index. Return type:str

get_output_shape(layer)

Get output shape of a layer.

Parameters:layer – Layer. Returns:output_shape – Output shape of layer. Return type:Sized

try_insert_flatten(layer, idx, name_map)

parse_dense(layer, attributes)

Parse a fully-connected layer.

Parameters:

• layer – Layer.
• attributes (dict) – The layer attributes as key-value pairs in a dict.

parse_convolution(layer, attributes)

Parse a convolutional layer.

Parameters:

• layer – Layer.
• attributes (dict) – The layer attributes as key-value pairs in a dict.

parse_depthwiseconvolution(layer, attributes)

Parse a depthwise convolution layer.

Parameters:

• layer – Layer.
• attributes (dict) – The layer attributes as key-value pairs in a dict.

parse_sparse(layer, attributes)

parse_sparse_convolution(layer, attributes)

parse_sparse_depthwiseconvolution(layer, attributes)

parse_pooling(layer, attributes)

Parse a pooling layer.

Parameters:

• layer – Layer.
• attributes (dict) – The layer attributes as key-value pairs in a dict.

absorb_activation(layer, attributes)

Detect what activation is used by the layer.

Sometimes the Dense or Conv layer specifies its activation directly, sometimes it is followed by a dedicated Activation layer (possibly with BatchNormalization in between). Here we try to find such an activation layer, and add this information to the Dense/Conv layer itself. The separate Activation layer can then be removed.

Parameters:

• layer – Layer.
• attributes (dict) – The layer attributes as key-value pairs in a dict.

get_activation(layer)

Get the activation string of an activation layer.

Parameters:layer – Layer Returns:activation – String indicating the activation of the layer. Return type:str

get_outbound_layers(layer)

Get outbound layers of layer.

Parameters:layer – Layer. Returns:outbound – Outbound layers of layer. Return type:list

parse_concatenate(layer, attributes)

Parse a concatenation layer.

Parameters:

• layer – Layer.
• attributes (dict) – The layer attributes as key-value pairs in a dict.

build_parsed_model()

Create a Keras model suitable for conversion to SNN.

This method uses the specifications in _layer_list to build a Keras model. The resulting model contains all essential information about the original network, independently of the model library in which the original network was built (e.g. Caffe).

Returns:parsed_model – A Keras model, functionally equivalent to input_model. Return type:keras.models.Model

evaluate(batch_size, num_to_test, x_test=None, y_test=None, dataflow=None)

Evaluate parsed Keras model.

Can use either numpy arrays x_test, y_test containing the test samples, or generate them with a dataflow (keras.ImageDataGenerator.flow_from_directory object).

Parameters:

• batch_size (int) – Batch size
• num_to_test (int) – Number of samples to test
• x_test (Optional[np.ndarray]) –
• y_test (Optional[np.ndarray]) –
• dataflow (keras.ImageDataGenerator.flow_from_directory) –

snntoolbox.parsing.utils.absorb_bn_parameters(weight, bias, mean, var_eps_sqrt_inv, gamma, beta, axis, image_data_format, is_depthwise=False)

Absorb the parameters of a batch-normalization layer into the previous layer.

snntoolbox.parsing.utils.modify_parameter_precision(weights, biases, config, attributes)

snntoolbox.parsing.utils.padding_string(pad, pool_size)

Get string defining the border mode.

Parameters:

• pad (tuple[int]) – Zero-padding in x- and y-direction.
• pool_size (list[int]) – Size of kernel.

Returns:

padding – Border mode identifier.

Return type:

str

snntoolbox.parsing.utils.load_parameters(filepath)

Load all layer parameters from an HDF5 file.

snntoolbox.parsing.utils.save_parameters(params, filepath, fileformat='h5')

Save all layer parameters to an HDF5 file.

snntoolbox.parsing.utils.has_weights(layer)

Return True if layer has weights.

Parameters:layer (keras.layers.Layer) – Keras layer Returns:True if layer has weights. Return type:bool

snntoolbox.parsing.utils.get_inbound_layers_with_params(layer)

Iterate until inbound layers are found that have parameters.

Parameters:layer (keras.layers.Layer) – Layer Returns:List of inbound layers. Return type:list

snntoolbox.parsing.utils.get_inbound_layers_without_params(layer)

Return inbound layers.

Parameters:layer (Keras.layers) – A Keras layer. Returns:List of inbound layers. Return type:list[Keras.layers]

snntoolbox.parsing.utils.get_inbound_layers(layer)

Return inbound layers.

Parameters:layer (Keras.layers) – A Keras layer. Returns:List of inbound layers. Return type:list[Keras.layers]

snntoolbox.parsing.utils.get_outbound_layers(layer)

Return outbound layers.

Parameters:layer (Keras.layers) – A Keras layer. Returns:List of outbound layers. Return type:list[Keras.layers]

snntoolbox.parsing.utils.get_outbound_activation(layer)

Iterate over 2 outbound layers to find an activation layer. If there is no activation layer, take the activation of the current layer.

Parameters:layer (Union[keras.layers.Conv2D, keras.layers.Dense]) – Layer Returns:activation – Name of outbound activation type. Return type:str

snntoolbox.parsing.utils.get_fanin(layer)

Return fan-in of a neuron in layer.

Parameters:layer (Subclass[keras.layers.Layer]) – Layer. Returns:fanin – Fan-in. Return type:int

snntoolbox.parsing.utils.get_fanout(layer, config)

Return fan-out of a neuron in layer.

Parameters:

• layer (Subclass[keras.layers.Layer]) – Layer.
• config (configparser.ConfigParser) – Settings.

Returns:

fanout – Fan-out. The fan-out of a neuron projecting onto a convolution layer varies between neurons in a feature map if the stride of the convolution layer is greater than unity. In this case, return an array of the same shape as the layer.

Return type:

Union[int, ndarray]

snntoolbox.parsing.utils.has_stride_unity(layer)

Return True if the strides in all dimensions of a layer are 1.

snntoolbox.parsing.utils.get_fanout_array(layer_pre, layer_post, is_depthwise_conv=False)

Return an array of the same shape as layer_pre, where each entry gives the number of outgoing connections of a neuron. In convolution layers where the post-synaptic layer has stride > 1, the fan-out varies between neurons.

snntoolbox.parsing.utils.get_type(layer)

Get type of Keras layer.

Parameters:layer (Keras.layers.Layer) – Keras layer. Returns:Layer type. Return type:str

snntoolbox.parsing.utils.get_quantized_activation_function_from_string(activation_str)

Parse a string describing the activation of a layer, and return the corresponding activation function.

Parameters:activation_str (str) – Describes activation. Returns:activation – Activation function. Return type:functools.partial

Examples

>>> f = get_quantized_activation_function_from_string('relu_Q1.15')
>>> f
functools.partial(<function reduce_precision at 0x7f919af92b70>,
                  f='15', m='1')
>>> print(f.__name__)
relu_Q1.15

snntoolbox.parsing.utils.get_clamped_relu_from_string(activation_str)

snntoolbox.parsing.utils.get_noisy_softplus_from_string(activation_str)

snntoolbox.parsing.utils.get_custom_activation(activation_str)

If activation_str describes a custom activation function, import this function from snntoolbox.utils.utils and return it. If custom activation function is not found or implemented, return the activation_str in place of the activation function.

Parameters:activation_str (str) – Describes activation. Returns:

• activation – Activation function.
• activation_str (str) – Describes activation.

snntoolbox.parsing.utils.assemble_custom_dict(*args)

snntoolbox.parsing.utils.get_custom_layers_dict(filepath=None)

Import all implemented custom layers so they can be used when loading a Keras model.

Parameters:filepath (Optional[str]) – Path to json file containing additional custom objects.

snntoolbox.parsing.utils.get_custom_activations_dict(filepath=None)

Import all implemented custom activation functions so they can be used when loading a Keras model.

Parameters:filepath (Optional[str]) – Path to json file containing additional custom objects.

snntoolbox.parsing.utils.check_for_custom_activations(layer_attributes)

Check if the layer contains a custom activation function, and deal with it appropriately.

Parameters:layer_attributes (dict) – A dictionary containing the attributes of the layer.

snntoolbox.parsing.utils.precision(y_true, y_pred)

Precision metric.

Computes the precision, a metric for multi-label classification of how many selected items are relevant. Only computes a batch-wise average of precision.

snntoolbox.parsing.utils.fix_input_layer_shape(shape)

tf.keras.models.load_model function introduced a bug that wraps the input tensors and shapes in a single-entry list, i.e. output_shape == [(None, 1, 28, 28)]. Thus we have to apply [0] here.