NeuroRBM

A modular PyTorch-based framework for training Restricted Boltzmann Machines (RBMs) with lateral inhibition in the form of cardinality restriction in the hidden layer and defending neural networks against adversarial attacks using generative reconstruction.

Structure

The code is structured in three files contained in \src:

• NeuroRBM.py which contains the definition of the launchable functions and the argument parsing logic
• models.py which contains the class definition used to build a custom RBM
• utils.py which contains all utility functions for saving and plotting results, as well as loading training evaluating and saving CNNs and creating adversarial examples and datasets for a given CNN.

Functions

When running NeuroRBM from a terminal, three functions can be called :

• train() : to train a RBM model from given parameters and dataset, with the possibility to add lateral inhibition

• test_adversarial() : to test the impact of a given RBM's reconstruction as pre-processing on normal and adversarial images. Will create and train a CNN and generate an adversarial dataset that can be saved and re-used when the function is used in the future.

• display_reconstructed() : to display a selected image from a dataset, its adversarial version and the RBM's reconstruction, along with CNN classification labels and confidence values.

These functions, how to launch them and their associated parameters are explained in the following section.

Train

python src/NeuroRBM.py --mode train <args>

Arguments

---

--layers

• Type: int array
• Description: Layer sizes for the RBM: <n_visible> <n_hidden>
• Default: [784, 200]
• Example:

  --layers 784 500

---

--min_w

• Type: float
• Description: Minimal value a weight can take
• Default: -1

---

--max_w

• Type: float
• Description: Maximal value a weight can take
• Default: 1

---

--init

• Type: string
• Description: Method used to initialize weights
• Possible values: ['glorot', 'glorot_normal']
• Behavior:
  Weights are sampled either from a uniform or normal distribution with Glorot amplitude:

Uniform: 𝕌(−√(6 / (nₕ + nᵥ)), √(6 / (nₕ + nᵥ)))

Normal: ℕ(−√(6 / (nₕ + nᵥ)), √(6 / (nₕ + nᵥ)))

where:

• nᵥ is the number of neurons in the visible layer

• nₕ is the number of neurons in the hidden layer

• Default: 'glorot' (uniform)

---

--epochs

• Type: int
• Description: Number of epochs to train the RBM
• Default: 10

---

--epoch_size

• Type: int
• Description: Number of training examples per epoch
• Default: 60000

---

--output_dir

• Type: string
• Description: Directory to save output files, including weights and activity logs
• Default: 'test'

---

--lr

• Type: float
• Description: Learning rate for the RBM training
• Default: 0.005

---

--process_std

• Type: float
• Description: Standard deviation for process noise in weight values
• Default: 0.0

---

--train_from_weights

• Type: flag : store True
• Description: If set, the RBM will be initialized from the weights specified in weight_file_path. Otherwise, it will be trained from scratch

---

--weight_file_path

• Type: string/None
• Description: Path to load existing weights from a file. If provided, the RBM will be initialized with these weights
• Default: None

---

--lateral_inhib

• Type: flag : store True
• Description: Enable lateral inhibition in the RBM. If set, the RBM will apply lateral inhibition with the parameter max_inhib during training and reconstruction

---

--max_inhib

• Type: int/int array
• Description: Maximum number of hidden neurons to inhibit during training. If not provided, no inhibition is applied. Can be a single value or a list of values for different runs. If a list is given, the whole training will be applied for each value one after the other
• Default: None

---

--dataset

• Type: string
• Description: Dataset to use for training and testing. For now, only MNIST and fashion-mnist are supported
• Possible values: ['mnist', 'fashion-mnist']
• Default: 'mnist'

---

--animate

• Type: flag : store True
• Description: If set, the training process will save a GIF of the weight evolution. Requires 'PIL' library

Weight evolution animation of a 784, 200 RBM on 50 epochs of full mnist (60000 images) with lateral inhibition : max_inhib=40 :

---

--record_activity

• Type: flag : store True
• Description: Record average hidden neuron activations per class during training, saves in hidden_activations_per_epoch.npy in output_dir

---

--monitor_adversarial

• Type: flag : store True
• Description: Monitor adversarial accuracy during training and save the results in a file and a accuracy vs epoch graph in output_dir

Example of the accuracy of a 784, 200 RBM after 50 epochs of full mnist (60000 images) with lateral inhibition : max_inhib=40 :

---

--load_model_from_disk

• Type: flag : store True
• Description: Load CNN model from cnn_model_path for adversarial testing if monitor_adversarial is activated

---

--load_adversarial

• Type: flag : store True
• Description: Load adversarial examples from adversarial_examples_path for testing if monitor_adversarial is activated

---

--cnn_model_path

• Type: string
• Description: Path to save or load the CNN model for adversarial testing
• Default: 'cnn_model.pth'

---

--adversarial_examples_path

• Type: string
• Description: Path to load adversarial examples from
• Default: None

---

--method

• Type: string
• Description: Method for generating adversarial examples.
• Possible values: ['fgsm', 'iterative']
• Default: 'iterative'

Weight heatmap of a 784, 200 RBM on 50 epochs of full mnist (60000 images) with lateral inhibition : max_inhib=40 :

---

Test adversarial

python src/NeuroRBM.py --mode test_adversarial <args>

Only requires a subset of train()'s arguments : --weight_file_path --cnn_model_path --dataset --lateral_inhib --max_inhib --load_model_from_disk --load_adversarial --adversarial_examples_path --method

---

Display reconstructed

python src/NeuroRBM.py --mode display_reconstructed <args>

Requires the same arguments as test_adversarial(), and additionally an argument to choose the index of the reconstructed image so reconstruction can be visualised from different models on the same image

---

--index

• Type: int
• Description: Index of the image to display
• Default: None

Reconstruction of a 3 from a 784, 200 RBM on 50 epochs of full mnist (60000 images) with lateral inhibition : max_inhib=40 :

Reconstruction of a shoe from a 784, 200 RBM on 50 epochs of full fashion-mnist (60000 images) with lateral inhibition : max_inhib=50 :