bindsnet

A Python package used for simulating spiking neural networks (SNNs) on CPUs or GPUs using PyTorch Tensor functionality.

BindsNET is a spiking neural network simulation library geared towards the development of biologically inspired algorithms for machine learning.

This package is used as part of ongoing research on applying SNNs, machine learning (ML) and reinforcement learning (RL) problems in the Biologically Inspired Neural & Dynamical Systems (BINDS) lab and the Allen Discovery Center at Tufts University.

Check out the BindsNET examples for a collection of experiments, functions for the analysis of results, plots of experiment outcomes, and more. Documentation for the package can be found here.

Requirements

• Python >=3.11,<3.14 (continuously tested on 3.11, 3.12, and 3.13)

Setting things up

Reproducible install

For a byte-for-byte reproducible environment, install the pinned dependency set from the committed poetry.lock:

poetry install

Alternatively, the provided Dockerfile builds the full pinned stack (see Using Docker below).

Using Pip

To install the latest release from PyPI

pip install bindsnet

To install the current development code from the GitHub repository

pip install git+https://github.com/BindsNET/bindsnet.git

Or, to build the bindsnet package from source, clone the GitHub repository, change directory to the top level of this project, and issue

pip install .

Or, to install in editable mode (allows modification of package without re-installing):

pip install -e .

The reinforcement-learning environments use Gymnasium with the Arcade Learning Environment (ale-py); both are installed with BindsNET.

Using Docker

The Dockerfile installs BindsNET with the dependency versions pinned in poetry.lock. From the top level directory of this project, issue

docker build -t bindsnet .

(add --build-arg DEPS=main to leave out the development tools). To get a bash terminal inside a container, issue

docker run --rm -it --gpus all bindsnet bash

--gpus all needs the NVIDIA Container Toolkit; leave it out to run on CPU only.

Getting started

To run a near-replication of the SNN from this paper, issue

cd examples/mnist
python eth_mnist.py

There are a number of optional command-line arguments which can be passed in, including --plot (displays useful monitoring figures), --n_neurons [int] (number of excitatory, inhibitory neurons simulated), --mode ['train' | 'test'] (sets network operation to the training or testing phase), and more. Run the script with the --help or -h flag for more information.

A number of other examples are available in the examples directory that are meant to showcase BindsNET’s functionality. Take a look, and let us know what you think!

Learning rules and their sources

Each weight-changing rule is validated against the equations of the paper it implements. The table of rules, papers, equation numbers and tests, plus the pitfalls (reward timing, traces, the Diehl & Cook rule versus PostPre), is in bindsnet/learning/README.md.

Running the tests

Issue the following to run the tests:

python -m pytest test/

Datasets

BindsNET ships no third-party datasets; its loaders fetch them from upstream sources. Every dataset and synthetic stimulus used by the examples, benchmarks, and dataset loaders — with source, retrieval method, license pointer, and spike-encoding preprocessing — is declared in DATA.md.

Reproducing results

REPRODUCING.md maps each shipped model and published claim to its model class, example script, exact command, seed, and measured output (e.g. the Diehl & Cook 2015 MNIST replication via examples/mnist/eth_mnist.py, and the Hazan et al. 2018 scaling benchmark).

Each BindsNET release is an archived snapshot. BindsNET is a research package that keeps gaining features and fixes, and results can also depend on the hardware, so results may differ between releases. A published result is reproduced with the release it was produced on; please name that release in the publication, ideally by its version DOI (see Citing the software).

Background

The simulation of biologically plausible spiking neuron dynamics can be challenging. It is typically done by solving ordinary differential equations (ODEs) which describe said dynamics. PyTorch does not explicitly support the solution of differential equations (as opposed to brian2, for example), but we can convert the ODEs defining the dynamics into difference equations and solve them at regular, short intervals (a dt on the order of 1 millisecond) as an approximation. Of course, under the hood, packages like brian2 are doing the same thing. Doing this in PyTorch is exciting for a few reasons:

1. We can use the powerful and flexible torch.Tensor object, an array similar to the numpy.ndarray that can be moved to and from GPU devices.

2. We can avoid “reinventing the wheel” by repurposing functions from the torch.nn.functional PyTorch submodule in our SNN architectures; e.g., convolution or pooling functions.

The concept that the neuron spike ordering and their relative timing encode information is a central theme in neuroscience. Markram et al. (1997) proposed that synapses between neurons should strengthen or degrade based on this relative timing, and prior to that, Donald Hebb proposed the theory of Hebbian learning, often simply stated as “Neurons that fire together, wire together.” Markram et al.'s extension of the Hebbian theory is known as spike-timing-dependent plasticity (STDP).

We are interested in applying SNNs to ML and RL problems. We use STDP to modify weights of synapses connecting pairs or populations of neurons in SNNs. In the context of ML, we want to learn a setting of synapse weights which will generate data-dependent spiking activity in SNNs. This activity will allow us to subsequently perform some ML task of interest; e.g., discriminating or clustering input data. In the context of RL, we may think of the spiking neural network as an RL agent, whose spiking activity may be converted into actions in an environment’s action space.

We have provided some simple starter scripts for doing unsupervised learning (learning a fully-connected or convolutional representation via STDP), supervised learning (clamping output neurons to desired spiking behavior depending on data labels), and reinforcement learning (converting observations from the Atari game Breakout to input to an SNN, and converting network activity back to actions in the game; see examples/breakout).

Benchmarking

We simulated a network with a population of n Poisson input neurons with firing rates (in Hertz) drawn randomly from U(0, 100), connected all-to-all with a equally-sized population of leaky integrate-and-fire (LIF) neurons, with connection weights sampled from N(0,1). We varied n systematically from 250 to 10,000 in steps of 250, and ran each simulation with every library for 1,000ms with a time resolution dt = 1.0. We tested BindsNET (with CPU and GPU computation), BRIAN2, PyNEST (the Python interface to the NEST SLI interface that runs the C++NEST core simulator), ANNarchy (with CPU and GPU computation), and BRIAN2genn (the BRIAN2 front-end to the GeNN simulator).

Several packages, including BRIAN and PyNEST, allow the setting of certain global preferences; e.g., the number of CPU threads, the number of OpenMP processes, etc. We chose these settings for our benchmark study in an attempt to maximize each library’s speed, but note that BindsNET requires no setting of such options. Our approach, inheriting the computational model of PyTorch, appears to make the best use of the available hardware, and therefore makes it simple for practitioners to get the best performance from their system with the least effort.

The figure above is the 2018 result. examples/benchmark/benchmark.py runs exactly the setup described above for BindsNET, BRIAN2, PyNEST and ANNarchy in one command (BindsNET alone: examples/benchmark/bindsnet_scaling.py), and REPRODUCING.md lists the times measured with it. It replaces the script written in 2018, which used its own input settings for each simulator.

These results are from the 2018 BindsNET paper. All simulations run on Ubuntu 16.04 LTS with Intel® Xeon® CPU E5-2687W v3 @ 3.10GHz, 128Gb RAM @ 2133MHz, and two GeForce GTX TITAN X (GM200) GPUs. Python 3.6 is used in all cases. Clock time was recorded for each simulation run.

Citation

If you use BindsNET in your research, please cite the following article:

@ARTICLE{10.3389/fninf.2018.00089,
	AUTHOR={Hazan, Hananel and Saunders, Daniel J. and Khan, Hassaan and Patel, Devdhar and Sanghavi, Darpan T. and Siegelmann, Hava T. and Kozma, Robert},   
	TITLE={BindsNET: A Machine Learning-Oriented Spiking Neural Networks Library in Python},      
	JOURNAL={Frontiers in Neuroinformatics},      
	VOLUME={12},      
	PAGES={89},     
	YEAR={2018}, 
	URL={https://www.frontiersin.org/article/10.3389/fninf.2018.00089},       
	DOI={10.3389/fninf.2018.00089},      
	ISSN={1662-5196},
}

Citing the software

To cite a specific version of the BindsNET software, use the archived release on Zenodo. The concept DOI below always resolves to the latest version:

BindsNET contributors. BindsNET. Zenodo. https://doi.org/10.5281/zenodo.20695115

(For the exact release used, cite its version DOI; e.g. v0.3.4 is 10.5281/zenodo.20695116. That archive is the GitHub tag 0.3.4; the PyPI package bindsnet==0.3.4 was built later and also contains the changes listed in CHANGELOG.md under 0.3.4 (PyPI).) A machine-readable citation is provided in CITATION.cff.

Contributors

• Hava Siegelmann - Director of BINDS lab at UMass
• Robert Kozma - Co-Director of BINDS lab (2018-2019)
• Hananel Hazan (email) - Spearheaded BindsNET and its main maintainer.
• Daniel Saunders (email) - MSc student, BindsNET core functions coder (2018-2019).
• Darpan Sanghavi (email) - MSc student BINDS Lab (2018)
• Hassaan Khan (email) - MSc student BINDS Lab (2018)
• Devdhar Patel (email) - MSc student BINDS Lab (2018)
• Simon Caby github
• Christopher Earl (email) - MSc student (2021 - present)

Made with contrib.rocks.

License

GNU Affero General Public License v3.0