Skip to content

Commit

Permalink
Merge pull request #48 from PKU-NIP-Lab/V1.1.0-alpha
Browse files Browse the repository at this point in the history 
V1.1.0 (alpha)
  • Loading branch information
@chaoming0625
chaoming0625 committed Sep 2, 2021
2 parents 7bd2755 + 848f692 commit 525aa98
Show file tree
Hide file tree
Showing 223 changed files with 27,021 additions and 17,090 deletions.
5 changes: 5 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@ publishment.md
#experimental/
.vscode

examples/recurrent_neural_network/neurogym
develop/iconip_paper
develop/benchmark/COBA/results
develop/test
develop/outputdir
Expand All @@ -13,6 +15,9 @@ docs/images/neuron_structure.xlsx
docs/images/neuron_structure.pdf
docs/images/connection_methods.pptx

*/_autosummary

docs/apis/dnn/_autosummary
docs/quickstart/_autosummary
docs/quickstart/.ipynb_checkpoints

Expand Down
211 changes: 82 additions & 129 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,167 +7,120 @@

# Why to use BrainPy

``BrainPy`` is an integrative framework for computational neuroscience and brain-inspired computation. Three core functions are provided in BrainPy:
``BrainPy`` is an integrative framework for computational neuroscience and brain-inspired computation based on Just-In-Time (JIT) compilation. Core functions provided in BrainPy includes

- *General numerical solvers* for ODEs and SDEs (support for DDEs and FDEs will come soon).
- *Neurodynamics simulation tools* for brain objects, such like neurons, synapses and networks (support for soma and dendrites will come soon).
- *Neurodynamics analysis tools* for differential equations, including phase plane analysis and bifurcation analysis (support for continuation analysis and sensitive analysis will come soon).
- **General numerical solvers** for ODEs, SDEs, DDEs, FDEs, and others.
- **Dynamics simulation tools** for various brain objects, like neurons, synapses, networks, soma, dendrites, channels, and even more.
- **Dynamics analysis tools** for differential equations, including phase plane analysis and bifurcation analysis, continuation analysis and sensitive analysis.
- **Seamless integration with deep learning models**, and has the speed benefit on JIT compilation.
- And more ......

Moreover, `BrainPy` is designed to effectively satisfy your basic requirements:
`BrainPy` is designed to effectively satisfy your basic requirements:

- *Easy to learn and use*, because BrainPy is only based on Python language and has little dependency requirements;
- *Highly flexible and transparent*, because BrainPy endows the users with the fully data/logic flow control;
- *Simulation can be guided with the analysis*, because the same code in BrainPy can not only be used for simulation, but also for dynamics analysis;
- *Efficient running speed*, because BrainPy is compatible with the latest JIT compilers or any other accelerating framework you prefer (below we list the speed comparison based on Numba JIT).
- *Easy to learn and use*: BrainPy is only based on Python language and has little dependency requirements.
- *Flexible and transparent*: BrainPy endows the users with the fully data/logic flow control. Users can code any logic they want with BrainPy.
- *Extensible*: BrainPy allow users to extend new functionality just based on Python coding. For example, we extend the numerical integration with the ability to do numerical analysis. In such a way, the same code in BrainPy can not only be used for simulation, but also for dynamics analysis.
- *Efficient running speed*: All codes in BrainPy can just-in-time compiled (based on [JAX](https://github.com/google/jax) and [Numba](https://github.com/numba/)) to run on CPU or GPU devices, thus guaranteeing its running efficiency.


![Speed Comparison](docs/_static/speed.png)

`BrainPy` is a backend-independent neural simulator. Users can define models with any backend they prefer. Intrinsically, BrainPy supports the array/tensor-oriented backends such like [NumPy](https://numpy.org/), [PyTorch](https://pytorch.org/), and [TensorFlow](https://www.tensorflow.org/), it also supports the JIT compilers such as [Numba](https://numba.pydata.org/) on CPU or CUDA devices. Extending BrainPy to support other backend frameworks you prefer is very easy. The details please see documents coming soon.
# How to use BrainPy

## Step 1: installation

``BrainPy`` is based on Python (>=3.6), and the following packages are required to be installed to use ``BrainPy``:

# Installation
- NumPy >= 1.15
- Matplotlib >= 3.3

*The installation details please see documentation: [Quickstart/Installation](https://brainpy.readthedocs.io/en/latest/quickstart/installation.html)*

``BrainPy`` is based on Python (>=3.7), and the following packages are required to be installed to use ``BrainPy``:

- NumPy >= 1.13
- Matplotlib >= 3.3

Install ``BrainPy`` by using ``pip``:
**Method 1**: install ``BrainPy`` by using ``pip``:

```bash
> pip install -U brainpy-simulator
> pip install -U brain-py
```

Install ``BrainPy`` by using ``conda``:
**Method 2**: install ``BrainPy`` by using ``conda``:

```bash
> conda install brainpy-simulator -c brainpy
> conda install brain-py -c conda-forge
```

Install ``BrainPy`` from source:
**Method 3**: install ``BrainPy`` from source:

```bash
> pip install git+https://github.com/PKU-NIP-Lab/BrainPy
>
> # or
> pip install git+https://git.openi.org.cn/OpenI/BrainPy
>
> # or
> pip install -e git://github.com/PKU-NIP-Lab/BrainPy.git@V1.0.0
```


# Let's start

- **Website (including documentations):** https://brainpy.readthedocs.io/
- **Source code:** https://github.com/PKU-NIP-Lab/BrainPy or https://git.openi.org.cn/OpenI/BrainPy
- **Bug reports:** https://github.com/PKU-NIP-Lab/BrainPy/issues or Email to adaduo@outlook.com
**Other dependencies**: you want to get the full supports by BrainPy, please install the following packages:

- `JAX >= 0.2.10`, needed for "jax" backend and "dnn" module
- `Numba >= 0.52`, needed for JIT compilation on "numpy" backend
- `SymPy >= 1.4`, needed for dynamics "analysis" module and Exponential Euler method



## Step 2: useful links

- **Documentation:** https://brainpy.readthedocs.io/
- **Source code:** https://github.com/PKU-NIP-Lab/BrainPy or https://git.openi.org.cn/OpenI/BrainPy
- **Bug reports:** https://github.com/PKU-NIP-Lab/BrainPy/issues or Email to adaduo@outlook.com
- **Examples from papers**: https://brainmodels.readthedocs.io/en/latest/from_papers.html

Here list several simple examples for neurodynamics simulation and analysis. Comprehensive examples and tutorials please see [BrainModels](https://brainmodels.readthedocs.io).

<table border="0">
<tr>
<td border="0" width="30%">
<a href="https://github.com/PKU-NIP-Lab/BrainModels/blob/main/brainmodels/tensor_backend/neurons/HodgkinHuxley_model.py">
<img src="docs/_static/HH_neuron.png">
</a>
</td>
<td border="0" valign="top">
<h3><a href="https://github.com/PKU-NIP-Lab/BrainModels/blob/main/brainmodels/tensor_backend/neurons/HodgkinHuxley_model.py">HH Neuron Model</a></h3>
<p>The Hodgkin–Huxley neuron model.</p>
</td>
</tr>
<tr>
<td border="0" width="30%">
<a href="https://github.com/PKU-NIP-Lab/BrainModels/blob/main/brainmodels/tensor_backend/synapses/AMPA_synapse.py">
<img src="docs/_static/AMPA_model.png">
</a>
</td>
<td border="0" valign="top">
<h3><a href="https://github.com/PKU-NIP-Lab/BrainModels/blob/main/brainmodels/tensor_backend/synapses/AMPA_synapse.py">AMPA Synapse Model</a></h3>
<p>The AMPA synapse model.</p>
</td>
</tr>
<tr>
<td border="0" width="30%">
<a href="https://brainmodels.readthedocs.io/en/latest/from_papers/Wang_1996_gamma_oscillation.html">
<img src="docs/_static/gamma_oscillation.png">
</a>
</td>
<td border="0" valign="top">
<h3><a href="https://brainmodels.readthedocs.io/en/latest/from_papers/Wang_1996_gamma_oscillation.html">Gamma Oscillation Model</a></h3>
<p>Implementation of the paper: <i> Wang, Xiao-Jing, and György Buzsáki. “Gamma oscillation by
synaptic inhibition in a hippocampal interneuronal network
model.” Journal of neuroscience 16.20 (1996): 6402-6413. </i>
</p>
</td>
</tr>
<tr>
<td border="0" width="30%">
<a href="https://brainmodels.readthedocs.io/en/latest/from_papers/Vreeswijk_1996_EI_net.html">
<img src="docs/_static/EI_balance_net.png">
</a>
</td>
<td border="0" valign="top">
<h3><a href="https://brainmodels.readthedocs.io/en/latest/from_papers/Vreeswijk_1996_EI_net.html">E/I Balance Network</a></h3>
<p>Implementation of the paper: <i>Van Vreeswijk, Carl, and Haim Sompolinsky.
“Chaos in neuronal networks with balanced excitatory and inhibitory activity.”
Science 274.5293 (1996): 1724-1726.</i></p>
</td>
</tr>
<tr>
<td border="0" width="30%">
<a href="https://brainmodels.readthedocs.io/en/latest/from_papers/Wu_2008_CANN.html">
<img src="docs/_static/CANN1d.png">
</a>
</td>
<td border="0" valign="top">
<h3><a href="https://brainmodels.readthedocs.io/en/latest/from_papers/Wu_2008_CANN.html">Continuous-attractor Network</a></h3>
<p>Implementation of the paper: <i> Si Wu, Kosuke Hamaguchi, and Shun-ichi Amari. "Dynamics and
computation of continuous attractors." Neural
computation 20.4 (2008): 994-1025. </i>
</p>
</td>
</tr>
<tr>
<td border="0" width="30%">
<a href="https://brainmodels.readthedocs.io/en/latest/tutorials/dynamics_analysis/NaK_model_analysis.html">
<img src="docs/_static/phase_plane_analysis1.png">
</a>
</td>
<td border="0" valign="top">
<h3><a href="https://brainmodels.readthedocs.io/en/latest/tutorials/dynamics_analysis/NaK_model_analysis.html">Phase Plane Analysis</a></h3>
<p>Phase plane analysis of the I<sub>Na,p+</sub>-I<sub>K</sub> model, where
"input" is 50., and "Vn_half" is -45..</p>
</td>
</tr>
<tr>
<td border="0" width="30%">
<a href="https://brainmodels.readthedocs.io/en/latest/tutorials/dynamics_analysis/FitzHugh_Nagumo_analysis.html">
<img src="docs/_static/FitzHugh_Nagumo_codimension1.png">
</a>
</td>
<td border="0" valign="top">
<h3><a href="https://brainmodels.readthedocs.io/en/latest/tutorials/dynamics_analysis/FitzHugh_Nagumo_analysis.html">
Codimension 1 Bifurcation Analysis</a></h3>
<p>Codimension 1 bifurcation analysis of FitzHugh Nagumo model, in which
"a" is equal to 0.7, and "Iext" is varied in [0., 1.].</p>
</td>
</tr>
<tr>
<td border="0" width="30%">
<a href="https://brainmodels.readthedocs.io/en/latest/tutorials/dynamics_analysis/FitzHugh_Nagumo_analysis.html#Codimension-2-bifurcation-analysis">
<img src="docs/_static/FitzHugh_Nagumo_codimension2.png">
</a>
</td>
<td border="0" valign="top">
<h3><a href="https://brainmodels.readthedocs.io/en/latest/tutorials/dynamics_analysis/FitzHugh_Nagumo_analysis.html#Codimension-2-bifurcation-analysis">
Codimension 2 Bifurcation Analysis</a></h3>
<p>Codimension 2 bifurcation analysis of FitzHugh Nagumo model, in which "a"
is varied in [0.5, 1.0], and "Iext" is varied in [0., 1.].</p>
</td>
</tr>
</table>


## Step 3: comprehensive examples

Here list several examples of BrainPy. More detailed examples and tutorials please see [**BrainModels**](https://brainmodels.readthedocs.io).



### Neuron models

- [Hodgkin–Huxley neuron model](https://github.com/PKU-NIP-Lab/BrainModels/blob/main/brainmodels/tensor_backend/neurons/HodgkinHuxley_model.py)



### Synapse models

- [AMPA synapse model](https://github.com/PKU-NIP-Lab/BrainModels/blob/main/brainmodels/tensor_backend/synapses/AMPA_synapse.py)



### Network models

- [Gamma oscillation network model](https://brainmodels.readthedocs.io/en/latest/from_papers/Wang_1996_gamma_oscillation.html)
- [E/I balanced network model](https://brainmodels.readthedocs.io/en/latest/from_papers/Vreeswijk_1996_EI_net.html)
- [Continuous attractor network model](https://brainmodels.readthedocs.io/en/latest/from_papers/Wu_2008_CANN.html)




### Phase plane analysis

- [Phase plane analysis of the I<sub>Na,p</sub>-I<sub>K</sub> model](https://brainmodels.readthedocs.io/en/latest/tutorials/dynamics_analysis/NaK_model_analysis.html)



### Bifurcation analysis

- [Codimension 1 bifurcation analysis of FitzHugh Nagumo model](https://brainmodels.readthedocs.io/en/latest/tutorials/dynamics_analysis/FitzHugh_Nagumo_analysis.html)
- [Codimension 2 bifurcation analysis of FitzHugh Nagumo model](https://brainmodels.readthedocs.io/en/latest/tutorials/dynamics_analysis/FitzHugh_Nagumo_analysis.html#Codimension-2-bifurcation-analysis)



### Deep neural networks



0 comments on commit 525aa98

Please sign in to comment.