Hopfield_network.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "6dbb806c",
   "metadata": {},
   "source": [
    "<img src=\"https://avatars.githubusercontent.com/u/61354833\" align=\"left\" width=\"70\" height=\"70\">\n",
    "\n",
    "Code by [TomMakesThings](https://github.com/TomMakesThings/Genome-Sequence-Analysis-HMM)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1b077ac4",
   "metadata": {},
   "source": [
    "# **About**\n",
    "A Hopfield network is a type of neural network commonly used for pattern recognition in which all nodes are fully connected. In this notebook, the Hopfield net is evaluated based on its capacity to recall patterns using either the Hebbian or Storkey learning rules. See the corresponding <a href=\"https://github.com/TomMakesThings/Hopfield-Network\">GitHub repository here</a>."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9656cb50",
   "metadata": {},
   "source": [
    "![Hopfield_Network.png](data:image/png;base64,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)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "18156745",
   "metadata": {},
   "source": [
    "# Imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 60,
   "id": "b5f631cf",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import random\n",
    "import math\n",
    "import statistics\n",
    "from matplotlib import pyplot as plt\n",
    "\n",
    "# Seed for reproducability\n",
    "random.seed(10)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b5c2c702",
   "metadata": {},
   "source": [
    "# Pattern Creation\n",
    "The functions below are for creating and visualising the patterns for the network to learn:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "d4a3d65e",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Allows binary patterns to be visualised as a grid\n",
    "def plotPatterns(patterns, num_row, num_col, new_shape = None,\n",
    "                 subplot_titles = None, file = None):\n",
    "    \n",
    "    if (isinstance(new_shape, tuple)):\n",
    "        patterns = [patterns[i].reshape(new_shape) for i in range(len(patterns))]\n",
    "    \n",
    "    # Create empty subplots\n",
    "    fig, axes = plt.subplots(num_row, num_col, figsize = (1.5 * num_col, 2 * num_row))\n",
    "\n",
    "    for i in range(len(patterns)):\n",
    "        \n",
    "        if (num_row == 1):\n",
    "            if (num_col == 1):\n",
    "                ax = axes\n",
    "            else:\n",
    "                ax = axes[i]\n",
    "        else:\n",
    "            ax = axes[i // num_col, i % num_col]\n",
    "            \n",
    "        # Check if stored in a dictionary\n",
    "        if (isinstance(patterns, dict)):\n",
    "            # Get the identifier from the dictionary\n",
    "            key = list(patterns.keys())[i]\n",
    "            \n",
    "            # Plot the pattern\n",
    "            ax.imshow(patterns[key], cmap = 'gray')\n",
    "            ax.set_title(key)\n",
    "        # Assume in array\n",
    "        else:\n",
    "            ax.imshow(patterns[i], cmap = 'gray')\n",
    "            \n",
    "            if not isinstance(subplot_titles, type(None)):\n",
    "                ax.set_title(subplot_titles[i])\n",
    "\n",
    "    # Hide x and y axis labels\n",
    "    try:\n",
    "        for ax in axes.flatten():\n",
    "            ax.get_xaxis().set_visible(False)\n",
    "            ax.get_yaxis().set_visible(False)\n",
    "    except:\n",
    "        axes.get_xaxis().set_visible(False)\n",
    "        axes.get_yaxis().set_visible(False)\n",
    "        \n",
    "    if not isinstance(file, type(None)):\n",
    "        # Save the figure\n",
    "        plt.savefig(file, bbox_inches = 'tight')\n",
    "        \n",
    "    # Display the plot\n",
    "    plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 98,
   "id": "305061f3",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Convert from dictionary to form suitable for training Hopfield network\n",
    "def convertPatterns(patterns):\n",
    "    # Flattern matricies to 1D and convert to array\n",
    "    patterns = [np.array(patterns[i].flatten())[0] for i in patterns.keys()]\n",
    "    \n",
    "    for i in range(len(patterns)):\n",
    "        # Change 0s to -1s\n",
    "        patterns[i][patterns[i] == 0] = -1\n",
    "        \n",
    "    return(patterns)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 99,
   "id": "1eafff2b",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Adds random noise to a pattern\n",
    "def addNoise(patterns, noise_threshold = 1):\n",
    "    noisy_patterns = np.copy(patterns)\n",
    "\n",
    "    for i in range(len(noisy_patterns)):\n",
    "        # Generate random noise from a normal distribution\n",
    "        noise_locations = np.array([np.random.normal(0) > noise_threshold for j in range(len(noisy_patterns[0]))])\n",
    "\n",
    "        for k in range(len(noise_locations)):\n",
    "            # Check if to add noise\n",
    "            if noise_locations[k] == True:\n",
    "                # Add noise by flipping bits\n",
    "                noisy_patterns[i][k] = 1 if (noisy_patterns[0][k] == -1) else -1\n",
    "                \n",
    "    return(noisy_patterns)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 100,
   "id": "7e2566df",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Corrupts a pattern by keeping only the upper part\n",
    "def hiddenPatterns(patterns, pattern_shape = (5,4), remaining = [2,2]):\n",
    "    # Record each new pattern\n",
    "    hidden_patterns = []\n",
    "\n",
    "    for i in range(len(patterns)):\n",
    "        # Reshape as a matrix\n",
    "        pattern = np.reshape(patterns[i], pattern_shape)\n",
    "        # Get the part to keep\n",
    "        remaining_part = pattern[:remaining[0], :remaining[1]]\n",
    "        # Create a blank pattern and add the conserved part\n",
    "        hidden_pattern = np.ones_like(pattern)\n",
    "        hidden_pattern[:remaining[0], :remaining[1]] = remaining_part\n",
    "        # Reshape to 1D\n",
    "        hidden_pattern = hidden_pattern.flatten()\n",
    "        # Record the updated pattern\n",
    "        hidden_patterns.append(hidden_pattern)\n",
    "                \n",
    "    return(hidden_patterns)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3bcb065a",
   "metadata": {},
   "source": [
    "## Letter Patterns\n",
    "The first training set consists of 4 × 5 binary patterns depicting the first eight letters of the alphabet.\n",
    "Each pattern is flattened to one dimension giving a pattern size of 20. For testing, two types of corrupt patterns were derived for each letter by:\n",
    "* Adding random noise\n",
    "* Masking the lower half of the pattern"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 101,
   "id": "e02943c7",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 864x432 with 24 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Create letter patterns\n",
    "letter_matrices = {'A' : np.matrix([[0,1,1,0],[1,0,0,1],[1,1,1,1],[1,0,0,1],[1,0,0,1]]),\n",
    "                   'B' : np.matrix([[1,1,1,0],[1,0,0,1],[1,1,1,0],[1,0,0,1],[1,1,1,0]]),\n",
    "                   'C' : np.matrix([[1,1,1,0],[1,0,0,0],[1,0,0,0],[1,0,0,0],[1,1,1,0]]),\n",
    "                   'D' : np.matrix([[1,1,1,0],[1,0,0,1],[1,0,0,1],[1,0,0,1],[1,1,1,0]]),\n",
    "                   'E' : np.matrix([[1,1,1,0],[1,0,0,0],[1,1,1,0],[1,0,0,0],[1,1,1,0]]),\n",
    "                   'F' : np.matrix([[1,1,1,0],[1,0,0,0],[1,1,1,0],[1,0,0,0],[1,0,0,0]]),\n",
    "                   'G' : np.matrix([[1,1,1,0],[1,0,0,0],[1,0,1,1],[1,0,0,1],[1,1,1,1]]),\n",
    "                   'H' : np.matrix([[1,0,0,1],[1,0,0,1],[1,1,1,1],[1,0,0,1],[1,0,0,1]])}\n",
    "\n",
    "# Convert from dictionary of matrices to array suitable for Hopfield network training\n",
    "letter_patterns = convertPatterns(letter_matrices)\n",
    "# Distort letters by adding noise\n",
    "noisy_letter_patterns = addNoise(letter_patterns, noise_threshold = 1.1)\n",
    "# Hide part of the letters\n",
    "hidden_letter_patterns = hiddenPatterns(letter_patterns, remaining = [3,5])\n",
    "\n",
    "# Plot the corrupted patterns\n",
    "noisy_plot_data = dict(zip(letter_matrices.keys(),\n",
    "                           [noisy_letter_patterns[i].reshape(5,4) for i in range(len(noisy_letter_patterns))]))\n",
    "hidden_plot_data = dict(zip(letter_matrices.keys(),\n",
    "                            [hidden_letter_patterns[i].reshape(5,4)for i in range(len(hidden_letter_patterns))]))\n",
    "\n",
    "# View the letters\n",
    "plotPatterns(list(letter_matrices.values()) + list(noisy_plot_data.values()) + list(hidden_plot_data.values()),\n",
    "             num_row = 3, num_col = len(letter_matrices),\n",
    "             subplot_titles = list(letter_matrices.keys()) + [\"\" for i in range(len(letter_matrices) * 2)],\n",
    "             file = \"Hopfield/letters.pdf\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "03ad6af8",
   "metadata": {},
   "source": [
    "## Shape Patterns\n",
    "The second training set consists of 10 larger 10 × 10 patterns."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "id": "9481fd20",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 1080x144 with 10 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 1080x144 with 10 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 1080x144 with 10 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Binary pattern dimensions\n",
    "pattern_size = (10, 10)\n",
    "\n",
    "# Calculate number of pixels based on pattern dimensions\n",
    "n_pixels = 1\n",
    "for i in pattern_size:\n",
    "    n_pixels *= i\n",
    "n_pixels\n",
    "\n",
    "# Create pattern of all -1\n",
    "binary_patterns = (np.ones(pattern_size) * -1).flatten()\n",
    "\n",
    "# Pattern of half 1, half -1\n",
    "half_pattern = np.ones(n_pixels).reshape(pattern_size)\n",
    "half_pattern[:pattern_size[0] // 2] = -1\n",
    "binary_patterns = np.vstack((binary_patterns, half_pattern.flatten()))\n",
    "\n",
    "# Pattern of three quarters 1s\n",
    "quarter_pattern = np.ones(n_pixels).reshape(pattern_size)\n",
    "quarter_pattern[:pattern_size[0] // 4] = -1\n",
    "binary_patterns = np.vstack((binary_patterns, quarter_pattern.flatten()))\n",
    "\n",
    "# Pattern of -1 and 1 every other pixel\n",
    "checkboard_pattern = np.indices(pattern_size).sum(axis = 0) % 2\n",
    "for i in range(len(checkboard_pattern)):\n",
    "    # Change 0s to -1s\n",
    "    checkboard_pattern[i][checkboard_pattern[i] == 0] = -1\n",
    "binary_patterns = np.vstack((binary_patterns, checkboard_pattern.flatten()))\n",
    "\n",
    "# Pattern of edge 1 and middle -1\n",
    "edge_ones = np.ones(pattern_size, dtype = int)\n",
    "edge_ones[1:-1,1:-1] = -1\n",
    "binary_patterns = np.vstack((binary_patterns, edge_ones.flatten()))\n",
    "\n",
    "# X shape of -1\n",
    "cross_pattern = np.ones(pattern_size)\n",
    "np.fill_diagonal(cross_pattern, val = -1)\n",
    "np.fill_diagonal(np.fliplr(cross_pattern), val = -1)\n",
    "binary_patterns = np.vstack((binary_patterns, cross_pattern.flatten()))\n",
    "\n",
    "# Create random patterns with different ratios of -1 and 1\n",
    "pattern_probabilities = [[0.1, 0.9],\n",
    "                         [0.3, 0.7],\n",
    "                         [0.5, 0.5],\n",
    "                         [0.7, 0.3]]\n",
    "\n",
    "random_patterns = np.array([])\n",
    "n_random = len(pattern_probabilities)\n",
    "\n",
    "while len(random_patterns) < n_random:\n",
    "    # Create a new randomly generated pattern\n",
    "    new_random = np.array([np.random.choice([-1, 1], p = pattern_probabilities[len(random_patterns)])\n",
    "                           for i in range(n_pixels)])\n",
    "    # Check the pattern hasn't been generated already\n",
    "    if not any([all(p == new_random) for p in random_patterns]):\n",
    "        # Check if this is the first random pattern\n",
    "        if len(random_patterns) == 0:\n",
    "            random_patterns = np.array([new_random])\n",
    "        else:\n",
    "            # Record it\n",
    "            random_patterns = np.vstack((random_patterns, new_random))\n",
    "            \n",
    "binary_patterns = np.vstack((binary_patterns, random_patterns))\n",
    "            \n",
    "# Visualise the randomly generated patterns\n",
    "plotPatterns(binary_patterns, new_shape = pattern_size,\n",
    "             num_row = 1, num_col = math.ceil(len(binary_patterns)/1),\n",
    "             subplot_titles = range(0, len(binary_patterns)),\n",
    "             file = \"Hopfield/binary_patterns.pdf\")\n",
    "\n",
    "noisy_binary_patterns = addNoise(binary_patterns, noise_threshold = 1.1)\n",
    "\n",
    "hidden_binary_patterns = hiddenPatterns(binary_patterns,\n",
    "                                        pattern_shape = pattern_size,\n",
    "                                        remaining = [pattern_size[0],\n",
    "                                                     pattern_size[0] // 2])\n",
    "\n",
    "plotPatterns(noisy_binary_patterns, new_shape = pattern_size,\n",
    "             num_row = 1, num_col = math.ceil(len(noisy_binary_patterns)/1),\n",
    "             subplot_titles = range(0, len(noisy_binary_patterns)),\n",
    "             file = \"Hopfield/noisy_binary_patterns.pdf\")\n",
    "\n",
    "plotPatterns(hidden_binary_patterns, new_shape = pattern_size,\n",
    "             num_row = 1, num_col = math.ceil(len(hidden_binary_patterns)/1),\n",
    "             subplot_titles = range(0, len(hidden_binary_patterns)),\n",
    "             file = \"Hopfield/hidden_binary_patterns.pdf\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "92f8cb4f",
   "metadata": {},
   "source": [
    "# Hopfield Network"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 102,
   "id": "54aa11c4",
   "metadata": {},
   "outputs": [],
   "source": [
    "class Hopfield:\n",
    "    \"\"\"\n",
    "    Create a trainable Hopfield network\n",
    "    \n",
    "    inputs:\n",
    "        patterns: array of binary patterns for the network to learn\n",
    "        learning_rule: set weights using either \"hebbian\" or \"storkey\" learning\n",
    "        unit_thresholds: decision thresholds for the state of the neurons\n",
    "        dropout_rate: percentage of weight dropout\n",
    "    \"\"\"\n",
    "    \n",
    "    def __init__(self, patterns, learning_rule = \"hebbian\", unit_thresholds = None, dropout_rate = 0):\n",
    "        self.patterns = patterns\n",
    "        self.learning_rule = learning_rule\n",
    "        # Determine number of neurons\n",
    "        self.N = len(self.patterns[0])\n",
    "        \n",
    "        # Set threshold theta\n",
    "        if isinstance(unit_thresholds, type(None)):\n",
    "            # Set as zero if none provided\n",
    "            self.unit_thresholds = np.zeros(self.N)\n",
    "        else:\n",
    "            self.unit_thresholds = unit_thresholds\n",
    "        \n",
    "        # Set percentage of weight dropout\n",
    "        self.dropout_rate = dropout_rate\n",
    "        # Set the network weights\n",
    "        self.weight_matrix = self.setWeights()\n",
    "        \n",
    "    def setWeights(self):\n",
    "        # Create empty weight matrix\n",
    "        weight_matrix = np.zeros((self.N, self.N))\n",
    "        # Set upper-triangle as nan as weigths are symmetric\n",
    "        weight_matrix[np.triu_indices(self.N)] = None\n",
    "        # Set diagonal weights to zero\n",
    "        np.fill_diagonal(weight_matrix, 0)\n",
    "        \n",
    "        # Set weights with Hebbian learning rule\n",
    "        if self.learning_rule.lower()[0] == \"h\":\n",
    "            for i in range(self.N):\n",
    "                # Set only lower half of matrix to prevent redundancy\n",
    "                for j in range((i - self.N) % self.N):\n",
    "                    # Prevent recurrent connection back to same neuron\n",
    "                    if i != j:\n",
    "                        # Add the product between components i and j in each pattern\n",
    "                        pattern_sum = 0\n",
    "                        # Iterate through each pattern mu\n",
    "                        for mu in range(len(self.patterns)):\n",
    "                            pattern_sum += self.patterns[mu][i] * self.patterns[mu][j]\n",
    "                        # Set weight i to j in matrix\n",
    "                        weight_matrix[i][j] = (1/self.N) * pattern_sum\n",
    "                        \n",
    "        # Set weights via Storkey learning rule\n",
    "        else:\n",
    "            # Iterate through each pattern mu\n",
    "            for mu in range(len(self.patterns)):\n",
    "                # Set each weight between neuron i and j\n",
    "                for i in range(self.N):\n",
    "                    for j in range((i - self.N) % self.N):\n",
    "                        # Calculate local field\n",
    "                        local_field = 0\n",
    "                        for k in range(self.N):\n",
    "                            if (k != i & k != j):\n",
    "                                if not np.isnan(weight_matrix[i][k]):\n",
    "                                    local_field += weight_matrix[i][k] * self.patterns[mu][k]\n",
    "                        # Increment weight for the pattern\n",
    "                        weight_matrix[i][j] += (1/self.N) * ((self.patterns[mu][i] * self.patterns[mu][j]) -\n",
    "                                                             ((1/self.N) * self.patterns[mu][i] * local_field) -\n",
    "                                                             ((1/self.N) * local_field * self.patterns[mu][j]))\n",
    "        \n",
    "        if (self.dropout_rate > 0):\n",
    "            # Count the total number of weights\n",
    "            n_weights = np.count_nonzero(~np.isnan(weight_matrix))\n",
    "            # Calculate how many to set as nan\n",
    "            n_to_remove = math.ceil(n_weights * self.dropout_rate)\n",
    "            # Count how many have been removed so far\n",
    "            counter = 0\n",
    "            \n",
    "            while counter < n_to_remove:\n",
    "                # Randomly select a weight\n",
    "                x = random.randint(0, len(weight_matrix) - 1)\n",
    "                y = random.randint(0, len(weight_matrix[x]) - 1)\n",
    "                \n",
    "                if not np.isnan(weight_matrix[x][y]):\n",
    "                    # Set it as nan if not already\n",
    "                    weight_matrix[x][y] = None\n",
    "                    counter += 1\n",
    "                    \n",
    "        return(weight_matrix)\n",
    "    \n",
    "    def calculateEnergy(self, network_state):\n",
    "        # Add energy between each connected neuron\n",
    "        sum_energy = 0\n",
    "        \n",
    "        for i in range(self.N):\n",
    "            for j in range((i - self.N) % self.N):\n",
    "                if not np.isnan(self.weight_matrix[i][j]):\n",
    "                    sum_energy += self.weight_matrix[i][j] * network_state[i] * network_state[j]\n",
    "\n",
    "        energy = -0.5 * sum_energy\n",
    "        \n",
    "        return(energy)\n",
    "    \n",
    "    def neuronInput(self, unit, network_state):\n",
    "        # Get the weights of neurons connected to unit i\n",
    "        connection_weights = [self.weight_matrix[unit][j] for j in range(unit)]\n",
    "        connection_weights = connection_weights + [self.weight_matrix[j][unit]\n",
    "                                                   for j in range(unit + 1, self.N)]\n",
    "\n",
    "        # Get the indexes of the removed weights\n",
    "        dropped_weights = [i for i in range(len(connection_weights))\n",
    "                           if np.isnan(connection_weights[i])]\n",
    "        connection_weights = np.delete(connection_weights, dropped_weights)\n",
    "        \n",
    "        # Get the states of connected neurons\n",
    "        connection_states = np.copy(network_state)\n",
    "        connection_states = np.delete(connection_states, unit)\n",
    "        connection_states = np.delete(connection_states, dropped_weights)\n",
    "        # Get the thresholds\n",
    "        connection_thresholds = np.copy(self.unit_thresholds)\n",
    "        connection_thresholds = np.delete(connection_thresholds, unit)\n",
    "        connection_thresholds = np.delete(connection_thresholds, dropped_weights)\n",
    "\n",
    "        # Calculate the neuron's total input\n",
    "        unit_input = sum((connection_weights * connection_states) - connection_thresholds)\n",
    "        \n",
    "        return(unit_input)\n",
    "    \n",
    "    def runNetwork(self, pattern, update_type = \"asynchronous\", random_update = True, \n",
    "                   stable_iterations = 500):\n",
    "        # Set the initial state as the values of the input pattern\n",
    "        network_state = np.copy(pattern)\n",
    "        # Calculate initial energy of the whole network\n",
    "        energy = self.calculateEnergy(network_state)\n",
    "        \n",
    "        # Count how many times energy has remained the same\n",
    "        same_energy_count = 0\n",
    "        # Whether the network state is stable\n",
    "        stable = False\n",
    "        unit_counter = 0\n",
    "        \n",
    "        # Run until network converges and pattern remains stable\n",
    "        while not stable:\n",
    "            # Asynchronous state update\n",
    "            if update_type[0].lower() != \"s\":\n",
    "                if (random_update):\n",
    "                    # Randomly select neuron i to update\n",
    "                    unit = random.randint(0, self.N - 1)\n",
    "                else:\n",
    "                    # Incrementally select each neuron\n",
    "                    unit = unit_counter\n",
    "                    unit_counter = (unit_counter + 1) % self.N\n",
    "\n",
    "                # Determine its output state\n",
    "                unit_input = self.neuronInput(unit, network_state)\n",
    "                network_state[unit] = 1 if unit_input >= 0 else -1\n",
    "            \n",
    "            # Synchronous state update\n",
    "            else:\n",
    "                # Copy the network state\n",
    "                updated_network_state = np.copy(network_state)\n",
    "                \n",
    "                # Update every unit i\n",
    "                for unit in range(self.N):\n",
    "                    unit_input = self.neuronInput(unit, network_state)\n",
    "                    updated_network_state[unit] = 1 if unit_input >= 0 else -1\n",
    "                    \n",
    "                network_state = updated_network_state\n",
    "\n",
    "            # Calculate the updated energy after changing the neurons state\n",
    "            new_energy = self.calculateEnergy(network_state)\n",
    "\n",
    "            # If energy hasn't changed, add to the counter\n",
    "            if (new_energy == energy):\n",
    "                same_energy_count += 1\n",
    "            else:\n",
    "                same_energy_count = 0\n",
    "\n",
    "            energy = new_energy\n",
    "\n",
    "            # Network is stable if energy hasn't improved after n iterations\n",
    "            if (same_energy_count == stable_iterations):\n",
    "                stable = True\n",
    "                \n",
    "        return(network_state)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a4ea626b",
   "metadata": {},
   "source": [
    "# Network Capacity\n",
    "The capacity of a Hopfield net is the number of memories it is able to store. A network trained with the Hebbian learning rule has an absolute capacity $C_{H}$, while a network trained with the Storkey learning rule theoretically has a higher capacity $C_{S}$. In these equations, n is the number of neurons which is equivalent to the length of the patterns the network is trained on.\n",
    "\n",
    "\\begin{equation}\n",
    "C_{H} \\cong \\frac{n}{2 log_{2}n}\n",
    "\\end{equation}\n",
    "\n",
    "\\begin{equation}\n",
    "C_{S} \\cong \\frac{n}{2 \\sqrt{log_{2}n}}\n",
    "\\end{equation}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 103,
   "id": "53c6a720",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hebbian absolute capacity:  2.3137821315975917\n",
      "Storkey absolute capacity:  4.810178927646653\n"
     ]
    }
   ],
   "source": [
    "# Calculate network capacity for letter patterns\n",
    "n = len(letter_patterns[0])\n",
    "\n",
    "print(\"Hebbian absolute capacity: \", str(n / (2 * math.log2(n))))\n",
    "print(\"Storkey absolute capacity: \", str(n / (2 * math.sqrt(math.log2(n)))))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "85e77807",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hebbian absolute capacity:  7.5257498915995305\n",
      "Storkey absolute capacity:  19.398131213598298\n"
     ]
    }
   ],
   "source": [
    "# Calculate network capacity for binary patterns\n",
    "n = len(binary_patterns[0])\n",
    "\n",
    "print(\"Hebbian absolute capacity: \", str(n / (2 * math.log2(n))))\n",
    "print(\"Storkey absolute capacity: \", str(n / (2 * math.sqrt(math.log2(n)))))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "15f19571",
   "metadata": {},
   "source": [
    "# Training and Testing"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2ed18863",
   "metadata": {},
   "source": [
    "## Letter Patterns\n",
    "### Network Initialisation\n",
    "\n",
    "To create the network, an array of p same size patterns is given and the number of neurons N is set as the pattern size. The network weights are initialised as a lower triangle matrix of zeros as Hopfield net weights between all neurons are symmetric. Weights are then calculated depending on the learning rule. If the Hebbian learning rule was specified, weights are set by the equation below, where $x_{i}^{\\mu}$ denotes the $i^{th}$ component of pattern $\\mu$.\n",
    "\n",
    "\\begin{equation}\n",
    "\\label{eqn:hopfield_weight_hebbian}\n",
    "w_{ij} = \\frac{1}{N} \\sum_{\\mu = 1}^{p} x_{i}^{\\mu}x_{j}^{\\mu}\n",
    "\\end{equation}\n",
    "\n",
    "If the learning rule is set as the Storkey learning rule, weights are determined through the equations below, where $h_{ij}$ is a form of local field.\n",
    "\n",
    "\\begin{equation}\n",
    "\\label{eqn:hopfield_weight_storkey_1}\n",
    "w_{ij}^{0} = 0,  \\mbox{for all i,j}\n",
    "\\end{equation}\n",
    "\n",
    "\\begin{equation}\n",
    "\\label{eqn:hopfield_weight_storkey_2}\n",
    "w_{ij}^{\\mu} = w_{ij}^{\\mu - 1} + \\frac{1}{N} (x_{i}^{\\mu} x_{j}^{\\mu} - \\frac{1}{N} x_{i}^{\\mu} h_{ij} - \\frac{1}{N} h_{ij} x_{j}^{\\mu})\n",
    "\\end{equation}\n",
    "\n",
    "\\begin{equation}\n",
    "\\label{eqn:hopfield_weight_storkey_3}\n",
    "h_{ij}^{\\mu} = \\sum_{k = 1 \\mbox{ } k \\neq i,j}^{N} w_{ik}^{\\mu - 1} x_{k}^{\\mu}\n",
    "\\end{equation}\n",
    "\n",
    "When the network is run, its initial state is set as the input pattern and the energy of the whole network calculated, where $v_{i}$ is the state of unit $i$ and $v_{i} \\in \\{-1, 1\\}$.\n",
    "\n",
    "\\begin{equation}\n",
    "\\label{eqn:hopfield_energy}\n",
    "E = -\\frac{1}{2} \\sum_{ij} w_{ij}v_{i}v_{j}\n",
    "\\end{equation}\n",
    "\n",
    "The state $s$ of all neurons are then repeatedly updated until the network converges to a stable state. This is determined by the network's energy not changing for n iterations, where in this case n was set as 500. By default, neuron state updates are set to be asynchronous, in which neurons are randomly selected to be updated one at a time.\n",
    "\n",
    "$\\text{if } \\sum_{j = 1}^{N} w_{ij}v_{j} - \\theta_{i} \\geq 0 $, $ s_{i} = 1$\n",
    "\n",
    "$\\text{else } s_{i} = -1$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3f52fbbc",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Train the network on the letter patterns\n",
    "n_train_patterns = 3\n",
    "\n",
    "letter_hopfield = Hopfield(letter_patterns[:n_train_patterns], learning_rule = \"h\", dropout_rate = 0.4)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6a6c860b",
   "metadata": {},
   "source": [
    "### Testing Performance\n",
    "After training the network, it can be tested to see how well it recalls a given pattern. In this case to evaluate performance, the percentage of pixels correctly recalled is calculated."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 111,
   "id": "629f4727",
   "metadata": {},
   "outputs": [],
   "source": [
    "def calculateSimilarity(predictions, expected):\n",
    "    # Calculate how similar each prediction is to the expected pattern\n",
    "    pixel_similarity = []\n",
    "\n",
    "    # Iterate through predictions\n",
    "    for out, ref in zip(predictions, expected):\n",
    "        count = 0\n",
    "        for i in range(len(out)):\n",
    "            # Check if pixels are the same\n",
    "            if out[i] == ref[i]:\n",
    "                count += 1\n",
    "        pixel_similarity.append(count / len(out))\n",
    "        \n",
    "    return(pixel_similarity)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 140,
   "id": "b16843e5",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1.0, 1.0, 0.8]\n",
      "Average percent identical: 93.33333333333333%\n"
     ]
    },
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAQ0AAAB+CAYAAAA+00TTAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjQuMywgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/MnkTPAAAACXBIWXMAAAsTAAALEwEAmpwYAAAEjElEQVR4nO3dsWtddRjG8ecRpVoKWkypgrV3rUuFOwmKY3HQZqpQof0DdFFxdRBswUFFsbOLDlKqIKI4KYJWSEbpJDSTrUZEVCzY8Ha4d4rG5Lk57e+c0+8HMiRwb968wzfn3Bt+cVUJAHbqjtYDABgWogEgQjQARIgGgAjRABAhGgAiRANAZNDRsP2V7d9s72k9y5jYvmz7b9t/zvf7me1DrecaG9snba/M9/yT7c9tP956ru0MNhq2J5KekFSSnmk7zSg9XVX7JD0o6aqkdxvPMyq2X5L0tqQzkg5KeljSOUnHG461I4ONhqRTki5Kel/S6bajjFdVXZN0XtIjrWcZC9v3SnpN0vNVdaGq/qqqf6rq06p6pfV827mz9QC7cErSm5K+l3TR9sGqutp4ptGxvVfSs5oFGt14TNLdkj5uPcgiBhmN+X3fYUkfVdW67R8lnZT0VtvJRuUT29cl7ZP0s6RjjecZk/slrVfV9daDLGKotyenJX1ZVevzzz8UtyhdW66q+yTtkfSCpK9tP9B2pNH4VdKS7UH+0h5cNGzfI+mEpCdtX7F9RdKLko7aPtp2uvGpqo2quiBpQ1LvX9kfiO8kXZO03HiOhQwuGpotekOzF+YenX8ckfSNZq9zoEOeOS5pv6RLrecZg6r6XdKrkt6zvWx7r+27bD9l+43W823HQztPw/YXkn6oqpc3ff2EpHckPTTUe8W+sH1Zs7cBNzR7S3tN0tmq+qDlXGNj+znNrpKPSPpD0qqk16vq26aDbWNw0QDQ1hBvTwA0RDQARIgGgAjRABAhGgAi0V+k2e7krZbpdNrF03RqdXW1y6dbr6oD6YOWlpZqMpl0OUdv9GG/EjsObLnjJn/GurKy0uLb/i/bXT7d2iIPmkwmvdxNF/qwX4kdB7bcMbcnACJEA0CEaACIEA0AEaIBIEI0AESIBoAI0QAQIRoAIkQDQIRoAIgQDQARogEgQjQARIgGgAjRABCJDuGZTqedHGDS8WEhnejy/7+0/vlaf///Mqb99mWGzW7VjrnSABAhGgAiRANAhGgAiBANABGiASBCNABEiAaACNEAECEaACJEA0CEaACIEA0AEaIBIEI0AESIBoAI0QAQiU7u6kqXJwzh3/q43z6edLUbt/OOudIAECEaACJEA0CEaACIEA0AEaIBIEI0AESIBoAI0QAQIRoAIkQDQIRoAIgQDQARogEgQjQARIgGgAjRABAhGgAiTY776+PRb308vm1RY99vH36+Psyw2a3aMVcaACJEA0CEaACIEA0AEaIBIEI0AESIBoAI0QAQIRoAIkQDQIRoAIgQDQARogEgQjQARIgGgAjRABAhGgAiTU7uws3Vx1PI+njS1W7czjvmSgNAhGgAiBANABGiASBCNABEiAaACNEAECEaACJEA0CEaACIEA0AEaIBIEI0AESIBoAI0QAQIRoAIkQDQIRoAIg4ObbM9i+S1m7eOKNxuKoOpA9ivzu20H4ldhzYcsdRNACA2xMAEaIBIEI0AESIBoAI0QAQIRoAIkQDQIRoAIgQDQCRG51P6Kl/zah8AAAAAElFTkSuQmCC\n",
      "text/plain": [
       "<Figure size 324x144 with 3 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "kwargs = {\"update_type\" : \"asynchronous\"}\n",
    "getLetterOutput = lambda pattern_idx, args : letter_hopfield.runNetwork(noisy_letter_patterns[pattern_idx],\n",
    "                                                                        **args).reshape((5,4))\n",
    "\n",
    "letter_outputs = {'A': getLetterOutput(0, kwargs),\n",
    "                  'B': getLetterOutput(1, kwargs),\n",
    "                  'C': getLetterOutput(2, kwargs),\n",
    "                  'D': getLetterOutput(3, kwargs),\n",
    "                  'E': getLetterOutput(4, kwargs),\n",
    "                  'F': getLetterOutput(5, kwargs),\n",
    "                  'G': getLetterOutput(6, kwargs),\n",
    "                  'H': getLetterOutput(7, kwargs)}\n",
    "\n",
    "# Check similarity between predictions and expected patterns\n",
    "percentage_same = calculateSimilarity([pred.flatten() for pred in np.array(list(letter_outputs.values())[:n_train_patterns])],\n",
    "                                      letter_patterns[:n_train_patterns])\n",
    "print(percentage_same)\n",
    "print(\"Average percent identical: \" + str(statistics.mean(percentage_same) * 100) + \"%\")\n",
    "\n",
    "plotPatterns({k: letter_outputs[k] for k in list(letter_outputs)[:n_train_patterns]},\n",
    "             1, n_train_patterns, file = \"Hopfield/noisy_letters_3.pdf\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "972b9327",
   "metadata": {},
   "source": [
    "## Shape Patterns"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 113,
   "id": "12240b59",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1.0, 1.0]\n",
      "Average percent identical: 100.0%\n"
     ]
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 216x288 with 4 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Train network on binary patterns\n",
    "first_train_pattern = 0\n",
    "last_train_pattern = 2\n",
    "n_train_patterns = last_train_pattern - first_train_pattern\n",
    "\n",
    "binary_hopfield = Hopfield(binary_patterns[first_train_pattern:last_train_pattern], learning_rule = \"s\", dropout_rate = 0.4)\n",
    "\n",
    "kwargs = {\"update_type\" : \"asynchronous\"}\n",
    "getRandomOutput = lambda pattern_idx, args : binary_hopfield.runNetwork(noisy_binary_patterns[pattern_idx],\n",
    "                                                                        **args)\n",
    "# Get predictions\n",
    "output_patterns = [getRandomOutput(0, kwargs)]\n",
    "\n",
    "for i in range(1, n_train_patterns):\n",
    "    output_patterns = np.vstack((output_patterns, getRandomOutput(i, kwargs)))\n",
    "    \n",
    "# Check similarity between predictions and expected patterns\n",
    "percentage_same = calculateSimilarity(output_patterns, binary_patterns[first_train_pattern:last_train_pattern])\n",
    "print(percentage_same)\n",
    "print(\"Average percent identical: \" + str(statistics.mean(percentage_same) * 100) + \"%\")\n",
    "    \n",
    "plotPatterns(np.vstack((output_patterns, binary_patterns[first_train_pattern:last_train_pattern])),\n",
    "             num_row = 2, num_col = n_train_patterns,\n",
    "             new_shape = pattern_size,\n",
    "             subplot_titles = [\"Prediction \\n\" + str(percentage_same[i] * 100) + \"%\" for i in range(n_train_patterns)] + [\"Expected\" for j in range(n_train_patterns)],\n",
    "             file = \"Hopfield/binary_patterns_dropout_20.pdf\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 86,
   "id": "087a0dae",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x144 with 4 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "plotPatterns(output_patterns,\n",
    "             num_row = 1, num_col = n_train_patterns,\n",
    "             new_shape = pattern_size,\n",
    "             subplot_titles = [\"Prediction \\n\" + str(percentage_same[i] * 100) + \"%\" for i in range(n_train_patterns)],\n",
    "             file = \"Hopfield/binary_patterns_last_hebbian.pdf\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}