done final revision of v1.1.0; temporarily putting mlp away

NN4Neurosim · Jun 21, 2024 · 571d405 · 571d405
1 parent 1b5b75a
commit 571d405
Show file tree

Hide file tree

Showing 53 changed files with 68 additions and 1,443 deletions.
diff --git a/.github/workflows/python-package-conda.yml b/.github/workflows/python-package-conda.yml
@@ -10,24 +10,17 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
-    - name: Set up Python 3.7
+    - name: Set up Python 3.12
       uses: actions/setup-python@v3
       with:
-        python-version: '3.7'
+        python-version: '3.12'
     - name: Add conda to system path
       run: |
         # $CONDA is an environment variable pointing to the root of the miniconda directory
         echo $CONDA/bin >> $GITHUB_PATH
     - name: Test install package
       run: |
         pip install .
-    - name: Lint with flake8
-      run: |
-        conda install flake8
-        # stop the build if there are Python syntax errors or undefined names
-        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics --max-line-length=150
-        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics --max-line-length=150
     - name: Test with pytest
       run: |
         conda install pytest

diff --git a/.readthedocs.yml b/.readthedocs.yml
diff --git a/README.md b/README.md
@@ -1,96 +1,29 @@
-# NN4N: Neural Networks for Neuroscience
+# NN4N: Neural Networks for Neurosimulations
+
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![PyPI version](https://badge.fury.io/py/nn4n.svg)](https://badge.fury.io/py/nn4n)
 [![Downloads](https://static.pepy.tech/badge/nn4n)](https://pepy.tech/project/nn4n)
 [![Downloads](https://static.pepy.tech/badge/nn4n/month)](https://pepy.tech/project/nn4n)<br>
-<!-- [![Python Package using Conda](https://github.com/zhaozewang/NN4Neurosci/actions/workflows/python-package-conda.yml/badge.svg)](https://github.com/zhaozewang/NN4Neurosci/actions/workflows/python-package-conda.yml) -->
-Some of the most commonly used neural networks in neuroscience research are included in this project to ease the implementation process.
-
-<p align="center"><img src="https://github.com/zhaozewang/NN4Neurosci/blob/main/docs/images/basics/RNN_structure.png" width="400"></p>
-
-[GitHub](https://github.com/zhaozewang/NN4Neurosci.git)
-[Documentation](https://nn4neurosci.readthedocs.io/en/latest/)
-
-## Table of contents
-- [Acknowledgements](#acknowledgements)
-- [Change Logs](#change-logs)
-- [Install](#install)
-    - [Install Using pip](#install-using-pip)
-    - [Install From GitHub](#install-from-github)
-- [Model](#model)
-    - [CTRNN (Continuous-Time RNN)](#ctrnn)
-- [Structure](#structure)
-    - [Multi-Area](#multi-area)
-    - [Multi-Area with E/I constraints](#multi-area-with-ei-constraints)
-    - [Random Input](#random-input)
-    - [Blocked CTRNN](#blocked-ctrnn)
-- [Criterion](#criterion)
-    - [RNNLoss](#rnnloss)
-- [Others](#others)
-
-## Acknowledgements
-Immense thanks to [Dr. Christopher J. Cueva](https://www.metaconscious.org/author/chris-cueva/) for his mentorship in developing this project. This project can't be done without his invaluable help.
 
-<!-- ## Change Logs -->
-<!-- - [v1.0.3 [stable]](https://github.com/zhaozewang/NN4Neurosci/blob/main/docs/change_logs/v1.0.3.md) -->
-<!-- - [v1.1.0 [newest]](https://github.com/zhaozewang/NN4Neurosci/blob/main/docs/change_logs/v1.1.0.md) -->
+<div align="center">
+  <video autoplay loop muted playsinline style="width: 50%; min-width: 350px; max-width: 500px;">
+    <source src="https://nn4n.org/assets/logo.mp4" type="video/mp4">
+  </video>
+</div>
 
-## Install
-### Install using pip
-```
-pip install nn4n
-```
+## About
 
-### Install from GitHub
-#### Clone the repository
-```
-git clone https://github.com/zhaozewang/NN4Neurosci.git
-```
-#### Navigate to the NN4Neurosci directory
-```
-cd NN4Neurosci/
-pip install -e .
-```
+Artificial Neural Networks (ANNs) trained with backpropagation, despite being biologically unrealistic, are exceptionally straightforward to configure, train, and evaluate, while allowing for exact examination of each neuron and weight. A growing trend within computational neuroscience is thus to train ANNs on simulated tasks to 'connect the dots', and then to compare their neuronal traits with those of biological brains to derive the underlying mechanisms of the brain.
 
+This project implements Recurrent Neural Networks (RNNs) and Multilayer Perceptrons (MLPs) designed for a parametrized and granular control over network modularity, synaptic plasticity, and other constraints to enable biologically feasible modeling of brain regions.
 
-## Model
-### CTRNN
-The implementation of standard continuous-time RNN (CTRNN). This implementation supports enforcing sparsity constraints (i.e., preventing new synapses from being created) and E/I constraints (i.e., enforcing Dale's law). This ensures that the gradient descent will update synapses with biological plausible constraints. <br>
-<!-- - [Documentation](https://github.com/zhaozewang/NN4Neurosci/blob/main/docs/model/CTRNN/index.md) -->
-- [Examples](https://github.com/zhaozewang/NN4Neurosci/blob/main/examples/CTRNN.ipynb)
-<p align="center"><img src="https://github.com/zhaozewang/NN4Neurosci/blob/main/docs/images/basics/EIRNN_structure.png" width="400"></p>
+## Documentation
+Documentation is available at [here](https://nn4n.org/).
+- [Installation](https://nn4n.org/install/installation/)
+- [Quickstart](https://nn4n.org/install/quickstart/)
 
-## Structure
-In CTRNN implementation, the hidden layer structure can be easily controlled by specifying sparsity masks and E/I masks. We put all RNN update logic in the `model` module and all structure-related logic in the `structure` module to streamline the implementation process. <br>
-We also emphasize on the structure more as it is often more informative to the underlying biological mechanisms. For instance, we might require different module sizes, or we require a multi-module network with E/I constraints; the implementation might be verbose and error-prone. Our following implementation will allow you to easily achieve these goals by simply specifying a few parameters. <br>
-<!-- - [Documentation](https://github.com/zhaozewang/NN4Neurosci/blob/main/docs/structure/index.md) -->
-
-#### Multi-Area
-The following implementation groups neurons into areas depending on your specification. Areas can have different sizes and different connectivities to other areas. <br>
-- [Examples](https://github.com/zhaozewang/NN4Neurosci/blob/main/examples/MultiArea.ipynb)
-<p align="center"><img src="https://github.com/zhaozewang/NN4Neurosci/blob/main/docs/images/basics/Multi_Area.png" width="400"></p>
-
-#### Multi-Area with E/I constraints
-On top of modeling brain with multi-area hidden layer, another critical constraint would be Dale's law, as proposed in the paper [Training Excitatory-Inhibitory Recurrent Neural Networks for Cognitive Tasks: A Simple and Flexible Framework](https://doi.org/10.1371/journal.pcbi.1004792) by Song et al. 2016. The `MultiAreaEI` class in the `structure` module is designed to implement such a connectivity matrix. <br>
-Additionally, how different E/I regions connect to each other could also be tricky; we parameterized this process such that it can be controlled with only two lines of code. <br>
-- [Examples](https://github.com/zhaozewang/NN4Neurosci/blob/main/examples/MultiArea.ipynb)
-<p align="center"><img src="https://github.com/zhaozewang/NN4Neurosci/blob/main/docs/images/basics/Multi_Area_EI.png" width="400"></p>
-
-#### Blocked CTRNN
-The hidden layer is a large connectivity matrix that can potentially be used to represent more than a single brain regions. Under the case when we want to model multiple brain regions and consider them altogether as a single dynamical system, different regions might require different initialization and different update speed. The `BlockedCTRNN` class is designed to support such a case. <br>
-The `BlockedCTRNN` class is temporally implemented as a parallel version of `CTRNN` class. It will potentially be merged into the `CTRNN` class in the future. <br>
-<!-- - [Documentation](https://github.com/zhaozewang/NN4Neurosci/blob/main/docs/model/BlockedCTRNN/index.md) -->
-<!-- <p align="center"><img src="./docs/images/basics/Blocked_Hidden.png" width="400"></p> -->
-
-#### Random Input
-Neurons' dynamic receiving input will be heavily driven by the inputting signal. Injecting signals to only part of the neuron will result in more versatile and hierarchical dynamics. See [A Versatile Hub Model For Efficient Information Propagation And Feature Selection](https://arxiv.org/abs/2307.02398). This is supported by `RandomInput` class <br>
-- Example to be added
-
-## Criterion
-#### RNNLoss
-The loss function is modularized. The `RNNLoss` class is designed in a modular fashion and includes the most commonly used loss functions, such as Frobenius norm on connectivity, metabolic cost, reconstruction loss, etc. <br>
-<!-- - [Documentation](https://github.com/zhaozewang/NN4Neurosci/blob/main/docs/criterion/index.md) -->
+## Acknowledgement
+Immense thanks to [Dr. Christopher J. Cueva](https://www.metaconscious.org/author/chris-cueva/) for his mentorship in developing this project. This project can't be done without his invaluable help.
 
-## Others
-For similar projects:
-- [nn-brain](https://github.com/gyyang/nn-brain)
+## License
+This project is licensed under the terms of the MIT license. See the [LICENSE](https://opensource.mit.edu/license) file for details.
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/make.bat b/docs/make.bat
diff --git a/docs/requirements.txt b/docs/requirements.txt
diff --git a/docs/source/_static/basics/Blocked_Hidden.png b/docs/source/_static/basics/Blocked_Hidden.png
diff --git a/docs/source/_static/basics/EIRNN_structure.png b/docs/source/_static/basics/EIRNN_structure.png
diff --git a/docs/source/_static/basics/Multi_Area.png b/docs/source/_static/basics/Multi_Area.png
diff --git a/docs/source/_static/basics/Multi_Area_EI.png b/docs/source/_static/basics/Multi_Area_EI.png
diff --git a/docs/source/_static/basics/Multi_Area_Transpose.png b/docs/source/_static/basics/Multi_Area_Transpose.png
diff --git a/docs/source/_static/basics/RNN_structure.png b/docs/source/_static/basics/RNN_structure.png
diff --git a/docs/source/_static/get_started/hidden_dist.png b/docs/source/_static/get_started/hidden_dist.png
diff --git a/docs/source/_static/get_started/hidden_mat.png b/docs/source/_static/get_started/hidden_mat.png
diff --git a/docs/source/_static/get_started/input_dist.png b/docs/source/_static/get_started/input_dist.png
diff --git a/docs/source/_static/get_started/input_mat.png b/docs/source/_static/get_started/input_mat.png
diff --git a/docs/source/_static/get_started/readout_dist.png b/docs/source/_static/get_started/readout_dist.png
diff --git a/docs/source/_static/get_started/readout_mat.png b/docs/source/_static/get_started/readout_mat.png
diff --git a/docs/source/_static/structure/hidden_mask.png b/docs/source/_static/structure/hidden_mask.png
diff --git a/docs/source/_static/structure/input_mask.png b/docs/source/_static/structure/input_mask.png
diff --git a/docs/source/_static/structure/readout_mask.png b/docs/source/_static/structure/readout_mask.png
diff --git a/docs/source/conf.py b/docs/source/conf.py