nsp package

Module contents

nsp is a Python package for extracting and visualizing activation patterns of PyTorch neural networks. It can - extract the computational graph of a neural network as a directed graph. - extract the activation pattern generated by an input of a neural network. - compute the Fourier transform of an activation pattern (signal) in a neural network (directed graph) based on [1] and [2]. - visualize activation patterns and their Fourier coefficients.

nsp.activations module

class nsp.activations.Activations(network, input)

Bases: object

Holds the activation pattern generated in a neural network.

Parameters

network (torch.nn.Module) – PyTorch neural network.
input (torch.tensor) – A valid single input to the network. For later computations make sure to pass a single input, i.e. batch_size = 1.

Variables

layernames (list of str) – Names of the children modules, i.e. layer names, of the network.
layerdescriptions (list of torch.nn) – Children modules, i.e. layer types and specifications, of the network.
layeractivations (list of torch.tensor) – Activations of every child module, i.e. values of the activation pattern.

to_activations(signal)

Create object like self but with layeractivations from values in signal.

Parameters: signal (list, ndarray) – layeractivations, i.e. activation pattern, as vector.
Returns
Return type: Activations

to_vector()

Get and reshape layeractivations into a vector.

Returns
Return type: list

nsp.nngraph module

class nsp.nngraph.NNGraph(activations, INCL=True)

Bases: networkx.classes.digraph.DiGraph

Directed graph representing in the computational graph structure of a Pytorch neural network.

Parameters

activations (Activations) – Any sample activation pattern generated by the network under observation. The resulting NNGraph is independent of the activation values contained in the specific activation pattern, i.e. activation.layeractivations.
INCL (boolean, default True) – If True, it includes edges in the NNGraph even if the weight of the edge in the neural network is 0. If False, only edges with weight unequal to 0 are added to the graph. Especially, INCL = False will only have one incoming edge per activation in a torch.nn.MaxPool layer.

Variables

inv_F (scipy.sparse.tril(A, format='csr'), default None) – Inverse Fourier Transform matrix w.r.t. https://acl.inf.ethz.ch/research/ASP/. Is None until the first invocation of NNGraph.transform(activations, type=’standard’) or can be explicitly assigned by calling NNGraph.compute_transformer(type=’standard’).
lu_piv (numpy.ndarray, numpy.ndarray) – LU-decomposition of the inverse Fourier Transform matrix w.r.t. https://arxiv.org/pdf/1211.0053.pdf. Is None until the first invocation of NNGraph.transform(activations, type=’laplacian’) or can be explicitly assigned by calling NNGraph.compute_transformer(type=’laplacian’).

get_transformer(type='standard')

Compute the inverse Fourier transformations for the graph.

Parameters

type ({‘standard’, ‘laplacian’}, default ‘standard’) –

‘standard’computes the inverse Fourier Transform matrix w.r.t.
https://acl.inf.ethz.ch/research/ASP/ and puts it in self.inv_F.
‘laplacian’computes the LU-Decomposition of the inverse Fourier Transform matrix w.r.t.
https://arxiv.org/pdf/1211.0053.pdf and puts it in self.lu_piv.

Returns

scipy.sparse.tril(A, format=’csr’) – if type=’standard’.
numpy.ndarray, numpy.ndarray – if type=’laplacian’.

node_id(node)

Get the index of a node in the total order of all nodes.

Returns
Return type: int

transform(activations, type='standard')

Compute the Fourier coefficients, or spectrum, of Activations.

It creates a copy of activations with the Fourier coefficients activations.layeractivations.

Parameters

activations (Activation) – Activation to transfrom.
type ({‘standard’, ‘laplacian’}, default ‘standard’) –
- ‘standard’computes the inverse Fourier Transform matrix w.r.t.
  https://acl.inf.ethz.ch/research/ASP/ and puts it in self.inv_F.
- ‘laplacian’computes the LU-Decomposition of the inverse Fourier Transform matrix w.r.t.
  https://arxiv.org/pdf/1211.0053.pdf and puts it in self.lu_piv

Returns

Return type

Activations

nsp.outputLoader module

class nsp.outputLoader.OutputLoader

Bases: object

Store and load intermediate results. Especially useful for storing NNGraph and their transformers

inv_F or lu_piv since their computations take long and they can be used to transform multiple Activations.

load()

Load python object like NNGrpah or Activation.

Parameters: path (str) – Path to location of the object.
Returns
Return type: The object stored at path.

save(path)

Store python object like NNGrpah or Activations.

Parameters

obj (NNGraph, Activation) – Object to save.
path (str) – Path to desired location of obj.

Returns

Return type

None

nsp.transformer module

class nsp.transformer.Transformer

Bases: object

get_fourier_coefficients(inv_F=None, type='standard', lu_piv=None)

Compute the Fourier coefficients, or spectrum, of Activations.

It creates a copy of activations with the Fourier coefficients activations.layeractivations.

Parameters

activations (Activation) – Activation to transfrom.
type ({‘standard’, ‘laplacian’}, default ‘standard’) –
- ‘standard’computes the inverse Fourier Transform matrix w.r.t.
  https://acl.inf.ethz.ch/research/ASP/ and puts it in self.inv_F.
- ‘laplacian’computes the LU-Decomposition of the inverse Fourier Transform matrix w.r.t.
  https://arxiv.org/pdf/1211.0053.pdf and puts it in self.lu_piv
inv_F (scipy.sparse) – Inverse Fourier transform matrix. Required if type=’standard’.
lu_piv (numpy.ndarray, numpy.ndarray) – LU-decomposition of the Inverse Fourier transform matrix. Required if type=’laplacian’.

Returns

Return type

Activations

get_fourier_matrix(inv_F)

Compute the Fourier transform matrix of a graph.

Parameters

graph (NNGraph) – Directed Graph.
inv_F (scipy.sparse) – Inverse Fourier transform matrix.

Returns

Return type

numpy.ndarray

get_inv_fourier_matrix(type='standard')

Compute the inverse Fourier transform matrices of a graph.

Parameters

graph (NNGraph) – Directed Graph.
type ({‘standard’, ‘laplacian’}, default ‘standard’) –
- ‘standard’computes the inverse Fourier Transform matrix w.r.t.
  https://acl.inf.ethz.ch/research/ASP/.
- ‘laplacian’computes the LU-Decomposition of the inverse Fourier Transform matrix w.r.t.
  https://arxiv.org/pdf/1211.0053.pdf.

Returns

scipy.sparse.tril(A, format=’csr’) – if type=’standard’.
numpy.ndarray, numpy.ndarray – if type=’laplacian’.

get_laplacian()

Compute the laplacian matrix of a graph.

Parameters: graph (NNGraph) – Directed Graph.
Returns
Return type: numpy.ndarray

nsp.visualizer module

class nsp.visualizer.Visualizer

Bases: object

Plot the generated data.

visualize_pattern(pdf_filepath, scale='layerscale', cmap_style='viridis')

Visualize an activation pattern.

Layers are visualized on seperate pages. Channels are visualized as seperately on one page.

Parameters

activations (Activations) – Activations to visualize.
pdf_filepath (str) – Pdf path to store the visualization.
scale ({‘layerscale’, ‘layernorm’, ‘globalscale’, ‘globalnorm’}, default ‘layerscale’) –
Scaling of the colomap.
- ‘layerscale’ : provides one color scale per activation layer.
- ‘layernorm’provides one color scale per activation layer
  and sets the center of the scale to 0.
- ‘globalscale’ : provides one color scale per activation pattern.
- ‘globalnorm’provides one color scale per activation pattern
  and sets the center of the scale to 0.
The options ‘layernorm’ and ‘globalnorm’ are particularly useful for diverging colormap styles.
cmap_style (str, default ‘viridis’) – Pick a cmap_style from the matplotlib colormaps (https://matplotlib.org/stable/tutorials/colors/colormaps.html).

Returns

Return type

None