Merge branch 'master' into enhance-tutorial-6

jeshraghian · Dec 14, 2022 · 5ab6ff0 · 5ab6ff0
2 parents 2b70e0a + 5b8af22
commit 5ab6ff0
Show file tree

Hide file tree

Showing 72 changed files with 3,919 additions and 1,580 deletions.
diff --git a/.flake8 b/.flake8
@@ -1,5 +1,4 @@
 [flake8]
-    ignore = E203, E266, E402, E501, W503, F403, F401, F405, F841, C901
-    max-line-length = 89
-    max-complexity = 18
-    select = B,C,E,F,W,T4,B9
+    #ignore = E203, E266, E402, E501, W503, F403, F401, F405, F841, C901
+    ignore = E203, W503, F401, F403, C901
+    max-line-length = 79
diff --git a/.github/workflows/build-tag.yml b/.github/workflows/build-tag.yml
@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8]
+        python-version: [3.7, 3.8, 3.9]
 
     steps:
     - uses: actions/checkout@v2

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8]
+        python-version: [3.7, 3.8, 3.9]
 
     steps:
     - uses: actions/checkout@v2

diff --git a/.gitignore b/.gitignore
@@ -106,6 +106,7 @@ snnenv/
 
 # IDE settings
 .vscode/
+.idea/
 
 # Additional Files
 tbptt_test/

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,11 +1,12 @@
 repos:
 -   repo: https://github.com/psf/black
-    rev: 21.5b1
+    rev: 22.3.0
     hooks:
     - id: black
       language_version: python3
 # -   repo: https://github.com/pre-commit/pre-commit-hooks
--   repo: https://gitlab.com/pycqa/flake8
+# -   repo: https://gitlab.com/pycqa/flake8
+-   repo: https://github.com/PyCQA/flake8
     rev: 3.9.2
     hooks:
     - id: flake8
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -102,7 +102,7 @@ Before you submit a pull request, check that it meets these guidelines:
 2. If the pull request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring, and add the
    feature to the list in README.rst.
-3. The pull request should work for Python 3.6, 3.7 and 3.8, and for PyPy. Check
+3. The pull request should work for Python 3.7, 3.8, 3.9 and for PyPy. Check
    https://github.com/jeshraghian/snntorch/actions
    and make sure that the tests pass for all supported Python versions.
 

diff --git a/README.rst b/README.rst
@@ -331,7 +331,7 @@ Acknowledgments
 ^^^^^^^^^^^^^^^^^^^^^^^^
 snnTorch is currently maintained by the `UCSC Neuromorphic Computing Group <https://ncg.ucsc.edu>`_. It was initially developed by `Jason K. Eshraghian`_ in the `Lu Group (University of Michigan)`_. 
 
-Additional contributions were made by `Vincent Sun <https://github.com/vinniesun>`_, `Peng Zhou <https://github.com/pengzhouzp>`_, `Ridger Zhu <https://github.com/ridgerchu>`_, Xinxin Wang, and Emre Neftci.
+Additional contributions were made by `Vincent Sun <https://github.com/vinniesun>`_, `Peng Zhou <https://github.com/pengzhouzp>`_, `Ridger Zhu <https://github.com/ridgerchu>`_, `Alexander Henkes <https://github.com/ahenkes1>`_, Xinxin Wang, and Emre Neftci.
 
 .. _Jason K. Eshraghian: https://jasoneshraghian.com
 .. _Lu Group (University of Michigan): https://lugroup.engin.umich.edu/

diff --git a/docs/conf.py b/docs/conf.py
@@ -4,7 +4,6 @@
 
 sys.path.insert(0, os.path.abspath(".."))
 
-import snntorch
 
 # fmt: off
 __version__ = '0.5.3'
@@ -49,7 +48,7 @@
 release = __version__
 # release = "0.1.0"
 
-language = None
+# language = None
 
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
@@ -71,7 +70,8 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-# html_logo = "_static/img/snntorch_alpha_full.png"  # RTD is adding an additional _static here
+# html_logo = "_static/img/snntorch_alpha_full.png"
+# RTD is adding an additional _static here
 html_logo = "_static/img/snntorch_alpha_full.png"
 
 # Add any paths that contain custom static files (such as style sheets) here,

diff --git a/docs/snntorch.rst b/docs/snntorch.rst
@@ -207,6 +207,14 @@ Neuron List
 
     snn.neurons_*
 
+snnTorch Layers
+---------------------
+
+.. automodule:: snntorch._layers.bntt
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 
 Neuron Parent Classes
 ---------------------

diff --git a/docs/tutorials/tutorial_1.rst b/docs/tutorials/tutorial_1.rst
@@ -2,7 +2,7 @@
 Tutorial 1 - Spike Encoding
 ===========================
 
-Tutorial written by Jason K. Eshraghian (`www.jasoneshraghian.com <https://www.jasoneshraghian.com>`_)
+Tutorial written by Jason K. Eshraghian (`www.ncg.ucsc.edu <https://www.ncg.ucsc.edu>`_)
 
 .. image:: https://colab.research.google.com/assets/colab-badge.svg
         :alt: Open In Colab

diff --git a/docs/tutorials/tutorial_2.rst b/docs/tutorials/tutorial_2.rst
@@ -2,7 +2,7 @@
 Tutorial 2 - The Leaky Integrate-and-Fire Neuron
 ======================================================
 
-Tutorial written by Jason K. Eshraghian (`www.jasoneshraghian.com <https://www.jasoneshraghian.com>`_)
+Tutorial written by Jason K. Eshraghian (`www.ncg.ucsc.edu <https://www.ncg.ucsc.edu>`_)
 
 .. image:: https://colab.research.google.com/assets/colab-badge.svg
         :alt: Open In Colab

diff --git a/docs/tutorials/tutorial_3.rst b/docs/tutorials/tutorial_3.rst
@@ -2,7 +2,7 @@
 Tutorial 3 - A Feedforward Spiking Neural Network
 ================================================
 
-Tutorial written by Jason K. Eshraghian (`www.jasoneshraghian.com <https://www.jasoneshraghian.com>`_)
+Tutorial written by Jason K. Eshraghian (`www.ncg.ucsc.edu <https://www.ncg.ucsc.edu>`_)
 
 .. image:: https://colab.research.google.com/assets/colab-badge.svg
         :alt: Open In Colab

diff --git a/docs/tutorials/tutorial_4.rst b/docs/tutorials/tutorial_4.rst
@@ -2,7 +2,7 @@
 Tutorial 4 - 2nd Order Spiking Neuron Models
 ===========================
 
-Tutorial written by Jason K. Eshraghian (`www.jasoneshraghian.com <https://www.jasoneshraghian.com>`_)
+Tutorial written by Jason K. Eshraghian (`www.ncg.ucsc.edu <https://www.ncg.ucsc.edu>`_)
 
 .. image:: https://colab.research.google.com/assets/colab-badge.svg
         :alt: Open In Colab

diff --git a/docs/tutorials/tutorial_5.rst b/docs/tutorials/tutorial_5.rst
@@ -2,7 +2,7 @@
 Tutorial 5 - Training Spiking Neural Networks with snntorch
 ===========================================================
 
-Tutorial written by Jason K. Eshraghian (`www.jasoneshraghian.com <https://www.jasoneshraghian.com>`_)
+Tutorial written by Jason K. Eshraghian (`www.ncg.ucsc.edu <https://www.ncg.ucsc.edu>`_)
 
 .. image:: https://colab.research.google.com/assets/colab-badge.svg
         :alt: Open In Colab

diff --git a/docs/tutorials/tutorial_6.rst b/docs/tutorials/tutorial_6.rst
@@ -2,7 +2,7 @@
 Tutorial 6 - Surrogate Gradient Descent in a Convolutional SNN
 ===============================================================================================
 
-Tutorial written by Jason K. Eshraghian (`www.jasoneshraghian.com <https://www.jasoneshraghian.com>`_)
+Tutorial written by Jason K. Eshraghian (`www.ncg.ucsc.edu <https://www.ncg.ucsc.edu>`_)
 
 .. image:: https://colab.research.google.com/assets/colab-badge.svg
         :alt: Open In Colab
@@ -278,7 +278,10 @@ The convolutional network architecture to be used is:
 
 In the previous tutorial, the network was wrapped inside of a class, as shown above. 
 With increasing network complexity, this adds a
-lot of boilerplate code that we might wish to avoid. Alternatively, the ``nn.Sequential`` method can be used instead:
+lot of boilerplate code that we might wish to avoid. Alternatively, the ``nn.Sequential`` method can be used instead.
+
+.. note::
+    The following code-block simulates over one single time-step, and requires a separate for-loop over time.
 
 ::
 

diff --git a/docs/tutorials/tutorial_7.rst b/docs/tutorials/tutorial_7.rst
@@ -2,7 +2,7 @@
 Tutorial 7 - Neuromorphic Datasets with Tonic + snnTorch
 ===============================================================================================
 
-Tutorial written by Gregor Lenz (`https://lenzgregor.com <https://lenzgregor.com)>`_) and Jason K. Eshraghian (`www.jasoneshraghian.com <https://www.jasoneshraghian.com>`_)
+Tutorial written by Gregor Lenz (`https://lenzgregor.com <https://lenzgregor.com)>`_) and Jason K. Eshraghian (`www.ncg.ucsc.edu <https://www.ncg.ucsc.edu>`_)
 
 .. image:: https://colab.research.google.com/assets/colab-badge.svg
         :alt: Open In Colab
@@ -123,61 +123,29 @@ dense format.
     trainset = tonic.datasets.NMNIST(save_to='./data', transform=frame_transform, train=True)
     testset = tonic.datasets.NMNIST(save_to='./data', transform=frame_transform, train=False)
 
-1.2 Fast Dataloading via Caching
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The original data is stored in a format that is slow to read. To speed
-up dataloading, we can make use of disk caching. That means that once
-files are loaded from the original file, they are written to disk in an
-efficient format in our cache directory. Let’s compare some file reading
-speeds to read 100 examples.
-
-::
 
-    def load_sample_simple():
-        for i in range(100):
-            events, target = trainset[i]
 
-::
+1.2 Fast DataLoading
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    >>> %timeit -o load_sample_simple()
-    1 loop, best of 5: 2.95 s per loop
+The original data is stored in a format that is slow to read. To speed up 
+dataloading, we can make use of disk caching and batching. That means that 
+once files are loaded from the original dataset, they are written to the disk. 
 
-We can decrease the time it takes to read 100 samples by using a PyTorch
-DataLoader in addition to disk caching.
+Because event recordings have different lengths, we are going to provide a 
+collation function ``tonic.collation.PadTensors()`` that will pad out shorter 
+recordings to ensure all samples in a batch have the same dimensions. 
 
-::
+::  
 
     from torch.utils.data import DataLoader
-    from tonic import CachedDataset
-    
-    cached_trainset = CachedDataset(trainset, cache_path='./cache/nmnist/train')
-    cached_dataloader = DataLoader(cached_trainset)
-    
-    def load_sample_cached():
-        for i, (events, target) in enumerate(iter(cached_dataloader)):
-            if i > 99: break
-
-::
-
-    >>> %timeit -o -r 20 load_sample_cached()
-    1 loop, best of 20: 2.05 s per loop
+    from tonic import DiskCachedDataset
 
 
-1.3 Even Faster DataLoading via Batching
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Now that we’ve reduced our loading time, we also want to use batching to
-make efficient use of the GPU.
-
-Because event recordings have different lengths, we are going to provide
-a collation function ``tonic.collation.PadTensors()`` that will pad out
-shorter recordings to ensure all samples in a batch have the same
-dimensions.
-
-::
+    cached_trainset = DiskCachedDataset(trainset, cache_path='./cache/nmnist/train')
+    cached_dataloader = DataLoader(cached_trainset)
 
-    batch_size = 100
+    batch_size = 128
     trainloader = DataLoader(cached_trainset, batch_size=batch_size, collate_fn=tonic.collation.PadTensors())
 
 ::
@@ -188,11 +156,20 @@ dimensions.
 ::
 
     >>> %timeit -o -r 10 load_sample_batched()
-    100 loops, best of 10: 18.1 ms per loop
+    4.2 ms ± 119 µs per loop (mean ± std. dev. of 10 runs, 100 loops each)
+
+
+By using disk caching and a PyTorch dataloader with multithreading and batching 
+support, we have signifantly reduced loading times.
+
+If you have a large amount of RAM available, you can speed up dataloading further 
+by caching to main memory instead of to disk:
+
+::
+    from tonic import MemoryCachedDataset
+
+    cached_trainset = MemoryCachedDataset(trainset)
 
-By using disk caching and a PyTorch dataloader with multithreading and
-batching support, we have reduced loading times to less than a tenth per
-sample in comparison to naively iterating over the dataset!
 
 2. Training our network using frames created from events
 -----------------------------------------------------------
@@ -212,14 +189,14 @@ like.
     transform = tonic.transforms.Compose([torch.from_numpy,
                                           torchvision.transforms.RandomRotation([-10,10])])
     
-    cached_trainset = CachedDataset(trainset, transform=transform, cache_path='./cache/nmnist/train')
+    cached_trainset = DiskCachedDataset(trainset, transform=transform, cache_path='./cache/nmnist/train')
     
     # no augmentations for the testset
-    cached_testset = CachedDataset(testset, cache_path='./cache/nmnist/test')
+    cached_testset = DiskCachedDataset(testset, cache_path='./cache/nmnist/test')
     
     batch_size = 128
-    trainloader = DataLoader(cached_trainset, batch_size=batch_size, collate_fn=tonic.collation.PadTensors(), shuffle=True)
-    testloader = DataLoader(cached_testset, batch_size=batch_size, collate_fn=tonic.collation.PadTensors())
+    trainloader = DataLoader(cached_trainset, batch_size=batch_size, collate_fn=tonic.collation.PadTensors(batch_first=False), shuffle=True)
+    testloader = DataLoader(cached_testset, batch_size=batch_size, collate_fn=tonic.collation.PadTensors(batch_first=False))
 
 A mini-batch now has the dimensions (time steps, batch size, channels,
 height, width). The number of time steps will be set to that of the
@@ -261,7 +238,7 @@ previous tutorial. The convolutional network architecture to be used is:
     device = torch.device("cuda") if torch.cuda.is_available() else torch.device("cpu")
     
     # neuron and simulation parameters
-    spike_grad = surrogate.fast_sigmoid(slope=75)
+    spike_grad = surrogate.atan()
     beta = 0.5
     
     #  Initialize Network

diff --git a/examples/tutorial_1_spikegen.ipynb b/examples/tutorial_1_spikegen.ipynb
@@ -9,7 +9,7 @@
     "[<img src='https://github.com/jeshraghian/snntorch/blob/master/docs/_static/img/snntorch_alpha_w.png?raw=true' width=\"400\">](https://github.com/jeshraghian/snntorch/)\n",
     "\n",
     "# Tutorial 1 - Spike Encoding\n",
-    "## By Jason K. Eshraghian (www.jasoneshraghian.com)\n",
+    "## By Jason K. Eshraghian (www.ncg.ucsc.edu)\n",
     "\n",
     "\n",
     "<a href=\"https://colab.research.google.com/github/jeshraghian/snntorch/blob/master/examples/tutorial_1_spikegen.ipynb\">\n",

diff --git a/examples/tutorial_2_lif_neuron.ipynb b/examples/tutorial_2_lif_neuron.ipynb
@@ -20,7 +20,7 @@
         "\n",
         "# snnTorch - The Leaky Integrate and Fire Neuron\n",
         "## Tutorial 2\n",
-        "### By Jason K. Eshraghian (www.jasoneshraghian.com)\n",
+        "### By Jason K. Eshraghian (www.ncg.ucsc.edu)\n",
         "\n",
         "<a href=\"https://colab.research.google.com/github/jeshraghian/snntorch/blob/master/examples/tutorial_2_lif_neuron.ipynb\">\n",
         "  <img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/>\n",
@@ -1451,7 +1451,7 @@
       "provenance": []
     },
     "kernelspec": {
-      "display_name": "Python 3",
+      "display_name": "Python 3.7.0 ('snnenv': venv)",
       "language": "python",
       "name": "python3"
     },
@@ -1465,7 +1465,12 @@
       "name": "python",
       "nbconvert_exporter": "python",
       "pygments_lexer": "ipython3",
-      "version": "3.6.8"
+      "version": "3.7.0"
+    },
+    "vscode": {
+      "interpreter": {
+        "hash": "cda51994da7a97c2e92f9e8832b8fe412980cf29d1c6c8cbe827a5abbabd9c57"
+      }
     }
   },
   "nbformat": 4,

diff --git a/examples/tutorial_3_feedforward_snn.ipynb b/examples/tutorial_3_feedforward_snn.ipynb
@@ -21,7 +21,7 @@
         "\n",
         "# snnTorch - A Feedforward Spiking Neural Network\n",
         "## Tutorial 3\n",
-        "### By Jason K. Eshraghian (www.jasoneshraghian.com)\n",
+        "### By Jason K. Eshraghian (www.ncg.ucsc.edu)\n",
         "\n",
         "<a href=\"https://colab.research.google.com/github/jeshraghian/snntorch/blob/master/examples/tutorial_3_feedforward_snn.ipynb\">\n",
         "  <img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/>\n",
@@ -659,7 +659,7 @@
       "provenance": []
     },
     "kernelspec": {
-      "display_name": "Python 3",
+      "display_name": "Python 3.7.0 ('snnenv': venv)",
       "language": "python",
       "name": "python3"
     },
@@ -673,7 +673,12 @@
       "name": "python",
       "nbconvert_exporter": "python",
       "pygments_lexer": "ipython3",
-      "version": "3.6.8"
+      "version": "3.7.0"
+    },
+    "vscode": {
+      "interpreter": {
+        "hash": "cda51994da7a97c2e92f9e8832b8fe412980cf29d1c6c8cbe827a5abbabd9c57"
+      }
     }
   },
   "nbformat": 4,

diff --git a/examples/tutorial_4_advanced_neurons.ipynb b/examples/tutorial_4_advanced_neurons.ipynb
@@ -20,7 +20,7 @@
         "\n",
         "# snnTorch - 2nd Order Spiking Neuron Models\n",
         "## Tutorial 4\n",
-        "### By Jason K. Eshraghian (www.jasoneshraghian.com)\n",
+        "### By Jason K. Eshraghian (www.ncg.ucsc.edu)\n",
         "\n",
         "<a href=\"https://colab.research.google.com/github/jeshraghian/snntorch/blob/master/examples/tutorial_4_advanced_neurons.ipynb\">\n",
         "  <img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/>\n",